release 2026.08.23.01

The commander creation flow rebuilt end to end, the delete path that actually removes one, /minesweeper, and docs:check. Schema change — command_hq_spawned is new and command_hq_sessions gains name, so bun db:push is a step. No dependency change; bun.lock is untouched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
usage limits are read live, and a cached reading belongs to one account
2026-08-23 01:56:03 +00:00 · 2026-08-23 01:54:05 +00:00 · 2026-08-23 01:44:06 +00:00 · 2026-08-23 01:22:44 +00:00 · 2026-08-23 02:02:38 +01:00 · 2026-08-23 00:54:32 +00:00
54 changed files with 2802 additions and 219 deletions
@@ -113,6 +113,19 @@ imported by their package name (`officerdev`, `hooks`, `state`, `types`, `helper
  building node-pty, or `officer-pty` cannot load its native module, restore the exact pin
  first. The source build also needs `build-essential` and `python3`.

+  **Bun itself is held at the 1.3 series, on purpose and temporarily.** 1.4.0 was published
+  2026-08-20; the owner asked on 2026-08-22 to stay on 1.3 for a few months until 1.4 has been
+  watched. Two places carry that number and they move together: `BUN_SERIES` in
+  `scripts/setup/machine-setup/lib/dev.sh`, which resolves the newest `1.3.x` from the npm registry
+  and passes it to the installer as a release tag, and `engines.bun` in `package.json`, which is
+  what `bun run doctor` reads. bun ignores `engines` (verified — an install declaring `1.9.x` ran
+  clean under 1.3.14), so that field is the declaration and doctor is the enforcement.
+
+  **Do not run `bun upgrade` on a machine running Officer.** It takes no version argument — latest
+  stable or `--canary`, nothing else — so it jumps straight past the pin and says nothing. That is
+  the whole reason `doctor` checks the running version at all; `machine-setup.sh --only 'JavaScript
+runtimes'` offers to pin a drifted machine back down. Lifting the hold is `todo/infra/`.
+
 - **Language**: TypeScript, strict. `bunx tsgo` is clean — keep it that way.
 - **Frontend**: React 19, React Router 7, React Query, Tailwind 4, shadcn/ui + custom components
 - **Backend**: Hono
@@ -194,7 +207,7 @@ ahead of everything, and it re-verifies the token itself so it covers routes tha
 - `permissions/registry.ts` — the single enumeration of what the platform can do, in five kinds:
  `core` (every account, not deniable), `app` (**the grantable surface**), `confined` (grantable, but
  only to an account that has a Linux user), `execution` and `admin` (owner only, and `execution` is
-  never grantable at any level). **18 entries as of 2026-08-22** — verified by `bun run docs:check`, which fails if this number drifts again: 5 core, 3 app, 3 confined, 3 execution, 4 admin. It said 27 for nine days.
+  never grantable at any level). **19 entries as of 2026-08-22** — verified by `bun run docs:check`, which fails if this number drifts again: 5 core, 3 app, 3 confined, 4 execution, 4 admin. It said 27 for nine days.
 - `permissions/authorize.ts` — resolves "may this account do this". Owner short-circuits first; every
  other answer is role grants plus core, with `execution`/`admin` stripped even if a row grants them,
  and `confined` stripped for an account with no `osUser`.
@@ -20,21 +20,21 @@ the owner's OS user and can never be granted. Indirection there really is accide

 ## Themes

-**88 open, 25 closed**, across 29 themes.
+**90 open, 25 closed**, across 29 themes.

 | Theme | Open | Closed |
-| ------------------------------------------------------------------------------------------ | ---- | ------ |
+| --- | --- | --- |
 | [Affordances](todo/affordances/) | 1 | 0 |
 | [Speaking into a session from the backend](todo/agent-delivery/) | 2 | 0 |
 | [Backburner](todo/backburner/) | 2 | 0 |
-| [Background jobs](todo/background-jobs/)                                                   | 2    | 0      |
+| [Background jobs](todo/background-jobs/) | 3 | 0 |
 | [Chat interface](todo/chat/) | 1 | 0 |
 | [Code editor](todo/code-editor/) | 1 | 0 |
 | [Components — the shared UI layer](todo/components/) | 1 | 0 |
 | [File watchers](todo/file-watchers/) | 1 | 0 |
 | [Fleet — one command across every server](todo/fleet/) | 5 | 2 |
 | [Headscale](todo/headscale/) | 0 | 5 |
-| [Infra (alpha)](todo/infra/)                                                               | 6    | 0      |
+| [Infra (alpha)](todo/infra/) | 7 | 0 |
 | [Known bugs](todo/known-bugs/) | 3 | 2 |
 | [Mobile apps](todo/mobile-apps/) | 3 | 0 |
 | [Multi-user](todo/multi-user/) | 16 | 5 |
@@ -63,6 +63,8 @@ the owner's OS user and can never be granted. Indirection there really is accide

 ## Newest ten

+- `2026-08-22` **'A commander picks the cheapest model that will do the job — for itself and for what it spawns'** — [background-jobs/a-commander-picks-the-cheapest-model-that-will](todo/background-jobs/a-commander-picks-the-cheapest-model-that-will.md)
+- `2026-08-22` **'Revisit the bun 1.3 pin once 1.4 has been watched for a while'** — [infra/revisit-the-bun-1-3-pin-once-1-4-has-been](todo/infra/revisit-the-bun-1-3-pin-once-1-4-has-been.md)
 - `2026-08-22` **A plugin's permission should be on for every role by default, off only on request** — [multi-user/a-plugin-s-permission-should-be-on-for-every](todo/multi-user/a-plugin-s-permission-should-be-on-for-every.md)
 - `2026-08-22` **A user's settings should export and import as a plain file** — [settings/a-user-s-settings-should-export-and-import-as](todo/settings/a-user-s-settings-should-export-and-import-as.md)
 - `2026-08-22` **The same for system settings, owned by the Super Admin** — [settings/the-same-for-system-settings-owned-by-the](todo/settings/the-same-for-system-settings-owned-by-the.md)
@@ -71,5 +73,3 @@ the owner's OS user and can never be granted. Indirection there really is accide
 - `2026-08-22` **Revamp the menus — spotlight, themes — toward an Omarchy-like shape** — [shell/revamp-the-menus-toward-an-omarchy-like-shape](todo/shell/revamp-the-menus-toward-an-omarchy-like-shape.md)
 - `2026-08-22` **Review officer-secret-store, built overnight and untested by the owner** — [waiting-on-owner/review-the-officer-secret-store-built-last](todo/waiting-on-owner/review-the-officer-secret-store-built-last.md)
 - `2026-08-21` **No way to see which affordances are reaching your agents, or to turn one off** — [affordances/no-way-to-see-which-affordances-are-reaching](todo/affordances/no-way-to-see-which-affordances-are-reaching.md)
- `2026-08-21` **Generalise it: deliver a turn to a named session, from anywhere in the backend** — [agent-delivery/generalise-it-deliver-a-turn-to-a-named](todo/agent-delivery/generalise-it-deliver-a-turn-to-a-named.md)
- `2026-08-21` **The cost of resuming grows with the transcript** — [agent-delivery/the-cost-of-resuming-grows-with-the-transcript](todo/agent-delivery/the-cost-of-resuming-grows-with-the-transcript.md)
@@ -0,0 +1,64 @@
+# 2026.08.23.01
+
+The commander creation flow, rebuilt end to end — named, given a directory, and started by a button that
+makes it interview you rather than waiting for a prompt somebody else wrote. Plus the delete path that
+actually removes one, `/minesweeper`, and `docs:check` guarding the documentation's checkable claims.
+
+**SCHEMA CHANGE.** `bun db:push` is a step. `command_hq_spawned` is new and `command_hq_sessions` gains
+`name`. Without the push, Command HQ fails on a missing column the first time it lists a commander.
+
+**No dependency change** — `bun.lock` is untouched across `deploy/2026.08.22.02..HEAD`. `package.json`
+moved only to add `engines.bun` and two scripts. **Do not run `bun install`.**
+
+## What is in it
+
+- **A commander is created, not configured.** Name it, choose its working directory, press Start. It reads
+  the directory, works out whether the job is already written down there, and either reads its
+  understanding back for confirmation or asks what it should be watching. The name is the brief — it is the
+  only thing the owner says before anything else, and it now reaches the model instead of only titling the
+  transcript.
+- **`command_hq_sessions.name`** — the platform owns the name. It was only ever in the transcript's summary
+  record, which the harness cannot write until the first turn ends, so the list showed the opening brief
+  while the header showed the real name.
+- **Deleting a commander removes it.** Four defects, each of which left something behind: the session kill
+  ran in the wrong process and always failed; the transcript was deleted while the harness was still
+  writing it, so it came straight back as an untitled chat; `chat_session_events` is keyed on officer's
+  session key while everything else uses the transcript id, so its rows were never matched; and the key was
+  resolved from an in-memory map that is empty for anything older than the process. The event rows carry
+  both ids, so they are asked when the maps cannot answer.
+- **`GET /chat/live?kind=`** — `agent` (the default), `commander`, or `all`, with `counts` always
+  describing the whole set. Defaulting to agents means a client that forgets cannot be handed a commander;
+  the web list asks for `all` explicitly.
+- **A dropped sidecar command says so.** `sendFire` did nothing when no sidecar was registered — no log, no
+  error — so answering a question during the reconnect window after a restart vanished and the card span
+  forever. Question answers and plan decisions now report it.
+- **`/minesweeper`** — a wine session streamed to the browser over RFB. The session is not running on
+  `officer-dev`, so the route renders its "not running" state with a Start button. That is expected.
+- **Usage limits are read live.** `limitsCache` was keyed on nothing, so switching Anthropic account showed
+  the previous account's percentages under the new name. The cache remains for the failure path only, keyed
+  per account.
+- **`bun docs:check`** compares documented claims against values derived at run time — the permission
+  count, the PM2 entry count, the generated platform skill. It found both claims it was written to check
+  already wrong. **Required before tagging a release.**
+- **Empty transcripts no longer list.** A file holding only harness metadata and no turns is not a
+  conversation; four had accumulated as "(untitled) · 0 msgs".
+- **Bun is held at the 1.3 series** — `engines.bun` and `BUN_SERIES` move together. Do not run
+  `bun upgrade` on a host.
+
+## Every host
+
+1. `git pull --ff-only`
+2. **`bun db:push`** — new this release
+3. `bun run plugins:update`
+4. `pm2 restart officer`
+
+`officer` only. Step 3 restarts each plugin's own sidecar; that is the script's behaviour and belongs in
+the report rather than being omitted.
+
+**`macbookpro`:** append `/opt/homebrew/bin` to PATH for the `bun` commands, run `pm2` separately. See
+`docs/servers.md`.
+
+## `officer-dev` — skip it
+
+This is the machine the rollout runs from, and restarting `officer` here ends the agent performing it.
+Name it as skipped in the report. It is already current.
@@ -57,6 +57,25 @@ so the walk exists — this is a second consumer of it, not a new class of work.
 live count needs no new endpoint. Correlate `live.claudeSessionId === session.id`; a live row whose id is
 still null contributes to no directory (see above).

+**`/chat/live` returns only agents unless asked otherwise.** `?kind=` takes `agent` (the default),
+`commander`, or `all`; anything else is a 400 rather than a silent fallback, and the plural forms are
+accepted because the web client's own type is already `'agents' | 'commanders'`.
+
+The default is the point. Commanders run background work and the phone swipes between live chats one at a
+time, with no room for tabs and no way to skip a row — so a client that forgets the parameter must not be
+handed a deploy commander. Defaulting to `agent` means forgetting can only ever under-report. The two
+callers that genuinely want both say `kind=all`, which is a fair price: they are few, they are on screens
+built to show both, and they are the ones positioned to notice if the answer is wrong.
+
+`counts` describes **every** live session regardless of the filter, so a filtered caller still renders
+`Agents (n) / Commanders (n)` without a second request. That is what stops a server-side filter from
+costing more round trips than the client-side one it replaced.
+
+Which rows are commanders comes from `command_hq_sessions`, **not** from the working directory — a
+commander chooses its own cwd, so the directory answers nothing. `GET /chat/sessions` reports no
+`isCommander` at all, because it removes commanders entirely; a list that excludes them has nothing to say
+about which of its rows is one.
+
 ---

 ## Landmines
