# A1 — Lane runtime isolation: slots, ports, profile hooks, detached lifecycle

**Status:** approved 2026-08-03. Roadmap it belongs to:
`docs/superpowers/plans/2026-08-03-shipyard-parity-lanes.md`.

## Problem

A lane isolates **code** and nothing else. `server/lib/worktree.js` gives each lane
its own git worktree and branch, so two agents never overwrite each other's files —
but they share every other resource: the same ports, the same database, the same
`.env`, the same upload directory. Booting two lanes' stacks at once does not work.

Shipyard (`AgentWorkflow/`) solved this with per-lane ports, database, Redis logical
index and `.env`. That is **not** containerization — every lane runs on the host as
the same user. Its isolation is *resource namespacing at the application layer*.

## Scope

Shipyard parity is six independent subsystems (see the roadmap). A — runtime
isolation — goes first because it blocks the rest, and splits into three:

- **A1 (this spec)** — a lane can boot its stack on isolated ports and directories,
  and the stack survives a dashboard restart. Profiles are hand-written.
- **A2** — data isolation: `.env` seeding, database create/drop/migrate/seed, Redis index.
- **A3** — stack detection + `ccam lane profile init` scaffolding, designed **from**
  the real profiles written during A1/A2.

The split point matters. Shipyard was genericized but its `profiles/` is still
empty (`PROFILE=_template`, `SOURCE_REPO=""`, `state/` empty) — a clean seam that
never ran against a real app. Designing presets before a real profile exists
repeats exactly that.

**A1 done means:** `ccam lane up` boots a lane's stack on ports no other lane uses,
and `ccam update` (or any dashboard restart) leaves running stacks alone.

## Decisions

| | Choice | Rationale |
|---|---|---|
| Profile location | `<repo>/.ccam/profile/` | CCAM is multi-repo (lanes keyed by `cwd`); one global `PROFILE` is wrong the moment two repos have lanes. A profile that lives in the repo is already present in a fresh worktree. |
| Engine | Node, `server/lib/` | `execFile` with argument arrays (repo rule: never build a git/shell command as a string). Shares the SQLite DB and the websocket. Hooks stay shell scripts; the engine spawns them. |
| Resource model | Declared per repo | `PORTS="api fe worker"`, `LANE_DIRS="…"`. An app with no database declares none, so A2 generates no database hooks — no dead code. |
| Process ownership | Fully detached | pid files outside the worktree; a dashboard restart does not touch a running stack. |
| Port allocation | Base + slot, step aside on collision, record the real number | Predictable in the common case, does not hard-fail when a port is busy. |
| Adopted lanes | May `up`/`down`; every write path refused | `up` only runs what the user can already run themselves. Writes into their `cwd` (A2) are refused outright. |
| Runtime state | DB owns allocation, disk owns handles, up/down **computed on read** | A process dies to OOM, `kill`, or a reboot — caching a truth you do not control buys ghost state. Slot allocation is the opposite: fully controlled, needs to be race-free, so it belongs in the DB. |

## Invariants

1. **The runtime never writes `stage`, `status`, or `notes`** — only `slot` and
   `ports`. In CCAM `status=running` means *an agent is working*, not *a stack is
   up*; conflating the two breaks `classifyLiveness`. Boot failures surface through
   `GET /runtime` and the hook log. Same reasoning as "the console never writes a
   lane's stage".
2. **CCAM still does not orchestrate.** A1 adds *primitives* (`up`/`down`/`hook`)
   that a session calls. The dashboard chains nothing, evaluates no gate, retries nothing.
3. **No shell command built as a string.** `execFile` + argv arrays everywhere.
   Hooks are the deliberate exception — they *are* scripts, spawned as
   `bash <hook> <args…>` with a fixed argv, never interpolated.
4. **`profile.env` is parsed, never sourced.** Sourcing arbitrary shell from a repo
   into the dashboard process is a code-execution path. Hooks are executed on
   purpose; config is only read.
5. **Adopted lanes stay non-destroyable** (`assertManaged` in `worktree.js`). A1
   adds no bypass.

## Design

### Schema (`server/db.js`)

```sql
ALTER TABLE lanes ADD COLUMN slot INTEGER;
ALTER TABLE lanes ADD COLUMN ports TEXT NOT NULL DEFAULT '{}';
CREATE UNIQUE INDEX IF NOT EXISTS idx_lanes_slot ON lanes(slot) WHERE slot IS NOT NULL;
```

Added with the existing probe-each-column-independently migration pattern.
`ports` is parsed by the same `hydrate()` branch that already handles
`stages`/`links`, corrupt-blob fallback included.

`slot` and `ports` join `PROVISIONING_FIELDS` and stay **out of** `PATCHABLE`, for
the reason `kind` is excluded: a client that can set `slot` can change the
slot-derived `DB_NAME` A2 will use — which aims a drop at another database.

No column records "is up". Deliberate.

### Modules

