AgentHub/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 agenthub lanes add:

agenthub 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). A cwd that exists is stored by its real path (fs.realpathSync.native), so /tmp/wt on macOS is stored as /private/tmp/wt and a differently-cased path on a case-insensitive volume as the spelling on disk — the path a session reports. A path that does not exist yet is resolved through its deepest existing ancestor (/tmp/new → /private/tmp/new); rows created before this rule keep theirs.

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

agenthub 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.

Adopting your main repo (agenthub lanes add --cwd $(pwd)) is also how you get stage detection working for sessions that work directly in it rather than in a worktree — see "Superpowers skill invocations" below. Once adopted, that lane's own card lists every managed-worktree lane whose source_repo matches its cwd, each a clickable link to jump to that lane.

Adding a lane through the dashboard's "+ Add lane" flow also auto-runs, best-effort, in parallel: agenthub lanes profile init (only if a Node.js project is detected — most repos won't be, and that's a normal outcome, not a failure), agenthub lanes agents install, and agenthub lanes mcp sync. None of the three blocks the lane from being created or from each other — a lane whose repo has no MCP servers configured, for instance, still gets created and is still usable, just without a synced .mcp.json. The modal shows a ✓/✗ summary of the three results and stays open until dismissed (Cancel/X) — it does not auto-close. Run any of the three manually later (from the lane's own card, or the CLI) if the automatic attempt didn't apply.

The "+ Add lane" modal

The modal has a segmented toggle mirroring the CLI's two modes:

• Repo — adopts the given directory as-is (maps to agenthub lanes add --cwd). No branch fields; the auto-setup summary above does not run (adopting is instant, nothing to wait on).
• Worktree (default) — provisions a managed worktree (maps to agenthub lanes add --repo).

In Worktree mode the branch question has three answers, because git's own rule decides which is available (issue #34):

• New branch — pick the base to fork from, and optionally a name. Leaving the name empty is the normal case: the route derives ${LANE_BRANCH_PREFIX}${slug} exactly as the CLI does, and the field's placeholder previews that name as you type the title. The modal no longer demands one.
• Existing branch — check a branch that already exists out into the new worktree, with no base and no new branch. Git allows one worktree per branch, so any branch another worktree already holds is listed but disabled, named with the directory holding it; picking it would have failed provisioning with EBRANCHBUSY after the lane row already existed.
• Current branch — no branch at all: the lane simply is the repo, working on whatever is checked out (main). Small and personal projects usually want this and nothing more, so the choice sits beside the other two rather than being reachable only from the top-level mode toggle — it switches the modal to Repo mode, which is exactly that behaviour. A worktree lane could not offer it in any case: git will not check main out in a second worktree while the repo itself holds it.

The modal also accepts a prefill (repo + branch). That is what the lane git bar's New lane here opens — a sibling worktree of the same repo on the branch selected there, created through this same flow rather than a second provisioning path.

Above the branch fields, once the repo path resolves, the modal lists that repo's existing worktrees (branch + directory, first eight). GET /api/lanes/branches?repo= carries them alongside the branch list — one subprocess more on a form still being typed into, versus a second round trip for facts that expire together.

The repo field's autocomplete also offers a Source repos group: the source_repo of every lane already provisioned, newest first, above the session-history recents (GET /api/run/cwds, kind: "repo"). A worktree lane's recent cwd is the worktree, never the repo it was cut from, so the one path this field wants had to be retyped every time.

