# Daily status board The status board is the operator's live view of the day: what is running, what is waiting on the operator, what closed. The operator keeps the workspace **Status** page open (second in the nav, after Home) and reads it instead of asking. A stale or wrong board is worse than none, because the operator trusts it. ## Where it lives Each PA instance has its own board at `agents//workspace/status-board.json` in the operator repo. The Status page shows the running PA's board; `?agent=` shows another instance's. The PA name resolves the way the workspace resolves it everywhere else (`paName` in preferences, else the single agent folder holding `next-session.md`). Every board reader and writer (the page's read and Dismiss, every `pa status` verb, `pa dispatch` and `pa board check`) turns the name into the board's path through one resolver: the name, whether it comes from `?agent=`, `--agent` or preferences, must be an agent folder name (lowercase letters, digits and hyphens), the workspace folder must really be `agents//workspace/` under the repo root (no symlink on the way), and the board file must lie inside it. Anything else is refused before a file is read or written: the page's routes answer 400, the CLI exits 1. A missing folder or board keeps its usual answer (the page shows no board yet; `pa status set` creates the folders, only inside that fence). ## The update rule The PA updates the board, through the CLI, at every one of these moments, in the same turn as the event: 1. **Every dispatch.** `pa dispatch open` adds the item as `running`, holding the dispatch id in `ids`, in the same call that writes the spawn-log entry; `pa dispatch stage` refreshes it and `pa dispatch close` moves it to `done`. Patch its `where` (local, a lane host, cloud) with `pa status patch --id ` when it differs. 2. **Every return.** The item moves on: `review`, `blocked`, `done`, or back to `queued` for the next stage, with a one-line `note` on the outcome. 3. **Every status tick.** When the PA checks on work in flight (a lane poll, a CI read, a scheduled tick), the board's `updatedAt` and the touched rows are refreshed even if nothing changed state, so the freshness pill tells the truth. 4. **Every operator ruling.** A question the operator answers leaves the on-me list (`--on-me --remove`), and whatever the ruling unblocks changes status in the same write. A new question for the operator goes onto the on-me list the moment it is asked. **At session boot the board is reset with the day's plan.** After the boot reads (see `operator-interface/session-boot-and-end.md`), the PA writes a fresh board with `pa status set`: the headline for the day, one group per workstream in priority order, every item in flight or planned, the open on-me questions, and an empty `done` list. ## The write path The PA never hand-edits the JSON. The CLI reads the clock, validates against the schema and writes atomically (temp file, then rename), so a bad write never lands and the page never reads a half-written file. Every writer (the `pa status` verbs, `pa dispatch` and the page's Dismiss) reads, changes and writes the board inside one lock, `status-board.json.lock` beside it, so two writers never lose each other's change; a write that cannot get the lock within a few seconds writes nothing and says so. A lock left by a writer on the same host counts as stale only when that writer's process is gone; a live writer is never broken, however long it holds. A long hold is made visible instead: a writer refused by the lock names the holder's pid and the lock's age, and `pa board check` warns once a lock held by a live writer on this host is more than ten minutes old, naming the manual clear, `rm` of the lock file after checking that pid is not a board writer; nothing clears it automatically. A lock from another host, or one with no readable owner, counts as stale after ten seconds. A stale lock is removed only under a short break mutex, `status-board.json.lock.break`, and only while it is still the lock judged stale, so recovering it never lets two writers in. A crash or a kill can leave the lock file behind: the next writer recovers it within its wait, and nothing is lost, because the board itself is only ever replaced whole. Neither file is ever committed. An option's value never starts with `--`, in the separate form or the `--flag=value` form, and `--started`, `--estimate` and `--ended` take an ISO 8601 date-time with a zone on a real calendar date, such as `2030-01-15T09:30:00Z` (`2030-02-31T09:30:00Z` is refused). | Verb | Use | |---|---| | `pa status set [--file ]` | Replace the whole board (the boot reset, or a reorder of priorities). Reads stdin when `--file` is absent. | | `pa status patch` | Merge one item (`--id` or `--match "