# Command HQ — design record Spec conversation 2026-08-18, owner + agent, back and forth. This is the write-up asked for partway through it, kept current as answers landed. **Status:** data model, the full REST API including both creation paths (web and `POST /commanders/new`), built and mounted 2026-08-18 (`bunx tsgo` clean, suite at its 7 pre-existing baseline failures — none of them this feature's). `bun db:push` and a restart of `officer` have both since run against the dev machine, so the backend is live. A member still needs `confineUserTree` re-run once if their account predates that — see "A member could not reach it" under "Working directory". **Web frontend v1 built 2026-08-18**, same session: `/command-hq` and `/command-hq/:sessionId`, three panels per "Layout, v1" below (`command-hq-categories`, `command-hq-grid`, `command-hq-detail`) under `officerdev/src/apps/CommandHQ/`, registered in `AppRegistry.tsx`, a `CORE_DOCK_ITEMS` tile, and a `usePageTitle` rule. **Now exercised against a running server** — a real commander created, categorised, armed as a watcher and observed running, its auto-generated name traced back to the actual process on this machine (see "Auto-naming" and the `>/dev/null` finding below). The composer creates a commander the same way `/chat` always has (an ordinary turn with `context: 'command-hq'`); once the harness reports a transcript id the URL is replaced onto it, and if a category was selected when composing, a `PATCH` sets it client-side — `fileAsCommander` itself always files uncategorised, the same race `POST /commanders/new` resolves server-side for mobile, resolved here the client-side equivalent. Rename, category, disarm and delete all go through Command HQ's own routes, never `/chat`'s — the two are scoped to different directories. Delete asks for confirmation inline (grid card and detail bar both), same shape as `/chat`'s own session-row delete. Tag UI is still deliberately absent, per "Tags — infrastructure now, UI not specified" below. The mobile side is further along on live exercise — `apps/commandhq` exists and typechecks against this router (see `COMMS/command-hq/mobile.md`) — and as of this revision has what it asked for to create a commander, though it has not yet been exercised against a running server on either side either. Every claim in this file is checked against the code, not aspirational — see "API reference" for what a client can call today. ## API reference — build against this Base path `/command-hq`, `core` permission (every signed-in account, no grant to hold), every query scoped to the caller's own `user_id` regardless. Router: `src/servers/api/command-hq/router.ts` — read it directly for exact request/response shapes; the table below is the map, not the full contract. | Method | Path | Body | Notes | | ------ | ------------------------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/categories` | — | `{ categories: [{id,name,createdAt}] }` | | POST | `/categories` | `{name}` | 409 on a duplicate name for this user | | PATCH | `/categories/:id` | `{name}` | rename | | DELETE | `/categories/:id` | — | uncategorises its commanders, does not delete them | | GET | `/tags` | — | schema exists; no UI planned for v1 | | POST | `/tags` | `{name}` | | | DELETE | `/tags/:id` | — | | | GET | `/commanders[?category=\|none]` | — | omitted = all, `none` = uncategorised bucket. See below | | POST | `/commanders/new` | `{prompt, displayText?, categoryId?}` | creates a commander; `prompt` required. `displayText ?? prompt` titles it, same precedence as the websocket. `-> {sessionId, cwd}` — `sessionId` is Claude's real transcript id, not a placeholder | | GET | `/commanders/:sessionId` | — | Command HQ's own metadata only — NOT the transcript, see below | | GET | `/commanders/:sessionId/turns` | — | `{turns: [...]}` — the raw per-turn cost ledger, oldest first. What "cost over time" plots from | | GET | `/commanders/:sessionId/fires` | — | `{fires: [...]}` — every trigger, oldest first. The full history behind `watcherLastFiredAt` | | POST | `/commanders` | `{sessionId, categoryId?}` | files an EXISTING session; idempotent; 404 if the session isn't in the commanders directory. Not the creation path — see `/commanders/new` | | PATCH | `/commanders/:sessionId` | `{categoryId?, name?, watcherArmed?}` | `name` proxies to `renameClaudeSession`; `watcherArmed: false` disarms (arming has no route — needs a live task id) | | DELETE | `/commanders/:sessionId` | — | deletes the TRANSCRIPT (`/clear` chain and all) via `deleteClaudeSession`, then the row. Not reversible, and not the same thing `/purge` does — see "The `/chat` ↔ `/command-hq` relationship" below | | POST | `/purge` | — | sweeps rows whose transcript no longer resolves; returns `{removed}` | | POST | `/commanders/:sessionId/tags` | `{tagId}` | | | DELETE | `/commanders/:sessionId/tags/:tagId` | — | | **A commander's conversation is `GET /chat/sessions/:id`, unchanged.** This router deliberately does not duplicate it — `GET /commanders/:sessionId` returns Command HQ's own metadata: `{sessionId, categoryId, tagIds, running, watcherArmed, watcherArmedAt, watcherStoppedAt, watcherLastFiredAt, cost, createdAt}`. A client wanting the full picture calls both; a client wanting the raw cost series calls `.../turns` as well — `cost` here is only the summary (`{turnCount, inputTokens, outputTokens, totalUsd}`), not the list. **`GET /commanders` is the grid endpoint** and returns the richest per-card shape: every field `/chat/sessions` already returns per session (`id`, `title`, `cwd`, `createdAt`, `updatedAt`, `messageCount`, …) plus `categoryId`, `tagIds`, `running` (derived live from the same `task:started`/ `task:notification` fold `/chat`'s own background-job tray uses), the watcher-arming fields, and the same `cost` summary the detail route returns — one aggregate query per card, the same cost class `running` already accepts for this grid. This is the field to poll if a client wants to know "did my watcher die" without opening it, or "what has this one cost me so far" without a second request. **A row whose transcript is gone is silently absent from every response.** Never a tombstone, never a 404 with a special shape — it simply is not in the list. See "The /chat ↔ /command-hq relationship" below for why that is the design rather than an oversight. **Two creation paths, one underlying mechanism.** The web composer sends an ordinary `/chat` websocket turn in the commanders directory and never calls `POST /commanders/new` — the row is written server-side the moment a real transcript id exists. A client that cannot open that websocket with the right parameters — mobile — calls `/commanders/new` instead, which drives the identical spawn path (`startClaudeTurn` in `websocket.ts`, extracted so there is exactly one) with no live socket, and waits for the same transcript id before answering. `POST /commanders` (bare) is neither of these — it is the low-level upsert both paths ultimately rely on, not something a client calls to create anything new. See "How a commander is created". ## What it is A home for **commanders** — long-running background jobs (watchers) the owner wants to find again, organise, and check on. Deliberately separate from `/chat`: **no cross-pollination**. A commander is started from inside Command HQ, not from an existing `/chat` conversation, and a `/chat` conversation never becomes a commander after the fact. Worked example the owner gave: a watcher that polls Gmail via IMAP every 10–60 minutes, compiles what came in, and pushes a summary — so the owner can uninstall the Gmail app and stop getting a notification per email. Command HQ is where that watcher lives, is named, is categorised, and is checked on. ## Route, surface, placement - **`/command-hq`** — new dock item, new route, **core** (`kind: 'core'` in `permissions/registry.ts`, not `app`). Every account gets it; there is no grant to hold. Core still needs the registry entry — `assertPermissionTotality` refuses to boot on an unregistered router regardless of kind. - **Per-user, not shared.** Every table carries `user_id`; every query is scoped to the caller. Nothing about this is visible across accounts. The owner named a _possible_ future (a super-admin view of who is running what) — do not build toward it, it costs nothing later because `user_id` is already there. - Workspace/Panel framework, per the standing rule for every new dashboard route: ``, panels under `officerdev/src/apps/CommandHQ/`, a rule added to `usePageTitle.ts`. - **API-first.** `/command-hq` will also be a mobile app surface eventually — not this task's concern, but every capability must be a real HTTP endpoint, not something only the web panel can reach. ## Layout, v1 Two columns. - **Left: category list.** Simple for v1 — a flat list of the user's categories, click to select. Filtering and search on this list are explicitly deferred (see "Later"). - **Right: commander grid**, scoped to the selected category. One card per commander. - **Click a card → detail pane.** The right side splits to show it. What the detail pane contains beyond "the conversation" is deferred — see "Later". For v1 it can be as simple as the chat transcript. - **New commander** starts from inside Command HQ's own composer — not a repurposed `/chat` panel reached from elsewhere. Almost certainly `EmbeddableChat` (`officerdev/src/apps/Chat/EmbeddableChat/`), which already exists as a chat surface embeddable outside the `/chat` screen. ## How a commander is created Resolved and **built, both paths** — there is no separate "file this into Command HQ" step on either one. Starting a new commander **is** the creation flow. **Web:** 1. The composer sends an ordinary `/chat` websocket turn with `context: 'command-hq'`. 2. `resolveChatCwd` (`websocket.ts`) reads that context and resolves `getCommandersDir(email)` itself — `msg.cwd` is never consulted on this branch. The client does not choose, or even need to know, where commanders live. 3. The moment the session has a real transcript id, `createMessageHandler` writes the `command_hq_sessions` row — the same `session:claude`-then-`result` seed `chat_session_models`' `record()` already waits on, with a sibling closure (`fileAsCommander`) hung off the same two triggers, gated on a `commandHq` flag threaded in from `msg.context === 'command-hq'` at the call site. **Mobile needed a different door.** `COMMS/command-hq/mobile.md` — read by the platform side 2026-08-18, after the mobile client had already been built against the router — found the web mechanism does not transfer: mobile sends chat turns with its own parameter set, so a context flag would have to be carried correctly by two independent clients, and a client that gets it wrong silently creates an ordinary `/chat` conversation in the wrong directory rather than failing loudly. Decided with the owner, and now built: ``` POST /command-hq/commanders/new body: { prompt: string, displayText?: string, categoryId?: number | null } -> { sessionId, cwd } ``` `prompt` is required — confirmed with the owner 2026-08-18. The actual usage pattern it needs to support: a commander often starts as an ordinary back-and-forth (figuring out the terms of the job with the agent) long before a background job is ever armed via the existing dialog — sometimes the first message really is just "we've already discussed this, do it." Either way there is always a real first message, the same as any conversation; there is no "empty commander" case to design around. **`displayText` was missing from the first version of this route, and the mobile side caught it** before it was exercised against a real server. A commander created to become a background job sends the FULL `buildBackgroundJobPrompt` mechanics as `prompt` — a page of preamble, the owner's actual sentence only at the end — and `command_hq_sessions` has no name column, so the title comes from `session.meta.title = (displayText ?? prompt).slice(0, 100)`, exactly the precedence the websocket path already uses (both clients already send `displayText` there — `sendWithHiddenPrefix` on web, `useSessionView.ts` on mobile). Without it, every commander created through this endpoint would have titled itself with the mechanics text, and the grid would have been a column of identical, unreadable cards. Fixed same session, before anyone had run it for real. **How it actually gets the id.** Claude assigns a transcript id only once a turn has run far enough to report `system.init` — there is no way to reserve one in advance. So the endpoint genuinely starts the turn: `startClaudeTurn` (`websocket.ts`), the turn-starting half of `handleClaudeCodeChat` extracted so both the websocket path and this endpoint drive ONE spawn function rather than two that drift, called with `ws: null`. It resolves as soon as the harness's `session:claude` arrives — not once the whole turn finishes — via an `onOutcome` callback that mirrors what a live socket would already have been told (a refusal reason, a spawn failure, or the transcript id), so an HTTP caller gets a real answer instead of a generic timeout. The turn then keeps streaming exactly like any other session; the endpoint's job ends the moment there is something real for the client to attach to. **The category race, and why it resolves deterministically anyway.** `fileAsCommander` (the web path's same hook, which this endpoint's turn ALSO passes through since `context: 'command-hq'` is set either way) always files with no category — it has no way to know one was requested. So the endpoint does its own `createCommandHqSession` (idempotent, upsert-on-conflict-do-nothing — safe whichever of the two insert attempts actually lands first) followed by an unconditional `setCommandHqSessionCategory` UPDATE. The UPDATE always runs last and always wins, so the category the client asked for is what's left standing regardless of ordering. No name is stored at creation, on either path — see "Naming", next. ## Naming — resolved, and it changes the schema **`/chat` never persists a title to Postgres.** `renameClaudeSession` (`claude-sessions.ts:646`) appends a `summary` entry straight into the transcript's own JSONL — Claude's own on-disk format is the title's only home. An unrenamed session's title is the first prompt, truncated, computed on the fly. There is no title column anywhere in Postgres for a `/chat` session, ever. Confirmed with the owner: **`command_hq_sessions` carries no `name` column.** The grid reads a commander's title live, the exact same way `/chat`'s list already does. Renaming a commander **is** `renameClaudeSession` — the same function, same route, same file on disk — not a second mechanism that could disagree with the first. One title, one place it can live, zero drift possible by construction. ## Data model Tables prefixed `command_hq_` per the house rule (`purge` finds a feature's tables by prefix; this one keeps the platform's naming convention even though it lives in core, a deliberate choice made explicit rather than an accident of copying a plugin schema). ### `command_hq_sessions` One row per commander. | column | notes | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | owner of the row, always the same account that owns the session | | `session_id` | **Claude's transcript uuid**, not Officer's `sessionId` — the same id `chat_session_models` keys on, for the same reason: everything else that joins to a session (models, events) uses this id | | `category_id` | FK to `command_hq_categories`, nullable — one category per commander (see below) | | `watcher_armed` | should the platform keep re-arming this watcher on every fire — see "The watcher loop" | | `watcher_task_id` | the currently-tracked watcher task, nullable | | `watcher_armed_at` | since when the CURRENT run has been going; set only on the false→true transition, untouched by re-arms | | `watcher_stopped_at` | when the current run ended; set on disarm, cleared on the next arm — paired with `watcher_armed_at` | | `created_at` | | No `name` column (see "Naming"). No `status` column, deliberately: liveness is **derived**, the same way the background-job tray already derives it — fold `chat_session_events` for the session, `task:started` minus `task:notification` (`collectRunningTasks` in `websocket.ts` is the existing implementation of exactly this fold; reuse it, do not reinvent it). A stored status would be a second source of truth that goes stale precisely in the case this feature is used for (see "Later" — silent death on sidecar restart) and nothing would ever correct it. **No `watcher_last_fired_at` either, deliberately removed** — see `command_hq_watcher_fires` below; the owner's call, once cost tracking made clear that a single overwritten timestamp was losing information a real table should hold instead. ### `command_hq_watcher_fires` — one row per trigger Added when cost tracking surfaced a real gap: the ORIGINAL design cached "last fired" as a single column on the commander row, which meant every new fire destroyed the previous one's timestamp. Fine for "when did it last fire", useless for "how many times, and what did each firing cost" — which is exactly what the owner asked for. So this became a real table instead of a column, and the commander row lost its cache entirely (the owner's call: derive `MAX(fired_at)` at read time rather than keep a copy that could only ever describe the same table this row also has to insert into). | column | notes | | ---------------- | ------------------------------------------ | | `session_row_id` | FK to `command_hq_sessions.id` | | `task_id` | which watcher task fired | | `fired_at` | the only timestamp this row exists to hold | ### `command_hq_turns` — the cost ledger One row per completed turn (every `result` message a commander's session produces, not only the ones that follow a fire — the setup conversation before a watcher is ever armed costs something too). | column | notes | | ---------------- | ------------------------------------------------------------------------------------------ | | `session_row_id` | FK to `command_hq_sessions.id` | | `fire_id` | FK to `command_hq_watcher_fires.id`, nullable — null for turns before the first-ever arm | | `input_tokens` | | | `output_tokens` | | | `total_usd` | `doublePrecision` — a monitoring number, not a billing ledger; see the schema file for why | | `created_at` | | **Nothing is pre-summed.** Running total, cost over time, cost per trigger and turn count are all queries over this table — `getCommandHqCostSummary` (one `SUM`/`COUNT`), `listCommandHqTurns` (the raw series a client plots), grouped by `fire_id` for per-trigger. Turn count in particular needed no column at all: `COUNT(*)` on this table already answers it, the same "derive it" call the owner made for `watcher_armed_at` and the dropped `watcher_last_fired_at` — raised explicitly when the schema was being designed, not assumed. ### `command_hq_categories` User-created, not a fixed enum. One category per commander — a plain FK column on `command_hq_sessions`, not a join table. | column | notes | | ------------ | ----- | | `user_id` | | | `name` | | | `created_at` | | ### Tags — infrastructure now, UI not specified Resolved: build the tag infrastructure alongside categories, not deferred. Many-to-many, unlike categories: - `command_hq_tags` — `user_id`, `name`, `created_at`. - `command_hq_session_tags` — join table, `(session_row_id, tag_id)`. Nothing in the spec describes a tag picker or tag filter chips for v1's UI (only the category list was described). Build the schema; treat the UI as open until asked for. ## Working directory — every commander shares one directory per user Resolved, and it came with an explicit reversal worth keeping: the owner's first instinct was a directory **per commander**, each with its own isolated cwd. Retracted on the spot — creating a fresh directory at the moment a commander starts races the harness's own spawn (the cwd has to exist before or exactly when the first turn fires, and centralising that creation moment is exactly the kind of timing hazard Claude Code's own directory-per-project convention was not designed to be driven by). Simpler and safer: no per-commander directory at all. **`DATA_PATH//commanders/`** — one fixed directory, shared by every commander a user has. Every commander's `cwd` is this same path. This is precedented, not new: `getEmailAccountsDir` in `data-path.ts` already follows the identical shape (`join(DATA_PATH, ownerEmail, 'email_accounts')`) for a different feature's per-user directory. A `getCommandersDir(email)` alongside it is the natural addition. Needs to exist once, idempotently (`mkdirSync(..., { recursive: true })`, the pattern already used in `websocket.ts`), created lazily before the first commander's first turn — never per-commander, which is the exact race that was rejected. **This is a deliberate departure from ordinary `/chat` cwd resolution for the owner.** A normal owner chat runs in `getOwnerHomeDir` — the owner's real login home — while `getHomeDir` (`DATA_PATH//home`) is otherwise reserved for non-owner accounts and the pipeline executor. Commanders use the managed, `DATA_PATH`-rooted directory **even for the owner**, which is exactly what keeps them out of the owner's own project transcripts and out of `/chat`'s history for the same underlying reason categories exist: a commander is not a project conversation, and should not be filed as if it were. ### A member could not reach it, and this is now fixed — but only going forward Found while wiring the creation flow, not guessed at: `getCommandersDir` is a sibling of `home`, and `confineUserTree` (`os-user.ts`) confines **every** sibling of `home` to 700, owned by the SERVICE user, "unreachable even by name" — correct for platform-written directories like `attachments/`, and exactly wrong here, because a member's commander turn runs as the MEMBER's own Linux account via `setpriv`. This is the identical shape of bug `resolveChatCwd`'s own comment already tells a story about (`general_chat_sessions`, abandoned for the same reason) — a working directory the turn cannot `cd` into, surfacing as an agent that fails on its own first command. **Fixed in `confineUserTree` itself**, not by abandoning the directory: it now chowns `commanders/` to the member exactly as it already chowns `home`, and excludes it from the loop that confines every other sibling. No ACL, unlike `home` — the file browser needs one because it reads a member's home from inside the platform process as the service user; Command HQ has no equivalent, since it reads a member's commander transcripts through `listTranscriptsAs`, the same as-the-member read `/chat` already uses for anyone's transcripts. Plain ownership is the whole requirement, same as `~/.claude/projects` itself. **The gap this leaves:** `confineUserTree` runs at provisioning time. An account provisioned _before_ this fix landed will not have `commanders/` chowned until it is provisioned again — the existing admin reprovision action (`provision-linux-route.ts` / `manage-users.ts`) already re-runs `confineUserTree` idempotently, so no new machinery was needed, but a member who existed before tonight needs that one manual re-run before their first commander turn will actually spawn. Worth a release note, not a code change. ## The `/chat` ↔ `/command-hq` relationship **One predicate, opposite sign, both directions read from the same join.** - `/chat`'s session lists (`listClaudeSessions`, `listAllClaudeSessions`, and the ChatHistory app) **exclude** any session with a `command_hq_sessions` row. - `/command-hq`'s card grid **includes only** sessions with a row, joined against the live session list. **The source of truth is always the live session list** (transcripts on disk, exactly what `/chat` reads today), never the table. `command_hq_sessions` is a filter and a set of annotations on top of that list, not an independent record of what sessions exist. Consequences the owner confirmed explicitly: - A row whose transcript is gone (deleted, home reset, whatever) is simply **absent from both lists** — it is not rendered as a tombstone, and nothing needs to notice. It is "someone else's problem" by design; the owner is not developing for people who will be surprised by this. - A **purge button** can sweep `command_hq_sessions` for rows whose `session_id` no longer resolves to a live session and delete them. Housekeeping only — correctness never depended on it running. - A session **never moves the other direction**. There is no unfile path, and none is planned — a commander is a commander for life, and (given commanders live in their own cwd, never a `/chat` cwd) the two spaces never actually overlap. - **`DELETE /commanders/:sessionId`, added 2026-08-18, is not an unfile path — it is real deletion**, and deliberately does not conflict with the bullet above: the commander does not become a `/chat` session, it stops existing. `deleteClaudeSession` (the SAME function `DELETE /chat/sessions/:id` calls) removes the transcript — a `/clear` chain and all — and `deleteCommandHqSession` removes the row. Once the confirm step lands, this is not recoverable: there is no undo, no trash, and the row disappearing is a side effect of the transcript being gone, not the other way around. ## Built on, mostly unchanged Everything about _how a background job runs_ was out of scope for the original build — a place to browse, name and categorise the sessions the existing system produces. That held until real testing found the mechanism itself wanting; see "The watcher loop" below for what changed and why. Otherwise, unmodified: - The whole lifecycle: `run_in_background`/`Monitor`, `task:started`/`task:notification`, `chat_session_events` as the durable log, `collectRunningTasks` as the fold, the tray. - Stop/pause/restart routes under `/chat/tasks/:id`. - `renameClaudeSession` — Command HQ's rename action IS this, not a new one. - `officer-notify` — assume it works and is wired up separately; do not build a parallel notification path for this feature. ## The watcher loop — exit, act, drain, re-arm `COMMS/command-hq/watchers-what-broke.md` and `watcher-loop-proposal.md`, both 2026-08-18: the mobile side actually ran a watcher (poll `git ls-remote`, react to each push) through the dialog, and the mechanism broke in ways no amount of reading the code would have found — two watchers alive at once because a new one was armed before the old was reaped, a watcher firing on the agent's own push to the branch it was watching, "keep going" silently meaning the agent would never see a firing again because a background process reaches the model only when it EXITS. The owner's call, confirmed 2026-08-18: **implement the proposal as written, before the first real tests** — this governs the agent's behaviour generally, not only Command HQ, so it is not optional groundwork the way most of this document is. **The re-arm mechanism, settled 2026-08-18, after two false starts recorded here rather than quietly fixed:** 1. First instinct: the PLATFORM silently respawns the watch command when it fires, no agent turn involved. Wrong — the SDK only ever notifies the agent about a process it is itself tracking via `Monitor`. A platform-side respawn exists outside that tracking, so it would fire once, work, and then go dark forever — the agent is never told about the second fire. Not a cost tradeoff, a dead end. 2. Second instinct: keep the agent in the loop, but have the PLATFORM drive it — detect the acting turn's `result` and send a synthetic follow-up message telling the agent to re-arm. Technically correct, but costs a real extra turn every single cycle, and the owner pushed back on that cost before it was built: an actual multi-hour, real-world watcher (the mobile side's own, on this repo, this session) had already been running with the agent re-arming ITSELF, same turn, for hours — zero failures. That is hard evidence to override with a hypothetical reliability argument. 3. **What is actually built:** the agent re-arms itself, as the LAST action of the SAME turn that handles the notification — no separate turn, no platform-side spawn. The platform's role is narrower than either false start: it only WATCHES for this happening and can say so if it doesn't (see "Built" below) — it does not drive the re-arm and does not respawn anything itself. **The evidence for step 3 is stronger than either side's first write-up said, and it is worth recording precisely rather than as "ran fine for a while" (`COMMS/command-hq/mobile-4.md`).** Both notes originally described the mobile side's own same-turn watcher as having run "for hours, this session." Andre's own count, checked directly: **at least 10–15 runs, spanning before and after the current mechanism existed, zero failures.** That is a different class of claim than "it worked tonight" — it is evidence against _revisiting_ the decision, not just evidence for having made it. Worth stating why that distinction matters: same-turn self-re-arm looks fragile on paper (it depends on the model correctly doing one specific thing as the last step of every turn, unsupervised, forever), so the instinct on reading the design cold is to add a safety net — a supervisor, a timeout, a platform-side check that re-arm actually happened. The record here is that a dozen-plus real runs across two different surrounding mechanisms never once needed one. It is also why the platform's role stays _noticing_ (`watcherArmed && !running`, "Deliberately not built" below) rather than _driving_: noticing is the right amount of machinery for a failure with zero observed instances, and building more than that would be solving a problem the evidence says does not occur. **Built:** - **A third dialog option**, `FireBehavior = 'stop' | 'handoff' | 'keep-going'` (was a `stopOnFire` boolean). `handoff` — "Exit and hand back to the agent, then re-arm" — carries the contract (`handoffContract` in `background-job-prompt.ts`) verbatim: _"When the condition fires you will be handed back, with the change. Do the work — and before you end this turn, start the SAME watch again yourself, exactly as you did the first time: same condition, same command. That is the whole loop, every time: act, then re-arm, in the one turn."_ The closing "IF IT EXITS" section is rewritten for `handoff` too, so it does not contradict rule 7 by telling the model an exit means stay-stopped. - **`isCommander`, gating the promise to where it can be kept.** The proposal frames this entirely in terms of commanders — "a commander already has a row," arming state's only home — and outside one there is nowhere to persist "this should keep re-arming itself," so nothing would fulfil the promise. Rather than make it anyway, `BackgroundJobDialog` only offers `handoff` when `isCommander` is true, defaulting to it there and to the pre-existing `stop` everywhere else. **Not yet wired to `true` anywhere** — Command HQ's own composer, which would set it, does not exist yet (web) or does not use this dialog (mobile has its own). Every existing `/chat` caller is unaffected: two options, `stop` default, exactly as before tonight. - **Stopped no longer reads as failed.** `watchers-what-broke.md` §5: a job Officer had just SIGTERM'd came back `status: 'failed'` (exit code 144) from the harness's own classification, which this codebase does not control. Fixed client-side, at the one place it can be fixed cheaply: `stopTask` in `BackgroundTaskTray.tsx` now also calls `markStopRequested(taskId)` (`background-job-origin.ts`), and `useChat.ts`'s `task:notification` handler overrides the displayed status to `stopped` when a stop was just requested for that id, regardless of what the harness reported. Known gap: this is in-memory client state, so it does not survive a page refresh between clicking Stop and the notification arriving — an acceptable, narrow window, not attempted to be closed tonight. - **`command_hq_sessions` gained `watcherArmed`, `watcherTaskId`, `watcherArmedAt`, `watcherStoppedAt`.** Unlike `running`, `watcherArmed` is allowed to be stored — it is the owner's INTENT ("keep re-arming this"), not a live process fact the platform is reporting on, so nothing external can silently falsify it the way a sidecar restart falsifies `running`. `watcherTaskId` is closer to that rejected shape and accepts the same known gap `running` already lives with — see the schema file's docstring. `watcherArmedAt`/`watcherStoppedAt` are the current-run boundary pair, added a turn later during the cost-tracking pass once "since when has this been going" was a real question — see "Data model" above. There is no `watcherLastFiredAt` column any more: that fact moved into `command_hq_watcher_fires` (its own table, one row per trigger) once cost tracking needed per-fire attribution, not a single overwritten timestamp. `armCommandHqWatcher` / `recordCommandHqWatcherFired` / `disarmCommandHqWatcher` / `recordCommandHqTurn` in `queries.ts`; exposed read-only on `GET /commanders` and `GET /commanders/:sessionId` (`watcherLastFiredAt` survives as a name in the JSON response — it is just computed there, `MAX(fired_at)`, not read off a column), and `PATCH /commanders/:sessionId` accepts `{watcherArmed: false}` to disarm (arming itself has no route — it needs a live task id, which only a running turn has). - **`armWatcher` threaded end-to-end, client to server.** `BackgroundJobDialog` computes it (`watching && onFire === 'handoff'`) → `sendWithHiddenPrefix` → `QueuedPrompt.armWatcher` → `sendPrompt`'s new last parameter → the chat websocket message → `ClientMessage`'s `'chat'` variant → `startClaudeTurn`'s `msg.armWatcher`, which sets `session.pendingArmWatcher = true` — on the SESSION object, not captured by `createMessageHandler`'s closure, because the dialog is routinely submitted turns after that closure was built (the session-scoped event subscription wires ONCE, on the session's first-ever turn) and a value captured then would never see a later arm. - **The noticing, in `createMessageHandler` (`websocket.ts`).** On `task:started`: if `pendingArmWatcher` is set, consume it (one-shot, the same arm/claim shape `background-job-origin.ts` already uses client-side for the identical problem) and call `armCommandHqWatcher` — this is what turns "some task started" into "this is the watcher" in the first place. If the commander is ALREADY armed instead, a new task starting is what the agent's own self-re-arm produces, so the tracked `watcherTaskId` is simply updated to it — the platform is not driving anything here, only keeping up with what the agent already did. On `task:notification`: if it matches the tracked `watcherTaskId` for an armed commander, record the fire — a new row in `command_hq_watcher_fires`, not a column write. Both read `getCommandHqSession` live rather than trusting any closure-local state, for the same reason as above. On `result`: every completed turn writes a row to `command_hq_turns`, attributed to the commander's most recent fire (`fire_id`, null before the first-ever arm) — see "Data model" for why nothing here is pre-summed. - **Known, accepted imprecision:** the "already armed → treat the next task:started as the re-arm" rule cannot tell a genuine self-re-arm apart from an unrelated background task the agent happens to start in the same commander conversation. A commander is one watcher by design, so this is a narrow gap rather than the common case, and not attempted to be closed tonight. Suggested order from the proposal, all four items now done: (1) prompt + dialog, (2) stopped-vs-died, (3) the re-arm mechanism itself — landed as agent-driven, same-turn, after two rejected designs recorded above — (4) arming state and the plumbing that watches for it. **Deliberately not built: the platform verifying re-arm happened.** Raised as a possible cheap addition — since the platform can already derive last-fired (`MAX(fired_at)` in `command_hq_watcher_fires`) and already computes `running` from the same fold `GET /commanders` uses for every card, a client could flag "fired N ago, nothing has run since" without any new mechanism, purely by reading what already exists. Not built tonight; noted here so it is not lost, not because it was rejected. **Auto-naming from the watcher's own description, added 2026-08-18 after the web frontend surfaced why it matters.** A fresh commander's title is whatever the first message was — the mechanics preamble, truncated, when that first message is a `handoff` background job. Expected, not a bug: that IS the first message, and Claude Code names sessions from it the same way it always has (see "Naming" above). But by the time the watcher's task actually STARTS, the harness has already given it a real description — `msg.description` on `task:started`, "Watch google.com reachability" for a ping watcher — and that reads far better than the preamble ever will. So the exact moment `pendingArmWatcher` is consumed (the FIRST arm, never a self-re-arm — see "known, accepted imprecision" above for why that distinction is already load-bearing here) now also calls `renameClaudeSession` with that description, resolving a fresh `ChatIdentity` via `resolveHomeDir` for the filesystem call. Best-effort, like everything else in this block: a failure is logged and does not touch `watcherArmed`. **Known gap, not closed:** the detail panel's title bar is fetched once on mount and does not live-refresh, so a commander open in the panel at the moment this fires keeps showing the old title until the next navigation or reload. The grid's cards do not have this problem — `GET /commanders` is already polled every 15s. Flagged rather than fixed; worth a `refetch()` hook if it turns out to matter in practice. **"(no output yet)" on that same google.com watcher, traced to the actual running process on this machine rather than guessed at.** The tray's live-log-tail (`BackgroundTaskTray` → `useTaskDetail` → `GET /chat/tasks/:id` → `loadBackgroundTask`/`tailFile`) is a general `/chat` feature Command HQ gets for free — nothing to build there, and it was already working correctly. The task's `.output` file was genuinely empty: the agent had written `timeout 8 ping -c 1 -W 5 google.com >/dev/null 2>&1`, silencing `ping`'s own output entirely and only ever `echo`ing on a FAILED ping — correct per "let me know if it goes down," but it means a healthy watcher shows nothing at all, indistinguishable at a glance from a stuck one. Fixed at the source rather than in the tray: `background-job-prompt.ts` gained an unconditional rule (every job, not only watchers — number 4, 5 or 8 depending on which rules already preceded it in that particular prompt) telling the agent not to discard a command's own output. The tray already shows whatever reaches the log file live; the gap was that jobs were routinely told, by habit rather than by this prompt, to send that output to `/dev/null`. **A real bug, caught by tracing rather than by the compiler, worth stating plainly.** When the cost-tracking schema changed `recordCommandHqWatcherFired`'s signature from `(userId, sessionId)` to `(sessionRowId, taskId)`, the ONE existing call site was not updated in the same pass — and `bunx tsgo` stayed clean, because `userId: number` and `transcriptId: string` still satisfy `sessionRowId: number, taskId: string` structurally. It would have written a fire row for a commander keyed on the wrong id entirely (the caller's OWN user id, not the row it belonged to). Found by re-reading every call site the schema change touched after the fact, not by any tool — worth remembering the next time a signature changes shape rather than just its types: a compiler that stays quiet is not the same as a diff that is correct. ## Later — explicitly deferred, not forgotten Raised during spec and set aside for a second version, in the owner's words: _"that's not... that's out of scope for tonight."_ - **Silent death is invisible.** A background job is a child of the agent sidecar process, not of Officer. `pm2 restart officer-claude-code` kills every running watcher with **no** `task:notification` ever emitted, so `collectRunningTasks` (started-minus-notified) reports it running until the 7-day event prune. For a watcher meant to run for months, this is the actual failure mode — a card that says "running" and has been dead since the last deploy. Deferred anyway, because tonight is development against a live server that gets restarted constantly; the target environment (a server nobody restarts) makes this rare in practice. When it is picked up: `task-restart.ts`'s `pidsHoldingFile` (`fuser` against the task's output file, run as the owning user) is the existing liveness probe used by the restart watcher — comparing "log says running" against "pid check says running" is what turns a false "running" into a third, honest state ("vanished"). Cost matters here: `fuser` is a subprocess spawn per task, so this is a detail-pane check or a batched sweep on load, never a per-card check on every render of the grid. - **No durable job record — REVISED.** True when written; no longer true for cost. The owner still does not care how many times a watcher fired or WHAT each firing found (the chat transcript remains the only record of content, and that is intentional), but does want per-turn token/dollar cost durably recorded — `command_hq_turns` and `command_hq_watcher_fires`, added same session. See "The watcher loop" and the data model section above. - **Cost-based limits — explicitly out of scope for tonight, said directly by the owner.** "If this agent reaches a certain cost in tokens, stop it, or compact the conversation and resend, or clear and resend." Not built, and deliberately not designed around either: the ledger this session added (`command_hq_turns`) is exactly the raw material a limit would need (`SUM` since a fire, or since armed), so nothing here forecloses it — but which action, at what threshold, and whether it is a per-commander setting or a global one, is all undecided. - **Detail pane contents beyond "the conversation".** The owner asked for logs, status, and transcript together in a split view; scoped down to "click a card, see its details" for v1, with the specifics (separate log tail vs transcript vs live status) left open. `/chat/sessions/:id` (transcript) and `/chat/tasks/:id` (log tail or subagent transcript) already cover the raw material. - **Filtering and search on the category list.** Named explicitly as v2 in the first message of the spec. - **Tag UI.** Schema is in scope for v1 (see above); a picker, filter chips, anything user-facing is not. - **Category management UI details** — delete behaviour (default: uncategorise the affected commanders rather than cascade-delete their rows, not explicitly confirmed), reordering, anything beyond create/list. - **Multi-account visibility for the owner** — "sometime for the next version we will want the super user to have visibility of who is running what." `user_id` on every table already makes this a query change, not a schema one. ## Resolved, previously open - **Creation flow** — resolved, see "How a commander is created". - **Naming / title storage** — resolved, see "Naming". - **Category cardinality** — resolved: one per commander, a column not a join table. Tags cover the many-per-commander case. - **`/clear` chains** — the owner's answer, plainly: nobody sane runs `/clear` on a commander, and this is not being built for the case where they do. A commander's `session_id` is one transcript; chain-splicing is not replicated. - **Working directory** — resolved, see "Working directory" above. Not something the owner had originally planned for; raised and settled within this same conversation. ## Still open Nothing blocking as of this revision. `POST /command-hq/commanders/new` is built — see "How a commander is created" — with `prompt` required, confirmed with the owner 2026-08-18. The web frontend v1 is built too (see the status line at the top). **Neither client has actually been clicked through against a running server yet** — that is the next real test, not a design question, and it is the thing most likely to turn up something this file gets wrong: the composer's redirect-on-real-id, the watcher-disarm button, the category-race PATCH, none of them have run once outside a typecheck.