# Worktree-backed Lanes Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Let a lane own a git worktree that CCAM creates, resets, removes and purges, with every destructive action gated on counted facts and on three independent safety checks.

**Architecture:** Design doc: `docs/superpowers/specs/2026-07-28-worktree-lanes-design.md` — read it once before Task 1. All git work goes through one module (`server/lib/worktree.js`) that shells out with `execFile` and an argv array, never a shell string, and re-verifies its own safety preconditions. Lanes gain a `kind` of `adopted` (pointer at a directory the user already had — never destroyable) or `managed` (a worktree CCAM created — destroyable). Destructive actions are serialised per lane and preceded by a preflight endpoint that returns counts, which the confirmation UI renders and the server re-checks before acting.

**Tech Stack:** Node 18+, Express, better-sqlite3, `node:child_process.execFile`, real `git` against temp-directory fixtures, `node:test` (server), React 18 + TypeScript + Vitest (client).

## Global Constraints

- Branch: create `feat/worktree-lanes` off the current head of `feat/lanes-pipeline`. Never work on `master`.
- Every `.js/.ts/.tsx` file created or modified MUST start with a file overview comment plus the exact line `@author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>`. Verify with `bash .claude/skills/file-headers/scripts/check-headers.sh` (must exit 0).
- Schema changes are additive only and migration-safe on an existing database: `try { SELECT col } catch { ALTER TABLE … ADD COLUMN }`, the pattern at `server/db.js:412-418`. Existing rows must migrate to `kind='adopted'`.
- **Never `rm -rf` a lane directory.** Removal goes through `git worktree remove`; if git refuses, surface git's error unchanged.
- **Never build a shell command string.** `execFile("git", [...args])` only. No `shell: true`, no template-literal commands.
- Destructive routes stay behind the existing same-origin guard exported from `server/routes/run.js`.
- Preserve existing behavior: no existing route, response shape, WebSocket type, or CLI command changes meaning. `lane_update` stays the only lane WS type.
- Server is CommonJS. No new npm dependencies. Server tests use `node:test` + `node:assert/strict`; client tests use Vitest + Testing Library.
- The pre-commit hook runs Prettier and the full server suite; a commit takes minutes. Do not disable it.
- Baseline before this plan: 790 server tests, 279 client tests, all passing.

---

## File Structure

**Create**
- `server/lib/worktree.js` — every git invocation, plus the three-check safety guard. No Express, no DB.
- `server/lib/lane-preflight.js` — counts for `reset` / `remove` / `purge`. Reads git and the DB; mutates nothing.
- `server/lib/lane-lock.js` — per-lane async mutex.
- `server/__tests__/worktree.test.js` — git behaviour against a real temp repo.
- `server/__tests__/lane-lifecycle.test.js` — HTTP: add / preflight / reset / remove / purge.
- `client/src/components/lanes/DestructiveLaneModal.tsx` — preflight table inside the existing `ConfirmModal`.

**Modify**
- `server/db.js` — four additive columns.
- `server/lib/lanes.js` — `kind`/`source_repo`/`base_branch`/`slug` in create/patch/payload; `purgeLaneSessions`.
- `server/routes/lanes.js` — `POST /worktree`, `GET /:id/preflight`, `reset` + `purge` actions, lock usage.
- `bin/ccam.js` — `ccam lanes add --repo`, `ccam lanes reset|remove|purge`.
- `client/src/lib/api.ts`, `client/src/lib/types.ts` — preflight + worktree types and calls.
- `client/src/components/lanes/LaneCard.tsx` — kind badge; destructive buttons only for `managed`.
- `docs/LANES.md`, `CLAUDE.md` — the new lifecycle.

---

## Task 1: `server/lib/worktree.js` — git plumbing and the safety guard

**Files:**
- Create: `server/lib/worktree.js`
- Test: `server/__tests__/worktree.test.js`

