{nodes.map((n, i) => (

{n.icon} {n.label}

{i < nodes.length - 1 &&

}

))}

); } ``` - [ ] **Step 4: Run test to verify it passes** Run: `cd client && npx vitest run src/components/lanes/__tests__/PipelineMap.test.tsx` Expected: PASS, 3 tests. - [ ] **Step 5: Add the API client group** In `client/src/lib/api.ts`, add the three interfaces from the **Interfaces** block above next to the other exported types, then add this group to the `api` object, matching the surrounding group style (same `request` helper, same scoped-GET convention): ```ts lanes: { list: () => request<{ lanes: Lane[]; counts: LaneCounts }>("/lanes"), get: (id: number) => request<{ lane: Lane }>(`/lanes/${id}`), create: (body: { title?: string; cwd: string; branch?: string; pipeline?: string }) => request<{ lane: Lane }>("/lanes", { method: "POST", body: JSON.stringify(body) }), update: (id: number, patch: Partial) => request<{ lane: Lane }>(`/lanes/${id}`, { method: "PATCH", body: JSON.stringify(patch) }), stage: (id: number, body: { stage: string; status?: string; evidence?: string; note?: string; result?: string }) => request<{ lane: Lane }>(`/lanes/${id}/stage`, { method: "POST", body: JSON.stringify(body) }), action: (id: number, action: string, body: Record = {}) => request<{ lane?: Lane; ok?: boolean }>(`/lanes/${id}/${action}`, { method: "POST", body: JSON.stringify(body), }), }, ``` - [ ] **Step 6: Write `LaneCard.tsx`** Create `client/src/components/lanes/LaneCard.tsx`: ```tsx /** * @file One lane's card: title, stage badge with time-on-phase, progress bar, * branch/CI/PR facts, the "needs you" banner sourced from Claude Code's * Notification hook, and the control row. A dead lane (its driving session went * silent while it should have been working) is called out loudly — that is the * failure this view exists to catch. * @author Nguyễn Ngọc Trí Vĩ */ import type { Lane } from "../../lib/api"; const LIVENESS_DOT: Record = { active: "bg-emerald-400", idle: "bg-neutral-500", dead: "bg-red-500", }; function since(sec: number | null): string { if (sec === null) return "—"; if (sec < 60) return `${sec}s`; if (sec < 3600) return `${Math.floor(sec / 60)}m ${sec % 60}s`; return `${Math.floor(sec / 3600)}h ${Math.floor((sec % 3600) / 60)}m`; } export default function LaneCard({ lane, onAction, }: { lane: Lane; onAction: (action: string, body?: Record) => void; }) { return (

Lane {lane.id} {lane.liveness === "dead" ? "DEAD" : lane.status.toUpperCase()}

{lane.title || lane.cwd}

{lane.stage}

{lane.progress}% {since(lane.stage_seconds)}

{lane.needs_action && (

⚠ {lane.needs_action}

)}

{lane.branch &&

⑂ {lane.branch}

} {lane.ci_status &&

CI {lane.ci_status}

}

{lane.cwd}

{(["start", "stop", "clear"] as const).map((a) => ( ))}

); } ``` - [ ] **Step 7: Write `Lanes.tsx`** Create `client/src/pages/Lanes.tsx`: ```tsx /** * @file The Lanes page: header counters, the selected lane's pipeline map, and * a card grid of every lane. Data arrives two ways — one `GET /api/lanes` on * mount, then incremental `lane_update` messages off the shared event bus — so * the page stays live without polling. * @author Nguyễn Ngọc Trí Vĩ */ import { useCallback, useEffect, useState } from "react"; import { api, type Lane, type LaneCounts } from "../lib/api"; import { eventBus } from "../lib/eventBus"; import PipelineMap from "../components/lanes/PipelineMap"; import LaneCard from "../components/lanes/LaneCard"; export default function Lanes() { const [lanes, setLanes] = useState([]); const [counts, setCounts] = useState({ total: 0, running: 0, needs_you: 0, dead: 0 }); const [selected, setSelected] = useState(null); const refresh = useCallback(async () => { const r = await api.lanes.list(); setLanes(r.lanes); setCounts(r.counts); setSelected((cur) => (cur !== null && r.lanes.some((l) => l.id === cur) ? cur : (r.lanes[0]?.id ?? null))); }, []); useEffect(() => { void refresh(); // Incremental: a lane_update carries the whole lane, so patch in place and // only refetch when a lane disappears (counters must stay truthful). return eventBus.subscribe((msg: WSMessage) => { if (msg.type !== "lane_update") return; const payload = msg.data as { lane?: Lane; removed?: number }; if (payload.removed !== undefined) return void refresh(); const lane = payload.lane; if (!lane) return; setLanes((cur) => { const i = cur.findIndex((l) => l.id === lane.id); if (i === -1) return [...cur, lane]; const next = [...cur]; next[i] = lane; return next; }); }); }, [refresh]); const act = async (id: number, action: string, body?: Record) => { await api.lanes.action(id, action, body); if (action === "remove") await refresh(); }; const current = lanes.find((l) => l.id === selected) || null; return (

Lanes

{counts.total} lanes {counts.running} running {counts.needs_you > 0 && ( {counts.needs_you} need you )} {counts.dead > 0 && ( {counts.dead} dead )}

{current && (

Lane {current.id} · {current.title || current.cwd} · {current.pipeline_name}

)}

{lanes.map((l) => ( ))}

{!lanes.length && (

No lanes yet. Create one from a working directory: ccam lanes add --cwd $(pwd)

)}

); } ``` `eventBus.subscribe(handler)` (`client/src/lib/eventBus.ts:109`) receives EVERY inbound `WSMessage` and returns its own unsubscribe function — hence the `msg.type !== "lane_update"` filter and returning the disposer straight out of the effect, matching `client/src/pages/Dashboard.tsx:1082`. Import both `eventBus` and the `WSMessage` type (`client/src/lib/types.ts:1648`). Because `WSMessage["type"]` is a closed union, add `"lane_update"` to it in `client/src/lib/types.ts` and extend the `data` union with `{ lane?: Lane; removed?: number }` — otherwise the filter above does not typecheck. - [ ] **Step 8: Route and nav** In `client/src/App.tsx`, add the import beside the other page imports and the route beside the others inside `Layout`: ```tsx import Lanes from "./pages/Lanes"; ``` ```tsx } /> ``` In `client/src/components/Sidebar.tsx`, add a nav item pointing at `/lanes` with the label pulled from i18n, matching the existing item structure. Add the string key `nav.lanes` (value `"Lanes"`) to every locale file under `client/src/i18n/`. - [ ] **Step 9: Run the client suite** Run: `npm run test:client` Expected: PASS. The per-screen snapshot suite (`client/src/pages/__tests__/screens.snapshot.test.tsx`) may fail solely because a new nav entry exists — review the diff, confirm it is only the added Lanes item, then regenerate with `cd client && npx vitest run -u`. - [ ] **Step 10: Header audit, build, commit** Run: `bash .claude/skills/file-headers/scripts/check-headers.sh` Run: `npm run build` Expected: both clean. ```bash git add client/src/components/lanes client/src/pages/Lanes.tsx client/src/lib/api.ts client/src/App.tsx client/src/components/Sidebar.tsx client/src/i18n git commit -m "feat(lanes): lanes page with pipeline map and live updates" ``` --- ## Task 8: Docs The repo's own rules require docs to move with behavior. This is one task, not a step folded into each of the above, because it is a single coherent write-up. **Files:** - Create: `docs/LANES.md` - Modify: `CLAUDE.md` (a `## Lanes` section: what a lane is, that CCAM does not orchestrate, and that stage reporting is the agent's job via `ccam stage`) - Modify: `README.md` (one paragraph + the two new CLI commands in the command list) **Interfaces:** - Consumes: the behavior shipped in Tasks 1-7. - Produces: no code. - [ ] **Step 1: Write `docs/LANES.md`** It must cover, with exact paths and runnable commands: what a lane is and why it is keyed by `cwd` rather than `session_id`; the five node states and specifically why `passed-no-evidence` is amber rather than green; how a skill reports a stage (`ccam stage review --evidence "3 findings"`); how to add a custom pipeline template (`DASHBOARD_PIPELINES_DIR`, the JSON shape from `server/data/pipelines/default.json`); the liveness rule (`LANE_DEAD_SEC`, why a silent watcher is dead but a silent idle lane is not); and an explicit statement that CCAM does not chain, queue, retry, or gate — the driving Claude session does. - [ ] **Step 2: Update `CLAUDE.md` and `README.md`** - [ ] **Step 3: Commit** ```bash git add docs/LANES.md CLAUDE.md README.md git commit -m "docs(lanes): document lanes, pipeline templates and stage reporting" ``` --- ## Out of scope (deliberately) Named here so a later reader knows these were decided, not forgotten: - **Worktree / port / database provisioning per lane.** Shipyard's `bin/lane-up.sh` territory. A lane here is just a directory that already exists. - **Any orchestrator** — no queue, no step chaining, no retry, no gate evaluation. Approach A: adding one would create a second scheduler competing with the Claude session that is already driving. - **An MCP `report_stage` tool.** `ccam stage` covers it with no TypeScript build step. Add the MCP tool later only if a session turns out to reach for tools more reliably than Bash. - **Stage inference from `TodoWrite` / `workflows.phases` for un-instrumented sessions.** Worth doing, but it is a distinct feature (inferred vs declared stage, with the UI distinguishing them) and belongs in its own plan once declared stages are proven.