@@ -0,0 +1,93 @@
+# SendOff — files land in the user's own tree, and a push says where
+
+**From:** mobile · **Date:** 2026-08-23 · **v2, replacing this morning's spec entirely.** The v1
+design (staging area, transfer/target/file tables, ack lifecycle, TTL cleanup) is withdrawn — Andre's
+observation kills it: every user already has a filesystem on the server, a file browser on the web,
+and a Files app on the phone. SendOff is not a new storage system; it is a folder convention, one
+endpoint, and a push.
+
+## The convention
+
+```
+~/Downloads/sendoff/from-<username>/   ← a file another USER sent you
+~/Downloads/sendoff/<machine>/         ← a file you sent yourself, aimed at a named device
+```
+
+That is the whole data model. Nothing to ack, nothing to expire, nothing to clean up — the files are
+ordinary files in the recipient's tree, visible in every file UI that already exists, managed like
+anything else they own.
+
+## The endpoint
+
+```
+POST /api/sendoff/send
+  multipart: any number of `file` parts + a `meta` part:
+    { "toUser": "<username>" }        — cross-user: writes into THEIR tree, from-<sender>/
+    { "machine": "<device name>" }    — self: writes into own tree, <machine>/
+  → { path: "Downloads/sendoff/…", files: [{ name, size }] }
+```
+
+Server-side because of the cross-user case: `/api/file-browser/upload` correctly writes only the
+caller's own tree, and that must not change. This endpoint is the one sanctioned door into another
+user's filesystem, and it writes ONLY under `Downloads/sendoff/from-<sender>/` — the sender's
+identity comes from their token, never from the payload, so the folder name cannot lie about who
+sent it. Filenames sanitised, collisions suffixed `(1)` — never overwritten; a second send of the
+same name is a second file.
+
+Whether user A may send to user B at all is a platform policy decision (everyone on the server? a
+grant?) — flagging it rather than deciding it here.
+
+## The push
+
+On write, push to the recipient's devices through the existing pipeline:
+
+```
+{ "officer": { "c": "officer/core:sendoff.landed", "path": "Downloads/sendoff/from-andre" } }
+alert: "photo.jpg from andre" / "3 files from omega"
+```
+
+The push catalogue's route for the category:
+
+```
+officer://files?path={path}
+```
+
+Mobile opens routes from the catalogue verbatim (`openNotificationRoute`), and Officer now parses
+`officer://files?path=…` into the Files app at that folder. The web can deep-link its file browser
+the same way.
+
+For a `machine`-targeted send, push only to that machine's device if it can be identified; to all
+the user's devices otherwise — the path in the folder name already says who it was for.
+
+## Devices
+
+The `machine` name needs a picker on the sending side, so a minimal registry survives from v1:
+
+```
+devices: id (client uuid), user_id, name, platform, last_seen_at
+POST /api/devices/register { id, name, platform }   (upsert; called on every app start)
+GET  /api/devices → { devices }                     (the "send to my…" picker)
+PATCH /api/devices/:id { name } · DELETE /api/devices/:id
+```
+
+No link to transfers — nothing references a device row except the picker and, best-effort, push
+targeting.
+
+## Web UI
+
+One send form: files + target (one of my machines / another user), POST, done. Received files need
+no UI at all — they are in the file browser already.
+
+## What mobile already does (shipped against this)
+
+- Registers the device on start (silent failure until the endpoint exists).
+- Parses `officer://files?path=…` and opens the Files app at that path — this is the piece that
+  makes the push tap land somewhere.
+- SendOff screen: the device's name (the folder senders will aim at), and an explanation of where
+  arrivals land. Sending FROM the phone comes later, likely through the existing share sheet.
+
+## Out of scope
+
+Receiving in the browser (already exists — it is the file browser); cross-user permission model
+(platform decision); phone-side arbitrary-file sending (needs a document picker; the share sheet is
+the natural door and is a later step).
@@ -1,12 +1,15 @@
 {
  "name": "officer",
-  "version": "2026.08.22.02",
+  "version": "2026.08.23.01",
  "private": true,
  "type": "module",
  "workspaces": [
    "src/databases/*",
    "src/workspaces/*"
  ],
+  "engines": {
+    "bun": "1.3.x"
+  },
  "scripts": {
    "preinstall": "node -e \"var v = +process.versions.node.split('.')[0]; if (v < 22) { console.error('Node 22 or newer required (got ' + process.versions.node + '). Run: nvm use 22'); process.exit(1); }\"",
    "gen:index": "bun run ./scripts/gen-index.ts",
@@ -0,0 +1,144 @@
+#!/usr/bin/env bash
+#
+# The wait half of the deploy commander: poll for a release tag, and when one appears that has not been
+# attempted, spawn a headless agent to deploy it.
+#
+# WHY THIS IS IN THE REPOSITORY AND NOT WRITTEN FRESH EACH ARMING
+#
+# prompts/deploy-commander.md says the watcher loop is rewritten from scratch every time one arms, and
+# treats that as a given. It is also how the same defect keeps arriving. The loop that was on disk at
+# data/deploy-watch.sh from 2026-08-21 gated on "$v.done" — a file that exists only on SUCCESS — and never
+# called deploy-claim.sh at all. That is precisely the retry storm the claim script was written to make
+# impossible, reintroduced in the one place the claim script cannot reach: the caller that decides whether
+# to invoke it. A rule enforced by a script nobody calls is not enforced.
+#
+# So the loop lives next to the claim it depends on, and changes with it.
+#
+# THE BASELINE IS THE CLAIM, NOT THE SUCCESS
+#
+# A watcher needs to know what counts as new. Here that is "no claim directory for this version" — a record
+# of what has been HANDLED, not of what has SUCCEEDED. The distinction is the whole point: a release that
+# failed is handled. It is looked at by a human, not retried by a loop.
+#
+# deploy-claim.sh honours a pre-existing .done with no .claim, so releases deployed before it existed are
+# already skipped and arming this today fires on none of them.
+#
+# THE CLAIM IS TAKEN HERE, BEFORE THE SPAWN
+#
+# An action that claims its own work has claimed nothing if it dies before getting that far. So the loop
+# claims, then spawns — which means the child must be TOLD the claim is already held. It is about to read
+# prompts/deploy-commander.md, whose claim instruction is addressed to whoever reads it, and an obedient
+# child that claims for itself gets exit 1 and correctly refuses to deploy. See PROMPT below.
+set -u
+
+PLATFORM_DIR="${PLATFORM_DIR:-$HOME/officer-dev/platform}"
+# Empty in the sidecar's environment, where anything built from it resolves to /data/... and the record
+# lands where nothing reads it. A watcher whose baseline is invisible to itself has none.
+OFFICER_ROOT="${OFFICER_ROOT:-$HOME/officer-dev}"
+DEPLOYS_DIR="${DEPLOYS_DIR:-$OFFICER_ROOT/data/deploys}"
+POLL_SECONDS="${POLL_SECONDS:-120}"
+export OFFICER_ROOT DEPLOYS_DIR
+
+CLAIM_SH="$PLATFORM_DIR/scripts/deploy-claim.sh"
+
+stamp() { date -Iseconds; }
+
+if [ ! -x "$CLAIM_SH" ]; then
+  echo "$(stamp) deploy-watch: no claim script at $CLAIM_SH — refusing to arm without one" >&2
+  exit 2
+fi
+
+mkdir -p "$DEPLOYS_DIR" || exit 2
+
+echo "$(stamp) deploy-watch: armed. polling $(cd "$PLATFORM_DIR" && git remote get-url origin) every ${POLL_SECONDS}s"
+echo "$(stamp) deploy-watch: baseline is $DEPLOYS_DIR — a version with a claim is never fired again"
+
+while true; do
+  # origin is the LOCAL gitea over the tailnet. The public hostname arrives through a proxy where every
+  # connection shares one source IP and SSH is refused for long stretches — which presents as an
+  # access-rights error and is not one. Eighty minutes of detection latency on 2026-08-21.
+  raw=$(cd "$PLATFORM_DIR" && timeout 30 git ls-remote --tags origin 'refs/tags/deploy/*' 2>&1)
+  rc=$?
+
+  if [ $rc -ne 0 ]; then
+    echo "$(stamp) tick: ls-remote failed (exit $rc) — ${raw%%$'\n'*}"
+    sleep "$POLL_SECONDS"
+    continue
+  fi
+
+  versions=$(printf '%s\n' "$raw" | grep -v '\^{}' | awk '{print $2}' | sed -E 's#.*refs/tags/deploy/##' | sort -u)
+
+  pending=""
+  for v in $versions; do
+    [ -n "$v" ] || continue
+    [ "$("$CLAIM_SH" state "$v" 2>/dev/null)" = unclaimed ] && pending="$pending $v"
+  done
+
+  # Every tick leaves a line, including the quiet ones: a fresh timestamp is the only thing that tells
+  # "nothing to deploy" apart from "the loop died".
+  echo "$(stamp) tick: $(printf '%s\n' "$versions" | grep -c .) tags,${pending:- none} pending"
+
+  for v in $pending; do
+    if ! "$CLAIM_SH" claim "$v"; then
+      # Lost a race with another watcher, or it was claimed between the state check and here. Either way
+      # it is not ours and never becomes ours.
+      continue
+    fi
+
+    echo "$(stamp) deploy/$v claimed — spawning deploy agent"
+
+    # The child reads the procedure, which tells ITS reader to claim first. It must not: we hold the claim
+    # on its behalf, and its own claim would return exit 1 and stop the deploy it was spawned to do.
+    PROMPT="Read prompts/deploy-commander.md in $PLATFORM_DIR and follow it exactly, for the release deploy/$v.
+
+The claim for $v is ALREADY HELD on your behalf by the watcher that spawned you. Do NOT run
+'scripts/deploy-claim.sh claim $v' — it will refuse, correctly, because the claim is taken, and stopping
+there would abandon a deploy you were started to perform. Everything else in that file applies unchanged,
+including running 'scripts/deploy-claim.sh done $v' once the rollout has succeeded.
+
+Roll it out across every host the plan names, skip the host you are running on, and write the report
+exactly as the procedure specifies."
+
+    raw_log="$DEPLOYS_DIR/$v.child.jsonl"
+
+    # Nothing links a spawned agent to its parent and a child transcript does not last, so the stream is
+    # kept here as it arrives. stderr never enters the pipe: the CLI writes warnings there and one landing
+    # in the stream corrupts the first jq parse.
+    {
+      cd "$PLATFORM_DIR" && claude -p "$PROMPT" \
+        --dangerously-skip-permissions \
+        --output-format=stream-json \
+        --verbose
+    } 2> >(while IFS= read -r l; do echo "  ! $l"; done) \
+      | tee -a "$raw_log" \
+      | jq -r --unbuffered '
+          if .type=="system" and .subtype=="init" then
+            "  · child session " + .session_id
+          elif .type=="assistant" then
+            (.message.content[]? |
+              if .type=="tool_use" then
+                "  ⚙ " + .name + ": " + ((.input.description // .input.command // .input.pattern // (.input | tostring)))
+              elif .type=="text" then
+                "  » " + .text
+              else empty end)
+          elif .type=="user" then
+            (.message.content[]? | select(.type=="tool_result") |
+              "    " + (if (.content|type)=="string" then .content else (.content // [] | map(.text? // "") | join(" ")) end))
+          elif .type=="result" then
+            "  = deploy agent " + .subtype + ", " + (.num_turns|tostring) + " turns, " + (.total_cost_usd|tostring) + " usd"
+          else empty end
+        ' 2>/dev/null
+
+    if [ -f "$DEPLOYS_DIR/$v.done" ]; then
+      echo "$(stamp) deploy/$v SUCCEEDED — recorded, transcript at $raw_log"
+    else
+      # The claim stays held. This is the loop's most important line and the one that used to say
+      # "will retry next poll".
+      echo "$(stamp) deploy/$v FAILED — no .done written. NOT retrying; the claim is held."
+      echo "$(stamp)   transcript: $raw_log"
+      echo "$(stamp)   to allow another attempt, deliberately: rm -rf $DEPLOYS_DIR/$v.claim"
+    fi
+  done
+
+  sleep "$POLL_SECONDS"
+done
@@ -34,6 +34,44 @@ const fail = (what: string, fix: string) => {
 };
 const pass = (what: string) => console.log(`${green('✓')} ${what}`);

+console.log('\n── Runtime ──\n');
+
+/**
+ * bun is deliberately held at a series — `BUN_SERIES` in
+ * scripts/setup/machine-setup/lib/dev.sh — while 1.4 is watched for a while.
+ *
+ * The setup script can pin the INSTALL and nothing more. `bun upgrade` takes no version
+ * argument (it offers latest-stable or --canary and nothing else), so it always jumps to the
+ * newest release and walks a pinned machine off the pin without saying so. This is the only
+ * thing that notices, which is why a version check sits in a script otherwise about accounts.
+ *
+ * The wanted series is READ from `engines.bun` rather than repeated here, because a second
+ * hardcoded copy is a second thing to drift. bun does not enforce that field — verified: an
+ * install declaring `engines.bun: "1.9.x"` ran clean under 1.3.14, no warning — so the field is
+ * the declaration and this is the enforcement.
+ */
+const pkg = (await Bun.file(new URL('../package.json', import.meta.url)).json()) as {
+  engines?: { bun?: string };
+};
+const wantSeries = (pkg.engines?.bun ?? '').replace(/\.x$/, '');
+const nowSeries = Bun.version.split('.').slice(0, 2).join('.');
+
+if (!wantSeries) {
+  fail(
+    'package.json declares no engines.bun',
+    'The setup scripts pin a bun series and nothing else records which one. Add it.',
+  );
+} else if (nowSeries === wantSeries) {
+  pass(`bun ${Bun.version} ${dim(`(inside the pinned ${wantSeries} series)`)}`);
+} else {
+  fail(
+    `bun ${Bun.version} is outside the pinned ${wantSeries} series`,
+    `Usually a 'bun upgrade', which always takes the newest release. Pin it back with ` +
+      `'curl -fsSL https://bun.sh/install | bash -s bun-v<newest ${wantSeries}.x>', or raise ` +
+      `engines.bun and BUN_SERIES together if ${nowSeries} is now wanted.`,
+  );
+}
+
 console.log('\n── Accounts ──\n');

 const users = await getUsers();
@@ -206,7 +206,7 @@ nvim_clone_config() {
 #          every process here. officer-pty imports node-pty, a native addon with
 #          no Linux prebuild — it compiles against the installed Node on every
 #          machine. Either one alone makes Node load-bearing.
-#   bun    the platform itself and nineteen of the twenty pm2 apps.
+#   bun    the platform itself, and every pm2 app except officer-pty.
 #   pm2    the process manager the ecosystem files are written for.
 #
 # Deno is not. Nothing in the platform imports it — checked across the whole
@@ -243,6 +243,69 @@ install_node() {
  npm config set prefix /usr/local >/dev/null 2>&1 || true
 }

+# ── Held at the 1.3 series, deliberately and temporarily ──
+#
+# bun 1.4.0 landed on 2026-08-20 and https://bun.sh/install takes whatever is
+# newest, so a machine provisioned two days later puts a brand-new release under
+# the platform and every pm2 app it runs. Held at 1.3 until 1.4 has been watched
+# for a while. That is the owner's call and it is meant to be revisited in a few
+# months, not a permanent ceiling — raise BUN_SERIES when 1.4 has earned it.
+#
+# The SERIES is pinned, not a patch. 1.3.x fixes still land and should still be
+# taken; a hardcoded 1.3.14 would rot into "the version we happened to pick"
+# exactly the way setup_22.x did for Node.
+#
+# This covers the INSTALL path only, and cannot cover the other one: `bun upgrade`
+# takes no version argument — checked against `bun upgrade --help` on 1.3.14, which
+# offers latest-stable or --canary and nothing else — so it always jumps to the
+# newest release and will walk a pinned machine onto 1.4 on its own. Nothing in a
+# setup script can prevent that. `bun run doctor` is where that drift is caught.
+BUN_SERIES="${BUN_SERIES:-1.3}"
+
+# The newest stable release inside the series.
+#
+# Asked of the npm registry rather than GitHub's releases API, which is the obvious
+# source and the wrong one: it rate-limits unauthenticated callers to 60 an hour per
+# IP, and it returned 504 twice while this was being written. An empty answer here
+# means no bun gets installed at all (see install_bun), so where it comes from is
+# load-bearing rather than a matter of taste. bun publishes every release to npm.
+#
+# `sort -V` rather than trusting the order the registry returns them in, and the
+# pattern is anchored so 1.3.1 cannot be mistaken for the newest when 1.3.14 exists.
+bun_series_latest() {
+  curl -fsSL https://registry.npmjs.org/bun 2>/dev/null |
+    jq -r '.versions | keys[]' 2>/dev/null |
+    grep -E "^${BUN_SERIES//./\\.}\.[0-9]+$" |
+    sort -V | tail -1
+}
+
+# The major.minor of a full version — "1.3.14" is in series "1.3".
+bun_series_of() { sed -E 's/^([0-9]+\.[0-9]+).*/\1/' <<<"${1:-}"; }
+
+# Where an installed bun sits relative to the pin: in, above, below, or unknown.
+#
+# Above and below are different problems and get different answers — above is a
+# machine that has upgraded itself past the pin, below is one that is simply old —
+# so this reports which rather than a yes/no. `sort -V` does the comparing, so
+# nothing here has to parse a version.
+bun_series_position() {
+  local now
+  now="$(bun_series_of "${1:-}")"
+  [[ -n "$now" ]] || {
+    echo unknown
+    return
+  }
+  [[ "$now" == "$BUN_SERIES" ]] && {
+    echo in
+    return
+  }
+  if [[ "$(printf '%s\n%s\n' "$now" "$BUN_SERIES" | sort -V | tail -1)" == "$now" ]]; then
+    echo above
+  else
+    echo below
+  fi
+}
+
 # Present anywhere: on PATH for this root shell, or in the account's own
 # ~/.bun/bin, which is where the installer puts it and where root cannot see it.
 bun_installed() { command -v bun &>/dev/null || [[ -x "${USER_HOME}/.bun/bin/bun" ]]; }
@@ -260,8 +323,8 @@ bun_version() {
 # The system-wide link, ensured on every run rather than only after an install.
 #
 # pm2 started at boot by systemd has no login shell, so ~/.bun/bin is not on its
-# PATH — and every one of the twenty ecosystem apps that says `script: 'bun'`
-# then fails to start on reboot while working perfectly when started by hand. A
+# PATH — and every ecosystem app that says `script: 'bun'` then fails to start on
+# reboot while working perfectly when started by hand. A
 # machine that already had bun before this script ran would never get the link if
 # it were only made as part of installing.
 #
@@ -280,8 +343,22 @@ ensure_bun_symlink() {
 # systemd has no login shell and therefore no ~/.bun/bin on PATH — without the
 # symlink every bun-based sidecar fails to start on reboot and works fine when
 # started by hand, which is a miserable thing to debug.
+#
+# The version goes in as the installer's first positional argument, which it
+# documents as "a specific tag of bun to install (e.g. bun-v0.1.4)" and turns into a
+# releases/download/<tag>/ URL. `bash -s` is what carries an argument through a pipe.
+# The installer handles being pointed at an older tag on purpose — it re-probes AVX2
+# rather than assuming the baseline the newest release was built for — so this both
+# installs and pins back down.
+#
+# It REFUSES to run unpinned. An empty tag means bun_series_latest could not reach
+# the registry, and installing whatever is newest is the single outcome the pin
+# exists to prevent, so a machine with no bun is the better failure: it is loud, and
+# officer-setup's pre-flight stops on a missing bun rather than building on 1.4.
 install_bun() {
-  (cd / && sudo -H -u "$USERNAME" bash -c 'curl -fsSL https://bun.sh/install | bash') >/dev/null 2>&1
+  local tag="${1:-}"
+  [[ -n "$tag" ]] || return 1
+  (cd / && sudo -H -u "$USERNAME" bash -c "curl -fsSL https://bun.sh/install | bash -s '${tag}'") >/dev/null 2>&1
  [[ -x "${USER_HOME}/.bun/bin/bun" ]]
 }

@@ -1981,14 +1981,18 @@ step "JavaScript runtimes"
 if ! skip; then
  NODE_LTS="$(node_lts_major)"
  NODE_NOW="$(node_installed_major)"
+  # Resolved before the banner so it can state the pin rather than only the version
+  # that happens to be here. One network call, same as node_lts_label above it.
+  BUN_WANT="$(bun_series_latest)"
+  BUN_NOW="$(bun_version)"

  echo ""
  info "JavaScript runtimes — required, so these are installed rather than offered"
  echo "     node   ${NODE_NOW:+v$NODE_NOW }${NODE_NOW:+-> }LTS $(node_lts_label)"
  echo "            pm2 is a Node application, and officer-pty compiles node-pty"
  echo "            against whatever Node is installed — there is no Linux prebuild."
-  echo "     bun    $(bun_installed && bun_version || echo 'not installed')"
-  echo "            the platform itself, and nineteen of the twenty pm2 apps."
+  echo "     bun    ${BUN_NOW:-not installed} — pinned to the ${BUN_SERIES} series${BUN_WANT:+, newest is ${BUN_WANT}}"
+  echo "            the platform itself, and every pm2 app except officer-pty."
  echo "     pm2    $(pm2_installed && echo installed || echo 'not installed')"
  echo "            supervises all of them, and the ecosystem files are written for it."
  echo ""
@@ -2014,18 +2018,93 @@ if ! skip; then
    fi
  fi

-  # ── bun ──
+  # ── bun, held at the pinned series ──
+  #
+  # Four states, because "installed" is not one answer. A machine can be inside the
+  # pin, behind it, or past it — and past it is the case worth catching, since that
+  # is what a `bun upgrade` leaves behind and nothing else reports it.
+  if [[ -z "$BUN_WANT" ]]; then
+    # No pin resolved means no install: taking whatever bun.sh serves is the one
+    # thing the pin exists to stop.
+    warn "could not reach the npm registry to find the newest bun ${BUN_SERIES}.x"
    if bun_installed; then
-    ok "bun $(bun_version) already installed"
+      echo "     leaving bun ${BUN_NOW} where it is"
+      ERRORS+=("Bun: could not resolve ${BUN_SERIES}.x; left ${BUN_NOW} alone")
    else
-    info "     installing bun..."
-    if install_bun && bun_installed; then
+      echo "     nothing installed — this will not install an unpinned bun, and"
+      echo "     officer-setup stops on a missing bun rather than building on 1.4."
+      ERRORS+=("Bun: could not resolve ${BUN_SERIES}.x; nothing installed")
+    fi
+
+  elif ! bun_installed; then
+    info "     installing bun ${BUN_WANT}, pinned to the ${BUN_SERIES} series..."
+    if install_bun "bun-v${BUN_WANT}" && bun_installed; then
      ok "bun $(bun_version)"
-      SUMMARY+=("Bun: $(bun_version)")
+      SUMMARY+=("Bun: $(bun_version) (pinned to ${BUN_SERIES}.x)")
    else
      warn "the bun install did not complete"
      ERRORS+=("Bun: install failed")
    fi
+
+  else
+    case "$(bun_series_position "$BUN_NOW")" in
+      in)
+        if [[ "$BUN_NOW" == "$BUN_WANT" ]]; then
+          ok "bun ${BUN_NOW} — the newest in the pinned ${BUN_SERIES} series"
+        else
+          info "bun ${BUN_NOW} is inside the pin, and ${BUN_WANT} is out"
+          echo "     A patch inside the series is what the pin is meant to let"
+          echo "     through. Note that 'bun upgrade' would not stop there — it"
+          echo "     takes the newest release, which is past the pin."
+          if confirm "Move to ${BUN_WANT}?"; then
+            if install_bun "bun-v${BUN_WANT}"; then
+              ok "bun $(bun_version)"
+              SUMMARY+=("Bun: ${BUN_NOW} -> $(bun_version)")
+            else
+              warn "the install did not complete — bun ${BUN_NOW} is untouched"
+              ERRORS+=("Bun: could not move to ${BUN_WANT}")
+            fi
+          else
+            echo "     left at ${BUN_NOW}"
+          fi
+        fi
+        ;;
+      above)
+        # The `bun upgrade` case. Reported rather than corrected silently: moving
+        # somebody's runtime backwards is a decision, and this is the only place
+        # that knows it happened.
+        warn "bun ${BUN_NOW} is PAST the pinned ${BUN_SERIES} series"
+        echo "     Most likely a 'bun upgrade', which takes no version argument and"
+        echo "     always jumps to the newest release. The platform and every pm2"
+        echo "     app except officer-pty run on this."
+        if confirm "Pin it back to ${BUN_WANT}?"; then
+          if install_bun "bun-v${BUN_WANT}"; then
+            ok "bun $(bun_version) — back inside the pin"
+            SUMMARY+=("Bun: pinned back, ${BUN_NOW} -> $(bun_version)")
+          else
+            warn "the install did not complete — bun ${BUN_NOW} is untouched"
+            ERRORS+=("Bun: could not pin ${BUN_NOW} back to ${BUN_WANT}")
+          fi
+        else
+          warn "left at ${BUN_NOW}, outside the pin"
+          SUMMARY+=("Bun: ${BUN_NOW}, PAST the ${BUN_SERIES} pin by choice")
+        fi
+        ;;
+      *)
+        info "bun ${BUN_NOW} is older than the pinned ${BUN_SERIES} series"
+        if confirm "Move to ${BUN_WANT}?"; then
+          if install_bun "bun-v${BUN_WANT}"; then
+            ok "bun $(bun_version)"
+            SUMMARY+=("Bun: ${BUN_NOW} -> $(bun_version)")
+          else
+            warn "the install did not complete — bun ${BUN_NOW} is untouched"
+            ERRORS+=("Bun: could not move to ${BUN_WANT}")
+          fi
+        else
+          echo "     left at ${BUN_NOW}"
+        fi
+        ;;
+    esac
  fi

  # Ensured every run, not only after an install. A machine that already had bun
@@ -760,7 +760,7 @@ if ! skip; then
  echo "     The ecosystem file is GENERATED, not checked in. It describes this"
  echo "     install and nothing else, so nothing in git can drift from it."
  echo ""
-  echo "     six processes:"
+  echo "     ${#CORE_PROCESSES[@]} processes:"
  for entry in "${CORE_PROCESSES[@]}"; do
    IFS='|' read -r _name _script _args <<<"$entry"
    printf "       %-24s %s %s\n" "$_name" "$_script" "$_args"
@@ -772,7 +772,7 @@ if ! skip; then
  if confirm "Write it and start them?"; then
    write_ecosystem
    ok "written — $(ecosystem_file)"
-    report_changed "wrote $(ecosystem_file) — six pm2 apps: $(printf '%s ' "${CORE_PROCESSES[@]%%|*}")"
+    report_changed "wrote $(ecosystem_file) — ${#CORE_PROCESSES[@]} pm2 apps: $(printf '%s ' "${CORE_PROCESSES[@]%%|*}")"

    # Starting against a database that is not answering is not fatal — the server
    # waits and the agent retries forever — but it makes the Verify section below
@@ -792,13 +792,13 @@ if ! skip; then
        if pm2_enable_startup; then
          ok "pm2 will resurrect them at boot"
          report_ran "pm2 startup systemd — installed a systemd unit so pm2 resurrects these at boot"
-          SUMMARY+=("Services: 6 processes started, enabled at boot")
+          SUMMARY+=("Services: ${#CORE_PROCESSES[@]} processes started, enabled at boot")
        else
          warn "could not enable the boot hook — run 'pm2 startup' yourself and follow it"
-          SUMMARY+=("Services: 6 processes started; boot hook NOT enabled")
+          SUMMARY+=("Services: ${#CORE_PROCESSES[@]} processes started; boot hook NOT enabled")
        fi
      else
-        SUMMARY+=("Services: 6 processes started; not enabled at boot")
+        SUMMARY+=("Services: ${#CORE_PROCESSES[@]} processes started; not enabled at boot")
      fi
    else
      warn "pm2 did not start cleanly"
@@ -945,7 +945,7 @@ fi
 #
 # Root, and that surprises people — reasonably, because everything this script just
 # installed belongs to somebody else. The platform runs as ${USERNAME}: the checkout,
-# node_modules, .env, the secret store and all six pm2 processes are theirs. Root was
+# node_modules, .env, the secret store and every pm2 process are theirs. Root was
 # the installer's privilege, never the platform's.
 #
 # Saying so matters for two things that are invisible until they bite:
@@ -59,7 +59,7 @@ tool_why() {
  case "$1" in
    git) echo "to clone and update the platform" ;;
    node) echo "pm2 runs on it, and the terminal sidecar builds node-pty against it" ;;
-    bun) echo "the platform itself and nineteen of the twenty processes" ;;
+    bun) echo "the platform itself and every process except the pty sidecar" ;;
    pm2) echo "supervises every process; the ecosystem files are written for it" ;;
    docker) echo "Postgres, and anything the app store provisions" ;;
    *) echo "" ;;
@@ -106,6 +106,7 @@ export function App() {
            <Route path="/system-monitor/:scope" element={<Dashboard.SystemMonitorScreen />} />
            {/* TEMPORARY / EXPERIMENTAL — offline file transfer over animated QR codes */}
            <Route path="/qr-transfer" element={<Dashboard.QrTransferScreen />} />
+            <Route path="/minesweeper" element={<Dashboard.MinesweeperScreen />} />
            <Route path="/activity" element={<Dashboard.ActivityScreen />} />
            <Route path="/activity/:id" element={<Dashboard.ActivityScreen />} />

@@ -0,0 +1,20 @@
+import type { LayoutNode } from 'officerdev';
+import { WorkspaceView } from 'officerdev';
+import { useDashboardState } from 'state/useDashboardState';
+import { defaultLayout } from './defaultLayout';
+
+// /minesweeper — Minesweeper X running under wine on a virtual display, streamed over RFB.
+//
+// The pixels arrive through /api/minesweeper/ws, which is a byte relay onto x11vnc's own TCP socket on
+// loopback — the same shape as the terminal's relay onto the pty sidecar, and the reason this works at
+// all where `plugins/desktop` could not: a websocket provider is a platform concern, and a plugin
+// cannot claim one.
+//
+// Owner-only, and not because a game is dangerous: wine runs as the server owner, so the game's menus
+// are file dialogs with the owner's home behind them.
+
+export const MinesweeperScreen = () => {
+  const workspace = useDashboardState<LayoutNode>('screens/minesweeper', defaultLayout);
+
+  return <WorkspaceView workspace={workspace} locked appTypes={{ allowed: ['minesweeper'], fallback: 'minesweeper' }} />;
+};
@@ -0,0 +1,9 @@
+import type { LayoutNode } from 'officerdev';
+
+// One panel. The board is 152x214 and there is nothing to put beside it — a split here would be a
+// second panel of empty space.
+export const defaultLayout: LayoutNode = {
+  type: 'panel',
+  id: 'minesweeper',
+  appType: 'minesweeper',
+};
@@ -0,0 +1 @@
+export * from './MinesweeperScreen';
@@ -22,3 +22,4 @@ export * from './Dashboards';
 export * from './Terminal';
 export * from './Jobs';
 export * from './QrTransfer';
+export * from './Minesweeper';
@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { inArray } from 'drizzle-orm';
+import { db } from './db';
+import { chatSessionEvents } from './chat-events/schema';
+import { chatSessionModels } from './chat-session-models/schema';
+import { forgetChatSessions } from './chat-session-cleanup';
+
+/*
+  Deleting a conversation, across the two id spaces it actually spans.
+
+  This file touches the real database, which the rest of the suite avoids on purpose. It has to: the defect
+  it exists to catch was never in a decision, it was in which column a `delete` matched. A test built on a
+  fake store would have passed against both the broken version and the fixed one.
+
+  Safe because every id here is a synthetic uuid in a reserved block that no harness produces, and because
+  each test removes exactly what it wrote. Nothing reads live rows and nothing deletes by anything but these
+  ids.
+
+  Two regressions are pinned here, and they are the same bug seen twice:
+
+  1. `chat_session_events` is keyed on officer's SESSION KEY while everything else is keyed on the TRANSCRIPT
+     id. One list passed to all four tables matched nothing in this one, ever, by construction — and counting
+     events by transcript id to check also returns zero by construction, so it read as clean.
+  2. Resolving that key from a live in-memory map only works for a session younger than the process. After a
+     restart it comes back null, the key list arrives empty, and the events survive a delete that reports
+     success. The key has to come from the rows, which carry `claudeSessionId` in their payload.
+*/
+
+const TRANSCRIPT = '00000000-dead-4000-8000-000000000001';
+const SESSION_KEY = '00000000-dead-4000-8000-0000000000ff';
+
+afterEach(async () => {
+  await db.delete(chatSessionEvents).where(inArray(chatSessionEvents.sessionId, [SESSION_KEY]));
+  await db.delete(chatSessionModels).where(inArray(chatSessionModels.sessionId, [TRANSCRIPT]));
+});
+
+const countEvents = async () =>
+  (
+    await db
+      .select()
+      .from(chatSessionEvents)
+      .where(inArray(chatSessionEvents.sessionId, [SESSION_KEY]))
+  ).length;
+
+describe('forgetChatSessions', () => {
+  test('removes events keyed on the session key, found via the transcript id in their payload', async () => {
+    // Exactly the real shape: one `result` carries both ids, the rest carry neither.
+    await db.insert(chatSessionEvents).values([
+      { sessionId: SESSION_KEY, event: { type: 'result', sessionId: SESSION_KEY, claudeSessionId: TRANSCRIPT } },
+      { sessionId: SESSION_KEY, event: { type: 'assistant:text', text: 'no ids on this one' } },
+      { sessionId: SESSION_KEY, event: { type: 'tool:start', toolName: 'Bash' } },
+    ]);
+    expect(await countEvents()).toBe(3);
+
+    // No `sessionKeys` — this is the post-restart case, where the caller cannot resolve one.
+    await forgetChatSessions({ transcriptIds: [TRANSCRIPT] });
+
+    // All three, not just the one carrying the id: resolving the key covers the whole session.
+    expect(await countEvents()).toBe(0);
+  });
+
+  test('an explicit session key still works when no event names the transcript', async () => {
+    await db
+      .insert(chatSessionEvents)
+      .values([{ sessionId: SESSION_KEY, event: { type: 'assistant:text', text: 'nothing identifying here' } }]);
+
+    await forgetChatSessions({ transcriptIds: [TRANSCRIPT], sessionKeys: [SESSION_KEY] });
+    expect(await countEvents()).toBe(0);
+  });
+
+  test('leaves another session alone', async () => {
+    const OTHER = '00000000-dead-4000-8000-0000000000ee';
+    await db
+      .insert(chatSessionEvents)
+      .values([{ sessionId: OTHER, event: { type: 'assistant:text', text: 'theirs' } }]);
+    try {
+      await forgetChatSessions({ transcriptIds: [TRANSCRIPT], sessionKeys: [SESSION_KEY] });
+      const left = await db
+        .select()
+        .from(chatSessionEvents)
+        .where(inArray(chatSessionEvents.sessionId, [OTHER]));
+      expect(left.length).toBe(1);
+    } finally {
+      await db.delete(chatSessionEvents).where(inArray(chatSessionEvents.sessionId, [OTHER]));
+    }
+  });
+
+  test('forgets the transcript-keyed tables too', async () => {
+    await db.insert(chatSessionModels).values({ sessionId: TRANSCRIPT, model: 'claude-code/opus', planMode: false });
+    await forgetChatSessions({ transcriptIds: [TRANSCRIPT] });
+    const left = await db
+      .select()
+      .from(chatSessionModels)
+      .where(inArray(chatSessionModels.sessionId, [TRANSCRIPT]));
+    expect(left.length).toBe(0);
+  });
+});
@@ -0,0 +1,113 @@
+import { eq, inArray, sql } from 'drizzle-orm';
+import { db } from './db';
+import { chatSessionEvents } from './chat-events/schema';
+import { chatNotificationPrefs } from './chat-notification-prefs/schema';
+import { chatSessionModels } from './chat-session-models/schema';
+import { nudges } from './nudges/schema';
+
+/*
+  Everything the platform stores ABOUT a conversation, forgotten together.
+
+  ── Why this exists as one function ──
+
+  Four tables describe a conversation, and none has a foreign key to anything, because the thing they
+  describe is a FILE — a transcript on disk, written by the harness. There is no row for a chat session to
+  reference, so the database cannot cascade and the delete path has to be explicit.
+
+  It was not. Deleting a conversation removed the transcript and left all four behind, for ever. Found on
+  2026-08-22 by counting rows after two commanders were deleted through the UI: `chat_session_models` held 36
+  rows against far fewer live conversations.
+
+  ── Why it is more than untidy ──
+
+  Three of the four are inert — a model, a bell preference, a durable copy of turn output that nothing will
+  ask for again. `nudges` is not: it is a SCHEDULE, and the tick in `nudger.ts` reads it. A nudge left behind
+  by a deleted conversation is a timer that keeps firing at something that does not exist.
+
+  ── TWO id spaces, and this is where they were confused ──
+
+  Three of these tables are keyed on the TRANSCRIPT id — the harness's uuid, which is also the filename.
+  `chat_session_events` is keyed on officer's own SESSION KEY, which is a different uuid for the same
+  conversation. Its rows carry both (`{sessionId, claudeSessionId}`), which is how the mismatch was finally
+  proved rather than argued.
+
+  This function used to take one list and pass it to all four. So the events delete matched nothing, ever —
+  not sometimes, by construction — and a deleted conversation left its entire durable output behind. The
+  verification missed it twice, because counting events BY TRANSCRIPT ID also returns zero by construction,
+  and zero read as "cleaned". Found 2026-08-22 by reading an orphaned event payload instead of counting it.
+
+  The parameter is named for its id space so a caller cannot pass the wrong one without writing the wrong
+  word. That is the entire defence: nothing else about the two distinguishes them, since both are uuids.
+
+  ── Why each takes a list ──
+
+  A `/clear` chain is several transcripts presenting as one conversation, and deleting it deletes every part.
+  Forgetting one id and leaving its siblings is the same bug at a smaller scale, so the caller passes the ids
+  it actually removed.
+*/
+type ForgetChatSessionsParams = {
+  /** Harness transcript uuids — the filenames that were removed, including every part of a `/clear` chain. */
+  transcriptIds: string[];
+  /**
+   * Officer's session keys for the same conversations, for `chat_session_events` alone.
+   *
+   * Empty is legitimate and common: a session spawned by `claude -p` outside officer's websocket never had a
+   * key and never wrote an event, which is exactly the case for a commander's children.
+   */
+  sessionKeys?: string[];
+};
+
+export async function forgetChatSessions({ transcriptIds, sessionKeys = [] }: ForgetChatSessionsParams): Promise<void> {
+  // Sequential rather than a transaction: these are independent tables with no invariant between them, and
+  // a partial forget is strictly better than a failed delete that leaves the transcript gone and every row
+  // in place. Each is idempotent — running it twice removes nothing the second time.
+  if (transcriptIds.length) {
+    await db.delete(nudges).where(inArray(nudges.sessionId, transcriptIds));
+    await db.delete(chatSessionModels).where(inArray(chatSessionModels.sessionId, transcriptIds));
+    await db.delete(chatNotificationPrefs).where(inArray(chatNotificationPrefs.sessionId, transcriptIds));
+  }
+  /*
+    Events, resolved from the table's OWN data rather than from the caller's key.
+
+    `sessionKeys` is a fast path and not a reliable one: the caller gets it from an in-memory map that is
+    empty for any session created before the last restart, so the first real test of this deleted everything
+    except the events — the key came back null and the list was empty. A cleanup that only works for
+    conversations younger than the process is not a cleanup.
+
+    So ask the rows. Every event carries `claudeSessionId` in its payload, which is durable, survives any
+    restart, and is the one place the two id spaces are written down together. One id inside the JSON is
+    enough to resolve the key for all of that session's rows, including the events that carry no id of their
+    own — which is most of them.
+  */
+  if (transcriptIds.length) {
+    const keysFromEvents = await db
+      .selectDistinct({ sessionId: chatSessionEvents.sessionId })
+      .from(chatSessionEvents)
+      .where(inArray(sql`${chatSessionEvents.event}->>'claudeSessionId'`, transcriptIds));
+    const keys = [...new Set([...sessionKeys, ...keysFromEvents.map((r) => r.sessionId)])];
+    if (keys.length) await db.delete(chatSessionEvents).where(inArray(chatSessionEvents.sessionId, keys));
+  } else if (sessionKeys.length) {
+    await db.delete(chatSessionEvents).where(inArray(chatSessionEvents.sessionId, sessionKeys));
+  }
+}
+
+/**
+ * Officer's session key for a transcript, read from the durable event log.
+ *
+ * The in-memory maps (`sessionKeyForTranscript`, `findSessionKeyByClaudeSession`) only answer for a session
+ * younger than the process that is asking. After a restart both return undefined, and the delete path then
+ * skips the kill entirely — so the transcript is removed while the harness is still writing it, and the
+ * harness writes it straight back. A deleted commander reappears as an untitled stub.
+ *
+ * Every `result` event carries both ids in its payload, which survives any restart. Same trick as
+ * `forgetChatSessions`, and for the same reason: the rows are the only place the two id spaces are written
+ * down together.
+ */
+export async function sessionKeyForTranscriptId(transcriptId: string): Promise<string | undefined> {
+  const [row] = await db
+    .select({ sessionId: chatSessionEvents.sessionId })
+    .from(chatSessionEvents)
+    .where(eq(sql`${chatSessionEvents.event}->>'claudeSessionId'`, transcriptId))
+    .limit(1);
+  return row?.sessionId;
+}
@@ -55,6 +55,8 @@ export async function deleteCommandHqCategory(userId: number, id: number): Promi
 export type CommandHqSessionRow = {
  id: number;
  sessionId: string;
+  /** What the owner called it. Null for rows filed before the column existed — fall back to the transcript. */
+  name: string | null;
  categoryId: number | null;
  watcherArmed: boolean;
  watcherTaskId: string | null;
@@ -67,6 +69,7 @@ export type CommandHqSessionRow = {
 const SESSION_ROW_COLUMNS = {
  id: commandHqSessions.id,
  sessionId: commandHqSessions.sessionId,
+  name: commandHqSessions.name,
  categoryId: commandHqSessions.categoryId,
  watcherArmed: commandHqSessions.watcherArmed,
  watcherTaskId: commandHqSessions.watcherTaskId,
@@ -84,10 +87,11 @@ export async function createCommandHqSession(
  userId: number,
  sessionId: string,
  categoryId: number | null = null,
+  name: string | null = null,
 ): Promise<CommandHqSessionRow> {
  const [row] = await db
    .insert(commandHqSessions)
-    .values({ userId, sessionId, categoryId })
+    .values({ userId, sessionId, categoryId, name })
    .onConflictDoNothing({ target: [commandHqSessions.userId, commandHqSessions.sessionId] })
    .returning(SESSION_ROW_COLUMNS);
  // `onConflictDoNothing` returns nothing on the conflict path, so the existing row is fetched explicitly —
@@ -86,6 +86,18 @@ export const commandHqSessions = pgTable(
     * id spaces both agree on only sometimes.
     */
    sessionId: text('session_id').notNull(),
+    /**
+     * What the owner called it, held here rather than only in the transcript's summary record.
+     *
+     * The summary is the harness's, and it can only be written once the transcript file exists — which is
+     * after the first turn. So a list reading the transcript showed the opening brief until that turn ended,
+     * while the header beside it showed the name from local state. Two names for one commander, and every
+     * fix for it was a cache-invalidation trick timed against somebody else's write.
+     *
+     * The row is written when the commander is filed, before any of that. Nullable for the rows that predate
+     * this, which fall back to the transcript.
+     */
+    name: text('name'),
    /** Nullable — a commander may be uncategorised. `onDelete: 'set null'`: deleting a category uncategorises its commanders rather than deleting them. */
    categoryId: integer('category_id').references(() => commandHqCategories.id, { onDelete: 'set null' }),
    /** Should the platform keep re-arming this commander's watcher on every fire? See the file docstring. */
@@ -39,6 +39,7 @@ export * from './nudges';
 export * from './ai-provider-usage';
 export * from './anthropic-accounts';
 export * from './theme-favorites';
+export { forgetChatSessions, sessionKeyForTranscriptId } from './chat-session-cleanup';
 export * from './command-hq';
 export * from './dashboards';
 export * from './integrations';
@@ -16,6 +16,7 @@ import { resolveAuthToken } from './servers/auth-token';
 import { isWsProviderAllowed } from './servers/permissions/authorize';
 import { isTokenBlacklisted, getUserById } from 'officerdb';
 import { terminalWebsocket } from './servers/api/terminal/websocket';
+import { minesweeperWebsocket } from './servers/api/minesweeper/websocket';
 import { chatWebsocket } from './servers/api/chat/websocket';
 import { chatNotifyWebsocket } from './servers/api/chat/notify-delivery';
 import { registerChatPushNotifications } from './servers/api/chat/notify-push';
@@ -159,6 +160,7 @@ const handlers: Record<string, any> = {
  'chat-notify': chatNotifyWebsocket,
  'task-runner': taskRunnerWebsocket,
  pipeline: pipelineWebsocket,
+  minesweeper: minesweeperWebsocket,
  sidecar: sidecarWebsocket,
 };

@@ -185,6 +187,7 @@ const WS_ROUTES: Record<string, UpgradableProvider> = {
  '/api/tasks/run/ws': 'task-runner',
  '/api/tasks/pipeline/ws': 'pipeline',
  '/api/terminal/ws': 'terminal',
+  '/api/minesweeper/ws': 'minesweeper',
  '/api/chat/ws': 'chat',
  '/api/chat/notify/ws': 'chat-notify',
 };
@@ -363,7 +366,7 @@ console.log(
 * cannot serve is now a typecheck failure instead of a runtime one. `sidecar` and `dev-proxy` are
 * deliberately absent — they upgrade through their own handlers, not through here.
 */
-type UpgradableProvider = 'terminal' | 'chat' | 'chat-notify' | 'task-runner' | 'pipeline';
+type UpgradableProvider = 'terminal' | 'chat' | 'chat-notify' | 'task-runner' | 'pipeline' | 'minesweeper';

 async function upgradeWs(req: Request, server: any, provider: UpgradableProvider) {
  const token = new URL(req.url).searchParams.get('token');
@@ -1,5 +1,5 @@
 import type { Context } from 'hono';
-import { emitToSession } from './websocket';
+import { emitToSession, sessionKeyForTranscript } from './websocket';
 import { pauseBackgroundTask, restartBackgroundTask } from './task-restart';
 import { createRouter } from '../../create-router';
 import * as errors from '@@/custom-errors';
@@ -12,6 +12,7 @@ import {
  getChatNotifyPreference,
  getChatNotifyPreferences,
  setChatNotifyPreference,
+  forgetChatSessions,
 } from 'officerdb';
 import type { NotifyPreference } from 'officerdb/types';
 import { setNudge, getNudge, cancelNudge } from 'officerdb';
@@ -19,7 +20,6 @@ import {
  listClaudePwds,
  listClaudeSessions,
  listAllClaudeSessions,
-  withCommanderFlag,
  loadClaudeSession,
  loadClaudeSessionById,
  deleteClaudeSession,
@@ -58,7 +58,7 @@ import { readSttConfig } from '../server-settings/stt';
 * Reachable by a member since 2026-08-12 — see the note below on what replaced the wholesale refusal that
 * used to stand at the top of this router.
 */
-async function chatIdentity(user: { id: number; email: string }): Promise<ChatIdentity> {
+export async function chatIdentity(user: { id: number; email: string }): Promise<ChatIdentity> {
  const resolved = await resolveHomeDir(user.id);
  if (!resolved.ok) throw errors.FORBIDDEN(resolved.reason);
  return { email: user.email, home: resolved.home, osUser: resolved.osUser, isOwner: resolved.isOwner };
@@ -129,15 +129,10 @@ chatRouter.get('/sessions', async (ctx) => {
  // the row renderer) is indifferent to which directories the rows came from.
  const all = ctx.req.query('all') === '1';

-  // Which of these are commanders comes from the ROWS, not from where the transcript lives — a commander
-  // chooses its own working directory now, so the directory answers nothing. One query for the whole set.
-  const commanderIds = await listCommandHqSessionIds(user.id);
-  const claude = withCommanderFlag(all ? listAllClaudeSessions(who) : listClaudeSessions(who, cwd), commanderIds).map(
-    (s) => ({
+  const claude = (all ? listAllClaudeSessions(who) : listClaudeSessions(who, cwd)).map((s) => ({
    ...s,
    harness: 'claude' as const,
-    }),
-  );
+  }));
  // OpenCode's store is shared and unscoped, so for anyone but the owner this list is other people's
  // conversations. Empty rather than filtered: there is no per-user field to filter ON.
  //
@@ -156,6 +151,12 @@ chatRouter.get('/sessions', async (ctx) => {

    Never fatal — a database hiccup on a feature /chat does not otherwise depend on must not take the whole
    conversation list down with it, the same posture `getChatSessionModels` below already takes.
+
+    This route does NOT report `isCommander` on its rows, and that is not an omission. It used to: rows were
+    tagged from this same set a few lines above and then removed by it here, so the flag was false on every
+    row that survived — a field that could only ever lie, plus a second identical query to produce it. A list
+    that excludes commanders has nothing to say about which of its rows is one. `/chat/live` is where the
+    flag is real, because that route keeps both kinds.
  */
  const filed = await listCommandHqSessionIds(user.id).catch(() => new Set<string>());
  const sessions = merged.filter((s) => !filed.has(s.id));
@@ -365,7 +366,42 @@ chatRouter.get('/live', async (ctx) => {
    };
  });

-  return ctx.json({ sessions: [...sessions, ...openCodeSessions] });
+  const rows = [...sessions, ...openCodeSessions];
+
+  /*
+    `?kind=` — the split, done here rather than by each client.
+
+    The classification was already server-side; what was not was the FILTER, so every client repeated it.
+    That is fine for the web list, which has both tabs on screen, and wrong for a phone that swipes between
+    live chats one at a time and must simply never be handed a commander.
+
+    **The default is `agent`, not "everything".** A caller that says nothing gets ordinary chats, so the way
+    to receive a commander is to ask for one by name. That is the whole point: forgetting the parameter can
+    only ever under-report, never put a deploy commander into a swipe order that has no way to skip it. It
+    costs the two callers that DO want both an explicit `kind=all`, which is the right trade — they are few,
+    they are on screens built for it, and they are the ones in a position to notice if it is wrong.
+
+    Counts always describe the WHOLE set, whatever the filter. The web tabs show `Agents (n) /
+    Commanders (n)` side by side and both numbers have to be right whichever tab is open — a filter that
+    also hid the other count would force a second request to render one screen, which is how a server-side
+    filter ends up costing more than the client-side one it replaced.
+
+    An unrecognised `kind` is a 400, never a silent fallback. Plural forms are accepted because the client's
+    own type is already `'agents' | 'commanders'`, and the failure silence would buy is precise: a mistyped
+    `?kind=agents` resolving to something other than agents is the exact bug this exists to prevent.
+  */
+  const kind = ctx.req.query('kind') ?? 'agent';
+  const counts = {
+    agents: rows.filter((s) => !s.isCommander).length,
+    commanders: rows.filter((s) => s.isCommander).length,
+  };
+  if (!['agent', 'agents', 'commander', 'commanders', 'all'].includes(kind)) {
+    return ctx.json({ error: `Unknown kind '${kind}' — expected 'agent', 'commander' or 'all'` }, 400);
+  }
+  const wantCommanders = kind === 'commander' || kind === 'commanders';
+  const shown = kind === 'all' ? rows : rows.filter((s) => s.isCommander === wantCommanders);
+
+  return ctx.json({ sessions: shown, counts });
 });

 // DELETE /chat/sessions/:id[?cwd=] — remove a conversation from the owning harness's store. For a
@@ -376,8 +412,36 @@ chatRouter.delete('/sessions/:id', async (ctx) => {
  const id = ctx.req.param('id');
  const cwd = cwdOf(ctx, who.home);
  if (isOpenCodeSessionId(id) && !who.isOwner) return ctx.text('Not found', 404);
-  const ok = isOpenCodeSessionId(id) ? await deleteOpenCodeSession(id) : deleteClaudeSession(who, cwd, id);
-  if (!ok) return ctx.text('Not found', 404);
+  if (isOpenCodeSessionId(id)) {
+    if (!(await deleteOpenCodeSession(id))) return ctx.text('Not found', 404);
+    return ctx.json({ ok: true });
+  }
+
+  /*
+    Stop the harness BEFORE removing its file, and wait for it.
+
+    The `claude` CLI owns the transcript. Deleting it while a live session is still writing removes a file
+    that is written straight back, so the conversation reappears untitled on the next refresh — see
+    `killClaudeAndWait`. No live session means nothing to wait for, which is the ordinary case here.
+  */
+  const liveKey = sessionKeyForTranscript(id);
+  if (liveKey) await sidecar.killClaudeAndWait(liveKey, ctx.get('user').id);
+
+  // `.length`, not truthiness: this returns the IDS it removed and an empty array is truthy in JavaScript,
+  // so `if (removed)` would report a delete that found nothing as a success.
+  const removed = deleteClaudeSession(who, cwd, id);
+  if (!removed.length) return ctx.text('Not found', 404);
+
+  /*
+    The transcript is gone; forget what the platform stored ABOUT it. Four tables describe a conversation with
+    no foreign key — there is no row for one to reference — so nothing cascades and this has to be explicit.
+    One of them, `nudges`, is a live schedule: left behind it keeps firing at a conversation that is gone.
+
+    Two id spaces, and they are not interchangeable: three tables are keyed on the transcript id, while
+    `chat_session_events` is keyed on officer's session key. Undefined here is the normal case for an old
+    conversation — no live session holds it, so nothing is keyed on a key to remove.
+  */
+  await forgetChatSessions({ transcriptIds: removed, sessionKeys: liveKey ? [liveKey] : [] });
  return ctx.json({ ok: true });
 });

@@ -1,4 +1,4 @@
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { DATA_PATH, getCommandersDir } from '../../data-path';
 import {
  appendTextAs,
@@ -642,9 +642,12 @@ const findTranscript = (who: ChatIdentity, cwd: string, sessionId: string): stri
 * routinely (see `findTranscript`), and the wrong group would find no chain and silently delete one
 * part of several.
 */
-export function deleteClaudeSession(who: ChatIdentity, cwd: string, sessionId: string): boolean {
+export function deleteClaudeSession(who: ChatIdentity, cwd: string, sessionId: string): string[] {
  const filePath = findTranscript(who, cwd, sessionId);
-  if (!filePath) return false;
+  // The IDS it removed, not a boolean — empty means nothing was there. The caller needs them to forget the
+  // rows keyed on each one (`forgetChatSessions`), and a `/clear` chain is several transcripts presenting as
+  // one conversation: returning true would have told a caller to forget the head and orphan its parts.
+  if (!filePath) return [];

  const ownCwd = firstCwd(who.osUser, filePath);
  const ids = ownCwd ? chainFileIds(who, ownCwd, sessionId) : [sessionId];
@@ -653,7 +656,7 @@ export function deleteClaudeSession(who: ChatIdentity, cwd: string, sessionId: s
  // success — the conversation reappeared on the next refresh.
  const dir = dirname(filePath);
  for (const id of ids) removeAs(who.osUser, join(dir, `${id}.jsonl`));
-  return true;
+  return ids;
 }

 /**
@@ -994,25 +997,28 @@ function scanGroup(who: ChatIdentity, cwd: string): TranscriptSummary[] {
 *
 * Identity is now the `command_hq_sessions` row, which is the only thing that survives the cwd being free.
 * It is applied by the CALLER, because that requires a database read and this function is synchronous over a
- * directory scan — see `withCommanderFlag`.
+ * directory scan.
 */
+/**
+ * A transcript with no human or assistant turn in it is not a conversation.
+ *
+ * The harness writes metadata records — `last-prompt`, `ai-title`, `atis-latch` — into a transcript file
+ * independently of the conversation, and it will happily create the file to hold them. So a session that was
+ * deleted, or one that never sent anything, leaves a file containing only those three lines, which listed as
+ * "(untitled) · 0 msgs" and accumulated: four of them from one evening of testing.
+ *
+ * Filtered at the list rather than deleted on disk. The files are the harness's, it is entitled to write
+ * them, and a cleanup that raced it would be the same class of bug as the one that produced them.
+ */
+const hasConversation = (s: ClaudeSessionSummary): boolean => s.messageCount > 0;
+
 export function listClaudeSessions(who: ChatIdentity, cwd: string): ClaudeSessionSummary[] {
  return mergeChains(scanGroup(who, cwd))
    .map(publish)
+    .filter(hasConversation)
    .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 }

-/**
- * Mark which of these are commanders, from the rows rather than from where they live.
- *
- * One query per request rather than one per session: `listCommandHqSessionIds` returns the whole set for an
- * account, and a set membership test is what the per-row decoration needs. Commanders are few, so the set is
- * small; the alternative — a lookup per transcript — would turn one list into fifty queries.
- */
-export function withCommanderFlag<T extends { id: string }>(rows: T[], commanderIds: ReadonlySet<string>): T[] {
-  return rows.map((row) => (commanderIds.has(row.id) ? { ...row, isCommander: true } : row));
-}
-
 /**
 * Is this the default commanders directory?
 *
@@ -1033,6 +1039,36 @@ export function isCommandersDir(email: string, cwd: string): boolean {
  }
 }

+/**
+ * One session's list-shaped summary, found by id wherever it lives.
+ *
+ * For callers that hold a set of ids rather than a directory — Command HQ, which reads its commanders from
+ * `command_hq_sessions` and cannot scan for them any more now that each chooses its own working directory.
+ *
+ * Returns null when no transcript can be found, which is the same signal a directory scan gave by omission:
+ * a filed row whose conversation has been deleted. `purgeCommandHqSessions` is what tidies those.
+ *
+ * Deliberately NOT chain-aware in the way `listClaudeSessions` is. It reports the transcript addressed by
+ * this id; a `/clear` chain's head is what gets filed and what every surface addresses, so the tail is not
+ * something a caller here holds an id for.
+ */
+export function loadClaudeSessionSummaryById(who: ChatIdentity, sessionId: string): ClaudeSessionSummary | null {
+  const filePath = locateTranscript(who, sessionId);
+  if (!filePath) return null;
+
+  // `mtimeMs` becomes `updatedAt`, which is what every caller sorts on — so it has to be real, not zero.
+  // Taken from `listTranscriptsAs` over the transcript's OWN directory rather than a bare `statSync`: the
+  // file may belong to a member, and reading a member's tree needs the as-user path. One directory listing
+  // per commander, scoped to one group — the same call the old whole-directory scan made, once per row
+  // instead of once for all of them, which is the cost of letting each choose where it lives.
+  const group = basename(dirname(filePath));
+  const entry = listTranscriptsAs(who.osUser, claudeProjectsDir(who.home), group).find((f) => f.id === sessionId);
+  if (!entry) return null;
+
+  const summary = summarizeTranscript(who.osUser, filePath, sessionId, entry.mtimeMs);
+  return summary ? publish(summary) : null;
+}
+
 /**
 * Every conversation in every directory, newest first.
 *
@@ -78,11 +78,15 @@ const USAGE_ENDPOINT = 'https://api.anthropic.com/api/oauth/usage';
 /**
 * How long a reading is reused.
 *
- * Both halves are expensive in different ways — the endpoint rate-limits, and the scan reads ~90MB of JSONL —
- * and neither changes meaningfully inside a minute. Cached SEPARATELY so a network failure does not throw
- * away a good scan, and so opening and shutting the popover is not a request per flick.
+ * The transcript scan reads ~90MB of JSONL and its answer does not change meaningfully inside a minute, so
+ * it is still served from cache. It is also the same answer whichever account is signed in — it counts what
+ * this machine wrote, not what an account is allowed — which is why switching account does not need to
+ * invalidate it.
+ *
+ * **The limits have no TTL and are never served from cache.** They are per-account and they are the number
+ * somebody opens this panel to read, so a stale one is worse than a slow one. The store is kept for the
+ * failure path only — see `lastGoodLimits`.
 */
-const LIMITS_TTL_MS = 60_000;
 const SCAN_TTL_MS = 60_000;

 const claudeDir = (): string => process.env.CLAUDE_CONFIG_DIR?.trim() || join(getOwnerHomeDir(''), '.claude');
@@ -142,7 +146,21 @@ export async function readAccountEmail(): Promise<string | null> {

 type LimitsResult = { limits: UsageLimit[]; problem?: string };

-let limitsCache: { at: number; result: LimitsResult } | null = null;
+/*
+  Last good reading PER ACCOUNT, and used only when a probe fails.
+
+  This was a TTL cache keyed on nothing, and the consequence was the whole feature lying. Switching account
+  changes which credential `readOauthLogin` returns, but a cached entry was served regardless — so the panel
+  showed the previous account's percentages under the new account's name for the length of the TTL, and the
+  failure fallback served them for as long as the probe kept failing. Reported by the owner: maxed out on one
+  account, switched, and the numbers did not move.
+
+  So there is no TTL any more. Every request probes, because these percentages are the entire point of the
+  panel and a stale one is worse than a slow one. What survives is the fallback, now keyed on the account it
+  was measured for, so a flaky request degrades to that account's own last reading rather than to a blank
+  panel or — far worse — to somebody else's numbers.
+*/
+const lastGoodLimits = new Map<string, { at: number; result: LimitsResult }>();

 const asPercent = (value: unknown): number => {
  const n = Number(
@@ -303,20 +321,22 @@ async function collectLimits(): Promise<LimitsResult & { plan: string | null; me
    return { limits: [], plan: null, measuredAt: now, problem: 'Claude Code is not signed in on this machine.' };
  }

-  if (limitsCache && now - limitsCache.at < LIMITS_TTL_MS) {
-    return { ...limitsCache.result, plan: login.plan, measuredAt: limitsCache.at };
-  }
+  // Which account this reading belongs to. Null would make every account share one entry, which is the bug
+  // this key exists to prevent, so an unattributable reading gets no fallback rather than a shared one.
+  const account = await readAccountEmail();

  const fresh = await probeLimits(login.accessToken);
  if (fresh.limits.length) {
-    limitsCache = { at: now, result: fresh };
+    if (account) lastGoodLimits.set(account, { at: now, result: fresh });
    return { ...fresh, plan: login.plan, measuredAt: now };
  }

-  // A failed probe falls back to the last good reading rather than to nothing — the numbers are minutes old
-  // at worst, and a panel that goes blank on one flaky request is worse than one that is slightly behind.
-  const stale = limitsCache?.result.limits.filter((l) => windowStillOpen(l, now)) ?? [];
-  return { limits: stale, plan: login.plan, measuredAt: limitsCache?.at ?? now, problem: fresh.problem };
+  // A failed probe falls back to THIS account's last good reading rather than to nothing — minutes old at
+  // worst, and a panel that blanks on one flaky request is worse than one slightly behind. Windows that have
+  // since reset are dropped: a stale 78% would misreport an allowance that is now untouched.
+  const previous = account ? lastGoodLimits.get(account) : undefined;
+  const stale = previous?.result.limits.filter((l) => windowStillOpen(l, now)) ?? [];
+  return { limits: stale, plan: login.plan, measuredAt: previous?.at ?? now, problem: fresh.problem };
 }

 // ── Local transcript scan ──
@@ -76,6 +76,20 @@ export type ClientMessage =
       * first turn is the first moment the preference can be acted on OR written down.
       */
      planMode?: boolean;
+      /**
+       * The name the owner chose for a COMMANDER before its first message.
+       *
+       * Claude Code will not accept a name for a new session — the harness names its own from the first
+       * prompt — so the platform renames the transcript the moment it exists. Carried on the turn rather
+       * than sent afterwards because it must not depend on a browser still being open: the name was chosen
+       * before anything was said, and losing it to a closed tab would leave a commander called after
+       * whatever it happened to say first.
+       *
+       * Applied once, by `fileAsCommander`, via `renameClaudeSession` — which writes a `summary` record and
+       * therefore an EXPLICIT title, and an explicit title is never overwritten by `ai-title` or by the
+       * first-message fallback.
+       */
+      commanderName?: string;
      /**
       * This turn is arming a Command HQ watcher — see `docs/command-hq.md` → "The watcher loop". Set only
       * by `BackgroundJobDialog` submitting a `handoff` job inside a commander (`isCommander` true); every
@@ -15,12 +15,7 @@ import { sendClaudeCodeStreaming } from '@@/channels/send-claude-code';
 import { sendOpenCodeStreaming } from '@@/channels/send-opencode';
 import * as sidecar from '@@/sidecar-registry';
 import { join } from 'path';
-import {
-  getOwnerHomeDir,
-  getEmailAccountsDir,
-  findEmailAccountName,
-  getCommandersDir,
-} from '../../../servers/data-path';
+import { getOwnerHomeDir, getEmailAccountsDir, findEmailAccountName } from '../../../servers/data-path';
 import { attachedFilePaths } from './attached-files';
 import {
  getUserSettings,
@@ -37,6 +32,8 @@ import {
 } from 'officerdb';
 import { resolveHomeDir } from '@@/user-home';
 import { renameClaudeSession, type ChatIdentity } from './claude-sessions';
+import { chatIdentity } from './chat';
+import { commanderBlock } from '../command-hq/commander-block';
 import { claudeLoginState } from '@@/os-user-claude';
 import { mkdirSync } from 'node:fs';
 import { logger } from './logger';
@@ -154,16 +151,25 @@ async function resolveChatCwd(
  userId: number,
  home: string,
 ): Promise<string> {
-  // Every commander a user has shares ONE directory — never a client-chosen one, and never per-commander
-  // (see `getCommandersDir`). `msg.cwd` is ignored on this branch entirely, the same posture the identity
-  // half of a turn already takes: resolved by the platform, never trusted from the caller.
-  //
-  // `mkdirSync` — synchronous, so this returns only once the directory genuinely exists, the same pattern
-  // `resolveEmailCwd` below already uses. No race: unlike the rejected per-commander design, this directory
-  // is shared and only the very first commander ever needs the mkdir to do anything; `recursive: true`
-  // makes every call after that a no-op stat.
+  /*
+    A commander runs where the owner chose, and the choice is required.
+
+    This used to force `getCommandersDir(email)` and ignore `msg.cwd` entirely — every commander shared one
+    empty directory whose only job was to BE a cwd, because the cwd was how a commander was recognised.
+    Identity is the `command_hq_sessions` row now, so the directory is free to be useful: a commander that
+    works on the platform can live in the platform checkout, where its relative paths mean something and its
+    transcripts sit beside the work they are about.
+
+    The chosen path is resolved through `resolveCwd(home, …)`, the same containment the ordinary chat branch
+    below uses — so "client-chosen" still does not mean "anywhere". A commander cannot be pointed outside
+    the account's own tree by a crafted message.
+
+    No fallback to the old shared directory when nothing is chosen: the UI requires a directory before the
+    first message can be sent, and a silent default would be a commander running somewhere nobody picked.
+    Falling back to the account's home is the honest last resort for a caller that predates the requirement.
+  */
  if (msg.context === 'command-hq') {
-    const dir = getCommandersDir(email);
+    const dir = msg.cwd?.trim() ? resolveCwd(home, msg.cwd) : home;
    mkdirSync(dir, { recursive: true });
    return dir;
  }
@@ -351,6 +357,15 @@ function createMessageHandler(
  resumeSessionId?: string,
  planMode?: boolean,
  commandHq?: boolean,
+  /**
+   * The name the owner chose before the conversation started, for a commander.
+   *
+   * Claude Code will not accept a name for a NEW session — the harness names its own — so the platform
+   * renames it the moment the transcript exists. Done here rather than by the client because it must not
+   * depend on a browser still being open: the name was chosen before the first message, and losing it to a
+   * closed tab would leave a commander called after whatever it happened to say first.
+   */
+  commanderName?: string,
 ) {
  /*
    The model messages are ATTRIBUTED to, which is not always the model the turn asked for.
@@ -450,14 +465,51 @@ function createMessageHandler(
    Fire-and-forget, swallowed failure, same posture as `record`: a database hiccup here must not be a
    reason a chat turn fails.
  */
+  // Whether the chosen name has actually reached the transcript. False until a rename RETURNS true — see
+  // the retry note inside `fileAsCommander`.
+  let commanderNamed = false;
+
  const fileAsCommander = (): void => {
    if (!commandHq || !transcriptId) return;
    const userId = sessionManager.getSession(sessionId)?.userId;
    if (!userId) return;
-    void createCommandHqSession(userId, transcriptId).catch((err: unknown) => {
+    const filedId = transcriptId;
+    // The name goes in with the row, not only to the transcript: the list reads it from here and is
+    // right immediately, rather than waiting on a summary record the harness cannot write until the
+    // first turn has finished.
+    void createCommandHqSession(userId, filedId, null, commanderName?.trim() || null)
+      .then(async () => {
+        /*
+          The chosen name, applied once — and RETRIED, because the first attempt usually fails.
+
+          `fileAsCommander` runs on `session:claude`, which arrives at the START of a turn: the transcript
+          file may not be on disk yet, and `renameClaudeSession` returns false when it cannot find one. It
+          returns a boolean that nothing was checking, so the name was silently dropped and the conversation
+          kept the harness's own `ai-title` — which is exactly what the first live test showed.
+
+          So the attempt is recorded and retried at the end of the turn, by which point the file certainly
+          exists. Idempotent: once it succeeds, `commanderNamed` stops it repeating.
+
+          It still writes a `summary` record, which sets `hasExplicitTitle` — and an explicit title is never
+          overwritten by `ai-title` or by the first-message fallback. So it wins whenever it lands.
+        */
+        if (!commanderName?.trim() || commanderNamed) return;
+        // The same identity resolution every chat route uses, rather than a second copy of it: it is what
+        // decides the home and the OS user, and a rename writes a file as that user.
+        const user = await getUserById(userId).catch(() => null);
+        if (!user?.email) return;
+        const who = await chatIdentity({ id: userId, email: user.email }).catch(() => null);
+        if (!who) return;
+        // `who.home` as the hint, not the old shared commanders directory: a commander chooses its own
+        // working directory now, so that path is usually wrong. `findTranscript` treats the cwd as a HINT
+        // and locates the transcript wherever it actually is — so this works either way, and passing a
+        // path we know is probably wrong would be the kind of thing that reads as intent later.
+        commanderNamed = renameClaudeSession(who, who.home, filedId, commanderName.trim());
+      })
+      .catch((err: unknown) => {
        logger.warn('Could not file this session as a commander', {
          sessionId,
-        transcriptId,
+          transcriptId: filedId,
          error: err instanceof Error ? err.message : String(err),
        });
      });
@@ -511,6 +563,8 @@ function createMessageHandler(
    // written on its very first turn rather than on its second.
    if (msg.type === 'session:claude' && msg.claudeSessionId) {
      transcriptId = msg.claudeSessionId;
+      // The platform's own copy of the mapping — see `transcriptIdBySessionKey`.
+      transcriptIdBySessionKey.set(sessionId, msg.claudeSessionId);
      record();
      fileAsCommander();
    }
@@ -519,6 +573,9 @@ function createMessageHandler(
      record();
      fileAsCommander();
    }
+    // And retried on every result until the name lands. The first attempt runs before the transcript file
+    // exists, so the end of the first turn is the earliest a rename can succeed.
+    if (msg.type === 'result' && commandHq && !commanderNamed) fileAsCommander();

    /*
      The watcher loop — see `docs/command-hq.md` → "The watcher loop" and `handoffContract` in
@@ -734,6 +791,11 @@ async function handleChat(
  msg: {
    prompt: string;
    displayText?: string;
+    /**
+     * The owner pressed Start instead of typing an opener — see `commanderBlock`. Carried on the message
+     * rather than derived, because the only thing that can know it is the client that rendered the button.
+     */
+    selfStarted?: boolean;
    sessionId?: string;
    model?: string;
    cwd?: string;
@@ -851,6 +913,32 @@ export type ClaudeTurnOutcome = { ok: true; transcriptId: string } | { ok: false
 * generic timeout: the reasons below (member not signed in, Claude not installed, spawn failure) are the
 * same reasons a websocket caller already sees via `sendToClient`, just mirrored to a second listener.
 */
+/**
+ * Officer's session key → Claude's transcript id, for the platform's own use.
+ *
+ * The sidecar keeps this mapping and the platform cannot read it: `state.ts` holds it in the sidecar's
+ * memory, and re-loading its file from here does not find a live session. So the platform keeps its own,
+ * filled from the `session:claude` message it already handles.
+ *
+ * This is the third distinct place the two ids have caused a bug today. The mapping is not derivable — it is
+ * announced, once, mid-turn — so anything needing it either records it when it passes or does without.
+ */
+const transcriptIdBySessionKey = new Map<string, string>();
+
+/** The mapping read backwards, for callers holding a transcript id — the delete route, mainly. */
+export function sessionKeyForTranscript(transcriptId: string): string | undefined {
+  for (const [key, id] of transcriptIdBySessionKey) if (id === transcriptId) return key;
+  return undefined;
+}
+
+/**
+ * Sessions already told what they are and where to record it.
+ *
+ * In memory, keyed on officer's session id: a restart re-briefs, which costs a few hundred tokens on one
+ * turn and is the safe direction — a commander that was never told is one that cannot be stopped.
+ */
+const briefedSessions = new Set<string>();
+
 export async function startClaudeTurn(params: {
  email: string;
  username: string;
@@ -861,6 +949,11 @@ export async function startClaudeTurn(params: {
  msg: {
    prompt: string;
    displayText?: string;
+    /**
+     * The owner pressed Start instead of typing an opener — see `commanderBlock`. Carried on the message
+     * rather than derived, because the only thing that can know it is the client that rendered the button.
+     */
+    selfStarted?: boolean;
    groupSlug?: string;
    context?: string;
    contextId?: string;
@@ -869,12 +962,44 @@ export async function startClaudeTurn(params: {
    images?: PromptImage[];
    resumeSessionId?: string;
    planMode?: boolean;
+    /** See `commanderName` on the wire type — the name chosen before a commander's first message. */
+    commanderName?: string;
    armWatcher?: boolean;
  };
  effectivePrompt: string;
  onOutcome?: (outcome: ClaudeTurnOutcome) => void;
 }): Promise<void> {
-  const { email, username, userId, ws, sessionId, model, msg, effectivePrompt, onOutcome } = params;
+  const { email, username, userId, ws, sessionId, model, msg, onOutcome } = params;
+
+  /*
+    A commander is told its record paths ON A TURN, not in the system preamble.
+
+    The preamble is built inside `createSession`, which runs ONCE — on a conversation's first turn. For a
+    commander that is precisely the turn where the block cannot exist: it has no `command_hq_sessions` row
+    and no transcript id yet, so `commanderBlock` returns null, and every later turn reuses the same session
+    and never rebuilds the preamble. So a commander never received the block at all, and its loop had no
+    paths to record itself at. Its own test caught it: it armed a perfectly good watcher and wrote no
+    `loop-pid`.
+
+    Riding `effectivePrompt` instead. That is the string the model sees; `displayText` is what the transcript
+    shows — the same seam the background-job dialog already uses to send a hidden preamble — so this reaches
+    the agent without appearing in the conversation.
+
+    Once per session, on the first turn where the block resolves, which is the first turn after the commander
+    is filed. It stays available afterwards because it is in the conversation's own history from then on.
+  */
+  let effectivePrompt = params.effectivePrompt;
+  if (!briefedSessions.has(sessionId)) {
+    const block = await commanderBlock({
+      userId,
+      sessionId: transcriptIdBySessionKey.get(sessionId) ?? msg.resumeSessionId ?? null,
+      selfStarted: msg.selfStarted === true,
+    });
+    if (block) {
+      briefedSessions.add(sessionId);
+      effectivePrompt = `${block}\n\n---\n\n${effectivePrompt}`;
+    }
+  }
  const fail = (error: string) => {
    sendToClient(ws, { type: 'error', message: error });
    onOutcome?.({ ok: false, error });
@@ -958,6 +1083,7 @@ export async function startClaudeTurn(params: {
    msg.resumeSessionId,
    msg.planMode,
    msg.context === 'command-hq',
+    msg.commanderName,
  );
  // Wrapped rather than passed straight to the spawn call, so `onOutcome` sees the transcript id at the
  // exact moment `fileAsCommander` (inside `createMessageHandler`) does — both react to the same
@@ -1035,6 +1161,11 @@ async function handleClaudeCodeChat(
  msg: {
    prompt: string;
    displayText?: string;
+    /**
+     * The owner pressed Start instead of typing an opener — see `commanderBlock`. Carried on the message
+     * rather than derived, because the only thing that can know it is the client that rendered the button.
+     */
+    selfStarted?: boolean;
    groupSlug?: string;
    context?: string;
    contextId?: string;
@@ -1058,6 +1189,11 @@ async function handleOpenCodeChat(
  msg: {
    prompt: string;
    displayText?: string;
+    /**
+     * The owner pressed Start instead of typing an opener — see `commanderBlock`. Carried on the message
+     * rather than derived, because the only thing that can know it is the client that rendered the button.
+     */
+    selfStarted?: boolean;
    groupSlug?: string;
    context?: string;
    contextId?: string;
@@ -1263,13 +1399,20 @@ function handlePlanDecision(
 ): void {
  const sessionId = wsToSessionMap.get(ws);
  if (!sessionId) return;
-  sidecar.decideClaudePlan({
+  const delivered = sidecar.decideClaudePlan({
    sessionKey: sessionId,
    userId: ws.data.userId,
    requestId: msg.requestId,
    approve: msg.approve,
    feedback: msg.feedback,
  });
+  // Same drop as `handleQuestionAnswer`, same spinning card — see `sendFire`.
+  if (!delivered) {
+    sendToClient(ws, {
+      type: 'error',
+      message: 'The agent is not connected right now, so that decision did not reach it. Try again in a moment.',
+    });
+  }
 }

 /**
@@ -1283,12 +1426,29 @@ function handlePlanDecision(
 function handleQuestionAnswer(ws: ServerWebSocket<WSData>, msg: { toolCallId: string; answer: string }): void {
  const sessionId = wsToSessionMap.get(ws);
  if (!sessionId) return;
-  sidecar.answerClaudeQuestion({
+  /*
+    A dropped answer has to reach the person who sent it.
+
+    `sendFire` does nothing when no sidecar is registered, and that window is real — every restart of this
+    process has one while the agent reconnects. The answer vanished with no log and no error, so the
+    question card spun on, which is indistinguishable from a slow agent. The only move left was to send
+    another message, which is the worst possible thing to do to a waiting tool call.
+
+    The agent's own handler already reports the failures it CAN see (no such session, question no longer
+    waiting). This is the one it cannot, because the command never arrives.
+  */
+  const delivered = sidecar.answerClaudeQuestion({
    sessionKey: sessionId,
    userId: ws.data.userId,
    toolCallId: msg.toolCallId,
    answer: msg.answer,
  });
+  if (!delivered) {
+    sendToClient(ws, {
+      type: 'error',
+      message: 'The agent is not connected right now, so that answer did not reach it. Try again in a moment.',
+    });
+  }
 }

 async function handleStop(ws: ServerWebSocket<WSData>): Promise<void> {
@@ -30,6 +30,14 @@ type CommanderBlockParams = {
  userId: number;
  /** Claude's transcript id — what a commander is keyed on everywhere. */
  sessionId: string | null;
+  /**
+   * The owner pressed Start rather than typing an opening message.
+   *
+   * They supplied a name and a working directory and nothing else, so there is no request to act on and
+   * the commander has to run the interview itself. Only ever true on the turn the button sends — a
+   * commander asked something later is an ordinary conversation and must not restart its intake.
+   */
+  selfStarted?: boolean;
 };

 export async function commanderBlock(params: CommanderBlockParams): Promise<string | null> {
@@ -66,5 +74,20 @@ export async function commanderBlock(params: CommanderBlockParams): Promise<stri
    'about it — arming before that is arming a guess, and a wrong condition either never fires or fires',
    'constantly and is found out days later. If you were given no paths above, you ARE on your first turn:',
    'that is what their absence means. Ask, and arm once it is agreed.',
+    /*
+      The button case. A pointer, not the interview itself: the questions live in the skill, which is
+      re-read from disk on every run, so rewording one costs nothing. The same words here would cost a
+      `pm2 restart officer` every time — and this file is the wrong home for doctrine that will be
+      edited far more often than the mechanism around it.
+    */
+    ...(params.selfStarted
+      ? [
+          '',
+          '**Nobody has told you what they want yet.** They gave a name and a working directory and',
+          'pressed Start, which is a request to run the interview — not a request to do anything else.',
+          'Read the **Commanders** skill now and follow "When you started yourself": orient in this',
+          'directory first, then open with what you found and ONE question.',
+        ]
+      : []),
  ].join('\n');
 }
@@ -5,18 +5,23 @@ import { checkBudget } from '../sub-agents/budget';
 import * as errors from '@@/custom-errors';
 import { resolveHomeDir } from '@@/user-home';
 import { getCommandersDir, toShellUsername } from '@@/data-path';
-import { getChatEventsSince, ingestSpawnedChildren } from 'officerdb';
+import { forgetChatSessions, getChatEventsSince, ingestSpawnedChildren, sessionKeyForTranscriptId } from 'officerdb';
+import * as sidecar from '@@/sidecar-registry';
+import { findSessionKeyByClaudeSession } from '@@/sidecar/claude/state';
+import { sessionKeyForTranscript } from '../chat/websocket';
 import {
  clearSpawnedRecord,
  listSpawnedSessions,
  loopPidPath,
  spawnedRecordPath,
  stopCommanderProcesses,
+  liveLoopPid,
 } from './spawned';
 import type { ServerMessage } from '../chat/types';
 import {
  listClaudeSessions,
  loadClaudeSessionById,
+  loadClaudeSessionSummaryById,
  renameClaudeSession,
  deleteClaudeSession,
  type ChatIdentity,
@@ -62,11 +67,17 @@ import {
 *
 * ── Where commanders live ──
 *
- * Every commander shares ONE working directory per user — `getCommandersDir(email)` — never one per
- * commander. That means listing a user's commanders is exactly `listClaudeSessions` (the same function
- * `/chat` uses for its own per-directory list) pointed at that one directory, filtered to sessions with a
- * `command_hq_sessions` row. No new session-scanning code exists here; this router is a client of the same
- * transcript reader `/chat` already is.
+ * **Wherever the owner chose.** Each commander names its own working directory when it is created, and that
+ * directory is where its relative paths resolve and where its transcripts are grouped.
+ *
+ * It was one shared directory per user until 2026-08-22, because the directory WAS the identity — the only
+ * way to tell a commander from an ordinary chat. Identity is the `command_hq_sessions` row now, so the
+ * directory became free to be useful, and a commander that works on the platform can live in the platform.
+ *
+ * The consequence for this router is that listing is no longer a directory scan. It reads its rows and loads
+ * each transcript BY ID (`loadClaudeSessionSummaryById`) — a handful of lookups rather than one walk. A row
+ * whose transcript cannot be found anywhere is treated as absent, exactly as a missing file in the old scan
+ * was, and `POST /purge` is what tidies those.
 */

 async function commandHqIdentity(user: { id: number; email: string }): Promise<ChatIdentity> {
@@ -201,12 +212,24 @@ commandHqRouter.get('/commanders', async (ctx) => {
  const categoryParam = ctx.req.query('category');
  const categoryId = categoryParam === undefined ? undefined : categoryParam === 'none' ? null : Number(categoryParam);

-  const [rows, live] = await Promise.all([
-    listCommandHqSessions(user.id, categoryId),
-    listClaudeSessions(who, getCommandersDir(who.email)),
-  ]);
+  /*
+    Each commander's transcript is loaded BY ID, not found by scanning one directory.

-  const liveById = new Map(live.map((s) => [s.id, s]));
+    It used to be `listClaudeSessions(who, getCommandersDir(...))` — every commander lived in one place, so
+    one scan found them all and a row without a match there was a row whose transcript had been deleted. A
+    commander chooses its own working directory now, so that scan finds only the ones that happen to still
+    live in the old shared folder and would silently hide every other.
+
+    One `locateTranscript` per row instead of one scan for all of them. Commanders are few — this is a
+    handful of stats, not a directory walk per row — and a row whose transcript cannot be found anywhere is
+    still treated exactly as before: absent, which is what `purgeCommandHqSessions` exists to tidy.
+  */
+  const rows = await listCommandHqSessions(user.id, categoryId);
+  const summaries = rows
+    .map((row) => loadClaudeSessionSummaryById(who, row.sessionId))
+    .filter((s): s is NonNullable<typeof s> => !!s);
+
+  const liveById = new Map(summaries.map((s) => [s.id, s]));
  const filed = rows.filter((row) => liveById.has(row.sessionId));

  const [tagsByRow, lastFiredByRow, runningById, costByRow] = await Promise.all([
@@ -226,10 +249,17 @@ commandHqRouter.get('/commanders', async (ctx) => {
  const commanders: CommanderSummary[] = filed
    .map((row) => ({
      ...liveById.get(row.sessionId)!,
+      // The row's name wins over the transcript's. It is written when the commander is filed, while the
+      // summary record cannot exist until the first turn ends — so until then the transcript still reports
+      // the opening brief, and the row is the only source that is right from the start.
+      ...(row.name ? { title: row.name } : {}),
      categoryId: row.categoryId,
      tagIds: tagsByRow.get(row.id) ?? [],
      running: runningById.get(row.sessionId) ?? false,
-      watcherArmed: row.watcherArmed,
+      // The pid file is the FACT; `watcher_armed` is a claim only one path sets. A commander that started
+      // its loop as a plain background job recorded its pid correctly and still reported unarmed, so the
+      // grid offered nothing to stop — which is the one thing this column exists to make possible.
+      watcherArmed: row.watcherArmed || liveLoopPid(who.email, row.sessionId) !== null,
      watcherArmedAt: row.watcherArmedAt,
      watcherStoppedAt: row.watcherStoppedAt,
      watcherLastFiredAt: lastFiredByRow.get(row.id) ?? null,
@@ -272,8 +302,10 @@ commandHqRouter.get('/commanders', async (ctx) => {
 commandHqRouter.post('/commanders/new', async (ctx) => {
  const user = ctx.get('user');
  const body = await ctx.req
-    .json<{ prompt?: string; displayText?: string; categoryId?: number | null }>()
-    .catch(() => ({}) as { prompt?: string; displayText?: string; categoryId?: number | null });
+    .json<{ prompt?: string; displayText?: string; categoryId?: number | null; cwd?: string; name?: string }>()
+    .catch(
+      () => ({}) as { prompt?: string; displayText?: string; categoryId?: number | null; cwd?: string; name?: string },
+    );
  const prompt = body.prompt?.trim();
  if (!prompt) throw errors.BAD_REQUEST('prompt is required');

@@ -309,7 +341,17 @@ commandHqRouter.post('/commanders/new', async (ctx) => {
      ws: null,
      sessionId,
      model,
-      msg: { prompt, displayText: body.displayText?.trim() || undefined, context: 'command-hq' },
+      msg: {
+        prompt,
+        displayText: body.displayText?.trim() || undefined,
+        context: 'command-hq',
+        // Where this commander runs, and its name. Both are chosen before the first message — the UI makes
+        // them mandatory — so this programmatic path takes them too rather than inventing a default. An
+        // absent cwd falls back to the account's home in `resolveChatCwd`, which is the honest last resort
+        // for a caller that predates the requirement.
+        ...(body.cwd?.trim() ? { cwd: body.cwd.trim() } : {}),
+        ...(body.name?.trim() ? { commanderName: body.name.trim() } : {}),
+      },
      effectivePrompt: prompt,
      onOutcome: settle,
    });
@@ -329,7 +371,9 @@ commandHqRouter.post('/commanders/new', async (ctx) => {
  await createCommandHqSession(user.id, outcome.transcriptId, body.categoryId ?? null);
  await setCommandHqSessionCategory(user.id, outcome.transcriptId, body.categoryId ?? null);

-  return ctx.json({ sessionId: outcome.transcriptId, cwd: getCommandersDir(user.email) });
+  // The cwd it ACTUALLY ran in, from the spawn outcome — not a guess at the old shared directory, which is
+  // no longer where a commander necessarily lives.
+  return ctx.json({ sessionId: outcome.transcriptId, cwd: body.cwd?.trim() ?? null });
 });

 /**
@@ -357,10 +401,11 @@ commandHqRouter.get('/commanders/:sessionId', async (ctx) => {
  ]);
  return ctx.json({
    sessionId: row.sessionId,
+    name: row.name,
    categoryId: row.categoryId,
    tagIds: tagsByRow.get(row.id) ?? [],
    running,
-    watcherArmed: row.watcherArmed,
+    watcherArmed: row.watcherArmed || liveLoopPid(who.email, row.sessionId) !== null,
    watcherArmedAt: row.watcherArmedAt,
    watcherStoppedAt: row.watcherStoppedAt,
    watcherLastFiredAt: lastFiredByRow.get(row.id) ?? null,
@@ -424,8 +469,10 @@ commandHqRouter.post('/commanders', async (ctx) => {
  const sessionId = body.sessionId?.trim();
  if (!sessionId) throw errors.BAD_REQUEST('sessionId is required');

-  const live = listClaudeSessions(who, getCommandersDir(who.email));
-  if (!live.some((s) => s.id === sessionId)) throw errors.NOT_FOUND('no such session in the commanders directory');
+  // Located by id wherever it lives, not required to be in the old shared directory. A commander chooses
+  // its own working directory, so "is it in the commanders folder" stopped being a meaningful check — and
+  // as a GUARD it only ever established that the transcript exists, which this still does.
+  if (!loadClaudeSessionSummaryById(who, sessionId)) throw errors.NOT_FOUND('no such conversation');

  const row = await createCommandHqSession(user.id, sessionId, body.categoryId ?? null);
  return ctx.json(row);
@@ -458,7 +505,9 @@ commandHqRouter.patch('/commanders/:sessionId', async (ctx) => {
    await setCommandHqSessionCategory(user.id, sessionId, body.categoryId);
  }
  if (body.name !== undefined) {
-    const ok = renameClaudeSession(who, getCommandersDir(who.email), sessionId, body.name.trim());
+    // `who.home` as the HINT only — `findTranscript` locates the transcript wherever it actually is, and a
+    // commander's directory is its own choice now.
+    const ok = renameClaudeSession(who, who.home, sessionId, body.name.trim());
    if (!ok) throw errors.NOT_FOUND('transcript not found');
  }
  if (body.watcherArmed === false) {
@@ -504,7 +553,45 @@ commandHqRouter.delete('/commanders/:sessionId', async (ctx) => {
  const row = await getCommandHqSession(user.id, sessionId);
  if (!row) throw errors.NOT_FOUND('not a commander');

-  // 1. Everything this commander is still running.
+  /*
+    1. Everything this commander is still running — the SESSION first, then the loop.
+
+    Killing the loop alone is not enough, and its own test proved it: the loop is a grandchild of the
+    commander's `claude` process, so ending the loop leaves the session alive — and a live session REWRITES
+    its transcript after the file is deleted. Twice tonight a deleted commander's transcript reappeared, and
+    twice it read as the delete having failed.
+
+    `killClaudeSession` takes officer's session key while this route holds a transcript id, so the map is
+    read backwards — `findSessionKeyByClaudeSession`, which exists for the same reason a refreshed browser
+    holds only the uuid. Ending the session takes its children with it, and the pid-based stop below then
+    catches anything that outlived its parent.
+  */
+  // Same mapping problem as the briefing: the sidecar's map is not visible from here, so the platform's own
+  // is asked first and the sidecar's is kept as a fallback for a session that predates this process.
+  /*
+    Third fallback, and the only one that survives a restart.
+  
+    Both maps above are in-memory and answer only for a session younger than this process. After a
+    restart they both return undefined, no kill is sent, and the transcript is deleted while the harness
+    is still writing — so it writes it back and the deleted commander returns as an untitled stub. Seen
+    twice tonight, after the fix that was meant to prevent exactly this.
+  */
+  const sessionKey =
+    sessionKeyForTranscript(sessionId) ??
+    findSessionKeyByClaudeSession(sessionId, user.id) ??
+    (await sessionKeyForTranscriptId(sessionId).catch(() => undefined));
+  /*
+    Across the socket, and AWAITED — both halves matter.
+
+    `killClaudeSession` from `claude-manager` was called directly here, and it could only ever return false:
+    the session map lives in the `officer-claude-code` process and this route runs in `officer`, so it was
+    reading an empty map in the wrong process. The kill silently never happened.
+
+    Awaited because the next thing this route does is delete the transcript, and the `claude` CLI owns that
+    file. Deleting it while the CLI is still unwinding removes a file that is written straight back — which
+    is exactly how a deleted commander came back as an untitled ordinary chat.
+  */
+  const sessionKilled = sessionKey ? await sidecar.killClaudeAndWait(sessionKey, user.id) : false;
  const stopped = stopCommanderProcesses(who.email, sessionId);

  // 2. Everything it spawned. Best-effort per child: one transcript that has already been cleaned up must
@@ -515,14 +602,23 @@ commandHqRouter.delete('/commanders/:sessionId', async (ctx) => {
    (c) => c.spawnedSessionId,
  );
  let childrenDeleted = 0;
+  // Every transcript id actually removed — the commander's and its children's, chains included. Collected
+  // rather than assumed, because a `/clear` chain is several ids behind one conversation.
+  const forgotten: string[] = [];
  for (const child of children) {
    try {
      // A spawned agent runs in the platform checkout, not the commanders directory, so its transcript
      // lives in that project's group — the same lookup `/chat/sessions/:id` falls back to.
      // The cwd is a HINT here, not an authority — `deleteClaudeSession` falls back to locating the
-      // transcript wherever it actually is, which is what makes this work for a child that ran in the
-      // platform checkout rather than the commanders directory.
-      if (deleteClaudeSession(who, getCommandersDir(who.email), child)) childrenDeleted += 1;
+      // transcript wherever it actually is, which is what makes this work for a child that ran in a
+      // different directory from its parent.
+      //
+      // `.length`, not truthiness: this returns the ids it removed, and an empty array is truthy.
+      const removedChild = deleteClaudeSession(who, who.home, child);
+      if (removedChild.length) {
+        childrenDeleted += 1;
+        forgotten.push(...removedChild);
+      }
    } catch {
      // Already gone, or never written. Counted as not-deleted rather than failing the request.
    }
@@ -530,12 +626,38 @@ commandHqRouter.delete('/commanders/:sessionId', async (ctx) => {
  clearSpawnedRecord(who.email, sessionId);

  // 3. The commander itself.
-  deleteClaudeSession(who, getCommandersDir(who.email), sessionId);
+  forgotten.push(...deleteClaudeSession(who, who.home, sessionId));
  await deleteCommandHqSession(user.id, sessionId);

+  /*
+    Forget what the platform stored ABOUT every transcript that just went — the commander's and its
+    children's, in one call.
+
+    The `command_hq_*` tables cascade from the row, because they reference it. These four do not: they are
+    keyed on a transcript id, which is a FILE, so there is no row for them to reference and nothing to
+    cascade from. Left behind they are mostly inert — a model, a bell preference, a durable copy of turn
+    output — except `nudges`, which is a live schedule that would keep firing at a conversation that no
+    longer exists.
+  */
+  /*
+    `sessionKeys` carries the commander's own key and nothing else, on purpose. Children are spawned by
+    `claude -p` outside officer's websocket, so they never had a key and never wrote a durable event — an
+    empty entry for them would be noise, not caution.
+
+    `sessionKey` is resolved above for the kill and reused here rather than looked up twice; when it is null
+    the session was already gone, and so were its events.
+  */
+  await forgetChatSessions({ transcriptIds: forgotten, sessionKeys: sessionKey ? [sessionKey] : [] });
+
  // Said back rather than a bare ok: this is the one irreversible action here, and the counts are what
  // make it auditable after the fact.
-  return ctx.json({ ok: true, processesStopped: stopped, childrenFound: children.length, childrenDeleted });
+  return ctx.json({
+    ok: true,
+    sessionKilled,
+    processesStopped: stopped,
+    childrenFound: children.length,
+    childrenDeleted,
+  });
 });

 /**
@@ -548,8 +670,16 @@ commandHqRouter.delete('/commanders/:sessionId', async (ctx) => {
 commandHqRouter.post('/purge', async (ctx) => {
  const user = ctx.get('user');
  const who = await commandHqIdentity(user);
-  const live = listClaudeSessions(who, getCommandersDir(who.email));
-  const removed = await purgeCommandHqSessions(user.id, new Set(live.map((s) => s.id)));
+  /*
+    "Still exists" is now per row, wherever that row's transcript lives.
+
+    Scanning one directory would have deleted every commander that chose a different one — a housekeeping
+    route quietly unfiling live commanders is the worst possible version of this bug, because the rows are
+    what identity depends on now.
+  */
+  const rows = await listCommandHqSessions(user.id);
+  const stillThere = new Set(rows.map((row) => row.sessionId).filter((id) => !!loadClaudeSessionSummaryById(who, id)));
+  const removed = await purgeCommandHqSessions(user.id, stillThere);
  return ctx.json({ removed });
 });

@@ -0,0 +1,28 @@
+import { createRouter } from '../../create-router';
+import { sessionStatus, startSession, stopSession } from './session';
+
+/**
+ * Session control. The pixels do not come through here — they come through the websocket relay; this
+ * is only "is it up, bring it up, take it down", plus the window size the panel needs to size its
+ * canvas.
+ */
+export const minesweeperRouter = createRouter();
+
+minesweeperRouter.get('/status', async (c) => c.json(await sessionStatus()));
+
+minesweeperRouter.post('/start', async (c) => {
+  const status = await sessionStatus();
+  if (!status.installed) {
+    return c.json({ error: 'Minesweeper is not installed on this server (wine-minesweeper is missing)' }, 501);
+  }
+  if (status.running) return c.json(status);
+
+  const result = await startSession();
+  if (!result.ok) return c.json({ error: `Could not start the session: ${result.out.trim()}` }, 500);
+  return c.json(await sessionStatus());
+});
+
+minesweeperRouter.post('/stop', async (c) => {
+  await stopSession();
+  return c.json(await sessionStatus());
+});
@@ -0,0 +1,111 @@
+import { join } from 'node:path';
+import { OFFICER_ROOT } from '../../data-path';
+
+/**
+ * The Minesweeper X session: a virtual display with one Windows game on it, and x11vnc serving that
+ * display on loopback.
+ *
+ * The platform does not implement any of that — it drives `bin/session.sh`, which is the same script
+ * used by hand. One implementation, so a session started from the browser and one started from a
+ * terminal are the same session with the same lifecycle.
+ */
+
+export const MINESWEEPER_DIR = join(OFFICER_ROOT, 'wine-minesweeper');
+const SESSION_SCRIPT = join(MINESWEEPER_DIR, 'bin', 'session.sh');
+
+export const VNC_HOST = '127.0.0.1';
+export const VNC_PORT = Number(process.env.MINESWEEPER_VNC_PORT ?? 5907);
+const DISPLAY = process.env.MINESWEEPER_DISPLAY ?? ':7';
+
+export type WindowGeometry = { width: number; height: number; x: number; y: number };
+export type SessionStatus = {
+  installed: boolean;
+  running: boolean;
+  /** Absent until the game has drawn its window. */
+  window: WindowGeometry | null;
+};
+
+const run = async (cmd: string[], env: Record<string, string> = {}): Promise<{ ok: boolean; out: string }> => {
+  const proc = Bun.spawn(cmd, {
+    cwd: MINESWEEPER_DIR,
+    env: { ...process.env, ...env },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+  const code = await proc.exited;
+  return { ok: code === 0, out: `${out}${err}` };
+};
+
+export const isInstalled = (): boolean => Bun.file(SESSION_SCRIPT).size > 0;
+
+/**
+ * Whether x11vnc is listening, decided by reading the kernel's socket table rather than by connecting.
+ *
+ * This used to open a TCP connection and drop it. That wedged the VNC server: libvncserver peeks at a
+ * new connection to decide whether it is a WebSocket handshake, and that peek blocks its main loop
+ * until the client speaks or the peek times out. A health check that connects and says nothing is
+ * therefore a small stall, and the panel polls status on a timer — so the stalls overlapped, the accept
+ * backlog filled (Recv-Q 32/32), and the server stopped accepting the real viewer too.
+ *
+ * The rule it cost to learn: a liveness check must not be indistinguishable from a client. Reading
+ * /proc/net/tcp is free, cannot block, and cannot be mistaken for a viewer.
+ */
+async function isServing(): Promise<boolean> {
+  const wanted = VNC_PORT.toString(16).toUpperCase().padStart(4, '0');
+  const LISTEN = '0A';
+
+  for (const table of ['/proc/net/tcp', '/proc/net/tcp6']) {
+    const text = await Bun.file(table)
+      .text()
+      .catch(() => '');
+
+    for (const line of text.split('\n').slice(1)) {
+      const columns = line.trim().split(/\s+/);
+      const local = columns[1];
+      const state = columns[3];
+      if (!local || state !== LISTEN) continue;
+      if (local.split(':')[1] === wanted) return true;
+    }
+  }
+  return false;
+}
+
+
+/**
+ * The game window's size, so the browser can size its canvas to the board rather than to the whole
+ * framebuffer. `session.sh` parks the window at 0,0, so the offset is expected to be zero and is
+ * reported anyway — a non-zero one means something moved it and the canvas would be misaligned.
+ *
+ * The board changes size when the difficulty changes, which is why this is polled rather than read
+ * once at connect.
+ */
+export async function windowGeometry(): Promise<WindowGeometry | null> {
+  const search = await run(['xdotool', 'search', '--name', 'Minesweeper X'], { DISPLAY });
+  if (!search.ok) return null;
+
+  let best: WindowGeometry | null = null;
+  for (const id of search.out.trim().split('\n').filter(Boolean)) {
+    const geom = await run(['xdotool', 'getwindowgeometry', '--shell', id], { DISPLAY });
+    if (!geom.ok) continue;
+
+    const read = (key: string): number => Number(new RegExp(`^${key}=(\\d+)$`, 'm').exec(geom.out)?.[1] ?? NaN);
+    const candidate = { width: read('WIDTH'), height: read('HEIGHT'), x: read('X'), y: read('Y') };
+    if (Object.values(candidate).some(Number.isNaN)) continue;
+
+    // wine creates a 1x1 owner stub alongside the real window; the larger one is the game.
+    if (!best || candidate.width * candidate.height > best.width * best.height) best = candidate;
+  }
+  return best && best.width > 1 ? best : null;
+}
+
+export async function sessionStatus(): Promise<SessionStatus> {
+  const installed = isInstalled();
+  if (!installed) return { installed, running: false, window: null };
+
+  const running = await isServing();
+  return { installed, running, window: running ? await windowGeometry() : null };
+}
+
+export const startSession = (): Promise<{ ok: boolean; out: string }> => run([SESSION_SCRIPT, 'start']);
+export const stopSession = (): Promise<{ ok: boolean; out: string }> => run([SESSION_SCRIPT, 'stop']);
@@ -0,0 +1,95 @@
+import type { ServerWebSocket, Socket } from 'bun';
+import { VNC_HOST, VNC_PORT } from './session';
+
+/**
+ * A byte relay between the browser and x11vnc, in the same spirit as the terminal's relay onto the pty
+ * sidecar — this file authenticates the upgrade (upgradeWs, in server.tsx) and moves bytes without
+ * reading them.
+ *
+ * One difference decides the shape: x11vnc serves raw TCP, not a WebSocket. So this is the job
+ * websockify would otherwise do, done in-process with `Bun.connect` rather than by adding a second
+ * daemon and a second port to protect. RFB is a stream protocol, so frame boundaries carry no meaning
+ * and chunks are forwarded exactly as they arrive.
+ */
+
+export type MinesweeperWSData = { provider: 'minesweeper'; search: string };
+
+type Relay = { socket: Socket | null; queue: Uint8Array[]; done: boolean };
+
+const relays = new Map<ServerWebSocket<MinesweeperWSData>, Relay>();
+
+const closeClient = (ws: ServerWebSocket<MinesweeperWSData>, code: number, reason: string) => {
+  const relay = relays.get(ws);
+  relays.delete(ws);
+  if (relay) relay.done = true;
+  try {
+    relay?.socket?.end();
+  } catch {
+    /* already gone */
+  }
+  try {
+    ws.close(code, reason);
+  } catch {
+    /* already closed */
+  }
+};
+
+export const minesweeperWebsocket = {
+  open(ws: ServerWebSocket<MinesweeperWSData>) {
+    // Registered synchronously, so bytes arriving before the TCP connection is up are queued rather
+    // than dropped. The RFB handshake starts with the SERVER talking, but a client that pipelines its
+    // version string would otherwise lose it.
+    const relay: Relay = { socket: null, queue: [], done: false };
+    relays.set(ws, relay);
+
+    void Bun.connect({
+      hostname: VNC_HOST,
+      port: VNC_PORT,
+      socket: {
+        open(socket) {
+          if (relay.done) {
+            socket.end();
+            return;
+          }
+          relay.socket = socket;
+          for (const chunk of relay.queue) socket.write(chunk);
+          relay.queue.length = 0;
+        },
+        data(_socket, chunk) {
+          try {
+            ws.send(chunk);
+          } catch {
+            /* client gone; the close handler tears down the socket */
+          }
+        },
+        close: () => closeClient(ws, 1000, 'vnc closed'),
+        error: () => closeClient(ws, 1011, 'vnc error'),
+      },
+    }).catch(() => {
+      // No x11vnc listening — the session is not running. 1011 rather than a silent close, so the
+      // panel can say so instead of showing an empty canvas.
+      closeClient(ws, 1011, 'minesweeper session is not running');
+    });
+  },
+
+  message(ws: ServerWebSocket<MinesweeperWSData>, raw: string | Buffer) {
+    const relay = relays.get(ws);
+    if (!relay) return;
+
+    // RFB is binary in both directions; a text frame is a client that is not speaking it.
+    const bytes = typeof raw === 'string' ? new TextEncoder().encode(raw) : new Uint8Array(raw);
+    if (relay.socket) relay.socket.write(bytes);
+    else relay.queue.push(bytes);
+  },
+
+  close(ws: ServerWebSocket<MinesweeperWSData>) {
+    const relay = relays.get(ws);
+    relays.delete(ws);
+    if (relay) relay.done = true;
+    try {
+      relay?.socket?.end();
+    } catch {
+      /* ignore */
+    }
+  },
+};
@@ -26,6 +26,7 @@ import { pluginsRouter } from './api/plugins/router';
 import { isPluginPublicPath, pluginForProtocolHeaders } from './plugins/public-paths';
 import { agentHandoffRouter } from './api/agent-handoff/router';
 import { terminalRouter } from './api/terminal/sidecar-server';
+import { minesweeperRouter } from './api/minesweeper/router';
 import { caldavRouter } from './api/dav/sidecar-server';
 // import { memosRouter } from './api/memos/router';
 import { appStoreRouter } from './api/app-store/router';
@@ -139,6 +140,7 @@ const PROTECTED_MOUNTS: [prefix: string, router: ReturnType<typeof createRouter>
  ['/dashboards', dashboardsRouter],
  ['/file-browser', fileBrowserRouter],
  ['/terminal', terminalRouter],
+  ['/minesweeper', minesweeperRouter],
  // ['/memos', memosRouter],  // plugin — switched off 2026-08-13
  ['/app-store', appStoreRouter],
  ['/plugins', pluginsRouter],
@@ -23,7 +23,7 @@ import { assertPermissionTotality, isExemptApiPath } from './totality';
 // switched off 2026-08-13. It was listed here until 2026-08-18 and made this file's own totality tests
 // fail for five days — the mirror claiming a provider the server does not serve, which is precisely the
 // drift the comment above warns about, caught by the check and then ignored because it was "the baseline".
-const REAL_WS = ['terminal', 'chat', 'chat-notify', 'task-runner', 'pipeline', 'sidecar'];
+const REAL_WS = ['terminal', 'chat', 'chat-notify', 'task-runner', 'pipeline', 'sidecar', 'minesweeper'];
 const realApi = () => [...new Set(PERMISSIONS.flatMap((c) => c.api))];
 const surface = () => ({
  apiPrefixes: [...realApi(), '/auth', '/landing-page-data', '/waitlist', '/sidecar'],
@@ -328,6 +328,25 @@ const CORE_REGISTRY: Permission[] = [
    ws: ['task-runner', 'pipeline'],
    routes: ['/jobs'],
  },
+  // Minesweeper X, on a virtual display, streamed to the browser over RFB.
+  //
+  // `execution` rather than `app`, and the reason is not that a game is dangerous. The wine process runs
+  // as the SERVER OWNER on the owner's display — so its File and Extras menus are file dialogs with the
+  // owner's home behind them, and "granted Minesweeper" would quietly mean "granted a file picker as the
+  // owner". `plugins/desktop` reached the same conclusion from the same premise.
+  //
+  // There is a second reason to keep it here for now: one display and one game means two viewers share a
+  // board and fight over the mouse. Per-viewer sessions would be a display and a wine prefix each, which
+  // is cheap for this but is a design decision rather than an implementation detail.
+  {
+    key: 'minesweeper',
+    label: 'Minesweeper',
+    description: 'A Windows Minesweeper session on a virtual display, as the server owner',
+    kind: 'execution',
+    api: ['/minesweeper'],
+    ws: ['minesweeper'],
+    routes: ['/minesweeper'],
+  },
  {
    key: 'items',
    label: 'Permission authoring',
@@ -224,11 +224,28 @@ function sendCommand(kind: string, cmd: SidecarCommand, timeoutMs = DEFAULT_TIME
  });
 }

-function sendFire(kind: string, cmd: SidecarCommand): void {
+/**
+ * Fire a command at whichever sidecar handles this kind. Returns whether one was there to take it.
+ *
+ * It used to return void and drop the command when no sidecar was registered — no log, no error, nothing.
+ * That window is real and predictable: every `pm2 restart officer` has one while the sidecars reconnect, and
+ * a person clicking a button has no idea they are in it.
+ *
+ * The cost landed on `claude:question-answer`, whose own handler documents this exact failure and cannot
+ * report it, because the message never arrives to be reported. From the person's side the question card just
+ * kept spinning — indistinguishable from a slow agent, so the only move left was to send another message.
+ *
+ * Callers that can tell somebody are now able to. The boolean is the whole mechanism; the warning is for
+ * whoever reads the log afterwards wondering why one click did nothing.
+ */
+function sendFire(kind: string, cmd: SidecarCommand): boolean {
  const sc = findSidecarHandling(kind);
-  if (sc) {
-    sc.ws.send(JSON.stringify(cmd));
+  if (!sc) {
+    console.warn(`[sidecar] dropped ${cmd.type}: no sidecar registered for "${kind}"`);
+    return false;
  }
+  sc.ws.send(JSON.stringify(cmd));
+  return true;
 }

 function sendCommandToSidecar(
@@ -330,6 +347,26 @@ export function killClaude(sessionKey: string, userId: number): void {
  sendFire('claude', { type: 'claude:kill', id: nextId(), sessionKey, userId });
 }

+/**
+ * Kill a session and wait for the agent to confirm its child process is gone.
+ *
+ * For callers that then delete the session's FILES. The transcript belongs to the `claude` CLI, not to
+ * officer, so removing it while the CLI is still unwinding deletes a file that is written straight back —
+ * which resurrects a conversation the user deleted, as an untitled ordinary chat that nothing filters out.
+ *
+ * Never fatal: a sidecar that is down or slow must not block a delete. The caller proceeds and accepts the
+ * race it was already running, which is no worse than before this existed.
+ */
+export async function killClaudeAndWait(sessionKey: string, userId: number): Promise<boolean> {
+  try {
+    const sc = await waitForHandler('claude');
+    const res = await sendCommandToSidecar(sc, { type: 'claude:kill', id: nextId(), sessionKey, userId });
+    return res.type === 'claude:killed';
+  } catch {
+    return false;
+  }
+}
+
 // Interrupt the current turn but keep the persistent session warm (the "stop" button).
 export function interruptClaude(sessionKey: string, userId: number): void {
  sendFire('claude', { type: 'claude:interrupt', id: nextId(), sessionKey, userId });
@@ -348,8 +385,8 @@ export function decideClaudePlan(params: {
  requestId: string;
  approve: boolean;
  feedback?: string;
-}): void {
-  sendFire('claude', { type: 'claude:plan-decision', id: nextId(), ...params });
+}): boolean {
+  return sendFire('claude', { type: 'claude:plan-decision', id: nextId(), ...params });
 }

 // The user's answer to an AskUserQuestion. Fire-and-forget for the same reason as the plan decision: the
@@ -360,8 +397,8 @@ export function answerClaudeQuestion(params: {
  userId: number;
  toolCallId: string;
  answer: string;
-}): void {
-  sendFire('claude', { type: 'claude:question-answer', id: nextId(), ...params });
+}): boolean {
+  return sendFire('claude', { type: 'claude:question-answer', id: nextId(), ...params });
 }

 /**
@@ -6,7 +6,6 @@ import { query, type Query, type SpawnOptions, type SpawnedProcess } from '@anth
 import type { ChatEvent, PromptImage } from '../../api/chat/types';
 import { affordanceBlock } from '../../affordances/load';
 import { skillsBlock } from '../../skills/load';
-import { commanderBlock } from '../../api/command-hq/commander-block';
 import type { ClaudeSpawnParams, ClaudeSpawnStreamingParams, ClaudeCodeResult, LiveClaudeSession } from '../protocol';
 import { setClaudeSession, clearClaudeSession, getClaudeSession } from './state';
 import { countsAsOutput, diagnoseExit, stderrReason } from './exit-diagnosis';
@@ -248,6 +247,18 @@ type PersistentSession = {
  interrupted: boolean;
  /** What we passed as `--resume`, so a failure can name it and decide whether it was to blame. */
  resumeId?: string;
+  /**
+   * Resolves when this session's child process is actually gone.
+   *
+   * Killing is not the same as being dead, and the difference is visible on disk: `abort()` returns at once
+   * while the `claude` CLI keeps writing for as long as it takes to unwind. Officer does not own the
+   * transcript — the CLI does — so a delete that races this window removes the file and the CLI writes it
+   * straight back, resurrecting a conversation the user deleted. Anything that deletes a session's FILES
+   * has to await this first.
+   */
+  exited: Promise<void>;
+  /** Called by the exit hook. Resolving twice is a no-op, which is what makes the double-fire safe. */
+  markExited: () => void;
  /**
   * The model this session is currently answering as, `harness/tier`.
   *
@@ -363,6 +374,10 @@ function spawnClaudeAsOwner({ command, args, cwd, env, signal }: SpawnOptions):
 * transcript by id.
 */
 function dropDeadSession(session: PersistentSession, detail: string): void {
+  // Before the identity guard, and deliberately: this fires on the real process exit, and a waiter must be
+  // released even when a newer session has already taken this key. Otherwise a replaced session's waiter
+  // blocks until its timeout for a process that died on schedule.
+  session.markExited();
  // Identity, not key: a later turn may have already replaced this entry, and killing its session because
  // its predecessor's process exited would break the live conversation instead of a dead one.
  if (sessions.get(session.sessionKey) !== session) return;
@@ -541,11 +556,6 @@ function createSession(
  params: ClaudeSpawnStreamingParams,
  onEvent: (event: ChatEvent) => void,
  onNotify: (kind: 'turn-ended' | 'input-needed') => void,
-  /**
-   * The commander block, or null. Passed IN because building it needs two database reads and this function
-   * is synchronous — hoisted to `spawnClaudeStreaming`, which is async and already has the account.
-   */
-  commander: string | null,
 ): PersistentSession {
  const { sessionKey } = params;
  const input = makeInputQueue();
@@ -568,7 +578,13 @@ function createSession(
    interrupted: false,
    stderrTail: '',
    sawOutput: false,
+    // Assigned immediately below — the resolver has to escape the executor before the object is usable.
+    exited: undefined as unknown as Promise<void>,
+    markExited: () => {},
  };
+  session.exited = new Promise<void>((resolve) => {
+    session.markExited = resolve;
+  });

  // Strip the nested-session guard vars so the SDK can spawn `claude` (mirrors the old spawn env clean).
  const cleanEnv = envWithoutParentSession();
@@ -621,8 +637,14 @@ function createSession(
    preamble, which is where this used to live and which an agent arming itself never sees. See
    `api/command-hq/commander-block.ts`.
  */
-  // `commander` is a parameter, not computed here — see the note on it.
-  const preamble = [affordances, skills, commander].filter(Boolean).join('\n\n') || null;
+  /*
+    No commander block here, deliberately.
+
+    It used to be composed in, and could never arrive: this runs once per session, and a commander's first
+    turn has no row and no transcript id, so the block resolved to null and no later turn rebuilt the
+    preamble. It rides `effectivePrompt` instead — see `startClaudeTurn` in api/chat/websocket.ts.
+  */
+  const preamble = [affordances, skills].filter(Boolean).join('\n\n') || null;

  const q = query({
    prompt: input.gen as AsyncIterable<SdkUserMessage>,
@@ -894,16 +916,7 @@ export async function spawnClaudeStreaming(
    await applyModelChange(session, params.model);
    await applyPlanModeChange(session, params.planMode);
  } else {
-    /*
-      The commander block is built here, before the session exists, because it needs the database and
-      `createSession` is synchronous. It resolves the row for this transcript id and returns null for
-      anything that is not a commander — which is every ordinary chat, at the cost of one indexed lookup.
-    */
-    const commander = await commanderBlock({
-      userId: params.userId,
-      sessionId: getClaudeSession(params.sessionKey, params.userId) ?? params.resumeSessionId ?? null,
-    });
-    session = createSession(params, onEvent, onNotify, commander);
+    session = createSession(params, onEvent, onNotify);
  }
  session.pushTurn(params.prompt, params.images);
 }
@@ -1245,6 +1258,33 @@ export async function interruptClaudeSession(sessionKey: string, userId: number)
 }

 /** Fully tear the session down (the "disconnect" action / idle GC): abort the query + close input. */
+/**
+ * Kill a session and wait for its child process to actually be gone.
+ *
+ * The bounded wait is the point. `killClaudeSession` returns as soon as it has aborted, which is before the
+ * `claude` CLI has finished writing — and the CLI, not officer, owns the transcript file. A caller that
+ * deletes files has to await this or it deletes them out from under a process still writing them.
+ *
+ * The timeout resolves rather than throws: a child that will not die within the window is a worse problem
+ * than a stale transcript, and blocking a user's delete on it forever helps nobody. The caller gets `false`
+ * and can say so.
+ */
+export async function killClaudeSessionAndWait(sessionKey: string, userId: number, timeoutMs = 5000): Promise<boolean> {
+  const session = ownedSession(sessionKey, userId);
+  if (!session) return false;
+  const { exited } = session;
+  killClaudeSession(sessionKey, userId);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = await Promise.race([
+    exited.then(() => false),
+    new Promise<boolean>((resolve) => {
+      timer = setTimeout(() => resolve(true), timeoutMs);
+    }),
+  ]);
+  if (timer) clearTimeout(timer);
+  return !timedOut;
+}
+
 export function killClaudeSession(sessionKey: string, userId: number): boolean {
  const session = ownedSession(sessionKey, userId);
  if (!session) return false;
@@ -294,11 +294,20 @@ async function handleCommand(cmd: SidecarCommand, reply: ReplyFn) {
      break;
    }

-    case 'claude:kill':
-      claudeManager.killClaudeSession(cmd.sessionKey, cmd.userId);
+    case 'claude:kill': {
+      /*
+        Reply only once the child is actually gone.
+      
+        The caller deleting a session's transcript has to know the CLI has stopped writing it, and this
+        reply is the only signal it can get — officer's side of the socket has no view of the process.
+        Bounded inside `killClaudeSessionAndWait`, so a child that will not die delays this by seconds
+        rather than hanging the caller's request.
+      */
+      await claudeManager.killClaudeSessionAndWait(cmd.sessionKey, cmd.userId);
      sessionLog.drop(cmd.sessionKey);
      reply({ type: 'claude:killed', id: cmd.id });
      break;
+    }

    case 'claude:interrupt':
      await claudeManager.interruptClaudeSession(cmd.sessionKey, cmd.userId);
@@ -11,6 +11,7 @@ import { appRegistryMetas as chatHistoryMetas } from '../apps/ChatHistory';
 import { appRegistryMetas as widgetMetas } from '../apps/Widgets';
 import { appRegistryMetas as monitorMetas } from '../apps/SystemMonitor';
 import { appRegistryMetas as qrTransferMetas } from '../apps/QrTransfer';
+import { appRegistryMetas as minesweeperMetas } from '../apps/Minesweeper';
 import { appRegistryMetas as davMetas } from '../apps/Dav';
 import { appRegistryMetas as commandHqMetas } from '../apps/CommandHQ';
 import type { QueryClient } from '@tanstack/react-query';
@@ -28,6 +29,7 @@ export const apps = [
  ...widgetMetas,
  ...monitorMetas,
  ...qrTransferMetas,
+  ...minesweeperMetas,
  ...davMetas,
  ...commandHqMetas,
  ...appStoreMetas,
@@ -84,16 +84,23 @@ const ChatPanelInner = ({

  useEffect(() => {
    setActiveSession(chat.sessionId);
-    // Only a REAL id, never null.
-    //
-    // A new chat is nameless until the harness names it on the first turn, and recording that id is what
-    // makes "New chat, say something, reload" return to that conversation instead of a third one. But
-    // `chat.sessionId` is also null for a moment while a resumed session connects — and writing that null
-    // would turn "this panel has never chosen" into "the user asked for a new chat", so the next reload
-    // would open blank. Asking for a new conversation is something the header says explicitly; this
-    // effect only ever reports what the harness decided.
-    if (chat.sessionId) onSessionId?.(chat.sessionId);
-  }, [chat.sessionId]);
+    /*
+      `claudeSessionId`, NOT `sessionId`. The panel's stored id is looked up in the sessions LIST — see
+      `ChatHeader`'s `sessions.find((s) => s.id === sessionId)` — and that list is keyed on Claude's
+      transcript id. Recording officer's own session key here put two id spaces on either side of one
+      lookup: it never matched, so a new chat's header read "New chat" for the life of the conversation and
+      offered no rename, because rename is a per-row action on a list the session was not found in.
+      Selecting the conversation from the list fixed it, which is why navigating away and back appeared to
+      be the cure.
+
+      Only a REAL id, never null. A new chat has none until the harness names its transcript on the first
+      turn, and recording it is what makes "new chat, say something, reload" return to that conversation
+      rather than a third one. Both ids are also null for a moment while a resumed session connects, and
+      writing that null would turn "this panel has never chosen" into "the user asked for a new chat", so
+      the next reload would open blank.
+    */
+    if (chat.claudeSessionId) onSessionId?.(chat.claudeSessionId);
+  }, [chat.sessionId, chat.claudeSessionId]);

  return (
    <div className="flex h-full min-h-0 flex-col">
@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 import type { UseChatType } from '../../../hooks/useChat';
 import { useEmbeddableChat } from './useEmbeddableChat';
 import { MessageList } from '../components/MessageList';
@@ -5,6 +6,14 @@ import { InputArea } from '../components/InputArea';

 type EmbeddableChatProps = {
  sessionId?: string;
+  /**
+   * What the transcript shows before there is anything in it. `null` shows nothing.
+   *
+   * The default, "Send a message to start", is true on the chat screen and wrong wherever something else
+   * already explains what to do — a new commander has a setup card and a Start button above it, so the
+   * message contradicts them and takes 200px of height while doing it.
+   */
+  emptyState?: ReactNode;
  /** Which panel this is — see `queue-store`. Absent on the screen, where there is only one chat. */
  panelId?: string;
  initialModel?: string | null;
@@ -31,6 +40,14 @@ type EmbeddableChatProps = {
   * a commander opened in /chat had `context: 'chat'` and silently lost the control.
   */
  isCommander?: boolean;
+  /**
+   * Refuse input entirely, with a reason the composer shows.
+   *
+   * For a surface where something must be chosen before a conversation can start — a new commander needs a
+   * name and a working directory, both unchangeable afterwards. Disabling the composer is the only honest
+   * place to enforce that: anywhere later and the person has already written what they meant to say.
+   */
+  disabled?: false | { reason: string };
  onMessageComplete?: () => void;
 };

@@ -43,7 +60,7 @@ export const EmbeddableChat = ({ className, onMessageComplete, ...params }: Embe
  return (
    <div className={`flex flex-col ${className ?? ''}`} onKeyDown={manager.handleEscape}>
      <MessageList manager={manager} />
-      <InputArea manager={manager} />
+      <InputArea manager={manager} disabled={params.disabled} />
    </div>
  );
 };
@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 import type { KeyboardEvent } from 'react';
 import { useState, useRef, useEffect, useCallback } from 'react';
 import { useUserVisibleModels } from 'state/useModels';
@@ -51,6 +52,7 @@ type UseEmbeddableChatParams = {
  contextId?: string;
  /** This session is a commander, per `GET /chat/sessions/:id`. See the note where it is surfaced. */
  isCommander?: boolean;
+  emptyState?: ReactNode;
 };

 /**
@@ -622,6 +624,7 @@ export function useEmbeddableChat(params: UseEmbeddableChatParams, onMessageComp
      would lose the brand-new composer, which has no session yet.
    */
    isCommander: params.context === 'command-hq' || params.isCommander === true,
+    emptyState: params.emptyState,
    /*
      Claude's transcript id, which is what a commander is keyed on everywhere — the Command HQ row, the
      record of what it spawned, the delete cascade. `sessionId` above is OFFICER's handle for the same
@@ -16,9 +16,11 @@ import { BackgroundTaskTray } from './BackgroundTaskTray';

 type InputAreaProps = {
  manager: UseEmbeddableChatType;
+  /** When set, input is refused and the reason is shown in place of the composer's own hints. */
+  disabled?: false | { reason: string };
 };

-export const InputArea = ({ manager }: InputAreaProps) => {
+export const InputArea = ({ manager, disabled }: InputAreaProps) => {
  const [loginOpen, setLoginOpen] = useState(false);
  // Only for a commander, and only once it has an id. Everything a commander's loop needs in order to be
  // stoppable and deletable hangs off these two paths — see api/command-hq/spawned.ts.
@@ -110,6 +112,9 @@ export const InputArea = ({ manager }: InputAreaProps) => {
        <textarea
          ref={textareaRef}
          value={input}
+          // Native `disabled`, not a click guard: it also takes the field out of the tab order and stops a
+          // paste, which a guard on send would not.
+          disabled={!!disabled}
          onChange={(ev) => setInput(ev.target.value)}
          onKeyDown={(ev) => {
            // Enter is how anybody actually sends, so the interception has to be here as well as on the
@@ -137,7 +142,10 @@ export const InputArea = ({ manager }: InputAreaProps) => {
              }
            }
          }}
-          placeholder="Type a message..."
+          // One placeholder, not two. It was declared twice on this element — the reason above and this
+          // below — and JSX takes the LAST, so the gate was applied and completely invisible: a disabled
+          // composer still inviting you to type a message.
+          placeholder={disabled ? disabled.reason : 'Type a message...'}
          rows={1}
          className="min-w-0 flex-1 resize-none rounded-lg border border-input bg-background/80 px-2 py-1.5 md:px-3 md:py-2 text-base md:text-sm text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-duck-teal/30 focus:border-duck-teal/50"
        />
@@ -107,11 +107,17 @@ export const MessageList = ({ manager }: MessageListProps) => {
        </div>
      )}
      <div ref={scrollViewportRef} className="h-full overflow-y-auto">
-        {rows.length === 0 && !isGenerating && (
+        {rows.length === 0 &&
+          !isGenerating &&
+          // `undefined` means nobody said, so keep the default. `null` means "show nothing", which is what
+          // a screen that already explains itself above the transcript passes.
+          (manager.emptyState !== undefined ? (
+            manager.emptyState
+          ) : (
            <div className="flex items-center justify-center h-full min-h-[200px] text-muted-foreground text-sm">
              Send a message to start
            </div>
-        )}
+          ))}
        {rows.length > 0 && (
          <ToolOpenProvider>
            <div className="relative w-full" style={{ height: virtualizer.getTotalSize() }}>
@@ -51,9 +51,11 @@ export function useClaudeUsage(enabled: boolean) {
    queryKey: KEY,
    queryFn: () => client.get<UsageResponse>('/chat/usage'),
    enabled,
-    // The stored rows only change when a turn ends, and a turn ending does not happen while you are reading
-    // this panel. The refresh below is what keeps it honest, not a stale timer.
-    staleTime: 5 * 60_000,
+    // No stale window. This query is only the instant first paint — the refresh below is the real answer
+    // — and a five-minute one meant that after switching account the panel painted the OLD account's
+    // stored row and held it until the refresh landed, which is exactly the moment somebody decides the
+    // numbers are wrong.
+    staleTime: 0,
    refetchOnWindowFocus: false,
    retry: false,
  });
@@ -1,12 +1,15 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
 import { useNavigate, useParams, useSearchParams } from 'react-router';
-import { Check, Radar, Trash2, Unplug, X } from 'lucide-react';
+import { Check, FolderOpen, Radar, Trash2, Unplug, X } from 'lucide-react';
+import { Button } from '@/components/ui/button';
 import { toast } from '@/components/ui/sonner';
 import { EditableTitle } from '@/components/EditableTitle';
 import { useClient } from 'hooks/useClient';
 import { errorText } from 'helpers/error-text';
 import type { ClaudeSessionDetail } from 'state/useClaudeSessions';
 import { useChat, EmbeddableChat } from '../Chat';
+import { DirPickerModal } from '../ChatHistory/DirPickerModal';
 import type { ChatMessage } from '../Chat/types';
 import { categoryFromParam, commandHqListPath, commandHqSessionPath } from './command-hq-routes';
 import { useCommandHqCategories, useCommandHqCommander, useCommandHqCommanderActions } from './useCommandHq';
@@ -41,7 +44,7 @@ function EmptyState() {
 * which matters because this ships on every deploy whether the copy is ready or not.
 */
 const NewCommanderGuide = () => (
-  <div className="shrink-0 overflow-y-auto border-b border-border px-5 py-4">
+  <div className="shrink-0 border-b border-border px-5 py-4">
    <div className="mx-auto flex max-w-2xl flex-col gap-4">
      {NEW_COMMANDER_GUIDE.map((section) => (
        <section key={section.title}>
@@ -64,6 +67,127 @@ const NewCommanderGuide = () => (
  </div>
 );

+/**
+ * The whole opening move, as one button.
+ *
+ * Writing a good first prompt is the hard part of starting a commander, and asking somebody to do it before
+ * they have talked to it gets it done badly or not at all. So this sends the opener instead: a brief the
+ * MODEL reads telling it to run the interview, while the transcript shows the short line a person would
+ * have written. That split is `effectivePrompt` vs `displayText`, which the chat path already had.
+ *
+ * The instruction itself is deliberately thin. What to ask, in what order, and to orient in the directory
+ * before asking anything at all, all live in the Commanders skill — which is re-read from disk every run, so
+ * it can be reworded without a deploy. Duplicating any of it here would create a second copy to drift.
+ */
+const startBrief = (name: string): string =>
+  [
+    `You have been named "${name}", and that is the only thing I have told you about what I want.`,
+    'It is not decoration — I chose it before anything else, so treat it as the subject and read this',
+    'directory looking for what it refers to.',
+    '',
+    'Read the **Commanders** skill before you reply. It is how this works, and it is short.',
+    '',
+    'You watch for the thing I name and you respond when it happens. You never cause it — not while we',
+    'are setting you up, and not on a first run. If you find work of that kind already waiting here, it',
+    'is mine to start, not yours to volunteer for.',
+    '',
+    'Now: can you tell what the job is from what is written here, or not?',
+    '',
+    'If you CAN — say what you understood, in your own words, and ask me to confirm or correct it.',
+    'If you CANNOT — ask me what you should be watching for here. One question, and wait.',
+    '',
+    'Either way, say it plainly. No headings, no bullet points, no file paths, no commit hashes, no tag',
+    'names. Do not open with "Oriented" and do not tell me you verified anything — I asked you to look,',
+    'so saying you looked is not news. Length is whatever the answer honestly needs and no more.',
+    '',
+    'Take as long as you like reading first. The constraint is on what you say, not on what you do.',
+  ].join('\n');
+
+const StartCommanderButton = ({ ready, blockedBy, onStart }: StartCommanderButtonProps) => (
+  <div className="shrink-0 border-b border-border px-5 py-4">
+    <div className="mx-auto flex max-w-2xl flex-col items-start gap-2">
+      <Button onClick={onStart} disabled={!ready} size="lg">
+        Start the conversation
+      </Button>
+      <p className="text-xs text-muted-foreground">
+        {ready
+          ? 'It will look around this directory, then ask you what to watch for.'
+          : `${blockedBy} — then this starts it.`}
+      </p>
+    </div>
+  </div>
+);
+
+type StartCommanderButtonProps = {
+  ready: boolean;
+  /** What is still missing, phrased to finish the sentence in the hint below the button. */
+  blockedBy: string;
+  onStart: () => void;
+};
+
+/**
+ * The two decisions a commander cannot be started without.
+ *
+ * Rendered above the guide rather than in a dialog: a first-time reader learns what a commander is and makes
+ * these choices without leaving the page, and somebody who already knows can fill both in without opening
+ * anything.
+ *
+ * The directory is a button rather than a text field. It is an absolute path on the server and typing one is
+ * how you get a commander running in a directory that does not exist — `DirPickerModal` browses the account's
+ * own tree, which is the same containment the server applies to whatever it is handed.
+ */
+const CommanderSetup = ({
+  name,
+  onName,
+  cwd,
+  onPickDirectory,
+}: {
+  name: string;
+  onName: (next: string) => void;
+  cwd: string | null;
+  onPickDirectory: () => void;
+}) => (
+  <div className="shrink-0 border-b border-border bg-muted/20 px-5 py-4">
+    <div className="mx-auto flex max-w-2xl flex-col gap-3">
+      <div className="flex flex-col gap-1">
+        <label htmlFor="commander-name" className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+          Name
+        </label>
+        <input
+          id="commander-name"
+          autoFocus
+          value={name}
+          onChange={(ev) => onName(ev.target.value)}
+          placeholder="Platform deploys"
+          className="rounded-lg border border-border bg-background px-3 py-2 text-sm outline-none focus:border-primary"
+        />
+        {/* Said here because it is not obvious and it is not reversible cheaply: the harness would otherwise
+            name this after whatever the first message happens to say. */}
+        <span className="text-[11px] text-muted-foreground">
+          Applied to the conversation as it starts, instead of the harness naming it after your first message.
+        </span>
+      </div>
+
+      <div className="flex flex-col gap-1">
+        <span className="text-xs font-medium uppercase tracking-wide text-muted-foreground">Working directory</span>
+        <button
+          type="button"
+          onClick={onPickDirectory}
+          className={`flex items-center gap-2 rounded-lg border px-3 py-2 text-left text-sm transition-colors ${
+            cwd ? 'border-border bg-background' : 'border-dashed border-border text-muted-foreground hover:bg-muted/40'
+          }`}
+        >
+          <FolderOpen className="h-4 w-4 shrink-0" />
+          <span className="min-w-0 flex-1 truncate font-mono text-xs">{cwd ?? 'Choose a directory…'}</span>
+        </button>
+        <span className="text-[11px] text-muted-foreground">
+          Where every command it runs resolves from, and where its history is kept. It cannot be moved later.
+        </span>
+      </div>
+    </div>
+  </div>
+);
+
 /**
 * A commander started in THIS pane, and it keeps the same live chat for as long as the pane is open.
 *
@@ -91,12 +215,76 @@ function NewCommander({
  onStarted: (id: string) => void;
 }) {
  const navigate = useNavigate();
-  const chat = useChat(undefined, undefined, { replaceUrl: false, context: 'command-hq' });
+  /*
+    A name and a working directory, both required BEFORE the first message.
+
+    Neither can be set afterwards without cost. The directory decides where every relative path in every turn
+    resolves and which project group holds the transcripts, so changing it later would strand a conversation
+    away from its own history. The name has to reach the transcript the moment it exists — `commanderName` on
+    the turn — because Claude Code names a new session from its first prompt, and the platform's rename only
+    wins by getting there first.
+
+    So the composer is disabled until both are chosen. That is why this lives on the card rather than in a
+    dialog: you read what a commander is and make the two decisions in the same place.
+  */
+  const [name, setName] = useState('');
+  const [cwd, setCwd] = useState<string | null>(null);
+  const [pickerOpen, setPickerOpen] = useState(false);
+  const ready = name.trim().length > 0 && !!cwd;
+
+  const chat = useChat(undefined, undefined, {
+    replaceUrl: false,
+    context: 'command-hq',
+    // The name rides the turn; the DIRECTORY is a prop on EmbeddableChat below, because that is what feeds
+    // `sendPrompt`'s `cwdParam`. Two different paths for two values chosen in the same place, which is worth
+    // a note rather than a discovery.
+    ...(name.trim() ? { commanderName: name.trim() } : {}),
+  });
  // Also the transcript id: `command_hq_sessions` is keyed on it, so an action addressed by officer's key
  // updates nothing and says nothing. Same root cause as the navigate below.
  const { setCategory } = useCommandHqCommanderActions(chat.claudeSessionId ?? '');
  const [filed, setFiled] = useState(false);

+  /*
+    Has this commander been started — which is NOT the same as "has it any messages".
+  
+    `messages.length === 0` was standing in for it, and it lies in exactly the situation that matters.
+    Lose the socket mid-turn and the messages come back empty, so the setup pane and its Start button
+    reappear on a commander that is already running; pressing Start then sends the opening brief a
+    SECOND time, and the agent answers a question nobody asked twice. Seen tonight, after a restart I
+    ran while a commander was live.
+  
+    A latch, not a derived value. Once started, always started — the point is to survive the moment the
+    live state goes empty, so anything recomputed from that state is the bug rather than the fix.
+  */
+  const [started, setStarted] = useState(false);
+  useEffect(() => {
+    if (chat.messages.length > 0 || chat.claudeSessionId || chat.isGenerating) setStarted(true);
+  }, [chat.messages.length, chat.claudeSessionId, chat.isGenerating]);
+  /*
+    Refresh the grid when the first turn ends.
+  
+    The commander's NAME is written server-side, into the transcript's summary record, on the first
+    `result` — the rename can only land once the transcript exists. Nothing tells the client that
+    happened, so the list kept whatever title it had fetched before, which for a self-started commander
+    is the opening brief: the pill read "I have given you a name and a working directory…" while the
+    header beside it read the real name from local state.
+  
+    The falling edge of `isGenerating` is the signal, rather than a poll or a shorter `staleTime`: it is
+    the one moment the server is known to have written something the list is showing.
+  */
+  const wasGenerating = useRef(false);
+  const qc = useQueryClient();
+  useEffect(() => {
+    if (wasGenerating.current && !chat.isGenerating) {
+      // Both shapes, not just the grid: the header reads the per-commander query and went stale the same
+      // way, so the first attempt at this fixed the pill and left the title beside it still wrong.
+      qc.invalidateQueries({ queryKey: ['command-hq', 'commanders'] });
+      qc.invalidateQueries({ queryKey: ['command-hq', 'commander'] });
+    }
+    wasGenerating.current = chat.isGenerating;
+  }, [chat.isGenerating, qc]);
+
  useEffect(() => {
    // `claudeSessionId`, NOT `sessionId`. The commander is filed under Claude's transcript id
    // (`fileAsCommander` in websocket.ts), and this URL has to match or the detail pane fetches an id
@@ -121,7 +309,15 @@ function NewCommander({
      {chat.claudeSessionId ? (
        <MetaBar
          sessionId={chat.claudeSessionId}
-          title={undefined}
+          /*
+            The name the owner typed, straight from state.
+
+            It cannot come from the server yet: the rename lands at the END of the first turn (the transcript
+            does not exist when the turn starts), and this bar has no fetched title of its own — a brand-new
+            commander has nothing to resume. So the header read "Untitled commander" until a refresh, showing
+            the one thing on screen that nobody had chosen while the chosen name sat in a field above it.
+          */
+          title={name.trim() || undefined}
          isConnected={chat.isConnected}
          isGenerating={chat.isGenerating}
          onDisconnect={chat.disconnectSession}
@@ -137,8 +333,55 @@ function NewCommander({
          and not to the component left that radio hidden inside a commander — the one place it exists for. */}
      {/* Before the first message, the pane explains itself. `EmbeddableChat`'s own empty state is "Send a
          message to start", which is true and tells a first-time user nothing about what to send. */}
-      {chat.messages.length === 0 && <NewCommanderGuide />}
-      <EmbeddableChat chat={chat} sessionId={undefined} context="command-hq" className="min-h-0 flex-1" />
+      {/*
+        One scroll region for the whole pre-start pane, rather than three `shrink-0` siblings.
+      
+        They stacked to whatever height they wanted and nothing could scroll: the guide carried its own
+        `overflow-y-auto`, which never engaged, because `shrink-0` had already given it its full natural
+        height. Fine at 100%, and the panel system is zoomable — at 120% the setup ran off the bottom of
+        the panel with no way to reach it.
+      
+        So the scroller is here, where the height is actually constrained, and the composer below keeps
+        `shrink-0` so it stays reachable at the bottom whatever the zoom.
+      */}
+      {!started && (
+        <div className="flex min-h-0 flex-1 flex-col overflow-y-auto">
+          <CommanderSetup name={name} onName={setName} cwd={cwd} onPickDirectory={() => setPickerOpen(true)} />
+          <StartCommanderButton
+            ready={ready}
+            blockedBy={!name.trim() ? 'Name it first' : 'Choose a working directory'}
+            onStart={() =>
+              // Positional, and the shape is why `opts` was added rather than a tenth slot: displayText is #7.
+              chat.sendPrompt(
+                startBrief(name.trim()),
+                undefined,
+                undefined,
+                cwd ? { path: cwd } : undefined,
+                undefined,
+                undefined,
+                'Set me up.',
+                undefined,
+                { selfStarted: true },
+              )
+            }
+          />
+          <NewCommanderGuide />
+        </div>
+      )}
+      {/* Disabled until both are chosen. The composer is where somebody would otherwise type first and
+          discover the requirement afterwards, having already written what they meant to say. */}
+      <EmbeddableChat
+        chat={chat}
+        sessionId={undefined}
+        context="command-hq"
+        {...(cwd ? { cwd: { path: cwd } } : {})}
+        disabled={
+          !started && !ready ? { reason: !name.trim() ? 'Name it first…' : 'Choose a working directory first…' } : false
+        }
+        className={!started ? 'shrink-0' : 'min-h-0 flex-1'}
+        {...(!started ? { emptyState: null } : {})}
+      />
+      <DirPickerModal open={pickerOpen} onClose={() => setPickerOpen(false)} onSelect={setCwd} />
    </div>
  );
 }
@@ -0,0 +1,234 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Bomb, Loader2, Play, RefreshCw } from "lucide-react";
+import { useClient } from "hooks/useClient";
+import { RfbClient } from "./rfb";
+
+type SessionStatus = {
+  installed: boolean;
+  running: boolean;
+  window: { width: number; height: number; x: number; y: number } | null;
+};
+
+// The framebuffer is bigger than the board — the board sits at 0,0 and the rest is empty desktop.
+// Rendering into an offscreen canvas the size of the framebuffer and showing only the board's corner
+// of it is what makes this look like a window rather than a small game adrift in grey.
+const VISIBLE = { width: 164, height: 226 };
+
+const BUTTON_MASK: Record<number, number> = { 0: 1, 1: 2, 2: 4 };
+
+export const MinesweeperPanel = () => {
+  // useClient() rebuilds its verbs on EVERY render, so putting one in a dependency list gives that
+  // list a new identity every render. Held in a ref instead — the same fix the Jellyfin player needed
+  // after its playback reports silently stopped for days. Getting this wrong here meant `refresh` was
+  // unstable, its mount effect re-ran every render, and each run set state and caused another render:
+  // an endless fetch loop that starved the socket and left the panel saying "connecting…" forever.
+  const client = useClient();
+  const clientRef = useRef(client);
+  clientRef.current = client;
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const offscreenRef = useRef<HTMLCanvasElement | null>(null);
+  const rfbRef = useRef<RfbClient | null>(null);
+  const buttonsRef = useRef(0);
+  const geometryRef = useRef(VISIBLE);
+
+  const [status, setStatus] = useState<SessionStatus | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [connected, setConnected] = useState(false);
+  const [busy, setBusy] = useState(false);
+
+  const adopt = useCallback((next: SessionStatus) => {
+    // The board is 152x214 on beginner and wider on the other difficulties. Taking the size from
+    // status means the canvas is right on the first paint instead of after the first poll.
+    if (next.window) geometryRef.current = { width: next.window.width, height: next.window.height };
+    setStatus(next);
+  }, []);
+
+  const refresh = useCallback(async () => {
+    try {
+      adopt(await clientRef.current.get<SessionStatus>("/minesweeper/status"));
+    } catch {
+      setError("Could not reach the server.");
+    }
+  }, [adopt]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const start = async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      adopt(await clientRef.current.post<SessionStatus>("/minesweeper/start", {}));
+    } catch {
+      setError("The session would not start. Is wine-minesweeper installed on the server?");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  // Paint the visible canvas from the offscreen one. Only the board's rectangle is copied, so the
+  // surrounding desktop never reaches the screen.
+  const present = useCallback(() => {
+    const canvas = canvasRef.current;
+    const offscreen = offscreenRef.current;
+    if (!canvas || !offscreen) return;
+    const context = canvas.getContext("2d");
+    if (!context) return;
+    const { width, height } = geometryRef.current;
+    if (canvas.width !== width || canvas.height !== height) {
+      canvas.width = width;
+      canvas.height = height;
+    }
+    context.drawImage(offscreen, 0, 0, width, height, 0, 0, width, height);
+  }, []);
+
+  useEffect(() => {
+    if (!status?.running) return;
+
+    const scheme = window.location.protocol === "https:" ? "wss" : "ws";
+    // 'BEARER_TOKEN' is the key the rest of the app uses (Terminal.tsx, useAudioRecording). Reading
+    // 'token' here sent an empty string, and upgradeWs answered 401 before any RFB byte was exchanged.
+    const token = localStorage.getItem("BEARER_TOKEN") ?? sessionStorage.getItem("BEARER_TOKEN") ?? "";
+    const url = `${scheme}://${window.location.host}/api/minesweeper/ws?token=${encodeURIComponent(token)}`;
+
+    const rfb = new RfbClient(url, {
+      onReady: (width, height) => {
+        const offscreen = document.createElement("canvas");
+        offscreen.width = width;
+        offscreen.height = height;
+        offscreenRef.current = offscreen;
+        setConnected(true);
+        setError(null);
+      },
+      onFrame: (image, x, y) => {
+        offscreenRef.current?.getContext("2d")?.putImageData(image, x, y);
+        present();
+      },
+      onCopyRect: (from, to) => {
+        const offscreen = offscreenRef.current;
+        const context = offscreen?.getContext("2d");
+        if (!offscreen || !context) return;
+        context.drawImage(offscreen, from.x, from.y, to.w, to.h, to.x, to.y, to.w, to.h);
+        present();
+      },
+      onResize: (width, height) => {
+        const offscreen = offscreenRef.current;
+        if (offscreen) {
+          offscreen.width = width;
+          offscreen.height = height;
+        }
+        rfb.requestUpdate(false);
+      },
+      onError: (message) => setError(message),
+      onClose: () => setConnected(false),
+    });
+
+    rfbRef.current = rfb;
+    return () => {
+      rfb.close();
+      rfbRef.current = null;
+      setConnected(false);
+    };
+  }, [status?.running, present]);
+
+  // The board resizes when the difficulty changes, and nothing in RFB announces that — the framebuffer
+  // stays the same size. Polling the window geometry is what keeps the visible canvas matched to it.
+  useEffect(() => {
+    if (!connected) return;
+    const timer = setInterval(async () => {
+      try {
+        const next = await clientRef.current.get<SessionStatus>("/minesweeper/status");
+        if (!next.window) return;
+        const { width, height } = next.window;
+        if (width !== geometryRef.current.width || height !== geometryRef.current.height) {
+          geometryRef.current = { width, height };
+          present();
+        }
+      } catch {
+        /* a failed poll is not worth surfacing; the next one will do */
+      }
+    }, 4000);
+    return () => clearInterval(timer);
+  }, [connected, present]);
+
+  const toFramebuffer = (ev: React.MouseEvent<HTMLCanvasElement>) => {
+    const rect = ev.currentTarget.getBoundingClientRect();
+    const scaleX = ev.currentTarget.width / rect.width;
+    const scaleY = ev.currentTarget.height / rect.height;
+    return { x: (ev.clientX - rect.left) * scaleX, y: (ev.clientY - rect.top) * scaleY };
+  };
+
+  const onPointer = (ev: React.MouseEvent<HTMLCanvasElement>, kind: "down" | "up" | "move") => {
+    const rfb = rfbRef.current;
+    if (!rfb) return;
+    ev.preventDefault();
+
+    if (kind !== "move") {
+      const bit = BUTTON_MASK[ev.button] ?? 0;
+      buttonsRef.current = kind === "down" ? buttonsRef.current | bit : buttonsRef.current & ~bit;
+    }
+    const { x, y } = toFramebuffer(ev);
+    rfb.pointer(x, y, buttonsRef.current);
+  };
+
+  if (status && !status.installed) {
+    return (
+      <Centred>
+        <Bomb className="size-8 text-muted-foreground" />
+        <p className="text-sm text-muted-foreground">Minesweeper is not installed on this server.</p>
+        <p className="max-w-sm text-center text-xs text-muted-foreground">
+          It needs <code>wine-minesweeper</code> beside the platform, with wine and a 32-bit prefix.
+        </p>
+      </Centred>
+    );
+  }
+
+  if (status && !status.running) {
+    return (
+      <Centred>
+        <Bomb className="size-8 text-muted-foreground" />
+        <p className="text-sm text-muted-foreground">The Minesweeper session is not running.</p>
+        {error ? <p className="text-xs text-destructive">{error}</p> : null}
+        <button
+          type="button"
+          onClick={start}
+          disabled={busy}
+          className="flex items-center gap-2 rounded-md bg-primary px-3 py-1.5 text-sm text-primary-foreground disabled:opacity-60"
+        >
+          {busy ? <Loader2 className="size-4 animate-spin" /> : <Play className="size-4" />}
+          {busy ? "Starting" : "Start it"}
+        </button>
+      </Centred>
+    );
+  }
+
+  return (
+    <div className="flex size-full flex-col items-center justify-center gap-3 bg-muted/30 p-4">
+      <canvas
+        ref={canvasRef}
+        width={VISIBLE.width}
+        height={VISIBLE.height}
+        onMouseDown={(ev) => onPointer(ev, "down")}
+        onMouseUp={(ev) => onPointer(ev, "up")}
+        onMouseMove={(ev) => onPointer(ev, "move")}
+        onContextMenu={(ev) => ev.preventDefault()}
+        // Nearest-neighbour: this is a 16px-per-cell bitmap from 1995 and smoothing it looks like a
+        // photograph of a screen rather than the screen.
+        className="rounded-sm shadow-lg [image-rendering:pixelated]"
+        style={{ cursor: connected ? "default" : "progress" }}
+      />
+      <div className="flex items-center gap-3 text-xs text-muted-foreground">
+        <span>{connected ? "connected" : "connecting…"}</span>
+        <button type="button" onClick={() => void refresh()} className="flex items-center gap-1 hover:text-foreground">
+          <RefreshCw className="size-3" /> refresh
+        </button>
+      </div>
+      {error ? <p className="text-xs text-destructive">{error}</p> : null}
+    </div>
+  );
+};
+
+const Centred = ({ children }: { children: React.ReactNode }) => (
+  <div className="flex size-full flex-col items-center justify-center gap-3 p-6">{children}</div>
+);
@@ -0,0 +1,13 @@
+import type { AppRegistryMeta } from '../../AppRegistry';
+import { Bomb } from 'lucide-react';
+import { MinesweeperPanel } from './MinesweeperPanel';
+
+export { MinesweeperPanel } from './MinesweeperPanel';
+export { RfbClient } from './rfb';
+
+// Minesweeper X on a virtual display, streamed over RFB. The client is ./rfb.ts — a few hundred lines
+// rather than a vendored noVNC, because we control the server and need two encodings out of ten.
+
+export const appRegistryMetas: AppRegistryMeta[] = [
+  { key: 'minesweeper', name: 'Minesweeper', icon: Bomb, component: MinesweeperPanel },
+];
@@ -0,0 +1,318 @@
+/**
+ * A minimal RFB 3.8 client — enough to watch a framebuffer and click on it, and no more.
+ *
+ * ── Why this rather than noVNC ──
+ *
+ * noVNC is the obvious choice and it is a good library. It is also ~200 KB of vendored JavaScript for a
+ * job this file does in a few hundred lines, and vendoring is this repository's reluctant exception
+ * (hls.js, committed unminified with provenance hashes) rather than its habit. What we need is one
+ * server we control, one pixel format we choose, and two encodings. The rest of RFB — the eight other
+ * encodings, the compression, the authentication schemes, the clipboard, the audio — is surface we would
+ * carry and never execute.
+ *
+ * So: Raw and CopyRect, one pixel format, security type None. If this ever has to face a VNC server we
+ * do not configure, that is the moment to reach for noVNC instead of growing this.
+ *
+ * ── The pixel format ──
+ *
+ * The client DICTATES the format via SetPixelFormat rather than accepting the server's, so decoding is
+ * a memcpy into ImageData instead of a per-pixel shift-and-mask. We ask for 32bpp true colour with
+ * big-endian byte order, which puts the bytes on the wire as R,G,B,X — exactly the order a canvas
+ * ImageData buffer wants, so a Raw rectangle copies straight in.
+ */
+
+export type RfbEvents = {
+  onReady: (width: number, height: number) => void;
+  onFrame: (image: ImageData, x: number, y: number) => void;
+  onCopyRect: (from: { x: number; y: number }, to: { x: number; y: number; w: number; h: number }) => void;
+  onResize: (width: number, height: number) => void;
+  onError: (message: string) => void;
+  onClose: () => void;
+};
+
+const ENCODING_RAW = 0;
+const ENCODING_COPY_RECT = 1;
+const PSEUDO_ENCODING_DESKTOP_SIZE = -223;
+
+type Phase = 'version' | 'security' | 'security-result' | 'init' | 'running';
+
+export class RfbClient {
+  private socket: WebSocket;
+  private buffer = new Uint8Array(0);
+  private phase: Phase = 'version';
+  private width = 0;
+  private height = 0;
+  private events: RfbEvents;
+  private closed = false;
+
+  constructor(url: string, events: RfbEvents) {
+    this.events = events;
+    this.socket = new WebSocket(url);
+    this.socket.binaryType = 'arraybuffer';
+    this.socket.onmessage = (ev) => this.receive(new Uint8Array(ev.data as ArrayBuffer));
+    this.socket.onclose = () => {
+      this.closed = true;
+      this.events.onClose();
+    };
+    this.socket.onerror = () => this.events.onError('The connection to the Minesweeper session failed.');
+  }
+
+  close(): void {
+    this.closed = true;
+    try {
+      this.socket.close();
+    } catch {
+      /* already closed */
+    }
+  }
+
+  // Uint8Array<ArrayBuffer>, not plain Uint8Array: the default is Uint8Array<ArrayBufferLike>, whose
+  // buffer may be a SharedArrayBuffer, and WebSocket.send takes only BufferSource. Every caller here
+  // builds its own array, so narrowing costs nothing. The terminal relay narrows the same way.
+  private send(bytes: Uint8Array<ArrayBuffer>): void {
+    if (this.socket.readyState === WebSocket.OPEN) this.socket.send(bytes);
+  }
+
+  private receive(chunk: Uint8Array): void {
+    const merged = new Uint8Array(this.buffer.length + chunk.length);
+    merged.set(this.buffer);
+    merged.set(chunk, this.buffer.length);
+    this.buffer = merged;
+
+    // Each step consumes a whole message or nothing at all, so a message split across TCP chunks simply
+    // waits for the rest. Returning false means "not enough bytes yet".
+    while (!this.closed && this.step()) {
+      /* keep draining */
+    }
+  }
+
+  private take(n: number): Uint8Array | null {
+    if (this.buffer.length < n) return null;
+    const head = this.buffer.subarray(0, n);
+    this.buffer = this.buffer.subarray(n);
+    return head;
+  }
+
+  private step(): boolean {
+    switch (this.phase) {
+      case 'version':
+        return this.stepVersion();
+      case 'security':
+        return this.stepSecurity();
+      case 'security-result':
+        return this.stepSecurityResult();
+      case 'init':
+        return this.stepInit();
+      case 'running':
+        return this.stepMessage();
+    }
+  }
+
+  private stepVersion(): boolean {
+    const head = this.take(12);
+    if (!head) return false;
+    // Answer 3.8 regardless of what the server offered; x11vnc speaks it and anything older is a server
+    // we are not configuring.
+    this.send(new TextEncoder().encode('RFB 003.008\n'));
+    this.phase = 'security';
+    return true;
+  }
+
+  private stepSecurity(): boolean {
+    if (this.buffer.length < 1) return false;
+    const count = this.buffer[0] as number;
+    if (count === 0) {
+      // A zero count means the server is refusing us, and the reason follows as a string.
+      const body = this.take(1 + 4);
+      if (!body) return false;
+      this.events.onError('The VNC server refused the connection.');
+      this.close();
+      return false;
+    }
+    const head = this.take(1 + count);
+    if (!head) return false;
+
+    const types = Array.from(head.subarray(1));
+    if (!types.includes(1)) {
+      this.events.onError('The VNC server wants authentication, which this client does not implement.');
+      this.close();
+      return false;
+    }
+    this.send(new Uint8Array([1])); // None — the relay is loopback-only and Officer is the authenticator
+    this.phase = 'security-result';
+    return true;
+  }
+
+  private stepSecurityResult(): boolean {
+    const head = this.take(4);
+    if (!head) return false;
+    if (new DataView(head.buffer, head.byteOffset, 4).getUint32(0) !== 0) {
+      this.events.onError('The VNC server rejected the handshake.');
+      this.close();
+      return false;
+    }
+    this.send(new Uint8Array([1])); // shared: do not disconnect other viewers
+    this.phase = 'init';
+    return true;
+  }
+
+  private stepInit(): boolean {
+    if (this.buffer.length < 24) return false;
+    const nameLength = new DataView(this.buffer.buffer, this.buffer.byteOffset + 20, 4).getUint32(0);
+    const head = this.take(24 + nameLength);
+    if (!head) return false;
+
+    const view = new DataView(head.buffer, head.byteOffset, head.byteLength);
+    this.width = view.getUint16(0);
+    this.height = view.getUint16(2);
+
+    this.setPixelFormat();
+    this.setEncodings();
+    this.phase = 'running';
+    this.events.onReady(this.width, this.height);
+    this.requestUpdate(false);
+    return true;
+  }
+
+  /** 32bpp true colour, big-endian, shifts 16/8/0 — i.e. R,G,B,X on the wire, which is ImageData order. */
+  private setPixelFormat(): void {
+    const message = new Uint8Array(20);
+    const view = new DataView(message.buffer);
+    message[0] = 0; // SetPixelFormat
+    message[4] = 32; // bits per pixel
+    message[5] = 24; // depth
+    message[6] = 1; // big-endian
+    message[7] = 1; // true colour
+    view.setUint16(8, 255); // red max
+    view.setUint16(10, 255); // green max
+    view.setUint16(12, 255); // blue max
+    message[14] = 16; // red shift
+    message[15] = 8; // green shift
+    message[16] = 0; // blue shift
+    this.send(message);
+  }
+
+  private setEncodings(): void {
+    const encodings = [ENCODING_COPY_RECT, ENCODING_RAW, PSEUDO_ENCODING_DESKTOP_SIZE];
+    const message = new Uint8Array(4 + encodings.length * 4);
+    const view = new DataView(message.buffer);
+    message[0] = 2; // SetEncodings
+    view.setUint16(2, encodings.length);
+    encodings.forEach((encoding, i) => view.setInt32(4 + i * 4, encoding));
+    this.send(message);
+  }
+
+  requestUpdate(incremental = true): void {
+    const message = new Uint8Array(10);
+    const view = new DataView(message.buffer);
+    message[0] = 3; // FramebufferUpdateRequest
+    message[1] = incremental ? 1 : 0;
+    view.setUint16(6, this.width);
+    view.setUint16(8, this.height);
+    this.send(message);
+  }
+
+  private stepMessage(): boolean {
+    if (this.buffer.length < 1) return false;
+    const type = this.buffer[0] as number;
+
+    // 0 FramebufferUpdate, 1 SetColourMapEntries, 2 Bell, 3 ServerCutText. Only the first matters here;
+    // the others still have to be CONSUMED or the stream desynchronises and every later frame is garbage.
+    if (type === 0) return this.stepFramebufferUpdate();
+    if (type === 2) return this.take(1) !== null;
+    if (type === 1) {
+      if (this.buffer.length < 6) return false;
+      const count = new DataView(this.buffer.buffer, this.buffer.byteOffset + 4, 2).getUint16(0);
+      return this.take(6 + count * 6) !== null;
+    }
+    if (type === 3) {
+      if (this.buffer.length < 8) return false;
+      const length = new DataView(this.buffer.buffer, this.buffer.byteOffset + 4, 4).getUint32(0);
+      return this.take(8 + length) !== null;
+    }
+
+    this.events.onError(`The VNC server sent an unknown message type (${type}).`);
+    this.close();
+    return false;
+  }
+
+  /**
+   * Parsed without consuming anything until the WHOLE update is present. A partial rectangle cannot be
+   * drawn and cannot be put back, so the alternative is a second parser for resumed state.
+   */
+  private stepFramebufferUpdate(): boolean {
+    if (this.buffer.length < 4) return false;
+    const rectangles = new DataView(this.buffer.buffer, this.buffer.byteOffset + 2, 2).getUint16(0);
+
+    let offset = 4;
+    type Rect = { x: number; y: number; w: number; h: number; encoding: number; at: number };
+    const rects: Rect[] = [];
+
+    for (let i = 0; i < rectangles; i++) {
+      if (this.buffer.length < offset + 12) return false;
+      const view = new DataView(this.buffer.buffer, this.buffer.byteOffset + offset, 12);
+      const rect = { x: view.getUint16(0), y: view.getUint16(2), w: view.getUint16(4), h: view.getUint16(6), encoding: view.getInt32(8), at: offset + 12 };
+      offset += 12;
+
+      if (rect.encoding === ENCODING_RAW) offset += rect.w * rect.h * 4;
+      else if (rect.encoding === ENCODING_COPY_RECT) offset += 4;
+      else if (rect.encoding === PSEUDO_ENCODING_DESKTOP_SIZE) {
+        /* no payload — the rect's w/h ARE the new size */
+      } else {
+        this.events.onError(`The VNC server used encoding ${rect.encoding}, which this client did not ask for.`);
+        this.close();
+        return false;
+      }
+
+      if (this.buffer.length < offset) return false;
+      rects.push(rect);
+    }
+
+    for (const rect of rects) {
+      if (rect.encoding === PSEUDO_ENCODING_DESKTOP_SIZE) {
+        this.width = rect.w;
+        this.height = rect.h;
+        this.events.onResize(rect.w, rect.h);
+        continue;
+      }
+      if (rect.encoding === ENCODING_COPY_RECT) {
+        const src = new DataView(this.buffer.buffer, this.buffer.byteOffset + rect.at, 4);
+        this.events.onCopyRect({ x: src.getUint16(0), y: src.getUint16(2) }, rect);
+        continue;
+      }
+      // Raw: the wire bytes are already R,G,B,X, so this is a copy rather than a conversion. The alpha
+      // byte is whatever the server sent, so force it opaque.
+      const pixels = new Uint8ClampedArray(this.buffer.subarray(rect.at, rect.at + rect.w * rect.h * 4));
+      for (let i = 3; i < pixels.length; i += 4) pixels[i] = 255;
+      this.events.onFrame(new ImageData(pixels, rect.w, rect.h), rect.x, rect.y);
+    }
+
+    this.take(offset);
+
+    // One request per update message, issued once the whole message is drawn. Requesting per
+    // rectangle would send several for one update, and requesting on a timer would queue updates the
+    // client has not consumed yet — the classic way a VNC view ends up lagging behind the pointer.
+    this.requestUpdate(true);
+    return true;
+  }
+
+  /** buttons is an RFB button mask: bit 0 left, bit 1 middle, bit 2 right. */
+  pointer(x: number, y: number, buttons: number): void {
+    const message = new Uint8Array(6);
+    const view = new DataView(message.buffer);
+    message[0] = 5; // PointerEvent
+    message[1] = buttons;
+    view.setUint16(2, Math.max(0, Math.min(this.width - 1, Math.round(x))));
+    view.setUint16(4, Math.max(0, Math.min(this.height - 1, Math.round(y))));
+    this.send(message);
+  }
+
+  key(keysym: number, down: boolean): void {
+    const message = new Uint8Array(8);
+    const view = new DataView(message.buffer);
+    message[0] = 4; // KeyEvent
+    message[1] = down ? 1 : 0;
+    view.setUint32(4, keysym);
+    this.send(message);
+  }
+}
@@ -1,5 +1,6 @@
 import { useState, useEffect, useRef, useCallback } from 'react';
 import { useQueryClient } from '@tanstack/react-query';
+import { useNavigate } from 'react-router';
 import { useChatWebSocket } from 'hooks/useChatWebSocket';
 import { useClient } from 'hooks/useClient';
 import { useSettings } from 'state/useSettings';
@@ -25,6 +26,15 @@ type UsePiChatOptions = {
  projectScoped?: boolean;
  context?: string;
  contextId?: string;
+  /**
+   * The name chosen for a COMMANDER before its first message.
+   *
+   * Rides every turn rather than just the first: the server applies it once, in `fileAsCommander`, and
+   * sending it again costs a few bytes. Sending it only on the first turn would mean losing it if that turn
+   * failed and was retried, which is the case that matters — a commander named after its second prompt is
+   * the bug this exists to prevent.
+   */
+  commanderName?: string;
  resumeSummary?: string;
  resumeSessionId?: string;
  initialMessages?: ChatMessage[];
@@ -44,11 +54,23 @@ type UsePiChatOptions = {
 * contradict it — which is what a hand-edited or stale `?cwd=` used to do. Anything else in the query
 * string is left alone.
 */
-function writePermalink(claudeSessionId: string): void {
+/**
+ * The permalink, as a ROUTER navigation rather than a raw history write.
+ *
+ * It was `window.history.replaceState`, which changes the address bar and tells react-router nothing. Every
+ * consumer that reads the URL through the router therefore never saw it: on the /chat screen the title and
+ * the rename control both come from `useParams().sessionId` (see `ChatDetailPanel`), so a new conversation
+ * stayed "New chat" and could not be renamed until something else forced the router to re-read the
+ * location — which is exactly what navigating away and back did.
+ *
+ * `replace`, not push, so the browser Back button still leaves the conversation rather than stepping through
+ * the same one under a different name.
+ */
+function permalinkTo(claudeSessionId: string): { pathname: string; search: string } {
  const params = new URLSearchParams(window.location.search);
  params.delete('cwd');
  const search = params.toString();
-  window.history.replaceState(null, '', `/chat/${claudeSessionId}${search ? `?${search}` : ''}`);
+  return { pathname: `/chat/${claudeSessionId}`, search: search ? `?${search}` : '' };
 }

 export function useChat(initialSessionId?: string, initialModel?: string | null, options?: UsePiChatOptions) {
@@ -60,6 +82,7 @@ export function useChat(initialSessionId?: string, initialModel?: string | null,
    projectScoped,
    context,
    contextId,
+    commanderName,
    resumeSummary: initialResumeSummary,
    resumeSessionId,
    initialMessages: preloadedMessages,
@@ -202,6 +225,21 @@ export function useChat(initialSessionId?: string, initialModel?: string | null,

  const client = useClient();
  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+
+  /*
+    Written through the router so `useParams` updates. A raw `history.replaceState` moves the address bar and
+    leaves react-router believing the location is unchanged — see `permalinkTo`.
+
+    In a ref because the message handler is re-created per render and closes over whatever it had; a stable
+    callback keeps the socket's copy valid.
+  */
+  const writePermalink = useCallback(
+    (claudeSessionId: string) => {
+      navigate(permalinkTo(claudeSessionId), { replace: true });
+    },
+    [navigate],
+  );

  /*
    Tell the session LISTS that this conversation exists.
@@ -263,9 +301,19 @@ export function useChat(initialSessionId?: string, initialModel?: string | null,
    });
  }

-  function commitStreaming() {
-    if (!streamingRef.current) return;
-    const text = streamingRef.current;
+  /**
+   * Turn the in-flight streaming buffer into a committed message.
+   *
+   * `authoritative` is the complete text from the `assistant:text` event that ends the stream, and it
+   * wins whenever it is present. The buffer is an accumulation of deltas and is only ever as good as the
+   * socket: lose one frame — a restart mid-turn will do it — and it is short by whatever that frame
+   * carried, while the event carries the whole message. Committing the buffer threw away a correct copy
+   * in favour of a damaged one, which is how a reply rendered as "ipped." with its first two characters
+   * missing while the durable log held it intact.
+   */
+  function commitStreaming(authoritative?: string) {
+    if (!streamingRef.current && !authoritative) return;
+    const text = authoritative ?? streamingRef.current;
    streamingRef.current = '';
    setStreamingText('');
    setMessages((prev) => [...prev, { role: 'assistant', id: randomId(), text }]);
@@ -389,7 +437,7 @@ export function useChat(initialSessionId?: string, initialModel?: string | null,
          break;
        }
        if (streamingRef.current) {
-          commitStreaming();
+          commitStreaming(msg.text);
        } else {
          setMessages((prev) => [...prev, { role: 'assistant', id: randomId(), text: msg.text }]);
        }
@@ -754,6 +802,20 @@ export function useChat(initialSessionId?: string, initialModel?: string | null,
     * exact message that starts the watching turn, not a later one.
     */
    armWatcher?: boolean,
+    /**
+     * Anything else this turn needs to say about ITSELF rather than about its content.
+     *
+     * An object rather than a tenth positional: nine is already past the point where a call site reads as
+     * a row of undefineds, and every flag added here would make that worse for every existing caller.
+     */
+    opts?: {
+      /**
+       * The owner pressed Start instead of typing an opening message, so this turn is a request for the
+       * commander to interview them — see `commanderBlock`. Only the client that rendered the button can
+       * know this, which is why it rides the message rather than being derived on the server.
+       */
+      selfStarted?: boolean;
+    },
  ) {
    // Mark session as started on first message
    if (!hasStarted) {
@@ -794,6 +856,7 @@ export function useChat(initialSessionId?: string, initialModel?: string | null,
      type: 'chat',
      prompt: text,
      ...(displayText ? { displayText } : {}),
+      ...(opts?.selfStarted ? { selfStarted: true } : {}),
      sessionId: sessionIdRef.current,
      ...(selectedModel ? { model: selectedModel } : {}),
      ...(cwdParam?.path ? { cwd: cwdParam.path } : {}),
@@ -806,6 +869,7 @@ export function useChat(initialSessionId?: string, initialModel?: string | null,
      ...(thinking ? { thinking } : {}),
      ...(context ? { context } : {}),
      ...(contextId ? { contextId } : {}),
+      ...(commanderName ? { commanderName } : {}),
      ...(pendingResumeSummary ? { resumeSummary: pendingResumeSummary } : {}),
      ...(resumeSessionId ? { resumeSessionId } : {}),
      ...(armWatcher ? { armWatcher } : {}),
@@ -27,7 +27,8 @@ export type LiveSession = {
  title: string | null;
  cwd: string | null;
  /**
-   * A commander rather than an ordinary chat, derived server-side from the cwd.
+   * A commander rather than an ordinary chat, derived server-side from its `command_hq_sessions` row.
+   * NOT from the cwd — a commander chooses its own working directory, so the directory answers nothing.
   *
   * Every consumer of this list needs it, and one of them cannot work around its absence. The sessions
   * panel splits Live into two tabs; the iPhone app swipes between live chats, has no tabs, and so can only
@@ -36,6 +37,12 @@ export type LiveSession = {
  isCommander: boolean;
 };

+/**
+ * Counts describe every live session, not just the ones returned — so a filtered request still renders
+ * `Agents (n) / Commanders (n)` without a second round trip.
+ */
+type LivePayload = { sessions: LiveSession[]; counts: { agents: number; commanders: number } };
+
 const LIVE_KEY = 'CHAT_LIVE_SESSIONS';

 /**
@@ -50,9 +57,17 @@ export function useLiveSessions() {
  const client = useClient();
  const { isAuthenticated } = useAuth();

-  const { data, isLoading, error, refetch } = useQuery<{ sessions: LiveSession[] }>({
+  /*
+    `kind=all` is required, not a default. `/chat/live` returns ONLY agents unless asked otherwise, so that
+    a caller which forgets can never be handed a commander — a phone swiping between live chats one at a
+    time has no way to skip one. This list is the other case: it renders both kinds as tabs, so it asks for
+    both, explicitly, and the explicitness is what makes it reviewable.
+
+    `counts` describes the whole set either way, which is why both tab numbers are right from one request.
+  */
+  const { data, isLoading, error, refetch } = useQuery<LivePayload>({
    queryKey: [LIVE_KEY],
-    queryFn: () => client.get<{ sessions: LiveSession[] }>('/chat/live'),
+    queryFn: () => client.get<LivePayload>('/chat/live?kind=all'),
    enabled: isAuthenticated,
    refetchInterval: 10_000,
    staleTime: 5_000,
@@ -0,0 +1,39 @@
+---
+id: background-jobs/a-commander-picks-the-cheapest-model-that-will
+title: 'A commander picks the cheapest model that will do the job — for itself and for what it spawns'
+theme: background-jobs
+status: open
+created: 2026-08-22
+date_source: stated
+order: 2
+---
+
+**Before it arms anything, a commander should weigh how hard the job actually is and say which model each
+half should run on.** Wanted 2026-08-22, for later.
+
+**Two models, not one**, and this is the part that makes it worth doing rather than a generic "use a cheaper
+model" note. A commander has two quite different workloads:
+
+- **the commander's own turns** — agreeing the job with the owner, writing a shell loop, reporting. Mostly
+  conversation and one piece of bash.
+- **the agent the loop SPAWNS when it fires** — which does the actual work, and whose difficulty is set by
+  the job rather than by the conversation.
+
+Those can differ by a lot in the same commander. The deploy commander is the worked example: its own turns
+ran on Sonnet and were unremarkable, while the spawned agent judged six hosts, parsed a plan, decided what to
+skip and wrote an honest report. A watcher that pings a URL and echoes the status needs neither to be clever.
+
+**Inferred from the job, and SUGGESTED rather than imposed.** The commander proposes ("this looks like Haiku
+for the watch and Sonnet for the action, because…") and the owner overrides. A model chosen silently is one
+nobody can argue with, and the failure mode of choosing too small is not a slower answer — it is a watcher
+that fires on the wrong condition, or an agent that half-finishes a deploy.
+
+**Where it goes:** a section in the Commanders skill, beside the four shaping questions, since the moment to
+ask it is the same moment — while the job is being agreed and before anything is armed. It is one more thing
+to settle in the conversation the skill already describes.
+
+**What would make it honest rather than a guess**, and the reason this is not urgent: nothing currently
+measures whether the choice was right. The cost of a spawned agent is not recorded at all yet
+(`command_hq_spawned.total_usd` exists and is always null), so a commander suggesting Haiku has no way to
+learn it was wrong. Worth doing after cost accounting, or at least knowing that until then this is a
+judgement with no feedback loop.
@@ -0,0 +1,32 @@
+---
+id: infra/revisit-the-bun-1-3-pin-once-1-4-has-been
+title: 'Revisit the bun 1.3 pin once 1.4 has been watched for a while'
+theme: infra
+status: open
+created: 2026-08-22
+date_source: stated
+order: 6
+---
+
+**Revisit the bun 1.3 pin once 1.4 has been watched for a while.** Raised by the owner 2026-08-22,
+who asked for it explicitly as a temporary hold — "a few months, until I'm sure the new 1.4 is going
+to be safe" — so this exists to stop a deliberate pause becoming permanent by nobody remembering it.
+
+bun 1.4.0 was published 2026-08-20 and `https://bun.sh/install` serves whatever is newest, so a
+machine provisioned on 2026-08-22 would have put a two-day-old release under the platform and every
+pm2 app except `officer-pty`. The hold is at the SERIES, not a patch: `BUN_SERIES=1.3` in
+`scripts/setup/machine-setup/lib/dev.sh`, resolved to the newest `1.3.x` from the npm registry at
+install time, so bug fixes inside the series still land.
+
+Two places carry the number and they must move together — `BUN_SERIES` in `dev.sh`, and
+`engines.bun` in `package.json`, which is what `bun run doctor` reads to decide whether the running
+bun has drifted. bun itself ignores `engines` (verified: an install declaring `1.9.x` ran clean under
+1.3.14), so that field is a declaration and doctor is the enforcement.
+
+What is NOT covered, and is the reason a drift check exists at all: `bun upgrade` takes no version
+argument — latest-stable or `--canary`, nothing else — so it always jumps to the newest release and
+walks a pinned machine off the pin silently. Nothing in a setup script can prevent that; `bun run
+doctor` reports it after the fact, and `machine-setup.sh --only 'JavaScript runtimes'` offers to pin
+it back down.
+
+To lift the hold: raise both numbers, run `bun run doctor` on each machine, and delete this item.