**Interfaces:**
- Consumes: nothing from earlier tasks.
- Produces:
  - `LANES_ROOT` — `process.env.LANES_ROOT || path.join(os.homedir(), ".claude", "ccam-lanes")`
  - `git(cwd, args): Promise<{stdout, stderr}>` — rejects with `err.git = {args, code, stderr}` on non-zero
  - `isGitRepo(dir): Promise<boolean>`
  - `resolveBase(sourceRepo, wanted): Promise<string>` — `origin/<wanted>` → `<wanted>` → current HEAD
  - `slugify(text): string` — lowercase, non-alphanumerics to `-`, collapsed, trimmed, max 40 chars
  - `listWorktrees(sourceRepo): Promise<Array<{path, branch, locked}>>` — parses `--porcelain`
  - `branchCheckedOutAt(sourceRepo, branch): Promise<string|null>`
  - `addWorktree({sourceRepo, dir, branch, base}): Promise<{dir, branch, created: boolean}>`
  - `assertDestroyable(lane): Promise<void>` — the three checks; throws `err.code = "ENOTMANAGED" | "EOUTSIDEROOT" | "ENOTWORKTREE"`
  - `resetWorktree(lane): Promise<void>`
  - `removeWorktree(lane): Promise<void>`
  - `statusCounts(dir): Promise<{dirty, untracked, head}>`
  - `unpushedCount(dir): Promise<number>`

- [ ] **Step 1: Write the failing test**

Create `server/__tests__/worktree.test.js`. It builds a real repository in a temp directory — mocks would test nothing that matters here.

