Claude-Code-Monitor/docs/LANES.md

Lanes: Parallel Agent Work Units

A lane is a durable unit of parallel agent work — one working directory, many Claude Code sessions over time. This document describes what lanes are, how to use them, and how the dashboard displays pipeline progress.

What is a lane?

A lane persists across session restarts, which is what makes a pipeline view possible. When you run a Claude Code session, the dashboard binds it to the lane that owns its working directory (cwd) through longest path-boundary prefix matching. This allows:

• Multiple sessions on the same directory to feed into one visible lane
• Nested working directories to own their own nested lanes (deeper paths take precedence)
• A session to migrate from one directory to another without losing its lane relationship

Lanes are keyed by cwd, not `session_id. A session is ephemeral (you run it, it finishes); a lane survives restarts and shows the cumulative progress through a declared pipeline.

Creating a lane

Create a lane bound to a working directory with ccam lanes add:

ccam lanes add --cwd /path/to/repo --title "My Feature"

The lane is now ready to track work. When you run a Claude Code session in that directory (or a subdirectory), the dashboard will bind the session to the lane automatically by matching the cwd.

Note: The directory must exist and be an absolute path. A lane with a cwd of /tmp/wt will NOT capture /tmp/wt-sibling (no partial prefix match) but WILL capture sessions in /tmp/wt/subdir/ (subdirectories are owned by the parent lane unless a deeper lane exists).

To provision a dashboard-managed git worktree instead of adopting an existing directory, use a source repository:

ccam lanes add --repo /path/to/repo --title "My Feature" --base main --slug my-feature

--title, --base, and --slug are optional. The CLI waits for background provisioning to finish and reports either the ready lane or its failure notes.

Destructive lane actions

Reset a managed worktree, remove one, or purge the lane's eligible session history with the CLI:

ccam lanes reset <id> [--force] --yes
ccam lanes remove <id> [--force] --yes
ccam lanes purge <id> --yes

Each command first fetches and prints its preflight counts. reset and remove show head, dirty, untracked, and unpushed; purge shows sessions, events, and tokenRows. The action refuses to run without --yes, and sends those exact facts back as its confirmation. Use --force only when the preflight reports unpushed commits. An adopted lane points at a directory you own, so the CLI refuses to reset it. remove IS allowed for an adopted lane: it drops only the dashboard's record and leaves the directory and its contents untouched.

Lifecycle

The two lane kinds

• managed — a git worktree the dashboard itself created (ccam lanes add --repo), rooted under LANES_ROOT. The dashboard owns its full lifecycle: it may reset the worktree to its base branch or remove it entirely.
• adopted — an existing directory you already had (ccam lanes add --cwd). The dashboard only ever tracks it; it never resets or deletes that worktree. "Removing" an adopted lane drops the dashboard's record of it and leaves the directory untouched.

The three independent safety checks

Before reset or remove touches a worktree, assertDestroyable (server/lib/worktree.js) runs three checks, all of which must pass:

1. lane.kind === "managed". An adopted lane fails immediately with ENOTMANAGED — this check alone is what keeps a directory you own off the destroy path.
2. The lane's cwd, resolved with fs.realpathSync, must sit inside the resolved LANES_ROOT on a path boundary. path.relative(root, cwd) must not start with .. or be absolute — EOUTSIDEROOT otherwise. This guards against a lane row that was hand-edited or drifted to point somewhere else.
3. The resolved path must actually appear in git worktree list --porcelain for the lane's source_repo — ENOTWORKTREE otherwise. A directory that merely happens to sit under LANES_ROOT but was never registered as a worktree of that repo is not destroyed.

These checks run unconditionally inside resetWorktree/removeWorktree themselves, not only when a confirmation is present — there is no code path to a git-destructive operation that skips them.

One documented exception, which does not weaken them: when a managed lane's directory has already been deleted by hand, removeWorktree takes a prune path instead. Checks 1 and 2 still hold (an adopted lane is refused outright; the recorded cwd must still be inside LANES_ROOT, verified lexically because a vanished path cannot be resolved), and check 3 is what the prune replaces — a worktree git no longer lists needs no removal. That path runs git worktree prune plus a safe branch delete against the source repo's bookkeeping and touches no directory at all.

Each verb

• add — either adopts an existing directory (--cwd, kind adopted) or provisions a new managed worktree (--repo, kind managed, created under LANES_ROOT on branch feat/<slug>).
• clear (UI/API action only, no CLI verb) — resets the lane's own bookkeeping (stage, status, gate/CI fields, notes) back to idle, including the detected columns (detected_stage/detected_signal/detected_at), since detection is forward-only and a surviving detection would both claim progress the reset tree no longer has and block every later detection. Touches only the lanes row; no git operation, no session/event data is deleted.
• reset (managed lanes only) — checks out the base branch, git reset --hard to it, then git clean -fd (no -x, so gitignored files such as node_modules and .env survive; only untracked-but-not-ignored files are deleted), then recreates the feature branch off the base and clears the lane's bookkeeping. Requires force: true when the preflight reports unpushed commits.
• remove — for a managed lane whose directory exists: git worktree remove --force, git worktree prune, then a safe branch delete, then the lane row is deleted. For a managed lane whose directory was deleted by hand: the prune path above (git's stale record and the branch are cleaned up, then the row is deleted) — a missing worktree does NOT make a lane unremovable. For an adopted lane: only the lane row is deleted (removeWorktree is never invoked for adopted, so the directory is never touched). The unpushed-commits force-gate only applies when the worktree is actually touched, i.e. action === "remove" && kind === "managed" — forgetting an adopted lane needs no force even with unpushed commits, since nothing on disk is at risk.
• purge — deletes the lane's own sessions/events/token_usage rows (excluding the lane's currently-bound or any still-active session), for its own cwd and subdirectories. No git operation, no worktree change; not gated on unpushed commits.

The preflight contract

GET /api/lanes/:id/preflight?action=reset|remove|purge (server/lib/lane-preflight.js) is read-only and returns:

• reset/remove: { action, lane, kind, branch, head, dirty, untracked, unpushed, blocked[], warnings[] }
• purge: { action, lane, sessions, events, tokenRows, bytesEstimate, activeSessionSkipped }

blocked[] can contain: adopted (not a managed worktree), missing (the directory is gone), unreadable (directory exists but git failed against it), and unpushed-commits (unpushed count > 0 — the only one a force: true can override).

Which entries actually prevent the action depends on the action, and the server is the authority. All of them block reset. None of them blocks remove — the server supports removing an adopted lane (forget the row), a hand-deleted worktree (prune path), and an unreadable one: it attempts git worktree remove --force, and if git itself refuses (e.g. a corrupt worktree .git pointer, which git validates and rejects even with a second --force), it deregisters the worktree directly from the source repo's bookkeeping instead — the directory itself is never touched either way. A surface that greys out confirmation on any blocked entry regardless of action makes a documented capability unreachable; client/src/components/lanes/DestructiveLaneModal.tsx encodes the per-action set in HARD_BLOCKERS and renders the rest as context.

unpushed is the count of commits the action would really discard: with remotes, commits on no remote; without remotes, the commits ahead of the lane's base_branch, which is this lane's own work. A freshly provisioned worktree in a local-only repository reports 0, not that repository's whole history — the no-remote warning, not an inflated count, is what tells the user nothing is backed up. A lane with no base_branch at all (an adopted one) falls back to the total commit count. warnings[] holds purely informational facts that never gate the action: currently just no-remote (no git remote configured at all — nothing here is backed up remotely, but the action proceeds normally). Both arrays are data, not an exception.

bytesEstimate is a rough estimate, not a measured disk size: it is derived as (events + tokenRows) * 512, a flat per-row byte guess, purely to give the confirmation dialog an order-of-magnitude sense of what purging will reclaim.

Every destructive POST /api/lanes/:id/:action must echo back an expect object with exactly the fields listed above for that action. The server re-runs preflight at execution time and rejects the request (400 EEXPECT if incomplete, 409 ESTALE if any field has changed since the client read it) rather than trusting a client-supplied count.

Environment variables

• LANES_ROOT (default ~/.claude/ccam-lanes) — the directory managed worktrees are provisioned under; also the boundary that safety check 2 resolves paths against.
• LANE_DEAD_SEC (default 300) — seconds of silence before a lane whose stage matches /watch|poll/i flips from active to dead liveness.
• LANE_BASE_BRANCH (default main) — the base branch a new managed worktree resolves against when a request omits base. An explicit --base <branch> (or request body base) always wins over this default.
• LANE_BRANCH_PREFIX (default feat/) — the prefix used to build a new managed worktree's feature branch name (<prefix><slug>).

Limitation: a fresh worktree has no dependencies

ccam lanes add --repo runs git worktree add only. It does not run npm install (or any other package manager), and it does not copy the source repo's untracked local files (.env, IDE config, etc.) into the new worktree. A managed lane is ready for git immediately but needs its own dependency install and local env setup before a session can run the project inside it — bootstrapping that automatically is out of scope for this feature (see docs/superpowers/specs/2026-07-28-worktree-lanes-design.md).

The Workspace page (/run)

The dashboard web UI merges lanes and runs into a single Workspace page accessible at /run (the old /lanes route now redirects here). Top to bottom:

• Header — the page title and four counters (lanes, running, needs you, dead), plus Add lane. The needs you and dead counters appear only when they are non-zero, so a quiet header means nothing is waiting on a human.
• Detail panel — the selected lane's declared stage, its inferred stage when detection leads, a full-width pipeline map, and a legend naming all five node states plus the dashed-amber inferred treatment.
• Console — RunSetup, RunConsole and RunHistory behind a disclosure that starts collapsed. Watching lanes is the default posture; driving one is the exception. Collapsing hides the console with CSS and never unmounts it, so a live run keeps its rendered history and scroll position.
• Lane grid — one card per lane, 1 column, 2 at md, 3 at xl. Each card carries the lane id, liveness dot and status, title, declared stage with a progress bar and time-on-stage, the auto: chip when detection leads, the kind and CI tags, the working-copy facts from GET /api/lanes/:id/git, the needs-you banner, and the action row.

Run history is per lane, queryable via GET /api/run/history?laneId=<n>.

The UI operates on a working directory (cwd), not a lane id. Starting a run in a cwd that no lane owns calls POST /api/lanes/ensure first, to idempotently find or adopt a lane for that path; a cwd an existing lane already owns is matched from the loaded lane list without a round trip. Either way the run is then started through POST /api/lanes/:id/start rather than directly through POST /api/run.

Finding or adopting a lane: POST /api/lanes/ensure

The Workspace page opens on a cwd and needs a lane to exist for that directory without ever creating a duplicate. The ensure endpoint handles this:

curl -X POST http://localhost:4820/api/lanes/ensure \
  -H "Content-Type: application/json" \
  -d '{"cwd": "/absolute/path/to/work", "title": "My Project"}'

Response:

{
  "lane": { "id": 5, "cwd": "/absolute/path/to/work", "title": "My Project", ... },
  "created": false
}

• If a lane already owns the cwd, returns that lane with created: false and HTTP 200.
• If the cwd is a subdirectory of an existing lane, returns the parent lane that owns it.
• If no lane owns the cwd, creates an adopted lane and returns it with created: true and HTTP 201.
• A relative or missing cwd returns 400 EBADCWD.

Two concurrent calls for the same path always yield one lane: the database's UNIQUE constraint on lanes.cwd decides the winner, and the loser re-reads and returns the winning lane.

Reading a lane's working copy: GET /api/lanes/:id/git

Each lane card shows the branch its working copy is actually on, the short HEAD, that commit's subject, and how much is uncommitted:

curl http://localhost:4820/api/lanes/5/git

{
  "available": true,
  "branch": "feat/rename-metric",
  "head": "9b3e74a",
  "subject": "free-text rule mode in the form",
  "dirty": 2,
  "untracked": 1
}

• A cwd that is missing, is not a git repository, or makes git fail returns {"available": false} with HTTP 200. A lane pointing at a plain directory is a normal state, not a fault, and the card simply renders without a git row.
• A detached checkout reports the literal HEAD that git returns, rather than a prettier invention.
• An unknown lane id is a 404.

This is not folded into GET /api/lanes on purpose: it shells out to git three times, and the lane list is polled and re-broadcast on every hook-driven lane_update. Putting it there would fire a burst of subprocesses behind every tool call an agent makes. The browser fetches it per card instead, on mount and every 30 seconds, and a failed fetch is silent.

Running and releasing lanes

The Workspace page starts runs through POST /api/lanes/:id/start, which accepts the same mode and effort parameters as POST /api/run:

curl -X POST http://localhost:4820/api/lanes/5/start \
  -H "Content-Type: application/json" \
  -d '{"mode": "conversation", "effort": "medium"}'

A finished run releases its lane. When a spawned Claude Code process exits (normally, non-zero, killed, or never spawned), the lane's run_id is cleared, its status returns to idle, and the change is broadcast as a lane_update WebSocket message. This prevents lanes from sitting at running with a dead child.

Runs started through a lane are recorded with the lane's id and are history-queryable:

curl http://localhost:4820/api/run/history?laneId=5

Viewing lanes

List all lanes with their current status:

ccam lanes

This shows each lane's:

• stage: the declared stage (e.g., plan, implement, review, done)
• status: running (a session is active), idle (no active session), or provisioning
• liveness: active (recently updated), dead (silent for too long), or idle (not expected to be running)
• progress: percentage of the pipeline completed (0–100%)
• needs_action: a notification if the session is blocked waiting for input

A lane row also gets a ⇢ detected:<stage> suffix when the server's inferred stage (see "Stage detection" below) leads the declared stage shown in the row — the same lead/behind comparison the web UI's auto: <stage> chip uses, so the terminal and the browser never disagree about which one is the headline. Nothing is printed when the declaration already leads or matches.

The dashboard web UI shows each lane as a card in a grid, with the selected lane's pipeline map visualized above.

Pipeline stages and the five node states

A lane moves through stages defined in a pipeline template (see "Custom pipeline templates" below). The default pipeline has eight stages: intake, plan, implement, tests, review, gate, ship, and done.

The dashboard renders every node in the pipeline in one of five states:

State	Color	Meaning
failed	Red	The stage recorded result "fail" — work was attempted and rejected
current	Blue	The lane's current declared stage
done	Green	The stage was recorded with evidence (an artifact, not just a claim)
passed-no-evidence	Amber	The stage was recorded without evidence, OR was skipped (a later stage was reached)
pending	Gray	Not reached yet

Why passed-no-evidence is amber, not green

A stage in this state was claimed but not proven. Two scenarios:

1. Declared but no artifact left. A skill called ccam stage review without --evidence, claiming the stage happened but leaving no proof that work occurred.
2. Implicitly skipped. The lane jumped from plan to implement (to stage index 2), leaving intake (index 0) in passed-no-evidence state.

In both cases, the stage is not done — it's incomplete or untested. Amber signals that the agent claimed to have done this work but the dashboard has no evidence to show it was actually completed. This matters in a pipeline: if your gate checks done not passed-no-evidence, a lane stuck in amber will block until evidence is provided.

Reporting a stage

When a skill reaches a significant milestone, it reports the current stage to the dashboard using ccam stage:

ccam stage implement --evidence "Schema created, migrations run"

This command:

• Declares the stage the work is now at
• Records evidence (optional, but highly encouraged) — a short text description of what was completed
• Moves the progress bar forward in the pipeline
• Broadcasts to the UI so connected dashboards see the update in real-time

Full command signature

ccam stage <stage> [--lane <id>] [--cwd <path>] [--status <s>] [--evidence <text>] [--note <text>] [--result pass|fail]

Parameters:

• <stage> (required): the pipeline stage name or alias. The default pipeline aliases are:

  • intake / assigned / claimed / start
  • plan / planning / brainstorm / design
  • implement / implementing / coding / build
  • tests / testing / unit / gates / pre-push-gate
  • review / reviewing / code-review / self-review
  • gate / verify / verification / sr-gate / gate-blocked
  • ship / pr / pr-open / publishing / commit / push
  • done / complete / completed / merged

• --lane <id> (optional): the numeric lane ID. If omitted, the command resolves the lane by cwd.

• --cwd <path> (optional): working directory to match against a lane's cwd. If omitted, uses the current working directory. Useful when calling from outside the repo.

• --status <s> (optional): the lane's overall status (running, idle, provisioning). Allows bundling a status update with the stage report.

• --evidence <text> (optional): a short description of what was completed at this stage. Moves the node from passed-no-evidence to done.

• --note <text> (optional): a longer note or comment, separate from evidence.

• --result pass|fail (optional): explicitly mark the stage as passed or failed. Ignored if result was already set; set once, never overwritten by a re-report.

Example: a skill reporting progress

A build skill might call:

ccam stage implement --evidence "Built and ran tests, 42 tests passing" --status running

Output:

lane #5 → implement (66%)

A later call reports completion:

ccam stage tests --evidence "Pre-push gate: all linters passing" --result pass

Custom pipeline templates

The default pipeline is suitable for feature work: intake → plan → implement → tests → review → gate → ship → done. For different workflows (data pipelines, research phases, deployment stages), you can provide custom templates.

Where templates come from

1. Built-in: server/data/pipelines/default.json (always available)
2. User override: directory specified by the DASHBOARD_PIPELINES_DIR environment variable

If both exist, files in the user directory override built-ins with the same id.

Custom template format

Create a JSON file in your custom pipeline directory (e.g., ~/.ccam/pipelines/ml-training.json):

{
  "id": "ml-training",
  "name": "ML Training Pipeline",
  "nodes": [
    { "id": "data",      "label": "data",      "icon": "📊", "gate": false, "aliases": ["intake"] },
    { "id": "preprocess","label": "preprocess","icon": "⚙️", "gate": false, "aliases": ["prepare", "clean"] },
    { "id": "train",     "label": "train",     "icon": "🧠", "gate": false, "aliases": ["training", "fit"] },
    { "id": "eval",      "label": "eval",      "icon": "📈", "gate": true,  "aliases": ["evaluate", "metrics"] },
    { "id": "deploy",    "label": "deploy",    "icon": "🚀", "gate": false, "aliases": ["ship", "release"] }
  ]
}

Schema:

• id (string, required): unique identifier for this template
• name (string, optional): display name shown in the UI
• nodes (array, required): list of pipeline stages, in order
  • id (string): stage identifier (used in ccam stage)
  • label (string, optional): display name in the UI; defaults to id if omitted
  • icon (string, optional): unicode emoji or single character shown before the stage name
  • gate (boolean, optional): true if this stage blocks unless explicitly passed; defaults to false
  • aliases (array, optional): alternative names for the stage (e.g., ["training", "fit"] lets you call ccam stage training)

Then set the environment variable:

export DASHBOARD_PIPELINES_DIR=~/.ccam/pipelines

When you create a new lane, you can optionally specify which pipeline to use:

ccam lanes add --cwd /path/to/ml-repo --title "Training run #1" --pipeline ml-training

(The pipeline is selected at creation time. Lanes created without --pipeline default to the default pipeline.)

Stage detection

Besides the stage a skill explicitly declares with ccam stage, the dashboard also infers a stage from the tool events every hook already delivers (POST /api/hooks/event). This is a best-effort heuristic for un-instrumented sessions that never call ccam stage — it fills in a lane's pipeline map without requiring every skill to be rewritten.

The evidence boundary

An inferred stage is never evidence and never renders as done. Green (done) requires a stage the agent explicitly declared with evidence; an inference can reach dashed amber at most — visually distinct from both solid green done and solid amber passed-no-evidence (client/src/components/lanes/PipelineMap.tsx). This boundary exists because detection is a guess from tool names and a handful of string fields, not proof that the agent actually finished the stage — a Bash call matching npm run test could be a flaky retry, not a passing suite. Treating it as proof would let a lane's pipeline map lie about what actually happened.

The node the agent declared itself on is never flagged as detected, so it keeps its blue current ring — including when the declaration came in through an alias (ccam stage coding resolves to the implement node, and stages is keyed by the raw declared word, not the node id).

The same rule governs ccam lanes: the inferred stage is printed only when it leads the declared one (see "Viewing lanes" below), and LaneCard.tsx's detectionLeadsDeclaration shows its auto: <stage> chip under the identical condition — the terminal and the browser never disagree about which one is the headline.

What signals are read

server/lib/stage-detect.js inspects every incoming hook's tool_name and tool_input (touchLaneFromHook in server/routes/hooks.js calls detect() on each hook). Detection runs ahead of the lane's needs_action/session_id bookkeeping — that block returns early when there is nothing to patch, so detection could not live after it — and therefore sits in a try/catch of its own: a throwing recordDetection (ENOLANE on a lane deleted mid-hook, SQLITE_BUSY) must never cost the bookkeeping that predates it. Only these tool_input fields are read — never old_string/new_string or other editor payloads that can contain whole code blocks:

• command
• file_path
• skill
• prompt
• pattern
• description
• subagent_type

The signal shown to the user is the span the rule's regex actually matched, plus 24 characters of context on each side, with an ellipsis marking either end that was trimmed. A shell line like cd /home/very/long/path && npm run test:server 2>&1 therefore reports `…path && npm run test:server 2>&1` rather than the whole command. A rule with no match fired on the tool name alone and has no span, so it falls back to the flattened input. Either way the result is capped at 120 characters (collapsing whitespace first) and stored as detected_signal — this is why a lane's tooltip sometimes shows a file path or a skill name rather than a shell command: it's whichever of the fields above the matching rule's tool carried.

Detection expires

Forward-only would otherwise park a lane at the highest stage it ever touched: a session that ran the test suite reaches tests and can never show implement again, even while the agent is back editing code.

So a standing detection holds the forward-only floor only while it is fresh. Once detected_at is older than DETECTION_TTL_MS (default 1800000, i.e. 30 minutes), the comparison against detected_stage is skipped and the new signal wins regardless of direction. A detected_at that is NULL or unparseable counts as stale — an unknown age cannot be proven fresh.

Two things the expiry deliberately does NOT do:

• It does not weaken declared-wins. An agent's own claim never expires: a lane declared at review still refuses an implement detection, stale standing detection or not.
• It does not let inference render done. Everything in "An inferred stage is never evidence" above still holds. The TTL changes which detection is current, never what a detection is worth.

Set DETECTION_TTL_MS in the server's environment to change the window; it is read per call, so no restart is needed for a test harness that sets it.

Where the rules live

Detection rules are not code — they live in the pipeline template itself, as a detect array on each node. The built-in default.json (server/data/pipelines/default.json) ships these rules today, node by node:

Node	Detect rules
intake	none — see below
plan	Skill matching brainstorming|writing-plans; Write matching docs/.*plan.*\.md
implement	Edit (any); Write to any path NOT under a docs/ directory (^(?!.*(?:^|/)docs/))
tests	Bash matching \b(npm (run )?test|pytest|vitest|jest|go test|cargo test)\b
review	Skill matching code-review|requesting-code-review; Bash matching git diff|gh pr diff
gate	none — see below
ship	Bash matching git push|gh pr create
done	none — see below

intake, gate, and done deliberately have no rules. intake is where a lane starts — there is no tool event that means "just claimed," so there is nothing to detect. gate and done are explicitly out of scope for inference (see the task's "Out of scope" list): a gate's pass/fail is a human or skill decision, and done is the one state detection must never reach on its own — inferring either would let a heuristic assert an outcome instead of observing activity.

To add a rule, drop a template into the directory named by the DASHBOARD_PIPELINES_DIR environment variable (see "Custom pipeline templates" above) with a detect array on the node you want to match:

{ "id": "implement", "label": "implement", "detect": [
  { "tool": "Bash", "match": "docker build" }
] }

match is a JavaScript regular expression tested against the flattened tool_input string; omit match entirely to match on tool name alone. An invalid regex is skipped rather than blocking hook ingestion.

Forward-only, write-on-change

Detection never rewinds a lane and never fights a declaration:

• Forward-only. A detection only overwrites detected_stage when its node index is strictly greater than the current detected_stage's index — reading a file after editing it must not drag a lane back to plan.
• Declared beats detected. A detection is written only when the lane's declared stage index is strictly less than the detection's. A lane already declared at review ignores an implement detection outright.
• Write-on-change only. The database write (and the lane_update WebSocket broadcast) happens only when recordDetection reports an actual change. A real install saw 29,470 Bash events alone from one project — writing to the DB and broadcasting on every matching hook, rather than only on a genuine advance, would turn routine ingestion into a DB write and a WS frame per tool call.

Detection writes only detected_stage, detected_signal, and detected_at (server/lib/lanes.js's recordDetection) — it never writes lanes.stage, the declared field. The agent's own declaration is the only path to a stage being recorded as done.

Liveness: detecting dead lanes

The dashboard watches for silent sessions using two rules:

The liveness rule

A lane's liveness state (shown as active, idle, or dead) depends on:

• Lane status (running, idle, provisioning)
• Stage name (does it match watch|poll regex?)
• Age (how long since the last event?)

Idle lanes are never dead. If a lane's status is idle, it's at rest by design — no session is expected to be running. A session might connect later.

Watching sessions die after silence. When a lane's stage matches the pattern /watch|poll/i (e.g., stage watch-for-updates), the session is expected to emit heartbeat events. If it goes silent for longer than LANE_DEAD_SEC (default 300 seconds), the dashboard marks it as dead. A watcher with no events is a dead process; an idle session with no events is just idle.

Configuring the timeout

Set the environment variable to change when a watcher is considered dead:

export LANE_DEAD_SEC=600  # 10 minutes instead of 5

Lane actions

The web UI and CLI provide these actions on a lane:

start

Launch a new Claude Code session bound to the lane. If the lane has a recorded session_id from a previous run, you can resume it instead with --resume.

curl -X POST http://localhost:4820/api/lanes/5/start \
  -H "Content-Type: application/json" \
  -d '{"prompt": "continue the work", "resume": true}'

mode accepts the same two values as POST /api/run — "conversation" (the default: multi-turn, message keeps working) or "headless" (one shot, the prompt goes in argv and the process exits when the turn finishes). Unlike POST /api/run, an unknown value is refused with 400 EBADMODE rather than silently treated as a conversation.

A finished run releases its lane. When the child truly exits — normally, non-zero, killed, or never spawned at all — the lane's run_id is cleared, its status returns to idle, and the change is broadcast as lane_update. So a lane never sits at running behind a dead run, and message reports 409 ENORUN instead of targeting one. Runs started this way are recorded with the lane's id and are listable via GET /api/run/history?laneId=<n>.

Currently the prompt field does not populate the input field in the UI (see "Known limitations" below).

message

Send input to a running session. The lane must have a live run_id (active session). The needs_action flag clears automatically when the message is delivered.

curl -X POST http://localhost:4820/api/lanes/5/message \
  -H "Content-Type: application/json" \
  -d '{"text": "approved, proceed"}'

stop

Terminate the running session. If the lane has no live run, this is a no-op (no error).

curl -X POST http://localhost:4820/api/lanes/5/stop

clear

Reset the lane's pipeline progress, stages, notes, and inferred stage. The lane itself persists; only its recorded history is cleared.

curl -X POST http://localhost:4820/api/lanes/5/clear

remove

Delete the lane entirely, including all its history. Requires confirmation (confirm: true):

curl -X POST http://localhost:4820/api/lanes/5/remove \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

Actions gated behind confirmation: remove requires the confirm flag to prevent accidental deletion.

Orchestration: what CCAM does NOT do

CCAM does not chain, queue, retry, or evaluate gates.

The driving Claude Code session is in control. Here's what that means:

• No automatic chaining: The lane doesn't automatically move from one stage to the next. A skill declares the stage explicitly with ccam stage.
• No queue: There is no work queue. When you run a session, it runs immediately; no waiting for dependencies or prior stages.
• No retry logic: If a stage fails (marked with --result fail), the lane stays at that stage. The next session must be told to reattempt it (the skill logic decides).
• No gate evaluation: A gate stage (marked gate: true in the template) doesn't block the UI, stop a session, or prevent a transition. It's just a visual marker. The skill must check the gate condition and decide whether to proceed.

Example: In a feature pipeline, if the tests stage is a gate, and tests fail:

1. A skill calls ccam stage tests --result fail --evidence "5 tests failing"
2. The UI shows tests in red (failed state)
3. The next session runs and a human/skill must explicitly decide: re-run tests, or skip to ship?
4. If re-running: ccam stage tests --evidence "2 tests still failing"
5. If skipping: ccam stage ship --evidence "manual gate override"

The dashboard shows the history; the driving session makes the decisions.

Known limitations

Lanes page snapshot

The Lanes screen currently shows only the empty state in the dashboard's design. Full design and implementation of the populated view (multiple lanes, interactions, pipeline map) is deferred to a follow-up.

Lane card UI

The lane card UI currently has no prompt/message input field. When you click start, it opens a promptless conversation run in Claude Code (no initial input). The message action exists server-side and via the API but is not exposed in the web UI yet. To send messages, use the API directly or the CLI.

Related commands

ccam lanes                                    # List all lanes
ccam lanes add --cwd <path> --title <text>    # Adopt an existing directory
ccam lanes add --repo <path> [--title <text>] [--base <branch>] [--slug <slug>]
ccam lanes reset|remove|purge <id> [--force] --yes
ccam stage <stage> [--evidence "..."]         # Report the current stage

See also

• server/lib/lanes.js — lane storage and lifecycle
• server/lib/worktree.js — git worktree creation/reset/removal and the three-check destroy guard
• server/lib/lane-preflight.js — the read-only preflight facts behind reset/remove/purge
• server/lib/pipelines.js — pipeline templates and node state derivation
• server/lib/stage-detect.js — the stage-detection matcher, field allowlist, and signal cap
• server/routes/lanes.js — REST API surface
• bin/ccam.js — CLI commands for lanes and stage reporting
• server/routes/hooks.js — hook-to-lane binding by cwd, and where detection is invoked