docs: fix Task 12 Round 1 accuracy findings

- Fix POST /api/run param: change 'prompt' to 'initialPrompt' (Finding 1)
- Fix POST /api/run response shape: show actual fields from publicRun() (Finding 2)
- Delete stale 'Running and releasing lanes' section with old POST /api/lanes/:id/start (Finding 3)
- Delete stale POST /api/lanes/:id/message section — endpoint now returns 400 EUNSUPPORTED (Finding 4)

All changes verified against actual code:
- server/routes/run.js:285 uses body.initialPrompt
- server/lib/pty-run.js:144-156 publicRun() returns {id, laneId, status, cwd, model, ...}
- server/routes/lanes.js:1134 message action returns 400 error
This commit is contained in:
2026-08-12 15:48:10 +07:00
parent 31af7aefbf
commit 9c3331c843
2 changed files with 4 additions and 32 deletions
+2 -2
View File
@@ -1480,12 +1480,12 @@ GET /api/run/cwds Suggested cwds (dashboard, home, recent)
GET /api/run/history?limit=&laneId= Persisted run history; laneId narrows to one lane's runs GET /api/run/history?limit=&laneId= Persisted run history; laneId narrows to one lane's runs
GET /api/run/files?cwd=&q= Fuzzy file search inside cwd for the @-file autocomplete GET /api/run/files?cwd=&q= Fuzzy file search inside cwd for the @-file autocomplete
(skips node_modules, .git, dist, build, .next, .cache, coverage, vendor) (skips node_modules, .git, dist, build, .next, .cache, coverage, vendor)
POST /api/run Start/attach run — Body: { laneId, prompt?, ... } POST /api/run Start/attach run — Body: { laneId, initialPrompt?, ... }
GET /api/run/:id Run handle (returns live run state) GET /api/run/:id Run handle (returns live run state)
DELETE /api/run/:id Kill (SIGTERM → SIGKILL after 5 s) DELETE /api/run/:id Kill (SIGTERM → SIGKILL after 5 s)
``` ```
**`POST /api/run` (start/attach):** Requires `laneId` (the lane this run belongs to). Creates or attaches an existing tmux session named `ccam-lane-<id>` in the lane's working directory. Optionally accepts `prompt` to immediately type/send into the session (if empty or omitted, the session is created/attached with no initial input). Returns `{ runId, tmuxSessionName, cwd, ... }`. The dashboard self-heals a lane's `run_id`/`status` on every read if the tmux session has been killed externally. **`POST /api/run` (start/attach):** Requires `laneId` (the lane this run belongs to). Creates or attaches an existing tmux session named `ccam-lane-<id>` in the lane's working directory. Optionally accepts `initialPrompt` to immediately type/send into the session (if empty or omitted, the session is created/attached with no initial input). Returns `{ id, laneId, status, cwd, model, permissionMode, effort, resumeSessionId, sessionId, startedAt, promptPreview }` where `id` is the tmux session name. The dashboard self-heals a lane's `run_id`/`status` on every read if the tmux session has been killed externally.
**PTY streaming:** Frames from the tmux pane are streamed to the client over `/ws-pty/:runId` as binary WebSocket frames (not JSON). The Workspace page's TerminalView component feeds these frames to xterm.js for live rendering. Simultaneously, `ccam lanes shell` can attach the same session via a real local terminal, staying in sync with the browser view. **PTY streaming:** Frames from the tmux pane are streamed to the client over `/ws-pty/:runId` as binary WebSocket frames (not JSON). The Workspace page's TerminalView component feeds these frames to xterm.js for live rendering. Simultaneously, `ccam lanes shell` can attach the same session via a real local terminal, staying in sync with the browser view.
+2 -30
View File
@@ -375,24 +375,6 @@ three times, and the lane list is polled and re-broadcast on every hook-driven
tool call an agent makes. The browser fetches it per card instead, on mount and tool call an agent makes. The browser fetches it per card instead, on mount and
every 30 seconds, and a failed fetch is silent. every 30 seconds, and a failed fetch is silent.
### Running and releasing lanes
The Workspace page starts runs through `POST /api/lanes/:id/start`, which accepts the same `mode` and `effort` parameters as `POST /api/run`:
```bash
curl -X POST http://localhost:4820/api/lanes/5/start \
-H "Content-Type: application/json" \
-d '{"mode": "conversation", "effort": "medium"}'
```
**A finished run releases its lane.** When a spawned Claude Code process exits (normally, non-zero, killed, or never spawned), the lane's `run_id` is cleared, its `status` returns to `idle`, and the change is broadcast as a `lane_update` WebSocket message. This prevents lanes from sitting at `running` with a dead child.
Runs started through a lane are recorded with the lane's id and are history-queryable:
```bash
curl http://localhost:4820/api/run/history?laneId=5
```
## Viewing lanes ## Viewing lanes
List all lanes with their current status: List all lanes with their current status:
@@ -940,23 +922,13 @@ Start a tmux-backed run attached to the lane. The Workspace page's "Start Run" b
```bash ```bash
curl -X POST http://localhost:4820/api/run \ curl -X POST http://localhost:4820/api/run \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"laneId": 5, "prompt": "continue the work"}' -d '{"laneId": 5, "initialPrompt": "continue the work"}'
``` ```
The `prompt` field is optional — if omitted, the tmux session is created/attached with no initial input, and you type into the terminal directly. Returns `{ runId, tmuxSessionName, cwd, ... }`. The same tmux session persists across attach/detach cycles, so you can switch between the browser Workspace and `ccam lanes shell` seamlessly. 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 `ccam lanes shell` seamlessly.
**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>`. **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>`.
### message
Send input to a running session. The lane must have a live `run_id` (active session). The `needs_action` flag clears automatically when the message is delivered.
```bash
curl -X POST http://localhost:4820/api/lanes/5/message \
-H "Content-Type: application/json" \
-d '{"text": "approved, proceed"}'
```
### stop ### stop
Terminate the running session. If the lane has no live run, this is a no-op (no error). Terminate the running session. If the lane has no live run, this is a no-op (no error).