```js
/**
 * @file Tests for server/lib/worktree.js against a REAL git repository created
 * in a temp directory. Every behaviour worth testing here is git's own — branch
 * collisions, what `clean -fd` spares, what `worktree list` reports — so mocking
 * git would only test our idea of git.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

const { describe, it, before, after } = require("node:test");
const assert = require("node:assert/strict");
const fs = require("node:fs");
const os = require("node:os");
const path = require("node:path");
const { execFileSync } = require("node:child_process");

const ROOT = fs.mkdtempSync(path.join(os.tmpdir(), "ccam-wt-"));
process.env.LANES_ROOT = path.join(ROOT, "lanes");

const wt = require("../lib/worktree");

const SRC = path.join(ROOT, "src-repo");
const g = (cwd, ...args) => execFileSync("git", args, { cwd, encoding: "utf8" });

before(() => {
  fs.mkdirSync(SRC, { recursive: true });
  g(SRC, "init", "-b", "main");
  g(SRC, "config", "user.email", "t@example.com");
  g(SRC, "config", "user.name", "Test");
  fs.writeFileSync(path.join(SRC, "README.md"), "hello\n");
  fs.writeFileSync(path.join(SRC, ".gitignore"), "node_modules/\n.env\n");
  g(SRC, "add", "-A");
  g(SRC, "commit", "-m", "init");
});

after(() => fs.rmSync(ROOT, { recursive: true, force: true }));

function laneFor(dir, branch, over = {}) {
  return { id: 1, kind: "managed", cwd: dir, branch, source_repo: SRC, base_branch: "main", ...over };
}

describe("worktree", () => {
  it("slugifies a title into a safe single segment", () => {
    assert.equal(wt.slugify("Rename Metric → Rule!"), "rename-metric-rule");
    assert.equal(wt.slugify("  a//b  "), "a-b");
    assert.ok(wt.slugify("x".repeat(80)).length <= 40);
  });

  it("resolves the base branch, falling back when origin has none", async () => {
    assert.equal(await wt.resolveBase(SRC, "main"), "main");
    assert.equal(await wt.resolveBase(SRC, "does-not-exist"), "main");
  });

  it("creates a worktree on a new branch and lists it", async () => {
    const dir = path.join(process.env.LANES_ROOT, "src-repo__alpha");
    const r = await wt.addWorktree({ sourceRepo: SRC, dir, branch: "feat/alpha", base: "main" });
    assert.equal(r.created, true);
    assert.ok(fs.existsSync(path.join(dir, "README.md")));
    const list = await wt.listWorktrees(SRC);
    assert.ok(list.some((w) => w.path === dir && w.branch === "feat/alpha"));
  });

  it("refuses a branch already checked out in another worktree", async () => {
    const dir2 = path.join(process.env.LANES_ROOT, "src-repo__alpha2");
    await assert.rejects(
      () => wt.addWorktree({ sourceRepo: SRC, dir: dir2, branch: "feat/alpha", base: "main" }),
      (e) => e.code === "EBRANCHBUSY" && typeof e.checkedOutAt === "string",
    );
  });

  it("counts dirty, untracked and unpushed work", async () => {
    const dir = path.join(process.env.LANES_ROOT, "src-repo__alpha");
    fs.appendFileSync(path.join(dir, "README.md"), "edit\n");
    fs.writeFileSync(path.join(dir, "scratch.txt"), "untracked\n");
    fs.mkdirSync(path.join(dir, "node_modules"), { recursive: true });
    fs.writeFileSync(path.join(dir, "node_modules", "dep.js"), "x\n");
    const s = await wt.statusCounts(dir);
    assert.equal(s.dirty, 1);
    assert.equal(s.untracked, 1); // node_modules is ignored, so it does not count
    assert.match(s.head, /^[0-9a-f]{7,40}$/);
    assert.equal(await wt.unpushedCount(dir), 0); // no upstream yet
  });

  it("reset restores base, drops untracked files, and spares gitignored ones", async () => {
    const dir = path.join(process.env.LANES_ROOT, "src-repo__alpha");
    await wt.resetWorktree(laneFor(dir, "feat/alpha"));
    assert.equal(fs.readFileSync(path.join(dir, "README.md"), "utf8"), "hello\n");
    assert.equal(fs.existsSync(path.join(dir, "scratch.txt")), false);
    assert.equal(fs.existsSync(path.join(dir, "node_modules", "dep.js")), true);
    const s = await wt.statusCounts(dir);
    assert.equal(s.dirty, 0);
  });

  it("refuses to destroy an adopted lane, a path outside LANES_ROOT, or a non-worktree", async () => {
    const dir = path.join(process.env.LANES_ROOT, "src-repo__alpha");
    await assert.rejects(
      () => wt.assertDestroyable(laneFor(dir, "feat/alpha", { kind: "adopted" })),
      (e) => e.code === "ENOTMANAGED",
    );
    await assert.rejects(
      () => wt.assertDestroyable(laneFor("/tmp", "feat/alpha")),
      (e) => e.code === "EOUTSIDEROOT",
    );
    const ghost = path.join(process.env.LANES_ROOT, "src-repo__ghost");
    fs.mkdirSync(ghost, { recursive: true });
    await assert.rejects(
      () => wt.assertDestroyable(laneFor(ghost, "feat/ghost")),
      (e) => e.code === "ENOTWORKTREE",
    );
  });

  it("removes the worktree and its branch, leaving git's list clean", async () => {
    const dir = path.join(process.env.LANES_ROOT, "src-repo__alpha");
    await wt.removeWorktree(laneFor(dir, "feat/alpha"));
    assert.equal(fs.existsSync(dir), false);
    const list = await wt.listWorktrees(SRC);
    assert.equal(list.some((w) => w.path === dir), false);
    const branches = g(SRC, "branch", "--list", "feat/alpha").trim();
    assert.equal(branches, "");
  });

  it("never deletes the base branch even if a lane claims it", async () => {
    const dir = path.join(process.env.LANES_ROOT, "src-repo__beta");
    await wt.addWorktree({ sourceRepo: SRC, dir, branch: "feat/beta", base: "main" });
    await wt.removeWorktree(laneFor(dir, "main")); // lane lies about its branch
    assert.match(g(SRC, "branch", "--list", "main"), /main/);
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `node --test server/__tests__/worktree.test.js`
Expected: FAIL — `Cannot find module '../lib/worktree'`.

- [ ] **Step 3: Implement the module**

Create `server/lib/worktree.js`. Key requirements the tests pin, restated so nothing is inferred:

- `git(cwd, args)` wraps `execFile("git", args, {cwd, maxBuffer: 8 * 1024 * 1024})` promisified. On failure throw an `Error` carrying `err.git = { args, code, stderr }`.
- `slugify` — `text.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40)`, and if the result is empty throw `err.code = "EBADSLUG"`.
- `resolveBase(sourceRepo, wanted)` — try `git rev-parse --verify --quiet origin/<wanted>`, then `<wanted>`, then `git rev-parse --abbrev-ref HEAD`. Return the first that resolves.
- `listWorktrees` — parse `git worktree list --porcelain`: records separated by blank lines, `worktree <path>`, `branch refs/heads/<name>`, bare `locked` line. Return `{path, branch, locked}` with `branch` null for a detached worktree.
- `branchCheckedOutAt(sourceRepo, branch)` — the `path` from `listWorktrees` whose branch matches, else null.
- `addWorktree({sourceRepo, dir, branch, base})`:
  - if `branchCheckedOutAt` returns a path, throw `err.code = "EBRANCHBUSY"`, `err.checkedOutAt = thatPath`
  - `fs.mkdirSync(path.dirname(dir), {recursive: true})`
  - if `git rev-parse --verify --quiet <branch>` succeeds, run `worktree add <dir> <branch>` and return `{created: false}`; otherwise `worktree add -b <branch> <dir> <base>` and return `{created: true}`
- `assertDestroyable(lane)` — in order: `kind !== "managed"` → `ENOTMANAGED`; `fs.realpathSync(lane.cwd)` not inside `fs.realpathSync(LANES_ROOT)` on a path boundary → `EOUTSIDEROOT` (a non-existent path fails this check too, which is correct — it cannot be a live worktree); not present in `listWorktrees(lane.source_repo)` → `ENOTWORKTREE`.
- `PROTECTED_BRANCHES = new Set(["main", "master"])`, plus the lane's own `base_branch`: `deleteBranchSafely(sourceRepo, branch, baseBranch)` returns without acting when the branch is protected or falsy.
- `resetWorktree(lane)` — `assertDestroyable` first, then, all in `lane.cwd`: `fetch origin --prune` (tolerate failure when there is no remote), `checkout <base>` (creating it from `origin/<base>` if absent), `reset --hard <base>`, `clean -fd` (**never** `-x`), then in `source_repo` `deleteBranchSafely(lane.branch)`, then back in the worktree `checkout -b <lane.branch> <base>`.
- `removeWorktree(lane)` — `assertDestroyable`, then in `source_repo`: `worktree unlock <dir>` (ignore failure), `worktree remove --force <dir>`, `worktree prune`, `deleteBranchSafely(lane.branch, lane.base_branch)`. If `worktree remove` fails, rethrow git's error untouched — do not fall back to filesystem deletion.
- `statusCounts(dir)` — parse `git status --porcelain=v1 --untracked-files=normal`: lines starting `??` are untracked, others dirty. `head` from `git rev-parse --short HEAD`.
- `unpushedCount(dir)` — `git rev-list --count @{u}..HEAD`; when there is no upstream, git exits non-zero — return 0.

- [ ] **Step 4: Run test to verify it passes**

Run: `node --test server/__tests__/worktree.test.js`
Expected: PASS, 8 tests.

- [ ] **Step 5: Header audit and commit**

Run: `bash .claude/skills/file-headers/scripts/check-headers.sh`

```bash
git add server/lib/worktree.js server/__tests__/worktree.test.js
git commit -m "feat(lanes): git worktree plumbing with a three-check destroy guard"
```

---

## Task 2: Schema, lane fields, and per-lane locking

**Files:**
- Modify: `server/db.js` (the `lanes` block)
- Modify: `server/lib/lanes.js`
- Create: `server/lib/lane-lock.js`
- Test: `server/__tests__/lanes-lib.test.js` (append a `describe`)

**Interfaces:**
- Consumes: nothing from Task 1 (kept independent so both can be reviewed alone).
- Produces:
  - four columns on `lanes`: `kind` (`NOT NULL DEFAULT 'adopted'`), `source_repo`, `base_branch`, `slug`
  - `createLane` accepts and stores `kind`, `source_repo`, `base_branch`, `slug`; unknown values of `kind` are rejected with `err.code = "EBADKIND"`
  - `PATCHABLE` gains `kind`, `source_repo`, `base_branch`, `slug`
  - `purgeLaneSessions(id): {sessions, events, tokenRows}` — deletes the lane's sessions (never the one in `lanes.session_id`), their events, and `token_usage` rows left orphaned
  - `server/lib/lane-lock.js`: `withLaneLock(id, fn): Promise<any>` — serialises per lane id, releases on throw

- [ ] **Step 1: Write the failing test** (append to `server/__tests__/lanes-lib.test.js`)

```js
const { withLaneLock } = require("../lib/lane-lock");