The modal has no pipeline picker: every lane it creates is born on default (the server's own default), and the template is changed afterwards from the lane's own detail header in Workspace, or at creation from the terminal with agenthub lanes add --pipeline <id>. Model endpoint is the one per-lane extra the form still asks for, and it sits in the form itself rather than behind a disclosure — a disclosure around a single field only hid it.

The Model endpoint radio chooses between Native (the vendor's own API) and AI Router — a profile saved in Settings › AI Router (9Router, OpenRouter, a self-hosted gateway). Choosing one writes it into the new lane's own config as the lane is created: a claude lane gets the env block of its .claude/settings.local.json, a codex lane gets a $CODEX_HOME/<name>.config.toml layer plus a -p <name> on every spawn. With no profile saved the radio stays on Native and says so. Unlike the lane's tool, this one is not immutable: an existing lane's detail header in Workspace carries a Model select (beside the pipeline picker) showing its current profile, and picking another calls POST /api/lanes/:id/router/apply, rewriting the lane's config and its router_profile column together. (The select is hidden when native is the only profile — there would be nothing to choose.) A failed apply puts the select back rather than leaving the row claiming a router the lane did not get, and marks itself ⚠ with the error in its tooltip. A session already running in the pane is only HALF switched: Claude Code re-applies an env block to a live session when the file changes, but the session's model was resolved at startup, so the previous router's model name keeps being sent to the new endpoint and the next prompt fails with a model-not-found error (switching back to Native included). The route therefore answers restart_required: true plus the run_id whenever a pane is live, and the select renders a Restart button that kills that pane and opens a fresh one — started from the lane id alone, since replaying the old run's --model would re-create the same mismatch. Editing or deleting the profile itself in Settings also reaches every lane using it: an edit re-applies it (so a rotated key actually lands), a delete resets those lanes to Native. See docs/API.md § AI Router profiles.

Both modes' path field has a Browse button next to it, opening a small folder browser (GET /api/lanes/browse?path=<abs>) instead of a native OS picker — a browser cannot hand a web page an absolute filesystem path from a native dialog, so this dashboard (local-first, server and browser on the same machine) lists directories server-side instead: click a subfolder to descend, ".." to go up, "Select this folder" to fill the path field. Git repos are marked in the listing.

Lane tool: Claude or Codex

A lane is driven by a tool: Claude (default) or Codex, chosen in the "+ Add lane" modal and immutable once the lane exists. A lane's tool determines which CLI is spawned when a run starts.

• claude (default) — claude binary is invoked; the session's hooks, messages, and tool calls flow through the dashboard. Claude lanes render Sessions, Analytics, cost, and stage-detection badges; liveness is tracked by the Claude Code session.
• codex (experimental) — codex binary is invoked instead. The Run Setup panel shows fields for model, sandbox, and approval mode instead of the Claude session picker, and offers "Resume last Codex run" instead of picking a session. Resume uses codex resume --last. Codex lanes carry no pipeline: no stage chip, no time-on-stage, no pipeline or feature picker and no PipelineMap, and nothing infers or advances their stage. They also get no Sessions/Analytics/cost. (The console pre-fills nothing into the prompt box, for either tool.)

How Codex arguments map

The Run Setup panel's fields map directly onto codex command-line arguments:

• Model → codex -m <model> (e.g. codex -m claude-opus-5)
• Sandbox (optional) → -s <mode> where mode is one of read-only, workspace-write, or danger-full-access
• Approval (optional) → -a <mode> where mode is one of on-request or never
• Reasoning effort → -c model_reasoning_effort=<level> (e.g. medium)

A codex lane's run console shows the full command line before execution.

Limitations of Codex lanes

Codex does not emit Claude Code hooks (sessions, agent events, tool-execution tracking), so the following surfaces remain empty for a Codex lane:

• Sessions and Analytics tabs — no session history or aggregated statistics
• Cost surface — no per-run or per-model pricing data

These are not bugs; they reflect Codex's architecture. Liveness is tracked by the lane's tmux pane (if the stack is up) and dashboard_runs table (recording every invocation). Cost tracking for Codex runs would require parsing Codex's own logs, a separate design not yet implemented.

Codex lanes carry no pipeline. Nothing infers their stage, nothing types a stage reminder into their pane, and agenthub lanes agents install installs nothing on them (installed: []). The one thing AgentHub reads from Codex is its running/idle status — see "Stage detection" for the journal poll that mirrors it. Every server start also wipes what older builds left behind on a codex lane — its stage columns, stage log (lane_stage_events) and feature records (lane_features) — and takes the old <!-- agenthub:stage:start --> block back out of its AGENTS.md (deleting the file if nothing else is in it).

Destructive lane actions

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

agenthub lanes reset <id> [--force] [--keep-db] --yes
agenthub lanes remove <id> [--force] --yes
agenthub lanes purge <id> --yes

Each command first fetches and prints its preflight counts. reset and remove show head, dirty, untracked, and unpushed (plus database, the name a data-isolated lane's reset will drop — remove drops no database at all; see "Data isolation" below); 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 — it applies to reset alone, since remove deletes nothing that could hold them. --keep-db (reset only) skips the whole drop-recreate-migrate-reseed sequence, leaving the lane's database exactly as it was. An adopted lane points at a directory you own, so the CLI refuses to reset it. remove is allowed for every lane kind, adopted or managed, because it drops only the dashboard's record and leaves the working tree, its branch, and its database (if any) untouched — deleting those is yours to do by hand.

Lifecycle

The two lane kinds

• managed — a git worktree the dashboard itself created (agenthub lanes add --repo), rooted under LANES_ROOT. The dashboard may reset that worktree to its base branch. It does NOT delete it: removing the lane forgets the dashboard's record and leaves the directory and its branch on disk.
• adopted — an existing directory you already had (agenthub 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 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.

removeWorktree (with its prune path for a hand-deleted directory) still lives in server/lib/worktree.js and still runs those checks, but no route calls it any more: the lane remove action no longer destroys anything. It is kept as a guarded primitive, not a reachable lane verb.

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 — deletes the dashboard's record of the lane and nothing else, for every lane kind. The working tree stays on disk, its branch stays in the source repo, git's own worktree bookkeeping is untouched, and the lane's database (if any) is left in place; deleting any of them is the user's own call (git worktree remove, git branch -d, dropping the database). Stopping the lane's run and stack still happens first — those are processes, not data — and the runtime bookkeeping under LANES_ROOT/.state/lane<slot>/ (pid files, hook logs) is cleared, because it is AgentHub's own and would otherwise be inherited by the next lane to claim that slot. Consequently there is no unpushed-commits force-gate on remove: nothing it does can discard a commit.
• 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, database, 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, including unpushed-commits: removal only deletes the lane's row, so an adopted lane, a hand-deleted directory and an unreadable one are all removable and none of them risks anything on disk. For remove the preflight counts are context, not a destruction manifest. 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.

database is the database name a reset (unless --keep-db) will drop — remove never drops one — null when the lane has no slot yet or its profile declares no DB_PREFIX. It is derived, not stored, the same way slot/ports are.

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/agenthub-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

agenthub 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.

A repository can close the dependency half of that gap itself by declaring a bootstrap hook in its profile (below) and running agenthub lanes hook bootstrap. Seeding a lane's .env and its database is handled automatically once the profile opts in — see "Data isolation" below.

Lane runtime: running a lane's own stack

A lane isolates code. Without more, two lanes running their project at the same time collide on everything else — the same ports, the same directories. The runtime layer gives each lane its own slot, and derives its ports and per-lane directories from it.

This is resource namespacing on the host, not a container: lanes run as the same user, share the network, and can read any file you can. If you need stronger isolation than that, this is not it.

Declaring a profile

Everything stack-specific lives in the repository, at <repo>/.agenthub/profile/. AgentHub is multi-repo, so there is no global profile setting — a profile travels with the repo it describes, and therefore already exists in every worktree cut from it.

myapp/
  .agenthub/profile/
    profile.env
    hooks/
      bootstrap.sh boot.sh health.sh
      migrate.sh seed.sh ci-gate.sh e2e.sh regen.sh
      db-create.sh db-drop.sh

profile.env is a KEY=VALUE declaration file. It is parsed, never sourced — $(…), backticks and ${VAR} are kept literally, because sourcing arbitrary shell from a repository into the dashboard process would be a code-execution path. Hooks are executed on purpose; config is only read.

# .agenthub/profile/profile.env
PORTS="api fe worker"       # names; each gets a <NAME>_PORT in the hook environment
PORT_BASE_api=8000          # lane in slot 3 prefers :8003
PORT_BASE_fe=3000
PORT_BASE_worker=9000
LANE_DIRS="uploads .cache"  # directories created per lane, inside its working copy
BACKEND_DIR=backend
FRONTEND_DIR=frontend

Every key has a default, so a missing one never breaks a lane: PORTS="api fe", PORT_BASE_api=8000, PORT_BASE_fe=3000, LANE_DIRS="", BACKEND_DIR=backend, FRONTEND_DIR=frontend, API_PATH=/api. A port name with no declared base falls back to 8000.

AgentHub resolves the profile from the lane's own working copy first, then its source repository. A branch that changes a boot command must boot with the command it changed; the source-repo fallback exists for a profile kept gitignored, which never reaches a worktree through git.

Scaffolding a profile automatically

agenthub lanes profile init <repo> [--force]   # detect + write .agenthub/profile/
agenthub lanes profile check [<path>]          # validate one (path defaults to cwd)

profile init currently detects Node.js only, in exactly two layouts: a root package.json (single-service), or backend/package.json and frontend/package.json both present (monorepo, checked first). Anything else — Python/Go/Ruby, a pnpm/yarn/turborepo workspace, non-standard directory names — is refused with an actionable message rather than guessed at; write .agenthub/profile/ by hand for those, following the reference above.

Detection reads package.json (which of start/dev/preview exists) and docker-compose.yml (a service matching /postgres/i or /redis/i), never executes anything, and never guesses a migration tool: a detected database gets migrate.sh/seed.sh scaffolded as an explicit, always-exit 0 TODO stub, not a guessed Prisma/Knex/TypeORM command. profile check is the hard gate — it fails (non-zero exit, every problem listed) on any leftover TODO:, any missing or non-executable hook, or a declared port already in use; it only warns when ~/.agenthub/secrets.env doesn't exist yet for a database-declaring profile.

profile check takes a path, not a lane id or --lane/--cwd flag like every other lanes subcommand — it is meant to run against a bare repository right after init, before any lane or worktree exists for it.

Slots and ports

A slot is the small integer every runtime fact derives from. Slots are allocated lazily — a lane that is only ever watched never takes one — from 1..LANE_MAX_SLOTS (default 9), lowest free first, and are freed when the lane is removed. A reset keeps the slot: moving a lane's ports out from under a session mid-feature would be a silent, confusing failure rather than a fresh start.

Ports prefer PORT_BASE_<name> + slot. When that number is already in use, the allocator steps aside by +100, +200, … up to ten times, which keeps the last digit equal to the slot so a stepped-aside port still reads as "lane 3". The number a lane actually got is recorded in lanes.ports and reused on the next boot, so a lane's URL does not move once it has one. A number is rejected when something is listening on it, when another lane has recorded it (a lane whose stack is down still owns its number), or when an earlier port name in the same boot took it.

If every candidate is busy the boot fails with EPORTBUSY, naming the process holding the preferred port.

The hook contract

Before running a hook, AgentHub exports:

Variable	Value
LANE	the slot number (not the lane id)
LANE_ID	the lane id
LANE_DIR	the lane's working copy
SOURCE_REPO	the repository it was cut from
PROFILE_DIR	the resolved .agenthub/profile
RUN_DIR / LOG_DIR	pid files and logs, under $LANES_ROOT/.state/lane<slot>/
<NAME>_PORT	one per declared port, upper-cased (PORTS="api fe" → API_PORT, FE_PORT)
everything in profile.env	verbatim

Two shell helpers are injected: die <msg>, and harness_spawn <name> <workdir> <cmd…> which backgrounds a long-lived service with fully detached stdio and records its pid at $RUN_DIR/<name>.pid. Use harness_spawn in boot — a child that inherits the caller's stdout holds that pipe open, and the hook never returns.

Inherited GIT_* variables are scrubbed exactly as server/lib/worktree.js scrubs them, so a hook that shells out to git cannot inherit a git context pointing at the dashboard's own repository.

# .agenthub/profile/hooks/boot.sh
#!/usr/bin/env bash
set -euo pipefail
harness_spawn api "$LANE_DIR/$BACKEND_DIR" npm run start -- --port "$API_PORT"
harness_spawn fe  "$LANE_DIR/$FRONTEND_DIR" npm run preview -- --port "$FE_PORT"

# .agenthub/profile/hooks/health.sh
#!/usr/bin/env bash
set -euo pipefail
curl -sf --retry 30 --retry-delay 1 --retry-all-errors "http://127.0.0.1:$FE_PORT/" >/dev/null

Runnable hook names are a fixed allowlist: bootstrap, boot, health, migrate, seed, ci-gate, e2e, regen, db-create, db-drop. A name from a request is never turned into a path.

Up, down, and surviving a restart

agenthub lanes up              # boot the lane owning this directory
agenthub lanes up 3 --no-build # boot lane 3, reusing an existing build
agenthub lanes runtime         # slot, ports, service liveness, last boot error
agenthub lanes logs api        # tail one service or hook log
agenthub lanes down            # stop the stack
agenthub lanes hook ci-gate    # run any allowlisted hook

up runs boot then health. It deliberately does not run bootstrap — installing dependencies on every boot would make a routine restart minutes long. A failing health check leaves the processes running: their logs are what tell you which service never came up, and killing them to report a tidy failure destroys the evidence.

Services are fully detached, so a lane's stack outlives the dashboard. Restarting or updating AgentHub does not touch a running lane. Nothing has to re-adopt them either: whether a stack is up is recomputed from pid files and port probes on every read, never cached, because a process can die to OOM or a stray kill without telling anyone.

down kills each recorded pid tree bottom-up (a parent killed first reparents its children to init, where nothing knows to look for them), then — only when there was a pid file — sweeps any listener still on the lane's ports. That condition matters: a lane whose stack is already down still owns its port numbers, and an unconditional sweep would kill a server you started there yourself.

While a hook runs, each output line is broadcast as a lane_hook_output WebSocket message ({ laneId, hook, stream, line }) and also appended to $LOG_DIR/<hook>.log. A boot ends with lane_runtime (fresh facts, or an error); a hook run started through POST /api/lanes/:id/hook/:name ends with lane_hook_result carrying its exit code. That is what lets a lane card show live progress through a multi-minute build instead of a disabled button that reads as a hang.

What the runtime does and does not write

The runtime writes slot and ports on the lane row, and nothing else. It never writes stage, status or notes.

In AgentHub those describe the agent's work, not the stack's state: status=running means a session is working, and a booted server is not a session. Conflating them would corrupt lane liveness. This is the same boundary as "the console never writes a lane's stage". Boot failures live in $LANES_ROOT/.state/lane<slot>/last-error.json and surface through GET /api/lanes/:id/runtime.

Adopted lanes may be brought up and down — up only runs what you could run yourself — but every path that writes into their working copy is refused.

Runtime environment variables

• LANE_MAX_SLOTS (default 9) — how many lanes may hold a runtime at once. Nine keeps base + slot readable as a single digit; raising it costs that readability.
• LANE_BOOT_TIMEOUT_MS (default 900000) — hard limit on the boot hook.
• LANE_HEALTH_TIMEOUT_MS (default 180000) — hard limit on the health hook; a health check that never returns is a failed boot, not an eternal wait.
• LANE_PORT_PROBE_MS (default 300) — connect timeout when probing whether a port is in use.

Data isolation: database, Redis and .env (A2)

Two lanes running their stack at once need more than separate ports — they need separate data, or one lane's migration corrupts the other's session. This is the other half of runtime isolation, and every piece of it is off by default: a profile that never declares DB_PREFIX gets no database, REDIS=1 gets no Redis index, and no ENV_FILES gets no .env writes at all.

Profile declarations (.agenthub/profile/profile.env, all optional):

DB_PREFIX="myapp_l"          # lane in slot 3 -> myapp_l3 ; empty = no per-lane DB
DB_KIND="postgres"           # informational
DB_URL_SCHEME="postgresql"   # DATABASE_URL scheme
REDIS=1                      # 1 = allocate a logical Redis index = slot
                              # (stock Redis ships 16 logical DBs, 0-15 — keep
                              #  LANE_MAX_SLOTS <= 15 if REDIS=1 is declared)

ENV_FILES="backend/.env"                          # file(s) to seed, relative to the lane
ENV_SOURCE="backend/.env"                         # source path in the source repo (defaults to ENV_FILES)
ENV_REWRITE="DATABASE_URL REDIS_URL UPLOAD_DIR"   # keys AgentHub overwrites per lane
ENV_PRESERVE="JWT_SECRET"                         # keys kept from the lane's OWN file on a --force refresh
UPLOAD_SUBDIR="backend/data/uploads"              # exported as UPLOAD_DIR

A ready-to-copy template (including db-create.sh/db-drop.sh for a Postgres-in-docker-compose stack) lives at server/data/profile-templates/postgres-compose/.

Machine-level credentials live at ~/.agenthub/secrets.env (mode 0600), never in the repo:

PG_HOST=127.0.0.1
PG_PORT=5432
PG_USER=postgres
PG_PASS=postgres
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Parsed with the same literal KEY=VALUE reader as profile.env — never sourced. A missing file falls back to those same defaults (with a one-time warning); a file readable by group or world is refused outright rather than trusted. No route ever returns a value from this file — GET /api/lanes/:id/runtime reports a database's name and a Redis index, never a connection string.

Who creates the database? A db-create.sh / db-drop.sh hook (already in the allowlist) — AgentHub stays stack-agnostic, since createdb vs mysqladmin create vs touch foo.db genuinely differ. Who rewrites .env? AgentHub itself: mechanical and identical across stacks, so pushing it into every repo would duplicate the same ~30 lines.

Hook environment additions, present only when their owning declaration is (a db-create.sh that forgot to check DB_PREFIX fails loudly on an unset variable instead of touching a database named "undefined"):

Variable	Present when	Value
DB_NAME	DB_PREFIX set	<prefix><slot>
DATABASE_URL / TEST_DATABASE_URL	DB_PREFIX set	full connection string to DB_NAME / DB_NAME_test
PG_HOST / PG_PORT / PG_USER	DB_PREFIX set	from secrets.env (PG_PASS is deliberately withheld — nothing in the ported hooks needs it)
REDIS_URL	REDIS=1	redis://<host>:<port>/<slot>
REDIS_HOST / REDIS_PORT	REDIS=1	from secrets.env
UPLOAD_DIR	UPLOAD_SUBDIR set	<lane>/<UPLOAD_SUBDIR>

When each step runs:

• Provisioning a new managed worktree (agenthub lanes add --repo) — after the worktree is created: seed .env, run bootstrap, create the database, migrate, seed. Runs once.
• up — repair .env (a hand-edited or never-seeded file gets fixed), ensure the database exists (cheap when it already does), migrate on every boot (a lane's schema drifts while it sits idle), and seed only on the boot that actually created the database.
• reset — refresh .env with --force (preserving ENV_PRESERVE keys from the lane's own file — swapping in the source's JWT_SECRET would 401 a running lane's tokens until reboot), re-run bootstrap (a reset can land on a branch with new dependencies), clear the declared LANE_DIRS, then drop, recreate, migrate and reseed the database — unless --keep-db, which skips that whole block.
• remove — drops nothing. removeLaneData still exists in server/lib/lane-runtime.js (and still refuses an adopted lane), but the remove action no longer calls it: a lane's database is the user's data and outlives the dashboard's record of it. Drop it yourself when you actually want it gone.

A missing source .env falls back to .env.example with a loud warning, never a silent success. And any hook output that echoes a value from secrets.env (the password, specifically) is redacted before it reaches $LOG_DIR/<hook>.log or the lane_hook_output WebSocket message — that stream reaches a browser tab, and a hook debugging its own environment must not publish a database password to everyone watching.

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:

• No page header. The page title and the four counters (lanes, running, needs you, dead) are gone: the lane strip below already shows every lane with its own liveness dot and its ⚠ marker, so the counters restated it a row higher and cost height on a screen whose point is the terminal. GET /api/lanes still returns counts for other callers.
• Lane strip — the horizontally scrolling row of lane tiles. Its FIRST tile is Add lane (dashed border, no liveness dot), not a header button: creating a lane is the same kind of act as picking one, so it reads as the empty slot at the head of the row. A tile shows the lane's id as a bare #23 — not "Lane 23", which cost a third of the row's width and said nothing, though the number itself stays because that is how the CLI addresses a lane.
• No lanes yet — the strip is replaced by a single banner (lane-empty): icon, one line of what a lane is, the CLI equivalent (agenthub lanes add --cwd $(pwd)) and an Add lane affordance. The whole banner IS the button — clicking anywhere on it opens the Add-lane modal, so there is no separate button to hit. The strip itself — the dashed add tile plus the lane tiles — only renders once at least one lane exists, because an add tile beside a stray sentence read as a half-drawn row. The banner stays compact on purpose: the run setup form below it is what needs the height.
• Reordering the strip — drag a tile onto another to move it there, or press Alt+←/→ with a tile focused (the keyboard path; HTML5 drag-and-drop has no touch support and does not auto-scroll an overflowing strip). The order is a per-viewer preference, not a lane fact: it persists to localStorage (agenthub.workspace.laneOrder) exactly like the split-view layout beside it, and writes nothing server-side — GET /api/lanes and agenthub lanes keep answering in id order, and the order does not follow you to another browser. A lane the stored order has never seen (created since, or created in another tab) lands at the END rather than wherever a stale index would put it; a stored id whose lane is gone is skipped.
• Renaming a lane — the detail header's name is a button: click it (a pencil appears on hover) to edit in place. Enter saves via PATCH /api/lanes/:id with {title}, Escape and clicking away both cancel, and saving an empty name clears the title, which puts the lane's cwd back in its place. Renaming is display-only — a managed lane's branch name was slugified from its title once, at creation.
• Lane-detail header row — one row, and every per-lane control lives on it: liveness + status, the lane's name (no "Lane 23 ·" prefix — the id is on the strip tile), time-on-stage, the pipeline picker, the Model (AI Router) select, the feature picker (there are no stage chips here — the declared stage and the auto: <stage> detection both render in the PipelineMap directly below, so the chips were a second, smaller copy of the same two facts), and on the right the Tools menu (agents install / mcp sync / sync-base check / create-update readme, hidden when the lane declares no runtime profile), the info toggle, the split-view toggle and Remove. Tools sits here rather than in Settings because every one of its actions runs against one lane's cwd — in Settings it would need a lane picker just to say which. Create/update readme file (Claude lanes only — Codex has no slash commands) starts the lane's terminal run with /sg-all:sg-md-writing as its first message, so the lane opens already writing/refreshing its CLAUDE.md/AGENTS.md set; it needs the sg-all plugin installed in Claude Code, and without it the session just reports an unknown command. It used to be a checkbox in the Add-lane modal: creating a lane and writing its docs are separate decisions, and the second is worth re-running long after the first.
• 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.
• Terminal — a real interactive terminal (xterm.js) displaying the tmux session's PTY output, with full support for interactive commands, editors, and pagers. A live run keeps its rendered history and scroll position when scrolling. It grabs the keyboard the moment it appears, so typing goes into the pane without clicking it first, and when the pane's process ends — a double Ctrl+C out of claude, exit, a crash — the console returns to the run setup form on its own, with no "New run" click.
• Clipboard in a pane — the lane's tmux session is started with the graphical session's own DISPLAY/WAYLAND_DISPLAY/XAUTHORITY/XDG_RUNTIME_DIR (read from systemctl --user show-environment, this process's own values winning; server/lib/desktop-env.js). The dashboard normally runs as a systemd user service, which has none of them, so a pane it started had no clipboard at all and claude answered "no image found in clipboard" on every image paste while the same CLI pasted fine in a terminal. Only those four names are forwarded, and only into panes this dashboard spawns — an already-running pane keeps the environment it was started with, so it needs a restart to gain one.
• Split view — a layout toggle (one pane / two side by side / a 2×2 grid, drawn as icons rather than the words, with the count kept as each button's aria-label and tooltip) renders that many terminal panes side by side (grid-cols-2 for 2, a 2×2 grid for 4). EVERY pane is bound to the lane strip's selection — there is no per-pane lane picker — and each pane owns its own tmux session on that lane: pane 0 is the lane's agenthub-lane-<id> (its run_id), panes 1–3 are agenthub-lane-<id>-<slot> (POST /api/lanes/:id/start with slot). A pane's Active runs leaves out the runs the other panes are showing, so one terminal is never attached twice side by side. Only the layout persists to localStorage (agenthub.workspace.splitView); a stored per-pane lane id from an older build is ignored.
• 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 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, and the action row. The needs-you message (needs_action) is on the lane strip tile only — the detail card no longer repeats it as a banner.

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

A console pane follows the lane it shows. Selecting another lane on the lane strip swaps every pane's cwd, run history and terminal over to the new lane. If the new lane already has a live session for that pane's slot in GET /api/run, the pane re-attaches to it immediately, so each pane sticks to its own agenthub-lane-<id>[-<slot>] tmux session; if it has none, the pane shows that lane's setup form. Nothing of the previous lane (a half-typed prompt, its terminal) carries over.

The working directory field tracks the selected lane's own cwd specifically, and re-syncs as soon as that path is known rather than only when the selection changes — a pane can render before GET /api/lanes has answered (the lane list loads after the page mounts), and its lane id never changes afterwards. RunSetup submits that string verbatim to POST /api/lanes/:id/start, so a cwd left over from the previous lane or from the home default would start the run in the wrong folder. The home suggestion is used only while no lane is selected at all.

Picking a session to resume starts it right away. In the setup form's Fresh/Resume switch, choosing a session from the resume picker fires the start immediately — POST /api/lanes/:id/start with that resumeSessionId and the session's own cwd — and the pane switches straight to the terminal. A resume carries its own transcript, so there is nothing to type first: the prompt box stays optional for resumes (the Run button no longer requires it) and required for fresh runs. A resume also sends no prompt at all — whatever is left in that box is dropped rather than fired as an extra turn into the session being continued. Type into the tmux terminal once it's attached.

Active runs list

The Active runs button in the console header opens the merged run list. It shows three sources in one place, newest first:

1. live in-memory tmux runs from GET /api/run,
2. persisted dashboard runs from GET /api/run/history,
3. Claude Code sessions running outside the dashboard — GET /api/sessions?status=active, i.e. a claude the user started by hand in a terminal tab. These carry an amber external badge, and the button's live count includes the ones its lane owns (next paragraph), so two hand-started agents in the lane's folder read as "2 active runs".

An external session is deduped against a dashboard run with the same session_id, and sessions from a remote data source (source !== "local") or without a cwd are skipped — neither can be resumed on this machine.

External rows have no Attach action: the dashboard owns no tmux session for them, so there is no PTY to bridge. Their action is Resume, which does what resuming from history does — POST /api/lanes/ensure for the session's cwd, then POST /api/lanes/:id/start with resumeSessionId — spawning a new tmux-backed claude --resume <session> in that folder. The original terminal keeps running; resuming gives you a second Claude Code process on the same transcript, not a view of the first one.

Live, dashboard-spawned rows (not external — there is no tmux session to kill for those) also carry a Kill button, DELETE /api/run/:id behind a two-click confirm. This is how you free a lane stuck on a previous live session when you actually want it gone, rather than attached to.

Start and Resume are create-or-reuse, and never silently swallow the request. When the lane's agenthub-lane-<id> tmux session does not exist, it is created with the full argv. When it exists but its pane is sitting at a shell prompt (a agenthub lanes shell you opened, or a claude that has since exited), the argv is typed into that pane — so --resume really runs, and an initial prompt really lands, in the session you are already looking at. Only when the pane is running something (a live claude, an editor, a build) is the request adopted as-is: attaching shows you what is running rather than typing over it. Before this, an existing session was always adopted silently, so the first Resume after a agenthub lanes shell answered 200 while doing nothing at all.

A lane whose run_id still points at a live run refuses a second Start/Resume outright — POST /api/lanes/:id/start answers 409 ERUNLIVE rather than typing a new prompt or --resume over a session that is still in flight. The console does not surface that raw error: LaneConsolePane catches it, re-reads the lane, and attaches to the run it is already holding instead — with a notice explaining that the previous session is still live, so nothing new started. Killing that session (Active runs list → Kill, two clicks, the same confirm convention as discarding a file in the Changes panel) is what actually frees the lane for a fresh Start or a different Resume; the kill goes straight through DELETE /api/run/:id, and the lane's own run_id/status self-heal to idle the next time anything reads the lane (healRunId in routes/lanes.js), so no separate lane-side call is needed.

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 for the requested tool, returns that lane with created: false and HTTP 200. tool (claude, codex or antigravity, default claude) is part of the identity: adopting the same cwd with a different tool creates a second, sibling lane rather than adopting the existing one — one cwd can back at most one claude lane and one codex lane at a time. This applies to Repo/Adopt mode only; Worktree mode always gets its own directory.
• If the cwd is a subdirectory of an existing lane with that same tool, returns the parent lane that owns it. Pass "exact": true to skip that: only a lane on this very directory is returned, and a nested one is created as its own lane — the Add-lane modal does this, and shows which lane already owns the folder when the answer is created: false.
• If no lane owns the (cwd, tool) pair, 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 (cwd, tool) pair always yield one lane: the database's composite UNIQUE index on lanes(cwd, tool) decides the winner, and the loser re-reads and returns the winning lane.

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

The top of a lane's Changes panel 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,
  "files": [
    { "path": "server/lib/alerts.js", "status": " M", "added": 12, "deleted": 3 },
    { "path": "client/src/lib/api.ts", "status": "M ", "added": 1, "deleted": 0 },
    { "path": "scratch.txt", "status": "??", "added": null, "deleted": null }
  ]
}

• 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 panel simply renders without a git line.
• A detached checkout reports the literal HEAD that git returns, rather than a prettier invention.
• files names the files the two counts came from, capped at 20 — a lane mid-npm install would otherwise ship thousands of paths through a polled endpoint. The counts are never capped, so the panel that shows this list says … and N more files when it is showing less than all of it. Each entry carries its two-character git status --porcelain code (status, for a rename the path is the NEW one) and its line delta.
• added/deleted come from one git diff --numstat HEAD, which covers staged and unstaged work together. They are null when git has no delta to report: an untracked file (git has never seen it — its content is deliberately not read off disk, since a lane mid-build can have a 100 MB artifact), a binary file, a rename (numstat keys those differently), or a repo with no commit to diff against yet.
• Hovering (or focusing, or tapping) the N modified · N untracked text at the top of the Changes panel opens this list as a panel: one row per file, its status letter colour-coded, the directory truncated before the filename ever is, and each row's +N −M aligned on the right under a total.
• A repo with no commit yet is not unavailable: it reports unborn: true, head: null, an empty subject and the branch its first commit will land on.
• An unknown lane id is a 404.

This is not folded into GET /api/lanes on purpose: it shells out to git five 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 Changes panel fetches it instead, on mount, every 30 seconds and after every git write it or its action row makes, and a failed fetch is silent.

The same response also carries the branch's standing against its remote: hasRemote, upstream, ahead, behind. A branch that has never been pushed reports upstream: null and null counts — not zeros, which would claim "in sync" about a comparison that was never possible. The panel renders them as ↑2 ↓1 beside the git actions below.

Acting on a lane's working copy: the git action row

On the same row as the git line — as icons, each naming itself in its tooltip — the Changes panel carries the per-repo git writes the dashboard offers (POST /api/lanes/:id/git/:action, see docs/API.md):

Button	Runs	Refuses when
Fetch	git fetch --all --prune	the repo has no remote
Pull	git pull --ff-only	the branch has diverged (it reports, never merges)
Push (labelled Publish branch while the branch has no upstream)	git push -u origin HEAD	the remote rejects it
Publish… (only when the repo has NO remote)	git remote add origin -- <url>, then git push -u origin HEAD; origin is removed again if the push fails	the repo has no commit yet, already has a remote, or the URL is not https:// (no user:token@), ssh:// or user@host:path
Branch	git switch …	the tree is dirty, or another worktree holds that branch
Create	git branch <name> — never switches	the branch already exists
Delete	git branch -d <name>	it is protected (main, master, development, develop), current, held by another worktree, or has unmerged commits
New lane here	opens Add lane prefilled with this repo and the selected branch	—
Merge into current	git merge --no-edit <branch> (after a confirm)	the tree is dirty, the lane is a subdirectory of its repo, or a merge is already in progress
Merge <upstream>	the same, offered when the branch has diverged (ahead AND behind)	as above

These sit in the panel rather than in the lane card's ⋯ menu deliberately: that menu holds the rare and dangerous (reset worktree), and these are the ordinary moves a lane needs several times an hour. There is no rebase, reset or stash button, because a dashboard click is the wrong place to start an operation whose recovery needs a terminal. Merge is the one exception (issue #45), because its recovery is a button too: a merge that stops on conflicts puts a banner at the top of the Changes panel — Complete merge (enabled once nothing is conflicted) and Abort merge (two clicks; back to where the branch was) — and lists the conflicted files in their own Merge conflicts group with Keep mine / Take theirs for the whole file and Mark resolved. Opening a conflicted file shows the conflict view instead of its diff: each conflict block drawn as its two sides — Mine (HEAD) tinted green, Theirs () tinted blue, labelled from git's own markers — with Keep mine, Take theirs or Keep both per block (undoable, ^/v to jump between blocks). Save and mark resolved is enabled once every block is chosen; it saves over exactly the version opened (a file changed meanwhile is refused, 409 ESTALE) and then marks the file resolved. Edit by hand opens the plain editor, for a block neither side gets right; marking resolved is refused while any <<<<<<</>>>>>>> marker is left. In the Files tree a conflicted file is listed once (git indexes it once per side) and marked with a red !. Pull and branch switch are disabled until the merge is finished or aborted. pull --ff-only and the dirty-tree guard on switch are what keep either from inventing a merge commit or a conflict underneath a running agent. Create deliberately does not switch: the usual reason to make a branch from a lane is to spawn a sibling worktree lane on it, and moving this pane's HEAD under a working agent is not. New lane here goes through the normal Add-lane flow with the fields prefilled — one provisioning path for every lane, not a second one hidden in the git bar. There is no Commit here: committing is the overview's staged-only box below, the one commit path, and it only ever takes what was staged.

Publish… is the one button whose destination the user types, so the server keeps it narrow: it only gives a remote to a repo that has none (it never re-points one), always names it origin, and accepts only https:// without credentials in the URL, ssh:// and scp-like git@host:owner/repo.git — never a local path, file://, ext:: or http://. Credentials come from the machine's own credential helper, ssh agent or AgentHub's own git login store (the login form below), exactly as for Push.

A repo with no commits yet (a fresh git init) still gets the header: its branch, "no commits yet", and a hint to commit first — the network and branch buttons are hidden because there is nothing to push, fetch into or branch from. The commit box below makes the first commit, and Publish… appears once it exists. Add lane in Worktree mode refuses such a repo (400 EEMPTYREPO, nothing to fork a worktree from) and offers Use as a Repo lane instead.

A failed action prints git's own stderr verbatim — ! [rejected] … (non-fast-forward) says more than any sentence the dashboard could write.

The exception is a remote that wants a login (issue #45). The dashboard runs git without a terminal, so where a shell would prompt, the bar opens a form instead — "Git needs a login for <host>": username, password or access token (on Gitea: Settings → Applications → Generate token), and Remember for everyone using this AgentHub (on by default) — and resends the same action with it. A saved login lives in AgentHub's own store, one per host, shared by every user of the install, and is managed from Settings → Git credentials; it is saved only after git accepted it. While AgentHub holds a login for a repo's host, that login is the only one git is given for the command — the machine's own credential helpers are left out, so a stale token there cannot win. Over plain http:// on a LAN address the form warns that the token crosses the network unencrypted. See docs/API.md § Git credentials.

The Changes panel

To the right of the lane detail sits a collapsible Changes card (its state persists per viewer in localStorage). Its header holds one control, which steps Narrow (30%) → Medium (50/50) → Full screen (the console beside it is hidden, never unmounted; the page is height-locked so the panel fills the viewport even with no live run; the whole Files view (finder, expand-all, tree) becomes a left sidebar and the Files tab is dropped, and every working-copy file opened there, from the sidebar, Overview or Review, IS the editor (Whole file toggles back to its diff; a commit still opens as a diff) — no Edit click, Save/Cancel stay and wake up once the text differs, Cancel restores the saved text) → closed (agenthub.workspace.changesSize alongside agenthub.workspace.changesOpen); the collapsed rail reopens it narrow. A stored size from an older build that no longer exists (wide) falls back to narrow. Reading a diff and watching a console want opposite amounts of room and which one is "work" changes several times an hour, so the width is a step, not a setting — and one button beats a width button wedged beside a collapse button in the panel's tightest corner. It is icon-only, and the icon it draws is the width the next click LANDS on (even split → wider → closed), with the wording left to its tooltip. It reads the lane's git surface in five modes (Files sits first: it is the only one that answers "show me the code" rather than "show me the change"):

• Files — quick-open by path (/git/ls) or the repo's tracked file tree (/git/tree), which expands folders in place rather than navigating into them — a folder's children render nested under it, siblings stay visible, and a toolbar button expands or collapses every folder at once (each unfetched level lazily calls /git/tree the first time it's opened). Untracked files git does not ignore are listed too, and the tree is decorated like VS Code's: a modified file is amber with M, an untracked one green with U (A added, D deleted and struck through, R renamed), and a folder holding any of them gets an amber dot. The colours come with the tree read, so Refresh re-reads them. Opening a file entry shows the whole file (/git/file) for reading, at every panel width. Clicking its text (or Enter on it; any range but a commit) turns that view into a text editor with the caret on the clicked line and the scroll position kept — a click that only ends a drag-selection does not, so copying never drops you into the editor. Cancel returns to reading. From a diff, which has no whole text to click, an Edit button does the same once the file has loaded. Save (or Ctrl/Cmd+S) is PUT /api/lanes/:id/git/file, which writes only over the exact version that was opened — a file the agent changed meanwhile answers 409 ESTALE and the draft stays for a retry — and keeps the file's CRLF line endings and final newline. A file the editor cannot take (binary, or over the 1 MB view cap) says so in the file's header.
• Overview — every changed file with its +N −M. Polls every 15s, because it is the cheap shape and the one you leave open while an agent works. Each row carries its own stage / unstage / discard buttons.
• Review — every file's full diff, stacked, for reading a whole change-set. Clicking a file's header folds it shut; only clicking the path itself opens that file. (A header that navigated on any click made folding a target-practice exercise against one chevron.) One toolbar button folds or unfolds all of them. What is remembered is the set of collapsed paths, so a file that appears later is open by default; a lane switch clears it. Each file's header stays pinned at the top while its diff scrolls past, and carries the same stage / unstage / discard buttons as its overview row. On a file with unstaged changes every change block — each run of consecutive +/- lines, not each @@ hunk: git merges edits up to six lines apart into one hunk, and one bar for all of them acted on every edit at once (issue #50) — gets an editor-style review bar, hung just under its last changed line and pinned to the visible right edge: ^/v to walk the blocks (each brings the next/previous block's first line to the top of the ONE scroller, below the sticky file header — a review diff has no scroll box of its own unless it is large enough to window, above 500 rows), n of N, Undo (discard-hunk — asks twice, like discard) and Keep (stage-hunk), both sent with the hunk's @@ line plus the block's index, so they touch that block alone. The single-file view offers the same bar.
• One file — clicking a file's path in any list opens just that file. All files returns to the list it was opened from — the same mode, at the same scroll offset — because reading a change-set is a walk down a long list and landing back at its top is the whole cost of opening one file.
• History — the lane's recent commits (GET /:id/git/log); opening one shows that commit's diff (?range=commit&sha=).

A range toggle switches the comparison between Uncommitted (HEAD vs the working tree, untracked files included as an all-added patch) and vs base (<base>...HEAD — what this lane's branch adds on top of base_branch; a lane with no base says so rather than guessing one). Opening a commit from History adds a third range, shown as a short-sha chip.

The viewer itself (issue #35) is VS Code-shaped: a unified / side-by-side toggle, syntax highlighting from the tokenizer the conversation view already ships (client/src/lib/highlight.ts — no new dependency), the changed span inside a modified line picked out by a common prefix/suffix trim, expand / collapse buttons that walk context both ways along 3 → 12 → 40 → the whole file, and a whole file switch that reads the file itself instead of its diff.

A diff scrolls on both axes inside its own bounded box, never by growing the panel: the single-file view takes the panel's remaining height, and each file in the stacked review list is capped, because a horizontal scrollbar at the bottom of a 2000-line container is only reachable after scrolling to the end of the file — the one place nobody needs it.

Side-by-side is two independently scrolling columns whose horizontal scroll is mirrored, not one wide row cut in half: a long line has to be able to run past its column's edge, and halves inside a single scroller instead painted over each other with nothing to scroll. The toolbar is two rows for the same reason — where you are (mode, refresh) above, how you are looking at it (range, layout, context, whole file) below — because one row wrapped mid-group in every panel narrow enough to sit beside a console.

Per-file writes are the panel's, per-repo writes are the git bar's. Staging one file means nothing unless a commit can take the index as it stands, so the overview grows a commit box the moment anything is staged — above the list and pinned while it scrolls, on ONE row with a Stage all that stages every listed file the index lacks in one call and an Unstage all that unstages every staged one — it sends only: "staged", never add -A, and it is absent with a clean index because there is nothing it could mean. It is the dashboard's ONLY commit: the git bar above it has none, so no click can sweep the rest of the tree in with add -A. Discard is the one irreversible action in the panel: it asks twice in the UI, and the server refuses it without confirm: true and accepts only paths git status is already reporting as changed. In the work range the overview splits like VS Code's Source Control: Staged Changes (what the next commit takes, each row offering Unstage) above Changes (unstaged and untracked, each offering Stage); a partly staged file appears in both. In the tree, a changed file's whole row takes its status tint, not only its letter.

Review, single-file, history and browse do not poll: re-fetching under the reader's scroll position is worse than a slightly stale view, and those are the expensive shapes. Diffs are capped server-side (300 files, 200 KB per file, 1 MB per full read) and say so when a cap bit.

Viewing lanes

List all lanes with their current status:

agenthub 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. needs_action_session records which session raised it, and only that session's next hook clears it — a second session in the same cwd (a hand-started terminal beside the dashboard pane) rebinds session_id but cannot clear a prompt it is not the one waiting on

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.

A lane is created on default unless told otherwise. The "+ Add lane" modal does not ask — it always creates on default. Pick another with agenthub lanes add --pipeline <id> at creation, or change it afterwards from the Pipeline template select in the lane's detail header in Workspace.

For a lane that already exists, switch it from the terminal:

agenthub lanes pipeline                 # which template this lane uses, and what else exists
agenthub lanes pipeline ship-feature    # switch it

or from the dashboard: the pipeline-template select next to the lane's title in the Workspace detail panel does the same PATCH /api/lanes/:id the CLI uses, live (disabled while viewing an archived feature snapshot).

The template names the skill that drives it. "skill": "/agenthub:ship-feature-lane" on the 16-node ship-feature template, "skill": "/agenthub:ship-feature" on the 8-node default one. It rides along on every lane payload as pipeline_skill, and from a terminal there is one command per depth of work — the command you type picks the pipeline, so no agenthub lanes pipeline step first:

cd ~/lanes/myrepo__feat-export

# 16 stages: ends in a published PR, watched until a human merges it
agenthub ship-full "add an export button"
# → lane switched to `ship-feature`, then: claude "/agenthub:ship-feature-lane add an export button"

# 8 stages: in-repo feature work, stops at review/gate — no PR, no browser QC
agenthub ship-quick "fix the CSV separator"
# → lane switched to `default`, then: claude "/agenthub:ship-feature fix the CSV separator"

agenthub ship-full "add an export button" --print   # show the command, switch nothing, run nothing

	agenthub ship-full	agenthub ship-quick
Template	ship-feature (16 nodes)	default (8 nodes)
Skill	/agenthub:ship-feature-lane	/agenthub:ship-feature
Ends at	PR open on development, watched until merged	ship in the working copy
Includes	unit-test agent, CI gates, e2e, code review, local browser QC, senior GO/NO-GO	plan, implement, tests, review, gate
Use when	the work should reach reviewers	the work stays local

The lane is resolved from the working directory, so no id is needed (pass one to target another lane). Each command puts the lane on its own template before spawning, so the dashboard renders the right node count from the first stage rather than after the skill self-corrects; --print switches nothing. The requirement is handed to claude as ONE argv element — never through a shell — so quotes, $ and ; in it are text. A template with no skill field makes the command refuse rather than guess.

Running ONE node

agenthub ship-full / agenthub ship-quick hand the whole pipeline to a skill. When you only want one step — re-run the CI gate, redo the brainstorm, open the PR by hand — run that node's own command:

agenthub lanes node                            # list every node of this lane's pipeline and its command
agenthub lanes node intake                     # → claude "/superpowers:brainstorming"
agenthub lanes node intake the export button   # extra words are appended to the prompt
agenthub lanes node review                     # → claude "/code-review"
agenthub lanes node gates                      # → agenthub lanes hook ci-gate
agenthub lanes node pr-open --print            # show the argv, run nothing

Both shipped templates give every node a command, so any of the 16 (or 8) is runnable. A node starting with / is spawned as claude "<command> <extra args>"; anything else is spawned directly. The lane comes from the working directory as usual, and the command always runs in the lane's own cwd.

The node is matched by id or alias, so one name works on either template: default calls the step implement and ship-feature calls it implementing, and agenthub lanes node implement finds it on both.

From inside a Claude session, use the slash commands instead. The plugin ships one per node — /intake, /plan, /implement, /tests, /e2e, /e2e-passed, /review, /qc-plan, /qc, /gate, /publishing, /pr-open, /reported, /watching-pr, /merged, /done — plus /ship-full and /ship-quick for the whole pipeline. Each resolves the node's command through agenthub lanes node <id> --print and runs it in the current session: a slash-command node is invoked directly (never as a nested claude process), anything else runs as a shell argv in the lane's cwd. Extra words are appended to the prompt: /intake the export button.

Two deliberate limits:

• The command is split on whitespace and spawned without a shell. A template is data — files anyone can drop into DASHBOARD_PIPELINES_DIR — so its command is never interpreted as shell. A node needing a pipe or a redirect names a script that contains them.
• Running a node does not declare its stage. A command executing is not proof the node passed — the same reason the run console never writes a lane's stage. Declare with agenthub stage <id> when the work is actually done. (The exception is a node whose command is agenthub stage <id>: there the declaration is the whole step.)

The template also decides what the Workspace run console pre-fills. A template may name the slash command that drives it — "skill": "/agenthub:ship-feature-lane" on the 16-node ship-feature template, "skill": "/agenthub:ship-feature" on the 8-node default one. That string rides along on every lane payload as pipeline_skill, and the run console starts its prompt box with it (plus a trailing space) so you only type the requirement: pick the 16-node template and Run starts the 16-step skill, pick the 8-node one and it starts the 8-step skill. The dashboard never executes it — it is text in a prompt box, exactly as if you had typed it. A prompt you have already edited is never overwritten by a later template switch, and a template with no skill field pre-fills nothing.

Switching re-resolves the lane's existing declared stage against the new node list. A stage the old template knew may resolve to nothing in the new one; the switch warns when that happens (both CLI and UI), and the next agenthub stage fixes it.

Aggregate pass rates across lanes

GET /api/lanes/pipeline-stats answers the other question about node states — not "where is this lane now" but "how often does this stage actually pass". It counts every stage record of every lane and every archived feature, grouped by pipeline template:

• entered — records that resolve onto the node (aliases included).
• failed — result: "fail"; passed is the rest, so passed + failed === entered.
• withEvidence — the passes that carry evidence, kept apart from passed because a claim and a proof are not the same fact (the same line the five node states draw between done and passed-no-evidence).

Archived features matter here: a lane's own stages only holds its current feature, so without them the history would reset every time a lane starts new work. This is also why new work reported as a bare backwards agenthub stage (see "Declaring an EARLIER stage") contributes less here than the same work reported under agenthub feature activate: the backwards declaration prunes the records ahead of it, so the previous pass leaves nothing behind to count, while a feature switch archives them first. Neither ever counted passes — one lane row contributes at most one record per node, however many times it ran — so this narrows the history, it does not skew a rate. The Workflows page renders this as one bar per node (see client/src/components/workflows/LanePipelinePanel.tsx).

A new run is opened by a DECLARATION, never by a detection alone. runs is the denominator every rate on that page is read against, so what counts as a run decides whether the page is worth reading. Stage detection bounces by design — one feature's work reads implement → tests → implement → tests as the session edits, runs the suite, and edits again — and when any backwards move opened a run, a single feature was recorded as five or six of them. A real pass ends where the session says it ends: a backwards move only starts a new run when it is declared (agenthub stage). A detection that moves backwards continues the run in flight. Reaching the last node still closes the run for both — work after done is new work by anyone's reading. On this repo's own lane the rule took a 26-run history down to 5, which is the number of features that were actually shipped through it.

?lane=<id> narrows the same aggregation to one lane and its own archived features, which is what the panel's lane picker sends. The lanes array in the response is never narrowed — it populates that picker, so it has to keep offering every other lane even while the counts show only one.

Attaching a real terminal to a lane

agenthub lanes shell attaches a real terminal to the exact tmux session the dashboard's Start/Resume buttons use for this lane (agenthub-lane-<id>), creating it if it doesn't exist yet. Type claude inside it like any normal terminal session — the dashboard's Workspace terminal view is just another client attached to the same tmux session, so both stay in sync live.

In practice you never have to pick correctly at creation. The template only has to match whichever skill is actually driving the lane, and the skill enforces that itself: ship-feature-lane runs agenthub lanes pipeline ship-feature and ship-feature runs agenthub lanes pipeline default before their first agenthub stage call — a no-op if the lane is already on that template, a self-correction if it isn't. A human chatting with the lane never needs to open the picker; whichever skill gets invoked decides the template.

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 agenthub 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

agenthub stage is not skill-only. Any Claude session working inside an adopted lane's cwd — including a plain chat session where no skill was ever invoked — should call it on real stage transitions. Tool-event detection (see "Inferred vs. declared" below) can only paint the amber "detected" badge; it never moves the blue current ring. A lane worked entirely through plain chat that never calls agenthub stage will keep showing whatever stage it was last declared at (often intake), regardless of how much real work happens.

When a skill — or a plain chat session — reaches a significant milestone, it reports the current stage to the dashboard using agenthub stage:

agenthub 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
• Advances the pipeline map to that node
• Broadcasts to the UI so connected dashboards see the update in real-time

Full command signature

agenthub stage <stage> [--lane <id>] [--cwd <path>] [--tool claude|codex] [--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

  Aliases are per template — the ship-feature pipeline has its own set (see "Pipeline template: ship-feature" below). A name matching no node and no alias is still recorded verbatim, but phaseIdx then resolves it to nothing: no node renders current and progress reads 0. The CLI prints a warning to stderr and still exits 0 in that case — a typo must not break a declaration the lane can record, but it must not pass silently either:

  ! "revieww" matches no node in pipeline "default" — recorded, but the pipeline map won't show it. Nodes: intake, plan, implement, …
  

  The check is skipped for --result fail, which paints the node failed rather than current.

• --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.

• --tool claude|codex (optional): which tool's lane to address when one directory backs both (see "Which lane a CLI command addresses" below).

• --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.

Declaring an EARLIER stage (going back)

A declaration may move a lane backwards — that is how a fix-loop re-entry, or a new request landing on a lane that already reached done, is reported:

agenthub stage plan --note "new request: export to CSV"

Declaring a stage that sits before the lane's current one does two extra things beyond the ordinary transition:

• Clears the detected columns, like every real transition (see "Inferred vs. declared" below).
• Drops the stages records of every node ahead of the new one. Those records belong to the previous pass. Left in place, a lane declared back at plan would render plan as current while tests/review/done still read done — carrying the old work's evidence — and progress (computed from the declared index alone) would contradict the map beside it. A gate ahead of where the agent now says it is has not been passed for this pass; it has to be re-earned and re-declared.

The node the declaration lands on keeps its own record (its evidence and result survive), and stage_since restarts, so time-on-phase measures this pass. Records stored under a key matching no node in the pipeline are left untouched — their position is unknown, so they cannot be proven to be ahead. Such keys only exist on lanes that predate validation: POST /api/lanes/:id/stage now rejects a stage naming no node of the lane's pipeline with 400 EBADSTAGE and lists the ones that exist. Aliases still resolve, so this catches typos and names borrowed from another template — agenthub stage test on a ship-feature lane, whose CI node is gates — which used to be stored, warned about on stderr, and then counted nowhere.

Every declaration is also appended to lane_stage_events, the append-only log the pass-rate report reads. lanes.stages describes the pass in flight and is overwritten and truncated by the rules above; the log is what remembers that the previous pass happened at all.

Going back this way is a declaration, not a reset: the lane, its worktree, and its archived features are untouched. To start a genuinely separate piece of work with its own archived pipeline, use agenthub feature activate <slug> instead (see "Per-feature state and archive").

Which lane a CLI command addresses

Every cwd-resolving agenthub command (stage, lanes pipeline, feature activate, lanes up/down/logs, …) shares one resolver, resolveLaneArg in bin/agenthub.js. It answers in this order:

1. --lane <id>, or a leading numeric positional.
2. AGENTHUB_LANE_ID in the environment — every tmux pane the dashboard starts carries it (tmux new-session -e, or an assignment prefix when the argv is typed into a pane already at a shell prompt). A session inside a dashboard-started pane therefore never has to guess.
3. --tool claude|codex, then the harness's own marker: Claude Code exports CLAUDECODE/CLAUDE_CODE_ENTRYPOINT, so a Claude session identifies itself for free. Codex has no equivalent marker (it only reads CODEX_HOME, and sets CODEX_SANDBOX* under a sandbox policy), so a codex session outside a dashboard pane must pass --tool codex.
4. The lane owning the directory — longest path-boundary match, the same rule the server uses.

The tool matters because one directory can back a claude lane AND a codex lane (the composite idx_lanes_cwd_tool). With two candidates at the same directory and no signal from steps 1-3, the command fails and names both lanes rather than picking one:

2 lanes own /home/me/repo — pass --tool <claude|codex> or --lane <id>: #23 (claude), #33 (codex)

That is deliberate. Silently taking the first would write a codex session's stage onto the claude lane's card — a lie about which agent did the work, and exactly the failure this resolver exists to prevent.

Example: a skill reporting progress

A build skill might call:

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

Output:

lane #5 → implement (66%)

A later call reports completion:

agenthub 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., ~/.agenthub/pipelines/ml-training.json):

{
  "id": "ml-training",
  "name": "ML Training Pipeline",
  "skill": "/my-training-skill",
  "nodes": [
    { "id": "data",      "label": "data",      "icon": "📊", "gate": false, "command": "dvc pull",          "aliases": ["intake"] },
    { "id": "preprocess","label": "preprocess","icon": "⚙️", "gate": false, "command": "make preprocess",    "aliases": ["prepare", "clean"] },
    { "id": "train",     "label": "train",     "icon": "🧠", "gate": false, "command": "/my-training-skill", "aliases": ["training", "fit"] },
    { "id": "eval",      "label": "eval",      "icon": "📈", "gate": true,  "command": "make eval",          "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
• skill (string, optional): the slash command that drives this pipeline (e.g. "/agenthub:ship-feature-lane"). The Workspace run console pre-fills its prompt with it for lanes on this template; omit it and the prompt starts empty. Never executed by the dashboard.
• nodes (array, required): list of pipeline stages, in order
  • id (string): stage identifier (used in agenthub 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
  • command (string, optional): the one command that drives THIS stage — a slash command ("/superpowers:writing-plans") or a shell one ("agenthub lanes hook ci-gate"). Where skill above names the driver for the whole pipeline, this narrows it to the step, so a reader of the pipeline map sees what moves each node instead of inferring it from the node's detect regexes. Omit it (or leave it empty) for a node with no single driver; both shipped templates fill every node, using "agenthub stage <id>" for the nodes whose only "work" is the declaration itself (a terminal done, a gate another agent declares). Surfaced in the node's tooltip on a lane card and as copyable text per node on the Workflows page, and run by agenthub lanes node <id> (below); never executed by the dashboard, same contract as skill.
  • aliases (array, optional): alternative names for the stage (e.g., ["training", "fit"] lets you call agenthub stage training)

Then set the environment variable:

export DASHBOARD_PIPELINES_DIR=~/.agenthub/pipelines

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

agenthub 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.)

Per-feature state and archive

A lane can carry many features (identified by slug) across its lifetime. Each feature has its own saved pipeline state (stage, status, notes) that persists separately from the live lane — the one every session and the Workspace console observe.

Why: clearLane used to erase the entire lane on each new feature. Now a lane can accumulate many features' saved states, letting you switch between them (via agenthub feature activate) and keep their pipeline histories separate. This matters for proof galleries, parallel task batches, and any flow where one lane runs many intentional phases.

The opt-in model

Nothing changes for a lane that never calls agenthub feature activate — clearLane still erases the live stage and status rows exactly as before. Only when you opt in to features does a lane start archiving. At that point:

• clearLane archives the current active feature (if any) before clearing the live lane row — its saved stage goes into the archive
• A lane that has never activated a feature is unaffected by this change and works exactly as it did before feature support

Slug canonicalization

Every feature is identified by a canonicalized slug. The rule is:

1. Drop a leading feat/ prefix if present
2. Replace / and whitespace with -
3. Keep [A-Za-z0-9._-] only
4. Do NOT lowercase — slugs preserve case

This is a deliberately different rule from worktree.js:slugify's branch-name slugification (which lowercases). The two must never be conflated. Every endpoint and CLI command echoes back the canonicalized form so the caller knows the exact slug that was stored.

Activate semantics

agenthub feature activate <slug> (or the API's POST /api/lanes/:id/features/activate):

1. Archives the current active feature (if any and if different from the target slug) — copies its live stage/status/notes to the archive
2. Restores the target slug's saved pipeline onto the live lane row — so switching back to a past feature resumes its pipeline exactly where it left off
3. Creates a fresh feature row for a never-seen slug (empty stage/status/notes)
4. Clears the live lane's detected columns (detected_stage/detected_signal/detected_at), the same way agenthub stage and clear do

This means activating an archived feature twice resumes the same pipeline both times.

Step 4 matters because a detection belongs to the feature that produced it. A never-seen slug starts at stage='idle' with stages={}, which is exactly the shape inferredDisplayStage renders from detection — so a carried-over detected_stage would paint the brand-new feature's map with the previous one's progress, and (detection being forward-only) reject every real detection for the new feature until the old one aged past DETECTION_TTL_MS. Detection is live-only state and is deliberately not snapshotted onto the outgoing archive row: switching back to a feature restores what was declared, never what was inferred.

The Workspace feature picker

The Workspace page's feature picker (read-only) shows every archived and active feature for the lane. Selecting one displays its saved pipeline. It never changes the live lane — a read-only view matching the standing rule that "the console never writes a lane's stage". Changing the active feature requires the CLI or the API route, not a UI button.

CLI commands

agenthub feature list [<id>]                          # List every feature (archived or live)
agenthub feature activate <slug> [--title text] [<id>] # Switch to a feature (echoes canonicalized slug)
agenthub feature show <slug> [<id>]                   # Show one feature's saved pipeline

Omit <id> to address the lane owning the current directory.

Stage detection

Besides the stage a skill explicitly declares with agenthub 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 agenthub stage — it fills in a lane's pipeline map without requiring every skill to be rewritten.

The matcher is fed by hooks — touchLaneFromHook in server/routes/hooks.js, on every hook, live — so it only ever sees claude lanes.

Codex has no hook mechanism at all, so touchLaneFromHook is pinned to "claude" — a hook must never touch a codex lane sharing the same directory. Codex lanes carry no pipeline, so nothing detects or advances their stage. server/lib/codex-ingest.js only mirrors a codex lane's status between idle and running: every DASHBOARD_CODEX_POLL_MS (default 15000; 0 disables) it lists $CODEX_HOME/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl ($CODEX_HOME defaults to ~/.codex), reads each thread's cwd from the session_meta on the file's first line, and calls the owning lane running while that journal's mtime is under two minutes old — and idle once it is older or in the future (a clock stepped back makes a raw now - mtime negative, which would otherwise read as live). It uses the identical guard hook ingestion uses (only a lane with no run_id, and only from idle/running — never from provisioning or failed) and writes nothing else: not stage, not notes, not slot/ports.

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 (agenthub stage coding resolves to the implement node, and stages is keyed by the raw declared word, not the node id). Past nodes get the same protection: stageRecords (server/lib/pipelines.js) resolves every recorded key back onto its node, so a stage declared by alias keeps its record — and its --evidence — instead of reading as an inference or losing its done. Where a node has both a canonical record and an alias record, the canonical one wins.

The same rule governs agenthub lanes: the inferred stage is printed only when it leads the declared one (see "Viewing lanes" below), and LaneStripCard.tsx's detectionLeads shows its badge under the identical condition — the terminal and the browser never disagree about which one is the headline. Both locate the declaration by the node the server already resolved it onto (the one whose state is current), never by looking lane.stage up as a node id: most of what the ship-feature skill declares is an ALIAS (tests, booting, ship, gate-blocked), which is not an id, and an id lookup scores it -1 — every detection, however far behind, would then read as leading.

Which lane a signal is credited to

A hook's cwd is the session's directory, not the directory the command ran in. Measured on a real install: 325 of 400 events carried the session's cwd while the edits and test runs happened in another repo reached with cd <other> && …. The lane doing the work detected nothing; the lane the terminal started in absorbed all of it.

So resolveLaneForWork (server/lib/lanes.js) prefers a lane named by the tool's own input — the file_path being edited, an absolute path a command cds into — and falls back to the session's cwd when the input names no other lane. Deepest match wins, same rule as resolveLaneByCwd.

Only the stage inference follows the work. session_id and needs_action stay on the session's own lane, because those really are session-scoped facts: the session is bound to the directory it started in even while it operates elsewhere.

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

Each rule is tested against these fields one at a time, never against a join of them. An Agent event really carries description + prompt + subagent_type together, so a rule anchored to the agent's identity — {"tool": "Agent", "match": "^Explore$"} in ship-feature.json — would never fire against a concatenation of all three, and a rule could otherwise match across the seam between two unrelated fields. Write anchored rules against the one field that identifies the tool call.

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.

Superpowers skill invocations

The built-in default pipeline's intake, plan, implement, review, and ship nodes each carry a {"tool": "Skill", "match": "..."} rule matching the workflow skill names they expect (brainstorming, writing-plans, executing-plans/subagent-driven-development, Claude Code's own code-review plus requesting-code-review/receiving-code-review, finishing-a-development-branch). Invoking one of these skills is a much stronger signal than a matched Bash command, but it is still detection, not declaration — it renders dashed amber and never done, same as every other detected stage.

Detection only ever attributes to a lane whose cwd matches the hook's session cwd (see "Which lane a signal is credited to" above). A session working directly in a source repo that was never itself adopted as a lane — run agenthub lanes add --cwd $(pwd) from that repo to fix that — gets no detection at all, because no lane owns that cwd.

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 300000, i.e. 5 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.

Five minutes, not thirty. A session cycles implement → tests → ship → implement → tests within one sitting, and a thirty-minute hold pinned the lane at the furthest stage it ever touched: one push left a lane reading ship while the agent was demonstrably back to running tests. Five minutes is still far longer than a burst of tool calls, so the anti-flap property is unaffected.

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	Agent matching subagent Explore — a lane sitting at nothing else yet, but already exploring, shows something instead of idle; Skill matching brainstorming, which is intake's own declared command
plan	Skill matching writing-plans; Write matching docs/.*plan.*\.md; Agent matching Plan|Software Architect|Backend Architect|UX Architect; TaskCreate (any)
implement	Skill matching executing-plans|subagent-driven-development|test-driven-development; 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|node\s+--test|rspec|phpunit|dotnet test|mvn test|gradle test)\b; Agent matching Test Results Analyzer|API Tester|Performance Benchmarker
review	Skill matching code-review|requesting-code-review|receiving-code-review; Bash matching \bgh\b[^;&|]*\bpr diff\b; Agent matching a name containing reviewer/Reviewer (excluding senior-gate-reviewer, a lookbehind), Evidence Collector, or Accessibility Auditor
gate	Skill matching verification-before-completion; Agent matching senior-gate-reviewer|Reality Checker — entering the gate, never its verdict
ship	Bash matching a git push invocation — git, then option groups, then push as the first non-flag token — or gh … pr create
done	none — see below

git diff is deliberately NOT a review signal. It was, and measured on a real session four git diff --stat runs — used to verify a generated file — outranked 81 test runs and 30 edits and pinned the lane at review, because detect() takes the LAST matching node and recordDetection is forward-only. Reading a diff is constant background activity, so it carries no stage information. gh pr diff stays: that one really is a review act.

The ship pattern matches a git invocation, not the word push. Two weaker forms were tried and both failed against real commands:

• git[^;&|]*push (same shell segment) misses this repo's own push, because git -c credential.helper='!f() { … }; f' push puts a ; between the two inside a quoted value. Six real pushes went undetected that way.
• git[\s\S]*push (anywhere after git) over-matches, and did so on a live lane within minutes: git log --oneline -1 && echo "… push …" pinned the lane at ship. Since ship sits near the end of the pipeline and detection is forward-only, that single over-read stuck — the same failure git diff caused for review.

So the pattern consumes option groups explicitly, treating a quoted option value as one unit, and then requires push to be the first non-flag token. That accepts git push, git -c core.hooksPath=/dev/null push and the credential -helper form, while rejecting git log … "push", git commit -m "don't push", docker push, and npm run push-docs.

The ship-feature template (server/data/pipelines/ship-feature.json) carries its own rules, aimed at the commands and Superpowers skills its driving skill actually runs:

Node	Detect rules
intake	Skill matching brainstorming; Bash matching agenthub … feature activate; Agent matching subagent Explore
plan	Skill matching writing-plans; Write matching docs/superpowers/specs/lane-.*\.md; Agent matching Plan|Software Architect; TaskCreate (any)
implementing	Skill matching test-driven-development|executing-plans|subagent-driven-development|systematic-debugging; Edit/Write to any path NOT under docs/superpowers/specs/ (resp. not under docs/)
gates	Bash matching agenthub … hook ci-gate or agenthub … sync-base --check
e2e-feature	Bash matching agenthub … up --qc or agenthub … hook e2e
review	Skill matching code-review|requesting-code-review|receiving-code-review; Agent matching a name containing reviewer/Reviewer (excluding senior-gate-reviewer, a lookbehind)
qc	Agent matching qc-local|Evidence Collector|Accessibility Auditor; Bash matching agenthub … lanes proof-link
gate	Agent matching senior-gate-reviewer|Reality Checker; Skill matching verification-before-completion
publishing	Skill matching finishing-a-development-branch; Bash matching a git push invocation (the same pattern default.json's ship uses)
pr-open	Bash matching gh … pr create
watching-pr	Bash matching gh … pr view
e2e-feature-passed, qc-plan, reported, merged, done	none — declaration-only

Two rules are deliberately absent from this template. There is no git diff rule on review, for the reason the default template learned the hard way below; the code-review skill invocation is the honest signal. And merged / done carry no rule at all, because inference must never reach a terminal state — a test pins that.

Detection here is a safety net, not the mechanism: the ship-feature-lane skill declares every one of these stages with agenthub stage itself. What detection adds is the stage an agent forgot after a context compaction, the heartbeat that keeps a working lane from reading STALLED, and coverage for a lane running Superpowers skills without the driving skill at all. It cannot substitute for the skill's own declarations: because recordDetection is forward-only AND never overrides a higher declared stage, a fix-loop re-entry that drops back to gates is invisible to detection — only the skill's agenthub stage gates moves the lane back down.

done in default.json deliberately has no rule — it is explicitly out of scope for inference (see the task's "Out of scope" list): done is the one state detection must never reach on its own, since inferring it would let a heuristic assert an outcome instead of observing activity. intake and gate now carry entry-activity rules (an Explore agent, a senior-gate-reviewer/ Reality Checker agent or verification-before-completion skill) — these detect that the activity of exploring or gate-reviewing started, never a gate's pass/fail verdict, so the "no outcome inference" rule still holds.

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. One exception: a declaration on the pipeline's LAST node (done, in both built-in templates) stops vetoing. The pipeline is finished there, so a later detection is new work rather than a stale rerun of what the claim covers — without the exception a lane left at done rejects every detection for the rest of its life, which reads as "auto-detect is broken". The exception changes nothing else: the detection still only paints the amber badge, and lanes.stage still says done until an agent declares otherwise.
• 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

Housekeeping: agenthub lanes gc

Runs machine-wide, not against one lane — safe to run any time, running lanes and live sessions are unaffected:

agenthub lanes gc [--dry-run]

Two things, both scoped to what's actually stale:

• Reaps orphaned Playwright MCP processes. A .playwright-mcp-scoped process whose owning Claude Code session died gets reparented to pid 1 — a live session's MCP keeps its real parent and is left alone. Kills the whole process tree so a spawned browser doesn't leak too.
• Caps oversized hook logs. Any LANES_ROOT/.state/lane<N>/logs/*.log over 10MB is truncated in place to its last 2MB (same inode — a concurrent writer's file descriptor stays valid).

--dry-run prints what would happen without doing it. This is a deliberately narrower port of Shipyard's lane-gc.sh — it does NOT auto-remove stale worktrees by age (that would violate this repo's own never-automatic-destroy rule; use agenthub lanes reset|remove|purge explicitly instead), archive feature state (AgentHub's lane/feature state lives in the database, not flat files), or sweep scratch debris (AgentHub doesn't generate the files Shipyard's own scripts did). See docs/superpowers/specs/2026-08-05-lane-gc-design.md for the full scoping rationale.

Lane actions

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

start

Start a tmux-backed run attached to the lane. The Workspace page's "Start Run" button calls POST /api/run with the lane's id; you can also attach from a real terminal using agenthub lanes shell.

curl -X POST http://localhost:4820/api/run \
  -H "Content-Type: application/json" \
  -d '{"laneId": 5, "initialPrompt": "continue the work"}'

The initialPrompt field is optional — if omitted, the tmux session is created/attached with no initial input, and you type into the terminal directly. Returns { id, laneId, status, cwd, model, permissionMode, effort, resumeSessionId, sessionId, startedAt, promptPreview } where id is the tmux session name. The same tmux session persists across attach/detach cycles, so you can switch between the browser Workspace and agenthub lanes shell seamlessly.

The model picker offers aliases, not pinned ids. The Run setup's Model select sends fable / opus / sonnet / haiku (plus Custom… for a literal id, and the empty value that inherits settings.json). claude --model documents those as "an alias for the latest model" and resolves each itself — 2.1.278 maps fable to claude-fable-5-1 — so a new model release reaches the dashboard the moment the CLI is updated, with no list to edit by hand. Cost maths is unaffected: pricing keys off the model id the transcript reports, which is always the resolved full name. Codex has no such aliases, so RUN_MODEL_CHOICES_CODEX stays a pinned list.

Permission mode in a lane run. permissionMode (one of auto — the default — acceptEdits, default, plan, bypassPermissions) sets the mode the pane starts in. auto hands the decision to the CLI's own classifier, which asks only for what it reads as risky; it is what a terminal claude starts in too. The pane's claude also gets --allow-dangerously-skip-permissions, which puts bypass permissions into the pane's own shift+tab cycle without enabling it — matching what you get in a real terminal, where the cycle would otherwise be limited to plan / auto / manual / accept-edits and bypass would be unreachable from inside a dashboard-started run. Bypass is still only ever entered by an explicit shift+tab in the pane or by asking for permissionMode: "bypassPermissions" up front; nothing skips permission checks by default.

A killed run releases the lane. When the tmux session is terminated (from the terminal, browser stop button, or external kill), the lane's run_id is cleared, its status returns to idle, and the change is broadcast as lane_update. Runs are recorded with the lane's id and are listable via GET /api/run/history?laneId=<n>.

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

git: fetch / pull / push / stage / unstage / discard / commit / switch / branch-create / branch-delete / publish

The git writes the Changes panel and its action row offer. See "Acting on a lane's working copy" above for what each one refuses and why.

curl -X POST http://localhost:4820/api/lanes/5/git/commit \
  -H "Content-Type: application/json" \
  -d '{"message": "wip: from the dashboard"}'

# Only what the Changes panel staged
curl -X POST http://localhost:4820/api/lanes/5/git/commit \
  -H "Content-Type: application/json" \
  -d '{"message": "wip: staged only", "only": "staged"}'

# Irreversible, so `confirm` is required and the path must be one git
# already reports as changed
curl -X POST http://localhost:4820/api/lanes/5/git/discard \
  -H "Content-Type: application/json" \
  -d '{"paths": ["src/scratch.ts"], "confirm": true}'

# A repo with commits but no remote: add `origin` and push HEAD to it
curl -X POST http://localhost:4820/api/lanes/5/git/publish \
  -H "Content-Type: application/json" \
  -d '{"url": "git@github.com:owner/repo.git"}'

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 dashboard's record of the lane, including its recorded history. The working tree, its branch and its database are left untouched. 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 accidentally dropping a lane's record. It deletes that record only — never the worktree, the branch or the database.

Proof gallery

A lane's proof gallery is a collection of QC screenshots captured during active work, grouped by feature (the same slug from Per-feature state and archive above) and phase (e.g. desktop, mobile, e2e, visual). A QC agent running an MCP server like playwright-mcp captures screenshots to disk at <lane.cwd>/.playwright-mcp/proof/<slug>/<phase-group>/ and generates an optional ticket report at <slug>/ticket/REPORT.html. The Workspace gallery panel displays these files grouped by feature, using the same feature picker as the per-feature state section.

Storage

Proof files live inside the lane's own cwd, not under LANES_ROOT:

<lane.cwd>/.playwright-mcp/proof/
├── auth-redesign/
│   ├── desktop/
│   │   ├── 01-login.png
│   │   └── 02-signup.png
│   ├── mobile/
│   │   ├── 01-login.png
│   │   └── 02-signup.png
│   └── ticket/
│       └── REPORT.html
├── another-feature/
│   ├── e2e/
│   │   └── 01-user-flow.png
│   └── ticket/
│       └── REPORT.html
└── …

Linking proof directories (the ensure_proof_link primitive)

An MCP server's --output-dir flag may point to different locations across runs. To converge all proof onto one canonical path regardless, AgentHub provides the ensure_proof_link operation, exposed only as the explicit agenthub lanes proof-link CLI command — it is never automatic. This matches the "AgentHub does not orchestrate" rule: a session decides when to link, not the dashboard.

ensure_proof_link works as follows:

1. If a stray proof/ directory exists at <lane.cwd>/proof, merge its contents into the canonical .playwright-mcp/proof (no-clobber — existing files are never overwritten) and replace it with a symlink.
2. If a proof/ symlink already points to .playwright-mcp/proof, the operation is a no-op.
3. If a file named proof exists (neither directory nor symlink), it is left untouched to avoid clobbering a user's file.

The operation is idempotent and always safe — running it multiple times on the same lane has no side effects.

Security

Every path the proof module touches — reading, serving, or deleting files — is resolved, realpath'd, and checked to be inside the lane's proof root before any filesystem operation. Symlink escapes, path traversal (../), and bad characters (/, \, .. in segment names) are all rejected with EBADPATH errors. deleteProof never removes the ticket/ directory, only the phase-group subdirectories and their images, so a lane's ticket report persists even when phase proofs are pruned.

Gallery panel and feature selection

The Workspace page's gallery panel reuses the feature picker from Per-feature state and archive — there is only one selector, not a separate one for proofs. Selecting a feature displays that feature's saved pipeline (from per-feature state) and its proof gallery (if any proofs exist for that feature).

Cross-lane named locks

Cross-lane named locks serialize work that thrashes a shared machine — builds, e2e runs, database migrations — across all lanes, not just within one lane. This is a separate axis from withLaneLock, the in-process per-lane lock in server/lib/lane-lock.js: lane-lock is about when a lane runs internal operations; named-lock is about which other lanes must wait.

How they work

• Atomicity via mkdir. Lock ownership is declared via an owner marker file inside LANES_ROOT/.locks/<lock-name>/. mkdir atomically creates the lock directory or fails with EEXIST — no race between check and create.
• Owner file format: <holder> <acquired-epoch-seconds> — the holder identity (defaults to lane<slot> for the calling lane) and a Unix seconds timestamp. When a new acquire finds the directory already exists but the holder is stale (older than LOCK_MAX_HOLD seconds, default 2700s / 45 minutes), the old holder is considered dead, its directory is removed, and the acquire is retried once before answering.
• The LOCK_MAX_HOLD floor. The default is 2700 seconds, but it has a hard floor of 300 seconds. No caller can force-break a live holder by setting LOCK_MAX_HOLD=1 — the floor prevents that mistake. The lowest possible break threshold is 300 seconds, even if LOCK_MAX_HOLD is overridden to something smaller.
• Waiting and polling. agenthub lock acquire blocks the calling lane (polling the server every ~2 seconds via a single-shot POST /:name/acquire — the server itself never blocks or queues) until the lock is free or --timeout expires. While waiting, it prints a status line every ~60 seconds, so a long wait reads as "still waiting", not a hung command — this is terminal output for whoever is watching, not a dashboard liveness signal.

The CLI

agenthub lock status [<name>]

Show one named lock's current holder, or every currently-held lock. <name> is optional — without it, lists all locks.

agenthub lock acquire <name> [--holder X] [--timeout N]

Acquire a cross-lane named lock, polling until it is free or the timeout expires. --holder defaults to lane<slot> (the calling lane's identifier based on its slot). --timeout is in seconds; without it, the command waits indefinitely.

agenthub lock release <name> [--holder X]

Release a lock. Refused with status 409 if the --holder does not match the current owner. The --holder default is the same as acquire: lane<slot>.

The lane card

The lane card shows a lock badge when the lane holds a named lock (its lane<slot> identity matches a held lock's holder) — polled every 30 seconds, the same interval as git and runtime facts. There is no server-side concept of "who is waiting" to display; only who currently holds.

Etiquette

Waiting is normal. A lane that sits at a lock for a few minutes while another finishes a build is expected behavior, not a failure. Do not interrupt or force-break a lock.

• Never kill a holder. If a lane is stuck holding a lock, do not kill the process or the dashboard. Investigate why the holder is not releasing it.
• Never delete the lock directory by hand. A lock that outlives its holder (e.g. after a hard reboot) is cleaned up automatically — the next acquire on that name finds it stale (older than LOCK_MAX_HOLD) and breaks it. Deleting LANES_ROOT/.locks/<name>/ yourself only races whoever else's acquire is about to do the same check safely.
• Never shrink LOCK_MAX_HOLD to force through a wait. The 300-second floor exists specifically to stop this mistake. If the true holder is gone, the 300-second minimum wait is the price of safety. If the true holder is still running (e.g., a build with a network stall), shortening the timeout from 2700 to 300 does not help — it converts a slow success into a premature timeout, leaving the lock held and every other lane blocked forever.

The ship-feature-lane skill (E1)

The ship-feature-lane skill is the ported Shipyard driving skill for autonomous end-to-end feature pipelines in a single AgentHub lane. It coordinates the entire development flow: implementation (TDD) → independent unit tests → pre-push CI gates + dev preflight → e2e testing → code review → local QC → senior gate authorization → PR push and publication → CI watch → final report.

Every stage whose job is to judge the work runs in a fresh-context subagent, never in the driving session. The plan debate (Stage 0b), unit tests (Stage 1b), the e2e run and its triage (Stage 3), code review (Stage 4), browser QC (Stage 6), the senior gate (Stage 7), and a re-triage of CI that stayed red after a fix (Stage 10) are each dispatched with the Agent tool to a subagent that starts with an empty context and receives only artifacts it can verify itself — working directory, lane spec, diff range, commands, and the other agents' reports verbatim, never the driving session's paraphrase of why a finding was fine. The stages the driving session keeps are the ones that do rather than judge: intake, implementation, the mechanical gates, publishing, the CI/PR watch, and applying every fix the judges ask for. subagent_type: fork is explicitly forbidden for these: a fork inherits the implementing session's context, so it inherits the belief that the code is already correct. The driving session implements and applies fixes; it never grades its own work. Stages 1b/3 use the generic general-purpose type (nothing to install). Stage 4 uses the generic Code Reviewer type as its catch-all, plus — in parallel, routed by which of server/, client/ the diff touches — the plugin-qualified agenthub:backend-reviewer / agenthub:frontend-reviewer domain reviewers (nothing to install; agenthub: addressing works from any lane). Stages 6/7 use the lane-installed qc-local/senior-gate-reviewer agents.

Getting the skill (nothing to do, if you run the plugin)

The skill lives in skills/ship-feature-lane/, and the repo root is the agenthub plugin root ("source": "./"), so skills/ is the plugin's own skills directory. Anyone with the agenthub plugin installed already has it in every session, from any lane's working directory, as /agenthub:ship-feature-lane — with the bare /ship-feature-lane working as an alias unless another skill or command claims that name.

Only a plain checkout without the plugin needs the fallback:

agenthub skills install

Copies skills/ship-feature-lane/ into ~/.claude/skills/ship-feature-lane/ (overwrites on reinstall — run it again after pulling an update to the skill), which restores the bare /ship-feature-lane name. One-time per machine, same as agenthub lanes agents install is one-time per lane.

Agents come from the same plugin, under two names. qc-local and senior-gate-reviewer live in agents/ at the repo root, so the plugin exposes them as agenthub:qc-local / agenthub:senior-gate-reviewer. agenthub lanes agents install copies those same files into the lane's own .claude/agents/ — the highest-priority agent source — which is what makes the bare subagent_type: qc-local the skill prefers resolve inside the lane. Either name reaches the same definition; the skill falls back to the agenthub: form when the lane copy is missing.

Invoking the skill

# Inside a lane's working directory:
/ship-feature-lane <requirement>

The skill frontloads all clarifying questions once, then runs unattended. The only interactive touchpoints are Stage 0 (Q&A intake) and merging the PR on GitHub; everything else runs to completion or escalates with a blocked status visible on the dashboard. Progress is declared via agenthub stage commands at every step.

Current status: stages 0–8, 10–12, 14 work; stage 9 deferred, stage 13 partially wired (CI-wait works, dev-QC doesn't); stages 6–7 agent-gated

Stages implemented now:

• 0-8: Intake & frontloaded Q&A → plan → implementation → independent unit tests (1b) → gates+preflight → e2e on feature branch → code review → QC plan → QC → senior gate → publish PR
• 10-12: CI watch on the PR → report → watch PR until merge (gated fix-loop re-entries on review feedback)
• 14: Done

Stages currently hardcoded skipped (pending F's integrations):

• 9 (Ticket): Ticket-filing integration not yet built — this stage is skipped entirely.

Partially wired:

• 13 (Post-merge verification): CI-wait half now runs for real via agenthub lanes ci status. The dev-QC half (QCing the deployed site) is still unavailable — Stage 13 always ends noting that gap even when CI-wait passes clean.

Stages 6 and 7 are now unblocked — run agenthub lanes agents install once per lane (see "Installing the QC/gate agents" below) before a lane's first run through Stage 6. A lane that reaches Stage 6/7 without having installed the agents will fail to find the qc-local/senior-gate-reviewer subagent type; install and re-run.

See the skill text for the full pipeline definition.

QC boot flag and profile integration

When the lane stack needs to run under QC conditions (deterministic, mocked externals), use the --qc flag:

agenthub lanes up --qc

This flag activates the lane's QC_BOOT_ENV profile declaration. Define it in the profile's profile.env file as space-separated KEY=value pairs (the same format as the PORTS declaration):

# .agenthub/profile/profile.env
PORTS="app"
PORT_BASE_app=3000
QC_BOOT_ENV="MOCK_PAYMENTS=1 STUB_EMAIL=1"

These environment variables are passed to the profile's boot hook during agenthub lanes up --qc, ensuring QC test runs are deterministic.

Dev preflight and merge safety: sync-base

agenthub lanes sync-base is the ONE sanctioned merge in the pipeline — origin/development into a feature branch — used at Stages 2, 8, and 12. Three modes:

agenthub lanes sync-base --check feat/<slug>      # read-only preflight: fetch + collision check + DEV_DELTA/DEV_OVERLAP
agenthub lanes sync-base feat/<slug>               # merge origin/development into the feature branch
agenthub lanes sync-base --continue feat/<slug>    # finish after a manually resolved conflict

Exit codes: 0 clean, 4 merge conflict (left in place — resolve, commit, then --continue), 5 migration-number collision (nothing merged — rename the printed file, re-run).

Two profile declarations control it, both empty (off) by default:

# .agenthub/profile/profile.env
MIGRATIONS_DIR="db/migrations"
GENERATED_MERGE_PATHS="api/openapi.json api/client.ts"

MIGRATIONS_DIR enables the collision preflight against a numbered-migrations directory. GENERATED_MERGE_PATHS gives the listed files a keep-ours merge driver (never hand-merged) and folds the profile's regen hook output into the sync commit — the single most common cross-lane conflict, for a repo that generates an API contract/client.

Installing the QC/gate agents: agents install

Stage 6 (browser QC) and Stage 7 (senior GO/NO-GO gate) run as subagents — qc-local and senior-gate-reviewer. The plugin already ships them as agenthub:qc-local / agenthub:senior-gate-reviewer; installing them into the lane's own .claude/agents/ is what makes the bare names work there:

agenthub lanes agents install

Writes both agent definitions (from the repo's own agents/, the same files the plugin ships) into <lane>/.claude/agents/ and adds that directory to the lane's local .git/info/exclude (never the tracked .gitignore — this is a per-clone runtime concern, not an app-repo change). Idempotent and never automatic, the same shape as agenthub lanes proof-link — a session installs the agents explicitly, once, before a lane's first run through Stage 6/7 (or after a AgentHub upgrade ships updated templates — reinstalling overwrites, it doesn't merge).

On a codex lane the same command installs nothing (installed: [], and the Tools menu hides it): Codex never reads .claude/agents/, and codex lanes carry no pipeline to drive.

Credentials are not embedded. Unlike Shipyard's original per-lane agent generation, these templates carry no QA account credentials — this repo has no seeded-QA-account system yet. qc-local degrades gracefully: if it hits a login page with no credentials block present, it reports LOCAL-QC: FAIL — login required, no seed-account mechanism configured for this profile rather than guessing.

ticketer, dev-qc, and pr-reviewer are not ported yet — ticketer is invoked by Stage 9 (skipped), and dev-qc by Stage 13's dev-QC half (unavailable); pr-reviewer isn't referenced anywhere in this skill's text.

Syncing MCP servers: mcp sync

A lane needs the same MCP servers (Playwright, a local-QC server) as its source repo to run Stage 3/6. agenthub lanes mcp sync gives it those:

agenthub lanes mcp sync

Reads the source repo's already-configured mcpServers from ~/.claude.json (normal Claude Code project-scope config — set this up for the source repo once, the same way you would for any project), relocates any absolute path under the source repo to the lane's own directory, pins a @playwright/mcp server's --output-dir to the lane's .playwright-mcp (so proof screenshots land where the proof gallery reads them), and writes <lane>/.mcp.json. Also seeds the lane's Chromium browser profiles from the source repo's own — preserves saved logins, and never overwrites a profile that already exists at the destination.

No permission/settings changes. Unlike Shipyard's original lane-mcp-sync.sh, this command never writes to <lane>/.claude/settings.local.json — no auto-approval rules, no autoMode bypass entries. A session's gh/git push commands go through the normal permission prompt like any other command.

A lane whose source repo has no mcpServers configured gets a clear ENOMCPCONFIG error, not a silently-empty .mcp.json — configure the source repo's MCP servers first, then re-run.

Restart the lane's Claude session after syncing — MCP config is read at session start.

Checking integration toggles: agenthub lanes integration

A profile can declare .agenthub/profile/integrations.env with TRACKER_ENABLED, DEV_QC_ENABLED, CI_WAIT_ENABLED flags (all off by default — see profiles/_template/integrations.env-style declarations in a profile's own docs). Check one:

agenthub lanes integration tracker    # exit 0 = on, 1 = off

This only reports what the PROFILE wants — it doesn't file a ticket, run dev-QC, or wait on CI. The agent that would act on an enabled dev_qc toggle isn't built yet, and neither is a tracker ticketer — ship-feature-lane's Stage 9 stays skipped and Stage 13's dev-QC half stays unavailable regardless of what those two toggles read. ci_wait's consumer is agenthub lanes ci status (added — see the command reference below); Stage 13's CI-wait half now honors it for real. The CLI command and GET /api/lanes/:id/integrations/:name are the only readouts: the lane card used to carry a row of three badges for these, and it no longer does — two of the three could never be anything but decoration, and a badge that reports a toggle nothing acts on costs a row of card height to say nothing.

Post-merge CI status: agenthub lanes ci status

Check GitHub Actions status for a commit SHA or branch ref — used by Stage 13's CI-wait loop:

agenthub lanes ci status <branch-or-sha> [<id>]

Exit codes: 0 = all checks passed, 1 = at least one check failed, 3 = checks pending or in progress. The <id> parameter is optional and filters results to a specific lane if provided; if omitted, it's not needed.

Pipeline template: ship-feature (16 node stages)

The skill uses the ship-feature pipeline template, which defines the following 16 stages (node IDs):

1. intake — frontloaded Q&A and feature activation
2. plan — investigation and plan debate
3. implementing — TDD implementation
4. gates — CI gates + preflight check
5. e2e-feature — run e2e on feature branch
6. e2e-feature-passed — e2e result gate
7. review — code review
8. qc-plan — bound QC scope
9. qc — browser QC (agent-gated until qc-local lands)
10. gate — senior GO/NO-GO gate (agent-gated until senior-gate-reviewer lands)
11. publishing — push branch + open/update PR
12. pr-open — PR open and published
13. reported — report posted
14. watching-pr — watch for comments, conflicts, merge
15. merged — PR merged, post-verify transition
16. done — pipeline complete

The Workspace page (/run) displays this template with nodes rendered in five states: failed (rejected), current (now), done (with evidence), passed-no-evidence (claimed or skipped), and pending (not reached).

More stage names than nodes

Each node carries aliases, and they do two different jobs. Some absorb a near-miss (implement for implementing). Others are sub-states: a name the skill declares to say why the lane is sitting on a node, without adding a node to the map.

This is the shape Shipyard converged on — its dashboard renders 13 nodes while its PHASES table folds roughly 35 stage names onto them. A pipeline map is read at a glance across many lanes at once, so it stays coarse; the stage name is read one lane at a time, so it can be specific.

Node	Near-miss aliases	Sub-states the skill declares
intake	assigned, claimed, start	bootstrapping
plan	planning, brainstorm, design	—
implementing	implement, coding, build	—
gates	pre-push-gate, tests	migration-collision, sync-conflict
e2e-feature	e2e, live	booting, e2e-scoped
e2e-feature-passed	e2e-passed	—
review	reviewing, code-review, self-review	—
qc-plan	—	—
qc	—	—
gate	sr-gate, verify, verification	gate-blocked
publishing	push	—
pr-open	ship, pr, push-conflict	push-revalidate
reported	—	—
watching-pr	—	pr-comment-fix
merged	—	—
done	complete, completed	—

50 names over 16 nodes. Every one of them has a source: the skill declares it, or default.json uses it (an agent moving between pipelines will type what the other one taught it), or Shipyard's PHASES lists it. An alias with no source is not "flexibility" — it is a synonym someone imagined, and the agenthub stage warning already catches a name that resolves to nothing, which is better feedback than silently absorbing every plausible spelling. Twelve sourceless aliases were written and then cut for exactly this reason.

Two constraints on this:

• No alias may collide with another node's id or alias. phaseIdx takes the FIRST match, so a duplicate would silently resolve a declaration onto the wrong node. A test asserts the whole template is collision-free.
• Aliases of one node share one record slot. lane.stages is keyed by the declared string, and stageRecords resolves each key onto its node — so declaring migration-collision and then gates leaves ONE record for that node (the canonical gates one wins). A sub-state that needs to keep its own --evidence separately has to be a real node, not an alias.

integrate, dev-gates, e2e-on-dev and push-dev are deliberately not nodes here. Shipyard had them and retired them on 2026-07-16 (see the comment above PHASES in its dashboard/src/lib/constants.js); it now folds those names into the surviving phases so old feature cards still render. AgentHub never shipped them, so there is nothing to fold.

These nodes also carry detect rules; see "Stage detection → Where the rules live".

Orchestration: what AgentHub does NOT do

AgentHub 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 agenthub 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 agenthub 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: agenthub stage tests --evidence "2 tests still failing"
5. If skipping: agenthub 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

agenthub lanes                                    # List all lanes
agenthub lanes add --cwd <path> --title <text>    # Adopt an existing directory
agenthub lanes add --repo <path> [--title <text>] [--base <branch>] [--slug <slug>]
agenthub lanes reset|remove|purge <id> [--force] --yes
agenthub 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/agenthub.js — CLI commands for lanes and stage reporting
• server/routes/hooks.js — hook-to-lane binding by cwd, and where detection is invoked