| File | Responsibility |
|---|---|
| `server/lib/ports.js` | `isListening(port)` via a short-timeout `net.connect`; `listenerPids(port)` via `lsof`, falling back to `ss`, returning `[]` with a one-time warning when neither exists. |
| `server/lib/lane-slots.js` | `allocateSlot()` — lowest free in `[1, LANE_MAX_SLOTS]` (default 9), called inside the existing `withLaneLock`, with the unique index as the backstop. `releaseSlot()` on `remove` only — **not** on `reset`, or a lane's ports and database move under a running session. `resolvePorts(slot, profile)` — prefers `PORT_BASE_<name> + slot`, then `+100`, `+200`… (the last digit stays the slot, so the number still reads as "lane 3"), up to 10 tries before `EPORTBUSY` naming the occupying pid. |
| `server/lib/lane-profile.js` | `resolveProfile(lane)` — looks in `lane.cwd/.ccam/profile/` **first**, `lane.source_repo/.ccam/profile/` second, because the profile lives in the repo and a branch that edits its hooks must run its own. `runHook(lane, name, args, {onLine})` — fixed hook-name allowlist, `bash <hook>` with an argv array, Shipyard's env contract verbatim so its profiles port unchanged (`LANE` = the **slot**, `LANE_DIR`, `RUN_DIR`, `LOG_DIR`, `PROFILE_DIR`, `SOURCE_REPO`, `<NAME>_PORT` per declared port), `harness_spawn` exported as a bash function writing the same `$RUN_DIR/<name>.pid` + `$LOG_DIR/<name>.log`, the `GIT_*` scrub from `worktree.js:git()`, and output streamed both to the log file and to a new `lane_hook_output` websocket message. |
| `server/lib/lane-runtime.js` | `upLane` (defensive down → mkdir run/log/`LANE_DIRS` → `boot` → `health`; no `bootstrap`, which belongs to provision/reset as in `lane-up.sh`), `downLane` (recursive pid-tree kill from the pid files — ported from `lane-down.sh:kill_tree`, which exists because detached uvicorn/celery prefork children were being missed — then a port-listener backstop; idempotent, sleep-free), `runtimeFacts` (**computed**: `kill -0` per pid file, `isListening` per port, plus `last-error.json`). |

State lives at `LANES_ROOT/.state/lane<slot>/{run,logs}/`, **outside** the
worktree: `lane reset` runs `git clean -fd`, which would sweep pid files mid-flight.

**Adopt-after-restart costs no code.** Pid files are on disk, detached processes
keep running, and `runtimeFacts` recomputes on read. That is the payoff of making
up/down computed rather than stored.

### Routes (`server/routes/lanes.js`)

```
POST /api/lanes/:id/up          { build? }   202 → background → broadcastLane
POST /api/lanes/:id/down        { mcp? }     200
GET  /api/lanes/:id/runtime                  200
POST /api/lanes/:id/hook/:name  { args? }    202
GET  /api/lanes/:id/logs/:svc   ?tail=N      200
```

All behind `sameOriginGuard` and the existing `withLaneLock`. `GET /runtime`
follows the contract of `GET /:id/git`: a lane with no profile returns
`{available:false}` with HTTP 200 — a normal state, not a fault. It probes ports
and stats pid files, which is why it is its own endpoint rather than part of the
polled `GET /api/lanes`.

`:name` and `:svc` come from allowlists, never from the request; log paths are
`realpath`-confined to `LOG_DIR`; `args` is an array of strings passed straight to
argv, never joined.

### Errors

| Condition | Code | Behaviour |
|---|---|---|
| No `.ccam/profile/` | `ENOPROFILE` | 400, naming both paths searched |
| Unknown hook | `ENOHOOK` | 400 |
| Hook exits non-zero | — | `lane_hook_output` + `last-error.json`; reflected by `/runtime` |
| Every candidate port busy | `EPORTBUSY` | names the occupying pid |
| `health` fails | `EUNHEALTHY` | **leaves the processes running** — killing them destroys the evidence — and points at the log |
| Slot pool exhausted | `ESLOTS` | 409 |
| Name outside an allowlist | — | 400, nothing spawned |

## Verification

`npm run test:server` (required) and `npm run test:client` (review the snapshot
diff before regenerating). A fixture repo with a three-line profile: `boot.sh`
starts `python3 -m http.server $FE_PORT` through `harness_spawn`, `health.sh` curls
it with retries.

Covered:

- **Real lifecycle** — `up` → `/runtime` healthy with the port listening → simulate
  a dashboard restart (rebuild the module) → still healthy, not rebooted → `down` →
  port free, pid files gone.
- **Slots** — nine allocations yield 1..9; releasing 4 makes the next allocation 4;
  concurrent allocations through `withLaneLock` never collide.
- **Port step-aside** — occupy the preferred port, assert `+100` is chosen and
  recorded in `ports`.
- **Profile parsing** — missing keys fall back to defaults; no profile returns
  `null` without throwing; a value containing `$(id)` stays literal and is **not**
  executed.
- **Guards** — `PATCH /api/lanes/:id` ignores `slot`/`ports`; a hook name outside
  the allowlist returns 400 and spawns nothing.
- **Env** — with `GIT_DIR` set on the parent, the hook does not see it.

Manual: create a lane on ccam-lanes itself, write a three-line profile,
`ccam lane up`, open the port, restart the server, confirm the stack survived.

## Out of scope

`.env` seeding and databases (A2). Detection and scaffolding (A3). Per-feature
state, proof gallery, cross-lane locks, the `ship-feature` skill, integrations
(subsystems B–F).

Container isolation is a separate design, not a later phase: hooks and MCP servers
would have to run *inside* the container, so the `cwd` a hook reports becomes a
container path and no longer matches the lane's host `cwd` — breaking
`resolveLaneByCwd`, which is what binds a session to a lane at all.