describe("lane kind, worktree fields and purge", () => {
  it("defaults to adopted and stores worktree fields when given", () => {
    const a = lanes.createLane({ cwd: "/tmp/wt-kind-a" });
    assert.equal(a.kind, "adopted");
    const m = lanes.createLane({
      cwd: "/tmp/wt-kind-b", kind: "managed",
      source_repo: "/tmp/src", base_branch: "main", slug: "b",
    });
    assert.equal(m.kind, "managed");
    assert.equal(m.source_repo, "/tmp/src");
    assert.equal(m.base_branch, "main");
    assert.equal(m.slug, "b");
    lanes.deleteLane(a.id);
    lanes.deleteLane(m.id);
  });

  it("rejects an unknown kind", () => {
    assert.throws(() => lanes.createLane({ cwd: "/tmp/wt-kind-c", kind: "gremlin" }),
      (e) => e.code === "EBADKIND");
  });

  it("purges a lane's sessions, their events and orphaned token rows, sparing the live one", () => {
    const l = lanes.createLane({ cwd: "/tmp/wt-purge" });
    const { db } = require("../db");
    db.prepare("INSERT INTO sessions (id, cwd, status) VALUES (?, ?, 'completed')").run("purge-1", "/tmp/wt-purge/sub");
    db.prepare("INSERT INTO sessions (id, cwd, status) VALUES (?, ?, 'active')").run("purge-live", "/tmp/wt-purge");
    db.prepare("INSERT INTO events (session_id, event_type) VALUES (?, 'PostToolUse')").run("purge-1");
    db.prepare("INSERT INTO token_usage (session_id, model, input_tokens) VALUES (?, 'm', 5)").run("purge-1");
    lanes.updateLane(l.id, { session_id: "purge-live" });

    const counts = lanes.purgeLaneSessions(l.id);
    assert.equal(counts.sessions, 1);
    assert.equal(counts.events, 1);
    assert.equal(counts.tokenRows, 1);
    assert.equal(db.prepare("SELECT COUNT(*) c FROM sessions WHERE id='purge-live'").get().c, 1);
    assert.equal(db.prepare("SELECT COUNT(*) c FROM events WHERE session_id='purge-1'").get().c, 0);
    assert.equal(db.prepare("SELECT COUNT(*) c FROM token_usage WHERE session_id='purge-1'").get().c, 0);
    lanes.deleteLane(l.id);
  });

  it("serialises work per lane and releases the lock when the body throws", async () => {
    const order = [];
    const slow = withLaneLock(7, async () => { order.push("a-start"); await new Promise((r) => setTimeout(r, 50)); order.push("a-end"); });
    const fast = withLaneLock(7, async () => { order.push("b"); });
    await Promise.all([slow, fast]);
    assert.deepEqual(order, ["a-start", "a-end", "b"]);
    await assert.rejects(() => withLaneLock(7, async () => { throw new Error("boom"); }));
    await withLaneLock(7, async () => order.push("c"));
    assert.equal(order[order.length - 1], "c");
  });
});
```

- [ ] **Step 2: Run test to verify it fails**

Run: `node --test server/__tests__/lanes-lib.test.js`
Expected: FAIL — `Cannot find module '../lib/lane-lock'`.

- [ ] **Step 3: Add the columns**

In `server/db.js`, after the `lanes` table and its index, following the probe pattern at `server/db.js:412-418`:

```js
// Managed lanes own a git worktree CCAM created and may be destroyed; adopted
// lanes merely point at a directory the user already had and never may be.
// Existing rows default to 'adopted', so no lane gains a destructive path by
// upgrading.
try {
  db.prepare("SELECT kind FROM lanes LIMIT 1").get();
} catch {
  db.prepare("ALTER TABLE lanes ADD COLUMN kind TEXT NOT NULL DEFAULT 'adopted'").run();
  db.prepare("ALTER TABLE lanes ADD COLUMN source_repo TEXT").run();
  db.prepare("ALTER TABLE lanes ADD COLUMN base_branch TEXT").run();
  db.prepare("ALTER TABLE lanes ADD COLUMN slug TEXT").run();
}
```

- [ ] **Step 4: Extend `server/lib/lanes.js` and write the lock**

`createLane` gains the four fields (validating `kind` against `new Set(["adopted", "managed"])`), `PATCHABLE` gains them, and `purgeLaneSessions(id)` runs inside one `db.transaction`:

- select the lane's sessions: `WHERE (cwd = ? OR cwd LIKE ? || '/%')` against `lane.cwd`, excluding `lanes.session_id` and any session whose `status = 'active'`
- count and delete their `events`, then their `token_usage`, then the sessions themselves
- return `{sessions, events, tokenRows}`
- run `db.pragma("optimize")` after the transaction commits — never `VACUUM`, which locks the whole database

Create `server/lib/lane-lock.js` — a `Map<laneId, Promise>` chain:

```js
const chains = new Map();

function withLaneLock(id, fn) {
  const key = String(id);
  const prev = chains.get(key) || Promise.resolve();
  const run = prev.then(fn, fn); // run regardless of how the previous holder settled
  // Keep the chain alive but never let a rejection poison the next waiter.
  chains.set(key, run.then(() => {}, () => {}));
  return run;
}
```

- [ ] **Step 5: Run tests to verify they pass**

Run: `node --test server/__tests__/lanes-lib.test.js`
Expected: PASS — the four new tests plus every earlier one.

- [ ] **Step 6: Full suite and commit**

Run: `npm run test:server`

```bash
git add server/db.js server/lib/lanes.js server/lib/lane-lock.js server/__tests__/lanes-lib.test.js
git commit -m "feat(lanes): managed/adopted kinds, worktree fields, session purge, per-lane lock"
```

---

## Task 3: Preflight — counted facts before anything destructive

**Files:**
- Create: `server/lib/lane-preflight.js`
- Test: `server/__tests__/lane-lifecycle.test.js` (new file; later tasks append to it)

**Interfaces:**
- Consumes: `statusCounts`, `unpushedCount`, `listWorktrees` (Task 1); `getLane` (Task 2).
- Produces: `preflight(lane, action): Promise<object>` where `action ∈ "reset" | "remove" | "purge"`.
  - `reset` / `remove` → `{action, lane, kind, branch, dirty, untracked, unpushed, head, blocked: string[], warnings: string[]}`
  - `purge` → `{action, lane, sessions, events, tokenRows, bytesEstimate, activeSessionSkipped: boolean}`
  - `blocked` contains `"adopted"` when the lane is not managed, `"missing"` when the directory is gone, and `"unpushed-commits"` when `unpushed > 0`. It is advisory data, not an exception — the route decides.

- [ ] **Step 1: Write the failing test**

Create `server/__tests__/lane-lifecycle.test.js` with the standard harness (temp `DASHBOARD_DB_PATH`, `DASHBOARD_REMOTE_SYNC_MS=0`, `DASHBOARD_LIVENESS_PROBE=0`, `LANES_ROOT` pointed at a temp dir, `startServer(createApp(), 0)`; copy the request helper from `server/__tests__/lanes-api.test.js`), plus a real git fixture repo as in Task 1. Tests:

```js
it("preflight on an adopted lane blocks and counts nothing", async () => { /* create adopted lane, GET preflight?action=reset, expect blocked includes "adopted" */ });
it("preflight counts dirty, untracked and unpushed for a managed lane", async () => { /* dirty the worktree, expect dirty:1 untracked:1 and a head sha */ });
it("preflight for purge counts only this lane's non-live sessions", async () => { /* two sessions, one bound live, expect sessions:1 and activeSessionSkipped:true */ });
it("preflight 404s for an unknown lane and 400s for an unknown action", async () => {});
```

- [ ] **Step 2: Run to verify it fails**

Run: `node --test server/__tests__/lane-lifecycle.test.js`
Expected: FAIL — the route does not exist yet (404 with an HTML body).

- [ ] **Step 3: Implement `server/lib/lane-preflight.js` and the route**

The module is read-only. `bytesEstimate` is `(events + tokenRows) * 512` — label it in `docs/LANES.md` as a rough estimate, because a real per-row size needs `dbstat`, which is not compiled in by default.

In `server/routes/lanes.js`, add **before** the `/:id/:action` route so it is not swallowed:

```js
router.get("/:id/preflight", async (req, res) => {
  const lane = lanesLib.getLane(req.params.id);
  if (!lane) return res.status(404).json({ error: { code: "ENOLANE", message: "lane not found" } });
  const action = String(req.query.action || "");
  if (!["reset", "remove", "purge"].includes(action)) {
    return res.status(400).json({ error: { code: "EBADACTION", message: `unknown action ${action}` } });
  }
  try {
    res.json(await preflight(lane, action));
  } catch (err) {
    res.status(500).json({ error: { code: err.code, message: err.message } });
  }
});
```

- [ ] **Step 4: Run to verify it passes**

Run: `node --test server/__tests__/lane-lifecycle.test.js`
Expected: PASS, 4 tests.

- [ ] **Step 5: Commit**

```bash
git add server/lib/lane-preflight.js server/routes/lanes.js server/__tests__/lane-lifecycle.test.js
git commit -m "feat(lanes): preflight counts for reset, remove and purge"
```

---

## Task 4: `add` — provision a worktree in the background

**Files:**
- Modify: `server/routes/lanes.js`
- Test: `server/__tests__/lane-lifecycle.test.js` (append)

**Interfaces:**
- Consumes: `addWorktree`, `resolveBase`, `slugify`, `LANES_ROOT` (Task 1); `createLane`, `updateLane` (Task 2); `broadcastLane`, `sameOriginGuard` (existing).
- Produces: `POST /api/lanes/worktree` with body `{sourceRepo, title, base?, slug?}` → `202 {lane}` with `status: "provisioning"`, then a background `lane_update` when the worktree is ready or `status: "failed"` with the git error in `notes`.

- [ ] **Step 1: Write the failing tests** (append)

```js
it("creates a managed lane, returns 202 provisioning, then flips to idle when the worktree lands", async () => {});
it("rejects a sourceRepo that is not an absolute path or not a git repo", async () => {});
it("suffixes the slug when the directory already exists", async () => {});
it("marks the lane failed with git's message when provisioning fails", async () => {});
```

Poll `GET /api/lanes/:id` until `status !== "provisioning"` with a bounded deadline (2 s, 50 ms interval) — never a bare sleep.

- [ ] **Step 2: Run to verify they fail**

Run: `node --test server/__tests__/lane-lifecycle.test.js`
Expected: FAIL — `POST /api/lanes/worktree` 404s.

- [ ] **Step 3: Implement**

Registered before `/:id/:action`, behind `sameOriginGuard`. Validate: `sourceRepo` absolute, exists, `isGitRepo`. Compute `slug = slugify(req.body.slug || req.body.title)`, `dir = path.join(LANES_ROOT, `${path.basename(sourceRepo)}__${slug}`)`, suffixing `-2`, `-3`… while the directory exists. Create the lane row `kind: "managed", status: "provisioning"`, respond `202`, then in the background — wrapped in `withLaneLock(lane.id, …)` — resolve the base, `addWorktree`, and `updateLane` to `status: "idle"` (or `"failed"` with `notes` set to `err.git?.stderr || err.message`), broadcasting either way.

Provisioning must never leave a half-state: if `addWorktree` throws, the lane row stays with `kind: "managed"` and `status: "failed"` so the user can `remove` it, and no directory is left behind that git does not know about.

- [ ] **Step 4: Run to verify they pass** — Expected: PASS, 8 tests total in the file.

- [ ] **Step 5: Commit**

```bash
git add server/routes/lanes.js server/__tests__/lane-lifecycle.test.js
git commit -m "feat(lanes): provision a git worktree for a managed lane"
```

---

## Task 5: `reset`, `remove`, `purge` actions

**Files:**
- Modify: `server/routes/lanes.js`
- Test: `server/__tests__/lane-lifecycle.test.js` (append)

**Interfaces:**
- Consumes: everything from Tasks 1-4.
- Produces: `reset` and `purge` join the `ACTIONS` set; `remove` gains worktree teardown. All three require `{confirm: true}`; `reset` and `remove` additionally require `{force: true}` when preflight reports `unpushed > 0`, and accept `{expect: {head, dirty, untracked, unpushed}}` — a mismatch returns `409 ESTALE`.

- [ ] **Step 1: Write the failing tests** (append)

```js
it("reset requires confirm, restores the branch from base and clears lane state", async () => {});
it("reset refuses with 409 when the worktree has unpushed commits, and proceeds with force", async () => {});
it("reset returns 409 ESTALE when the head moved since preflight", async () => {});
it("remove tears down the worktree and the branch, and deletes the lane row", async () => {});
it("reset and remove refuse an adopted lane with 400 ENOTMANAGED", async () => {});
it("purge deletes the lane's sessions and reports the counts", async () => {});
```

The adopted-lane refusal is the single most important test in this plan: it is what stands between a mis-click and a user's real project directory.

- [ ] **Step 2: Run to verify they fail** — Expected: FAIL, the actions are unknown or non-destructive.

- [ ] **Step 3: Implement**

Inside the existing `/:id/:action` handler, all three branches run within `withLaneLock(lane.id, async () => …)`, and each begins by killing the lane's run and awaiting its exit (poll `runs.getRun(lane.run_id)` until it is no longer `running`/`spawning`, bounded, then clear `run_id`).

Map the guard errors to HTTP: `ENOTMANAGED` / `EOUTSIDEROOT` / `ENOTWORKTREE` → `400` with the code intact; `ESTALE` → `409`; `EUNPUSHED` → `409`; git failures → `500` carrying `err.git.stderr`.

- [ ] **Step 4: Run to verify they pass** — Expected: PASS, 14 tests in the file.

- [ ] **Step 5: Full suite and commit**

Run: `npm run test:server`

```bash
git add server/routes/lanes.js server/__tests__/lane-lifecycle.test.js
git commit -m "feat(lanes): reset, remove and purge with preflight and stale-state guards"
```

---

## Task 6: CLI

**Files:**
- Modify: `bin/ccam.js`
- Test: `server/__tests__/lanes-cli.test.js` (append)

**Interfaces:**
- Consumes: the routes from Tasks 3-5, via the existing `get` / `post` helpers (`bin/ccam.js:191-192`).
- Produces: `ccam lanes add --repo <path> [--title <t>] [--base <branch>]` (worktree mode; the existing `--cwd` form still adopts); `ccam lanes reset|remove|purge <id> [--force]`, each printing the preflight table and refusing without `--yes`.

- [ ] **Step 1: Write the failing tests** (append) — worktree add via CLI lands a managed lane; `reset` without `--yes` exits non-zero and changes nothing; `--yes` performs it.
- [ ] **Step 2: Run to verify they fail.**
- [ ] **Step 3: Implement**, reusing the async `cli()` harness and the existing flag reader. Print the preflight counts as a small aligned table before asking for `--yes`, so the terminal path has the same "confirm against numbers" property as the UI.
- [ ] **Step 4: Run to verify they pass.**
- [ ] **Step 5: Commit** — `feat(lanes): ccam lanes add --repo, reset, remove, purge`

---

## Task 7: UI and docs

**Files:**
- Create: `client/src/components/lanes/DestructiveLaneModal.tsx`
- Modify: `client/src/components/lanes/LaneCard.tsx`, `client/src/lib/api.ts`, `client/src/lib/types.ts`, `client/src/i18n/locales/*/lanes.json`
- Modify: `docs/LANES.md`, `CLAUDE.md`
- Test: `client/src/components/lanes/__tests__/DestructiveLaneModal.test.tsx`

**Interfaces:**
- Consumes: `api.lanes.preflight(id, action)` and `api.lanes.action(id, action, body)`.
- Produces: `<DestructiveLaneModal lane action onClose onConfirm>` — fetches preflight on open, renders the counts, disables the confirm button while loading or when `blocked` contains anything other than `unpushed-commits`, and exposes a "Force" checkbox only for `unpushed-commits`.

- [ ] **Step 1: Write the failing test** — the modal renders the counts it was given; the confirm button is disabled for an `adopted` lane; ticking Force enables confirm when the only blocker is unpushed commits; confirming passes back the `expect` block it displayed.
- [ ] **Step 2: Run to verify it fails.**
- [ ] **Step 3: Implement**, wrapping the repo's existing `ConfirmModal`. `LaneCard` shows a `managed`/`adopted` badge and renders reset/remove/purge only for `managed` lanes. Every string goes through i18n in all four locales.
- [ ] **Step 4: Run `npm run test:client` and `npm run build`.** Review the screens snapshot diff before accepting it.
- [ ] **Step 5: Docs** — `docs/LANES.md` gains a Lifecycle section covering the two kinds, the three safety checks, each verb with what it destroys and what it spares (`clean -fd` keeps gitignored files), the preflight contract, the env vars, and the fresh-worktree-has-no-dependencies limitation. `CLAUDE.md`'s Lanes section gains the rule: **never `rm -rf` a lane; never build a git command as a shell string; adopted lanes are not destroyable.**
- [ ] **Step 6: Header audit and commit** — `feat(lanes): destructive-action modal with preflight counts, lifecycle docs`

---

## Out of scope

- Dependency bootstrap for a fresh worktree (`node_modules`, `.env`) — Shipyard's profile-hook subsystem. A separate sub-project if wanted.
- `VACUUM` as part of `purge` — it locks the whole database; if disk reclamation is wanted it becomes its own maintenance action.
- Per-lane ports, databases, Docker services.
- Stage auto-detection (sub-project B) and the merged Workspace page (sub-project A) — separate specs.