From 52d1e8bde911f437bb056a25994e96b5c6daad6c Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 10:34:23 -0400
Subject: [PATCH 01/24] feat(capacity): publish the dashboard as a persistent
 tailnet-only command service

Add bin/fm-dash-serve.mjs, a loopback service published tailnet-only through
tailscale serve (never Funnel) that wears the producer dashboard unchanged and
injects an interactive layer for the captain-authenticated tailnet identity:
one-click CAP action approval, decision option approval, idea verdicts over
data/ideas/, server-side and interval capacity refresh, and de-anonymized
clickable work-item and decision detail views assembled from briefs, recorded
metadata, the backlog, status tails, and scout reports.

Clicked commands never execute in the web process: each becomes one durable
fm-dash-command.v1 record in state/dash-inbox/, surfaced to the running
firstmate through the registered fm-dash watcher check and claimed exactly
once with bin/fm-dash-inbox.sh under the capacity skill's authority limits.
bin/fm-dash-install.sh owns launchd persistence (RunAtLoad + KeepAlive +
kickstart), the never-Funnel serve mapping with post-install verification,
config/dash.json, and a --read-only install shape for serving ahead of
command wiring.

fm-capacity.mjs gains the opt-in --refs identity sidecar it owns so the
authenticated service can enrich the page while the on-disk dashboard stays
identity-opaque, plus a fix for the rollcall empty-state wrapping. AGENTS.md,
docs/configuration.md, docs/dashboard-service.md, docs/scripts.md, and the
capacity skill carry the contract; tests/fm-dash.test.sh covers identity
fail-closed behavior, dispatch validation, detail assembly, idea verdicts,
read-only mode, inbox claim, the watcher check, and the installer's funnel-free
structure.
---
 .agents/skills/capacity/SKILL.md |   18 +-
 .gitignore                       |    1 +
 AGENTS.md                        |    7 +-
 bin/fm-capacity.mjs              |   40 +-
 bin/fm-dash-inbox.sh             |  121 ++++
 bin/fm-dash-install.sh           |  275 ++++++++
 bin/fm-dash-serve.mjs            | 1089 ++++++++++++++++++++++++++++++
 docs/configuration.md            |    7 +
 docs/dashboard-service.md        |   85 +++
 docs/scripts.md                  |    3 +
 tests/fm-dash.test.sh            |  397 +++++++++++
 11 files changed, 2035 insertions(+), 8 deletions(-)
 create mode 100755 bin/fm-dash-inbox.sh
 create mode 100755 bin/fm-dash-install.sh
 create mode 100755 bin/fm-dash-serve.mjs
 create mode 100644 docs/dashboard-service.md
 create mode 100644 tests/fm-dash.test.sh

diff --git a/.agents/skills/capacity/SKILL.md b/.agents/skills/capacity/SKILL.md
index 3e67fbf0a86..704dbb78ef4 100644
--- a/.agents/skills/capacity/SKILL.md
+++ b/.agents/skills/capacity/SKILL.md
@@ -28,7 +28,7 @@ Structured captain holds and the keyed open-decision fold are the only decision
 
 The generated dashboard is a polished, responsive, accessible, self-contained HTML file that works directly from disk.
 Do not invoke, depend on, open, poll, share, or embed Lavish for `/capacity`.
-Do not expose the dashboard through a local, LAN, Tailscale, public, or third-party service.
+Do not expose the dashboard through any local, LAN, public, or third-party service; the sole sanctioned exposure is the tailnet-only dashboard service in section 6, and even that surface is never Funnel and never public.
 The normal invocation may replace only the generated private dashboard and must not write a cache unless the producing script's help explicitly adds and owns one in the future.
 Never put secrets, credentials, PHI, production data, or report bodies into the dashboard.
 
@@ -84,3 +84,19 @@ Do not compare against, incrementally patch, or rely on the prior dashboard as c
 The normal `/capacity` invocation is read-mostly and must not dispatch, merge, tear down, mutate task state, edit the backlog, register decisions, or create speculative work as a side effect.
 If the fresh result reveals an action, report its stable ID and wait for or discuss the captain's ordinary chat direction.
 Continue the already-required live supervision cycle after presenting the result whenever fleet work or X mode is under way.
+
+## 6. Dashboard command service
+
+The optional persistent dashboard service (`bin/fm-dash-serve.mjs`, installed by `bin/fm-dash-install.sh`, designed in `docs/dashboard-service.md`) publishes the generated dashboard tailnet-only, never Funnel, and lets the captain click a current `CAP-NN` action or a server-side refresh.
+The service never executes fleet commands: a click only writes a durable command record into `state/dash-inbox/`, and the registered `fm-dash` watcher check wakes Firstmate while records are pending.
+Its refresh button reruns the producer server-side and is equivalent to a fresh normal invocation, so it needs no Firstmate action.
+
+On a `check:` wake naming `fm-dash.check.sh`, run `bin/fm-dash-inbox.sh claim` and handle each claimed record by its kind:
+
+- A `CAP-NN` record is the captain's ordinary chat approval of that action ID under section 4, including its full re-resolution and authority limits.
+- A `decision` record is the captain's answer for the named decision key with the recorded option text; route it through `decision-hold-lifecycle` exactly as a chat answer, and re-confirm in chat before acting when the chosen option has a destructive or irreversible consequence.
+- An `idea` record is the captain's verdict on the named `data/ideas/` idea: on approve, create the follow-up work item(s) through the normal backlog lifecycle; on deny, record the outcome against the idea; on suggest, treat the suggestion text as captain input on that idea.
+
+A claimed record never authorizes a PR merge, `local-only` landing, destructive action, irreversible action, security-sensitive action, or discard of unlanded work; when a claimed action leads to such a choice, escalate it to captain chat exactly as section 4 requires.
+Report the outcome of handled commands to the captain through normal escalation etiquette rather than assuming the dashboard told them.
+While the service is installed and registered, treat pending dashboard commands like X-mode mentions for supervision: keep the live supervision cycle running even with no other fleet work so a click can wake Firstmate.
diff --git a/.gitignore b/.gitignore
index 5ed2da0c32a..4f6425a4d57 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,3 +16,4 @@ config/backend
 config/x-mode.env
 config/cmux-socket-password
 config/wedge-alarm
+config/dash.json
diff --git a/AGENTS.md b/AGENTS.md
index e0bb07a8f1f..8ac15b6ac0e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -71,6 +71,7 @@ config/backend  runtime session-provider backend override for new tasks; LOCAL,
 config/cmux-socket-password  optional cmux control-socket password; LOCAL, gitignored; read fresh on every cmux CLI call and passed through without ever overriding an operator's own ambient CMUX_SOCKET_PASSWORD when absent (docs/cmux-backend.md "Setup")
 config/wedge-alarm  optional away-mode wedge-alarm active-alert directives; LOCAL, gitignored; absent means auto (macOS Notification Center when available); see docs/wedge-alarm.md
 config/x-mode.env    generated X-mode watcher cadence; LOCAL, gitignored; source before arming watcher when present
+config/dash.json     optional capacity dashboard service settings (loopback port, authorized captain tailnet logins); LOCAL, gitignored; written by bin/fm-dash-install.sh (docs/dashboard-service.md)
 data/                personal fleet records; LOCAL, gitignored as a whole
   backlog.md         task queue, dependencies, history
   captain.md         this home's domain-local captain preferences and working style; LOCAL, gitignored, canonical even if harness memory mirrors it, and updated with inspect-then-update
@@ -99,6 +100,9 @@ state/               volatile runtime signals; gitignored
   x-context/         generated X-mode durable per-request reply context (platform/budget), keyed by request_id; survives inbox cleanup so a delayed follow-up recovers the original platform (section 14; bin/fm-x-lib.sh)
   x-outbox/          generated X-mode dry-run reply and dismiss previews; inspect it when FMX_DRY_RUN is set (section 14)
   x-poll.error       generated X-mode relay diagnostic dedupe marker
+  fm-dash.check.sh   registered dashboard-service command poll; wakes firstmate while captain dashboard commands are pending (section 7; docs/dashboard-service.md)
+  dash-inbox/        durable captain commands clicked on the served capacity dashboard; claimed exactly once with bin/fm-dash-inbox.sh under the capacity skill
+  dash-refs.json     producer-owned private mapping from opaque dashboard references to real identities, written by fm-capacity.mjs --refs for the authenticated dashboard service
   .wake-queue        durable queued wakes: epoch<TAB>seq<TAB>kind<TAB>key<TAB>payload
   .wake-queue.seq    monotonic wake sequence used to distinguish a normal watcher wake handoff from a silent arm-cycle death
   .watcher-arm-dead  durable alarm from an arm cycle that ended without a wake handoff or healthy successor while tasks remain; cleared by a confirmed healthy arm or normal handoff
@@ -313,6 +317,7 @@ When the captain invokes `/user-journey-audit` or explicitly asks for a user-jou
 That invocation narrowly authorizes confirmed ordinary reversible bug implementation, never feature implementation or merge, and the skill owns the conditional procedure.
 
 When the captain invokes `/capacity` or asks about capacity, bottlenecks, pipeline utilization, work supply, idle lanes, or maximizing fleet throughput, load `capacity`.
+Also load `capacity` on a `check:` wake naming `fm-dash.check.sh`: it delivers captain-clicked dashboard commands, and the skill owns their claim and handling.
 That read-mostly skill owns the conditional procedure and must never invent work, dispatch for utilization, or weaken lifecycle safety.
 
 ## 8. Supervision protocol
@@ -320,7 +325,7 @@ That read-mostly skill owns the conditional procedure and must never invent work
 Fleet supervision is an always-loaded operational contract; `docs/architecture.md`, `docs/turnend-guard.md`, the emitted session-start block, and script help own mechanisms and harness-specific recipes.
 
 Whenever work is under way, keep exactly one live supervision cycle using the emitted protocol for this primary harness.
-X mode may require that same live cycle with no fleet work.
+X mode or an installed dashboard command service may require that same live cycle with no fleet work.
 Do not substitute another harness's wait shape, use shell `&`, or create a second cycle when a healthy one already exists.
 After every actionable wake, resume the emitted protocol as the final action before ending the turn.
 No turn ends blind while work is under way, including turns described as holding or waiting.
diff --git a/bin/fm-capacity.mjs b/bin/fm-capacity.mjs
index a9cefa29e4a..7da76654d69 100755
--- a/bin/fm-capacity.mjs
+++ b/bin/fm-capacity.mjs
@@ -21,9 +21,10 @@
  * Run --help for the exact inherited snapshot bounds, environment-probe budget,
  * bottleneck order, CAP-01 through CAP-10 meanings, and output replacement rules.
  *
- * The producer is read-mostly. It writes only the selected dashboard path and
- * never dispatches, merges, tears down, changes backlog/task state, or opens a
- * service. Inline dashboard JavaScript copies prompts only and cannot run actions.
+ * The producer is read-mostly. It writes only the selected dashboard path,
+ * plus the opt-in --refs identity sidecar it owns for the authenticated
+ * dashboard service, and never dispatches, merges, tears down, changes
+ * backlog/task state, or opens a service. Inline dashboard JavaScript copies prompts only and cannot run actions.
  * Live environment probes share one 30-second fleet-wide deadline and preserve
  * unavailable evidence for homes that cannot be inspected within that bound.
  */
@@ -60,7 +61,7 @@ const STAGE_LABELS = {
 
 function usage(exitCode = 0) {
   const out = exitCode === 0 ? process.stdout : process.stderr;
-  out.write(`usage: fm-capacity.mjs [--json] [--output <path>] [--snapshot <json>] [--environment <json>]
+  out.write(`usage: fm-capacity.mjs [--json] [--output <path>] [--snapshot <json>] [--environment <json>] [--refs <path>]
 
 Gather a fresh bounded fleet snapshot, classify meaningful capacity, and atomically
 replace a self-contained offline dashboard. The default destination is
@@ -71,6 +72,13 @@ must not traverse a symlink below FM_HOME or replace a symlink leaf, and is mode
 --environment are deterministic fixture inputs for tests/offline review and must not
 be used for a normal /capacity run.
 
+--refs additionally writes the fm-capacity-refs.v1 sidecar this producer owns: the
+private mode-0600 mapping from every opaque dashboard reference (item-NN, project-NN,
+home-NN) to its real identity. The dashboard itself stays identity-opaque; the sidecar
+exists so the captain-authenticated tailnet dashboard service (bin/fm-dash-serve.mjs)
+can enrich the page and serve rich detail views without weakening the offline file.
+The sidecar path must stay inside the effective state or data directory.
+
 MODEL fm-capacity.v1
   generated, dashboard_path, provenance, measures, primary_bottleneck, pipeline,
   lanes, readiness, aging, recommendations, omissions. Pipeline owns queued, ready,
@@ -105,7 +113,7 @@ BOTTLENECK ORDER AND STABLE ACTIONS
 }
 
 function parseArgs(argv) {
-  const opts = { json: false, output: null, snapshot: null, environment: null };
+  const opts = { json: false, output: null, snapshot: null, environment: null, refs: null };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--json") opts.json = true;
@@ -115,9 +123,11 @@ function parseArgs(argv) {
     else if (arg.startsWith("--snapshot=")) opts.snapshot = arg.slice(11);
     else if (arg === "--environment") opts.environment = argv[++i];
     else if (arg.startsWith("--environment=")) opts.environment = arg.slice(14);
+    else if (arg === "--refs") opts.refs = argv[++i];
+    else if (arg.startsWith("--refs=")) opts.refs = arg.slice(7);
     else if (arg === "-h" || arg === "--help") usage(0);
     else usage(2);
-    if ((arg === "--output" || arg === "--snapshot" || arg === "--environment") && !argv[i]) usage(2);
+    if ((arg === "--output" || arg === "--snapshot" || arg === "--environment" || arg === "--refs") && !argv[i]) usage(2);
   }
   return opts;
 }
@@ -1343,6 +1353,7 @@ function renderHtml(model, captainActions) {
     .needs-you h2{color:var(--serious)}.blocked-items h2{color:var(--crit)}
     .rollcall ul{margin-top:.6rem}
     .rollcall li{display:grid;grid-template-columns:5.2rem minmax(0,.45fr) minmax(0,1fr);gap:.4rem 1.1rem;align-items:baseline;border-top:1px solid color-mix(in srgb,var(--sev) 30%,var(--hair));padding:.55rem 0;font-size:1.02rem;min-width:0}
+    .rollcall li.empty{display:block}
     .verb{font-weight:800;text-transform:uppercase;letter-spacing:.08em;font-size:.72rem}
     .verb-approve{color:var(--blue)}.verb-decide{color:var(--serious)}.verb-blocked{color:var(--crit)}
     .who{font-weight:650;min-width:0}.who .item-id{margin-right:.35rem}
@@ -1474,6 +1485,23 @@ function main() {
   }
   const { model, captainActions } = classify(snapshot, environment);
   writePrivateAtomic(output, renderHtml(model, captainActions), snapshot.fm_home || path.dirname(allowedData));
+  if (opts.refs) {
+    const allowedState = path.resolve(snapshot.roots?.state || path.join(snapshot.fm_home || ROOT, "state"));
+    const refsPath = path.resolve(opts.refs);
+    const insideOf = (root) => {
+      const relative = path.relative(root, refsPath);
+      return relative && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    };
+    if (!insideOf(allowedState) && !insideOf(allowedData)) {
+      throw new Error("refs sidecar path must stay inside the effective state or data directory");
+    }
+    const refs = {};
+    for (const [key, ref] of opaqueRefs.entries()) {
+      const separator = key.indexOf("\0");
+      refs[ref] = { kind: key.slice(0, separator), value: key.slice(separator + 1) };
+    }
+    writePrivateAtomic(refsPath, `${JSON.stringify({ schema: "fm-capacity-refs.v1", generated: model.generated, refs }, null, 2)}\n`, snapshot.fm_home || path.dirname(allowedData));
+  }
   if (opts.json) {
     process.stdout.write(`${JSON.stringify(model, null, 2)}\n`);
   } else {
diff --git a/bin/fm-dash-inbox.sh b/bin/fm-dash-inbox.sh
new file mode 100755
index 00000000000..d0b9d4a4b5f
--- /dev/null
+++ b/bin/fm-dash-inbox.sh
@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# fm-dash-inbox.sh - firstmate-side consumer for captain dashboard commands.
+#
+# Single owner of state/dash-inbox/ consumption: listing pending
+# fm-dash-command.v1 records written by bin/fm-dash-serve.mjs and claiming them
+# durably. "claim" atomically archives each record under
+# state/dash-inbox/archive/ (newest 50 kept) and prints it, so a command is
+# surfaced exactly once even across interrupted turns; a claim that printed is a
+# claim that archived. Consumption semantics are owned by the capacity skill:
+# each claimed prompt is the captain's approval of that CAP action ID with all
+# of that skill's authority limits, never destructive or merge authority.
+#
+# Usage: fm-dash-inbox.sh [list|claim|pending-count]
+#   list           print pending commands without consuming them
+#   claim          archive and print pending commands for handling
+#   pending-count  print the number of pending commands
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
+STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+INBOX="$STATE/dash-inbox"
+ARCHIVE="$INBOX/archive"
+ARCHIVE_KEEP=50
+
+usage() {
+  sed -n 's/^# \{0,1\}//p' "${BASH_SOURCE[0]}" | sed -n '2,15p'
+  exit "${1:-0}"
+}
+
+pending_files() {
+  [ -d "$INBOX" ] || return 0
+  find "$INBOX" -maxdepth 1 -name '*.json' -type f 2>/dev/null | LC_ALL=C sort
+}
+
+print_record() {
+  local file=$1
+  # shellcheck disable=SC2016 # the $-expressions below are JavaScript template literals, not shell
+  node -e '
+    const fs = require("node:fs");
+    try {
+      const r = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+      if (r.schema !== "fm-dash-command.v1" || typeof r.id !== "string" || typeof r.prompt !== "string") {
+        console.log(`- unreadable record ${process.argv[1]} (unexpected schema); inspect it by hand`);
+        process.exit(0);
+      }
+      console.log(`- ${r.id} requested by ${r.requested_by || "unknown"} at ${r.requested_at || "unknown"} (dashboard generated ${r.dashboard_generated || "unknown"})`);
+      console.log(`  prompt: ${r.prompt.replace(/\s+/g, " ")}`);
+    } catch {
+      console.log(`- unreadable record ${process.argv[1]} (invalid JSON); inspect it by hand`);
+    }
+  ' "$file"
+}
+
+prune_archive() {
+  local extra
+  extra=$(find "$ARCHIVE" -maxdepth 1 -name '*.json' -type f 2>/dev/null | LC_ALL=C sort -r | tail -n +$((ARCHIVE_KEEP + 1)))
+  [ -n "$extra" ] || return 0
+  printf '%s\n' "$extra" | while IFS= read -r old; do
+    rm -f -- "$old"
+  done
+}
+
+command -v node >/dev/null 2>&1 || { echo "error: node is required to read dashboard command records" >&2; exit 1; }
+
+case "${1:-list}" in
+  -h|--help)
+    usage 0
+    ;;
+  pending-count)
+    pending_files | grep -c . || true
+    ;;
+  list)
+    files=$(pending_files)
+    if [ -z "$files" ]; then
+      echo "no pending dashboard commands"
+      exit 0
+    fi
+    printf 'pending: %s captain dashboard command(s)\n' "$(printf '%s\n' "$files" | grep -c .)"
+    printf '%s\n' "$files" | while IFS= read -r f; do
+      print_record "$f"
+    done
+    ;;
+  claim)
+    files=$(pending_files)
+    if [ -z "$files" ]; then
+      echo "no pending dashboard commands"
+      exit 0
+    fi
+    mkdir -p "$ARCHIVE"
+    chmod 700 "$ARCHIVE" 2>/dev/null || true
+    count=0
+    claimed=""
+    while IFS= read -r f; do
+      dest="$ARCHIVE/$(basename "$f")"
+      # rename-based claim: a record either stays pending or is archived; a
+      # concurrent claimer loses the rename and skips the record.
+      if mv -n -- "$f" "$dest" 2>/dev/null && [ ! -e "$f" ] && [ -e "$dest" ]; then
+        count=$((count + 1))
+        claimed="$claimed$dest"$'\n'
+      fi
+    done <<EOF
+$files
+EOF
+    if [ "$count" -eq 0 ]; then
+      echo "no pending dashboard commands"
+      exit 0
+    fi
+    printf 'claimed: %s captain dashboard command(s)\n' "$count"
+    printf '%s' "$claimed" | while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      print_record "$f"
+    done
+    echo "handle each prompt as the captain's approval of that action ID under the capacity skill; its authority limits apply and nothing here authorizes a merge, discard, or other destructive act."
+    prune_archive
+    ;;
+  *)
+    usage 2 >&2
+    ;;
+esac
diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
new file mode 100755
index 00000000000..6b1ddf294c3
--- /dev/null
+++ b/bin/fm-dash-install.sh
@@ -0,0 +1,275 @@
+#!/usr/bin/env bash
+# fm-dash-install.sh - persistent tailnet-only publication of the capacity dashboard.
+#
+# Single owner of dashboard-service persistence: the launchd agent that keeps
+# bin/fm-dash-serve.mjs running across reboots, the tailscale serve proxy that
+# exposes it tailnet-only at one stable HTTPS URL, config/dash.json, and the
+# registered fm-dash watcher check that lets clicked commands wake firstmate.
+# It never enables Funnel: the serve mapping is tailnet-only by construction and
+# install verifies Funnel is off for the served port, tearing the mapping back
+# down and refusing if any Funnel exposure is detected.
+#
+# Usage: fm-dash-install.sh <command> [options]
+#   install       write config, launchd agent, tailscale serve mapping, and the
+#                 fm-dash watcher check; idempotent, prints the stable URL
+#   uninstall     remove the serve mapping and launchd agent; keeps config and
+#                 any pending commands in state/dash-inbox/
+#   status        report agent, serve mapping, and pending-command state
+#   print-plist   print the launchd plist to stdout without installing
+#   write-check   write and register only the fm-dash watcher check
+# Options:
+#   --port <n>        local loopback port for the service (default 8847)
+#   --serve-port <n>  tailnet HTTPS port for tailscale serve (default 8443)
+#   --captain <login> authorized tailnet login; repeatable; defaults to the
+#                     tailnet self login reported by tailscale status
+#   --read-only       serve the dashboard without command dispatch and skip the
+#                     watcher check; for running the service ahead of command wiring
+# FM_HOME selects the home; scripts and the service always run from this
+# checkout. docs/dashboard-service.md owns the architecture and evidence.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
+STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+CONFIG_DIR="$FM_HOME/config"
+CONFIG="$CONFIG_DIR/dash.json"
+CHECK="$STATE/fm-dash.check.sh"
+DEFAULT_PORT=8847
+DEFAULT_SERVE_PORT=8443
+
+usage() {
+  sed -n 's/^# \{0,1\}//p' "${BASH_SOURCE[0]}" | sed -n '2,29p'
+  exit "${1:-0}"
+}
+
+err() {
+  printf 'error: %s\n' "$1" >&2
+  exit 1
+}
+
+home_label() {
+  local hash
+  hash=$(printf '%s' "$FM_HOME" | { shasum -a 256 2>/dev/null || sha256sum; } | awk '{print substr($1,1,8)}')
+  printf 'io.firstmate.dashboard.%s' "$hash"
+}
+
+node_bin() {
+  command -v node || err "node is required"
+}
+
+tailscale_bin() {
+  command -v tailscale || err "the tailscale CLI is required"
+}
+
+tailscale_self_json() {
+  "$(tailscale_bin)" status --json 2>/dev/null
+}
+
+tailscale_self_login() {
+  tailscale_self_json | node -e '
+    let raw = "";
+    process.stdin.on("data", (c) => { raw += c; });
+    process.stdin.on("end", () => {
+      try {
+        const s = JSON.parse(raw);
+        const user = s.User && s.Self ? s.User[s.Self.UserID] : null;
+        if (user && user.LoginName) { console.log(user.LoginName); return; }
+      } catch {}
+      process.exit(1);
+    });
+  '
+}
+
+tailscale_self_dnsname() {
+  tailscale_self_json | node -e '
+    let raw = "";
+    process.stdin.on("data", (c) => { raw += c; });
+    process.stdin.on("end", () => {
+      try {
+        const s = JSON.parse(raw);
+        if (s.Self && s.Self.DNSName) { console.log(s.Self.DNSName.replace(/\.$/, "")); return; }
+      } catch {}
+      process.exit(1);
+    });
+  '
+}
+
+# Refuse loudly if any Funnel exposure exists for the served port. Funnel is
+# never acceptable for this service.
+assert_no_funnel() {
+  local serve_port=$1
+  "$(tailscale_bin)" serve status --json 2>/dev/null | node -e '
+    let raw = "";
+    process.stdin.on("data", (c) => { raw += c; });
+    process.stdin.on("end", () => {
+      try {
+        const s = JSON.parse(raw || "{}");
+        const allow = s.AllowFunnel || {};
+        for (const [hostport, enabled] of Object.entries(allow)) {
+          if (enabled && hostport.endsWith(":" + process.argv[1])) {
+            console.error("funnel is enabled for " + hostport);
+            process.exit(1);
+          }
+        }
+      } catch {}
+    });
+  ' "$serve_port"
+}
+
+write_config() {
+  local port=$1 read_only=$2
+  shift 2
+  mkdir -p "$CONFIG_DIR"
+  node -e '
+    const fs = require("node:fs");
+    const [config, port, readOnly, ...logins] = process.argv.slice(1);
+    const payload = { port: Number(port), captain_logins: logins, read_only: readOnly === "true" };
+    fs.writeFileSync(config, JSON.stringify(payload, null, 2) + "\n", { mode: 0o600 });
+  ' "$CONFIG" "$port" "$read_only" "$@" || err "could not write $CONFIG"
+  chmod 600 "$CONFIG" 2>/dev/null || true
+}
+
+render_plist() {
+  local label=$1 node_path=$2 log_dir=$3
+  cat <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>$label</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>$node_path</string>
+    <string>$FM_ROOT/bin/fm-dash-serve.mjs</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>FM_HOME</key><string>$FM_HOME</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>$log_dir/dash-serve.log</string>
+  <key>StandardErrorPath</key><string>$log_dir/dash-serve.log</string>
+</dict>
+</plist>
+PLIST
+}
+
+write_check() {
+  mkdir -p "$STATE"
+  cat > "$CHECK" <<'SHIM'
+#!/bin/sh
+# fm-dash watcher check - wakes firstmate when captain dashboard commands are
+# pending in state/dash-inbox/. Written and registered by bin/fm-dash-install.sh.
+state_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)
+inbox="$state_dir/dash-inbox"
+[ -d "$inbox" ] || exit 0
+count=0
+for f in "$inbox"/*.json; do
+  [ -e "$f" ] || continue
+  count=$((count + 1))
+done
+[ "$count" -gt 0 ] || exit 0
+printf 'dashboard: %s captain command(s) pending - run bin/fm-dash-inbox.sh claim and handle them under the capacity skill\n' "$count"
+SHIM
+  chmod 700 "$CHECK"
+  "$SCRIPT_DIR/fm-check-register.sh" fm-dash || err "could not register the fm-dash watcher check"
+}
+
+cmd_install() {
+  local port=$DEFAULT_PORT serve_port=$DEFAULT_SERVE_PORT read_only=false captains=() label plist_path node_path dnsname
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --port) port=${2:?--port needs a value}; shift 2 ;;
+      --serve-port) serve_port=${2:?--serve-port needs a value}; shift 2 ;;
+      --captain) captains+=("${2:?--captain needs a value}"); shift 2 ;;
+      --read-only) read_only=true; shift ;;
+      *) err "unknown install option: $1" ;;
+    esac
+  done
+  [ "$(uname)" = Darwin ] || err "install requires macOS launchd; on another OS run bin/fm-dash-serve.mjs under your init system and proxy it with tailscale serve (never funnel)"
+  command -v launchctl >/dev/null 2>&1 || err "launchctl is required"
+  node_path=$(node_bin)
+  tailscale_bin >/dev/null
+
+  if [ "${#captains[@]}" -eq 0 ]; then
+    local self_login
+    self_login=$(tailscale_self_login) || err "could not resolve the tailnet self login; pass --captain <login>"
+    captains=("$self_login")
+  fi
+
+  write_config "$port" "$read_only" "${captains[@]}"
+  # A read-only install serves the dashboard without command dispatch, so the
+  # watcher check that surfaces clicked commands is not registered.
+  [ "$read_only" = true ] || write_check
+
+  label=$(home_label)
+  plist_path="$HOME/Library/LaunchAgents/$label.plist"
+  mkdir -p "$HOME/Library/LaunchAgents" "$STATE"
+  render_plist "$label" "$node_path" "$STATE" > "$plist_path"
+  launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+  launchctl bootstrap "gui/$(id -u)" "$plist_path" || err "launchctl bootstrap failed for $plist_path"
+  # RunAtLoad does not reliably start a re-bootstrapped agent on every macOS;
+  # kickstart makes install-serves-now deterministic.
+  launchctl kickstart "gui/$(id -u)/$label" 2>/dev/null || true
+
+  # Tailnet-only HTTPS proxy. tailscale serve without funnel is tailnet-only by
+  # construction; the assertion below still verifies no Funnel exposure exists
+  # for this port and tears the mapping down if one is found.
+  "$(tailscale_bin)" serve --bg --https="$serve_port" "http://127.0.0.1:$port" >/dev/null \
+    || err "tailscale serve refused the mapping; is tailscale up?"
+  if ! assert_no_funnel "$serve_port"; then
+    "$(tailscale_bin)" serve --https="$serve_port" off >/dev/null 2>&1 || true
+    err "funnel exposure detected for port $serve_port; the mapping was removed - this service must stay tailnet-only"
+  fi
+
+  dnsname=$(tailscale_self_dnsname) || err "could not resolve this machine's tailnet name"
+  printf 'installed: launchd agent %s\n' "$label"
+  printf 'captains: %s\n' "${captains[*]}"
+  printf 'dashboard: https://%s:%s/\n' "$dnsname" "$serve_port"
+}
+
+cmd_uninstall() {
+  local serve_port=$DEFAULT_SERVE_PORT label plist_path
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --serve-port) serve_port=${2:?--serve-port needs a value}; shift 2 ;;
+      *) err "unknown uninstall option: $1" ;;
+    esac
+  done
+  [ "$(uname)" = Darwin ] || err "uninstall requires macOS launchd"
+  label=$(home_label)
+  plist_path="$HOME/Library/LaunchAgents/$label.plist"
+  if command -v tailscale >/dev/null 2>&1; then
+    tailscale serve --https="$serve_port" off >/dev/null 2>&1 || true
+  fi
+  launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
+  rm -f "$plist_path"
+  printf 'uninstalled: %s (config and any pending commands were kept)\n' "$label"
+}
+
+cmd_status() {
+  local label pending
+  label=$(home_label)
+  if launchctl print "gui/$(id -u)/$label" >/dev/null 2>&1; then
+    printf 'agent: %s loaded\n' "$label"
+  else
+    printf 'agent: %s not loaded\n' "$label"
+  fi
+  if command -v tailscale >/dev/null 2>&1; then
+    tailscale serve status 2>/dev/null | sed 's/^/serve: /' || true
+  fi
+  pending=$("$SCRIPT_DIR/fm-dash-inbox.sh" pending-count 2>/dev/null || echo unknown)
+  printf 'pending commands: %s\n' "$pending"
+}
+
+case "${1:-}" in
+  -h|--help|'') usage 0 ;;
+  install) shift; cmd_install "$@" ;;
+  uninstall) shift; cmd_uninstall "$@" ;;
+  status) shift; cmd_status ;;
+  print-plist) shift; render_plist "$(home_label)" "$(node_bin)" "$STATE" ;;
+  write-check) shift; write_check ;;
+  *) usage 2 >&2 ;;
+esac
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
new file mode 100755
index 00000000000..71b55af38b8
--- /dev/null
+++ b/bin/fm-dash-serve.mjs
@@ -0,0 +1,1089 @@
+#!/usr/bin/env node
+/**
+ * fm-dash-serve.mjs - persistent tailnet-only capacity dashboard service.
+ *
+ * This file is the single owner of the dashboard service's HTTP surface,
+ * captain-identity enforcement, interactive layer injection, refresh
+ * serialization, and durable command-inbox write mechanics. docs/dashboard-service.md
+ * owns the architecture narrative and setup evidence; bin/fm-dash-install.sh owns
+ * launchd persistence and tailscale serve wiring; bin/fm-dash-inbox.sh owns
+ * firstmate-side consumption of the records this service writes.
+ *
+ * The service never executes fleet commands, never calls firstmate tooling other
+ * than the read-mostly bin/fm-capacity.mjs producer, and never mutates any state
+ * outside state/dash-inbox/ and the producer-owned dashboard file. A clicked
+ * CAP action becomes one durable fm-dash-command.v1 record in state/dash-inbox/;
+ * the running firstmate consumes it through its registered fm-dash watcher check
+ * (bin/fm-dash-inbox.sh claim). Delivery therefore rides the sanctioned wake
+ * path and inherits its cadence rather than any direct control channel.
+ *
+ * Identity fails closed: every route except /healthz requires the
+ * Tailscale-User-Login header injected by tailscale serve to match a login in
+ * config/dash.json. Requests without a matching identity get 403 and cause no
+ * writes. Dispatch accepts only known CAP-NN identifiers that are present in
+ * the currently served dashboard AND in the fixed one-click allowlist below;
+ * free-text commands are structurally impossible and unknown or future action
+ * IDs are refused (route those through captain chat). The server binds
+ * 127.0.0.1 only, so the only remote path in is the tailnet proxy.
+ *
+ * Environment: FM_HOME selects the home (defaults to this checkout);
+ * FM_DASH_CAPACITY_ARGS appends producer fixture args for tests ONLY and must
+ * stay unset in real deployments. Run --help for routes and config schema.
+ */
+
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import process from "node:process";
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(SCRIPT_DIR, "..");
+const FM_HOME = path.resolve(process.env.FM_HOME || process.env.FM_ROOT_OVERRIDE || ROOT);
+const STATE = process.env.FM_STATE_OVERRIDE || path.join(FM_HOME, "state");
+const DATA = path.join(FM_HOME, "data");
+const CONFIG_PATH = path.join(FM_HOME, "config", "dash.json");
+const DASHBOARD = path.join(DATA, "capacity-dashboard.html");
+const INBOX = path.join(STATE, "dash-inbox");
+const CAPACITY = path.join(ROOT, "bin", "fm-capacity.mjs");
+const REFS = path.join(STATE, "dash-refs.json");
+const BACKLOG = path.join(DATA, "backlog.md");
+const IDEAS = path.join(DATA, "ideas", "idea-backlog.md");
+const PITCHES = path.join(DATA, "ideas", "pitches");
+const REFRESH_TIMEOUT_MS = 180000;
+const MAX_BODY_BYTES = 4096;
+
+// One-click eligible action IDs. Every current CAP action only requests
+// lifecycle-safe guidance or work that re-enters normal authority checks
+// (capacity skill section 4); none authorizes a merge, discard, or other
+// destructive or irreversible act. A future action ID absent from this list is
+// refused with guidance to raise it in captain chat, so new actions default to
+// NOT one-click until deliberately reviewed and added here.
+const ONE_CLICK_ACTIONS = new Set([
+  "CAP-01", "CAP-02", "CAP-03", "CAP-04", "CAP-05",
+  "CAP-06", "CAP-07", "CAP-08", "CAP-09", "CAP-10",
+]);
+
+function usage(exitCode = 0) {
+  const out = exitCode === 0 ? process.stdout : process.stderr;
+  out.write(`usage: fm-dash-serve.mjs [--port <n>]
+
+Serve the FM_HOME capacity dashboard on 127.0.0.1 for a tailnet-only
+tailscale serve proxy. Config lives in config/dash.json:
+  {"port": 8847, "captain_logins": ["captain@example.com"],
+   "read_only": false, "auto_refresh_seconds": 900}
+--port overrides the configured port. read_only=true refuses dispatch and
+serves the page without send buttons, for running the service before command
+consumption is wired up. auto_refresh_seconds reruns the producer on that
+interval (and at startup when the dashboard is missing or stale); 0 disables
+auto-render. Routes:
+  GET  /healthz       liveness, no identity required
+  GET  /              dashboard with the interactive layer injected
+  GET  /api/pending   pending command count
+  POST /api/refresh   rerun bin/fm-capacity.mjs server-side (serialized)
+  POST /api/dispatch  {"id":"CAP-NN"} -> durable record in state/dash-inbox/
+All routes except /healthz require a Tailscale-User-Login header matching a
+configured captain login and fail closed otherwise. Dispatch refuses IDs not in
+both the served dashboard and the fixed one-click allowlist.
+`);
+  process.exit(exitCode);
+}
+
+function log(line) {
+  process.stdout.write(`${new Date().toISOString()} ${line}\n`);
+}
+
+function readConfig() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+    const logins = Array.isArray(parsed.captain_logins)
+      ? parsed.captain_logins.filter((login) => typeof login === "string" && login.trim() !== "")
+      : [];
+    const port = Number.isInteger(parsed.port) && parsed.port > 0 && parsed.port < 65536 ? parsed.port : null;
+    const readOnly = parsed.read_only === true;
+    const autoRefreshSeconds = Number.isInteger(parsed.auto_refresh_seconds) && parsed.auto_refresh_seconds >= 0
+      ? parsed.auto_refresh_seconds
+      : 900;
+    return { port, logins, readOnly, autoRefreshSeconds };
+  } catch {
+    return { port: null, logins: [], readOnly: false, autoRefreshSeconds: 900 };
+  }
+}
+
+function unescapeHtml(text) {
+  return text
+    .replaceAll("&quot;", '"')
+    .replaceAll("&#39;", "'")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&amp;", "&");
+}
+
+// The producer-rendered dashboard is the single source of current actions: an
+// ID is dispatchable only while the served page actually recommends it.
+function readDashboard() {
+  let html;
+  try {
+    html = fs.readFileSync(DASHBOARD, "utf8");
+  } catch {
+    return null;
+  }
+  const actions = new Map();
+  for (const match of html.matchAll(/data-copy="([^"]*)"/g)) {
+    const prompt = unescapeHtml(match[1]);
+    const id = (prompt.match(/CAP-\d{2}/) || [])[0];
+    if (id && !actions.has(id)) actions.set(id, prompt);
+  }
+  const generated = (html.match(/generated ([^<]+)</) || [])[1] || "unknown";
+  return { html, actions, generated: generated.trim() };
+}
+
+function pendingRecords() {
+  let names;
+  try {
+    names = fs.readdirSync(INBOX);
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const name of names.sort()) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const record = JSON.parse(fs.readFileSync(path.join(INBOX, name), "utf8"));
+      if (record && typeof record.id === "string") records.push(record);
+    } catch {
+      // An unreadable record still counts as pending for the inbox owner; skip here.
+    }
+  }
+  return records;
+}
+
+function enqueueCommand(record) {
+  fs.mkdirSync(INBOX, { recursive: true, mode: 0o700 });
+  const name = `${Math.floor(Date.now() / 1000)}-${randomBytes(4).toString("hex")}-${record.id}.json`;
+  const tmp = path.join(INBOX, `.tmp-${randomBytes(6).toString("hex")}`);
+  fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, path.join(INBOX, name));
+  return name;
+}
+
+// --- read-only detail assembly -------------------------------------------
+// Everything below only READS records the home already keeps: the producer's
+// refs sidecar, the backlog, task briefs, task metadata, status tails, and
+// scout reports. Detail is served only to the authenticated captain.
+
+function readRefs() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(REFS, "utf8"));
+    if (parsed.schema !== "fm-capacity-refs.v1" || typeof parsed.refs !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function readText(file, maxBytes = 65536) {
+  try {
+    const buffer = fs.readFileSync(file);
+    return buffer.subarray(0, maxBytes).toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+// Parse the tasks-axi markdown backlog: "## Section" headers and
+// "- [ ] id - Title (annotation) ..." items with indented body lines.
+function parseBacklog() {
+  const text = readText(BACKLOG, 262144);
+  if (!text) return [];
+  const items = [];
+  let section = "";
+  let current = null;
+  for (const line of text.split("\n")) {
+    const heading = line.match(/^##\s+(.+)$/);
+    if (heading) { section = heading[1].trim(); current = null; continue; }
+    const item = line.match(/^- \[([ xX])\] (\S+) - (.*)$/);
+    if (item) {
+      current = { id: item[2], done: item[1] !== " ", title: item[3].trim(), section, body: [] };
+      items.push(current);
+      continue;
+    }
+    if (current && /^\s+\S/.test(line)) current.body.push(line.trim());
+    else if (current && line.trim() === "") current.body.push("");
+    else current = null;
+  }
+  return items;
+}
+
+function briefSections(id) {
+  const text = readText(path.join(DATA, id, "brief.md"), 131072);
+  if (!text) return { description: null, testPlan: null, raw: null };
+  const taskMatch = text.match(/^# Task\s*\n([\s\S]*?)(?=^# |\n# |$(?![\s\S]))/m);
+  const description = taskMatch ? taskMatch[1].trim().slice(0, 3000) : null;
+  const planMatch = text.match(/^(?:#+\s*)?(?:acceptance criteria|test plan|definition of done)[:\s]*\n([\s\S]*?)(?=^#+ |$(?![\s\S]))/im);
+  const testPlan = planMatch ? planMatch[1].trim().slice(0, 1500) : null;
+  return { description, testPlan, raw: text };
+}
+
+function readMeta(id) {
+  const text = readText(path.join(STATE, `${id}.meta`), 8192);
+  const meta = {};
+  if (!text) return meta;
+  for (const line of text.split("\n")) {
+    const pair = line.match(/^([a-z_]+)=(.*)$/);
+    if (pair) meta[pair[1]] = pair[2];
+  }
+  return meta;
+}
+
+function statusTail(id, lines = 6) {
+  const text = readText(path.join(STATE, `${id}.status`), 65536);
+  if (!text) return [];
+  return text.trim().split("\n").filter(Boolean).slice(-lines);
+}
+
+function previewLinks(...texts) {
+  const links = new Set();
+  for (const text of texts) {
+    if (!text) continue;
+    for (const match of text.matchAll(/https:\/\/[^\s"'`<>)\]]+\.ts\.net[^\s"'`<>)\]]*/g)) links.add(match[0]);
+  }
+  return [...links];
+}
+
+// Bulleted or numbered body lines of a captain-hold item are its options; each
+// option's impact is the text of that line plus any continuation up to the next
+// option marker.
+function decisionOptions(body) {
+  const options = [];
+  let current = null;
+  for (const line of body) {
+    const marker = line.match(/^(?:[-*]|\d+[.)])\s+(.*)$/);
+    if (marker) { current = { text: marker[1].trim(), impact: [] }; options.push(current); continue; }
+    if (current && line !== "") current.impact.push(line);
+  }
+  return options.map((option) => ({ text: option.text, impact: option.impact.join(" ").slice(0, 800) }));
+}
+
+function refDisplayMap(refsFile) {
+  const display = {};
+  for (const [ref, entry] of Object.entries(refsFile.refs)) {
+    if (entry.kind === "project") display[ref] = { t: "project", label: entry.value };
+    else if (entry.kind === "home") display[ref] = { t: "home", label: entry.value };
+    else if (entry.kind === "item") {
+      const separator = entry.value.indexOf("/");
+      const owner = entry.value.slice(0, separator);
+      const id = entry.value.slice(separator + 1);
+      display[ref] = owner === "decision"
+        ? { t: "decision", label: id }
+        : { t: "work", label: id, owner };
+    }
+  }
+  return display;
+}
+
+function assembleDetail(ref) {
+  const refsFile = readRefs();
+  const entry = refsFile?.refs?.[ref];
+  if (!entry || entry.kind !== "item") return null;
+  const separator = entry.value.indexOf("/");
+  const owner = entry.value.slice(0, separator);
+  const id = entry.value.slice(separator + 1);
+  const backlogItem = parseBacklog().find((item) => item.id === id) || null;
+
+  if (owner === "decision") {
+    const body = backlogItem ? backlogItem.body : [];
+    return {
+      type: "decision",
+      ref,
+      id,
+      title: backlogItem ? backlogItem.title : id,
+      description: body.filter((line) => !/^(?:[-*]|\d+[.)])\s+/.test(line)).join("\n").trim().slice(0, 2000) || null,
+      options: decisionOptions(body),
+      recent: statusTail(id),
+      note: backlogItem ? null : "No structured record was found for this decision key; answer it in captain chat.",
+    };
+  }
+  if (owner !== "main") {
+    return {
+      type: "work",
+      ref,
+      id,
+      owner,
+      title: backlogItem ? backlogItem.title : id,
+      note: "This work lives with a domain supervisor; its instructions and records are in that home.",
+    };
+  }
+  const brief = briefSections(id);
+  const meta = readMeta(id);
+  const report = readText(path.join(DATA, id, "report.md"), 8192);
+  const recent = statusTail(id);
+  const backlogBody = backlogItem ? backlogItem.body.join("\n") : "";
+  const testPlan = brief.testPlan
+    || (backlogBody.match(/acceptance criteria[:\s]*([\s\S]{0,600})/i) || [])[1]?.trim()
+    || null;
+  return {
+    type: "work",
+    ref,
+    id,
+    owner: "main",
+    title: backlogItem ? backlogItem.title : id,
+    description: brief.description || backlogBody.slice(0, 2000) || null,
+    test_plan: testPlan,
+    pr: meta.pr || null,
+    project: meta.project ? path.basename(meta.project) : null,
+    delivery_mode: meta.mode || null,
+    previews: previewLinks(brief.raw, report, recent.join("\n")),
+    report_excerpt: report ? report.trim().slice(0, 1200) : null,
+    recent,
+  };
+}
+
+// Parse data/ideas/idea-backlog.md generously: any heading or list line
+// carrying an IDEA-XX token starts an idea; following lines up to the next
+// idea are its concept summary.
+function parseIdeas() {
+  const text = readText(IDEAS, 262144);
+  if (!text) return [];
+  const ideas = [];
+  let current = null;
+  for (const line of text.split("\n")) {
+    const marker = line.match(/^\s*(?:#{1,4}\s*|[-*]\s+|\d+[.)]\s+)?.*?\b(IDEA-\d+)\b[:\s-]*(.*)$/);
+    if (marker && !ideas.some((idea) => idea.id === marker[1])) {
+      current = { id: marker[1], title: marker[2].trim() || marker[1], summary: [] };
+      ideas.push(current);
+      continue;
+    }
+    if (current && !/\bIDEA-\d+\b/.test(line)) current.summary.push(line);
+  }
+  return ideas.map((idea) => ({ id: idea.id, title: idea.title, summary: idea.summary.join("\n").trim().slice(0, 3000) }));
+}
+
+function ideaDetail(id) {
+  const idea = parseIdeas().find((entry) => entry.id === id);
+  if (!idea) return null;
+  const pitch = /^IDEA-\d+$/.test(id) ? readText(path.join(PITCHES, `${id}.md`), 131072) : null;
+  return {
+    type: "idea",
+    id: idea.id,
+    title: idea.title,
+    pitch: pitch ? pitch.trim().slice(0, 12000) : null,
+    description: pitch ? null : idea.summary || null,
+  };
+}
+
+let refreshing = null;
+function runRefresh() {
+  if (refreshing) return refreshing;
+  const extraArgs = (process.env.FM_DASH_CAPACITY_ARGS || "").split(" ").filter(Boolean);
+  refreshing = new Promise((resolve) => {
+    const child = spawn(process.execPath, [CAPACITY, "--refs", REFS, ...extraArgs], {
+      cwd: ROOT,
+      env: { ...process.env, FM_HOME },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    const timer = setTimeout(() => child.kill("SIGKILL"), REFRESH_TIMEOUT_MS);
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      refreshing = null;
+      if (code === 0) resolve({ ok: true });
+      else resolve({ ok: false, error: stderr.trim().slice(0, 500) || `capacity producer exited ${code}` });
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      refreshing = null;
+      resolve({ ok: false, error: error.message });
+    });
+  });
+  return refreshing;
+}
+
+function sendJson(res, status, payload) {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8", "content-length": Buffer.byteLength(body) });
+  res.end(body);
+}
+
+function sendHtml(res, status, html) {
+  res.writeHead(status, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+  res.end(html);
+}
+
+function requesterLogin(req) {
+  const value = req.headers["tailscale-user-login"];
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function authorized(req, config) {
+  const login = requesterLogin(req);
+  return login !== "" && config.logins.includes(login);
+}
+
+// Injected interactive layer. It only talks to this service's own API; the
+// underlying producer file stays untouched on disk and keeps working offline.
+// When the producer's refs sidecar is present the layer also de-anonymizes the
+// page for the authenticated captain: opaque item/project/home references get
+// their real names, and work items and decisions become clickable detail views.
+function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
+  const config = JSON.stringify({
+    dispatchable,
+    pending,
+    generated,
+    readOnly: readOnly === true,
+    refs: extras?.refs || {},
+    ideas: extras?.ideas || [],
+  });
+  return `<style>
+  .fmdash-bar{display:flex;justify-content:space-between;align-items:center;gap:.6rem 1.5rem;flex-wrap:wrap;padding:.6rem clamp(1rem,6vw,5rem);border-bottom:1px solid var(--line);background:var(--bg)}
+  .fmdash-bar .fmdash-live{font-weight:800;font-size:.72rem;letter-spacing:.16em;text-transform:uppercase;color:var(--muted)}
+  .fmdash-bar .fmdash-live::before{content:"";display:inline-block;width:.55rem;height:.55rem;border-radius:50%;background:var(--good);margin-right:.5rem;vertical-align:baseline}
+  .fmdash-bar button{border:1px solid var(--ink);background:var(--ink);color:var(--bg);font-weight:700;padding:.45rem .9rem;cursor:pointer;font-size:.8rem}
+  .fmdash-bar button[disabled]{opacity:.55;cursor:progress}
+  .fmdash-pending{font-size:.76rem;color:var(--ink2)}
+  .fmdash-send{border:1px solid var(--ink);background:transparent;color:var(--ink);font-weight:700;padding:.5rem .9rem;cursor:pointer;font-size:.82rem;grid-column:2}
+  .fmdash-send[disabled]{opacity:.55;cursor:default}
+  .fmdash-chat{color:var(--muted);font-size:.76rem;align-self:center}
+  .fmdash-click{cursor:pointer;text-decoration:underline;text-decoration-color:var(--muted);text-underline-offset:.22em}
+  .fmdash-click:hover,.fmdash-click:focus-visible{color:var(--blue);text-decoration-color:var(--blue)}
+  .fmdash-overlay{position:fixed;inset:0;background:color-mix(in srgb,var(--bg) 55%,transparent);backdrop-filter:blur(2px);display:grid;place-items:start center;overflow-y:auto;padding:clamp(1rem,6vh,4rem) 1rem;z-index:50}
+  .fmdash-panel{background:var(--bg);border:1px solid var(--line);border-top:.55rem solid var(--sev,var(--blue));max-width:46rem;width:100%;padding:clamp(1.25rem,3vw,2.25rem)}
+  .fmdash-panel .fmdash-kicker{display:flex;justify-content:space-between;gap:1rem;font-weight:800;font-size:.72rem;letter-spacing:.16em;text-transform:uppercase;color:var(--muted)}
+  .fmdash-panel h2{font-size:clamp(1.4rem,3vw,2rem);font-weight:800;letter-spacing:-.02em;margin-top:.5rem;overflow-wrap:anywhere}
+  .fmdash-panel h3{font-size:.74rem;font-weight:800;letter-spacing:.14em;text-transform:uppercase;color:var(--muted);margin-top:1.4rem;border-bottom:1px solid var(--hair);padding-bottom:.35rem}
+  .fmdash-panel p,.fmdash-panel pre,.fmdash-panel li{color:var(--ink2);font-size:.92rem;margin-top:.5rem}
+  .fmdash-panel pre{white-space:pre-wrap;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.8rem;border:1px solid var(--hair);padding:.6rem .8rem;overflow-x:auto}
+  .fmdash-panel a{overflow-wrap:anywhere}
+  .fmdash-option{border-bottom:1px solid var(--hair);padding:.7rem 0;display:grid;grid-template-columns:minmax(0,1fr) auto;gap:.6rem;align-items:start}
+  .fmdash-option strong{color:var(--ink);font-size:.95rem}
+  .fmdash-option small{display:block;color:var(--muted);margin-top:.25rem}
+  .fmdash-close{border:1px solid var(--ink);background:transparent;color:var(--ink);font-weight:700;padding:.4rem .8rem;cursor:pointer;font-size:.78rem}
+  </style>
+  <script>
+  (() => {
+    const cfg = ${config};
+    const bar = document.createElement("div");
+    bar.className = "fmdash-bar";
+    bar.innerHTML = '<span class="fmdash-live">Live over your tailnet</span>'
+      + '<span class="fmdash-pending"></span>'
+      + '<button type="button" class="fmdash-refresh">Refresh capacity</button>';
+    document.body.prepend(bar);
+    const pendingEl = bar.querySelector(".fmdash-pending");
+    const showPending = (n) => {
+      pendingEl.textContent = cfg.readOnly
+        ? ""
+        : (n > 0
+          ? n + " command" + (n === 1 ? "" : "s") + " queued for firstmate"
+          : "No commands queued");
+    };
+    showPending(cfg.pending);
+    const refreshButton = bar.querySelector(".fmdash-refresh");
+    refreshButton.addEventListener("click", async () => {
+      refreshButton.disabled = true;
+      refreshButton.textContent = "Refreshing…";
+      try {
+        const res = await fetch("/api/refresh", { method: "POST" });
+        const out = await res.json();
+        if (out.status === "refreshed") { location.reload(); return; }
+        refreshButton.textContent = out.status === "busy" ? "Already refreshing…" : "Refresh failed";
+      } catch { refreshButton.textContent = "Refresh failed"; }
+      setTimeout(() => { refreshButton.disabled = false; refreshButton.textContent = "Refresh capacity"; }, 4000);
+    });
+    // De-anonymize known references for the authenticated captain and open
+    // rich detail views on click. The server refuses detail and approval
+    // requests it cannot validate, so this layer is presentation only.
+    const clickableTypes = { work: 1, decision: 1 };
+    const refTokens = Object.keys(cfg.refs);
+    if (refTokens.length) {
+      const tokenPattern = /\\b(?:item|project|home)-\\d{2,}\\b/g;
+      document.querySelectorAll(".item-id").forEach((chip) => {
+        const token = (chip.textContent || "").trim();
+        const entry = cfg.refs[token];
+        if (!entry) return;
+        chip.textContent = entry.label;
+        if (clickableTypes[entry.t]) {
+          chip.classList.add("fmdash-click");
+          chip.setAttribute("role", "button");
+          chip.setAttribute("tabindex", "0");
+          chip.setAttribute("aria-label", "Open detail for " + entry.label);
+          const open = () => openDetail(token, entry);
+          chip.addEventListener("click", (event) => { event.stopPropagation(); open(); });
+          chip.addEventListener("keydown", (event) => { if (event.key === "Enter" || event.key === " ") { event.preventDefault(); open(); } });
+        }
+      });
+      const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+      const textNodes = [];
+      while (walker.nextNode()) textNodes.push(walker.currentNode);
+      textNodes.forEach((node) => {
+        const value = node.nodeValue;
+        if (!value || !tokenPattern.test(value)) { tokenPattern.lastIndex = 0; return; }
+        tokenPattern.lastIndex = 0;
+        node.nodeValue = value.replace(tokenPattern, (token) => (cfg.refs[token] ? cfg.refs[token].label : token));
+      });
+    }
+    function section(title, node) {
+      if (!node) return [];
+      const heading = document.createElement("h3");
+      heading.textContent = title;
+      return [heading, node];
+    }
+    function textBlock(tag, text) {
+      if (!text) return null;
+      const el = document.createElement(tag);
+      el.textContent = text;
+      return el;
+    }
+    function linkBlock(urls) {
+      if (!urls || !urls.length) return null;
+      const list = document.createElement("ul");
+      urls.forEach((url) => {
+        const li = document.createElement("li");
+        const a = document.createElement("a");
+        a.href = url;
+        a.textContent = url;
+        li.appendChild(a);
+        list.appendChild(li);
+      });
+      return list;
+    }
+    async function approveDecision(ref, index, button, key) {
+      button.disabled = true;
+      button.textContent = "Sending…";
+      try {
+        const res = await fetch("/api/dispatch", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ ref, option: index }),
+        });
+        const out = await res.json();
+        if (out.status === "queued" || out.status === "already-queued") {
+          button.textContent = "Approved · queued";
+          showPending(out.pending);
+          return;
+        }
+        button.textContent = "Refused";
+        button.disabled = false;
+      } catch { button.textContent = "Failed"; button.disabled = false; }
+    }
+    async function openDetail(ref, entry) {
+      const overlay = document.createElement("div");
+      overlay.className = "fmdash-overlay";
+      const panel = document.createElement("div");
+      panel.className = "fmdash-panel";
+      panel.setAttribute("role", "dialog");
+      panel.setAttribute("aria-modal", "true");
+      panel.setAttribute("aria-label", entry.label + " detail");
+      overlay.appendChild(panel);
+      const close = () => { overlay.remove(); document.removeEventListener("keydown", onKey); };
+      const onKey = (event) => { if (event.key === "Escape") close(); };
+      overlay.addEventListener("click", (event) => { if (event.target === overlay) close(); });
+      document.addEventListener("keydown", onKey);
+      const kicker = document.createElement("div");
+      kicker.className = "fmdash-kicker";
+      kicker.textContent = entry.t === "decision" ? "Open decision" : "Work item";
+      const closeButton = document.createElement("button");
+      closeButton.type = "button";
+      closeButton.className = "fmdash-close";
+      closeButton.textContent = "Close";
+      closeButton.addEventListener("click", close);
+      kicker.appendChild(closeButton);
+      panel.appendChild(kicker);
+      panel.appendChild(textBlock("h2", entry.label));
+      panel.appendChild(textBlock("p", "Loading detail…"));
+      document.body.appendChild(overlay);
+      closeButton.focus();
+      let detail = null;
+      try {
+        const res = await fetch("/api/detail?ref=" + encodeURIComponent(ref));
+        if (res.ok) detail = await res.json();
+      } catch { /* handled below */ }
+      panel.replaceChildren(kicker);
+      if (!detail) {
+        panel.appendChild(textBlock("h2", entry.label));
+        panel.appendChild(textBlock("p", "No further recorded detail is available for this entry."));
+        return;
+      }
+      panel.appendChild(textBlock("h2", detail.title || detail.id));
+      if (detail.title && detail.title !== detail.id) panel.appendChild(textBlock("p", detail.id));
+      if (detail.note) panel.appendChild(textBlock("p", detail.note));
+      section("What it is", textBlock("pre", detail.description)).forEach((el) => panel.appendChild(el));
+      section("Test plan", textBlock("pre", detail.test_plan)).forEach((el) => panel.appendChild(el));
+      if (detail.pr) section("Pull request", linkBlock([detail.pr])).forEach((el) => panel.appendChild(el));
+      section("Tailnet previews", linkBlock(detail.previews)).forEach((el) => panel.appendChild(el));
+      const facts = [detail.project ? "Project: " + detail.project : null, detail.delivery_mode ? "Delivery: " + detail.delivery_mode : null].filter(Boolean).join(" · ");
+      if (facts) panel.appendChild(textBlock("p", facts));
+      section("Report excerpt", textBlock("pre", detail.report_excerpt)).forEach((el) => panel.appendChild(el));
+      if (detail.options && detail.options.length) {
+        const heading = document.createElement("h3");
+        heading.textContent = "Options";
+        panel.appendChild(heading);
+        detail.options.forEach((option, index) => {
+          const row = document.createElement("div");
+          row.className = "fmdash-option";
+          const body = document.createElement("div");
+          const label = document.createElement("strong");
+          label.textContent = option.text;
+          body.appendChild(label);
+          if (option.impact) {
+            const impact = document.createElement("small");
+            impact.textContent = option.impact;
+            body.appendChild(impact);
+          }
+          row.appendChild(body);
+          if (!cfg.readOnly) {
+            const approve = document.createElement("button");
+            approve.type = "button";
+            approve.className = "fmdash-send";
+            approve.textContent = "Approve";
+            approve.setAttribute("aria-label", "Approve: " + option.text);
+            approve.addEventListener("click", () => approveDecision(ref, index, approve, detail.id));
+            row.appendChild(approve);
+          }
+          panel.appendChild(row);
+        });
+        if (!cfg.readOnly) panel.appendChild(textBlock("p", "An approval here is your routine decision only; anything destructive or irreversible still gets re-confirmed with you in chat."));
+      } else if (detail.type === "decision") {
+        panel.appendChild(textBlock("p", "This decision has no structured options on record; answer it in chat."));
+      }
+      section("Recent activity", linkBlock(null) || textBlock("pre", (detail.recent || []).join("\\n"))).forEach((el) => panel.appendChild(el));
+    }
+    // Ideas: rendered from data/ideas/idea-backlog.md; each idea opens its
+    // pitch with approve / deny / add-suggestions controls that only enqueue
+    // captain messages for firstmate.
+    if (cfg.ideas.length) {
+      const ideasSection = document.createElement("section");
+      ideasSection.className = "band band-quiet";
+      ideasSection.setAttribute("aria-label", "Ideas");
+      const wrap = document.createElement("div");
+      wrap.className = "wrap";
+      const heading = document.createElement("h2");
+      heading.className = "qhead";
+      heading.textContent = "Ideas · awaiting your verdict";
+      wrap.appendChild(heading);
+      const list = document.createElement("ul");
+      list.className = "mlist";
+      cfg.ideas.forEach((idea) => {
+        const row = document.createElement("li");
+        row.className = "mrow";
+        const chip = document.createElement("span");
+        chip.className = "item-id fmdash-click";
+        chip.textContent = idea.id;
+        chip.setAttribute("role", "button");
+        chip.setAttribute("tabindex", "0");
+        chip.setAttribute("aria-label", "Open pitch for " + idea.id);
+        const title = document.createElement("span");
+        title.className = "mreason";
+        title.textContent = idea.title;
+        const open = () => openIdea(idea);
+        chip.addEventListener("click", (event) => { event.stopPropagation(); open(); });
+        chip.addEventListener("keydown", (event) => { if (event.key === "Enter" || event.key === " ") { event.preventDefault(); open(); } });
+        row.addEventListener("click", open);
+        row.style.cursor = "pointer";
+        row.appendChild(chip);
+        row.appendChild(title);
+        list.appendChild(row);
+      });
+      wrap.appendChild(list);
+      ideasSection.appendChild(wrap);
+      const footer = document.querySelector("footer");
+      const main = document.querySelector("main");
+      if (main) main.appendChild(ideasSection);
+      else if (footer) footer.before(ideasSection);
+    }
+    async function sendIdeaVerdict(id, verdict, suggestion, button) {
+      button.disabled = true;
+      const original = button.textContent;
+      button.textContent = "Sending…";
+      try {
+        const res = await fetch("/api/dispatch", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ idea: id, verdict, suggestion }),
+        });
+        const out = await res.json();
+        if (out.status === "queued" || out.status === "already-queued") {
+          button.textContent = verdict === "suggest" ? "Suggestions sent" : (verdict === "approve" ? "Approved · queued" : "Denied · queued");
+          showPending(out.pending);
+          return true;
+        }
+        button.textContent = "Refused";
+        button.disabled = false;
+      } catch { button.textContent = original; button.disabled = false; }
+      return false;
+    }
+    async function openIdea(idea) {
+      const overlay = document.createElement("div");
+      overlay.className = "fmdash-overlay";
+      const panel = document.createElement("div");
+      panel.className = "fmdash-panel";
+      panel.setAttribute("role", "dialog");
+      panel.setAttribute("aria-modal", "true");
+      panel.setAttribute("aria-label", idea.id + " pitch");
+      overlay.appendChild(panel);
+      const close = () => { overlay.remove(); document.removeEventListener("keydown", onKey); };
+      const onKey = (event) => { if (event.key === "Escape") close(); };
+      overlay.addEventListener("click", (event) => { if (event.target === overlay) close(); });
+      document.addEventListener("keydown", onKey);
+      const kicker = document.createElement("div");
+      kicker.className = "fmdash-kicker";
+      kicker.textContent = "Idea pitch";
+      const closeButton = document.createElement("button");
+      closeButton.type = "button";
+      closeButton.className = "fmdash-close";
+      closeButton.textContent = "Close";
+      closeButton.addEventListener("click", close);
+      kicker.appendChild(closeButton);
+      panel.appendChild(kicker);
+      panel.appendChild(textBlock("h2", idea.id + " — " + idea.title));
+      panel.appendChild(textBlock("p", "Loading pitch…"));
+      document.body.appendChild(overlay);
+      closeButton.focus();
+      let detail = null;
+      try {
+        const res = await fetch("/api/detail?idea=" + encodeURIComponent(idea.id));
+        if (res.ok) detail = await res.json();
+      } catch { /* handled below */ }
+      panel.replaceChildren(kicker);
+      panel.appendChild(textBlock("h2", idea.id + " — " + idea.title));
+      const pitchText = detail && (detail.pitch || detail.description);
+      panel.appendChild(textBlock("pre", pitchText || "No pitch or concept summary is on file for this idea."));
+      if (cfg.readOnly) return;
+      const controls = document.createElement("div");
+      controls.className = "fmdash-option";
+      const buttons = document.createElement("div");
+      const approve = document.createElement("button");
+      approve.type = "button";
+      approve.className = "fmdash-send";
+      approve.textContent = "Approve";
+      approve.addEventListener("click", () => sendIdeaVerdict(idea.id, "approve", null, approve));
+      const deny = document.createElement("button");
+      deny.type = "button";
+      deny.className = "fmdash-send";
+      deny.textContent = "Deny";
+      deny.style.marginLeft = ".6rem";
+      deny.addEventListener("click", () => sendIdeaVerdict(idea.id, "deny", null, deny));
+      const suggest = document.createElement("button");
+      suggest.type = "button";
+      suggest.className = "fmdash-send";
+      suggest.textContent = "Add suggestions";
+      suggest.style.marginLeft = ".6rem";
+      buttons.appendChild(approve);
+      buttons.appendChild(deny);
+      buttons.appendChild(suggest);
+      controls.appendChild(buttons);
+      panel.appendChild(controls);
+      panel.appendChild(textBlock("p", "Approving asks firstmate to create the work item(s) through the normal backlog lifecycle; nothing runs from this page."));
+      suggest.addEventListener("click", () => {
+        if (panel.querySelector("textarea")) return;
+        const box = document.createElement("textarea");
+        box.rows = 4;
+        box.style.width = "100%";
+        box.style.marginTop = ".6rem";
+        box.setAttribute("aria-label", "Suggestions for " + idea.id);
+        box.placeholder = "Your suggestions for this idea…";
+        const send = document.createElement("button");
+        send.type = "button";
+        send.className = "fmdash-send";
+        send.style.marginTop = ".5rem";
+        send.textContent = "Send suggestions";
+        send.addEventListener("click", async () => {
+          if (!box.value.trim()) return;
+          const ok = await sendIdeaVerdict(idea.id, "suggest", box.value.trim(), send);
+          if (ok) box.disabled = true;
+        });
+        panel.appendChild(box);
+        panel.appendChild(send);
+        box.focus();
+      });
+    }
+    if (cfg.readOnly) return;
+    document.querySelectorAll("button[data-copy]").forEach((copyButton) => {
+      const id = ((copyButton.dataset.copy || "").match(/CAP-\\d{2}/) || [])[0];
+      if (!id) return;
+      if (!cfg.dispatchable.includes(id)) {
+        const note = document.createElement("span");
+        note.className = "fmdash-chat";
+        note.textContent = "Raise in captain chat";
+        copyButton.after(note);
+        return;
+      }
+      const send = document.createElement("button");
+      send.type = "button";
+      send.className = "fmdash-send";
+      send.textContent = "Approve & send";
+      send.setAttribute("aria-label", "Approve " + id + " and queue it for firstmate");
+      send.addEventListener("click", async () => {
+        send.disabled = true;
+        send.textContent = "Sending…";
+        try {
+          const res = await fetch("/api/dispatch", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ id }),
+          });
+          const out = await res.json();
+          if (out.status === "queued" || out.status === "already-queued") {
+            send.textContent = "Approved · queued";
+            showPending(out.pending);
+            return;
+          }
+          send.textContent = "Refused";
+          send.disabled = false;
+        } catch { send.textContent = "Failed"; send.disabled = false; }
+      });
+      copyButton.after(send);
+    });
+  })();
+  </script>`;
+}
+
+function setupPage(message) {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="dark light"><title>Firstmate capacity dashboard</title>
+<style>:root{color-scheme:dark;--bg:#0d0d0d;--ink:#fff;--muted:#898781}@media(prefers-color-scheme: light){:root{color-scheme:light;--bg:#f9f9f7;--ink:#0b0b0b;--muted:#66645f}}
+body{margin:0;background:var(--bg);color:var(--ink);font-family:system-ui,-apple-system,"Segoe UI",sans-serif;display:grid;min-height:100vh;place-items:center;padding:2rem}
+p{color:var(--muted);max-width:45ch;line-height:1.5}</style></head>
+<body><div><h1>Capacity dashboard</h1><p>${message}</p></div></body></html>`;
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) { reject(new Error("body too large")); req.destroy(); return; }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+async function handle(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  if (req.method === "GET" && url.pathname === "/healthz") {
+    sendJson(res, 200, { status: "ok" });
+    return;
+  }
+  const config = readConfig();
+  if (config.logins.length === 0) {
+    sendHtml(res, 403, setupPage("No captain login is configured yet. Run bin/fm-dash-install.sh on the firstmate machine to finish setup."));
+    return;
+  }
+  if (!authorized(req, config)) {
+    log(`refused ${req.method} ${url.pathname} identity=${JSON.stringify(requesterLogin(req)) || "none"}`);
+    sendJson(res, 403, { status: "forbidden", error: "tailnet identity is not an authorized captain login" });
+    return;
+  }
+  if (req.method === "GET" && url.pathname === "/") {
+    const dashboard = readDashboard();
+    if (!dashboard) {
+      sendHtml(res, 200, setupPage("No dashboard has been generated yet. Use the Refresh capacity action once firstmate has generated a first snapshot, or run /capacity from firstmate.")
+        .replace("</body>", `${interactiveLayer([], pendingRecords().length, "never", config.readOnly)}</body>`));
+      return;
+    }
+    const dispatchable = config.readOnly ? [] : [...dashboard.actions.keys()].filter((id) => ONE_CLICK_ACTIONS.has(id));
+    const refsFile = readRefs();
+    const layer = interactiveLayer(dispatchable, pendingRecords().length, dashboard.generated, config.readOnly, {
+      refs: refsFile ? refDisplayMap(refsFile) : {},
+      ideas: parseIdeas().map((idea) => ({ id: idea.id, title: idea.title })),
+    });
+    sendHtml(res, 200, dashboard.html.replace("</body>", `${layer}</body>`));
+    return;
+  }
+  if (req.method === "GET" && url.pathname === "/api/detail") {
+    const ref = url.searchParams.get("ref");
+    const idea = url.searchParams.get("idea");
+    let detail = null;
+    if (idea && /^IDEA-\d+$/.test(idea)) detail = ideaDetail(idea);
+    else if (ref && /^(?:item|project|home)-\d{2,}$/.test(ref)) detail = assembleDetail(ref);
+    if (!detail) {
+      sendJson(res, 404, { status: "not-found" });
+      return;
+    }
+    sendJson(res, 200, detail);
+    return;
+  }
+  if (req.method === "GET" && url.pathname === "/api/pending") {
+    sendJson(res, 200, { status: "ok", pending: pendingRecords().length });
+    return;
+  }
+  if (req.method === "POST" && url.pathname === "/api/refresh") {
+    if (refreshing) {
+      sendJson(res, 409, { status: "busy" });
+      return;
+    }
+    log(`refresh requested by ${requesterLogin(req)}`);
+    const result = await runRefresh();
+    if (result.ok) sendJson(res, 200, { status: "refreshed" });
+    else sendJson(res, 502, { status: "failed", error: result.error });
+    return;
+  }
+  if (req.method === "POST" && url.pathname === "/api/dispatch") {
+    if (config.readOnly) {
+      sendJson(res, 403, { status: "refused", error: "this dashboard is read-only; command dispatch is not enabled yet" });
+      return;
+    }
+    let body;
+    try {
+      body = JSON.parse(await readBody(req) || "{}");
+    } catch {
+      sendJson(res, 400, { status: "refused", error: "invalid request body" });
+      return;
+    }
+
+    // Decision approval: the chosen option must be one the server itself just
+    // read from the decision's structured record.
+    if (typeof body.ref === "string") {
+      const detail = /^(?:item|project|home)-\d{2,}$/.test(body.ref) ? assembleDetail(body.ref) : null;
+      if (!detail || detail.type !== "decision") {
+        sendJson(res, 400, { status: "refused", error: "approval accepts a currently listed decision only" });
+        return;
+      }
+      const option = detail.options?.[body.option];
+      if (!option) {
+        sendJson(res, 400, { status: "refused", error: "the chosen option is not on the decision's record" });
+        return;
+      }
+      const pending = pendingRecords();
+      if (pending.some((record) => record.kind === "decision" && record.decision_key === detail.id)) {
+        sendJson(res, 200, { status: "already-queued", pending: pending.length });
+        return;
+      }
+      const record = {
+        schema: "fm-dash-command.v1",
+        kind: "decision",
+        id: body.ref,
+        decision_key: detail.id,
+        option_text: option.text,
+        requested_by: requesterLogin(req),
+        requested_at: new Date().toISOString(),
+        prompt: `Captain approved decision ${detail.id}: choose "${option.text}". Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`,
+      };
+      const name = enqueueCommand(record);
+      log(`queued decision ${detail.id} as ${name} for ${record.requested_by}`);
+      sendJson(res, 200, { status: "queued", pending: pending.length + 1 });
+      return;
+    }
+
+    // Idea verdicts: approve, deny, or captain suggestions for a listed idea.
+    // The suggestion text is captain-authored data for firstmate, never a
+    // command the service interprets or executes.
+    if (typeof body.idea === "string") {
+      const verdict = body.verdict;
+      if (!/^IDEA-\d+$/.test(body.idea) || !["approve", "deny", "suggest"].includes(verdict)) {
+        sendJson(res, 400, { status: "refused", error: "idea dispatch needs a listed idea and an approve, deny, or suggest verdict" });
+        return;
+      }
+      const idea = parseIdeas().find((entry) => entry.id === body.idea);
+      if (!idea) {
+        sendJson(res, 404, { status: "refused", error: `${body.idea} is not in the idea backlog` });
+        return;
+      }
+      const suggestion = verdict === "suggest" ? String(body.suggestion || "").trim().slice(0, 2000) : null;
+      if (verdict === "suggest" && !suggestion) {
+        sendJson(res, 400, { status: "refused", error: "suggestions need text" });
+        return;
+      }
+      const pending = pendingRecords();
+      if (verdict !== "suggest" && pending.some((record) => record.kind === "idea" && record.idea === idea.id && record.verdict === verdict)) {
+        sendJson(res, 200, { status: "already-queued", pending: pending.length });
+        return;
+      }
+      const verbs = { approve: "approved", deny: "denied", suggest: "added suggestions to" };
+      const record = {
+        schema: "fm-dash-command.v1",
+        kind: "idea",
+        id: idea.id,
+        idea: idea.id,
+        verdict,
+        suggestion,
+        requested_by: requesterLogin(req),
+        requested_at: new Date().toISOString(),
+        prompt: `Captain ${verbs[verdict]} idea ${idea.id} (${idea.title}).${suggestion ? ` Captain suggestion text: ${suggestion}` : ""}${verdict === "approve" ? " Create the follow-up work item(s) through the normal backlog lifecycle." : ""}`,
+      };
+      const name = enqueueCommand(record);
+      log(`queued idea ${idea.id} ${verdict} as ${name} for ${record.requested_by}`);
+      sendJson(res, 200, { status: "queued", pending: pending.length + 1 });
+      return;
+    }
+
+    const id = body.id;
+    if (typeof id !== "string" || !/^CAP-\d{2}$/.test(id)) {
+      sendJson(res, 400, { status: "refused", error: "dispatch accepts a known CAP-NN action id only" });
+      return;
+    }
+    if (!ONE_CLICK_ACTIONS.has(id)) {
+      sendJson(res, 403, { status: "refused", error: `${id} is not one-click eligible; raise it in captain chat` });
+      return;
+    }
+    const dashboard = readDashboard();
+    const prompt = dashboard?.actions.get(id);
+    if (!prompt) {
+      sendJson(res, 409, { status: "refused", error: `${id} is not recommended by the current dashboard; refresh first` });
+      return;
+    }
+    const pending = pendingRecords();
+    if (pending.some((record) => record.id === id)) {
+      sendJson(res, 200, { status: "already-queued", pending: pending.length });
+      return;
+    }
+    const record = {
+      schema: "fm-dash-command.v1",
+      id,
+      prompt,
+      requested_by: requesterLogin(req),
+      requested_at: new Date().toISOString(),
+      dashboard_generated: dashboard.generated,
+    };
+    const name = enqueueCommand(record);
+    log(`queued ${id} as ${name} for ${record.requested_by}`);
+    sendJson(res, 200, { status: "queued", pending: pending.length + 1 });
+    return;
+  }
+  sendJson(res, 404, { status: "not-found" });
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  let portOverride = null;
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--help" || args[i] === "-h") usage(0);
+    else if (args[i] === "--port" && args[i + 1]) { portOverride = Number(args[i + 1]); i += 1; }
+    else usage(2);
+  }
+  const config = readConfig();
+  const port = portOverride || config.port || 8847;
+  const server = http.createServer((req, res) => {
+    handle(req, res).catch((error) => {
+      log(`error handling ${req.method} ${req.url}: ${error.message}`);
+      if (!res.headersSent) sendJson(res, 500, { status: "error" });
+      else res.end();
+    });
+  });
+  server.listen(port, "127.0.0.1", () => {
+    log(`fm-dash-serve listening on 127.0.0.1:${port} for FM_HOME=${FM_HOME}${config.readOnly ? " (read-only)" : ""}`);
+  });
+  if (config.autoRefreshSeconds > 0) {
+    const autoRender = async () => {
+      const result = await runRefresh();
+      log(result.ok ? "auto-render replaced the dashboard" : `auto-render failed: ${result.error}`);
+    };
+    let stale = true;
+    try {
+      stale = Date.now() - fs.statSync(DASHBOARD).mtimeMs > config.autoRefreshSeconds * 1000;
+    } catch { /* missing dashboard is stale */ }
+    if (stale) autoRender();
+    setInterval(autoRender, config.autoRefreshSeconds * 1000).unref();
+  }
+  const stop = () => server.close(() => process.exit(0));
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+}
+
+main();
diff --git a/docs/configuration.md b/docs/configuration.md
index 17f1e16091c..ad9fd95a340 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -102,6 +102,13 @@ An absent file means `auto`, i.e. default-on on macOS: the alarm exists precisel
 A missing or failing channel logs and falls through to the next, never crashing the daemon.
 See [`wedge-alarm.md`](wedge-alarm.md) for the channel reference and macOS verification evidence, and [`examples/wedge-alarm`](examples/wedge-alarm) for a copyable config.
 
+## Capacity dashboard service (config/dash.json)
+
+The optional persistent dashboard service publishes `data/capacity-dashboard.html` tailnet-only at one stable HTTPS URL, adds one-click `CAP-NN` dispatch, clickable de-anonymized work-item and decision detail views, idea verdicts over `data/ideas/`, and a server-side refresh, and delivers clicked commands to the running Firstmate through durable `state/dash-inbox/` records surfaced by the registered `fm-dash` watcher check.
+`config/dash.json` (local, gitignored, written by `bin/fm-dash-install.sh`) holds `port` (loopback service port, default 8847), `captain_logins` (the tailnet logins allowed to reach the service), `read_only` (serve and auto-render without any mutation route), and `auto_refresh_seconds` (producer rerun interval, default 900, 0 disables); the service fails closed without a matching `Tailscale-User-Login` identity.
+The service reads the producer's opt-in `state/dash-refs.json` identity sidecar (`fm-capacity.mjs --refs`) to enrich the served page; the on-disk dashboard itself stays identity-opaque.
+`bin/fm-dash-serve.mjs --help` owns routes and the one-click allowlist, `bin/fm-dash-install.sh --help` owns launchd persistence and the never-Funnel tailscale serve wiring, `bin/fm-dash-inbox.sh --help` owns command consumption, and [`dashboard-service.md`](dashboard-service.md) owns the architecture and trust design.
+
 ## Gate defaults (.no-mistakes.yaml)
 
 The tracked `.no-mistakes.yaml` keeps test evidence outside the repo and defines `commands.test` so no-mistakes runs firstmate's bash behavior suite directly.
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
new file mode 100644
index 00000000000..a2584727693
--- /dev/null
+++ b/docs/dashboard-service.md
@@ -0,0 +1,85 @@
+# Persistent tailnet-only capacity dashboard service
+
+This document owns the architecture narrative, trust design, and verification evidence for the always-on capacity dashboard.
+Mechanics live with their owners: `bin/fm-dash-serve.mjs --help` (routes, config schema, one-click allowlist), `bin/fm-dash-install.sh --help` (persistence and tailscale wiring), `bin/fm-dash-inbox.sh --help` (command consumption), and the capacity skill (handling semantics for delivered commands).
+
+## What it is
+
+The service publishes the producer-generated `data/capacity-dashboard.html` at one stable tailnet HTTPS URL that survives reboots, and layers interactive abilities onto it:
+
+- Every current one-click-eligible `CAP-NN` action gets an "Approve & send" button.
+- A "Refresh capacity" button reruns `bin/fm-capacity.mjs` server-side and reloads the page; the producer also reruns automatically on the configured interval so the page never goes stale.
+- The page is de-anonymized for the authenticated captain: opaque `item-NN`/`project-NN`/`home-NN` references become real names, and work items and decisions are clickable rich detail views (description, test plan, PR link, tailnet preview links, report excerpt, recent activity) assembled from task briefs, recorded metadata, the backlog, and scout reports.
+- Open decisions show each recorded option with its impact, and every option carries an Approve button.
+- An Ideas section renders `data/ideas/idea-backlog.md`; each idea opens its pitch (`data/ideas/pitches/IDEA-XX.md` when present, else the concept summary) with Approve, Deny, and Add-suggestions controls.
+- A service bar shows how many captain commands are queued for firstmate.
+
+`bin/fm-capacity.mjs` remains the single owner of the dashboard's content and look; the service injects its interactive layer at serve time and never modifies the file on disk, so the file keeps working offline exactly as before.
+The on-disk dashboard stays identity-opaque: the producer's opt-in `--refs` sidecar (`state/dash-refs.json`, `fm-capacity-refs.v1`, mode 0600) carries the opaque-to-real mapping, and only the captain-authenticated service reads it to enrich the served page.
+
+## Components
+
+- `bin/fm-dash-serve.mjs` - the HTTP service, bound to 127.0.0.1 only.
+- `bin/fm-dash-install.sh` - launchd agent (`RunAtLoad` + `KeepAlive`, so it survives reboots and crashes), `tailscale serve` mapping, `config/dash.json`, and the registered `fm-dash` watcher check.
+- `state/dash-inbox/` - durable captain command records (`fm-dash-command.v1`), one file per clicked action.
+- `state/fm-dash.check.sh` - watcher check registered through `bin/fm-check-register.sh`; prints one line while commands are pending so the watcher wakes firstmate.
+- `bin/fm-dash-inbox.sh` - firstmate's list/claim helper; claim archives each record under `state/dash-inbox/archive/` so a command is surfaced exactly once.
+
+## Inbound command channel
+
+Button clicks never execute anything.
+The design keeps the web process outside every fleet-mutation path:
+
+1. The captain clicks "Send to firstmate" on a `CAP-NN` action.
+2. The service validates the request (see trust design) and writes one durable `fm-dash-command.v1` record into `state/dash-inbox/` with an atomic temp-file rename, mode 0600.
+3. The registered `fm-dash` watcher check notices the pending record on its normal cadence (`FM_CHECK_INTERVAL`, default 300 seconds) and wakes the running firstmate through the standard durable wake queue.
+4. Firstmate claims the records with `bin/fm-dash-inbox.sh claim` and handles each prompt as the captain's approval of that action ID under the capacity skill's section 4 semantics.
+
+Consequences of that shape:
+
+- The service holds no session with firstmate, no terminal access, and no merge, dispatch, or teardown capability; compromise of the web process yields at most bogus `CAP-NN` approval records, which firstmate still re-resolves through every normal lifecycle authority check.
+- Delivery is durable: a click made while firstmate is down waits in the inbox and is delivered on the next watcher cycle or session start sweep of pending checks.
+- Delivery latency is the watcher check cadence, not instantaneous; the page says "queued for firstmate" honestly rather than pretending immediacy.
+- Commands survive service restarts, firstmate restarts, and reboots because the inbox is plain durable state.
+
+## Trust design
+
+Identity is enforced at every layer that can fail:
+
+- `tailscale serve` terminates HTTPS on the tailnet and injects the `Tailscale-User-Login` header for the authenticated tailnet peer; Funnel traffic would carry no such identity.
+- The service refuses every route except `/healthz` unless that header matches a login in `config/dash.json` (`captain_logins`, recorded from the tailnet self login at install time or passed with `--captain`).
+- With no configured captain login the service serves only a setup notice and refuses everything else.
+- The service binds 127.0.0.1, so the only remote path in is the tailscale proxy; a local process on the captain's machine is already inside the trust boundary because it could write `FM_HOME` state directly.
+
+Dispatch is validated against records the server itself reads:
+
+- A `CAP-NN` request must currently be recommended by the served dashboard itself AND sit in the service's fixed one-click allowlist of reviewed lifecycle-safe actions; unknown or future IDs are refused with guidance to raise them in captain chat, so new actions default to chat-only.
+- A decision approval must name a decision in the producer's refs sidecar, and the chosen option must be one the server just parsed from that decision's structured backlog record; an off-record option is refused.
+- An idea verdict must name an idea currently listed in `data/ideas/idea-backlog.md` and one of the approve, deny, or suggest verbs; on approval, firstmate creates the work item(s) through the normal backlog lifecycle - the service itself never creates work.
+- The only free text accepted anywhere is the bounded add-suggestions note on an idea, which is captain-authored data for firstmate (the tailnet identity check makes it genuinely the captain), never a command the service interprets or executes.
+- Destructive, irreversible, and security-sensitive choices stay in captain chat structurally: no current `CAP-NN` prompt grants such authority, the capacity skill forbids treating a dashboard approval as merge or discard authority, decision records carry an explicit re-confirm-in-chat boundary for destructive consequences, and firstmate re-resolves every claimed command through the normal lifecycle before acting.
+
+Funnel is never acceptable for this surface.
+The installer only ever creates a plain `tailscale serve` mapping, verifies after configuring that no Funnel exposure exists for the served port, and tears the mapping back down and refuses if one is found.
+
+## Setup and removal
+
+```
+bin/fm-dash-install.sh install                # defaults: port 8847, serve port 8443, captain = tailnet self login
+bin/fm-dash-install.sh install --read-only    # serve and auto-render only; no dispatch, no watcher check
+bin/fm-dash-install.sh status
+bin/fm-dash-install.sh uninstall
+```
+
+A read-only install is the right shape for running the service ahead of command-consumption wiring: the page, detail views, refresh, and auto-render all work, while every mutation route refuses.
+
+Install is idempotent and prints the stable URL, `https://<machine>.<tailnet>.ts.net:8443/`.
+Uninstall removes the serve mapping and launchd agent but keeps `config/dash.json` and any pending commands.
+The launchd agent logs to `state/dash-serve.log`.
+On a non-macOS host the installer refuses and the service can be run under the local init system with the same tailscale serve mapping.
+
+## Verification evidence
+
+2026-07-28, macOS 15.6, node v26.5.0, tailscale CLI present at /opt/homebrew/bin/tailscale.
+`bash tests/fm-dash.test.sh` passed end to end against a live local service instance: identity-less and wrong-identity requests got 403 with no inbox write; an authorized dispatch wrote exactly one mode-0600 `fm-dash-command.v1` record and a duplicate click coalesced; free-text, non-allowlisted (`CAP-99`), and not-currently-recommended IDs were refused; `/api/refresh` regenerated the dashboard through the real producer; claim archived and printed each record exactly once; the registered check shim printed one line only while commands were pending; and the rendered plist carried `RunAtLoad`, `KeepAlive`, the pinned `FM_HOME`, and no Funnel reference.
+The launchd bootstrap and live `tailscale serve` mapping mutate the host machine and were not exercised from the isolated task worktree; run `bin/fm-dash-install.sh install` once on the target machine and confirm `status` shows the agent loaded, the serve mapping present, and `tailscale serve status` showing no Funnel line for the port.
diff --git a/docs/scripts.md b/docs/scripts.md
index 999a4a7a598..b5ad932dc11 100644
--- a/docs/scripts.md
+++ b/docs/scripts.md
@@ -14,6 +14,9 @@ The shared no-mistakes gate refusal used by `fm-spawn.sh`, `fm-send.sh`, and `fm
 | `fm-fleet-view.sh`       | Render the fleet snapshot as a human Markdown view                                   |
 | `fm-bearings-snapshot.sh` | Project the fleet snapshot to the compact TOON bearings view; local-only unless `--include-prs` |
 | `fm-capacity.mjs`        | Classify meaningful fleet capacity and replace the private offline pipeline dashboard |
+| `fm-dash-serve.mjs`      | Serve the capacity dashboard tailnet-only with one-click CAP dispatch and server-side refresh (docs/dashboard-service.md) |
+| `fm-dash-install.sh`     | Install the persistent dashboard service: launchd agent, never-Funnel tailscale serve mapping, and registered fm-dash check |
+| `fm-dash-inbox.sh`       | List and claim durable captain dashboard commands from `state/dash-inbox/`           |
 | `fm-update.sh`           | Fast-forward-only self-update of firstmate and secondmate homes from origin          |
 | `fm-task-add.sh`         | Create backlog items with creation-time task-ID validation and safe mint fitting     |
 | `fm-backlog-handoff.sh`  | Validate and delegate queued backlog-item moves into a secondmate home               |
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
new file mode 100644
index 00000000000..0f1f0927cba
--- /dev/null
+++ b/tests/fm-dash.test.sh
@@ -0,0 +1,397 @@
+#!/usr/bin/env bash
+# Behavior and contract tests for the persistent tailnet-only dashboard service:
+# bin/fm-dash-serve.mjs, bin/fm-dash-inbox.sh, and bin/fm-dash-install.sh.
+set -u
+
+# shellcheck source=tests/lib.sh disable=SC1091
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+SERVE="$ROOT/bin/fm-dash-serve.mjs"
+INBOX_SH="$ROOT/bin/fm-dash-inbox.sh"
+INSTALL_SH="$ROOT/bin/fm-dash-install.sh"
+CAPACITY="$ROOT/bin/fm-capacity.mjs"
+TMP_ROOT=$(fm_test_tmproot fm-dash)
+
+command -v node >/dev/null 2>&1 || { echo "skip: node not found"; exit 0; }
+command -v curl >/dev/null 2>&1 || { echo "skip: curl not found"; exit 0; }
+
+CAPTAIN="captain@example.com"
+SERVER_PID=""
+
+cleanup() {
+  [ -z "$SERVER_PID" ] || kill "$SERVER_PID" 2>/dev/null || true
+  fm_test_cleanup
+}
+trap cleanup EXIT
+
+make_fixture() {
+  local home=$1 snapshot=$2 environment=$3
+  mkdir -p "$home/data" "$home/state" "$home/config" "$home/projects"
+  cat > "$snapshot" <<EOF
+{
+  "schema": "fm-fleet-snapshot.v1",
+  "generated": "2026-07-28T10:00:00Z",
+  "fm_home": "$home",
+  "roots": {"fm_root":"$ROOT","state":"$home/state","data":"$home/data","config":"$home/config","projects":"$home/projects"},
+  "backlog": {
+    "path": "$home/data/backlog.md",
+    "present": true,
+    "records": [
+      {"order":1,"state":"queued","structured":true,"id":"ready-safe","title":"Ship the gamma feature","repo":"gamma","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: bounded regression tests pass."},
+      {"order":2,"state":"queued","structured":true,"id":"captain-choice","title":"Choose the rollout policy","repo":"alpha","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"pick conservative or fast rollout"}
+    ]
+  },
+  "tasks": [],
+  "scout_reports": [],
+  "secondmate_current": {"registry":{"available":true,"complete":true,"records":[]},"records":[],"total":0,"shown":0,"truncated":0},
+  "secondmate_landed": {"records":[],"truncated":[],"unreadable":[]}
+}
+EOF
+  cat > "$environment" <<'EOF'
+{
+  "backend": {"name":"tmux","available":true,"evidence":"required runtime tools present","owner":"fixture"},
+  "github_auth": {"status":"available","evidence":"authenticated","owner":"fixture"},
+  "dispatch": {"config_present":true,"valid":true,"reason":null,"lanes":[
+    {"harness":"codex","model":"gpt-test","effort":"high","when":"default","available":true,"availability_evidence":"executable present","quota":"not observed - capacity never guesses quota"}
+  ]},
+  "secondmates": {}
+}
+EOF
+  cat > "$home/data/backlog.md" <<'EOF'
+## In flight
+
+## Queued
+- [ ] ready-safe - Ship the gamma feature (repo: gamma) (kind: ship)
+  Acceptance criteria: bounded regression tests pass.
+- [ ] captain-choice - Choose the rollout policy (repo: alpha) (kind: captain)
+  Pick the alpha rollout pace before dependent work starts.
+  - Conservative rollout: slower, safest for existing users
+  - Fast rollout: reaches everyone this week, higher regression risk
+
+## Done
+EOF
+  mkdir -p "$home/data/ready-safe" "$home/data/ideas/pitches"
+  cat > "$home/data/ready-safe/brief.md" <<'EOF'
+# Task
+Ship the gamma feature so gamma users get streaming exports.
+
+Acceptance criteria:
+bounded regression tests pass and the export path stays backward compatible.
+
+# Setup
+Standard worktree setup.
+EOF
+  printf 'pr=https://github.com/purple-phoenix/firstmate/pull/999\nproject=%s/projects/gamma\nmode=no-mistakes\n' "$home" > "$home/state/ready-safe.meta"
+  printf 'working: preview at https://demo.tailebcf61.ts.net:5300/\n' > "$home/state/ready-safe.status"
+  cat > "$home/data/ideas/idea-backlog.md" <<'EOF'
+# Idea backlog
+
+## IDEA-01 - Faster onboarding
+New crew homes should self-provision in one command.
+
+## IDEA-02 - Nightly digest
+Send the captain a nightly fleet digest.
+EOF
+  printf '# Faster onboarding pitch\n\nOne command provisions a ready home.\n' > "$home/data/ideas/pitches/IDEA-01.md"
+}
+
+write_config() {
+  local home=$1 port=$2
+  cat > "$home/config/dash.json" <<EOF
+{"port": $port, "captain_logins": ["$CAPTAIN"]}
+EOF
+}
+
+pick_port() {
+  node -e 'const s=require("node:net").createServer();s.listen(0,"127.0.0.1",()=>{console.log(s.address().port);s.close();});'
+}
+
+start_server() {
+  local home=$1 port=$2 fixture_args=${3:-}
+  FM_HOME="$home" FM_DASH_CAPACITY_ARGS="$fixture_args" node "$SERVE" --port "$port" > "$TMP_ROOT/serve.log" 2>&1 &
+  SERVER_PID=$!
+  local tries=0
+  while ! curl -sf "http://127.0.0.1:$port/healthz" >/dev/null 2>&1; do
+    tries=$((tries + 1))
+    [ "$tries" -lt 50 ] || fail "dashboard service did not start (see $TMP_ROOT/serve.log)"
+    sleep 0.1
+  done
+}
+
+stop_server() {
+  [ -z "$SERVER_PID" ] || kill "$SERVER_PID" 2>/dev/null || true
+  SERVER_PID=""
+}
+
+REQ_STATUS=""
+RESP=""
+req() {
+  # req <method> <url> [login] [body] -> sets REQ_STATUS and RESP
+  local method=$1 url=$2 login=${3:-} body=${4:-}
+  local args=(-s -o "$TMP_ROOT/resp.body" -w '%{http_code}' -X "$method")
+  [ -z "$login" ] || args+=(-H "Tailscale-User-Login: $login")
+  [ -z "$body" ] || args+=(-H "content-type: application/json" -d "$body")
+  REQ_STATUS=$(curl "${args[@]}" "$url")
+  RESP=$(cat "$TMP_ROOT/resp.body")
+}
+
+HOME_DIR="$TMP_ROOT/home"
+SNAPSHOT="$TMP_ROOT/snapshot.json"
+ENVIRONMENT="$TMP_ROOT/environment.json"
+make_fixture "$HOME_DIR" "$SNAPSHOT" "$ENVIRONMENT"
+FM_HOME="$HOME_DIR" "$CAPACITY" --snapshot "$SNAPSHOT" --environment "$ENVIRONMENT" \
+  --output "$HOME_DIR/data/capacity-dashboard.html" --refs "$HOME_DIR/state/dash-refs.json" >/dev/null \
+  || fail "could not render the fixture dashboard with its refs sidecar"
+PORT=$(pick_port)
+write_config "$HOME_DIR" "$PORT"
+
+test_identity_fails_closed() {
+  local body
+  start_server "$HOME_DIR" "$PORT"
+  req GET "http://127.0.0.1:$PORT/healthz"
+  [ "$REQ_STATUS" = 200 ] || fail "healthz should not require identity (got $REQ_STATUS)"
+  req GET "http://127.0.0.1:$PORT/"
+  [ "$REQ_STATUS" = 403 ] || fail "identity-less page read was not refused (got $REQ_STATUS)"
+  req GET "http://127.0.0.1:$PORT/" "mallory@example.com"
+  [ "$REQ_STATUS" = 403 ] || fail "unauthorized tailnet identity was not refused (got $REQ_STATUS)"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "mallory@example.com" '{"id":"CAP-06"}'
+  [ "$REQ_STATUS" = 403 ] || fail "unauthorized dispatch was not refused (got $REQ_STATUS)"
+  [ -z "$(find "$HOME_DIR/state/dash-inbox" -name '*.json' 2>/dev/null)" ] \
+    || fail "a refused dispatch still wrote an inbox record"
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  [ "$REQ_STATUS" = 200 ] || fail "authorized captain read failed (got $REQ_STATUS)"
+  pass "every route except healthz requires the configured captain identity"
+}
+
+test_served_page_wears_dashboard_with_interactive_layer() {
+  local body
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  assert_contains "$RESP" 'Firstmate capacity dashboard' "served page is not the producer dashboard"
+  assert_contains "$RESP" 'fmdash-bar' "served page lacks the injected service bar"
+  assert_contains "$RESP" 'Refresh capacity' "served page lacks the refresh control"
+  assert_contains "$RESP" 'Approve & send' "served page lacks the dispatch control script"
+  assert_contains "$RESP" 'data-copy' "producer copy layer was lost in serving"
+  assert_contains "$RESP" '"ready-safe"' "served page config lacks the de-anonymized work item id"
+  assert_contains "$RESP" 'IDEA-01' "served page config lacks the idea backlog"
+  pass "served page is the producer dashboard wearing the injected interactive layer"
+}
+
+ref_for() {
+  # ref_for <kind-owner-prefix> e.g. "main/ready-safe" or "decision/captain-choice"
+  node -e '
+    const refs = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).refs;
+    const wanted = process.argv[2];
+    for (const [ref, entry] of Object.entries(refs)) {
+      if (entry.kind === "item" && entry.value === wanted) { console.log(ref); process.exit(0); }
+    }
+    process.exit(1);
+  ' "$HOME_DIR/state/dash-refs.json" "$1"
+}
+
+test_refs_sidecar_and_rich_work_item_detail() {
+  local ref
+  assert_present "$HOME_DIR/state/dash-refs.json" "producer did not write the refs sidecar"
+  assert_grep 'fm-capacity-refs.v1' "$HOME_DIR/state/dash-refs.json" "refs sidecar lacks its schema"
+  ref=$(ref_for "main/ready-safe") || fail "refs sidecar does not map the main work item"
+  req GET "http://127.0.0.1:$PORT/api/detail?ref=$ref" "$CAPTAIN"
+  [ "$REQ_STATUS" = 200 ] || fail "work item detail failed (got $REQ_STATUS: $RESP)"
+  assert_contains "$RESP" 'streaming exports' "detail lacks the brief description"
+  assert_contains "$RESP" 'backward compatible' "detail lacks the test plan"
+  assert_contains "$RESP" 'pull/999' "detail lacks the PR link"
+  assert_contains "$RESP" 'demo.tailebcf61.ts.net' "detail lacks the tailnet preview link"
+  req GET "http://127.0.0.1:$PORT/api/detail?ref=$ref"
+  [ "$REQ_STATUS" = 403 ] || fail "identity-less detail read was not refused (got $REQ_STATUS)"
+  pass "clickable work items serve rich detail from briefs, metadata, and previews"
+}
+
+test_decision_detail_options_and_validated_approval() {
+  local ref record
+  ref=$(ref_for "decision/captain-choice") || fail "refs sidecar does not map the decision"
+  req GET "http://127.0.0.1:$PORT/api/detail?ref=$ref" "$CAPTAIN"
+  [ "$REQ_STATUS" = 200 ] || fail "decision detail failed (got $REQ_STATUS: $RESP)"
+  assert_contains "$RESP" 'Conservative rollout' "decision detail lacks its first option"
+  assert_contains "$RESP" 'higher regression risk' "decision detail lacks the option impact"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"option\":7}"
+  [ "$REQ_STATUS" = 400 ] || fail "an off-record option was not refused (got $REQ_STATUS)"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"option\":0}"
+  [ "$REQ_STATUS" = 200 ] || fail "decision approval failed (got $REQ_STATUS: $RESP)"
+  record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name "*$ref.json" | head -1)")
+  assert_contains "$record" '"decision"' "decision record lacks its kind"
+  assert_contains "$record" 'captain-choice' "decision record lacks the decision key"
+  assert_contains "$record" 'Conservative rollout' "decision record lacks the chosen option"
+  assert_contains "$record" 'chat confirmation' "decision record lacks the destructive-consequence boundary"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"option\":1}"
+  assert_contains "$RESP" 'already-queued' "a second choice for the same decision was not coalesced"
+  find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name "*$ref.json" -delete
+  pass "decisions serve option detail and approvals are validated against the record"
+}
+
+test_idea_pitch_and_verdicts() {
+  local record
+  req GET "http://127.0.0.1:$PORT/api/detail?idea=IDEA-01" "$CAPTAIN"
+  [ "$REQ_STATUS" = 200 ] || fail "idea pitch failed (got $REQ_STATUS: $RESP)"
+  assert_contains "$RESP" 'One command provisions' "idea detail lacks the pitch file content"
+  req GET "http://127.0.0.1:$PORT/api/detail?idea=IDEA-02" "$CAPTAIN"
+  assert_contains "$RESP" 'nightly fleet digest' "pitchless idea lacks its concept summary"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-01","verdict":"approve"}'
+  [ "$REQ_STATUS" = 200 ] || fail "idea approval failed (got $REQ_STATUS: $RESP)"
+  record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-01.json' | head -1)")
+  assert_contains "$record" '"idea"' "idea record lacks its kind"
+  assert_contains "$record" 'normal backlog lifecycle' "idea approval does not route creation through firstmate"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-99","verdict":"approve"}'
+  [ "$REQ_STATUS" = 404 ] || fail "an unlisted idea was not refused (got $REQ_STATUS)"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-02","verdict":"suggest","suggestion":"scope it to weekdays only"}'
+  [ "$REQ_STATUS" = 200 ] || fail "idea suggestion failed (got $REQ_STATUS: $RESP)"
+  record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-02.json' | head -1)")
+  assert_contains "$record" 'scope it to weekdays only' "suggestion text was not recorded for firstmate"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-02","verdict":"suggest","suggestion":""}'
+  [ "$REQ_STATUS" = 400 ] || fail "an empty suggestion was not refused (got $REQ_STATUS)"
+  find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-*.json' -delete
+  pass "ideas render their pitches and verdicts flow through the durable inbox"
+}
+
+test_dispatch_writes_one_durable_record() {
+  local body record file
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"id":"CAP-06"}'
+  [ "$REQ_STATUS" = 200 ] || fail "captain dispatch failed (got $REQ_STATUS: $RESP)"
+  assert_contains "$RESP" '"queued"' "dispatch did not report queued"
+  file=$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*CAP-06.json' | head -1)
+  [ -n "$file" ] || fail "dispatch wrote no durable inbox record"
+  case "$(uname)" in
+    Darwin) [ "$(stat -f %Lp "$file")" = 600 ] || fail "inbox record is not mode 0600" ;;
+    *) [ "$(stat -c %a "$file")" = 600 ] || fail "inbox record is not mode 0600" ;;
+  esac
+  record=$(cat "$file")
+  assert_contains "$record" '"fm-dash-command.v1"' "inbox record lacks its schema"
+  assert_contains "$record" '"CAP-06"' "inbox record lacks the action id"
+  assert_contains "$record" 'Approve CAP-06' "inbox record lacks the model prompt"
+  assert_contains "$record" "$CAPTAIN" "inbox record lacks the requesting identity"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"id":"CAP-06"}'
+  assert_contains "$RESP" 'already-queued' "duplicate dispatch was not coalesced"
+  [ "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*CAP-06.json' | wc -l | tr -d ' ')" = 1 ] \
+    || fail "duplicate dispatch wrote a second record"
+  pass "a click becomes exactly one durable captain command record"
+}
+
+test_dispatch_refuses_unknown_and_uncurrent_actions() {
+  local body
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"id":"rm -rf /"}'
+  [ "$REQ_STATUS" = 400 ] || fail "free-text dispatch was not refused (got $REQ_STATUS)"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"id":"CAP-99"}'
+  [ "$REQ_STATUS" = 403 ] || fail "an action outside the one-click allowlist was not refused (got $REQ_STATUS)"
+  assert_contains "$RESP" 'captain chat' "the allowlist refusal does not route to captain chat"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"id":"CAP-02"}'
+  [ "$REQ_STATUS" = 409 ] || fail "an action absent from the current dashboard was not refused (got $REQ_STATUS)"
+  pass "dispatch refuses free text, non-allowlisted actions, and stale actions"
+}
+
+test_refresh_reruns_producer_server_side() {
+  local body before after
+  before=$(grep -o 'generated [^<]*' "$HOME_DIR/data/capacity-dashboard.html" | head -1)
+  stop_server
+  start_server "$HOME_DIR" "$PORT" "--snapshot $SNAPSHOT --environment $ENVIRONMENT"
+  rm -f "$HOME_DIR/data/capacity-dashboard.html"
+  req POST "http://127.0.0.1:$PORT/api/refresh" "$CAPTAIN"
+  [ "$REQ_STATUS" = 200 ] || fail "refresh failed (got $REQ_STATUS: $RESP)"
+  assert_contains "$RESP" 'refreshed' "refresh did not report success"
+  [ -f "$HOME_DIR/data/capacity-dashboard.html" ] || fail "refresh did not regenerate the dashboard"
+  after=$(grep -o 'generated [^<]*' "$HOME_DIR/data/capacity-dashboard.html" | head -1)
+  [ -n "$after" ] || fail "regenerated dashboard has no generated stamp"
+  : "$before"
+  pass "refresh reruns the capacity producer server-side and replaces the dashboard"
+}
+
+test_inbox_list_claim_and_archive() {
+  local out
+  out=$(FM_HOME="$HOME_DIR" "$INBOX_SH" pending-count)
+  [ "$out" = 1 ] || fail "pending-count expected 1, got: $out"
+  out=$(FM_HOME="$HOME_DIR" "$INBOX_SH" list)
+  assert_contains "$out" 'CAP-06' "list omits the pending action"
+  assert_contains "$out" "$CAPTAIN" "list omits the requesting identity"
+  out=$(FM_HOME="$HOME_DIR" "$INBOX_SH" claim)
+  assert_contains "$out" 'claimed: 1' "claim did not claim the pending command"
+  assert_contains "$out" 'Approve CAP-06' "claim omits the command prompt"
+  assert_contains "$out" 'authority limits apply' "claim omits the authority boundary reminder"
+  [ -z "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*.json' 2>/dev/null)" ] \
+    || fail "claim left the record pending"
+  [ -n "$(find "$HOME_DIR/state/dash-inbox/archive" -name '*CAP-06.json' 2>/dev/null)" ] \
+    || fail "claim did not archive the record"
+  out=$(FM_HOME="$HOME_DIR" "$INBOX_SH" claim)
+  assert_contains "$out" 'no pending dashboard commands' "second claim re-surfaced the archived command"
+  pass "inbox claim surfaces each command exactly once and archives it durably"
+}
+
+test_read_only_mode_fails_safe() {
+  stop_server
+  cat > "$HOME_DIR/config/dash.json" <<EOF
+{"port": $PORT, "captain_logins": ["$CAPTAIN"], "read_only": true, "auto_refresh_seconds": 0}
+EOF
+  start_server "$HOME_DIR" "$PORT"
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  [ "$REQ_STATUS" = 200 ] || fail "read-only page read failed (got $REQ_STATUS)"
+  assert_contains "$RESP" '"readOnly":true' "read-only page does not declare read-only mode"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"id":"CAP-06"}'
+  [ "$REQ_STATUS" = 403 ] || fail "read-only dispatch was not refused (got $REQ_STATUS)"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-01","verdict":"approve"}'
+  [ "$REQ_STATUS" = 403 ] || fail "read-only idea verdict was not refused (got $REQ_STATUS)"
+  stop_server
+  write_config "$HOME_DIR" "$PORT"
+  pass "read-only mode serves the page and refuses every mutation"
+}
+
+test_check_shim_wakes_only_when_pending() {
+  local out
+  FM_HOME="$HOME_DIR" "$INSTALL_SH" write-check >/dev/null || fail "write-check failed"
+  [ -f "$HOME_DIR/state/fm-dash.check-trust" ] || fail "write-check did not register the check"
+  out=$(sh "$HOME_DIR/state/fm-dash.check.sh")
+  [ -z "$out" ] || fail "check shim woke with an empty inbox: $out"
+  printf '{"schema":"fm-dash-command.v1","id":"CAP-06","prompt":"x"}\n' > "$HOME_DIR/state/dash-inbox/1-test-CAP-06.json"
+  out=$(sh "$HOME_DIR/state/fm-dash.check.sh")
+  assert_contains "$out" '1 captain command(s) pending' "check shim did not report the pending command"
+  assert_contains "$out" 'fm-dash-inbox.sh claim' "check shim does not name the claim helper"
+  [ "$(printf '%s\n' "$out" | wc -l | tr -d ' ')" = 1 ] || fail "check shim printed more than one line"
+  rm -f "$HOME_DIR/state/dash-inbox/1-test-CAP-06.json"
+  pass "the registered watcher check wakes firstmate only while commands are pending"
+}
+
+test_installer_plist_and_funnel_stance() {
+  local plist
+  plist=$(FM_HOME="$HOME_DIR" "$INSTALL_SH" print-plist) || fail "print-plist failed"
+  assert_contains "$plist" 'io.firstmate.dashboard.' "plist lacks the per-home label"
+  assert_contains "$plist" 'fm-dash-serve.mjs' "plist does not run the dashboard service"
+  assert_contains "$plist" '<key>KeepAlive</key><true/>' "plist does not keep the service alive"
+  assert_contains "$plist" '<key>RunAtLoad</key><true/>' "plist does not start at load"
+  assert_contains "$plist" "<string>$HOME_DIR</string>" "plist does not pin FM_HOME"
+  printf '%s' "$plist" | grep -qi funnel && fail "plist mentions funnel"
+  grep -n 'tailscale funnel' "$INSTALL_SH" && fail "installer invokes tailscale funnel"
+  assert_grep 'assert_no_funnel' "$INSTALL_SH" "installer does not verify funnel is off"
+  assert_grep 'never enables Funnel' "$INSTALL_SH" "installer does not declare the funnel boundary"
+  pass "the launchd agent survives reboots and the installer is structurally funnel-free"
+}
+
+test_service_contract_docs_and_ownership() {
+  assert_present "$ROOT/docs/dashboard-service.md" "dashboard service doc is missing"
+  assert_grep 'dash-inbox' "$ROOT/docs/dashboard-service.md" "service doc omits the inbound channel"
+  assert_grep 'fm-dash' "$ROOT/AGENTS.md" "AGENTS.md lacks the dashboard command wake trigger"
+  assert_grep 'dash-inbox' "$ROOT/AGENTS.md" "AGENTS.md state map lacks dash-inbox"
+  assert_grep 'config/dash.json' "$ROOT/.gitignore" "config/dash.json is not gitignored"
+  assert_grep 'dashboard service' "$ROOT/.agents/skills/capacity/SKILL.md" "capacity skill does not own dashboard command handling"
+  assert_grep 'never Funnel' "$ROOT/.agents/skills/capacity/SKILL.md" "capacity skill does not carry the funnel boundary"
+  pass "the service is documented and wired into the operating contract"
+}
+
+test_identity_fails_closed
+test_served_page_wears_dashboard_with_interactive_layer
+test_refs_sidecar_and_rich_work_item_detail
+test_decision_detail_options_and_validated_approval
+test_idea_pitch_and_verdicts
+test_dispatch_writes_one_durable_record
+test_dispatch_refuses_unknown_and_uncurrent_actions
+test_refresh_reruns_producer_server_side
+test_inbox_list_claim_and_archive
+test_read_only_mode_fails_safe
+test_check_shim_wakes_only_when_pending
+test_installer_plist_and_funnel_stance
+test_service_contract_docs_and_ownership
+
+echo "fm-dash tests passed"

From 4f6483c6a8149153eed5649dcea2fc4ecf77b9ee Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 10:43:37 -0400
Subject: [PATCH 02/24] no-mistakes(review): Harden dashboard rendering, refs,
 and plist generation

---
 bin/fm-dash-install.sh | 15 +++++++++++---
 bin/fm-dash-serve.mjs  | 18 +++++++++++-----
 tests/fm-dash.test.sh  | 47 +++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 71 insertions(+), 9 deletions(-)

diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index 6b1ddf294c3..68f0d6b1999 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -131,7 +131,12 @@ write_config() {
 }
 
 render_plist() {
-  local label=$1 node_path=$2 log_dir=$3
+  local label node_path log_dir fm_root fm_home
+  label=$(xml_escape "$1")
+  node_path=$(xml_escape "$2")
+  log_dir=$(xml_escape "$3")
+  fm_root=$(xml_escape "$FM_ROOT")
+  fm_home=$(xml_escape "$FM_HOME")
   cat <<PLIST
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -141,11 +146,11 @@ render_plist() {
   <key>ProgramArguments</key>
   <array>
     <string>$node_path</string>
-    <string>$FM_ROOT/bin/fm-dash-serve.mjs</string>
+    <string>$fm_root/bin/fm-dash-serve.mjs</string>
   </array>
   <key>EnvironmentVariables</key>
   <dict>
-    <key>FM_HOME</key><string>$FM_HOME</string>
+    <key>FM_HOME</key><string>$fm_home</string>
   </dict>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><true/>
@@ -156,6 +161,10 @@ render_plist() {
 PLIST
 }
 
+xml_escape() {
+  node -e 'process.stdout.write(process.argv[1].replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("\x27", "&apos;"))' "$1"
+}
+
 write_check() {
   mkdir -p "$STATE"
   cat > "$CHECK" <<'SHIM'
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
index 71b55af38b8..6ddb2bdd9cf 100755
--- a/bin/fm-dash-serve.mjs
+++ b/bin/fm-dash-serve.mjs
@@ -174,10 +174,10 @@ function enqueueCommand(record) {
 // refs sidecar, the backlog, task briefs, task metadata, status tails, and
 // scout reports. Detail is served only to the authenticated captain.
 
-function readRefs() {
+function readRefs(generated) {
   try {
     const parsed = JSON.parse(fs.readFileSync(REFS, "utf8"));
-    if (parsed.schema !== "fm-capacity-refs.v1" || typeof parsed.refs !== "object") return null;
+    if (parsed.schema !== "fm-capacity-refs.v1" || parsed.generated !== generated || typeof parsed.refs !== "object") return null;
     return parsed;
   } catch {
     return null;
@@ -285,7 +285,8 @@ function refDisplayMap(refsFile) {
 }
 
 function assembleDetail(ref) {
-  const refsFile = readRefs();
+  const dashboard = readDashboard();
+  const refsFile = dashboard ? readRefs(dashboard.generated) : null;
   const entry = refsFile?.refs?.[ref];
   if (!entry || entry.kind !== "item") return null;
   const separator = entry.value.indexOf("/");
@@ -423,13 +424,20 @@ function authorized(req, config) {
   return login !== "" && config.logins.includes(login);
 }
 
+function inlineScriptJson(value) {
+  return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (character) => {
+    const escapes = { "<": "\\u003c", ">": "\\u003e", "&": "\\u0026", "\u2028": "\\u2028", "\u2029": "\\u2029" };
+    return escapes[character];
+  });
+}
+
 // Injected interactive layer. It only talks to this service's own API; the
 // underlying producer file stays untouched on disk and keeps working offline.
 // When the producer's refs sidecar is present the layer also de-anonymizes the
 // page for the authenticated captain: opaque item/project/home references get
 // their real names, and work items and decisions become clickable detail views.
 function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
-  const config = JSON.stringify({
+  const config = inlineScriptJson({
     dispatchable,
     pending,
     generated,
@@ -888,7 +896,7 @@ async function handle(req, res) {
       return;
     }
     const dispatchable = config.readOnly ? [] : [...dashboard.actions.keys()].filter((id) => ONE_CLICK_ACTIONS.has(id));
-    const refsFile = readRefs();
+    const refsFile = readRefs(dashboard.generated);
     const layer = interactiveLayer(dispatchable, pendingRecords().length, dashboard.generated, config.readOnly, {
       refs: refsFile ? refDisplayMap(refsFile) : {},
       ideas: parseIdeas().map((idea) => ({ id: idea.id, title: idea.title })),
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index 0f1f0927cba..ebb5e224233 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -176,6 +176,19 @@ test_served_page_wears_dashboard_with_interactive_layer() {
   pass "served page is the producer dashboard wearing the injected interactive layer"
 }
 
+test_inline_config_is_script_safe() {
+  cat >> "$HOME_DIR/data/ideas/idea-backlog.md" <<'EOF'
+
+## IDEA-03 - </script><script>globalThis.fmdashPwned=true</script>&
+Inline configuration must remain data.
+EOF
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  [ "$REQ_STATUS" = 200 ] || fail "page with hostile operational data failed (got $REQ_STATUS)"
+  assert_not_contains "$RESP" '</script><script>globalThis.fmdashPwned=true</script>' "operational data broke out of the inline script"
+  assert_contains "$RESP" '\u003c/script\u003e\u003cscript\u003eglobalThis.fmdashPwned=true\u003c/script\u003e\u0026' "inline script data was not safely escaped"
+  pass "operational data cannot break out of the inline configuration script"
+}
+
 ref_for() {
   # ref_for <kind-owner-prefix> e.g. "main/ready-safe" or "decision/captain-choice"
   node -e '
@@ -226,6 +239,32 @@ test_decision_detail_options_and_validated_approval() {
   pass "decisions serve option detail and approvals are validated against the record"
 }
 
+test_stale_refs_are_disabled() {
+  local ref
+  ref=$(ref_for "decision/captain-choice") || fail "refs sidecar does not map the decision"
+  node -e '
+    const fs = require("node:fs");
+    const file = process.argv[1];
+    const refs = JSON.parse(fs.readFileSync(file, "utf8"));
+    refs.generated = "stale-generation";
+    fs.writeFileSync(file, `${JSON.stringify(refs, null, 2)}\n`);
+  ' "$HOME_DIR/state/dash-refs.json"
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  assert_contains "$RESP" '"refs":{}' "stale refs still de-anonymized the served page"
+  req GET "http://127.0.0.1:$PORT/api/detail?ref=$ref" "$CAPTAIN"
+  [ "$REQ_STATUS" = 404 ] || fail "stale refs still resolved detail (got $REQ_STATUS)"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"option\":0}"
+  [ "$REQ_STATUS" = 400 ] || fail "stale refs still authorized an approval (got $REQ_STATUS)"
+  node -e '
+    const fs = require("node:fs");
+    const file = process.argv[1];
+    const refs = JSON.parse(fs.readFileSync(file, "utf8"));
+    refs.generated = "2026-07-28T10:00:00Z";
+    fs.writeFileSync(file, `${JSON.stringify(refs, null, 2)}\n`);
+  ' "$HOME_DIR/state/dash-refs.json"
+  pass "refs are usable only for their matching dashboard generation"
+}
+
 test_idea_pitch_and_verdicts() {
   local record
   req GET "http://127.0.0.1:$PORT/api/detail?idea=IDEA-01" "$CAPTAIN"
@@ -355,7 +394,7 @@ test_check_shim_wakes_only_when_pending() {
 }
 
 test_installer_plist_and_funnel_stance() {
-  local plist
+  local escaped_home plist
   plist=$(FM_HOME="$HOME_DIR" "$INSTALL_SH" print-plist) || fail "print-plist failed"
   assert_contains "$plist" 'io.firstmate.dashboard.' "plist lacks the per-home label"
   assert_contains "$plist" 'fm-dash-serve.mjs' "plist does not run the dashboard service"
@@ -366,6 +405,10 @@ test_installer_plist_and_funnel_stance() {
   grep -n 'tailscale funnel' "$INSTALL_SH" && fail "installer invokes tailscale funnel"
   assert_grep 'assert_no_funnel' "$INSTALL_SH" "installer does not verify funnel is off"
   assert_grep 'never enables Funnel' "$INSTALL_SH" "installer does not declare the funnel boundary"
+  escaped_home="$HOME_DIR/xml & < >"
+  plist=$(FM_HOME="$escaped_home" FM_ROOT_OVERRIDE="$HOME_DIR/root & < >" "$INSTALL_SH" print-plist) || fail "print-plist with XML metacharacters failed"
+  assert_contains "$plist" "$HOME_DIR/xml &amp; &lt; &gt;" "plist did not XML-escape FM_HOME"
+  assert_contains "$plist" "$HOME_DIR/root &amp; &lt; &gt;/bin/fm-dash-serve.mjs" "plist did not XML-escape the executable path"
   pass "the launchd agent survives reboots and the installer is structurally funnel-free"
 }
 
@@ -382,8 +425,10 @@ test_service_contract_docs_and_ownership() {
 
 test_identity_fails_closed
 test_served_page_wears_dashboard_with_interactive_layer
+test_inline_config_is_script_safe
 test_refs_sidecar_and_rich_work_item_detail
 test_decision_detail_options_and_validated_approval
+test_stale_refs_are_disabled
 test_idea_pitch_and_verdicts
 test_dispatch_writes_one_durable_record
 test_dispatch_refuses_unknown_and_uncurrent_actions

From 309dd593bd77fa25d46958c54338726b708d797b Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 11:03:55 -0400
Subject: [PATCH 03/24] no-mistakes(review): Harden dashboard commands,
 decisions, usage, and delivery

---
 .agents/skills/capacity/SKILL.md |   4 +-
 bin/fm-capacity.mjs              |  20 +-
 bin/fm-dash-inbox.sh             |  21 +-
 bin/fm-dash-install.sh           |  28 ++-
 bin/fm-dash-serve.mjs            | 335 ++++++++++++++++++++++++++-----
 docs/dashboard-service.md        |  38 +++-
 tests/fm-dash.test.sh            | 153 ++++++++++++--
 7 files changed, 509 insertions(+), 90 deletions(-)

diff --git a/.agents/skills/capacity/SKILL.md b/.agents/skills/capacity/SKILL.md
index 704dbb78ef4..c9eebd26eca 100644
--- a/.agents/skills/capacity/SKILL.md
+++ b/.agents/skills/capacity/SKILL.md
@@ -25,6 +25,7 @@ Do not assemble a competing snapshot with ad hoc state reads, GitHub calls, term
 Never infer current state from `state/<id>.status`, because it is append-only wake-event history rather than current-state truth.
 Do not scrape scout reports, browser review artifacts, or Lavish surfaces to discover decisions.
 Structured captain holds and the keyed open-decision fold are the only decision inputs.
+When filing a decision, Firstmate or its worker must write the deciding home's structured options document using the format owned by `docs/dashboard-service.md`.
 
 The generated dashboard is a polished, responsive, accessible, self-contained HTML file that works directly from disk.
 Do not invoke, depend on, open, poll, share, or embed Lavish for `/capacity`.
@@ -92,9 +93,10 @@ The service never executes fleet commands: a click only writes a durable command
 Its refresh button reruns the producer server-side and is equivalent to a fresh normal invocation, so it needs no Firstmate action.
 
 On a `check:` wake naming `fm-dash.check.sh`, run `bin/fm-dash-inbox.sh claim` and handle each claimed record by its kind:
+Claim delivery is at-least-once across interruption, so check whether a re-surfaced record was already handled before applying it again.
 
 - A `CAP-NN` record is the captain's ordinary chat approval of that action ID under section 4, including its full re-resolution and authority limits.
-- A `decision` record is the captain's answer for the named decision key with the recorded option text; route it through `decision-hold-lifecycle` exactly as a chat answer, and re-confirm in chat before acting when the chosen option has a destructive or irreversible consequence.
+- A `decision` record is the captain's answer for the named decision key with either the recorded option text or bounded custom answer; route it through `decision-hold-lifecycle` exactly as a chat answer, and re-confirm in chat before acting when the answer has a destructive or irreversible consequence.
 - An `idea` record is the captain's verdict on the named `data/ideas/` idea: on approve, create the follow-up work item(s) through the normal backlog lifecycle; on deny, record the outcome against the idea; on suggest, treat the suggestion text as captain input on that idea.
 
 A claimed record never authorizes a PR merge, `local-only` landing, destructive action, irreversible action, security-sensitive action, or discard of unlanded work; when a claimed action leads to such a choice, escalate it to captain chat exactly as section 4 requires.
diff --git a/bin/fm-capacity.mjs b/bin/fm-capacity.mjs
index 7da76654d69..6fe98360421 100755
--- a/bin/fm-capacity.mjs
+++ b/bin/fm-capacity.mjs
@@ -387,6 +387,10 @@ function itemRef(owner, id) {
   return opaqueRef("item", `${owner}/${id}`);
 }
 
+function decisionRef(owner, id) {
+  return opaqueRef("item", `decision/${owner}/${id}`);
+}
+
 function ownerRef(owner) {
   if (owner === "main" || owner === "ephemeral worker") return owner;
   return `persistent ${opaqueRef("home", String(owner).replace(/^secondmate\s+/, ""))}`;
@@ -600,7 +604,7 @@ function classify(snapshot, environment) {
       decisions.push({
         owner: "main",
         task: itemRef("main", task.id),
-        key: itemRef("decision", decision.key || task.id),
+        key: decisionRef("main", decision.key || task.id),
         reason: "Open decision raised by work already under way.",
       });
     }
@@ -641,7 +645,7 @@ function classify(snapshot, environment) {
       decisions.push({
         owner: "main",
         task: itemRef("main", record.id),
-        key: itemRef("decision", record.id),
+        key: decisionRef("main", record.id),
         reason: "A queued choice is held for your decision.",
       });
       blockedRows.push({ id: itemRef("main", record.id), owner: "main", reason: "captain hold" });
@@ -649,8 +653,9 @@ function classify(snapshot, environment) {
       continue;
     }
     if (record.blocked_by || record.hold_reason) {
-      blockedRows.push({ id: itemRef("main", record.id), owner: "main", reason: "dependency or structured hold" });
-      pipeline.blocked.push(cardFromBacklog(record, "main", "blocked", "Dependency or structured hold"));
+      const reason = record.blocked_by ? `Blocked by ${itemRef("main", record.blocked_by)}` : "Structured hold";
+      blockedRows.push({ id: itemRef("main", record.id), owner: "main", reason });
+      pipeline.blocked.push(cardFromBacklog(record, "main", "blocked", reason));
       continue;
     }
     const timeGate = futureTimeGate(record, now);
@@ -705,7 +710,7 @@ function classify(snapshot, environment) {
       decisions.push({
         owner: ownerRef(mate.id),
         task: itemRef(mate.id, decision.id || mate.id),
-        key: itemRef("decision", decision.key || decision.id || mate.id),
+        key: decisionRef(mate.id, decision.key || decision.id || mate.id),
         reason: "Open decision raised by work already under way.",
       });
     }
@@ -766,8 +771,9 @@ function classify(snapshot, environment) {
         continue;
       }
       if (record.blocked_by || record.hold_reason) {
-        blockedRows.push({ id: itemRef(mate.id, record.id), owner: ownerRef(mate.id), reason: "dependency or structured hold" });
-        pipeline.blocked.push(cardFromBacklog(record, mate.id, "blocked", "Dependency or structured hold"));
+        const reason = record.blocked_by ? `Blocked by ${itemRef(mate.id, record.blocked_by)}` : "Structured hold";
+        blockedRows.push({ id: itemRef(mate.id, record.id), owner: ownerRef(mate.id), reason });
+        pipeline.blocked.push(cardFromBacklog(record, mate.id, "blocked", reason));
         continue;
       }
       const timeGate = futureTimeGate(record, now);
diff --git a/bin/fm-dash-inbox.sh b/bin/fm-dash-inbox.sh
index d0b9d4a4b5f..39559dbf9ce 100755
--- a/bin/fm-dash-inbox.sh
+++ b/bin/fm-dash-inbox.sh
@@ -3,10 +3,9 @@
 #
 # Single owner of state/dash-inbox/ consumption: listing pending
 # fm-dash-command.v1 records written by bin/fm-dash-serve.mjs and claiming them
-# durably. "claim" atomically archives each record under
-# state/dash-inbox/archive/ (newest 50 kept) and prints it, so a command is
-# surfaced exactly once even across interrupted turns; a claim that printed is a
-# claim that archived. Consumption semantics are owned by the capacity skill:
+# durably. "claim" prints each record before archiving it under
+# state/dash-inbox/archive/ (newest 50 kept), so an interruption can re-surface
+# a command but can never silently lose one. Consumption semantics are owned by the capacity skill:
 # each claimed prompt is the captain's approval of that CAP action ID with all
 # of that skill's authority limits, never destructive or merge authority.
 #
@@ -91,14 +90,16 @@ case "${1:-list}" in
     mkdir -p "$ARCHIVE"
     chmod 700 "$ARCHIVE" 2>/dev/null || true
     count=0
-    claimed=""
     while IFS= read -r f; do
       dest="$ARCHIVE/$(basename "$f")"
-      # rename-based claim: a record either stays pending or is archived; a
-      # concurrent claimer loses the rename and skips the record.
+      if [ -e "$dest" ]; then
+        rm -f -- "$f"
+        continue
+      fi
+      [ -e "$f" ] || continue
+      print_record "$f"
       if mv -n -- "$f" "$dest" 2>/dev/null && [ ! -e "$f" ] && [ -e "$dest" ]; then
         count=$((count + 1))
-        claimed="$claimed$dest"$'\n'
       fi
     done <<EOF
 $files
@@ -108,10 +109,6 @@ EOF
       exit 0
     fi
     printf 'claimed: %s captain dashboard command(s)\n' "$count"
-    printf '%s' "$claimed" | while IFS= read -r f; do
-      [ -n "$f" ] || continue
-      print_record "$f"
-    done
     echo "handle each prompt as the captain's approval of that action ID under the capacity skill; its authority limits apply and nothing here authorizes a merge, discard, or other destructive act."
     prune_archive
     ;;
diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index 68f0d6b1999..b359b3c5562 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -98,21 +98,39 @@ tailscale_self_dnsname() {
 # Refuse loudly if any Funnel exposure exists for the served port. Funnel is
 # never acceptable for this service.
 assert_no_funnel() {
-  local serve_port=$1
-  "$(tailscale_bin)" serve status --json 2>/dev/null | node -e '
+  local serve_port=$1 status_json
+  status_json=$("$(tailscale_bin)" serve status --json 2>/dev/null) || {
+    echo "could not verify Funnel state: tailscale serve status failed" >&2
+    return 1
+  }
+  printf '%s' "$status_json" | node -e '
     let raw = "";
     process.stdin.on("data", (c) => { raw += c; });
     process.stdin.on("end", () => {
       try {
-        const s = JSON.parse(raw || "{}");
+        const s = JSON.parse(raw);
+        if (!s || Array.isArray(s) || typeof s !== "object"
+          || !s.TCP || Array.isArray(s.TCP) || typeof s.TCP !== "object"
+          || !s.Web || Array.isArray(s.Web) || typeof s.Web !== "object"
+          || !s.TCP[process.argv[1]] || s.TCP[process.argv[1]].HTTPS !== true
+          || !Object.keys(s.Web).some((hostport) => hostport.endsWith(":" + process.argv[1]))) {
+          throw new Error("unsupported tailscale serve status schema");
+        }
+        if (s.AllowFunnel !== undefined && (!s.AllowFunnel || Array.isArray(s.AllowFunnel) || typeof s.AllowFunnel !== "object")) {
+          throw new Error("unsupported AllowFunnel schema");
+        }
         const allow = s.AllowFunnel || {};
         for (const [hostport, enabled] of Object.entries(allow)) {
+          if (typeof enabled !== "boolean") throw new Error("unsupported AllowFunnel value");
           if (enabled && hostport.endsWith(":" + process.argv[1])) {
             console.error("funnel is enabled for " + hostport);
             process.exit(1);
           }
         }
-      } catch {}
+      } catch (error) {
+        console.error("could not verify Funnel state: " + error.message);
+        process.exit(1);
+      }
     });
   ' "$serve_port"
 }
@@ -230,7 +248,7 @@ cmd_install() {
     || err "tailscale serve refused the mapping; is tailscale up?"
   if ! assert_no_funnel "$serve_port"; then
     "$(tailscale_bin)" serve --https="$serve_port" off >/dev/null 2>&1 || true
-    err "funnel exposure detected for port $serve_port; the mapping was removed - this service must stay tailnet-only"
+    err "could not verify tailnet-only exposure for port $serve_port; the mapping was removed - this service must stay tailnet-only"
   fi
 
   dnsname=$(tailscale_self_dnsname) || err "could not resolve this machine's tailnet name"
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
index 6ddb2bdd9cf..605d4263cdf 100755
--- a/bin/fm-dash-serve.mjs
+++ b/bin/fm-dash-serve.mjs
@@ -9,8 +9,8 @@
  * launchd persistence and tailscale serve wiring; bin/fm-dash-inbox.sh owns
  * firstmate-side consumption of the records this service writes.
  *
- * The service never executes fleet commands, never calls firstmate tooling other
- * than the read-mostly bin/fm-capacity.mjs producer, and never mutates any state
+ * The service never executes fleet commands, calls only the read-mostly capacity
+ * producer and quota probe, and never mutates any state
  * outside state/dash-inbox/ and the producer-owned dashboard file. A clicked
  * CAP action becomes one durable fm-dash-command.v1 record in state/dash-inbox/;
  * the running firstmate consumes it through its registered fm-dash watcher check
@@ -52,8 +52,11 @@ const REFS = path.join(STATE, "dash-refs.json");
 const BACKLOG = path.join(DATA, "backlog.md");
 const IDEAS = path.join(DATA, "ideas", "idea-backlog.md");
 const PITCHES = path.join(DATA, "ideas", "pitches");
+const QUOTA_AXI = process.env.FM_DASH_QUOTA_AXI || "quota-axi";
 const REFRESH_TIMEOUT_MS = 180000;
-const MAX_BODY_BYTES = 4096;
+const QUOTA_TIMEOUT_MS = 8000;
+const QUOTA_CACHE_MS = 60000;
+const MAX_BODY_BYTES = 16384;
 
 // One-click eligible action IDs. Every current CAP action only requests
 // lifecycle-safe guidance or work that re-enters normal authority checks
@@ -83,10 +86,11 @@ auto-render. Routes:
   GET  /              dashboard with the interactive layer injected
   GET  /api/pending   pending command count
   POST /api/refresh   rerun bin/fm-capacity.mjs server-side (serialized)
-  POST /api/dispatch  {"id":"CAP-NN"} -> durable record in state/dash-inbox/
+  POST /api/dispatch  validated CAP action, decision answer, or idea verdict
 All routes except /healthz require a Tailscale-User-Login header matching a
 configured captain login and fail closed otherwise. Dispatch refuses IDs not in
-both the served dashboard and the fixed one-click allowlist.
+both the served dashboard and the fixed one-click allowlist. Browser POSTs must
+also be same-origin.
 `);
   process.exit(exitCode);
 }
@@ -152,7 +156,10 @@ function pendingRecords() {
     if (!name.endsWith(".json")) continue;
     try {
       const record = JSON.parse(fs.readFileSync(path.join(INBOX, name), "utf8"));
-      if (record && typeof record.id === "string") records.push(record);
+      if (record && typeof record.id === "string") {
+        Object.defineProperty(record, "_file", { value: path.join(INBOX, name) });
+        records.push(record);
+      }
     } catch {
       // An unreadable record still counts as pending for the inbox owner; skip here.
     }
@@ -169,6 +176,13 @@ function enqueueCommand(record) {
   return name;
 }
 
+function replaceCommand(file, record) {
+  const tmp = path.join(INBOX, `.tmp-${randomBytes(6).toString("hex")}`);
+  fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  return path.basename(file);
+}
+
 // --- read-only detail assembly -------------------------------------------
 // Everything below only READS records the home already keeps: the producer's
 // refs sidecar, the backlog, task briefs, task metadata, status tails, and
@@ -253,18 +267,54 @@ function previewLinks(...texts) {
   return [...links];
 }
 
-// Bulleted or numbered body lines of a captain-hold item are its options; each
-// option's impact is the text of that line plus any continuation up to the next
-// option marker.
-function decisionOptions(body) {
+function decisionRef(entry) {
+  const parts = entry.value.split("/");
+  if (parts[0] !== "decision") return null;
+  if (parts.length >= 3) return { home: parts[1], id: parts.slice(2).join("/") };
+  return { home: "main", id: parts.slice(1).join("/") };
+}
+
+function decisionHome(home) {
+  if (home === "main") return FM_HOME;
+  const meta = readMeta(home);
+  return meta.home ? path.resolve(meta.home) : null;
+}
+
+function decisionDocument(home, id) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id)) return null;
+  const root = decisionHome(home);
+  if (!root) return null;
+  const text = readText(path.join(root, "data", "decisions", `${id}.md`), 131072);
+  if (!text) return null;
+  const title = (text.match(/^#\s+(.+)$/m) || [])[1]?.trim();
+  const sections = text.split(/^##\s+Options\s*$/im);
+  if (!title || sections.length < 2) return null;
+  const context = sections[0].replace(/^#\s+.*$/m, "").trim().slice(0, 4000) || null;
   const options = [];
   let current = null;
-  for (const line of body) {
-    const marker = line.match(/^(?:[-*]|\d+[.)])\s+(.*)$/);
-    if (marker) { current = { text: marker[1].trim(), impact: [] }; options.push(current); continue; }
-    if (current && line !== "") current.impact.push(line);
+  for (const line of sections.slice(1).join("\n## Options\n").split("\n")) {
+    const marker = line.match(/^\s*-\s+(?:\[recommended\]\s*)?(.+?)(?:\s+-\s+(.+))?\s*$/i);
+    if (marker) {
+      current = {
+        text: marker[1].trim(),
+        impact: (marker[2] || "").trim(),
+        recommended: /^\s*-\s+\[recommended\]/i.test(line),
+      };
+      options.push(current);
+      continue;
+    }
+    if (current && /^\s{2,}\S/.test(line)) current.impact = `${current.impact} ${line.trim()}`.trim();
   }
-  return options.map((option) => ({ text: option.text, impact: option.impact.join(" ").slice(0, 800) }));
+  const boundedOptions = options
+    .filter((option) => option.text && option.impact)
+    .slice(0, 20)
+    .map((option) => ({ ...option, text: option.text.slice(0, 300), impact: option.impact.slice(0, 1200) }));
+  if (!context || boundedOptions.length === 0) return null;
+  return {
+    title,
+    context,
+    options: boundedOptions,
+  };
 }
 
 function refDisplayMap(refsFile) {
@@ -275,7 +325,8 @@ function refDisplayMap(refsFile) {
     else if (entry.kind === "item") {
       const separator = entry.value.indexOf("/");
       const owner = entry.value.slice(0, separator);
-      const id = entry.value.slice(separator + 1);
+      const decision = decisionRef(entry);
+      const id = decision ? decision.id : entry.value.slice(separator + 1);
       display[ref] = owner === "decision"
         ? { t: "decision", label: id }
         : { t: "work", label: id, owner };
@@ -291,20 +342,21 @@ function assembleDetail(ref) {
   if (!entry || entry.kind !== "item") return null;
   const separator = entry.value.indexOf("/");
   const owner = entry.value.slice(0, separator);
-  const id = entry.value.slice(separator + 1);
+  const decision = decisionRef(entry);
+  const id = decision ? decision.id : entry.value.slice(separator + 1);
   const backlogItem = parseBacklog().find((item) => item.id === id) || null;
 
   if (owner === "decision") {
-    const body = backlogItem ? backlogItem.body : [];
+    const document = decisionDocument(decision.home, id);
     return {
       type: "decision",
       ref,
       id,
-      title: backlogItem ? backlogItem.title : id,
-      description: body.filter((line) => !/^(?:[-*]|\d+[.)])\s+/.test(line)).join("\n").trim().slice(0, 2000) || null,
-      options: decisionOptions(body),
+      title: document?.title || backlogItem?.title || id,
+      description: document?.context || null,
+      options: document?.options || [],
       recent: statusTail(id),
-      note: backlogItem ? null : "No structured record was found for this decision key; answer it in captain chat.",
+      note: document ? null : "This legacy decision has no structured options document; answer it in captain chat.",
     };
   }
   if (owner !== "main") {
@@ -403,6 +455,75 @@ function runRefresh() {
   return refreshing;
 }
 
+let usageCache = null;
+let usageProbe = null;
+function probeUsage() {
+  const now = Date.now();
+  if (usageCache && now - usageCache.at < QUOTA_CACHE_MS) return Promise.resolve(usageCache.value);
+  if (usageProbe) return usageProbe;
+  usageProbe = new Promise((resolve) => {
+    const child = spawn(QUOTA_AXI, ["--json"], { cwd: ROOT, env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+    const chunks = [];
+    let size = 0;
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      usageCache = { at: Date.now(), value };
+      usageProbe = null;
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish({ status: "unavailable", providers: [] });
+    }, QUOTA_TIMEOUT_MS);
+    child.stdout.on("data", (chunk) => {
+      size += chunk.length;
+      if (size <= 1024 * 1024) chunks.push(chunk);
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      finish({ status: "unavailable", providers: [] });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0 || size > 1024 * 1024) {
+        finish({ status: "unavailable", providers: [] });
+        return;
+      }
+      try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (parsed.schemaVersion !== 2 || !Array.isArray(parsed.providers)) throw new Error("unsupported schema");
+        const allowed = new Set(["claude", "codex", "grok"]);
+        const providers = parsed.providers
+          .filter((provider) => allowed.has(provider?.provider))
+          .map((provider) => ({
+            provider: provider.provider,
+            label: typeof provider.label === "string" ? provider.label.slice(0, 80) : provider.provider,
+            windows: Array.isArray(provider.windows)
+              ? provider.windows.filter((window) =>
+                typeof window?.label === "string"
+                && Number.isFinite(window.percentUsed)
+                && window.percentUsed >= 0
+                && window.percentUsed <= 100
+                && typeof window.resetsAt === "string"
+                && Number.isFinite(Date.parse(window.resetsAt))
+              ).slice(0, 8).map((window) => ({
+                label: window.label.slice(0, 100),
+                percentUsed: window.percentUsed,
+                resetsAt: window.resetsAt,
+              }))
+              : [],
+          }));
+        finish({ status: "ok", providers });
+      } catch {
+        finish({ status: "unavailable", providers: [] });
+      }
+    });
+  });
+  return usageProbe;
+}
+
 function sendJson(res, status, payload) {
   const body = JSON.stringify(payload);
   res.writeHead(status, { "content-type": "application/json; charset=utf-8", "content-length": Buffer.byteLength(body) });
@@ -424,6 +545,18 @@ function authorized(req, config) {
   return login !== "" && config.logins.includes(login);
 }
 
+function sameOriginPost(req) {
+  const origin = req.headers.origin;
+  const fetchSite = req.headers["sec-fetch-site"];
+  if (origin === undefined && fetchSite === undefined) return true;
+  if (typeof origin !== "string" || fetchSite !== "same-origin") return false;
+  try {
+    return new URL(origin).host === req.headers.host;
+  } catch {
+    return false;
+  }
+}
+
 function inlineScriptJson(value) {
   return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (character) => {
     const escapes = { "<": "\\u003c", ">": "\\u003e", "&": "\\u0026", "\u2028": "\\u2028", "\u2029": "\\u2029" };
@@ -444,6 +577,7 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
     readOnly: readOnly === true,
     refs: extras?.refs || {},
     ideas: extras?.ideas || [],
+    usage: extras?.usage || { status: "unavailable", providers: [] },
   });
   return `<style>
   .fmdash-bar{display:flex;justify-content:space-between;align-items:center;gap:.6rem 1.5rem;flex-wrap:wrap;padding:.6rem clamp(1rem,6vw,5rem);border-bottom:1px solid var(--line);background:var(--bg)}
@@ -469,6 +603,17 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
   .fmdash-option strong{color:var(--ink);font-size:.95rem}
   .fmdash-option small{display:block;color:var(--muted);margin-top:.25rem}
   .fmdash-close{border:1px solid var(--ink);background:transparent;color:var(--ink);font-weight:700;padding:.4rem .8rem;cursor:pointer;font-size:.78rem}
+  .fmdash-usage{border-top:1px solid var(--line);border-bottom:1px solid var(--line)}
+  .fmdash-usage-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:1rem;margin-top:1rem}
+  .fmdash-usage-card{min-width:0;border-top:.45rem solid var(--blue);padding:.8rem 0}
+  .fmdash-usage-card h3{font-size:.76rem;letter-spacing:.14em;text-transform:uppercase}
+  .fmdash-window{margin-top:.7rem}
+  .fmdash-window-head{display:flex;justify-content:space-between;gap:.8rem;font-size:.8rem;color:var(--ink2)}
+  .fmdash-meter{height:.65rem;background:var(--hair);margin-top:.3rem}
+  .fmdash-meter span{display:block;height:100%;background:var(--blue)}
+  .fmdash-reset{font-size:.72rem;color:var(--muted);margin-top:.25rem}
+  .fmdash-custom{width:100%;margin-top:.7rem;padding:.6rem;background:var(--bg);color:var(--ink);border:1px solid var(--hair)}
+  @media(max-width:760px){.fmdash-usage-grid{grid-template-columns:1fr}}
   </style>
   <script>
   (() => {
@@ -500,6 +645,64 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
       } catch { refreshButton.textContent = "Refresh failed"; }
       setTimeout(() => { refreshButton.disabled = false; refreshButton.textContent = "Refresh capacity"; }, 4000);
     });
+    const postJson = (body) => fetch("/api/dispatch", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    const usageSection = document.createElement("section");
+    usageSection.className = "band fmdash-usage";
+    usageSection.setAttribute("aria-label", "Subscription usage");
+    const usageWrap = document.createElement("div");
+    usageWrap.className = "wrap";
+    usageWrap.innerHTML = '<p class="kicker">Subscription usage</p>';
+    const usageGrid = document.createElement("div");
+    usageGrid.className = "fmdash-usage-grid";
+    const distance = (iso) => {
+      const milliseconds = Date.parse(iso) - Date.now();
+      if (milliseconds <= 0) return "reset due";
+      const minutes = Math.ceil(milliseconds / 60000);
+      if (minutes < 60) return "resets in " + minutes + "m";
+      const hours = Math.ceil(minutes / 60);
+      if (hours < 48) return "resets in " + hours + "h";
+      return "resets in " + Math.ceil(hours / 24) + "d";
+    };
+    if (cfg.usage.status === "ok" && cfg.usage.providers.some((provider) => provider.windows.length)) {
+      cfg.usage.providers.forEach((provider) => {
+        if (!provider.windows.length) return;
+        const card = document.createElement("article");
+        card.className = "fmdash-usage-card";
+        card.appendChild(textBlock("h3", provider.label));
+        provider.windows.forEach((window) => {
+          const item = document.createElement("div");
+          item.className = "fmdash-window";
+          const head = document.createElement("div");
+          head.className = "fmdash-window-head";
+          head.appendChild(textBlock("span", window.label));
+          head.appendChild(textBlock("strong", Math.round(window.percentUsed) + "% used"));
+          const meter = document.createElement("div");
+          meter.className = "fmdash-meter";
+          const fill = document.createElement("span");
+          fill.style.width = window.percentUsed + "%";
+          meter.appendChild(fill);
+          const reset = textBlock("div", distance(window.resetsAt) + " · " + new Date(window.resetsAt).toLocaleString());
+          reset.className = "fmdash-reset";
+          item.appendChild(head);
+          item.appendChild(meter);
+          item.appendChild(reset);
+          card.appendChild(item);
+        });
+        usageGrid.appendChild(card);
+      });
+    } else {
+      usageGrid.appendChild(textBlock("p", "Subscription usage is temporarily unavailable."));
+    }
+    usageWrap.appendChild(usageGrid);
+    usageSection.appendChild(usageWrap);
+    const meterBand = document.querySelector(".band-meter");
+    const mainForUsage = document.querySelector("main");
+    if (meterBand) meterBand.after(usageSection);
+    else if (mainForUsage) mainForUsage.appendChild(usageSection);
     // De-anonymize known references for the authenticated captain and open
     // rich detail views on click. The server refuses detail and approval
     // requests it cannot validate, so this layer is presentation only.
@@ -561,11 +764,7 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
       button.disabled = true;
       button.textContent = "Sending…";
       try {
-        const res = await fetch("/api/dispatch", {
-          method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ ref, option: index }),
-        });
+        const res = await postJson({ ref, option: index });
         const out = await res.json();
         if (out.status === "queued" || out.status === "already-queued") {
           button.textContent = "Approved · queued";
@@ -576,6 +775,21 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
         button.disabled = false;
       } catch { button.textContent = "Failed"; button.disabled = false; }
     }
+    async function answerDecision(ref, answer, button) {
+      button.disabled = true;
+      button.textContent = "Sending…";
+      try {
+        const res = await postJson({ ref, answer });
+        const out = await res.json();
+        if (out.status === "queued" || out.status === "already-queued") {
+          button.textContent = "Answer queued";
+          showPending(out.pending);
+          return;
+        }
+        button.textContent = "Refused";
+      } catch { button.textContent = "Failed"; }
+      button.disabled = false;
+    }
     async function openDetail(ref, entry) {
       const overlay = document.createElement("div");
       overlay.className = "fmdash-overlay";
@@ -633,7 +847,7 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
           row.className = "fmdash-option";
           const body = document.createElement("div");
           const label = document.createElement("strong");
-          label.textContent = option.text;
+          label.textContent = option.recommended ? "Recommended · " + option.text : option.text;
           body.appendChild(label);
           if (option.impact) {
             const impact = document.createElement("small");
@@ -653,6 +867,23 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
           panel.appendChild(row);
         });
         if (!cfg.readOnly) panel.appendChild(textBlock("p", "An approval here is your routine decision only; anything destructive or irreversible still gets re-confirmed with you in chat."));
+        if (!cfg.readOnly) {
+          const custom = document.createElement("textarea");
+          custom.className = "fmdash-custom";
+          custom.rows = 4;
+          custom.maxLength = 2000;
+          custom.placeholder = "Or give firstmate a custom answer…";
+          custom.setAttribute("aria-label", "Custom answer for " + detail.id);
+          const sendCustom = document.createElement("button");
+          sendCustom.type = "button";
+          sendCustom.className = "fmdash-send";
+          sendCustom.textContent = "Send custom answer";
+          sendCustom.addEventListener("click", () => {
+            if (custom.value.trim()) answerDecision(ref, custom.value.trim(), sendCustom);
+          });
+          panel.appendChild(custom);
+          panel.appendChild(sendCustom);
+        }
       } else if (detail.type === "decision") {
         panel.appendChild(textBlock("p", "This decision has no structured options on record; answer it in chat."));
       }
@@ -706,13 +937,9 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
       const original = button.textContent;
       button.textContent = "Sending…";
       try {
-        const res = await fetch("/api/dispatch", {
-          method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ idea: id, verdict, suggestion }),
-        });
+        const res = await postJson({ idea: id, verdict, suggestion });
         const out = await res.json();
-        if (out.status === "queued" || out.status === "already-queued") {
+        if (out.status === "queued" || out.status === "replaced" || out.status === "already-queued") {
           button.textContent = verdict === "suggest" ? "Suggestions sent" : (verdict === "approve" ? "Approved · queued" : "Denied · queued");
           showPending(out.pending);
           return true;
@@ -827,11 +1054,7 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
         send.disabled = true;
         send.textContent = "Sending…";
         try {
-          const res = await fetch("/api/dispatch", {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ id }),
-          });
+          const res = await postJson({ id });
           const out = await res.json();
           if (out.status === "queued" || out.status === "already-queued") {
             send.textContent = "Approved · queued";
@@ -888,6 +1111,10 @@ async function handle(req, res) {
     sendJson(res, 403, { status: "forbidden", error: "tailnet identity is not an authorized captain login" });
     return;
   }
+  if (req.method === "POST" && !sameOriginPost(req)) {
+    sendJson(res, 403, { status: "forbidden", error: "cross-origin browser posts are refused" });
+    return;
+  }
   if (req.method === "GET" && url.pathname === "/") {
     const dashboard = readDashboard();
     if (!dashboard) {
@@ -897,9 +1124,11 @@ async function handle(req, res) {
     }
     const dispatchable = config.readOnly ? [] : [...dashboard.actions.keys()].filter((id) => ONE_CLICK_ACTIONS.has(id));
     const refsFile = readRefs(dashboard.generated);
+    const usage = await probeUsage();
     const layer = interactiveLayer(dispatchable, pendingRecords().length, dashboard.generated, config.readOnly, {
       refs: refsFile ? refDisplayMap(refsFile) : {},
       ideas: parseIdeas().map((idea) => ({ id: idea.id, title: idea.title })),
+      usage,
     });
     sendHtml(res, 200, dashboard.html.replace("</body>", `${layer}</body>`));
     return;
@@ -953,11 +1182,15 @@ async function handle(req, res) {
         sendJson(res, 400, { status: "refused", error: "approval accepts a currently listed decision only" });
         return;
       }
-      const option = detail.options?.[body.option];
-      if (!option) {
+      const customAnswer = typeof body.answer === "string" ? body.answer.trim() : "";
+      const hasOption = Number.isInteger(body.option)
+        && body.option >= 0
+        && body.option < detail.options.length;
+      if (!hasOption && (!customAnswer || customAnswer.length > 2000 || detail.options.length === 0)) {
         sendJson(res, 400, { status: "refused", error: "the chosen option is not on the decision's record" });
         return;
       }
+      const option = hasOption ? detail.options[body.option] : null;
       const pending = pendingRecords();
       if (pending.some((record) => record.kind === "decision" && record.decision_key === detail.id)) {
         sendJson(res, 200, { status: "already-queued", pending: pending.length });
@@ -968,10 +1201,13 @@ async function handle(req, res) {
         kind: "decision",
         id: body.ref,
         decision_key: detail.id,
-        option_text: option.text,
+        option_text: option?.text || null,
+        custom_answer: option ? null : customAnswer,
         requested_by: requesterLogin(req),
         requested_at: new Date().toISOString(),
-        prompt: `Captain approved decision ${detail.id}: choose "${option.text}". Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`,
+        prompt: option
+          ? `Captain approved decision ${detail.id}: choose "${option.text}". Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`
+          : `Captain answered decision ${detail.id}: ${customAnswer}. Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`,
       };
       const name = enqueueCommand(record);
       log(`queued decision ${detail.id} as ${name} for ${record.requested_by}`);
@@ -993,13 +1229,16 @@ async function handle(req, res) {
         sendJson(res, 404, { status: "refused", error: `${body.idea} is not in the idea backlog` });
         return;
       }
-      const suggestion = verdict === "suggest" ? String(body.suggestion || "").trim().slice(0, 2000) : null;
-      if (verdict === "suggest" && !suggestion) {
+      const suggestion = verdict === "suggest" && typeof body.suggestion === "string" ? body.suggestion.trim() : null;
+      if (verdict === "suggest" && (!suggestion || suggestion.length > 2000)) {
         sendJson(res, 400, { status: "refused", error: "suggestions need text" });
         return;
       }
       const pending = pendingRecords();
-      if (verdict !== "suggest" && pending.some((record) => record.kind === "idea" && record.idea === idea.id && record.verdict === verdict)) {
+      const priorVerdict = verdict === "suggest"
+        ? null
+        : pending.find((record) => record.kind === "idea" && record.idea === idea.id && record.verdict !== "suggest");
+      if (priorVerdict?.verdict === verdict) {
         sendJson(res, 200, { status: "already-queued", pending: pending.length });
         return;
       }
@@ -1015,9 +1254,9 @@ async function handle(req, res) {
         requested_at: new Date().toISOString(),
         prompt: `Captain ${verbs[verdict]} idea ${idea.id} (${idea.title}).${suggestion ? ` Captain suggestion text: ${suggestion}` : ""}${verdict === "approve" ? " Create the follow-up work item(s) through the normal backlog lifecycle." : ""}`,
       };
-      const name = enqueueCommand(record);
+      const name = priorVerdict ? replaceCommand(priorVerdict._file, record) : enqueueCommand(record);
       log(`queued idea ${idea.id} ${verdict} as ${name} for ${record.requested_by}`);
-      sendJson(res, 200, { status: "queued", pending: pending.length + 1 });
+      sendJson(res, 200, { status: priorVerdict ? "replaced" : "queued", pending: pending.length + (priorVerdict ? 0 : 1) });
       return;
     }
 
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index a2584727693..8378b879ceb 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -10,9 +10,10 @@ The service publishes the producer-generated `data/capacity-dashboard.html` at o
 - Every current one-click-eligible `CAP-NN` action gets an "Approve & send" button.
 - A "Refresh capacity" button reruns `bin/fm-capacity.mjs` server-side and reloads the page; the producer also reruns automatically on the configured interval so the page never goes stale.
 - The page is de-anonymized for the authenticated captain: opaque `item-NN`/`project-NN`/`home-NN` references become real names, and work items and decisions are clickable rich detail views (description, test plan, PR link, tailnet preview links, report excerpt, recent activity) assembled from task briefs, recorded metadata, the backlog, and scout reports.
-- Open decisions show each recorded option with its impact, and every option carries an Approve button.
+- Open decisions with `data/decisions/<key>.md` records show each recorded option with its impact, a per-option Approve button, and a bounded custom-answer control.
 - An Ideas section renders `data/ideas/idea-backlog.md`; each idea opens its pitch (`data/ideas/pitches/IDEA-XX.md` when present, else the concept summary) with Approve, Deny, and Add-suggestions controls.
 - A service bar shows how many captain commands are queued for firstmate.
+- A Subscription usage band shows cached `quota-axi --json` windows for Claude, Codex, and Grok, including percent used and reset distance with reset time formatted by the captain's browser in local time.
 
 `bin/fm-capacity.mjs` remains the single owner of the dashboard's content and look; the service injects its interactive layer at serve time and never modifies the file on disk, so the file keeps working offline exactly as before.
 The on-disk dashboard stays identity-opaque: the producer's opt-in `--refs` sidecar (`state/dash-refs.json`, `fm-capacity-refs.v1`, mode 0600) carries the opaque-to-real mapping, and only the captain-authenticated service reads it to enrich the served page.
@@ -23,7 +24,7 @@ The on-disk dashboard stays identity-opaque: the producer's opt-in `--refs` side
 - `bin/fm-dash-install.sh` - launchd agent (`RunAtLoad` + `KeepAlive`, so it survives reboots and crashes), `tailscale serve` mapping, `config/dash.json`, and the registered `fm-dash` watcher check.
 - `state/dash-inbox/` - durable captain command records (`fm-dash-command.v1`), one file per clicked action.
 - `state/fm-dash.check.sh` - watcher check registered through `bin/fm-check-register.sh`; prints one line while commands are pending so the watcher wakes firstmate.
-- `bin/fm-dash-inbox.sh` - firstmate's list/claim helper; claim archives each record under `state/dash-inbox/archive/` so a command is surfaced exactly once.
+- `bin/fm-dash-inbox.sh` - firstmate's list/claim helper; claim prints each record before archiving it under `state/dash-inbox/archive/`, so an interruption may re-surface a command but cannot silently lose one.
 
 ## Inbound command channel
 
@@ -41,6 +42,7 @@ Consequences of that shape:
 - Delivery is durable: a click made while firstmate is down waits in the inbox and is delivered on the next watcher cycle or session start sweep of pending checks.
 - Delivery latency is the watcher check cadence, not instantaneous; the page says "queued for firstmate" honestly rather than pretending immediacy.
 - Commands survive service restarts, firstmate restarts, and reboots because the inbox is plain durable state.
+- Consumption is at-least-once across an interruption between delivery and archive, so Firstmate must apply normal idempotency checks when handling a re-surfaced record.
 
 ## Trust design
 
@@ -48,19 +50,45 @@ Identity is enforced at every layer that can fail:
 
 - `tailscale serve` terminates HTTPS on the tailnet and injects the `Tailscale-User-Login` header for the authenticated tailnet peer; Funnel traffic would carry no such identity.
 - The service refuses every route except `/healthz` unless that header matches a login in `config/dash.json` (`captain_logins`, recorded from the tailnet self login at install time or passed with `--captain`).
+- Authenticated browser POSTs must also carry a matching Origin and `Sec-Fetch-Site: same-origin`; headerless same-machine clients remain allowed because a local process is already inside the filesystem trust boundary.
 - With no configured captain login the service serves only a setup notice and refuses everything else.
 - The service binds 127.0.0.1, so the only remote path in is the tailscale proxy; a local process on the captain's machine is already inside the trust boundary because it could write `FM_HOME` state directly.
 
 Dispatch is validated against records the server itself reads:
 
 - A `CAP-NN` request must currently be recommended by the served dashboard itself AND sit in the service's fixed one-click allowlist of reviewed lifecycle-safe actions; unknown or future IDs are refused with guidance to raise them in captain chat, so new actions default to chat-only.
-- A decision approval must name a decision in the producer's refs sidecar, and the chosen option must be one the server just parsed from that decision's structured backlog record; an off-record option is refused.
+- A decision answer must name a decision in the producer's current-generation refs sidecar, and its integer option index must match the options document the server just parsed; a custom answer is accepted only for a decision with that document and is bounded to 2,000 characters.
 - An idea verdict must name an idea currently listed in `data/ideas/idea-backlog.md` and one of the approve, deny, or suggest verbs; on approval, firstmate creates the work item(s) through the normal backlog lifecycle - the service itself never creates work.
-- The only free text accepted anywhere is the bounded add-suggestions note on an idea, which is captain-authored data for firstmate (the tailnet identity check makes it genuinely the captain), never a command the service interprets or executes.
+- The only free text accepted is a bounded idea-suggestion note or decision custom answer, which is captain-authored data for firstmate, never a command the service interprets or executes.
+- A newer approve or deny verdict atomically replaces the pending verdict for the same idea, while suggestions remain additive.
 - Destructive, irreversible, and security-sensitive choices stay in captain chat structurally: no current `CAP-NN` prompt grants such authority, the capacity skill forbids treating a dashboard approval as merge or discard authority, decision records carry an explicit re-confirm-in-chat boundary for destructive consequences, and firstmate re-resolves every claimed command through the normal lifecycle before acting.
 
+## Decision options document
+
+The home that owns a decision writes `data/decisions/<key>.md`, where `<key>` is the stable decision key carried by the refs sidecar even when it is not a backlog item ID.
+The document is producer-owned decision data and uses this format:
+
+```markdown
+# Choose the rollout policy
+
+Explain the decision context and constraints here.
+
+## Options
+
+- [recommended] Conservative rollout - Slower delivery with the lowest regression risk.
+- Fast rollout - Reaches everyone this week with higher regression risk.
+```
+
+The first level-one heading is the title, prose before `## Options` is context, and each option is one bullet with an optional `[recommended]` marker followed by ` - ` and its impact.
+Indented continuation lines extend the preceding impact.
+The service accepts at most 20 options and applies bounded text limits while rendering.
+Firstmate and workers create this document in the deciding home when filing a new decision.
+Legacy decisions without the document remain visible but route the captain to answer in chat.
+In v1, a secondmate-owned work item deliberately shows only a limited ownership note because the main service does not ingest rich task records across home boundaries.
+
 Funnel is never acceptable for this surface.
 The installer only ever creates a plain `tailscale serve` mapping, verifies after configuring that no Funnel exposure exists for the served port, and tears the mapping back down and refuses if one is found.
+Unreadable, malformed, or schema-unexpected `tailscale serve status --json` output is a verification failure and triggers the same teardown.
 
 ## Setup and removal
 
@@ -81,5 +109,5 @@ On a non-macOS host the installer refuses and the service can be run under the l
 ## Verification evidence
 
 2026-07-28, macOS 15.6, node v26.5.0, tailscale CLI present at /opt/homebrew/bin/tailscale.
-`bash tests/fm-dash.test.sh` passed end to end against a live local service instance: identity-less and wrong-identity requests got 403 with no inbox write; an authorized dispatch wrote exactly one mode-0600 `fm-dash-command.v1` record and a duplicate click coalesced; free-text, non-allowlisted (`CAP-99`), and not-currently-recommended IDs were refused; `/api/refresh` regenerated the dashboard through the real producer; claim archived and printed each record exactly once; the registered check shim printed one line only while commands were pending; and the rendered plist carried `RunAtLoad`, `KeepAlive`, the pinned `FM_HOME`, and no Funnel reference.
+`bash tests/fm-dash.test.sh` passed end to end against a live local service instance: identity-less and wrong-identity requests got 403 with no inbox write; cross-origin browser posts were refused; an authorized dispatch wrote one mode-0600 `fm-dash-command.v1` record; decision documents, custom answers, newest-verdict replacement, usage filtering, and blocked chains were exercised; `/api/refresh` regenerated the dashboard through the real producer; claim delivered before archive and safely replayed after a simulated archive failure; the registered check shim printed one line only while commands were pending; and the rendered plist carried `RunAtLoad`, `KeepAlive`, the pinned `FM_HOME`, and no Funnel reference.
 The launchd bootstrap and live `tailscale serve` mapping mutate the host machine and were not exercised from the isolated task worktree; run `bin/fm-dash-install.sh install` once on the target machine and confirm `status` shows the agent loaded, the serve mapping present, and `tailscale serve status` showing no Funnel line for the port.
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index ebb5e224233..0398916bfd7 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -11,6 +11,7 @@ INBOX_SH="$ROOT/bin/fm-dash-inbox.sh"
 INSTALL_SH="$ROOT/bin/fm-dash-install.sh"
 CAPACITY="$ROOT/bin/fm-capacity.mjs"
 TMP_ROOT=$(fm_test_tmproot fm-dash)
+QUOTA_STUB="$TMP_ROOT/quota-axi"
 
 command -v node >/dev/null 2>&1 || { echo "skip: node not found"; exit 0; }
 command -v curl >/dev/null 2>&1 || { echo "skip: curl not found"; exit 0; }
@@ -37,11 +38,15 @@ make_fixture() {
     "path": "$home/data/backlog.md",
     "present": true,
     "records": [
+      {"order":0,"state":"in_flight","structured":true,"id":"active-task","title":"Run the active rollout","repo":"alpha","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: rollout remains observable."},
       {"order":1,"state":"queued","structured":true,"id":"ready-safe","title":"Ship the gamma feature","repo":"gamma","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: bounded regression tests pass."},
-      {"order":2,"state":"queued","structured":true,"id":"captain-choice","title":"Choose the rollout policy","repo":"alpha","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"pick conservative or fast rollout"}
+      {"order":2,"state":"queued","structured":true,"id":"captain-choice","title":"Choose the rollout policy","repo":"alpha","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"pick conservative or fast rollout"},
+      {"order":3,"state":"queued","structured":true,"id":"blocked-child","title":"Ship after rollout choice","repo":"alpha","project_resolved":true,"kind":"ship","blocked_by":"captain-choice","body_excerpt":"Acceptance criteria: follows the selected rollout."}
     ]
   },
-  "tasks": [],
+  "tasks": [
+    {"id":"active-task","kind":"ship","project":"alpha","current_state":{"state":"working","source":"pane","detail":"running rollout"},"endpoint":{"exists":true},"hints":{"open_decisions":[{"key":"runtime-policy"}]},"pr":{"url":null},"paths":{"report":{"present":false}},"backlog":{"id":"active-task","title":"Run the active rollout","repo":"alpha","project_resolved":true,"kind":"ship"}}
+  ],
   "scout_reports": [],
   "secondmate_current": {"registry":{"available":true,"complete":true,"records":[]},"records":[],"total":0,"shown":0,"truncated":0},
   "secondmate_landed": {"records":[],"truncated":[],"unreadable":[]}
@@ -59,6 +64,8 @@ EOF
 EOF
   cat > "$home/data/backlog.md" <<'EOF'
 ## In flight
+- [ ] active-task - Run the active rollout (repo: alpha) (kind: ship)
+  Acceptance criteria: rollout remains observable.
 
 ## Queued
 - [ ] ready-safe - Ship the gamma feature (repo: gamma) (kind: ship)
@@ -67,10 +74,12 @@ EOF
   Pick the alpha rollout pace before dependent work starts.
   - Conservative rollout: slower, safest for existing users
   - Fast rollout: reaches everyone this week, higher regression risk
+- [ ] blocked-child - Ship after rollout choice (repo: alpha) (kind: ship) (blocked-by: captain-choice)
+  Acceptance criteria: follows the selected rollout.
 
 ## Done
 EOF
-  mkdir -p "$home/data/ready-safe" "$home/data/ideas/pitches"
+  mkdir -p "$home/data/ready-safe" "$home/data/ideas/pitches" "$home/data/decisions"
   cat > "$home/data/ready-safe/brief.md" <<'EOF'
 # Task
 Ship the gamma feature so gamma users get streaming exports.
@@ -93,6 +102,26 @@ New crew homes should self-provision in one command.
 Send the captain a nightly fleet digest.
 EOF
   printf '# Faster onboarding pitch\n\nOne command provisions a ready home.\n' > "$home/data/ideas/pitches/IDEA-01.md"
+  cat > "$home/data/decisions/captain-choice.md" <<'EOF'
+# Choose the rollout policy
+
+Pick the alpha rollout pace before dependent work starts.
+
+## Options
+
+- [recommended] Conservative rollout - Slower delivery with the lowest regression risk.
+- Fast rollout - Reaches everyone this week with higher regression risk.
+EOF
+  cat > "$home/data/decisions/runtime-policy.md" <<'EOF'
+# Choose the runtime policy
+
+Choose how the active rollout should continue.
+
+## Options
+
+- [recommended] Conservative rollout - Slower delivery with the lowest regression risk.
+- Fast rollout - Reaches everyone this week with higher regression risk.
+EOF
 }
 
 write_config() {
@@ -108,7 +137,7 @@ pick_port() {
 
 start_server() {
   local home=$1 port=$2 fixture_args=${3:-}
-  FM_HOME="$home" FM_DASH_CAPACITY_ARGS="$fixture_args" node "$SERVE" --port "$port" > "$TMP_ROOT/serve.log" 2>&1 &
+  FM_HOME="$home" FM_DASH_CAPACITY_ARGS="$fixture_args" FM_DASH_QUOTA_AXI="$QUOTA_STUB" node "$SERVE" --port "$port" > "$TMP_ROOT/serve.log" 2>&1 &
   SERVER_PID=$!
   local tries=0
   while ! curl -sf "http://127.0.0.1:$port/healthz" >/dev/null 2>&1; do
@@ -139,6 +168,11 @@ HOME_DIR="$TMP_ROOT/home"
 SNAPSHOT="$TMP_ROOT/snapshot.json"
 ENVIRONMENT="$TMP_ROOT/environment.json"
 make_fixture "$HOME_DIR" "$SNAPSHOT" "$ENVIRONMENT"
+cat > "$QUOTA_STUB" <<'EOF'
+#!/bin/sh
+printf '%s\n' '{"schemaVersion":2,"providers":[{"provider":"claude","label":"Claude","windows":[{"label":"session","percentUsed":42,"resetsAt":"2026-07-29T10:00:00Z"}]},{"provider":"codex","label":"Codex","windows":[{"label":"week","percentUsed":61,"resetsAt":"2026-08-01T10:00:00Z"}]},{"provider":"grok","label":"Grok","windows":[{"label":"credits","percentUsed":7,"resetsAt":"2026-07-30T10:00:00Z"}]},{"provider":"cursor","label":"Cursor","windows":[{"label":"month","percentUsed":99,"resetsAt":"2026-08-28T10:00:00Z"}]}]}'
+EOF
+chmod 700 "$QUOTA_STUB"
 FM_HOME="$HOME_DIR" "$CAPACITY" --snapshot "$SNAPSHOT" --environment "$ENVIRONMENT" \
   --output "$HOME_DIR/data/capacity-dashboard.html" --refs "$HOME_DIR/state/dash-refs.json" >/dev/null \
   || fail "could not render the fixture dashboard with its refs sidecar"
@@ -163,6 +197,35 @@ test_identity_fails_closed() {
   pass "every route except healthz requires the configured captain identity"
 }
 
+test_browser_posts_require_same_origin() {
+  REQ_STATUS=$(curl -s -o "$TMP_ROOT/resp.body" -w '%{http_code}' -X POST \
+    -H "Tailscale-User-Login: $CAPTAIN" \
+    -H 'Origin: https://evil.example' \
+    -H 'Sec-Fetch-Site: cross-site' \
+    -H 'content-type: application/json' \
+    -d '{"id":"CAP-06"}' \
+    "http://127.0.0.1:$PORT/api/dispatch")
+  [ "$REQ_STATUS" = 403 ] || fail "cross-site browser dispatch was not refused (got $REQ_STATUS)"
+  REQ_STATUS=$(curl -s -o "$TMP_ROOT/resp.body" -w '%{http_code}' -X POST \
+    -H "Tailscale-User-Login: $CAPTAIN" \
+    -H 'Sec-Fetch-Site: same-origin' \
+    -H 'content-type: application/json' \
+    -d '{"id":"CAP-06"}' \
+    "http://127.0.0.1:$PORT/api/dispatch")
+  [ "$REQ_STATUS" = 403 ] || fail "browser dispatch without Origin was not refused (got $REQ_STATUS)"
+  REQ_STATUS=$(curl -s -o "$TMP_ROOT/resp.body" -w '%{http_code}' -X POST \
+    -H "Tailscale-User-Login: $CAPTAIN" \
+    -H "Origin: http://127.0.0.1:$PORT" \
+    -H 'Sec-Fetch-Site: same-origin' \
+    -H 'content-type: application/json' \
+    -d '{"id":"CAP-02"}' \
+    "http://127.0.0.1:$PORT/api/dispatch")
+  [ "$REQ_STATUS" = 409 ] || fail "same-origin browser dispatch did not reach normal validation (got $REQ_STATUS)"
+  [ -z "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*.json' 2>/dev/null)" ] \
+    || fail "refused browser dispatch wrote an inbox record"
+  pass "authenticated browser posts require a matching same origin"
+}
+
 test_served_page_wears_dashboard_with_interactive_layer() {
   local body
   req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
@@ -173,9 +236,29 @@ test_served_page_wears_dashboard_with_interactive_layer() {
   assert_contains "$RESP" 'data-copy' "producer copy layer was lost in serving"
   assert_contains "$RESP" '"ready-safe"' "served page config lacks the de-anonymized work item id"
   assert_contains "$RESP" 'IDEA-01' "served page config lacks the idea backlog"
+  assert_contains "$RESP" 'postJson({ id })' "served prompt actions still require copy-paste"
+  assert_contains "$RESP" 'Blocked by item-' "served dashboard does not render the blocked dependency chain"
   pass "served page is the producer dashboard wearing the injected interactive layer"
 }
 
+test_subscription_usage_panel() {
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  assert_contains "$RESP" 'Subscription usage' "served page lacks the subscription usage panel"
+  assert_contains "$RESP" '"label":"Claude"' "usage panel lacks Claude"
+  assert_contains "$RESP" '"label":"Codex"' "usage panel lacks Codex"
+  assert_contains "$RESP" '"label":"Grok"' "usage panel lacks Grok"
+  assert_not_contains "$RESP" '"label":"Cursor"' "usage panel included a forbidden provider"
+  assert_contains "$RESP" 'percentUsed":42' "usage panel lacks percent-used data"
+  assert_contains "$RESP" 'toLocaleString()' "usage reset time is not rendered in the captain local timezone"
+  assert_contains "$RESP" 'resets in ' "usage panel lacks reset-distance rendering"
+  stop_server
+  rm -f "$QUOTA_STUB"
+  start_server "$HOME_DIR" "$PORT"
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  assert_contains "$RESP" '"usage":{"status":"unavailable","providers":[]}' "missing quota-axi did not degrade gracefully"
+  pass "subscription usage is bounded to Claude, Codex, and Grok"
+}
+
 test_inline_config_is_script_safe() {
   cat >> "$HOME_DIR/data/ideas/idea-backlog.md" <<'EOF'
 
@@ -190,7 +273,7 @@ EOF
 }
 
 ref_for() {
-  # ref_for <kind-owner-prefix> e.g. "main/ready-safe" or "decision/captain-choice"
+  # ref_for <kind-owner-prefix> e.g. "main/ready-safe" or "decision/main/runtime-policy"
   node -e '
     const refs = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).refs;
     const wanted = process.argv[2];
@@ -219,29 +302,46 @@ test_refs_sidecar_and_rich_work_item_detail() {
 
 test_decision_detail_options_and_validated_approval() {
   local ref record
-  ref=$(ref_for "decision/captain-choice") || fail "refs sidecar does not map the decision"
+  ref=$(ref_for "decision/main/runtime-policy") || fail "refs sidecar does not map a non-backlog decision key"
   req GET "http://127.0.0.1:$PORT/api/detail?ref=$ref" "$CAPTAIN"
   [ "$REQ_STATUS" = 200 ] || fail "decision detail failed (got $REQ_STATUS: $RESP)"
   assert_contains "$RESP" 'Conservative rollout' "decision detail lacks its first option"
   assert_contains "$RESP" 'higher regression risk' "decision detail lacks the option impact"
+  assert_contains "$RESP" '"recommended":true' "decision detail lacks its recommended marker"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"option\":7}"
   [ "$REQ_STATUS" = 400 ] || fail "an off-record option was not refused (got $REQ_STATUS)"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"option\":\"length\"}"
+  [ "$REQ_STATUS" = 400 ] || fail "an array property was accepted as an option index (got $REQ_STATUS)"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"option\":\"constructor\"}"
+  [ "$REQ_STATUS" = 400 ] || fail "an inherited property was accepted as an option index (got $REQ_STATUS)"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"option\":0}"
   [ "$REQ_STATUS" = 200 ] || fail "decision approval failed (got $REQ_STATUS: $RESP)"
   record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name "*$ref.json" | head -1)")
   assert_contains "$record" '"decision"' "decision record lacks its kind"
-  assert_contains "$record" 'captain-choice' "decision record lacks the decision key"
+  assert_contains "$record" 'runtime-policy' "decision record lacks the decision key"
   assert_contains "$record" 'Conservative rollout' "decision record lacks the chosen option"
   assert_contains "$record" 'chat confirmation' "decision record lacks the destructive-consequence boundary"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"option\":1}"
   assert_contains "$RESP" 'already-queued' "a second choice for the same decision was not coalesced"
   find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name "*$ref.json" -delete
-  pass "decisions serve option detail and approvals are validated against the record"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"answer\":\"Use a 10% canary for 48 hours\"}"
+  [ "$REQ_STATUS" = 200 ] || fail "custom decision answer failed (got $REQ_STATUS: $RESP)"
+  record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name "*$ref.json" | head -1)")
+  assert_contains "$record" 'Use a 10% canary for 48 hours' "decision record lacks the custom answer"
+  find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name "*$ref.json" -delete
+  mv "$HOME_DIR/data/decisions/runtime-policy.md" "$HOME_DIR/data/decisions/runtime-policy.md.off"
+  req GET "http://127.0.0.1:$PORT/api/detail?ref=$ref" "$CAPTAIN"
+  assert_contains "$RESP" 'legacy decision' "legacy decision does not route to captain chat"
+  assert_contains "$RESP" '"options":[]' "legacy backlog bullets were treated as structured decision options"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"answer\":\"unsafe fallback\"}"
+  [ "$REQ_STATUS" = 400 ] || fail "legacy decision accepted free text without an options document"
+  mv "$HOME_DIR/data/decisions/runtime-policy.md.off" "$HOME_DIR/data/decisions/runtime-policy.md"
+  pass "decision documents validate option picks and bounded custom answers"
 }
 
 test_stale_refs_are_disabled() {
   local ref
-  ref=$(ref_for "decision/captain-choice") || fail "refs sidecar does not map the decision"
+  ref=$(ref_for "decision/main/runtime-policy") || fail "refs sidecar does not map the decision"
   node -e '
     const fs = require("node:fs");
     const file = process.argv[1];
@@ -277,12 +377,21 @@ test_idea_pitch_and_verdicts() {
   record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-01.json' | head -1)")
   assert_contains "$record" '"idea"' "idea record lacks its kind"
   assert_contains "$record" 'normal backlog lifecycle' "idea approval does not route creation through firstmate"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-01","verdict":"deny"}'
+  assert_contains "$RESP" '"replaced"' "newest contradictory idea verdict did not replace the pending verdict"
+  [ "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-01.json' | wc -l | tr -d ' ')" = 1 ] \
+    || fail "verdict replacement left contradictory pending records"
+  record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-01.json' | head -1)")
+  assert_contains "$record" '"verdict": "deny"' "verdict replacement did not retain the newest choice"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-99","verdict":"approve"}'
   [ "$REQ_STATUS" = 404 ] || fail "an unlisted idea was not refused (got $REQ_STATUS)"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-02","verdict":"suggest","suggestion":"scope it to weekdays only"}'
   [ "$REQ_STATUS" = 200 ] || fail "idea suggestion failed (got $REQ_STATUS: $RESP)"
   record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-02.json' | head -1)")
   assert_contains "$record" 'scope it to weekdays only' "suggestion text was not recorded for firstmate"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-02","verdict":"suggest","suggestion":"include landed work"}'
+  [ "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-02.json' | wc -l | tr -d ' ')" = 2 ] \
+    || fail "additive idea suggestions were coalesced"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-02","verdict":"suggest","suggestion":""}'
   [ "$REQ_STATUS" = 400 ] || fail "an empty suggestion was not refused (got $REQ_STATUS)"
   find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-*.json' -delete
@@ -341,12 +450,23 @@ test_refresh_reruns_producer_server_side() {
 }
 
 test_inbox_list_claim_and_archive() {
-  local out
+  local out stub_bin
   out=$(FM_HOME="$HOME_DIR" "$INBOX_SH" pending-count)
   [ "$out" = 1 ] || fail "pending-count expected 1, got: $out"
   out=$(FM_HOME="$HOME_DIR" "$INBOX_SH" list)
   assert_contains "$out" 'CAP-06' "list omits the pending action"
   assert_contains "$out" "$CAPTAIN" "list omits the requesting identity"
+  stub_bin="$TMP_ROOT/failing-mv"
+  mkdir -p "$stub_bin"
+  cat > "$stub_bin/mv" <<'EOF'
+#!/bin/sh
+exit 1
+EOF
+  chmod 700 "$stub_bin/mv"
+  out=$(PATH="$stub_bin:$PATH" FM_HOME="$HOME_DIR" "$INBOX_SH" claim)
+  assert_contains "$out" 'Approve CAP-06' "claim did not deliver before attempting archive"
+  [ -n "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*CAP-06.json' 2>/dev/null)" ] \
+    || fail "failed archive silently removed the delivered command"
   out=$(FM_HOME="$HOME_DIR" "$INBOX_SH" claim)
   assert_contains "$out" 'claimed: 1' "claim did not claim the pending command"
   assert_contains "$out" 'Approve CAP-06' "claim omits the command prompt"
@@ -357,7 +477,7 @@ test_inbox_list_claim_and_archive() {
     || fail "claim did not archive the record"
   out=$(FM_HOME="$HOME_DIR" "$INBOX_SH" claim)
   assert_contains "$out" 'no pending dashboard commands' "second claim re-surfaced the archived command"
-  pass "inbox claim surfaces each command exactly once and archives it durably"
+  pass "inbox claim delivers before archive and safely permits replay"
 }
 
 test_read_only_mode_fails_safe() {
@@ -394,7 +514,7 @@ test_check_shim_wakes_only_when_pending() {
 }
 
 test_installer_plist_and_funnel_stance() {
-  local escaped_home plist
+  local escaped_home funnel_check plist
   plist=$(FM_HOME="$HOME_DIR" "$INSTALL_SH" print-plist) || fail "print-plist failed"
   assert_contains "$plist" 'io.firstmate.dashboard.' "plist lacks the per-home label"
   assert_contains "$plist" 'fm-dash-serve.mjs' "plist does not run the dashboard service"
@@ -405,6 +525,11 @@ test_installer_plist_and_funnel_stance() {
   grep -n 'tailscale funnel' "$INSTALL_SH" && fail "installer invokes tailscale funnel"
   assert_grep 'assert_no_funnel' "$INSTALL_SH" "installer does not verify funnel is off"
   assert_grep 'never enables Funnel' "$INSTALL_SH" "installer does not declare the funnel boundary"
+  funnel_check=$(sed -n '/^assert_no_funnel()/,/^write_config()/p' "$INSTALL_SH")
+  assert_contains "$funnel_check" 'unsupported tailscale serve status schema' "Funnel verification does not reject unexpected schemas"
+  assert_contains "$funnel_check" 'could not verify Funnel state' "Funnel verification does not report unreadable status"
+  assert_contains "$funnel_check" 'process.exit(1)' "Funnel verification does not fail closed"
+  assert_contains "$(sed -n '/if ! assert_no_funnel/,/fi/p' "$INSTALL_SH")" 'serve --https="$serve_port" off' "failed Funnel verification does not tear down the mapping"
   escaped_home="$HOME_DIR/xml & < >"
   plist=$(FM_HOME="$escaped_home" FM_ROOT_OVERRIDE="$HOME_DIR/root & < >" "$INSTALL_SH" print-plist) || fail "print-plist with XML metacharacters failed"
   assert_contains "$plist" "$HOME_DIR/xml &amp; &lt; &gt;" "plist did not XML-escape FM_HOME"
@@ -420,11 +545,15 @@ test_service_contract_docs_and_ownership() {
   assert_grep 'config/dash.json' "$ROOT/.gitignore" "config/dash.json is not gitignored"
   assert_grep 'dashboard service' "$ROOT/.agents/skills/capacity/SKILL.md" "capacity skill does not own dashboard command handling"
   assert_grep 'never Funnel' "$ROOT/.agents/skills/capacity/SKILL.md" "capacity skill does not carry the funnel boundary"
+  assert_grep 'data/decisions/<key>.md' "$ROOT/docs/dashboard-service.md" "service doc does not own the decision-options format"
+  assert_grep 'secondmate-owned work item deliberately shows only a limited ownership note' "$ROOT/docs/dashboard-service.md" "service doc omits the accepted secondmate detail boundary"
   pass "the service is documented and wired into the operating contract"
 }
 
 test_identity_fails_closed
+test_browser_posts_require_same_origin
 test_served_page_wears_dashboard_with_interactive_layer
+test_subscription_usage_panel
 test_inline_config_is_script_safe
 test_refs_sidecar_and_rich_work_item_detail
 test_decision_detail_options_and_validated_approval

From 290aef0f8d1d5f5ac24a9f94e6101d832e2694cd Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 11:20:16 -0400
Subject: [PATCH 04/24] no-mistakes(review): Harden decision routing and
 durable dashboard delivery

---
 .agents/skills/capacity/SKILL.md              |  4 +-
 .../skills/decision-hold-lifecycle/SKILL.md   |  4 +-
 AGENTS.md                                     |  2 +-
 bin/fm-capacity.mjs                           |  7 ++-
 bin/fm-dash-inbox.sh                          | 15 +++--
 bin/fm-dash-serve.mjs                         | 40 ++++++++-----
 bin/fm-decision-hold.sh                       | 51 +++++++++++++++-
 bin/fm-fleet-snapshot.sh                      |  5 +-
 docs/dashboard-service.md                     |  5 +-
 docs/decision-hold-lifecycle.md               |  2 +
 tests/fm-dash.test.sh                         | 58 +++++++++++++++++--
 tests/fm-decision-hold-lifecycle.test.sh      | 56 ++++++++++++++----
 12 files changed, 205 insertions(+), 44 deletions(-)

diff --git a/.agents/skills/capacity/SKILL.md b/.agents/skills/capacity/SKILL.md
index c9eebd26eca..5ee481c665f 100644
--- a/.agents/skills/capacity/SKILL.md
+++ b/.agents/skills/capacity/SKILL.md
@@ -25,7 +25,7 @@ Do not assemble a competing snapshot with ad hoc state reads, GitHub calls, term
 Never infer current state from `state/<id>.status`, because it is append-only wake-event history rather than current-state truth.
 Do not scrape scout reports, browser review artifacts, or Lavish surfaces to discover decisions.
 Structured captain holds and the keyed open-decision fold are the only decision inputs.
-When filing a decision, Firstmate or its worker must write the deciding home's structured options document using the format owned by `docs/dashboard-service.md`.
+Decision filing and its structured options document are owned by the decision-hold lifecycle.
 
 The generated dashboard is a polished, responsive, accessible, self-contained HTML file that works directly from disk.
 Do not invoke, depend on, open, poll, share, or embed Lavish for `/capacity`.
@@ -96,7 +96,7 @@ On a `check:` wake naming `fm-dash.check.sh`, run `bin/fm-dash-inbox.sh claim` a
 Claim delivery is at-least-once across interruption, so check whether a re-surfaced record was already handled before applying it again.
 
 - A `CAP-NN` record is the captain's ordinary chat approval of that action ID under section 4, including its full re-resolution and authority limits.
-- A `decision` record is the captain's answer for the named decision key with either the recorded option text or bounded custom answer; route it through `decision-hold-lifecycle` exactly as a chat answer, and re-confirm in chat before acting when the answer has a destructive or irreversible consequence.
+- A `decision` record is the captain's answer for the owner-qualified decision identity with either the recorded option text or bounded custom answer; route it in `decision_home` through `decision-hold-lifecycle` exactly as a chat answer, and re-confirm in chat before acting when the answer has a destructive or irreversible consequence.
 - An `idea` record is the captain's verdict on the named `data/ideas/` idea: on approve, create the follow-up work item(s) through the normal backlog lifecycle; on deny, record the outcome against the idea; on suggest, treat the suggestion text as captain input on that idea.
 
 A claimed record never authorizes a PR merge, `local-only` landing, destructive action, irreversible action, security-sensitive action, or discard of unlanded work; when a claimed action leads to such a choice, escalate it to captain chat exactly as section 4 requires.
diff --git a/.agents/skills/decision-hold-lifecycle/SKILL.md b/.agents/skills/decision-hold-lifecycle/SKILL.md
index 5db5690ebc9..656ec6ea7c5 100644
--- a/.agents/skills/decision-hold-lifecycle/SKILL.md
+++ b/.agents/skills/decision-hold-lifecycle/SKILL.md
@@ -14,6 +14,8 @@ This skill is the single policy owner for unresolved captain decisions discovere
 
 ## Policy
 
+Before filing a new decision, author its title, context, options, and per-option impacts in the format owned by `docs/dashboard-service.md`, then pass that file to `bin/fm-decision-hold.sh hold --options-file`; legacy holds that already exist without a document remain answer-in-chat decisions.
+
 Every unresolved decision that belongs to the captain and is discovered while producing, reading, presenting, or ending an investigation or visual review must become a structured captain-held work item in the authoritative backlog of the home that owns the originating work before that work or review may be treated as complete.
 The agent performs the semantic inventory because scripts must not infer decisions from report prose, visual-review artifacts, terminal output, or chat.
 Give each distinct unresolved decision a stable privacy-safe key, register it through `bin/fm-decision-hold.sh hold`, and use the same key on retry so registration is idempotent while different decisions retain different durable identities.
@@ -29,7 +31,7 @@ Bearings reads the resulting structured state and must never compensate by scrap
 
 1. Read the complete investigation result and complete the visual review before declaring either complete.
 2. Inventory only genuine unresolved choices that require the captain.
-3. For each choice, choose a stable key and use the script's `hold` command with a concise title, reason, and repository.
+3. For each choice, choose a stable key, author its options document, and use the script's `hold --options-file` command with a concise title, reason, and repository.
 4. Run the script's `complete` command with the full unresolved-key inventory for that review pass.
 5. Relay the choices to the captain as decisions from Bearings' Captain's Call section under `AGENTS.md` section 9; do not use the word hold in captain chat.
 6. After the captain decides, record dependent work with normal tasks-axi commands and block it by the hold identity.
diff --git a/AGENTS.md b/AGENTS.md
index 8ac15b6ac0e..32d19816997 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,7 +101,7 @@ state/               volatile runtime signals; gitignored
   x-outbox/          generated X-mode dry-run reply and dismiss previews; inspect it when FMX_DRY_RUN is set (section 14)
   x-poll.error       generated X-mode relay diagnostic dedupe marker
   fm-dash.check.sh   registered dashboard-service command poll; wakes firstmate while captain dashboard commands are pending (section 7; docs/dashboard-service.md)
-  dash-inbox/        durable captain commands clicked on the served capacity dashboard; claimed exactly once with bin/fm-dash-inbox.sh under the capacity skill
+  dash-inbox/        durable captain commands clicked on the served capacity dashboard; delivered at least once with idempotency checks under the capacity skill
   dash-refs.json     producer-owned private mapping from opaque dashboard references to real identities, written by fm-capacity.mjs --refs for the authenticated dashboard service
   .wake-queue        durable queued wakes: epoch<TAB>seq<TAB>kind<TAB>key<TAB>payload
   .wake-queue.seq    monotonic wake sequence used to distinguish a normal watcher wake handoff from a silent arm-cycle death
diff --git a/bin/fm-capacity.mjs b/bin/fm-capacity.mjs
index 6fe98360421..6503c6b57b4 100755
--- a/bin/fm-capacity.mjs
+++ b/bin/fm-capacity.mjs
@@ -391,6 +391,11 @@ function decisionRef(owner, id) {
   return opaqueRef("item", `decision/${owner}/${id}`);
 }
 
+function backlogDecisionKey(record) {
+  const match = String(record.body_excerpt || "").match(/(?:^|\n)Decision key:\s*([A-Za-z0-9._-]+)/);
+  return match ? match[1] : record.id;
+}
+
 function ownerRef(owner) {
   if (owner === "main" || owner === "ephemeral worker") return owner;
   return `persistent ${opaqueRef("home", String(owner).replace(/^secondmate\s+/, ""))}`;
@@ -645,7 +650,7 @@ function classify(snapshot, environment) {
       decisions.push({
         owner: "main",
         task: itemRef("main", record.id),
-        key: decisionRef("main", record.id),
+        key: decisionRef("main", backlogDecisionKey(record)),
         reason: "A queued choice is held for your decision.",
       });
       blockedRows.push({ id: itemRef("main", record.id), owner: "main", reason: "captain hold" });
diff --git a/bin/fm-dash-inbox.sh b/bin/fm-dash-inbox.sh
index 39559dbf9ce..615f0fd58f2 100755
--- a/bin/fm-dash-inbox.sh
+++ b/bin/fm-dash-inbox.sh
@@ -11,7 +11,7 @@
 #
 # Usage: fm-dash-inbox.sh [list|claim|pending-count]
 #   list           print pending commands without consuming them
-#   claim          archive and print pending commands for handling
+#   claim          print and archive pending commands for handling
 #   pending-count  print the number of pending commands
 set -u
 
@@ -89,7 +89,8 @@ case "${1:-list}" in
     fi
     mkdir -p "$ARCHIVE"
     chmod 700 "$ARCHIVE" 2>/dev/null || true
-    count=0
+    delivered=0
+    archived=0
     while IFS= read -r f; do
       dest="$ARCHIVE/$(basename "$f")"
       if [ -e "$dest" ]; then
@@ -98,18 +99,20 @@ case "${1:-list}" in
       fi
       [ -e "$f" ] || continue
       print_record "$f"
+      delivered=$((delivered + 1))
       if mv -n -- "$f" "$dest" 2>/dev/null && [ ! -e "$f" ] && [ -e "$dest" ]; then
-        count=$((count + 1))
+        archived=$((archived + 1))
       fi
     done <<EOF
 $files
 EOF
-    if [ "$count" -eq 0 ]; then
+    if [ "$delivered" -eq 0 ]; then
       echo "no pending dashboard commands"
       exit 0
     fi
-    printf 'claimed: %s captain dashboard command(s)\n' "$count"
-    echo "handle each prompt as the captain's approval of that action ID under the capacity skill; its authority limits apply and nothing here authorizes a merge, discard, or other destructive act."
+    printf 'delivered: %s captain dashboard command(s)\n' "$delivered"
+    printf 'archived: %s captain dashboard command(s)\n' "$archived"
+    echo "apply idempotency checks to every delivered prompt, then handle it as the captain's approval of that action ID under the capacity skill; its authority limits apply and nothing here authorizes a merge, discard, or other destructive act."
     prune_archive
     ;;
   *)
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
index 605d4263cdf..6b427ac27e4 100755
--- a/bin/fm-dash-serve.mjs
+++ b/bin/fm-dash-serve.mjs
@@ -35,7 +35,7 @@ import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import process from "node:process";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -155,9 +155,14 @@ function pendingRecords() {
   for (const name of names.sort()) {
     if (!name.endsWith(".json")) continue;
     try {
-      const record = JSON.parse(fs.readFileSync(path.join(INBOX, name), "utf8"));
+      const file = path.join(INBOX, name);
+      const raw = fs.readFileSync(file, "utf8");
+      const record = JSON.parse(raw);
       if (record && typeof record.id === "string") {
-        Object.defineProperty(record, "_file", { value: path.join(INBOX, name) });
+        Object.defineProperties(record, {
+          _file: { value: file },
+          _digest: { value: createHash("sha256").update(raw).digest("hex") },
+        });
         records.push(record);
       }
     } catch {
@@ -176,11 +181,15 @@ function enqueueCommand(record) {
   return name;
 }
 
-function replaceCommand(file, record) {
-  const tmp = path.join(INBOX, `.tmp-${randomBytes(6).toString("hex")}`);
-  fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
-  fs.renameSync(tmp, file);
-  return path.basename(file);
+function removePendingIfUnchanged(record) {
+  try {
+    const raw = fs.readFileSync(record._file, "utf8");
+    if (createHash("sha256").update(raw).digest("hex") !== record._digest) return false;
+    fs.unlinkSync(record._file);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 // --- read-only detail assembly -------------------------------------------
@@ -352,6 +361,8 @@ function assembleDetail(ref) {
       type: "decision",
       ref,
       id,
+      decision_home: decision.home,
+      decision_identity: `${decision.home}/${id}`,
       title: document?.title || backlogItem?.title || id,
       description: document?.context || null,
       options: document?.options || [],
@@ -1192,7 +1203,7 @@ async function handle(req, res) {
       }
       const option = hasOption ? detail.options[body.option] : null;
       const pending = pendingRecords();
-      if (pending.some((record) => record.kind === "decision" && record.decision_key === detail.id)) {
+      if (pending.some((record) => record.kind === "decision" && record.decision_identity === detail.decision_identity)) {
         sendJson(res, 200, { status: "already-queued", pending: pending.length });
         return;
       }
@@ -1201,13 +1212,15 @@ async function handle(req, res) {
         kind: "decision",
         id: body.ref,
         decision_key: detail.id,
+        decision_home: detail.decision_home,
+        decision_identity: detail.decision_identity,
         option_text: option?.text || null,
         custom_answer: option ? null : customAnswer,
         requested_by: requesterLogin(req),
         requested_at: new Date().toISOString(),
         prompt: option
-          ? `Captain approved decision ${detail.id}: choose "${option.text}". Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`
-          : `Captain answered decision ${detail.id}: ${customAnswer}. Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`,
+          ? `Captain approved decision ${detail.id} in ${detail.decision_home}: choose "${option.text}". Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`
+          : `Captain answered decision ${detail.id} in ${detail.decision_home}: ${customAnswer}. Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`,
       };
       const name = enqueueCommand(record);
       log(`queued decision ${detail.id} as ${name} for ${record.requested_by}`);
@@ -1254,9 +1267,10 @@ async function handle(req, res) {
         requested_at: new Date().toISOString(),
         prompt: `Captain ${verbs[verdict]} idea ${idea.id} (${idea.title}).${suggestion ? ` Captain suggestion text: ${suggestion}` : ""}${verdict === "approve" ? " Create the follow-up work item(s) through the normal backlog lifecycle." : ""}`,
       };
-      const name = priorVerdict ? replaceCommand(priorVerdict._file, record) : enqueueCommand(record);
+      const name = enqueueCommand(record);
+      if (priorVerdict) removePendingIfUnchanged(priorVerdict);
       log(`queued idea ${idea.id} ${verdict} as ${name} for ${record.requested_by}`);
-      sendJson(res, 200, { status: priorVerdict ? "replaced" : "queued", pending: pending.length + (priorVerdict ? 0 : 1) });
+      sendJson(res, 200, { status: priorVerdict ? "replaced" : "queued", pending: pendingRecords().length });
       return;
     }
 
diff --git a/bin/fm-decision-hold.sh b/bin/fm-decision-hold.sh
index e8865091aa5..f62948cd249 100755
--- a/bin/fm-decision-hold.sh
+++ b/bin/fm-decision-hold.sh
@@ -19,7 +19,7 @@
 # Usage:
 #   fm-decision-hold.sh id <origin-id> <decision-key>
 #   fm-decision-hold.sh hold <origin-id> <decision-key> \
-#     --title <title> --reason <reason> [--repo <repo>]
+#     --title <title> --reason <reason> --options-file <path> [--repo <repo>]
 #   fm-decision-hold.sh complete <origin-id> (--none | <decision-key>...)
 #   fm-decision-hold.sh verify <origin-id>
 #   fm-decision-hold.sh resolve <origin-id> <decision-key> \
@@ -124,6 +124,48 @@ origin_exists_here() {  # <origin-id>
   task_show "$1" >/dev/null 2>&1
 }
 
+validate_options_file() {  # <path> <title>
+  local file=$1 title=$2 bytes document_title
+  [ -f "$file" ] || fail "options file is not a regular file: $file"
+  bytes=$(wc -c < "$file" | tr -d '[:space:]')
+  [ "$bytes" -gt 0 ] && [ "$bytes" -le 131072 ] || fail "options file must contain 1 to 131072 bytes"
+  document_title=$(sed -n 's/^# //p' "$file" | head -1)
+  [ "$document_title" = "$title" ] || fail "options file title must match --title"
+  awk '
+    /^# / && !title { title = 1; next }
+    /^## Options[[:space:]]*$/ { options = 1; next }
+    title && !options && /[^[:space:]]/ { context = 1 }
+    options && /^- (\[recommended\] )?.+[[:space:]]-[[:space:]].+/ { choices += 1 }
+    END { exit !(title && context && options && choices > 0) }
+  ' "$file" || fail "options file must include context and at least one option with its impact"
+}
+
+publish_options_file() {  # <key> <source>
+  local key=$1 source=$2 directory target tmp
+  directory="$DATA/decisions"
+  target="$directory/$key.md"
+  if [ -e "$target" ]; then
+    cmp -s "$source" "$target" || fail "decision options already exist with different content: $target"
+    return 0
+  fi
+  mkdir -p "$directory"
+  chmod 700 "$directory" 2>/dev/null || true
+  tmp=$(mktemp "$directory/.$key.XXXXXX") || fail "could not stage decision options"
+  if ! cp "$source" "$tmp" || ! chmod 600 "$tmp"; then
+    rm -f "$tmp"
+    fail "could not stage decision options: $target"
+  fi
+  if mv -n "$tmp" "$target" && [ ! -e "$tmp" ] && [ -e "$target" ]; then
+    return 0
+  fi
+  if [ -e "$target" ] && cmp -s "$source" "$target"; then
+    rm -f "$tmp"
+    return 0
+  fi
+  rm -f "$tmp"
+  fail "could not publish decision options: $target"
+}
+
 list_has_key() {  # <comma-list> <key>
   case ",$1," in
     *",$2,"*) return 0 ;;
@@ -236,7 +278,7 @@ command_id() {
 }
 
 command_hold() {
-  local origin=${1:-} key=${2:-} title='' reason='' repo='' id show state kind existing_title body
+  local origin=${1:-} key=${2:-} title='' reason='' repo='' options_file='' id show state kind existing_title body
   [ "$#" -ge 2 ] || { usage >&2; exit 2; }
   shift 2
   while [ "$#" -gt 0 ]; do
@@ -244,6 +286,7 @@ command_hold() {
       --title) shift; title=${1:-} ;;
       --reason) shift; reason=${1:-} ;;
       --repo) shift; repo=${1:-} ;;
+      --options-file) shift; options_file=${1:-} ;;
       *) usage >&2; exit 2 ;;
     esac
     shift
@@ -252,6 +295,7 @@ command_hold() {
   validate_slug decision-key "$key"
   validate_one_line title "$title"
   validate_one_line reason "$reason"
+  [ -z "$options_file" ] || validate_options_file "$options_file" "$title"
   case "$reason" in *'('*|*')'*) fail "reason must not contain parentheses (tasks-axi hold contract)" ;; esac
   require_tasks_axi
   origin_exists_here "$origin" || fail "origin $origin is not owned by the active home $FM_HOME"
@@ -263,7 +307,10 @@ command_hold() {
     [ "$state" != "done" ] || fail "captain decision $id is already durably resolved; use a new decision key for a new decision"
     [ "$kind" = captain ] || fail "existing backlog identity $id is not kind captain"
     [ "$existing_title" = "$title" ] || fail "existing captain hold $id has a different title"
+    [ -z "$options_file" ] || publish_options_file "$key" "$options_file"
   else
+    [ -n "$options_file" ] || fail "new captain hold $id requires --options-file"
+    publish_options_file "$key" "$options_file"
     if [ -z "$repo" ] && [ -f "$STATE/$origin.meta" ]; then
       repo=$(meta_value "$STATE/$origin.meta" project)
       repo=${repo%/}
diff --git a/bin/fm-fleet-snapshot.sh b/bin/fm-fleet-snapshot.sh
index a6c1306e900..a03af98f957 100755
--- a/bin/fm-fleet-snapshot.sh
+++ b/bin/fm-fleet-snapshot.sh
@@ -572,7 +572,10 @@ secondmate_home_summary_json() {  # <backlog-json> <tasks-json>
     | ([ $backlog.records[]? | select(.state == "queued" and .structured) ]) as $queued_all
     | ([ $queued_all[]
          | select(.kind == "captain" and .hold_kind == "captain" and .hold_reason != null)
-         | {id,key:.id,verb:"captain-hold",summary:(.title | trunc(160)),
+         | . as $hold
+         | {id,key:(([($hold.body_excerpt // "" | split("\n")[])
+                       | select(startswith("Decision key: "))
+                       | ltrimstr("Decision key: ")] | first) // $hold.id),verb:"captain-hold",summary:(.title | trunc(160)),
             reason:(.hold_reason | trunc(160)),source:"backlog"} ]) as $captain_holds_all
     | ([ $backlog.records[]? | select(.state == "done" and .structured and .kind != "captain")
          | {id:(.id | trunc(120)),title:(.title | trunc(120)),
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index 8378b879ceb..52f909246c2 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -58,9 +58,10 @@ Dispatch is validated against records the server itself reads:
 
 - A `CAP-NN` request must currently be recommended by the served dashboard itself AND sit in the service's fixed one-click allowlist of reviewed lifecycle-safe actions; unknown or future IDs are refused with guidance to raise them in captain chat, so new actions default to chat-only.
 - A decision answer must name a decision in the producer's current-generation refs sidecar, and its integer option index must match the options document the server just parsed; a custom answer is accepted only for a decision with that document and is bounded to 2,000 characters.
+- Decision answers persist and deduplicate against an owner-qualified home and key so equal keys in different homes remain independently routable after refs regenerate.
 - An idea verdict must name an idea currently listed in `data/ideas/idea-backlog.md` and one of the approve, deny, or suggest verbs; on approval, firstmate creates the work item(s) through the normal backlog lifecycle - the service itself never creates work.
 - The only free text accepted is a bounded idea-suggestion note or decision custom answer, which is captain-authored data for firstmate, never a command the service interprets or executes.
-- A newer approve or deny verdict atomically replaces the pending verdict for the same idea, while suggestions remain additive.
+- A newer approve or deny verdict is published under a fresh immutable inbox name before the unchanged older pending verdict is removed, while suggestions remain additive.
 - Destructive, irreversible, and security-sensitive choices stay in captain chat structurally: no current `CAP-NN` prompt grants such authority, the capacity skill forbids treating a dashboard approval as merge or discard authority, decision records carry an explicit re-confirm-in-chat boundary for destructive consequences, and firstmate re-resolves every claimed command through the normal lifecycle before acting.
 
 ## Decision options document
@@ -82,7 +83,7 @@ Explain the decision context and constraints here.
 The first level-one heading is the title, prose before `## Options` is context, and each option is one bullet with an optional `[recommended]` marker followed by ` - ` and its impact.
 Indented continuation lines extend the preceding impact.
 The service accepts at most 20 options and applies bounded text limits while rendering.
-Firstmate and workers create this document in the deciding home when filing a new decision.
+Firstmate and workers author this document when filing a new decision, and `bin/fm-decision-hold.sh hold --options-file` publishes it in the deciding home under the decision-hold lifecycle.
 Legacy decisions without the document remain visible but route the captain to answer in chat.
 In v1, a secondmate-owned work item deliberately shows only a limited ownership note because the main service does not ingest rich task records across home boundaries.
 
diff --git a/docs/decision-hold-lifecycle.md b/docs/decision-hold-lifecycle.md
index e29fe1f3d28..8fe3e021717 100644
--- a/docs/decision-hold-lifecycle.md
+++ b/docs/decision-hold-lifecycle.md
@@ -10,6 +10,8 @@ The command runs tasks-axi in the active `FM_HOME`, so the existing backlog rema
 It never reads report bodies, review artifacts, terminal output, or chat.
 
 The `hold` subcommand maps an originating work id and stable decision key to `<origin-id>-decision-<decision-key>`.
+For a new hold, it requires `--options-file`, validates the dashboard format owned by `docs/dashboard-service.md`, and atomically publishes it as `data/decisions/<key>.md` in the active home before creating the backlog item.
+An already existing legacy hold can still be retried without an options document and remains on the dashboard's answer-in-chat fallback.
 It creates a kind `captain` backlog item when absent and invokes `tasks-axi hold <id> --reason <reason> --kind captain` on every retry.
 It rejects an identity collision, a changed title, and attempts to reopen an already resolved identity.
 
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index 0398916bfd7..d88a1ec4480 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -40,7 +40,7 @@ make_fixture() {
     "records": [
       {"order":0,"state":"in_flight","structured":true,"id":"active-task","title":"Run the active rollout","repo":"alpha","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: rollout remains observable."},
       {"order":1,"state":"queued","structured":true,"id":"ready-safe","title":"Ship the gamma feature","repo":"gamma","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: bounded regression tests pass."},
-      {"order":2,"state":"queued","structured":true,"id":"captain-choice","title":"Choose the rollout policy","repo":"alpha","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"pick conservative or fast rollout"},
+      {"order":2,"state":"queued","structured":true,"id":"captain-choice","title":"Choose the rollout policy","repo":"alpha","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"pick conservative or fast rollout","body_excerpt":"Origin: active-task\nDecision key: rollout-policy\nState: awaiting captain decision."},
       {"order":3,"state":"queued","structured":true,"id":"blocked-child","title":"Ship after rollout choice","repo":"alpha","project_resolved":true,"kind":"ship","blocked_by":"captain-choice","body_excerpt":"Acceptance criteria: follows the selected rollout."}
     ]
   },
@@ -102,7 +102,7 @@ New crew homes should self-provision in one command.
 Send the captain a nightly fleet digest.
 EOF
   printf '# Faster onboarding pitch\n\nOne command provisions a ready home.\n' > "$home/data/ideas/pitches/IDEA-01.md"
-  cat > "$home/data/decisions/captain-choice.md" <<'EOF'
+  cat > "$home/data/decisions/rollout-policy.md" <<'EOF'
 # Choose the rollout policy
 
 Pick the alpha rollout pace before dependent work starts.
@@ -285,9 +285,12 @@ ref_for() {
 }
 
 test_refs_sidecar_and_rich_work_item_detail() {
-  local ref
+  local ref decision_ref
   assert_present "$HOME_DIR/state/dash-refs.json" "producer did not write the refs sidecar"
   assert_grep 'fm-capacity-refs.v1' "$HOME_DIR/state/dash-refs.json" "refs sidecar lacks its schema"
+  decision_ref=$(ref_for "decision/main/rollout-policy") || fail "captain hold ref did not preserve its filed decision key"
+  req GET "http://127.0.0.1:$PORT/api/detail?ref=$decision_ref" "$CAPTAIN"
+  assert_contains "$RESP" 'Conservative rollout' "filed captain hold did not resolve its options document"
   ref=$(ref_for "main/ready-safe") || fail "refs sidecar does not map the main work item"
   req GET "http://127.0.0.1:$PORT/api/detail?ref=$ref" "$CAPTAIN"
   [ "$REQ_STATUS" = 200 ] || fail "work item detail failed (got $REQ_STATUS: $RESP)"
@@ -339,6 +342,40 @@ test_decision_detail_options_and_validated_approval() {
   pass "decision documents validate option picks and bounded custom answers"
 }
 
+test_decision_answers_are_qualified_by_owning_home() {
+  local main_ref mate_ref files records file
+  mkdir -p "$HOME_DIR/design/data/decisions"
+  printf 'home=%s\n' "$HOME_DIR/design" > "$HOME_DIR/state/design.meta"
+  cp "$HOME_DIR/data/decisions/runtime-policy.md" "$HOME_DIR/data/decisions/shared-policy.md"
+  cp "$HOME_DIR/data/decisions/runtime-policy.md" "$HOME_DIR/design/data/decisions/shared-policy.md"
+  node -e '
+    const fs = require("node:fs");
+    const file = process.argv[1];
+    const refs = JSON.parse(fs.readFileSync(file, "utf8"));
+    refs.refs["item-90"] = { kind: "item", value: "decision/main/shared-policy" };
+    refs.refs["item-91"] = { kind: "item", value: "decision/design/shared-policy" };
+    fs.writeFileSync(file, `${JSON.stringify(refs, null, 2)}\n`);
+  ' "$HOME_DIR/state/dash-refs.json"
+  main_ref=item-90
+  mate_ref=item-91
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$main_ref\",\"option\":0}"
+  [ "$REQ_STATUS" = 200 ] || fail "main-home decision answer failed (got $REQ_STATUS: $RESP)"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$mate_ref\",\"option\":0}"
+  [ "$REQ_STATUS" = 200 ] || fail "same-key secondmate decision was wrongly coalesced (got $REQ_STATUS: $RESP)"
+  files=$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*item-9[01].json')
+  [ "$(printf '%s\n' "$files" | grep -c .)" = 2 ] || fail "owner-qualified decision answers did not produce two records"
+  records=''
+  while IFS= read -r file; do
+    records="$records$(cat "$file")"
+    rm -f "$file"
+  done <<EOF
+$files
+EOF
+  assert_contains "$records" '"decision_identity": "main/shared-policy"' "main decision record lacks durable owner identity"
+  assert_contains "$records" '"decision_identity": "design/shared-policy"' "secondmate decision record lacks durable owner identity"
+  pass "equal decision keys remain distinct across owning homes"
+}
+
 test_stale_refs_are_disabled() {
   local ref
   ref=$(ref_for "decision/main/runtime-policy") || fail "refs sidecar does not map the decision"
@@ -366,7 +403,7 @@ test_stale_refs_are_disabled() {
 }
 
 test_idea_pitch_and_verdicts() {
-  local record
+  local record prior_name
   req GET "http://127.0.0.1:$PORT/api/detail?idea=IDEA-01" "$CAPTAIN"
   [ "$REQ_STATUS" = 200 ] || fail "idea pitch failed (got $REQ_STATUS: $RESP)"
   assert_contains "$RESP" 'One command provisions' "idea detail lacks the pitch file content"
@@ -377,12 +414,17 @@ test_idea_pitch_and_verdicts() {
   record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-01.json' | head -1)")
   assert_contains "$record" '"idea"' "idea record lacks its kind"
   assert_contains "$record" 'normal backlog lifecycle' "idea approval does not route creation through firstmate"
+  prior_name=$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-01.json' | head -1)
+  mkdir -p "$HOME_DIR/state/dash-inbox/archive"
+  cp "$prior_name" "$HOME_DIR/state/dash-inbox/archive/$(basename "$prior_name")"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-01","verdict":"deny"}'
   assert_contains "$RESP" '"replaced"' "newest contradictory idea verdict did not replace the pending verdict"
   [ "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-01.json' | wc -l | tr -d ' ')" = 1 ] \
     || fail "verdict replacement left contradictory pending records"
   record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-01.json' | head -1)")
   assert_contains "$record" '"verdict": "deny"' "verdict replacement did not retain the newest choice"
+  [ "$(basename "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*IDEA-01.json' | head -1)")" != "$(basename "$prior_name")" ] \
+    || fail "verdict replacement reused a claimable inbox identity"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-99","verdict":"approve"}'
   [ "$REQ_STATUS" = 404 ] || fail "an unlisted idea was not refused (got $REQ_STATUS)"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" '{"idea":"IDEA-02","verdict":"suggest","suggestion":"scope it to weekdays only"}'
@@ -465,10 +507,14 @@ EOF
   chmod 700 "$stub_bin/mv"
   out=$(PATH="$stub_bin:$PATH" FM_HOME="$HOME_DIR" "$INBOX_SH" claim)
   assert_contains "$out" 'Approve CAP-06' "claim did not deliver before attempting archive"
+  assert_contains "$out" 'delivered: 1' "failed archive did not report the delivered command"
+  assert_contains "$out" 'archived: 0' "failed archive did not report its archive count"
+  assert_contains "$out" 'idempotency checks' "failed archive omitted the replay handling reminder"
   [ -n "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*CAP-06.json' 2>/dev/null)" ] \
     || fail "failed archive silently removed the delivered command"
   out=$(FM_HOME="$HOME_DIR" "$INBOX_SH" claim)
-  assert_contains "$out" 'claimed: 1' "claim did not claim the pending command"
+  assert_contains "$out" 'delivered: 1' "claim did not report the delivered command"
+  assert_contains "$out" 'archived: 1' "claim did not report the archived command"
   assert_contains "$out" 'Approve CAP-06' "claim omits the command prompt"
   assert_contains "$out" 'authority limits apply' "claim omits the authority boundary reminder"
   [ -z "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*.json' 2>/dev/null)" ] \
@@ -546,6 +592,7 @@ test_service_contract_docs_and_ownership() {
   assert_grep 'dashboard service' "$ROOT/.agents/skills/capacity/SKILL.md" "capacity skill does not own dashboard command handling"
   assert_grep 'never Funnel' "$ROOT/.agents/skills/capacity/SKILL.md" "capacity skill does not carry the funnel boundary"
   assert_grep 'data/decisions/<key>.md' "$ROOT/docs/dashboard-service.md" "service doc does not own the decision-options format"
+  assert_grep 'hold --options-file' "$ROOT/.agents/skills/decision-hold-lifecycle/SKILL.md" "decision lifecycle does not own options-document filing"
   assert_grep 'secondmate-owned work item deliberately shows only a limited ownership note' "$ROOT/docs/dashboard-service.md" "service doc omits the accepted secondmate detail boundary"
   pass "the service is documented and wired into the operating contract"
 }
@@ -557,6 +604,7 @@ test_subscription_usage_panel
 test_inline_config_is_script_safe
 test_refs_sidecar_and_rich_work_item_detail
 test_decision_detail_options_and_validated_approval
+test_decision_answers_are_qualified_by_owning_home
 test_stale_refs_are_disabled
 test_idea_pitch_and_verdicts
 test_dispatch_writes_one_durable_record
diff --git a/tests/fm-decision-hold-lifecycle.test.sh b/tests/fm-decision-hold-lifecycle.test.sh
index 09087cce940..abda96c832a 100755
--- a/tests/fm-decision-hold-lifecycle.test.sh
+++ b/tests/fm-decision-hold-lifecycle.test.sh
@@ -121,6 +121,22 @@ write_origin_meta() {  # <home> <id> [kind]
     "mode=$kind"
 }
 
+write_options() {  # <home> <key> <title>
+  local home=$1 key=$2 title=$3 file
+  file="$home/options-$key.md"
+  cat > "$file" <<EOF
+# $title
+
+Choose the bounded synthetic route for this decision.
+
+## Options
+
+- [recommended] Conservative route - Keeps the synthetic change narrow.
+- Fast route - Delivers sooner with a wider synthetic risk.
+EOF
+  printf '%s\n' "$file"
+}
+
 test_structured_holds_survive_teardown_and_route_resolution() {
   local home id route_hold access_hold before after json open show
   home=$(make_home durable-lifecycle)
@@ -147,8 +163,17 @@ EOF
   assert_no_grep "decisions_reviewed=1" "$home/state/$id.meta" \
     "failed completion recorded a false completion attestation"
 
+  if run_decisions "$home" hold "$id" undocumented \
+    --title "Choose an undocumented route" --reason "captain undocumented choice pending" --repo sample \
+    > "$home/undocumented.out" 2> "$home/undocumented.err"; then
+    fail "new hold succeeded without a structured options document"
+  fi
+  assert_grep "requires --options-file" "$home/undocumented.err" "missing options refusal was not explicit"
+  assert_no_grep "$id-decision-undocumented" "$home/data/backlog.md" "refused undocumented hold mutated the backlog"
+
   route_hold=$(run_decisions "$home" hold "$id" route \
-    --title "Choose the sample route" --reason "captain route choice pending" --repo sample) \
+    --title "Choose the sample route" --reason "captain route choice pending" \
+    --options-file "$(write_options "$home" route "Choose the sample route")" --repo sample) \
     || fail "could not register route hold"
   [ "$route_hold" = "$id-decision-route" ] || fail "route hold identity was not deterministic: $route_hold"
   run_decisions "$home" hold "$id" route \
@@ -158,13 +183,16 @@ EOF
     fail "completion succeeded while one of two distinct decisions lacked a hold"
   fi
   access_hold=$(run_decisions "$home" hold "$id" access \
-    --title "Choose the sample access level" --reason "captain access choice pending" --repo sample) \
+    --title "Choose the sample access level" --reason "captain access choice pending" \
+    --options-file "$(write_options "$home" access "Choose the sample access level")" --repo sample) \
     || fail "could not register access hold"
   [ "$access_hold" = "$id-decision-access" ] || fail "access hold identity was not distinct: $access_hold"
   [ "$(grep -cE "^- \[ \] $route_hold -" "$home/data/backlog.md")" = 1 ] \
     || fail "idempotent retry duplicated the route hold"
   [ "$(grep -cE "^- \[ \] $access_hold -" "$home/data/backlog.md")" = 1 ] \
     || fail "second decision did not retain one distinct backlog identity"
+  assert_grep "Conservative route" "$home/data/decisions/route.md" "route options were not published with the hold"
+  assert_grep "Fast route" "$home/data/decisions/access.md" "access options were not published with the hold"
 
   run_decisions "$home" complete "$id" route access >/dev/null \
     || fail "shared investigation completion gate failed"
@@ -344,7 +372,8 @@ test_visual_review_uses_shared_completion_owner() {
   mkdir -p "$home/.lavish"
   printf '<html><body>Synthetic sample board</body></html>\n' > "$home/.lavish/sample-board.html"
   hold=$(run_decisions "$home" hold "$id" layout \
-    --title "Choose the sample layout" --reason "captain layout choice pending" --repo sample) \
+    --title "Choose the sample layout" --reason "captain layout choice pending" \
+    --options-file "$(write_options "$home" layout "Choose the sample layout")" --repo sample) \
     || fail "post-teardown visual review could not use the shared hold owner"
   run_decisions "$home" complete "$id" layout >/dev/null \
     || fail "post-teardown visual review could not use the shared completion owner"
@@ -437,7 +466,8 @@ EOF
   printf 'done: report and visual review complete\n' > "$mate/state/$origin.status"
   printf '# Sample secondmate review\n\nOne captain choice remains.\n' > "$mate/data/$origin/report.md"
   hold=$(run_decisions "$mate" hold "$origin" release \
-    --title "Choose the sample release" --reason "captain release choice pending" --repo sample) \
+    --title "Choose the sample release" --reason "captain release choice pending" \
+    --options-file "$(write_options "$mate" release "Choose the sample release")" --repo sample) \
     || fail "secondmate-owned hold creation failed"
   run_decisions "$mate" complete "$origin" release >/dev/null \
     || fail "secondmate-owned completion failed"
@@ -451,10 +481,11 @@ EOF
     "firstmate:fm-sample-mate" sample
   json=$(run_bearings "$parent") || fail "parent Bearings could not read secondmate hold"
   printf '%s' "$json" | jq -e --arg hold "$hold" '
-    .decisions_open | any(.owner == "sample-mate" and .verb == "captain-hold" and (.id | endswith($hold)))
+    .decisions_open | any(.owner == "sample-mate" and .key == "release" and .verb == "captain-hold" and (.id | endswith($hold)))
   ' >/dev/null || fail "secondmate captain hold did not surface with authoritative owner: $json"
   assert_no_grep "$hold" "$parent/data/backlog.md" "secondmate hold leaked into the main backlog"
   assert_grep "$hold" "$mate/data/backlog.md" "secondmate hold left its authoritative backlog"
+  assert_grep "Conservative route" "$mate/data/decisions/release.md" "secondmate options were not published in the owning home"
   pass "main-home and secondmate-home captain holds remain correctly routed"
 }
 
@@ -466,7 +497,8 @@ test_overlong_captain_hold_is_non_dispatchable() {
   mkdir -p "$home/data/$origin"
   write_origin_meta "$home" "$origin"
   hold=$(run_decisions "$home" hold "$origin" "$key" \
-    --title "Choose the sample release route" --reason "captain release route pending" --repo sample) \
+    --title "Choose the sample release route" --reason "captain release route pending" \
+    --options-file "$(write_options "$home" "$key" "Choose the sample release route")" --repo sample) \
     || fail "overlong captain hold creation failed"
   [ "${#hold}" -gt "$FM_TASK_ID_MAX_LENGTH" ] \
     || fail "captain hold fixture was not overlong: $hold"
@@ -503,16 +535,20 @@ test_resolve_matches_quoted_blocked_by_edges() {
   printf '# Quote edge review\n\nThree edge decisions and one absent control.\n' > "$home/data/$origin/report.md"
 
   hold_first=$(run_decisions "$home" hold "$origin" edge-first \
-    --title "First edge decision" --reason "captain first pending" --repo sample) \
+    --title "First edge decision" --reason "captain first pending" \
+    --options-file "$(write_options "$home" edge-first "First edge decision")" --repo sample) \
     || fail "could not register first-edge hold"
   hold_mid=$(run_decisions "$home" hold "$origin" edge-mid \
-    --title "Middle edge decision" --reason "captain mid pending" --repo sample) \
+    --title "Middle edge decision" --reason "captain mid pending" \
+    --options-file "$(write_options "$home" edge-mid "Middle edge decision")" --repo sample) \
     || fail "could not register mid-edge hold"
   hold_last=$(run_decisions "$home" hold "$origin" edge-last \
-    --title "Last edge decision" --reason "captain last pending" --repo sample) \
+    --title "Last edge decision" --reason "captain last pending" \
+    --options-file "$(write_options "$home" edge-last "Last edge decision")" --repo sample) \
     || fail "could not register last-edge hold"
   hold_absent=$(run_decisions "$home" hold "$origin" edge-absent \
-    --title "Absent edge decision" --reason "captain absent pending" --repo sample) \
+    --title "Absent edge decision" --reason "captain absent pending" \
+    --options-file "$(write_options "$home" edge-absent "Absent edge decision")" --repo sample) \
     || fail "could not register absent-edge hold"
 
   tasks_in "$home" add pad-a "Pad A" --kind ship --repo sample >/dev/null \

From eacd860fec4252d08e7000fbf2e3745fcdec5a7d Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 11:27:58 -0400
Subject: [PATCH 05/24] no-mistakes(review): Origin-qualify dashboard decision
 identities

---
 .agents/skills/capacity/SKILL.md              |  2 +-
 .../skills/decision-hold-lifecycle/SKILL.md   |  2 +-
 bin/fm-capacity.mjs                           | 19 +++--
 bin/fm-dash-serve.mjs                         | 34 +++++----
 bin/fm-decision-hold.sh                       | 10 +--
 bin/fm-fleet-snapshot.sh                      |  5 +-
 docs/dashboard-service.md                     |  9 ++-
 docs/decision-hold-lifecycle.md               |  2 +-
 tests/fm-dash.test.sh                         | 75 ++++++++++++-------
 tests/fm-decision-hold-lifecycle.test.sh      | 36 ++++++++-
 10 files changed, 131 insertions(+), 63 deletions(-)

diff --git a/.agents/skills/capacity/SKILL.md b/.agents/skills/capacity/SKILL.md
index 5ee481c665f..4ed7c3ad8c6 100644
--- a/.agents/skills/capacity/SKILL.md
+++ b/.agents/skills/capacity/SKILL.md
@@ -96,7 +96,7 @@ On a `check:` wake naming `fm-dash.check.sh`, run `bin/fm-dash-inbox.sh claim` a
 Claim delivery is at-least-once across interruption, so check whether a re-surfaced record was already handled before applying it again.
 
 - A `CAP-NN` record is the captain's ordinary chat approval of that action ID under section 4, including its full re-resolution and authority limits.
-- A `decision` record is the captain's answer for the owner-qualified decision identity with either the recorded option text or bounded custom answer; route it in `decision_home` through `decision-hold-lifecycle` exactly as a chat answer, and re-confirm in chat before acting when the answer has a destructive or irreversible consequence.
+- A `decision` record is the captain's answer for the owner-qualified decision identity with either the recorded option text or bounded custom answer; route `decision_origin` in `decision_home` through `decision-hold-lifecycle` exactly as a chat answer, and re-confirm in chat before acting when the answer has a destructive or irreversible consequence.
 - An `idea` record is the captain's verdict on the named `data/ideas/` idea: on approve, create the follow-up work item(s) through the normal backlog lifecycle; on deny, record the outcome against the idea; on suggest, treat the suggestion text as captain input on that idea.
 
 A claimed record never authorizes a PR merge, `local-only` landing, destructive action, irreversible action, security-sensitive action, or discard of unlanded work; when a claimed action leads to such a choice, escalate it to captain chat exactly as section 4 requires.
diff --git a/.agents/skills/decision-hold-lifecycle/SKILL.md b/.agents/skills/decision-hold-lifecycle/SKILL.md
index 656ec6ea7c5..d4ce32af2d2 100644
--- a/.agents/skills/decision-hold-lifecycle/SKILL.md
+++ b/.agents/skills/decision-hold-lifecycle/SKILL.md
@@ -14,7 +14,7 @@ This skill is the single policy owner for unresolved captain decisions discovere
 
 ## Policy
 
-Before filing a new decision, author its title, context, options, and per-option impacts in the format owned by `docs/dashboard-service.md`, then pass that file to `bin/fm-decision-hold.sh hold --options-file`; legacy holds that already exist without a document remain answer-in-chat decisions.
+Before filing a new decision, author its title, context, options, and per-option impacts in the origin-qualified format owned by `docs/dashboard-service.md`, then pass that file to `bin/fm-decision-hold.sh hold --options-file`; legacy holds that already exist without a document remain answer-in-chat decisions.
 
 Every unresolved decision that belongs to the captain and is discovered while producing, reading, presenting, or ending an investigation or visual review must become a structured captain-held work item in the authoritative backlog of the home that owns the originating work before that work or review may be treated as complete.
 The agent performs the semantic inventory because scripts must not infer decisions from report prose, visual-review artifacts, terminal output, or chat.
diff --git a/bin/fm-capacity.mjs b/bin/fm-capacity.mjs
index 6503c6b57b4..50869275694 100755
--- a/bin/fm-capacity.mjs
+++ b/bin/fm-capacity.mjs
@@ -387,13 +387,15 @@ function itemRef(owner, id) {
   return opaqueRef("item", `${owner}/${id}`);
 }
 
-function decisionRef(owner, id) {
-  return opaqueRef("item", `decision/${owner}/${id}`);
+function decisionRef(owner, origin, key) {
+  return opaqueRef("item", `decision/${owner}/${origin}/${key}`);
 }
 
-function backlogDecisionKey(record) {
-  const match = String(record.body_excerpt || "").match(/(?:^|\n)Decision key:\s*([A-Za-z0-9._-]+)/);
-  return match ? match[1] : record.id;
+function backlogDecisionIdentity(record) {
+  const body = String(record.body_excerpt || "");
+  const origin = body.match(/(?:^|\n)Origin:\s*([A-Za-z0-9._-]+)/)?.[1] || record.id;
+  const key = body.match(/(?:^|\n)Decision key:\s*([A-Za-z0-9._-]+)/)?.[1] || record.id;
+  return { origin, key };
 }
 
 function ownerRef(owner) {
@@ -609,7 +611,7 @@ function classify(snapshot, environment) {
       decisions.push({
         owner: "main",
         task: itemRef("main", task.id),
-        key: decisionRef("main", decision.key || task.id),
+        key: decisionRef("main", task.id, decision.key || task.id),
         reason: "Open decision raised by work already under way.",
       });
     }
@@ -647,10 +649,11 @@ function classify(snapshot, environment) {
     }
     if (isSuperseded(record)) continue;
     if (record.kind === "captain" && record.hold_kind === "captain") {
+      const decision = backlogDecisionIdentity(record);
       decisions.push({
         owner: "main",
         task: itemRef("main", record.id),
-        key: decisionRef("main", backlogDecisionKey(record)),
+        key: decisionRef("main", decision.origin, decision.key),
         reason: "A queued choice is held for your decision.",
       });
       blockedRows.push({ id: itemRef("main", record.id), owner: "main", reason: "captain hold" });
@@ -715,7 +718,7 @@ function classify(snapshot, environment) {
       decisions.push({
         owner: ownerRef(mate.id),
         task: itemRef(mate.id, decision.id || mate.id),
-        key: decisionRef(mate.id, decision.key || decision.id || mate.id),
+        key: decisionRef(mate.id, decision.origin || decision.id || mate.id, decision.key || decision.id || mate.id),
         reason: "Open decision raised by work already under way.",
       });
     }
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
index 6b427ac27e4..cebbac71b3f 100755
--- a/bin/fm-dash-serve.mjs
+++ b/bin/fm-dash-serve.mjs
@@ -279,8 +279,9 @@ function previewLinks(...texts) {
 function decisionRef(entry) {
   const parts = entry.value.split("/");
   if (parts[0] !== "decision") return null;
-  if (parts.length >= 3) return { home: parts[1], id: parts.slice(2).join("/") };
-  return { home: "main", id: parts.slice(1).join("/") };
+  if (parts.length >= 4) return { home: parts[1], origin: parts[2], key: parts.slice(3).join("/") };
+  if (parts.length === 3) return { home: parts[1], origin: null, key: parts[2] };
+  return { home: "main", origin: null, key: parts.slice(1).join("/") };
 }
 
 function decisionHome(home) {
@@ -289,11 +290,15 @@ function decisionHome(home) {
   return meta.home ? path.resolve(meta.home) : null;
 }
 
-function decisionDocument(home, id) {
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id)) return null;
+function decisionDocument(home, origin, key) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(key)) return null;
+  if (origin !== null && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(origin)) return null;
   const root = decisionHome(home);
   if (!root) return null;
-  const text = readText(path.join(root, "data", "decisions", `${id}.md`), 131072);
+  const file = origin === null
+    ? path.join(root, "data", "decisions", `${key}.md`)
+    : path.join(root, "data", origin, "decisions", `${key}.md`);
+  const text = readText(file, 131072);
   if (!text) return null;
   const title = (text.match(/^#\s+(.+)$/m) || [])[1]?.trim();
   const sections = text.split(/^##\s+Options\s*$/im);
@@ -335,7 +340,7 @@ function refDisplayMap(refsFile) {
       const separator = entry.value.indexOf("/");
       const owner = entry.value.slice(0, separator);
       const decision = decisionRef(entry);
-      const id = decision ? decision.id : entry.value.slice(separator + 1);
+      const id = decision ? `${decision.origin ? `${decision.origin}/` : ""}${decision.key}` : entry.value.slice(separator + 1);
       display[ref] = owner === "decision"
         ? { t: "decision", label: id }
         : { t: "work", label: id, owner };
@@ -352,21 +357,23 @@ function assembleDetail(ref) {
   const separator = entry.value.indexOf("/");
   const owner = entry.value.slice(0, separator);
   const decision = decisionRef(entry);
-  const id = decision ? decision.id : entry.value.slice(separator + 1);
-  const backlogItem = parseBacklog().find((item) => item.id === id) || null;
+  const id = decision ? decision.key : entry.value.slice(separator + 1);
+  const holdId = decision?.origin ? `${decision.origin}-decision-${decision.key}` : id;
+  const backlogItem = parseBacklog().find((item) => item.id === holdId) || null;
 
   if (owner === "decision") {
-    const document = decisionDocument(decision.home, id);
+    const document = decisionDocument(decision.home, decision.origin, decision.key);
     return {
       type: "decision",
       ref,
       id,
       decision_home: decision.home,
-      decision_identity: `${decision.home}/${id}`,
+      decision_origin: decision.origin,
+      decision_identity: `${decision.home}/${decision.origin || ""}/${decision.key}`,
       title: document?.title || backlogItem?.title || id,
       description: document?.context || null,
       options: document?.options || [],
-      recent: statusTail(id),
+      recent: statusTail(decision.origin || id),
       note: document ? null : "This legacy decision has no structured options document; answer it in captain chat.",
     };
   }
@@ -1213,14 +1220,15 @@ async function handle(req, res) {
         id: body.ref,
         decision_key: detail.id,
         decision_home: detail.decision_home,
+        decision_origin: detail.decision_origin,
         decision_identity: detail.decision_identity,
         option_text: option?.text || null,
         custom_answer: option ? null : customAnswer,
         requested_by: requesterLogin(req),
         requested_at: new Date().toISOString(),
         prompt: option
-          ? `Captain approved decision ${detail.id} in ${detail.decision_home}: choose "${option.text}". Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`
-          : `Captain answered decision ${detail.id} in ${detail.decision_home}: ${customAnswer}. Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`,
+          ? `Captain approved decision ${detail.id} for ${detail.decision_origin || "legacy"} in ${detail.decision_home}: choose "${option.text}". Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`
+          : `Captain answered decision ${detail.id} for ${detail.decision_origin || "legacy"} in ${detail.decision_home}: ${customAnswer}. Route it through the normal decision lifecycle; a destructive or irreversible consequence still needs chat confirmation.`,
       };
       const name = enqueueCommand(record);
       log(`queued decision ${detail.id} as ${name} for ${record.requested_by}`);
diff --git a/bin/fm-decision-hold.sh b/bin/fm-decision-hold.sh
index f62948cd249..b401cd958c3 100755
--- a/bin/fm-decision-hold.sh
+++ b/bin/fm-decision-hold.sh
@@ -140,9 +140,9 @@ validate_options_file() {  # <path> <title>
   ' "$file" || fail "options file must include context and at least one option with its impact"
 }
 
-publish_options_file() {  # <key> <source>
-  local key=$1 source=$2 directory target tmp
-  directory="$DATA/decisions"
+publish_options_file() {  # <origin> <key> <source>
+  local origin=$1 key=$2 source=$3 directory target tmp
+  directory="$DATA/$origin/decisions"
   target="$directory/$key.md"
   if [ -e "$target" ]; then
     cmp -s "$source" "$target" || fail "decision options already exist with different content: $target"
@@ -307,10 +307,10 @@ command_hold() {
     [ "$state" != "done" ] || fail "captain decision $id is already durably resolved; use a new decision key for a new decision"
     [ "$kind" = captain ] || fail "existing backlog identity $id is not kind captain"
     [ "$existing_title" = "$title" ] || fail "existing captain hold $id has a different title"
-    [ -z "$options_file" ] || publish_options_file "$key" "$options_file"
+    [ -z "$options_file" ] || publish_options_file "$origin" "$key" "$options_file"
   else
     [ -n "$options_file" ] || fail "new captain hold $id requires --options-file"
-    publish_options_file "$key" "$options_file"
+    publish_options_file "$origin" "$key" "$options_file"
     if [ -z "$repo" ] && [ -f "$STATE/$origin.meta" ]; then
       repo=$(meta_value "$STATE/$origin.meta" project)
       repo=${repo%/}
diff --git a/bin/fm-fleet-snapshot.sh b/bin/fm-fleet-snapshot.sh
index a03af98f957..d21ad1279d6 100755
--- a/bin/fm-fleet-snapshot.sh
+++ b/bin/fm-fleet-snapshot.sh
@@ -573,7 +573,10 @@ secondmate_home_summary_json() {  # <backlog-json> <tasks-json>
     | ([ $queued_all[]
          | select(.kind == "captain" and .hold_kind == "captain" and .hold_reason != null)
          | . as $hold
-         | {id,key:(([($hold.body_excerpt // "" | split("\n")[])
+         | {id,origin:(([($hold.body_excerpt // "" | split("\n")[])
+                          | select(startswith("Origin: "))
+                          | ltrimstr("Origin: ")] | first) // $hold.id),
+            key:(([($hold.body_excerpt // "" | split("\n")[])
                        | select(startswith("Decision key: "))
                        | ltrimstr("Decision key: ")] | first) // $hold.id),verb:"captain-hold",summary:(.title | trunc(160)),
             reason:(.hold_reason | trunc(160)),source:"backlog"} ]) as $captain_holds_all
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index 52f909246c2..0fe9657d520 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -10,7 +10,7 @@ The service publishes the producer-generated `data/capacity-dashboard.html` at o
 - Every current one-click-eligible `CAP-NN` action gets an "Approve & send" button.
 - A "Refresh capacity" button reruns `bin/fm-capacity.mjs` server-side and reloads the page; the producer also reruns automatically on the configured interval so the page never goes stale.
 - The page is de-anonymized for the authenticated captain: opaque `item-NN`/`project-NN`/`home-NN` references become real names, and work items and decisions are clickable rich detail views (description, test plan, PR link, tailnet preview links, report excerpt, recent activity) assembled from task briefs, recorded metadata, the backlog, and scout reports.
-- Open decisions with `data/decisions/<key>.md` records show each recorded option with its impact, a per-option Approve button, and a bounded custom-answer control.
+- Open decisions with `data/<origin>/decisions/<key>.md` records show each recorded option with its impact, a per-option Approve button, and a bounded custom-answer control.
 - An Ideas section renders `data/ideas/idea-backlog.md`; each idea opens its pitch (`data/ideas/pitches/IDEA-XX.md` when present, else the concept summary) with Approve, Deny, and Add-suggestions controls.
 - A service bar shows how many captain commands are queued for firstmate.
 - A Subscription usage band shows cached `quota-axi --json` windows for Claude, Codex, and Grok, including percent used and reset distance with reset time formatted by the captain's browser in local time.
@@ -58,7 +58,7 @@ Dispatch is validated against records the server itself reads:
 
 - A `CAP-NN` request must currently be recommended by the served dashboard itself AND sit in the service's fixed one-click allowlist of reviewed lifecycle-safe actions; unknown or future IDs are refused with guidance to raise them in captain chat, so new actions default to chat-only.
 - A decision answer must name a decision in the producer's current-generation refs sidecar, and its integer option index must match the options document the server just parsed; a custom answer is accepted only for a decision with that document and is bounded to 2,000 characters.
-- Decision answers persist and deduplicate against an owner-qualified home and key so equal keys in different homes remain independently routable after refs regenerate.
+- Decision answers persist and deduplicate against an owner-qualified home, origin, and key so equal keys from different origins or homes remain independently routable after refs regenerate.
 - An idea verdict must name an idea currently listed in `data/ideas/idea-backlog.md` and one of the approve, deny, or suggest verbs; on approval, firstmate creates the work item(s) through the normal backlog lifecycle - the service itself never creates work.
 - The only free text accepted is a bounded idea-suggestion note or decision custom answer, which is captain-authored data for firstmate, never a command the service interprets or executes.
 - A newer approve or deny verdict is published under a fresh immutable inbox name before the unchanged older pending verdict is removed, while suggestions remain additive.
@@ -66,7 +66,8 @@ Dispatch is validated against records the server itself reads:
 
 ## Decision options document
 
-The home that owns a decision writes `data/decisions/<key>.md`, where `<key>` is the stable decision key carried by the refs sidecar even when it is not a backlog item ID.
+The home that owns a decision writes `data/<origin>/decisions/<key>.md`, where `<origin>` is the originating work ID and `<key>` is its stable decision key.
+The refs sidecar carries `decision/<home>/<origin>/<key>`, preserving the same durable identity even when the key is not a backlog item ID.
 The document is producer-owned decision data and uses this format:
 
 ```markdown
@@ -83,7 +84,7 @@ Explain the decision context and constraints here.
 The first level-one heading is the title, prose before `## Options` is context, and each option is one bullet with an optional `[recommended]` marker followed by ` - ` and its impact.
 Indented continuation lines extend the preceding impact.
 The service accepts at most 20 options and applies bounded text limits while rendering.
-Firstmate and workers author this document when filing a new decision, and `bin/fm-decision-hold.sh hold --options-file` publishes it in the deciding home under the decision-hold lifecycle.
+Firstmate and workers author this document when filing a new decision, and `bin/fm-decision-hold.sh hold --options-file` publishes it under the originating work in the deciding home through the decision-hold lifecycle.
 Legacy decisions without the document remain visible but route the captain to answer in chat.
 In v1, a secondmate-owned work item deliberately shows only a limited ownership note because the main service does not ingest rich task records across home boundaries.
 
diff --git a/docs/decision-hold-lifecycle.md b/docs/decision-hold-lifecycle.md
index 8fe3e021717..9e8612a8ad2 100644
--- a/docs/decision-hold-lifecycle.md
+++ b/docs/decision-hold-lifecycle.md
@@ -10,7 +10,7 @@ The command runs tasks-axi in the active `FM_HOME`, so the existing backlog rema
 It never reads report bodies, review artifacts, terminal output, or chat.
 
 The `hold` subcommand maps an originating work id and stable decision key to `<origin-id>-decision-<decision-key>`.
-For a new hold, it requires `--options-file`, validates the dashboard format owned by `docs/dashboard-service.md`, and atomically publishes it as `data/decisions/<key>.md` in the active home before creating the backlog item.
+For a new hold, it requires `--options-file`, validates the dashboard format owned by `docs/dashboard-service.md`, and atomically publishes it as `data/<origin>/decisions/<key>.md` in the active home before creating the backlog item.
 An already existing legacy hold can still be retried without an options document and remains on the dashboard's answer-in-chat fallback.
 It creates a kind `captain` backlog item when absent and invokes `tasks-axi hold <id> --reason <reason> --kind captain` on every retry.
 It rejects an identity collision, a changed title, and attempts to reopen an already resolved identity.
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index d88a1ec4480..6212eeef5da 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -41,7 +41,8 @@ make_fixture() {
       {"order":0,"state":"in_flight","structured":true,"id":"active-task","title":"Run the active rollout","repo":"alpha","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: rollout remains observable."},
       {"order":1,"state":"queued","structured":true,"id":"ready-safe","title":"Ship the gamma feature","repo":"gamma","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: bounded regression tests pass."},
       {"order":2,"state":"queued","structured":true,"id":"captain-choice","title":"Choose the rollout policy","repo":"alpha","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"pick conservative or fast rollout","body_excerpt":"Origin: active-task\nDecision key: rollout-policy\nState: awaiting captain decision."},
-      {"order":3,"state":"queued","structured":true,"id":"blocked-child","title":"Ship after rollout choice","repo":"alpha","project_resolved":true,"kind":"ship","blocked_by":"captain-choice","body_excerpt":"Acceptance criteria: follows the selected rollout."}
+      {"order":3,"state":"queued","structured":true,"id":"captain-choice-two","title":"Choose the secondary rollout policy","repo":"alpha","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"pick a secondary rollout","body_excerpt":"Origin: secondary-task\nDecision key: rollout-policy\nState: awaiting captain decision."},
+      {"order":4,"state":"queued","structured":true,"id":"blocked-child","title":"Ship after rollout choice","repo":"alpha","project_resolved":true,"kind":"ship","blocked_by":"captain-choice","body_excerpt":"Acceptance criteria: follows the selected rollout."}
     ]
   },
   "tasks": [
@@ -74,12 +75,14 @@ EOF
   Pick the alpha rollout pace before dependent work starts.
   - Conservative rollout: slower, safest for existing users
   - Fast rollout: reaches everyone this week, higher regression risk
+- [ ] captain-choice-two - Choose the secondary rollout policy (repo: alpha) (kind: captain)
+  Pick the secondary rollout pace independently.
 - [ ] blocked-child - Ship after rollout choice (repo: alpha) (kind: ship) (blocked-by: captain-choice)
   Acceptance criteria: follows the selected rollout.
 
 ## Done
 EOF
-  mkdir -p "$home/data/ready-safe" "$home/data/ideas/pitches" "$home/data/decisions"
+  mkdir -p "$home/data/ready-safe" "$home/data/ideas/pitches" "$home/data/active-task/decisions" "$home/data/secondary-task/decisions"
   cat > "$home/data/ready-safe/brief.md" <<'EOF'
 # Task
 Ship the gamma feature so gamma users get streaming exports.
@@ -102,7 +105,7 @@ New crew homes should self-provision in one command.
 Send the captain a nightly fleet digest.
 EOF
   printf '# Faster onboarding pitch\n\nOne command provisions a ready home.\n' > "$home/data/ideas/pitches/IDEA-01.md"
-  cat > "$home/data/decisions/rollout-policy.md" <<'EOF'
+  cat > "$home/data/active-task/decisions/rollout-policy.md" <<'EOF'
 # Choose the rollout policy
 
 Pick the alpha rollout pace before dependent work starts.
@@ -112,7 +115,7 @@ Pick the alpha rollout pace before dependent work starts.
 - [recommended] Conservative rollout - Slower delivery with the lowest regression risk.
 - Fast rollout - Reaches everyone this week with higher regression risk.
 EOF
-  cat > "$home/data/decisions/runtime-policy.md" <<'EOF'
+  cat > "$home/data/active-task/decisions/runtime-policy.md" <<'EOF'
 # Choose the runtime policy
 
 Choose how the active rollout should continue.
@@ -121,6 +124,16 @@ Choose how the active rollout should continue.
 
 - [recommended] Conservative rollout - Slower delivery with the lowest regression risk.
 - Fast rollout - Reaches everyone this week with higher regression risk.
+EOF
+  cat > "$home/data/secondary-task/decisions/rollout-policy.md" <<'EOF'
+# Choose the secondary rollout policy
+
+Choose the independent secondary rollout pace.
+
+## Options
+
+- [recommended] Staged secondary rollout - Keeps secondary users isolated during validation.
+- Immediate secondary rollout - Moves faster with broader secondary exposure.
 EOF
 }
 
@@ -273,7 +286,7 @@ EOF
 }
 
 ref_for() {
-  # ref_for <kind-owner-prefix> e.g. "main/ready-safe" or "decision/main/runtime-policy"
+  # ref_for <kind-owner-prefix> e.g. "main/ready-safe" or "decision/main/active-task/runtime-policy"
   node -e '
     const refs = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).refs;
     const wanted = process.argv[2];
@@ -285,12 +298,16 @@ ref_for() {
 }
 
 test_refs_sidecar_and_rich_work_item_detail() {
-  local ref decision_ref
+  local ref decision_ref same_key_ref
   assert_present "$HOME_DIR/state/dash-refs.json" "producer did not write the refs sidecar"
   assert_grep 'fm-capacity-refs.v1' "$HOME_DIR/state/dash-refs.json" "refs sidecar lacks its schema"
-  decision_ref=$(ref_for "decision/main/rollout-policy") || fail "captain hold ref did not preserve its filed decision key"
+  decision_ref=$(ref_for "decision/main/active-task/rollout-policy") || fail "captain hold ref did not preserve its filed decision identity"
   req GET "http://127.0.0.1:$PORT/api/detail?ref=$decision_ref" "$CAPTAIN"
   assert_contains "$RESP" 'Conservative rollout' "filed captain hold did not resolve its options document"
+  same_key_ref=$(ref_for "decision/main/secondary-task/rollout-policy") || fail "second same-home decision did not retain its origin-qualified ref"
+  [ "$same_key_ref" != "$decision_ref" ] || fail "same-key decisions from distinct origins shared one opaque ref"
+  req GET "http://127.0.0.1:$PORT/api/detail?ref=$same_key_ref" "$CAPTAIN"
+  assert_contains "$RESP" 'Staged secondary rollout' "second same-key decision did not resolve its own options document"
   ref=$(ref_for "main/ready-safe") || fail "refs sidecar does not map the main work item"
   req GET "http://127.0.0.1:$PORT/api/detail?ref=$ref" "$CAPTAIN"
   [ "$REQ_STATUS" = 200 ] || fail "work item detail failed (got $REQ_STATUS: $RESP)"
@@ -305,7 +322,7 @@ test_refs_sidecar_and_rich_work_item_detail() {
 
 test_decision_detail_options_and_validated_approval() {
   local ref record
-  ref=$(ref_for "decision/main/runtime-policy") || fail "refs sidecar does not map a non-backlog decision key"
+  ref=$(ref_for "decision/main/active-task/runtime-policy") || fail "refs sidecar does not map an origin-qualified non-backlog decision key"
   req GET "http://127.0.0.1:$PORT/api/detail?ref=$ref" "$CAPTAIN"
   [ "$REQ_STATUS" = 200 ] || fail "decision detail failed (got $REQ_STATUS: $RESP)"
   assert_contains "$RESP" 'Conservative rollout' "decision detail lacks its first option"
@@ -332,38 +349,43 @@ test_decision_detail_options_and_validated_approval() {
   record=$(cat "$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name "*$ref.json" | head -1)")
   assert_contains "$record" 'Use a 10% canary for 48 hours' "decision record lacks the custom answer"
   find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name "*$ref.json" -delete
-  mv "$HOME_DIR/data/decisions/runtime-policy.md" "$HOME_DIR/data/decisions/runtime-policy.md.off"
+  mv "$HOME_DIR/data/active-task/decisions/runtime-policy.md" "$HOME_DIR/data/active-task/decisions/runtime-policy.md.off"
   req GET "http://127.0.0.1:$PORT/api/detail?ref=$ref" "$CAPTAIN"
   assert_contains "$RESP" 'legacy decision' "legacy decision does not route to captain chat"
   assert_contains "$RESP" '"options":[]' "legacy backlog bullets were treated as structured decision options"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"answer\":\"unsafe fallback\"}"
   [ "$REQ_STATUS" = 400 ] || fail "legacy decision accepted free text without an options document"
-  mv "$HOME_DIR/data/decisions/runtime-policy.md.off" "$HOME_DIR/data/decisions/runtime-policy.md"
+  mv "$HOME_DIR/data/active-task/decisions/runtime-policy.md.off" "$HOME_DIR/data/active-task/decisions/runtime-policy.md"
   pass "decision documents validate option picks and bounded custom answers"
 }
 
-test_decision_answers_are_qualified_by_owning_home() {
-  local main_ref mate_ref files records file
-  mkdir -p "$HOME_DIR/design/data/decisions"
+test_decision_answers_are_qualified_by_home_and_origin() {
+  local main_ref same_home_ref mate_ref files records file
+  mkdir -p "$HOME_DIR/data/origin-alpha/decisions" "$HOME_DIR/data/origin-beta/decisions" "$HOME_DIR/design/data/design-origin/decisions"
   printf 'home=%s\n' "$HOME_DIR/design" > "$HOME_DIR/state/design.meta"
-  cp "$HOME_DIR/data/decisions/runtime-policy.md" "$HOME_DIR/data/decisions/shared-policy.md"
-  cp "$HOME_DIR/data/decisions/runtime-policy.md" "$HOME_DIR/design/data/decisions/shared-policy.md"
+  cp "$HOME_DIR/data/active-task/decisions/runtime-policy.md" "$HOME_DIR/data/origin-alpha/decisions/shared-policy.md"
+  cp "$HOME_DIR/data/active-task/decisions/rollout-policy.md" "$HOME_DIR/data/origin-beta/decisions/shared-policy.md"
+  cp "$HOME_DIR/data/active-task/decisions/runtime-policy.md" "$HOME_DIR/design/data/design-origin/decisions/shared-policy.md"
   node -e '
     const fs = require("node:fs");
     const file = process.argv[1];
     const refs = JSON.parse(fs.readFileSync(file, "utf8"));
-    refs.refs["item-90"] = { kind: "item", value: "decision/main/shared-policy" };
-    refs.refs["item-91"] = { kind: "item", value: "decision/design/shared-policy" };
+    refs.refs["item-90"] = { kind: "item", value: "decision/main/origin-alpha/shared-policy" };
+    refs.refs["item-91"] = { kind: "item", value: "decision/main/origin-beta/shared-policy" };
+    refs.refs["item-92"] = { kind: "item", value: "decision/design/design-origin/shared-policy" };
     fs.writeFileSync(file, `${JSON.stringify(refs, null, 2)}\n`);
   ' "$HOME_DIR/state/dash-refs.json"
   main_ref=item-90
-  mate_ref=item-91
+  same_home_ref=item-91
+  mate_ref=item-92
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$main_ref\",\"option\":0}"
   [ "$REQ_STATUS" = 200 ] || fail "main-home decision answer failed (got $REQ_STATUS: $RESP)"
+  req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$same_home_ref\",\"option\":0}"
+  [ "$REQ_STATUS" = 200 ] || fail "same-key same-home decision was wrongly coalesced (got $REQ_STATUS: $RESP)"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$mate_ref\",\"option\":0}"
   [ "$REQ_STATUS" = 200 ] || fail "same-key secondmate decision was wrongly coalesced (got $REQ_STATUS: $RESP)"
-  files=$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*item-9[01].json')
-  [ "$(printf '%s\n' "$files" | grep -c .)" = 2 ] || fail "owner-qualified decision answers did not produce two records"
+  files=$(find "$HOME_DIR/state/dash-inbox" -maxdepth 1 -name '*item-9[012].json')
+  [ "$(printf '%s\n' "$files" | grep -c .)" = 3 ] || fail "origin-qualified decision answers did not produce three records"
   records=''
   while IFS= read -r file; do
     records="$records$(cat "$file")"
@@ -371,14 +393,15 @@ test_decision_answers_are_qualified_by_owning_home() {
   done <<EOF
 $files
 EOF
-  assert_contains "$records" '"decision_identity": "main/shared-policy"' "main decision record lacks durable owner identity"
-  assert_contains "$records" '"decision_identity": "design/shared-policy"' "secondmate decision record lacks durable owner identity"
-  pass "equal decision keys remain distinct across owning homes"
+  assert_contains "$records" '"decision_identity": "main/origin-alpha/shared-policy"' "first main decision record lacks durable origin identity"
+  assert_contains "$records" '"decision_identity": "main/origin-beta/shared-policy"' "same-home decision record lacks distinct origin identity"
+  assert_contains "$records" '"decision_identity": "design/design-origin/shared-policy"' "secondmate decision record lacks durable owner identity"
+  pass "equal decision keys remain distinct across origins and homes"
 }
 
 test_stale_refs_are_disabled() {
   local ref
-  ref=$(ref_for "decision/main/runtime-policy") || fail "refs sidecar does not map the decision"
+  ref=$(ref_for "decision/main/active-task/runtime-policy") || fail "refs sidecar does not map the decision"
   node -e '
     const fs = require("node:fs");
     const file = process.argv[1];
@@ -591,7 +614,7 @@ test_service_contract_docs_and_ownership() {
   assert_grep 'config/dash.json' "$ROOT/.gitignore" "config/dash.json is not gitignored"
   assert_grep 'dashboard service' "$ROOT/.agents/skills/capacity/SKILL.md" "capacity skill does not own dashboard command handling"
   assert_grep 'never Funnel' "$ROOT/.agents/skills/capacity/SKILL.md" "capacity skill does not carry the funnel boundary"
-  assert_grep 'data/decisions/<key>.md' "$ROOT/docs/dashboard-service.md" "service doc does not own the decision-options format"
+  assert_grep 'data/<origin>/decisions/<key>.md' "$ROOT/docs/dashboard-service.md" "service doc does not own the origin-qualified decision-options format"
   assert_grep 'hold --options-file' "$ROOT/.agents/skills/decision-hold-lifecycle/SKILL.md" "decision lifecycle does not own options-document filing"
   assert_grep 'secondmate-owned work item deliberately shows only a limited ownership note' "$ROOT/docs/dashboard-service.md" "service doc omits the accepted secondmate detail boundary"
   pass "the service is documented and wired into the operating contract"
@@ -604,7 +627,7 @@ test_subscription_usage_panel
 test_inline_config_is_script_safe
 test_refs_sidecar_and_rich_work_item_detail
 test_decision_detail_options_and_validated_approval
-test_decision_answers_are_qualified_by_owning_home
+test_decision_answers_are_qualified_by_home_and_origin
 test_stale_refs_are_disabled
 test_idea_pitch_and_verdicts
 test_dispatch_writes_one_durable_record
diff --git a/tests/fm-decision-hold-lifecycle.test.sh b/tests/fm-decision-hold-lifecycle.test.sh
index abda96c832a..0777a5fb60d 100755
--- a/tests/fm-decision-hold-lifecycle.test.sh
+++ b/tests/fm-decision-hold-lifecycle.test.sh
@@ -191,8 +191,8 @@ EOF
     || fail "idempotent retry duplicated the route hold"
   [ "$(grep -cE "^- \[ \] $access_hold -" "$home/data/backlog.md")" = 1 ] \
     || fail "second decision did not retain one distinct backlog identity"
-  assert_grep "Conservative route" "$home/data/decisions/route.md" "route options were not published with the hold"
-  assert_grep "Fast route" "$home/data/decisions/access.md" "access options were not published with the hold"
+  assert_grep "Conservative route" "$home/data/$id/decisions/route.md" "route options were not published with the hold"
+  assert_grep "Fast route" "$home/data/$id/decisions/access.md" "access options were not published with the hold"
 
   run_decisions "$home" complete "$id" route access >/dev/null \
     || fail "shared investigation completion gate failed"
@@ -485,10 +485,39 @@ EOF
   ' >/dev/null || fail "secondmate captain hold did not surface with authoritative owner: $json"
   assert_no_grep "$hold" "$parent/data/backlog.md" "secondmate hold leaked into the main backlog"
   assert_grep "$hold" "$mate/data/backlog.md" "secondmate hold left its authoritative backlog"
-  assert_grep "Conservative route" "$mate/data/decisions/release.md" "secondmate options were not published in the owning home"
+  assert_grep "Conservative route" "$mate/data/$origin/decisions/release.md" "secondmate options were not published in the owning home"
   pass "main-home and secondmate-home captain holds remain correctly routed"
 }
 
+test_same_home_same_key_decisions_are_origin_qualified() {
+  local home first second first_hold second_hold
+  home=$(make_home same-home-same-key)
+  first=sample-alpha-review
+  second=sample-beta-review
+  mkdir -p "$home/data/$first" "$home/data/$second"
+  tasks_in "$home" add "$first" "Review sample alpha" --kind scout --repo sample --start >/dev/null \
+    || fail "could not create first same-key origin"
+  tasks_in "$home" add "$second" "Review sample beta" --kind scout --repo sample --start >/dev/null \
+    || fail "could not create second same-key origin"
+  write_origin_meta "$home" "$first"
+  write_origin_meta "$home" "$second"
+  first_hold=$(run_decisions "$home" hold "$first" route \
+    --title "Choose the alpha route" --reason "captain alpha route pending" \
+    --options-file "$(write_options "$home" route "Choose the alpha route")" --repo sample) \
+    || fail "first same-key decision was not filed"
+  second_hold=$(run_decisions "$home" hold "$second" route \
+    --title "Choose the beta route" --reason "captain beta route pending" \
+    --options-file "$(write_options "$home" route "Choose the beta route")" --repo sample) \
+    || fail "second same-key decision collided with the first"
+  [ "$first_hold" = "$first-decision-route" ] || fail "first same-key hold lost its origin identity"
+  [ "$second_hold" = "$second-decision-route" ] || fail "second same-key hold lost its origin identity"
+  assert_grep "Choose the alpha route" "$home/data/$first/decisions/route.md" "first origin options were not retained"
+  assert_grep "Choose the beta route" "$home/data/$second/decisions/route.md" "second origin options were not retained"
+  cmp -s "$home/data/$first/decisions/route.md" "$home/data/$second/decisions/route.md" \
+    && fail "distinct same-key options collapsed to one document"
+  pass "same-home same-key decisions retain distinct origin-qualified documents"
+}
+
 test_overlong_captain_hold_is_non_dispatchable() {
   local home origin key hold show out rc
   home=$(make_home overlong-captain-hold)
@@ -628,5 +657,6 @@ test_visual_review_uses_shared_completion_owner
 test_none_inventory_and_resolved_prose_do_not_create_holds
 test_terminal_single_owner_status_decision_does_not_block_empty_inventory
 test_secondmate_hold_stays_in_authoritative_home
+test_same_home_same_key_decisions_are_origin_qualified
 test_overlong_captain_hold_is_non_dispatchable
 test_resolve_matches_quoted_blocked_by_edges

From 7768227402d3f9c44d58d939291602477d8fcf6c Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 11:34:54 -0400
Subject: [PATCH 06/24] no-mistakes(review): Align dashboard contracts and
 unregister disabled watchers

---
 bin/fm-dash-inbox.sh      |  3 ++-
 bin/fm-dash-install.sh    | 22 ++++++++++++++++------
 bin/fm-dash-serve.mjs     | 10 ++++++----
 docs/dashboard-service.md |  6 +++---
 tests/fm-dash.test.sh     | 17 +++++++++++++----
 5 files changed, 40 insertions(+), 18 deletions(-)

diff --git a/bin/fm-dash-inbox.sh b/bin/fm-dash-inbox.sh
index 615f0fd58f2..8524d4b8a62 100755
--- a/bin/fm-dash-inbox.sh
+++ b/bin/fm-dash-inbox.sh
@@ -5,7 +5,8 @@
 # fm-dash-command.v1 records written by bin/fm-dash-serve.mjs and claiming them
 # durably. "claim" prints each record before archiving it under
 # state/dash-inbox/archive/ (newest 50 kept), so an interruption can re-surface
-# a command but can never silently lose one. Consumption semantics are owned by the capacity skill:
+# a command but can never silently lose one. Delivery is at-least-once across
+# interruption, and the capacity skill requires idempotency checks before handling re-surfaced records:
 # each claimed prompt is the captain's approval of that CAP action ID with all
 # of that skill's authority limits, never destructive or merge authority.
 #
diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index b359b3c5562..898df014c97 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -12,17 +12,18 @@
 # Usage: fm-dash-install.sh <command> [options]
 #   install       write config, launchd agent, tailscale serve mapping, and the
 #                 fm-dash watcher check; idempotent, prints the stable URL
-#   uninstall     remove the serve mapping and launchd agent; keeps config and
-#                 any pending commands in state/dash-inbox/
+#   uninstall     remove the serve mapping, launchd agent, and watcher registration;
+#                 keeps config and any pending commands in state/dash-inbox/
 #   status        report agent, serve mapping, and pending-command state
 #   print-plist   print the launchd plist to stdout without installing
 #   write-check   write and register only the fm-dash watcher check
+#   unregister-check  remove only the fm-dash watcher registration
 # Options:
 #   --port <n>        local loopback port for the service (default 8847)
 #   --serve-port <n>  tailnet HTTPS port for tailscale serve (default 8443)
 #   --captain <login> authorized tailnet login; repeatable; defaults to the
 #                     tailnet self login reported by tailscale status
-#   --read-only       serve the dashboard without command dispatch and skip the
+#   --read-only       serve the dashboard without command dispatch and remove the
 #                     watcher check; for running the service ahead of command wiring
 # FM_HOME selects the home; scripts and the service always run from this
 # checkout. docs/dashboard-service.md owns the architecture and evidence.
@@ -35,6 +36,7 @@ STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
 CONFIG_DIR="$FM_HOME/config"
 CONFIG="$CONFIG_DIR/dash.json"
 CHECK="$STATE/fm-dash.check.sh"
+CHECK_TRUST="$STATE/fm-dash.check-trust"
 DEFAULT_PORT=8847
 DEFAULT_SERVE_PORT=8443
 
@@ -204,6 +206,10 @@ SHIM
   "$SCRIPT_DIR/fm-check-register.sh" fm-dash || err "could not register the fm-dash watcher check"
 }
 
+unregister_check() {
+  rm -f -- "$CHECK" "$CHECK_TRUST" || err "could not unregister the fm-dash watcher check"
+}
+
 cmd_install() {
   local port=$DEFAULT_PORT serve_port=$DEFAULT_SERVE_PORT read_only=false captains=() label plist_path node_path dnsname
   while [ $# -gt 0 ]; do
@@ -227,9 +233,11 @@ cmd_install() {
   fi
 
   write_config "$port" "$read_only" "${captains[@]}"
-  # A read-only install serves the dashboard without command dispatch, so the
-  # watcher check that surfaces clicked commands is not registered.
-  [ "$read_only" = true ] || write_check
+  if [ "$read_only" = true ]; then
+    unregister_check
+  else
+    write_check
+  fi
 
   label=$(home_label)
   plist_path="$HOME/Library/LaunchAgents/$label.plist"
@@ -273,6 +281,7 @@ cmd_uninstall() {
   fi
   launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
   rm -f "$plist_path"
+  unregister_check
   printf 'uninstalled: %s (config and any pending commands were kept)\n' "$label"
 }
 
@@ -298,5 +307,6 @@ case "${1:-}" in
   status) shift; cmd_status ;;
   print-plist) shift; render_plist "$(home_label)" "$(node_bin)" "$STATE" ;;
   write-check) shift; write_check ;;
+  unregister-check) shift; unregister_check ;;
   *) usage 2 >&2 ;;
 esac
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
index cebbac71b3f..279cbd3355f 100755
--- a/bin/fm-dash-serve.mjs
+++ b/bin/fm-dash-serve.mjs
@@ -21,10 +21,12 @@
  * Tailscale-User-Login header injected by tailscale serve to match a login in
  * config/dash.json. Requests without a matching identity get 403 and cause no
  * writes. Dispatch accepts only known CAP-NN identifiers that are present in
- * the currently served dashboard AND in the fixed one-click allowlist below;
- * free-text commands are structurally impossible and unknown or future action
- * IDs are refused (route those through captain chat). The server binds
- * 127.0.0.1 only, so the only remote path in is the tailnet proxy.
+ * the currently served dashboard AND in the fixed one-click allowlist below.
+ * The only free text accepted anywhere is bounded captain-authored content: an
+ * idea suggestion or decision custom answer delivered to firstmate as data,
+ * never interpreted or executed by this service. Unknown or future action IDs
+ * are refused (route those through captain chat). The server binds 127.0.0.1
+ * only, so the only remote path in is the tailnet proxy.
  *
  * Environment: FM_HOME selects the home (defaults to this checkout);
  * FM_DASH_CAPACITY_ARGS appends producer fixture args for tests ONLY and must
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index 0fe9657d520..2146935c1c3 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -60,7 +60,7 @@ Dispatch is validated against records the server itself reads:
 - A decision answer must name a decision in the producer's current-generation refs sidecar, and its integer option index must match the options document the server just parsed; a custom answer is accepted only for a decision with that document and is bounded to 2,000 characters.
 - Decision answers persist and deduplicate against an owner-qualified home, origin, and key so equal keys from different origins or homes remain independently routable after refs regenerate.
 - An idea verdict must name an idea currently listed in `data/ideas/idea-backlog.md` and one of the approve, deny, or suggest verbs; on approval, firstmate creates the work item(s) through the normal backlog lifecycle - the service itself never creates work.
-- The only free text accepted is a bounded idea-suggestion note or decision custom answer, which is captain-authored data for firstmate, never a command the service interprets or executes.
+- The only free text accepted anywhere is bounded captain-authored content: an idea-suggestion note or decision custom answer authenticated as above and delivered as data for Firstmate, never interpreted or executed by the service.
 - A newer approve or deny verdict is published under a fresh immutable inbox name before the unchanged older pending verdict is removed, while suggestions remain additive.
 - Destructive, irreversible, and security-sensitive choices stay in captain chat structurally: no current `CAP-NN` prompt grants such authority, the capacity skill forbids treating a dashboard approval as merge or discard authority, decision records carry an explicit re-confirm-in-chat boundary for destructive consequences, and firstmate re-resolves every claimed command through the normal lifecycle before acting.
 
@@ -101,10 +101,10 @@ bin/fm-dash-install.sh status
 bin/fm-dash-install.sh uninstall
 ```
 
-A read-only install is the right shape for running the service ahead of command-consumption wiring: the page, detail views, refresh, and auto-render all work, while every mutation route refuses.
+A read-only install is the right shape for running the service ahead of command-consumption wiring: the page, detail views, refresh, and auto-render all work, every mutation route refuses, and any watcher registration from a prior writable install is removed.
 
 Install is idempotent and prints the stable URL, `https://<machine>.<tailnet>.ts.net:8443/`.
-Uninstall removes the serve mapping and launchd agent but keeps `config/dash.json` and any pending commands.
+Uninstall removes the serve mapping, launchd agent, watcher check, and watcher trust registration but keeps `config/dash.json` and any pending commands.
 The launchd agent logs to `state/dash-serve.log`.
 On a non-macOS host the installer refuses and the service can be run under the local init system with the same tailscale serve mapping.
 
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index 6212eeef5da..4266c8397e3 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -568,18 +568,23 @@ EOF
 }
 
 test_check_shim_wakes_only_when_pending() {
-  local out
+  local out pending_record
   FM_HOME="$HOME_DIR" "$INSTALL_SH" write-check >/dev/null || fail "write-check failed"
   [ -f "$HOME_DIR/state/fm-dash.check-trust" ] || fail "write-check did not register the check"
   out=$(sh "$HOME_DIR/state/fm-dash.check.sh")
   [ -z "$out" ] || fail "check shim woke with an empty inbox: $out"
-  printf '{"schema":"fm-dash-command.v1","id":"CAP-06","prompt":"x"}\n' > "$HOME_DIR/state/dash-inbox/1-test-CAP-06.json"
+  pending_record="$HOME_DIR/state/dash-inbox/1-test-CAP-06.json"
+  printf '{"schema":"fm-dash-command.v1","id":"CAP-06","prompt":"x"}\n' > "$pending_record"
   out=$(sh "$HOME_DIR/state/fm-dash.check.sh")
   assert_contains "$out" '1 captain command(s) pending' "check shim did not report the pending command"
   assert_contains "$out" 'fm-dash-inbox.sh claim' "check shim does not name the claim helper"
   [ "$(printf '%s\n' "$out" | wc -l | tr -d ' ')" = 1 ] || fail "check shim printed more than one line"
-  rm -f "$HOME_DIR/state/dash-inbox/1-test-CAP-06.json"
-  pass "the registered watcher check wakes firstmate only while commands are pending"
+  FM_HOME="$HOME_DIR" "$INSTALL_SH" unregister-check >/dev/null || fail "unregister-check failed"
+  [ ! -e "$HOME_DIR/state/fm-dash.check.sh" ] || fail "unregister-check left the watcher check installed"
+  [ ! -e "$HOME_DIR/state/fm-dash.check-trust" ] || fail "unregister-check left the watcher trust registration installed"
+  [ -f "$pending_record" ] || fail "unregister-check removed a pending inbox record"
+  rm -f "$pending_record"
+  pass "watcher registration follows writable mode without deleting pending commands"
 }
 
 test_installer_plist_and_funnel_stance() {
@@ -599,6 +604,8 @@ test_installer_plist_and_funnel_stance() {
   assert_contains "$funnel_check" 'could not verify Funnel state' "Funnel verification does not report unreadable status"
   assert_contains "$funnel_check" 'process.exit(1)' "Funnel verification does not fail closed"
   assert_contains "$(sed -n '/if ! assert_no_funnel/,/fi/p' "$INSTALL_SH")" 'serve --https="$serve_port" off' "failed Funnel verification does not tear down the mapping"
+  assert_contains "$(sed -n '/write_config .*port/,/label=/p' "$INSTALL_SH")" 'unregister_check' "read-only install does not unregister a prior writable watcher"
+  assert_contains "$(sed -n '/^cmd_uninstall()/,/^cmd_status()/p' "$INSTALL_SH")" 'unregister_check' "uninstall does not unregister the watcher"
   escaped_home="$HOME_DIR/xml & < >"
   plist=$(FM_HOME="$escaped_home" FM_ROOT_OVERRIDE="$HOME_DIR/root & < >" "$INSTALL_SH" print-plist) || fail "print-plist with XML metacharacters failed"
   assert_contains "$plist" "$HOME_DIR/xml &amp; &lt; &gt;" "plist did not XML-escape FM_HOME"
@@ -617,6 +624,8 @@ test_service_contract_docs_and_ownership() {
   assert_grep 'data/<origin>/decisions/<key>.md' "$ROOT/docs/dashboard-service.md" "service doc does not own the origin-qualified decision-options format"
   assert_grep 'hold --options-file' "$ROOT/.agents/skills/decision-hold-lifecycle/SKILL.md" "decision lifecycle does not own options-document filing"
   assert_grep 'secondmate-owned work item deliberately shows only a limited ownership note' "$ROOT/docs/dashboard-service.md" "service doc omits the accepted secondmate detail boundary"
+  assert_grep 'only free text accepted anywhere is bounded captain-authored content' "$ROOT/docs/dashboard-service.md" "service doc omits the bounded free-text boundary"
+  assert_grep 'at-least-once' "$INBOX_SH" "inbox consumer omits its delivery contract"
   pass "the service is documented and wired into the operating contract"
 }
 

From 6ba0a63ab79d94b5ece9f4d34ed4ff2f32099c4c Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 11:41:11 -0400
Subject: [PATCH 07/24] no-mistakes(review): Persist and clean up dashboard
 serve ports

---
 bin/fm-dash-install.sh    | 48 ++++++++++++++++++++++++-------
 bin/fm-dash-serve.mjs     |  3 +-
 docs/configuration.md     |  2 +-
 docs/dashboard-service.md |  1 +
 tests/fm-dash.test.sh     | 60 ++++++++++++++++++++++++++++++++++++++-
 5 files changed, 101 insertions(+), 13 deletions(-)

diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index 898df014c97..4ccde2f2abb 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -138,18 +138,37 @@ assert_no_funnel() {
 }
 
 write_config() {
-  local port=$1 read_only=$2
-  shift 2
+  local port=$1 serve_port=$2 read_only=$3
+  shift 3
   mkdir -p "$CONFIG_DIR"
   node -e '
     const fs = require("node:fs");
-    const [config, port, readOnly, ...logins] = process.argv.slice(1);
-    const payload = { port: Number(port), captain_logins: logins, read_only: readOnly === "true" };
+    const [config, port, servePort, readOnly, ...logins] = process.argv.slice(1);
+    const payload = { port: Number(port), serve_port: Number(servePort), captain_logins: logins, read_only: readOnly === "true" };
     fs.writeFileSync(config, JSON.stringify(payload, null, 2) + "\n", { mode: 0o600 });
-  ' "$CONFIG" "$port" "$read_only" "$@" || err "could not write $CONFIG"
+  ' "$CONFIG" "$port" "$serve_port" "$read_only" "$@" || err "could not write $CONFIG"
   chmod 600 "$CONFIG" 2>/dev/null || true
 }
 
+configured_serve_port() {
+  [ -f "$CONFIG" ] || return 0
+  node -e '
+    const fs = require("node:fs");
+    try {
+      const parsed = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+      const port = parsed.serve_port === undefined ? Number(process.argv[2]) : parsed.serve_port;
+      if (!Number.isInteger(port) || port < 1 || port > 65535) process.exit(1);
+      console.log(port);
+    } catch {
+      process.exit(1);
+    }
+  ' "$CONFIG" "$DEFAULT_SERVE_PORT"
+}
+
+disable_serve_port() {
+  "$(tailscale_bin)" serve --https="$1" off >/dev/null 2>&1 || true
+}
+
 render_plist() {
   local label node_path log_dir fm_root fm_home
   label=$(xml_escape "$1")
@@ -211,7 +230,7 @@ unregister_check() {
 }
 
 cmd_install() {
-  local port=$DEFAULT_PORT serve_port=$DEFAULT_SERVE_PORT read_only=false captains=() label plist_path node_path dnsname
+  local port=$DEFAULT_PORT serve_port=$DEFAULT_SERVE_PORT previous_serve_port read_only=false captains=() label plist_path node_path dnsname
   while [ $# -gt 0 ]; do
     case "$1" in
       --port) port=${2:?--port needs a value}; shift 2 ;;
@@ -225,6 +244,7 @@ cmd_install() {
   command -v launchctl >/dev/null 2>&1 || err "launchctl is required"
   node_path=$(node_bin)
   tailscale_bin >/dev/null
+  previous_serve_port=$(configured_serve_port) || err "could not read the previously configured dashboard serve port"
 
   if [ "${#captains[@]}" -eq 0 ]; then
     local self_login
@@ -232,7 +252,7 @@ cmd_install() {
     captains=("$self_login")
   fi
 
-  write_config "$port" "$read_only" "${captains[@]}"
+  write_config "$port" "$serve_port" "$read_only" "${captains[@]}"
   if [ "$read_only" = true ]; then
     unregister_check
   else
@@ -255,9 +275,12 @@ cmd_install() {
   "$(tailscale_bin)" serve --bg --https="$serve_port" "http://127.0.0.1:$port" >/dev/null \
     || err "tailscale serve refused the mapping; is tailscale up?"
   if ! assert_no_funnel "$serve_port"; then
-    "$(tailscale_bin)" serve --https="$serve_port" off >/dev/null 2>&1 || true
+    disable_serve_port "$serve_port"
     err "could not verify tailnet-only exposure for port $serve_port; the mapping was removed - this service must stay tailnet-only"
   fi
+  if [ -n "$previous_serve_port" ] && [ "$previous_serve_port" != "$serve_port" ]; then
+    disable_serve_port "$previous_serve_port"
+  fi
 
   dnsname=$(tailscale_self_dnsname) || err "could not resolve this machine's tailnet name"
   printf 'installed: launchd agent %s\n' "$label"
@@ -266,7 +289,7 @@ cmd_install() {
 }
 
 cmd_uninstall() {
-  local serve_port=$DEFAULT_SERVE_PORT label plist_path
+  local serve_port="" configured_port label plist_path
   while [ $# -gt 0 ]; do
     case "$1" in
       --serve-port) serve_port=${2:?--serve-port needs a value}; shift 2 ;;
@@ -274,10 +297,15 @@ cmd_uninstall() {
     esac
   done
   [ "$(uname)" = Darwin ] || err "uninstall requires macOS launchd"
+  configured_port=$(configured_serve_port) || err "could not read the configured dashboard serve port"
+  [ -n "$serve_port" ] || serve_port=${configured_port:-$DEFAULT_SERVE_PORT}
   label=$(home_label)
   plist_path="$HOME/Library/LaunchAgents/$label.plist"
   if command -v tailscale >/dev/null 2>&1; then
-    tailscale serve --https="$serve_port" off >/dev/null 2>&1 || true
+    disable_serve_port "$serve_port"
+    if [ -n "$configured_port" ] && [ "$configured_port" != "$serve_port" ]; then
+      disable_serve_port "$configured_port"
+    fi
   fi
   launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
   rm -f "$plist_path"
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
index 279cbd3355f..9c00a8492e6 100755
--- a/bin/fm-dash-serve.mjs
+++ b/bin/fm-dash-serve.mjs
@@ -77,7 +77,8 @@ function usage(exitCode = 0) {
 
 Serve the FM_HOME capacity dashboard on 127.0.0.1 for a tailnet-only
 tailscale serve proxy. Config lives in config/dash.json:
-  {"port": 8847, "captain_logins": ["captain@example.com"],
+  {"port": 8847, "serve_port": 8443,
+   "captain_logins": ["captain@example.com"],
    "read_only": false, "auto_refresh_seconds": 900}
 --port overrides the configured port. read_only=true refuses dispatch and
 serves the page without send buttons, for running the service before command
diff --git a/docs/configuration.md b/docs/configuration.md
index ad9fd95a340..cbb185f50ea 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -105,7 +105,7 @@ See [`wedge-alarm.md`](wedge-alarm.md) for the channel reference and macOS verif
 ## Capacity dashboard service (config/dash.json)
 
 The optional persistent dashboard service publishes `data/capacity-dashboard.html` tailnet-only at one stable HTTPS URL, adds one-click `CAP-NN` dispatch, clickable de-anonymized work-item and decision detail views, idea verdicts over `data/ideas/`, and a server-side refresh, and delivers clicked commands to the running Firstmate through durable `state/dash-inbox/` records surfaced by the registered `fm-dash` watcher check.
-`config/dash.json` (local, gitignored, written by `bin/fm-dash-install.sh`) holds `port` (loopback service port, default 8847), `captain_logins` (the tailnet logins allowed to reach the service), `read_only` (serve and auto-render without any mutation route), and `auto_refresh_seconds` (producer rerun interval, default 900, 0 disables); the service fails closed without a matching `Tailscale-User-Login` identity.
+`config/dash.json` (local, gitignored, written by `bin/fm-dash-install.sh`) holds `port` (loopback service port, default 8847), `serve_port` (active tailnet HTTPS port, default 8443), `captain_logins` (the tailnet logins allowed to reach the service), `read_only` (serve and auto-render without any mutation route), and `auto_refresh_seconds` (producer rerun interval, default 900, 0 disables); the service fails closed without a matching `Tailscale-User-Login` identity.
 The service reads the producer's opt-in `state/dash-refs.json` identity sidecar (`fm-capacity.mjs --refs`) to enrich the served page; the on-disk dashboard itself stays identity-opaque.
 `bin/fm-dash-serve.mjs --help` owns routes and the one-click allowlist, `bin/fm-dash-install.sh --help` owns launchd persistence and the never-Funnel tailscale serve wiring, `bin/fm-dash-inbox.sh --help` owns command consumption, and [`dashboard-service.md`](dashboard-service.md) owns the architecture and trust design.
 
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index 2146935c1c3..ae3d9baea5f 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -104,6 +104,7 @@ bin/fm-dash-install.sh uninstall
 A read-only install is the right shape for running the service ahead of command-consumption wiring: the page, detail views, refresh, and auto-render all work, every mutation route refuses, and any watcher registration from a prior writable install is removed.
 
 Install is idempotent and prints the stable URL, `https://<machine>.<tailnet>.ts.net:8443/`.
+Changing `--serve-port` removes the previously recorded mapping after the replacement passes the never-Funnel verification.
 Uninstall removes the serve mapping, launchd agent, watcher check, and watcher trust registration but keeps `config/dash.json` and any pending commands.
 The launchd agent logs to `state/dash-serve.log`.
 On a non-macOS host the installer refuses and the service can be run under the local init system with the same tailscale serve mapping.
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index 4266c8397e3..ce99d6ae781 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -603,7 +603,7 @@ test_installer_plist_and_funnel_stance() {
   assert_contains "$funnel_check" 'unsupported tailscale serve status schema' "Funnel verification does not reject unexpected schemas"
   assert_contains "$funnel_check" 'could not verify Funnel state' "Funnel verification does not report unreadable status"
   assert_contains "$funnel_check" 'process.exit(1)' "Funnel verification does not fail closed"
-  assert_contains "$(sed -n '/if ! assert_no_funnel/,/fi/p' "$INSTALL_SH")" 'serve --https="$serve_port" off' "failed Funnel verification does not tear down the mapping"
+  assert_contains "$(sed -n '/if ! assert_no_funnel/,/fi/p' "$INSTALL_SH")" 'disable_serve_port "$serve_port"' "failed Funnel verification does not tear down the mapping"
   assert_contains "$(sed -n '/write_config .*port/,/label=/p' "$INSTALL_SH")" 'unregister_check' "read-only install does not unregister a prior writable watcher"
   assert_contains "$(sed -n '/^cmd_uninstall()/,/^cmd_status()/p' "$INSTALL_SH")" 'unregister_check' "uninstall does not unregister the watcher"
   escaped_home="$HOME_DIR/xml & < >"
@@ -613,6 +613,63 @@ test_installer_plist_and_funnel_stance() {
   pass "the launchd agent survives reboots and the installer is structurally funnel-free"
 }
 
+test_installer_tracks_custom_serve_port() {
+  local fake_bin install_home launch_home tailscale_log tailscale_state
+  fake_bin="$TMP_ROOT/fake-bin"
+  install_home="$TMP_ROOT/install-home"
+  launch_home="$TMP_ROOT/launch-home"
+  tailscale_log="$TMP_ROOT/tailscale.log"
+  tailscale_state="$TMP_ROOT/tailscale.state"
+  mkdir -p "$fake_bin" "$install_home" "$launch_home"
+  cat > "$fake_bin/uname" <<'EOF'
+#!/bin/sh
+echo Darwin
+EOF
+  cat > "$fake_bin/launchctl" <<'EOF'
+#!/bin/sh
+exit 0
+EOF
+  cat > "$fake_bin/tailscale" <<'EOF'
+#!/bin/sh
+if [ "$1" = status ] && [ "${2:-}" = --json ]; then
+  printf '%s\n' '{"Self":{"UserID":1,"DNSName":"dash.tail.ts.net."},"User":{"1":{"LoginName":"captain@example.com"}}}'
+elif [ "$1" = serve ] && [ "${2:-}" = status ] && [ "${3:-}" = --json ]; then
+  port=$(cat "$TAILSCALE_STATE")
+  printf '{"TCP":{"%s":{"HTTPS":true}},"Web":{"dash.tail.ts.net:%s":{}},"AllowFunnel":{"dash.tail.ts.net:%s":false}}\n' "$port" "$port" "$port"
+elif [ "$1" = serve ] && [ "${2:-}" = --bg ]; then
+  port=${3#--https=}
+  printf '%s\n' "$port" > "$TAILSCALE_STATE"
+  printf 'map %s\n' "$port" >> "$TAILSCALE_LOG"
+elif [ "$1" = serve ] && [ "${2#--https=}" != "$2" ] && [ "${3:-}" = off ]; then
+  port=${2#--https=}
+  printf 'off %s\n' "$port" >> "$TAILSCALE_LOG"
+  if [ -f "$TAILSCALE_STATE" ] && [ "$(cat "$TAILSCALE_STATE")" = "$port" ]; then
+    : > "$TAILSCALE_STATE"
+  fi
+else
+  exit 1
+fi
+EOF
+  chmod 700 "$fake_bin/uname" "$fake_bin/launchctl" "$fake_bin/tailscale"
+  HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --read-only --port 18847 --serve-port 19443 --captain "$CAPTAIN" >/dev/null \
+    || fail "custom-port install failed"
+  node -e 'const c=require(process.argv[1]); if(c.serve_port !== 19443) process.exit(1)' "$install_home/config/dash.json" \
+    || fail "install did not persist the custom serve port"
+  : > "$tailscale_log"
+  HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --read-only --port 18847 --serve-port 19553 --captain "$CAPTAIN" >/dev/null \
+    || fail "custom-port replacement install failed"
+  assert_grep 'off 19443' "$tailscale_log" "port-change install did not remove the recorded previous mapping"
+  node -e 'const c=require(process.argv[1]); if(c.serve_port !== 19553) process.exit(1)' "$install_home/config/dash.json" \
+    || fail "replacement install did not persist the active serve port"
+  : > "$tailscale_log"
+  HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" uninstall >/dev/null || fail "plain uninstall failed"
+  assert_grep 'off 19553' "$tailscale_log" "plain uninstall did not remove the recorded active mapping"
+  pass "custom serve ports persist and old mappings are removed"
+}
+
 test_service_contract_docs_and_ownership() {
   assert_present "$ROOT/docs/dashboard-service.md" "dashboard service doc is missing"
   assert_grep 'dash-inbox' "$ROOT/docs/dashboard-service.md" "service doc omits the inbound channel"
@@ -646,6 +703,7 @@ test_inbox_list_claim_and_archive
 test_read_only_mode_fails_safe
 test_check_shim_wakes_only_when_pending
 test_installer_plist_and_funnel_stance
+test_installer_tracks_custom_serve_port
 test_service_contract_docs_and_ownership
 
 echo "fm-dash tests passed"

From aa82bd59f249795cf1b59f78520730ba194da7ad Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 11:44:55 -0400
Subject: [PATCH 08/24] no-mistakes(review): Make dashboard port changes
 transactional

---
 bin/fm-dash-install.sh    | 24 ++++++++++++++++--------
 docs/dashboard-service.md |  2 +-
 tests/fm-dash.test.sh     | 25 ++++++++++++++++++++++++-
 3 files changed, 41 insertions(+), 10 deletions(-)

diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index 4ccde2f2abb..c0d599e8326 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -146,7 +146,7 @@ write_config() {
     const [config, port, servePort, readOnly, ...logins] = process.argv.slice(1);
     const payload = { port: Number(port), serve_port: Number(servePort), captain_logins: logins, read_only: readOnly === "true" };
     fs.writeFileSync(config, JSON.stringify(payload, null, 2) + "\n", { mode: 0o600 });
-  ' "$CONFIG" "$port" "$serve_port" "$read_only" "$@" || err "could not write $CONFIG"
+  ' "$CONFIG" "$port" "$serve_port" "$read_only" "$@" || return 1
   chmod 600 "$CONFIG" 2>/dev/null || true
 }
 
@@ -166,7 +166,7 @@ configured_serve_port() {
 }
 
 disable_serve_port() {
-  "$(tailscale_bin)" serve --https="$1" off >/dev/null 2>&1 || true
+  "$(tailscale_bin)" serve --https="$1" off >/dev/null 2>&1
 }
 
 render_plist() {
@@ -230,7 +230,7 @@ unregister_check() {
 }
 
 cmd_install() {
-  local port=$DEFAULT_PORT serve_port=$DEFAULT_SERVE_PORT previous_serve_port read_only=false captains=() label plist_path node_path dnsname
+  local port=$DEFAULT_PORT serve_port=$DEFAULT_SERVE_PORT recorded_serve_port previous_serve_port read_only=false captains=() label plist_path node_path dnsname
   while [ $# -gt 0 ]; do
     case "$1" in
       --port) port=${2:?--port needs a value}; shift 2 ;;
@@ -252,7 +252,8 @@ cmd_install() {
     captains=("$self_login")
   fi
 
-  write_config "$port" "$serve_port" "$read_only" "${captains[@]}"
+  recorded_serve_port=${previous_serve_port:-$serve_port}
+  write_config "$port" "$recorded_serve_port" "$read_only" "${captains[@]}" || err "could not write $CONFIG"
   if [ "$read_only" = true ]; then
     unregister_check
   else
@@ -275,11 +276,18 @@ cmd_install() {
   "$(tailscale_bin)" serve --bg --https="$serve_port" "http://127.0.0.1:$port" >/dev/null \
     || err "tailscale serve refused the mapping; is tailscale up?"
   if ! assert_no_funnel "$serve_port"; then
-    disable_serve_port "$serve_port"
+    disable_serve_port "$serve_port" || err "could not remove the unverified mapping for port $serve_port"
     err "could not verify tailnet-only exposure for port $serve_port; the mapping was removed - this service must stay tailnet-only"
   fi
   if [ -n "$previous_serve_port" ] && [ "$previous_serve_port" != "$serve_port" ]; then
-    disable_serve_port "$previous_serve_port"
+    if ! disable_serve_port "$previous_serve_port"; then
+      disable_serve_port "$serve_port" || true
+      err "could not remove the previous dashboard mapping for port $previous_serve_port; the replacement was removed and the previous port remains configured"
+    fi
+    if ! write_config "$port" "$serve_port" "$read_only" "${captains[@]}"; then
+      disable_serve_port "$serve_port" || true
+      err "could not persist the replacement dashboard serve port; the replacement mapping was removed"
+    fi
   fi
 
   dnsname=$(tailscale_self_dnsname) || err "could not resolve this machine's tailnet name"
@@ -302,9 +310,9 @@ cmd_uninstall() {
   label=$(home_label)
   plist_path="$HOME/Library/LaunchAgents/$label.plist"
   if command -v tailscale >/dev/null 2>&1; then
-    disable_serve_port "$serve_port"
+    disable_serve_port "$serve_port" || err "could not remove the dashboard mapping for port $serve_port"
     if [ -n "$configured_port" ] && [ "$configured_port" != "$serve_port" ]; then
-      disable_serve_port "$configured_port"
+      disable_serve_port "$configured_port" || err "could not remove the configured dashboard mapping for port $configured_port"
     fi
   fi
   launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index ae3d9baea5f..9f6aa34c1bf 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -104,7 +104,7 @@ bin/fm-dash-install.sh uninstall
 A read-only install is the right shape for running the service ahead of command-consumption wiring: the page, detail views, refresh, and auto-render all work, every mutation route refuses, and any watcher registration from a prior writable install is removed.
 
 Install is idempotent and prints the stable URL, `https://<machine>.<tailnet>.ts.net:8443/`.
-Changing `--serve-port` removes the previously recorded mapping after the replacement passes the never-Funnel verification.
+Changing `--serve-port` creates and verifies the replacement, removes the previously recorded mapping, and only then records the new active port.
 Uninstall removes the serve mapping, launchd agent, watcher check, and watcher trust registration but keeps `config/dash.json` and any pending commands.
 The launchd agent logs to `state/dash-serve.log`.
 On a non-macOS host the installer refuses and the service can be run under the local init system with the same tailscale serve mapping.
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index ce99d6ae781..93519bd9055 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -635,9 +635,15 @@ if [ "$1" = status ] && [ "${2:-}" = --json ]; then
   printf '%s\n' '{"Self":{"UserID":1,"DNSName":"dash.tail.ts.net."},"User":{"1":{"LoginName":"captain@example.com"}}}'
 elif [ "$1" = serve ] && [ "${2:-}" = status ] && [ "${3:-}" = --json ]; then
   port=$(cat "$TAILSCALE_STATE")
-  printf '{"TCP":{"%s":{"HTTPS":true}},"Web":{"dash.tail.ts.net:%s":{}},"AllowFunnel":{"dash.tail.ts.net:%s":false}}\n' "$port" "$port" "$port"
+  funnel=false
+  [ "${TAILSCALE_FUNNEL_PORT:-}" != "$port" ] || funnel=true
+  printf '{"TCP":{"%s":{"HTTPS":true}},"Web":{"dash.tail.ts.net:%s":{}},"AllowFunnel":{"dash.tail.ts.net:%s":%s}}\n' "$port" "$port" "$port" "$funnel"
 elif [ "$1" = serve ] && [ "${2:-}" = --bg ]; then
   port=${3#--https=}
+  if [ "${TAILSCALE_FAIL_MAP_PORT:-}" = "$port" ]; then
+    printf 'map-failed %s\n' "$port" >> "$TAILSCALE_LOG"
+    exit 1
+  fi
   printf '%s\n' "$port" > "$TAILSCALE_STATE"
   printf 'map %s\n' "$port" >> "$TAILSCALE_LOG"
 elif [ "$1" = serve ] && [ "${2#--https=}" != "$2" ] && [ "${3:-}" = off ]; then
@@ -657,6 +663,23 @@ EOF
   node -e 'const c=require(process.argv[1]); if(c.serve_port !== 19443) process.exit(1)' "$install_home/config/dash.json" \
     || fail "install did not persist the custom serve port"
   : > "$tailscale_log"
+  if HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" TAILSCALE_FAIL_MAP_PORT=19663 PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --read-only --port 18847 --serve-port 19663 --captain "$CAPTAIN" >/dev/null 2>&1; then
+    fail "failed replacement mapping was reported as installed"
+  fi
+  node -e 'const c=require(process.argv[1]); if(c.serve_port !== 19443) process.exit(1)' "$install_home/config/dash.json" \
+    || fail "failed replacement mapping overwrote the recorded active port"
+  assert_no_grep 'off 19443' "$tailscale_log" "failed replacement mapping removed the recorded active mapping"
+  : > "$tailscale_log"
+  if HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" TAILSCALE_FUNNEL_PORT=19664 PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --read-only --port 18847 --serve-port 19664 --captain "$CAPTAIN" >/dev/null 2>&1; then
+    fail "Funnel-exposed replacement mapping was reported as installed"
+  fi
+  node -e 'const c=require(process.argv[1]); if(c.serve_port !== 19443) process.exit(1)' "$install_home/config/dash.json" \
+    || fail "failed Funnel verification overwrote the recorded active port"
+  assert_grep 'off 19664' "$tailscale_log" "failed Funnel verification did not remove the replacement mapping"
+  assert_no_grep 'off 19443' "$tailscale_log" "failed Funnel verification removed the recorded active mapping"
+  : > "$tailscale_log"
   HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
     "$INSTALL_SH" install --read-only --port 18847 --serve-port 19553 --captain "$CAPTAIN" >/dev/null \
     || fail "custom-port replacement install failed"

From 75b09c5e4ec3388af9d6f4c001278a29ab275a9b Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 11:52:40 -0400
Subject: [PATCH 09/24] no-mistakes(review): Make dashboard installation fully
 transactional

---
 bin/fm-dash-install.sh    | 169 +++++++++++++++++++++++++++++++-------
 docs/dashboard-service.md |   2 +-
 tests/fm-dash.test.sh     | 103 +++++++++++++++++++----
 3 files changed, 227 insertions(+), 47 deletions(-)

diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index c0d599e8326..ee70bbfd275 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -39,6 +39,24 @@ CHECK="$STATE/fm-dash.check.sh"
 CHECK_TRUST="$STATE/fm-dash.check-trust"
 DEFAULT_PORT=8847
 DEFAULT_SERVE_PORT=8443
+TX_ACTIVE=false
+TX_CONFIG_BACKUP=""
+TX_CONFIG_EXISTED=false
+TX_PLIST_BACKUP=""
+TX_PLIST_EXISTED=false
+TX_CHECK_BACKUP=""
+TX_CHECK_EXISTED=false
+TX_TRUST_BACKUP=""
+TX_TRUST_EXISTED=false
+TX_CONFIG_STAGE=""
+TX_PLIST_STAGE=""
+TX_PRIOR_LOADED=false
+TX_PREVIOUS_PORT=""
+TX_PREVIOUS_SERVE_PORT=""
+TX_NEW_SERVE_PORT=""
+TX_NEW_MAPPING=false
+TX_LABEL=""
+TX_PLIST_PATH=""
 
 usage() {
   sed -n 's/^# \{0,1\}//p' "${BASH_SOURCE[0]}" | sed -n '2,29p'
@@ -137,17 +155,18 @@ assert_no_funnel() {
   ' "$serve_port"
 }
 
-write_config() {
-  local port=$1 serve_port=$2 read_only=$3
-  shift 3
-  mkdir -p "$CONFIG_DIR"
+write_config_file() {
+  local target=$1 port=$2 serve_port=$3 read_only=$4
+  shift 4
   node -e '
     const fs = require("node:fs");
     const [config, port, servePort, readOnly, ...logins] = process.argv.slice(1);
     const payload = { port: Number(port), serve_port: Number(servePort), captain_logins: logins, read_only: readOnly === "true" };
     fs.writeFileSync(config, JSON.stringify(payload, null, 2) + "\n", { mode: 0o600 });
-  ' "$CONFIG" "$port" "$serve_port" "$read_only" "$@" || return 1
-  chmod 600 "$CONFIG" 2>/dev/null || true
+    const verified = JSON.parse(fs.readFileSync(config, "utf8"));
+    if (verified.port !== Number(port) || verified.serve_port !== Number(servePort)) process.exit(1);
+  ' "$target" "$port" "$serve_port" "$read_only" "$@" || return 1
+  chmod 600 "$target" 2>/dev/null || true
 }
 
 configured_serve_port() {
@@ -165,10 +184,88 @@ configured_serve_port() {
   ' "$CONFIG" "$DEFAULT_SERVE_PORT"
 }
 
+configured_loopback_port() {
+  [ -f "$CONFIG" ] || return 0
+  node -e '
+    const fs = require("node:fs");
+    try {
+      const parsed = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+      const port = parsed.port === undefined ? Number(process.argv[2]) : parsed.port;
+      if (!Number.isInteger(port) || port < 1 || port > 65535) process.exit(1);
+      console.log(port);
+    } catch {
+      process.exit(1);
+    }
+  ' "$CONFIG" "$DEFAULT_PORT"
+}
+
 disable_serve_port() {
   "$(tailscale_bin)" serve --https="$1" off >/dev/null 2>&1
 }
 
+cleanup_install_transaction() {
+  local file
+  for file in "$TX_CONFIG_BACKUP" "$TX_PLIST_BACKUP" "$TX_CHECK_BACKUP" "$TX_TRUST_BACKUP" "$TX_CONFIG_STAGE" "$TX_PLIST_STAGE"; do
+    [ -z "$file" ] || rm -f -- "$file"
+  done
+}
+
+fail_staging() {
+  local message=$1
+  cleanup_install_transaction
+  err "$message"
+}
+
+restore_snapshot() {
+  local path=$1 backup=$2 existed=$3
+  if [ "$existed" = true ]; then
+    mv -f -- "$backup" "$path"
+  else
+    rm -f -- "$path"
+  fi
+}
+
+rollback_install() {
+  local status=0
+  TX_ACTIVE=false
+  if [ "$TX_NEW_MAPPING" = true ]; then
+    disable_serve_port "$TX_NEW_SERVE_PORT" || status=1
+  fi
+  restore_snapshot "$CONFIG" "$TX_CONFIG_BACKUP" "$TX_CONFIG_EXISTED" || status=1
+  restore_snapshot "$TX_PLIST_PATH" "$TX_PLIST_BACKUP" "$TX_PLIST_EXISTED" || status=1
+  restore_snapshot "$CHECK" "$TX_CHECK_BACKUP" "$TX_CHECK_EXISTED" || status=1
+  restore_snapshot "$CHECK_TRUST" "$TX_TRUST_BACKUP" "$TX_TRUST_EXISTED" || status=1
+  launchctl bootout "gui/$(id -u)/$TX_LABEL" >/dev/null 2>&1 || true
+  if [ "$TX_PRIOR_LOADED" = true ]; then
+    launchctl bootstrap "gui/$(id -u)" "$TX_PLIST_PATH" >/dev/null 2>&1 || status=1
+    launchctl kickstart "gui/$(id -u)/$TX_LABEL" >/dev/null 2>&1 || status=1
+  fi
+  if [ -n "$TX_PREVIOUS_SERVE_PORT" ]; then
+    "$(tailscale_bin)" serve --bg --https="$TX_PREVIOUS_SERVE_PORT" "http://127.0.0.1:$TX_PREVIOUS_PORT" >/dev/null 2>&1 || status=1
+    assert_no_funnel "$TX_PREVIOUS_SERVE_PORT" >/dev/null 2>&1 || status=1
+  fi
+  cleanup_install_transaction
+  return "$status"
+}
+
+fail_install() {
+  local message=$1
+  if rollback_install; then
+    err "$message; the previous dashboard installation was restored"
+  fi
+  err "$message; rollback was incomplete and requires manual inspection"
+}
+
+snapshot_file() {
+  local path=$1 template=$2 backup_var=$3 existed_var=$4 backup
+  if [ -e "$path" ]; then
+    backup=$(mktemp "$template") || return 1
+    printf -v "$backup_var" '%s' "$backup"
+    cp -p -- "$path" "$backup" || return 1
+    printf -v "$existed_var" '%s' true
+  fi
+}
+
 render_plist() {
   local label node_path log_dir fm_root fm_home
   label=$(xml_escape "$1")
@@ -230,7 +327,7 @@ unregister_check() {
 }
 
 cmd_install() {
-  local port=$DEFAULT_PORT serve_port=$DEFAULT_SERVE_PORT recorded_serve_port previous_serve_port read_only=false captains=() label plist_path node_path dnsname
+  local port=$DEFAULT_PORT serve_port=$DEFAULT_SERVE_PORT previous_serve_port read_only=false captains=() label plist_path node_path dnsname
   while [ $# -gt 0 ]; do
     case "$1" in
       --port) port=${2:?--port needs a value}; shift 2 ;;
@@ -245,6 +342,7 @@ cmd_install() {
   node_path=$(node_bin)
   tailscale_bin >/dev/null
   previous_serve_port=$(configured_serve_port) || err "could not read the previously configured dashboard serve port"
+  TX_PREVIOUS_PORT=$(configured_loopback_port) || err "could not read the previously configured dashboard loopback port"
 
   if [ "${#captains[@]}" -eq 0 ]; then
     local self_login
@@ -252,45 +350,58 @@ cmd_install() {
     captains=("$self_login")
   fi
 
-  recorded_serve_port=${previous_serve_port:-$serve_port}
-  write_config "$port" "$recorded_serve_port" "$read_only" "${captains[@]}" || err "could not write $CONFIG"
-  if [ "$read_only" = true ]; then
-    unregister_check
-  else
-    write_check
-  fi
-
   label=$(home_label)
   plist_path="$HOME/Library/LaunchAgents/$label.plist"
-  mkdir -p "$HOME/Library/LaunchAgents" "$STATE"
-  render_plist "$label" "$node_path" "$STATE" > "$plist_path"
+  mkdir -p "$CONFIG_DIR" "$HOME/Library/LaunchAgents" "$STATE"
+  TX_LABEL=$label
+  TX_PLIST_PATH=$plist_path
+  TX_PREVIOUS_SERVE_PORT=$previous_serve_port
+  TX_NEW_SERVE_PORT=$serve_port
+  launchctl print "gui/$(id -u)/$label" >/dev/null 2>&1 && TX_PRIOR_LOADED=true
+  snapshot_file "$CONFIG" "$CONFIG_DIR/.dash.json.backup.XXXXXX" TX_CONFIG_BACKUP TX_CONFIG_EXISTED || fail_staging "could not snapshot $CONFIG"
+  snapshot_file "$plist_path" "$HOME/Library/LaunchAgents/.$label.backup.XXXXXX" TX_PLIST_BACKUP TX_PLIST_EXISTED || fail_staging "could not snapshot $plist_path"
+  snapshot_file "$CHECK" "$STATE/.fm-dash.check.backup.XXXXXX" TX_CHECK_BACKUP TX_CHECK_EXISTED || fail_staging "could not snapshot $CHECK"
+  snapshot_file "$CHECK_TRUST" "$STATE/.fm-dash.check-trust.backup.XXXXXX" TX_TRUST_BACKUP TX_TRUST_EXISTED || fail_staging "could not snapshot $CHECK_TRUST"
+  TX_CONFIG_STAGE=$(mktemp "$CONFIG_DIR/.dash.json.stage.XXXXXX") || fail_staging "could not stage $CONFIG"
+  TX_PLIST_STAGE=$(mktemp "$HOME/Library/LaunchAgents/.$label.stage.XXXXXX") || fail_staging "could not stage $plist_path"
+  write_config_file "$TX_CONFIG_STAGE" "$port" "$serve_port" "$read_only" "${captains[@]}" || fail_staging "could not stage $CONFIG"
+  render_plist "$label" "$node_path" "$STATE" > "$TX_PLIST_STAGE" || fail_staging "could not stage $plist_path"
+  TX_ACTIVE=true
+  trap '[ "$TX_ACTIVE" != true ] || rollback_install' EXIT
+  mv -f -- "$TX_CONFIG_STAGE" "$CONFIG" || fail_install "could not activate $CONFIG"
+  TX_CONFIG_STAGE=""
+  mv -f -- "$TX_PLIST_STAGE" "$plist_path" || fail_install "could not activate $plist_path"
+  TX_PLIST_STAGE=""
   launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
-  launchctl bootstrap "gui/$(id -u)" "$plist_path" || err "launchctl bootstrap failed for $plist_path"
+  launchctl bootstrap "gui/$(id -u)" "$plist_path" || fail_install "launchctl bootstrap failed for $plist_path"
   # RunAtLoad does not reliably start a re-bootstrapped agent on every macOS;
   # kickstart makes install-serves-now deterministic.
-  launchctl kickstart "gui/$(id -u)/$label" 2>/dev/null || true
+  launchctl kickstart "gui/$(id -u)/$label" >/dev/null 2>&1 || fail_install "launchctl kickstart failed for $label"
 
   # Tailnet-only HTTPS proxy. tailscale serve without funnel is tailnet-only by
   # construction; the assertion below still verifies no Funnel exposure exists
   # for this port and tears the mapping down if one is found.
   "$(tailscale_bin)" serve --bg --https="$serve_port" "http://127.0.0.1:$port" >/dev/null \
-    || err "tailscale serve refused the mapping; is tailscale up?"
+    || fail_install "tailscale serve refused the replacement mapping"
+  TX_NEW_MAPPING=true
   if ! assert_no_funnel "$serve_port"; then
-    disable_serve_port "$serve_port" || err "could not remove the unverified mapping for port $serve_port"
-    err "could not verify tailnet-only exposure for port $serve_port; the mapping was removed - this service must stay tailnet-only"
+    fail_install "could not verify tailnet-only exposure for port $serve_port"
   fi
   if [ -n "$previous_serve_port" ] && [ "$previous_serve_port" != "$serve_port" ]; then
     if ! disable_serve_port "$previous_serve_port"; then
-      disable_serve_port "$serve_port" || true
-      err "could not remove the previous dashboard mapping for port $previous_serve_port; the replacement was removed and the previous port remains configured"
-    fi
-    if ! write_config "$port" "$serve_port" "$read_only" "${captains[@]}"; then
-      disable_serve_port "$serve_port" || true
-      err "could not persist the replacement dashboard serve port; the replacement mapping was removed"
+      fail_install "could not remove the previous dashboard mapping for port $previous_serve_port"
     fi
   fi
+  if [ "$read_only" = true ]; then
+    unregister_check
+  else
+    write_check
+  fi
+  dnsname=$(tailscale_self_dnsname) || fail_install "could not resolve this machine's tailnet name"
+  TX_ACTIVE=false
+  cleanup_install_transaction
+  trap - EXIT
 
-  dnsname=$(tailscale_self_dnsname) || err "could not resolve this machine's tailnet name"
   printf 'installed: launchd agent %s\n' "$label"
   printf 'captains: %s\n' "${captains[*]}"
   printf 'dashboard: https://%s:%s/\n' "$dnsname" "$serve_port"
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index 9f6aa34c1bf..f296951f683 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -104,7 +104,7 @@ bin/fm-dash-install.sh uninstall
 A read-only install is the right shape for running the service ahead of command-consumption wiring: the page, detail views, refresh, and auto-render all work, every mutation route refuses, and any watcher registration from a prior writable install is removed.
 
 Install is idempotent and prints the stable URL, `https://<machine>.<tailnet>.ts.net:8443/`.
-Changing `--serve-port` creates and verifies the replacement, removes the previously recorded mapping, and only then records the new active port.
+Changing `--serve-port` stages the full replacement, verifies it, removes the previous mapping, and restores the prior config, launchd state, watcher registration, and mapping if any step fails.
 Uninstall removes the serve mapping, launchd agent, watcher check, and watcher trust registration but keeps `config/dash.json` and any pending commands.
 The launchd agent logs to `state/dash-serve.log`.
 On a non-macOS host the installer refuses and the service can be run under the local init system with the same tailscale serve mapping.
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index 93519bd9055..1453941188f 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -599,12 +599,13 @@ test_installer_plist_and_funnel_stance() {
   grep -n 'tailscale funnel' "$INSTALL_SH" && fail "installer invokes tailscale funnel"
   assert_grep 'assert_no_funnel' "$INSTALL_SH" "installer does not verify funnel is off"
   assert_grep 'never enables Funnel' "$INSTALL_SH" "installer does not declare the funnel boundary"
-  funnel_check=$(sed -n '/^assert_no_funnel()/,/^write_config()/p' "$INSTALL_SH")
+  funnel_check=$(sed -n '/^assert_no_funnel()/,/^write_config_file()/p' "$INSTALL_SH")
   assert_contains "$funnel_check" 'unsupported tailscale serve status schema' "Funnel verification does not reject unexpected schemas"
   assert_contains "$funnel_check" 'could not verify Funnel state' "Funnel verification does not report unreadable status"
   assert_contains "$funnel_check" 'process.exit(1)' "Funnel verification does not fail closed"
-  assert_contains "$(sed -n '/if ! assert_no_funnel/,/fi/p' "$INSTALL_SH")" 'disable_serve_port "$serve_port"' "failed Funnel verification does not tear down the mapping"
-  assert_contains "$(sed -n '/write_config .*port/,/label=/p' "$INSTALL_SH")" 'unregister_check' "read-only install does not unregister a prior writable watcher"
+  assert_contains "$(sed -n '/if ! assert_no_funnel/,/fi/p' "$INSTALL_SH")" 'fail_install' "failed Funnel verification does not enter transactional rollback"
+  assert_contains "$(sed -n '/^rollback_install()/,/^fail_install()/p' "$INSTALL_SH")" 'disable_serve_port "$TX_NEW_SERVE_PORT"' "transactional rollback does not tear down the replacement mapping"
+  assert_contains "$(sed -n '/^cmd_install()/,/^cmd_uninstall()/p' "$INSTALL_SH")" 'unregister_check' "read-only install does not unregister a prior writable watcher"
   assert_contains "$(sed -n '/^cmd_uninstall()/,/^cmd_status()/p' "$INSTALL_SH")" 'unregister_check' "uninstall does not unregister the watcher"
   escaped_home="$HOME_DIR/xml & < >"
   plist=$(FM_HOME="$escaped_home" FM_ROOT_OVERRIDE="$HOME_DIR/root & < >" "$INSTALL_SH" print-plist) || fail "print-plist with XML metacharacters failed"
@@ -614,10 +615,14 @@ test_installer_plist_and_funnel_stance() {
 }
 
 test_installer_tracks_custom_serve_port() {
-  local fake_bin install_home launch_home tailscale_log tailscale_state
+  local fake_bin install_home launch_home launchctl_log launchctl_state prior_config real_mv tailscale_log tailscale_state
   fake_bin="$TMP_ROOT/fake-bin"
   install_home="$TMP_ROOT/install-home"
   launch_home="$TMP_ROOT/launch-home"
+  launchctl_log="$TMP_ROOT/launchctl.log"
+  launchctl_state="$TMP_ROOT/launchctl.state"
+  prior_config="$TMP_ROOT/prior-dash.json"
+  real_mv=$(command -v mv)
   tailscale_log="$TMP_ROOT/tailscale.log"
   tailscale_state="$TMP_ROOT/tailscale.state"
   mkdir -p "$fake_bin" "$install_home" "$launch_home"
@@ -627,7 +632,38 @@ echo Darwin
 EOF
   cat > "$fake_bin/launchctl" <<'EOF'
 #!/bin/sh
-exit 0
+case "$1" in
+  print)
+    [ -f "$LAUNCHCTL_STATE" ] && [ "$(cat "$LAUNCHCTL_STATE")" = loaded ]
+    ;;
+  bootout)
+    : > "$LAUNCHCTL_STATE"
+    printf 'bootout\n' >> "$LAUNCHCTL_LOG"
+    ;;
+  bootstrap)
+    if [ -n "${LAUNCHCTL_FAIL_ONCE:-}" ] && [ ! -e "$LAUNCHCTL_FAIL_ONCE" ]; then
+      : > "$LAUNCHCTL_FAIL_ONCE"
+      printf 'bootstrap-failed\n' >> "$LAUNCHCTL_LOG"
+      exit 1
+    fi
+    printf 'loaded\n' > "$LAUNCHCTL_STATE"
+    printf 'bootstrap\n' >> "$LAUNCHCTL_LOG"
+    ;;
+  kickstart)
+    printf 'kickstart\n' >> "$LAUNCHCTL_LOG"
+    ;;
+  *) exit 1 ;;
+esac
+EOF
+  cat > "$fake_bin/mv" <<'EOF'
+#!/bin/sh
+last=""
+for arg in "$@"; do last=$arg; done
+if [ -n "${MV_FAIL_DEST:-}" ] && [ "$last" = "$MV_FAIL_DEST" ] && [ ! -e "$MV_FAIL_MARKER" ]; then
+  : > "$MV_FAIL_MARKER"
+  exit 1
+fi
+exec "$REAL_MV" "$@"
 EOF
   cat > "$fake_bin/tailscale" <<'EOF'
 #!/bin/sh
@@ -648,6 +684,11 @@ elif [ "$1" = serve ] && [ "${2:-}" = --bg ]; then
   printf 'map %s\n' "$port" >> "$TAILSCALE_LOG"
 elif [ "$1" = serve ] && [ "${2#--https=}" != "$2" ] && [ "${3:-}" = off ]; then
   port=${2#--https=}
+  if [ "${TAILSCALE_FAIL_OFF_PORT:-}" = "$port" ] && [ ! -e "$TAILSCALE_FAIL_OFF_MARKER" ]; then
+    : > "$TAILSCALE_FAIL_OFF_MARKER"
+    printf 'off-failed %s\n' "$port" >> "$TAILSCALE_LOG"
+    exit 1
+  fi
   printf 'off %s\n' "$port" >> "$TAILSCALE_LOG"
   if [ -f "$TAILSCALE_STATE" ] && [ "$(cat "$TAILSCALE_STATE")" = "$port" ]; then
     : > "$TAILSCALE_STATE"
@@ -656,38 +697,66 @@ else
   exit 1
 fi
 EOF
-  chmod 700 "$fake_bin/uname" "$fake_bin/launchctl" "$fake_bin/tailscale"
-  HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+  chmod 700 "$fake_bin/uname" "$fake_bin/launchctl" "$fake_bin/mv" "$fake_bin/tailscale"
+  HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
     "$INSTALL_SH" install --read-only --port 18847 --serve-port 19443 --captain "$CAPTAIN" >/dev/null \
     || fail "custom-port install failed"
   node -e 'const c=require(process.argv[1]); if(c.serve_port !== 19443) process.exit(1)' "$install_home/config/dash.json" \
     || fail "install did not persist the custom serve port"
+  cp "$install_home/config/dash.json" "$prior_config"
   : > "$tailscale_log"
-  if HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" TAILSCALE_FAIL_MAP_PORT=19663 PATH="$fake_bin:$PATH" \
-    "$INSTALL_SH" install --read-only --port 18847 --serve-port 19663 --captain "$CAPTAIN" >/dev/null 2>&1; then
+  if HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" TAILSCALE_FAIL_MAP_PORT=19663 PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --port 18848 --serve-port 19663 --captain "other@example.com" >/dev/null 2>&1; then
     fail "failed replacement mapping was reported as installed"
   fi
-  node -e 'const c=require(process.argv[1]); if(c.serve_port !== 19443) process.exit(1)' "$install_home/config/dash.json" \
-    || fail "failed replacement mapping overwrote the recorded active port"
+  cmp -s "$prior_config" "$install_home/config/dash.json" || fail "failed replacement mapping did not restore the full prior config"
+  [ "$(cat "$launchctl_state")" = loaded ] || fail "failed replacement mapping did not restore the prior launchd service"
+  assert_grep 'map 19443' "$tailscale_log" "failed replacement mapping did not restore the prior mapping"
   assert_no_grep 'off 19443' "$tailscale_log" "failed replacement mapping removed the recorded active mapping"
   : > "$tailscale_log"
-  if HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" TAILSCALE_FUNNEL_PORT=19664 PATH="$fake_bin:$PATH" \
-    "$INSTALL_SH" install --read-only --port 18847 --serve-port 19664 --captain "$CAPTAIN" >/dev/null 2>&1; then
+  if HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" TAILSCALE_FUNNEL_PORT=19664 PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --port 18848 --serve-port 19664 --captain "other@example.com" >/dev/null 2>&1; then
     fail "Funnel-exposed replacement mapping was reported as installed"
   fi
-  node -e 'const c=require(process.argv[1]); if(c.serve_port !== 19443) process.exit(1)' "$install_home/config/dash.json" \
-    || fail "failed Funnel verification overwrote the recorded active port"
+  cmp -s "$prior_config" "$install_home/config/dash.json" || fail "failed Funnel verification did not restore the full prior config"
+  [ "$(cat "$launchctl_state")" = loaded ] || fail "failed Funnel verification did not restore the prior launchd service"
   assert_grep 'off 19664' "$tailscale_log" "failed Funnel verification did not remove the replacement mapping"
+  assert_grep 'map 19443' "$tailscale_log" "failed Funnel verification did not restore the prior mapping"
   assert_no_grep 'off 19443' "$tailscale_log" "failed Funnel verification removed the recorded active mapping"
   : > "$tailscale_log"
-  HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+  if HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_FAIL_ONCE="$TMP_ROOT/bootstrap-failed" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --port 18848 --serve-port 19665 --captain "other@example.com" >/dev/null 2>&1; then
+    fail "failed launchd replacement was reported as installed"
+  fi
+  cmp -s "$prior_config" "$install_home/config/dash.json" || fail "failed launchd replacement did not restore the full prior config"
+  [ "$(cat "$launchctl_state")" = loaded ] || fail "failed launchd replacement did not restore the prior service"
+  assert_grep 'map 19443' "$tailscale_log" "failed launchd replacement did not restore the prior mapping"
+  : > "$tailscale_log"
+  if HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" MV_FAIL_DEST="$install_home/config/dash.json" MV_FAIL_MARKER="$TMP_ROOT/config-mv-failed" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --port 18848 --serve-port 19666 --captain "other@example.com" >/dev/null 2>&1; then
+    fail "failed config activation was reported as installed"
+  fi
+  cmp -s "$prior_config" "$install_home/config/dash.json" || fail "failed config activation did not restore the full prior config"
+  [ "$(cat "$launchctl_state")" = loaded ] || fail "failed config activation did not restore the prior service"
+  assert_grep 'map 19443' "$tailscale_log" "failed config activation did not restore the prior mapping"
+  : > "$tailscale_log"
+  if HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_FAIL_OFF_MARKER="$TMP_ROOT/off-failed" TAILSCALE_FAIL_OFF_PORT=19443 TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --port 18848 --serve-port 19667 --captain "other@example.com" >/dev/null 2>&1; then
+    fail "failed old-mapping teardown was reported as installed"
+  fi
+  cmp -s "$prior_config" "$install_home/config/dash.json" || fail "failed old-mapping teardown did not restore the full prior config"
+  [ "$(cat "$launchctl_state")" = loaded ] || fail "failed old-mapping teardown did not restore the prior service"
+  assert_grep 'off 19667' "$tailscale_log" "failed old-mapping teardown did not remove the replacement mapping"
+  assert_grep 'map 19443' "$tailscale_log" "failed old-mapping teardown did not restore the prior mapping"
+  : > "$tailscale_log"
+  HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
     "$INSTALL_SH" install --read-only --port 18847 --serve-port 19553 --captain "$CAPTAIN" >/dev/null \
     || fail "custom-port replacement install failed"
   assert_grep 'off 19443' "$tailscale_log" "port-change install did not remove the recorded previous mapping"
   node -e 'const c=require(process.argv[1]); if(c.serve_port !== 19553) process.exit(1)' "$install_home/config/dash.json" \
     || fail "replacement install did not persist the active serve port"
   : > "$tailscale_log"
-  HOME="$launch_home" FM_HOME="$install_home" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+  HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
     "$INSTALL_SH" uninstall >/dev/null || fail "plain uninstall failed"
   assert_grep 'off 19553' "$tailscale_log" "plain uninstall did not remove the recorded active mapping"
   pass "custom serve ports persist and old mappings are removed"

From cce96d61abebc3a5fa9e3a3b575fb3d78a4da19c Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 11:59:50 -0400
Subject: [PATCH 10/24] no-mistakes(review): Restore only observed dashboard
 mappings during rollback

---
 bin/fm-dash-install.sh    | 53 ++++++++++++++++++++++++++-------------
 docs/dashboard-service.md |  2 +-
 tests/fm-dash.test.sh     | 25 +++++++++++++++---
 3 files changed, 58 insertions(+), 22 deletions(-)

diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index ee70bbfd275..20e08d12267 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -51,8 +51,9 @@ TX_TRUST_EXISTED=false
 TX_CONFIG_STAGE=""
 TX_PLIST_STAGE=""
 TX_PRIOR_LOADED=false
-TX_PREVIOUS_PORT=""
 TX_PREVIOUS_SERVE_PORT=""
+TX_PREVIOUS_MAPPING_PRESENT=false
+TX_PREVIOUS_MAPPING_TARGET=""
 TX_NEW_SERVE_PORT=""
 TX_NEW_MAPPING=false
 TX_LABEL=""
@@ -184,19 +185,34 @@ configured_serve_port() {
   ' "$CONFIG" "$DEFAULT_SERVE_PORT"
 }
 
-configured_loopback_port() {
-  [ -f "$CONFIG" ] || return 0
-  node -e '
-    const fs = require("node:fs");
-    try {
-      const parsed = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
-      const port = parsed.port === undefined ? Number(process.argv[2]) : parsed.port;
-      if (!Number.isInteger(port) || port < 1 || port > 65535) process.exit(1);
-      console.log(port);
-    } catch {
-      process.exit(1);
-    }
-  ' "$CONFIG" "$DEFAULT_PORT"
+snapshot_serve_mapping() {
+  local serve_port=$1 status_json
+  status_json=$("$(tailscale_bin)" serve status --json 2>/dev/null) || return 1
+  printf '%s' "$status_json" | node -e '
+    let raw = "";
+    process.stdin.on("data", (c) => { raw += c; });
+    process.stdin.on("end", () => {
+      try {
+        const s = JSON.parse(raw);
+        if (!s || Array.isArray(s) || typeof s !== "object") throw new Error();
+        const tcp = s.TCP === undefined ? {} : s.TCP;
+        const web = s.Web === undefined ? {} : s.Web;
+        if (!tcp || Array.isArray(tcp) || typeof tcp !== "object"
+          || !web || Array.isArray(web) || typeof web !== "object") throw new Error();
+        const tcpMapping = tcp[process.argv[1]];
+        const webMappings = Object.entries(web).filter(([hostport]) => hostport.endsWith(":" + process.argv[1]));
+        if (tcpMapping === undefined && webMappings.length === 0) return;
+        if (!tcpMapping || tcpMapping.HTTPS !== true || webMappings.length !== 1) throw new Error();
+        const handlers = webMappings[0][1] && webMappings[0][1].Handlers;
+        if (!handlers || Array.isArray(handlers) || typeof handlers !== "object") throw new Error();
+        const proxies = Object.values(handlers).map((handler) => handler && handler.Proxy).filter((proxy) => typeof proxy === "string" && proxy.length > 0);
+        if (proxies.length !== 1) throw new Error();
+        console.log(proxies[0]);
+      } catch {
+        process.exit(1);
+      }
+    });
+  ' "$serve_port"
 }
 
 disable_serve_port() {
@@ -240,8 +256,8 @@ rollback_install() {
     launchctl bootstrap "gui/$(id -u)" "$TX_PLIST_PATH" >/dev/null 2>&1 || status=1
     launchctl kickstart "gui/$(id -u)/$TX_LABEL" >/dev/null 2>&1 || status=1
   fi
-  if [ -n "$TX_PREVIOUS_SERVE_PORT" ]; then
-    "$(tailscale_bin)" serve --bg --https="$TX_PREVIOUS_SERVE_PORT" "http://127.0.0.1:$TX_PREVIOUS_PORT" >/dev/null 2>&1 || status=1
+  if [ "$TX_PREVIOUS_MAPPING_PRESENT" = true ]; then
+    "$(tailscale_bin)" serve --bg --https="$TX_PREVIOUS_SERVE_PORT" "$TX_PREVIOUS_MAPPING_TARGET" >/dev/null 2>&1 || status=1
     assert_no_funnel "$TX_PREVIOUS_SERVE_PORT" >/dev/null 2>&1 || status=1
   fi
   cleanup_install_transaction
@@ -342,7 +358,10 @@ cmd_install() {
   node_path=$(node_bin)
   tailscale_bin >/dev/null
   previous_serve_port=$(configured_serve_port) || err "could not read the previously configured dashboard serve port"
-  TX_PREVIOUS_PORT=$(configured_loopback_port) || err "could not read the previously configured dashboard loopback port"
+  if [ -n "$previous_serve_port" ]; then
+    TX_PREVIOUS_MAPPING_TARGET=$(snapshot_serve_mapping "$previous_serve_port") || err "could not snapshot the previous dashboard mapping"
+    [ -z "$TX_PREVIOUS_MAPPING_TARGET" ] || TX_PREVIOUS_MAPPING_PRESENT=true
+  fi
 
   if [ "${#captains[@]}" -eq 0 ]; then
     local self_login
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index f296951f683..849ae6d3688 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -104,7 +104,7 @@ bin/fm-dash-install.sh uninstall
 A read-only install is the right shape for running the service ahead of command-consumption wiring: the page, detail views, refresh, and auto-render all work, every mutation route refuses, and any watcher registration from a prior writable install is removed.
 
 Install is idempotent and prints the stable URL, `https://<machine>.<tailnet>.ts.net:8443/`.
-Changing `--serve-port` stages the full replacement, verifies it, removes the previous mapping, and restores the prior config, launchd state, watcher registration, and mapping if any step fails.
+Changing `--serve-port` stages the full replacement, verifies it, removes the previous mapping, and restores the prior config, launchd state, watcher registration, and observed live mapping state if any step fails.
 Uninstall removes the serve mapping, launchd agent, watcher check, and watcher trust registration but keeps `config/dash.json` and any pending commands.
 The launchd agent logs to `state/dash-serve.log`.
 On a non-macOS host the installer refuses and the service can be run under the local init system with the same tailscale serve mapping.
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index 1453941188f..44ed089ac9f 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -670,17 +670,23 @@ EOF
 if [ "$1" = status ] && [ "${2:-}" = --json ]; then
   printf '%s\n' '{"Self":{"UserID":1,"DNSName":"dash.tail.ts.net."},"User":{"1":{"LoginName":"captain@example.com"}}}'
 elif [ "$1" = serve ] && [ "${2:-}" = status ] && [ "${3:-}" = --json ]; then
-  port=$(cat "$TAILSCALE_STATE")
+  state=$(cat "$TAILSCALE_STATE")
+  if [ -z "$state" ]; then
+    printf '%s\n' '{"TCP":{},"Web":{},"AllowFunnel":{}}'
+    exit 0
+  fi
+  port=${state%%|*}
+  target=${state#*|}
   funnel=false
   [ "${TAILSCALE_FUNNEL_PORT:-}" != "$port" ] || funnel=true
-  printf '{"TCP":{"%s":{"HTTPS":true}},"Web":{"dash.tail.ts.net:%s":{}},"AllowFunnel":{"dash.tail.ts.net:%s":%s}}\n' "$port" "$port" "$port" "$funnel"
+  printf '{"TCP":{"%s":{"HTTPS":true}},"Web":{"dash.tail.ts.net:%s":{"Handlers":{"/":{"Proxy":"%s"}}}},"AllowFunnel":{"dash.tail.ts.net:%s":%s}}\n' "$port" "$port" "$target" "$port" "$funnel"
 elif [ "$1" = serve ] && [ "${2:-}" = --bg ]; then
   port=${3#--https=}
   if [ "${TAILSCALE_FAIL_MAP_PORT:-}" = "$port" ]; then
     printf 'map-failed %s\n' "$port" >> "$TAILSCALE_LOG"
     exit 1
   fi
-  printf '%s\n' "$port" > "$TAILSCALE_STATE"
+  printf '%s|%s\n' "$port" "$4" > "$TAILSCALE_STATE"
   printf 'map %s\n' "$port" >> "$TAILSCALE_LOG"
 elif [ "$1" = serve ] && [ "${2#--https=}" != "$2" ] && [ "${3:-}" = off ]; then
   port=${2#--https=}
@@ -690,7 +696,8 @@ elif [ "$1" = serve ] && [ "${2#--https=}" != "$2" ] && [ "${3:-}" = off ]; then
     exit 1
   fi
   printf 'off %s\n' "$port" >> "$TAILSCALE_LOG"
-  if [ -f "$TAILSCALE_STATE" ] && [ "$(cat "$TAILSCALE_STATE")" = "$port" ]; then
+  state=$(cat "$TAILSCALE_STATE")
+  if [ "${state%%|*}" = "$port" ]; then
     : > "$TAILSCALE_STATE"
   fi
 else
@@ -759,6 +766,16 @@ EOF
   HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
     "$INSTALL_SH" uninstall >/dev/null || fail "plain uninstall failed"
   assert_grep 'off 19553' "$tailscale_log" "plain uninstall did not remove the recorded active mapping"
+  cp "$install_home/config/dash.json" "$prior_config"
+  : > "$tailscale_log"
+  if HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" TAILSCALE_FAIL_MAP_PORT=19668 PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --read-only --port 18848 --serve-port 19668 --captain "$CAPTAIN" >/dev/null 2>&1; then
+    fail "failed reinstall after uninstall was reported as installed"
+  fi
+  cmp -s "$prior_config" "$install_home/config/dash.json" || fail "failed reinstall after uninstall did not restore the retained config"
+  [ ! -s "$launchctl_state" ] || fail "failed reinstall after uninstall restored an absent launchd service"
+  [ ! -s "$tailscale_state" ] || fail "failed reinstall after uninstall recreated an absent mapping"
+  assert_no_grep 'map 19553' "$tailscale_log" "failed reinstall after uninstall recreated the removed prior mapping"
   pass "custom serve ports persist and old mappings are removed"
 }
 

From 597973a637843202d1b663b5e22273dff9f933a3 Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 12:06:44 -0400
Subject: [PATCH 11/24] no-mistakes(review): Protect occupied Tailscale serve
 ports during install

---
 bin/fm-dash-install.sh    | 41 +++++++++++++++++++++++++++-----
 docs/dashboard-service.md |  1 +
 tests/fm-dash.test.sh     | 49 ++++++++++++++++++++++++++-------------
 3 files changed, 69 insertions(+), 22 deletions(-)

diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index 20e08d12267..fc0b8cc4c7e 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -185,6 +185,21 @@ configured_serve_port() {
   ' "$CONFIG" "$DEFAULT_SERVE_PORT"
 }
 
+configured_mapping_target() {
+  [ -f "$CONFIG" ] || return 0
+  node -e '
+    const fs = require("node:fs");
+    try {
+      const parsed = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+      const port = parsed.port === undefined ? Number(process.argv[2]) : parsed.port;
+      if (!Number.isInteger(port) || port < 1 || port > 65535) process.exit(1);
+      console.log("http://127.0.0.1:" + port);
+    } catch {
+      process.exit(1);
+    }
+  ' "$CONFIG" "$DEFAULT_PORT"
+}
+
 snapshot_serve_mapping() {
   local serve_port=$1 status_json
   status_json=$("$(tailscale_bin)" serve status --json 2>/dev/null) || return 1
@@ -205,9 +220,10 @@ snapshot_serve_mapping() {
         if (!tcpMapping || tcpMapping.HTTPS !== true || webMappings.length !== 1) throw new Error();
         const handlers = webMappings[0][1] && webMappings[0][1].Handlers;
         if (!handlers || Array.isArray(handlers) || typeof handlers !== "object") throw new Error();
-        const proxies = Object.values(handlers).map((handler) => handler && handler.Proxy).filter((proxy) => typeof proxy === "string" && proxy.length > 0);
-        if (proxies.length !== 1) throw new Error();
-        console.log(proxies[0]);
+        const paths = Object.keys(handlers);
+        const proxy = handlers["/"] && handlers["/"].Proxy;
+        if (paths.length !== 1 || paths[0] !== "/" || typeof proxy !== "string" || proxy.length === 0) throw new Error();
+        console.log(proxy);
       } catch {
         process.exit(1);
       }
@@ -343,7 +359,7 @@ unregister_check() {
 }
 
 cmd_install() {
-  local port=$DEFAULT_PORT serve_port=$DEFAULT_SERVE_PORT previous_serve_port read_only=false captains=() label plist_path node_path dnsname
+  local port=$DEFAULT_PORT serve_port=$DEFAULT_SERVE_PORT previous_serve_port previous_mapping_target requested_mapping_target expected_mapping_target read_only=false captains=() label plist_path node_path dnsname
   while [ $# -gt 0 ]; do
     case "$1" in
       --port) port=${2:?--port needs a value}; shift 2 ;;
@@ -358,9 +374,22 @@ cmd_install() {
   node_path=$(node_bin)
   tailscale_bin >/dev/null
   previous_serve_port=$(configured_serve_port) || err "could not read the previously configured dashboard serve port"
+  expected_mapping_target=$(configured_mapping_target) || err "could not read the previously configured dashboard mapping target"
   if [ -n "$previous_serve_port" ]; then
-    TX_PREVIOUS_MAPPING_TARGET=$(snapshot_serve_mapping "$previous_serve_port") || err "could not snapshot the previous dashboard mapping"
-    [ -z "$TX_PREVIOUS_MAPPING_TARGET" ] || TX_PREVIOUS_MAPPING_PRESENT=true
+    previous_mapping_target=$(snapshot_serve_mapping "$previous_serve_port") || err "could not inspect the previously configured dashboard serve port"
+    if [ -n "$previous_mapping_target" ] && [ "$previous_mapping_target" != "$expected_mapping_target" ]; then
+      err "configured dashboard serve port $previous_serve_port carries a non-dashboard mapping; refusing to replace it"
+    fi
+    TX_PREVIOUS_MAPPING_TARGET=$previous_mapping_target
+    [ -z "$previous_mapping_target" ] || TX_PREVIOUS_MAPPING_PRESENT=true
+  fi
+  if [ "$serve_port" = "$previous_serve_port" ]; then
+    requested_mapping_target=$previous_mapping_target
+  else
+    requested_mapping_target=$(snapshot_serve_mapping "$serve_port") || err "could not inspect requested dashboard serve port $serve_port"
+  fi
+  if [ -n "$requested_mapping_target" ] && { [ "$serve_port" != "$previous_serve_port" ] || [ "$requested_mapping_target" != "$expected_mapping_target" ]; }; then
+    err "requested dashboard serve port $serve_port carries a non-dashboard mapping; choose another --serve-port"
   fi
 
   if [ "${#captains[@]}" -eq 0 ]; then
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index 849ae6d3688..a828acf950b 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -105,6 +105,7 @@ A read-only install is the right shape for running the service ahead of command-
 
 Install is idempotent and prints the stable URL, `https://<machine>.<tailnet>.ts.net:8443/`.
 Changing `--serve-port` stages the full replacement, verifies it, removes the previous mapping, and restores the prior config, launchd state, watcher registration, and observed live mapping state if any step fails.
+Install refuses a requested serve port that is already owned by another mapping.
 Uninstall removes the serve mapping, launchd agent, watcher check, and watcher trust registration but keeps `config/dash.json` and any pending commands.
 The launchd agent logs to `state/dash-serve.log`.
 On a non-macOS host the installer refuses and the service can be run under the local init system with the same tailscale serve mapping.
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index 44ed089ac9f..1234b55e49d 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -615,7 +615,7 @@ test_installer_plist_and_funnel_stance() {
 }
 
 test_installer_tracks_custom_serve_port() {
-  local fake_bin install_home launch_home launchctl_log launchctl_state prior_config real_mv tailscale_log tailscale_state
+  local fake_bin install_home launch_home launchctl_log launchctl_state occupied_error prior_config real_mv tailscale_log tailscale_state
   fake_bin="$TMP_ROOT/fake-bin"
   install_home="$TMP_ROOT/install-home"
   launch_home="$TMP_ROOT/launch-home"
@@ -670,23 +670,30 @@ EOF
 if [ "$1" = status ] && [ "${2:-}" = --json ]; then
   printf '%s\n' '{"Self":{"UserID":1,"DNSName":"dash.tail.ts.net."},"User":{"1":{"LoginName":"captain@example.com"}}}'
 elif [ "$1" = serve ] && [ "${2:-}" = status ] && [ "${3:-}" = --json ]; then
-  state=$(cat "$TAILSCALE_STATE")
-  if [ -z "$state" ]; then
-    printf '%s\n' '{"TCP":{},"Web":{},"AllowFunnel":{}}'
-    exit 0
-  fi
-  port=${state%%|*}
-  target=${state#*|}
-  funnel=false
-  [ "${TAILSCALE_FUNNEL_PORT:-}" != "$port" ] || funnel=true
-  printf '{"TCP":{"%s":{"HTTPS":true}},"Web":{"dash.tail.ts.net:%s":{"Handlers":{"/":{"Proxy":"%s"}}}},"AllowFunnel":{"dash.tail.ts.net:%s":%s}}\n' "$port" "$port" "$target" "$port" "$funnel"
+  node -e '
+    const fs = require("node:fs");
+    const state = fs.existsSync(process.argv[1]) ? fs.readFileSync(process.argv[1], "utf8").trim().split("\n").filter(Boolean) : [];
+    const payload = { TCP: {}, Web: {}, AllowFunnel: {} };
+    for (const record of state) {
+      const separator = record.indexOf("|");
+      const port = record.slice(0, separator);
+      const target = record.slice(separator + 1);
+      const hostport = "dash.tail.ts.net:" + port;
+      payload.TCP[port] = { HTTPS: true };
+      payload.Web[hostport] = { Handlers: { "/": { Proxy: target } } };
+      payload.AllowFunnel[hostport] = process.argv[2] === port;
+    }
+    console.log(JSON.stringify(payload));
+  ' "$TAILSCALE_STATE" "${TAILSCALE_FUNNEL_PORT:-}"
 elif [ "$1" = serve ] && [ "${2:-}" = --bg ]; then
   port=${3#--https=}
   if [ "${TAILSCALE_FAIL_MAP_PORT:-}" = "$port" ]; then
     printf 'map-failed %s\n' "$port" >> "$TAILSCALE_LOG"
     exit 1
   fi
-  printf '%s|%s\n' "$port" "$4" > "$TAILSCALE_STATE"
+  awk -F '|' -v port="$port" '$1 != port' "$TAILSCALE_STATE" > "$TAILSCALE_STATE.next"
+  printf '%s|%s\n' "$port" "$4" >> "$TAILSCALE_STATE.next"
+  mv "$TAILSCALE_STATE.next" "$TAILSCALE_STATE"
   printf 'map %s\n' "$port" >> "$TAILSCALE_LOG"
 elif [ "$1" = serve ] && [ "${2#--https=}" != "$2" ] && [ "${3:-}" = off ]; then
   port=${2#--https=}
@@ -696,15 +703,14 @@ elif [ "$1" = serve ] && [ "${2#--https=}" != "$2" ] && [ "${3:-}" = off ]; then
     exit 1
   fi
   printf 'off %s\n' "$port" >> "$TAILSCALE_LOG"
-  state=$(cat "$TAILSCALE_STATE")
-  if [ "${state%%|*}" = "$port" ]; then
-    : > "$TAILSCALE_STATE"
-  fi
+  awk -F '|' -v port="$port" '$1 != port' "$TAILSCALE_STATE" > "$TAILSCALE_STATE.next"
+  mv "$TAILSCALE_STATE.next" "$TAILSCALE_STATE"
 else
   exit 1
 fi
 EOF
   chmod 700 "$fake_bin/uname" "$fake_bin/launchctl" "$fake_bin/mv" "$fake_bin/tailscale"
+  : > "$tailscale_state"
   HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
     "$INSTALL_SH" install --read-only --port 18847 --serve-port 19443 --captain "$CAPTAIN" >/dev/null \
     || fail "custom-port install failed"
@@ -712,6 +718,17 @@ EOF
     || fail "install did not persist the custom serve port"
   cp "$install_home/config/dash.json" "$prior_config"
   : > "$tailscale_log"
+  printf '%s\n' '20553|http://127.0.0.1:29999' >> "$tailscale_state"
+  occupied_error=$(HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" install --read-only --port 18847 --serve-port 20553 --captain "$CAPTAIN" 2>&1) && fail "occupied replacement port was reported as installed"
+  assert_contains "$occupied_error" 'requested dashboard serve port 20553 carries a non-dashboard mapping' "occupied replacement port refusal was unclear"
+  cmp -s "$prior_config" "$install_home/config/dash.json" || fail "occupied replacement port mutated the dashboard config"
+  [ "$(cat "$launchctl_state")" = loaded ] || fail "occupied replacement port mutated the launchd service"
+  assert_no_grep 'map 20553' "$tailscale_log" "occupied replacement port was overwritten"
+  assert_no_grep 'off 20553' "$tailscale_log" "occupied replacement port was removed"
+  HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$fake_bin/tailscale" serve --https=20553 off >/dev/null || fail "could not remove the foreign mapping fixture"
+  : > "$tailscale_log"
   if HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" TAILSCALE_FAIL_MAP_PORT=19663 PATH="$fake_bin:$PATH" \
     "$INSTALL_SH" install --port 18848 --serve-port 19663 --captain "other@example.com" >/dev/null 2>&1; then
     fail "failed replacement mapping was reported as installed"

From 3cb44daa8bb04ece36eff3cb8024642589d50f9d Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 12:11:02 -0400
Subject: [PATCH 12/24] no-mistakes(review): Protect foreign mappings during
 dashboard uninstall

---
 bin/fm-dash-install.sh    | 18 +++++++++++++++---
 docs/dashboard-service.md |  2 +-
 tests/fm-dash.test.sh     | 16 +++++++++++++++-
 3 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index fc0b8cc4c7e..d79147af8a3 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -235,6 +235,17 @@ disable_serve_port() {
   "$(tailscale_bin)" serve --https="$1" off >/dev/null 2>&1
 }
 
+disable_owned_serve_port() {
+  local serve_port=$1 expected_target=$2 live_target
+  live_target=$(snapshot_serve_mapping "$serve_port") || return 1
+  [ -n "$live_target" ] || return 0
+  if [ -z "$expected_target" ] || [ "$live_target" != "$expected_target" ]; then
+    printf 'kept: serve port %s carries a non-dashboard mapping\n' "$serve_port"
+    return 0
+  fi
+  disable_serve_port "$serve_port"
+}
+
 cleanup_install_transaction() {
   local file
   for file in "$TX_CONFIG_BACKUP" "$TX_PLIST_BACKUP" "$TX_CHECK_BACKUP" "$TX_TRUST_BACKUP" "$TX_CONFIG_STAGE" "$TX_PLIST_STAGE"; do
@@ -456,7 +467,7 @@ cmd_install() {
 }
 
 cmd_uninstall() {
-  local serve_port="" configured_port label plist_path
+  local serve_port="" configured_port configured_target label plist_path
   while [ $# -gt 0 ]; do
     case "$1" in
       --serve-port) serve_port=${2:?--serve-port needs a value}; shift 2 ;;
@@ -465,13 +476,14 @@ cmd_uninstall() {
   done
   [ "$(uname)" = Darwin ] || err "uninstall requires macOS launchd"
   configured_port=$(configured_serve_port) || err "could not read the configured dashboard serve port"
+  configured_target=$(configured_mapping_target) || err "could not read the configured dashboard mapping target"
   [ -n "$serve_port" ] || serve_port=${configured_port:-$DEFAULT_SERVE_PORT}
   label=$(home_label)
   plist_path="$HOME/Library/LaunchAgents/$label.plist"
   if command -v tailscale >/dev/null 2>&1; then
-    disable_serve_port "$serve_port" || err "could not remove the dashboard mapping for port $serve_port"
+    disable_owned_serve_port "$serve_port" "$configured_target" || err "could not inspect or remove the dashboard mapping for port $serve_port"
     if [ -n "$configured_port" ] && [ "$configured_port" != "$serve_port" ]; then
-      disable_serve_port "$configured_port" || err "could not remove the configured dashboard mapping for port $configured_port"
+      disable_owned_serve_port "$configured_port" "$configured_target" || err "could not inspect or remove the configured dashboard mapping for port $configured_port"
     fi
   fi
   launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index a828acf950b..58d8dccef3f 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -106,7 +106,7 @@ A read-only install is the right shape for running the service ahead of command-
 Install is idempotent and prints the stable URL, `https://<machine>.<tailnet>.ts.net:8443/`.
 Changing `--serve-port` stages the full replacement, verifies it, removes the previous mapping, and restores the prior config, launchd state, watcher registration, and observed live mapping state if any step fails.
 Install refuses a requested serve port that is already owned by another mapping.
-Uninstall removes the serve mapping, launchd agent, watcher check, and watcher trust registration but keeps `config/dash.json` and any pending commands.
+Uninstall removes only serve mappings whose live proxy target matches this dashboard's configured loopback target, plus the launchd agent, watcher check, and watcher trust registration, while keeping `config/dash.json` and any pending commands.
 The launchd agent logs to `state/dash-serve.log`.
 On a non-macOS host the installer refuses and the service can be run under the local init system with the same tailscale serve mapping.
 
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index 1234b55e49d..fba36990025 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -615,7 +615,7 @@ test_installer_plist_and_funnel_stance() {
 }
 
 test_installer_tracks_custom_serve_port() {
-  local fake_bin install_home launch_home launchctl_log launchctl_state occupied_error prior_config real_mv tailscale_log tailscale_state
+  local fake_bin install_home launch_home launchctl_log launchctl_state occupied_error prior_config real_mv tailscale_log tailscale_state uninstall_output
   fake_bin="$TMP_ROOT/fake-bin"
   install_home="$TMP_ROOT/install-home"
   launch_home="$TMP_ROOT/launch-home"
@@ -783,6 +783,20 @@ EOF
   HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
     "$INSTALL_SH" uninstall >/dev/null || fail "plain uninstall failed"
   assert_grep 'off 19553' "$tailscale_log" "plain uninstall did not remove the recorded active mapping"
+  printf '%s\n' '19553|http://127.0.0.1:29998' '20554|http://127.0.0.1:29999' >> "$tailscale_state"
+  : > "$tailscale_log"
+  uninstall_output=$(HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" uninstall --serve-port 20554) || fail "repeated uninstall with foreign mappings failed"
+  assert_contains "$uninstall_output" 'kept: serve port 20554 carries a non-dashboard mapping' "uninstall did not report the foreign requested mapping"
+  assert_contains "$uninstall_output" 'kept: serve port 19553 carries a non-dashboard mapping' "uninstall did not report the foreign configured mapping"
+  assert_no_grep 'off 20554' "$tailscale_log" "uninstall removed a foreign requested mapping"
+  assert_no_grep 'off 19553' "$tailscale_log" "uninstall removed a foreign configured mapping"
+  assert_grep '19553|http://127.0.0.1:29998' "$tailscale_state" "uninstall mutated the foreign configured mapping"
+  assert_grep '20554|http://127.0.0.1:29999' "$tailscale_state" "uninstall mutated the foreign requested mapping"
+  HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$fake_bin/tailscale" serve --https=19553 off >/dev/null || fail "could not remove the configured foreign mapping fixture"
+  HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$fake_bin/tailscale" serve --https=20554 off >/dev/null || fail "could not remove the requested foreign mapping fixture"
   cp "$install_home/config/dash.json" "$prior_config"
   : > "$tailscale_log"
   if HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" TAILSCALE_FAIL_MAP_PORT=19668 PATH="$fake_bin:$PATH" \

From 2086b130db9f84108c1e58e98a13a7a876d5a0e0 Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 12:13:29 -0400
Subject: [PATCH 13/24] no-mistakes(review): Classify foreign serve mappings
 without blocking uninstall

---
 bin/fm-dash-install.sh    | 15 ++++++++++++---
 docs/dashboard-service.md |  2 +-
 tests/fm-dash.test.sh     | 22 ++++++++++++++++------
 3 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index d79147af8a3..d02f5163fe9 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -217,12 +217,21 @@ snapshot_serve_mapping() {
         const tcpMapping = tcp[process.argv[1]];
         const webMappings = Object.entries(web).filter(([hostport]) => hostport.endsWith(":" + process.argv[1]));
         if (tcpMapping === undefined && webMappings.length === 0) return;
-        if (!tcpMapping || tcpMapping.HTTPS !== true || webMappings.length !== 1) throw new Error();
+        if (!tcpMapping || tcpMapping.HTTPS !== true || webMappings.length !== 1) {
+          console.log("foreign");
+          return;
+        }
         const handlers = webMappings[0][1] && webMappings[0][1].Handlers;
-        if (!handlers || Array.isArray(handlers) || typeof handlers !== "object") throw new Error();
+        if (!handlers || Array.isArray(handlers) || typeof handlers !== "object") {
+          console.log("foreign");
+          return;
+        }
         const paths = Object.keys(handlers);
         const proxy = handlers["/"] && handlers["/"].Proxy;
-        if (paths.length !== 1 || paths[0] !== "/" || typeof proxy !== "string" || proxy.length === 0) throw new Error();
+        if (paths.length !== 1 || paths[0] !== "/" || typeof proxy !== "string" || proxy.length === 0) {
+          console.log("foreign");
+          return;
+        }
         console.log(proxy);
       } catch {
         process.exit(1);
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index 58d8dccef3f..42f9e71e534 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -106,7 +106,7 @@ A read-only install is the right shape for running the service ahead of command-
 Install is idempotent and prints the stable URL, `https://<machine>.<tailnet>.ts.net:8443/`.
 Changing `--serve-port` stages the full replacement, verifies it, removes the previous mapping, and restores the prior config, launchd state, watcher registration, and observed live mapping state if any step fails.
 Install refuses a requested serve port that is already owned by another mapping.
-Uninstall removes only serve mappings whose live proxy target matches this dashboard's configured loopback target, plus the launchd agent, watcher check, and watcher trust registration, while keeping `config/dash.json` and any pending commands.
+Uninstall removes only serve mappings whose live shape is a single root proxy to this dashboard's configured loopback target, plus the launchd agent, watcher check, and watcher trust registration, while keeping `config/dash.json` and any pending commands.
 The launchd agent logs to `state/dash-serve.log`.
 On a non-macOS host the installer refuses and the service can be run under the local init system with the same tailscale serve mapping.
 
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index fba36990025..de69fe4f677 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -670,17 +670,21 @@ EOF
 if [ "$1" = status ] && [ "${2:-}" = --json ]; then
   printf '%s\n' '{"Self":{"UserID":1,"DNSName":"dash.tail.ts.net."},"User":{"1":{"LoginName":"captain@example.com"}}}'
 elif [ "$1" = serve ] && [ "${2:-}" = status ] && [ "${3:-}" = --json ]; then
+  if [ "${TAILSCALE_INVALID_SERVE_STATUS:-}" = 1 ]; then
+    printf '{\n'
+    exit 0
+  fi
   node -e '
     const fs = require("node:fs");
     const state = fs.existsSync(process.argv[1]) ? fs.readFileSync(process.argv[1], "utf8").trim().split("\n").filter(Boolean) : [];
     const payload = { TCP: {}, Web: {}, AllowFunnel: {} };
     for (const record of state) {
-      const separator = record.indexOf("|");
-      const port = record.slice(0, separator);
-      const target = record.slice(separator + 1);
+      const [port, target, shape] = record.split("|");
       const hostport = "dash.tail.ts.net:" + port;
       payload.TCP[port] = { HTTPS: true };
-      payload.Web[hostport] = { Handlers: { "/": { Proxy: target } } };
+      payload.Web[hostport] = shape === "complex"
+        ? { Handlers: { "/api": { Proxy: target }, "/": { Text: "foreign service" } } }
+        : { Handlers: { "/": { Proxy: target } } };
       payload.AllowFunnel[hostport] = process.argv[2] === port;
     }
     console.log(JSON.stringify(payload));
@@ -780,10 +784,16 @@ EOF
   node -e 'const c=require(process.argv[1]); if(c.serve_port !== 19553) process.exit(1)' "$install_home/config/dash.json" \
     || fail "replacement install did not persist the active serve port"
   : > "$tailscale_log"
+  uninstall_output=$(HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_INVALID_SERVE_STATUS=1 TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
+    "$INSTALL_SH" uninstall 2>&1) && fail "uninstall accepted unreadable serve status"
+  assert_contains "$uninstall_output" 'could not inspect or remove the dashboard mapping for port 19553' "uninstall did not fail clearly on unreadable serve status"
+  [ "$(cat "$launchctl_state")" = loaded ] || fail "unreadable serve status removed the launchd service"
+  assert_no_grep 'off 19553' "$tailscale_log" "unreadable serve status removed the dashboard mapping"
+  : > "$tailscale_log"
   HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
     "$INSTALL_SH" uninstall >/dev/null || fail "plain uninstall failed"
   assert_grep 'off 19553' "$tailscale_log" "plain uninstall did not remove the recorded active mapping"
-  printf '%s\n' '19553|http://127.0.0.1:29998' '20554|http://127.0.0.1:29999' >> "$tailscale_state"
+  printf '%s\n' '19553|http://127.0.0.1:29998' '20554|http://127.0.0.1:29999|complex' >> "$tailscale_state"
   : > "$tailscale_log"
   uninstall_output=$(HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
     "$INSTALL_SH" uninstall --serve-port 20554) || fail "repeated uninstall with foreign mappings failed"
@@ -792,7 +802,7 @@ EOF
   assert_no_grep 'off 20554' "$tailscale_log" "uninstall removed a foreign requested mapping"
   assert_no_grep 'off 19553' "$tailscale_log" "uninstall removed a foreign configured mapping"
   assert_grep '19553|http://127.0.0.1:29998' "$tailscale_state" "uninstall mutated the foreign configured mapping"
-  assert_grep '20554|http://127.0.0.1:29999' "$tailscale_state" "uninstall mutated the foreign requested mapping"
+  assert_grep '20554|http://127.0.0.1:29999|complex' "$tailscale_state" "uninstall mutated the complex foreign requested mapping"
   HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \
     "$fake_bin/tailscale" serve --https=19553 off >/dev/null || fail "could not remove the configured foreign mapping fixture"
   HOME="$launch_home" FM_HOME="$install_home" LAUNCHCTL_LOG="$launchctl_log" LAUNCHCTL_STATE="$launchctl_state" REAL_MV="$real_mv" TAILSCALE_LOG="$tailscale_log" TAILSCALE_STATE="$tailscale_state" PATH="$fake_bin:$PATH" \

From da1f682df1c89116becc8f418ce9085b4ed8ec07 Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 12:50:33 -0400
Subject: [PATCH 14/24] no-mistakes(test): Captain: align capacity blocker
 identity expectation

---
 tests/fm-capacity.test.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/fm-capacity.test.sh b/tests/fm-capacity.test.sh
index 1ad0e41e190..f2fe60e9ac8 100755
--- a/tests/fm-capacity.test.sh
+++ b/tests/fm-capacity.test.sh
@@ -113,7 +113,7 @@ test_classification_priority_overlap_and_idle_semantics() {
     and .readiness.available == true
     and (.pipeline.ready | length) == 2
     and (.readiness.conservative_overlap_gates | length) == 1
-    and (.readiness.explicit_gates | any(.reason == "dependency or structured hold"))
+    and (.readiness.explicit_gates | any(.reason == "Blocked by item-01"))
     and (.readiness.explicit_gates | any(.reason == "time gate until 2026-08-01"))
     and (.readiness.definition_gaps | any(.gaps | index("project unresolved")))
     and (.lanes.persistent_secondmates | any(.utilization == "idle with grounded ready in-scope work"))

From 32220a3c3e0ef8abb394df7444adb2c02b423f03 Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 13:14:39 -0400
Subject: [PATCH 15/24] no-mistakes(document): Document persistent tailnet
 capacity dashboard

---
 README.md                 |  2 +-
 bin/fm-dash-inbox.sh      |  7 ++++---
 bin/fm-dash-serve.mjs     |  4 ++--
 docs/configuration.md     |  2 +-
 docs/dashboard-service.md | 10 +++++-----
 5 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 8422be811ae..786fb5feb47 100644
--- a/README.md
+++ b/README.md
@@ -165,7 +165,7 @@ Claude and grok use the slash form shown here; codex uses the same names with `$
 | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | `/afk`             | Enter away-mode supervision: the sub-supervisor self-handles routine notifications in bash, escalates captain-relevant events and bounded declared-external-wait rechecks as batched digests, and actively alerts if delivery gets stuck while you step away |
 | `/bearings`        | Generate a standalone current-status report from bounded local fleet and registered-secondmate state, with live PR enrichment only when requested, written to a dated file in `data/` and surfaced concisely in chat; read-mostly, mutates no task state |
-| `/capacity`        | Diagnose meaningful ready-work supply and delivery bottlenecks, render a private offline pipeline dashboard with stable action IDs, and keep all approved follow-ups inside the normal safety lifecycle |
+| `/capacity`        | Diagnose meaningful ready-work supply and delivery bottlenecks, render a private offline pipeline dashboard with stable action IDs, optionally publish it through the persistent tailnet-only dashboard service, and keep all approved follow-ups inside the normal safety lifecycle |
 | `/user-journey-audit` | Audit one isolated local application through browser-driven, product-derived personas, automatically route confirmed ordinary bugs for fixes, and queue grounded feature opportunities without implementing or merging them |
 | `/updatefirstmate` | Self-update the running firstmate and its secondmates to the latest from origin with fast-forward-only pulls, then re-read instructions and nudge secondmates |
 | `/stow`            | Sweep the session for uncaptured durable knowledge, route each finding to its disk home per AGENTS.md, file undone next steps to the backlog, and report what is now safe to reset |
diff --git a/bin/fm-dash-inbox.sh b/bin/fm-dash-inbox.sh
index 8524d4b8a62..d0875a8f649 100755
--- a/bin/fm-dash-inbox.sh
+++ b/bin/fm-dash-inbox.sh
@@ -6,9 +6,10 @@
 # durably. "claim" prints each record before archiving it under
 # state/dash-inbox/archive/ (newest 50 kept), so an interruption can re-surface
 # a command but can never silently lose one. Delivery is at-least-once across
-# interruption, and the capacity skill requires idempotency checks before handling re-surfaced records:
-# each claimed prompt is the captain's approval of that CAP action ID with all
-# of that skill's authority limits, never destructive or merge authority.
+# interruption, and the capacity skill requires idempotency checks before
+# handling re-surfaced CAP actions, decision answers, or idea verdicts.
+# Each claimed prompt carries the capacity skill's authority limits and never
+# grants destructive or merge authority.
 #
 # Usage: fm-dash-inbox.sh [list|claim|pending-count]
 #   list           print pending commands without consuming them
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
index 9c00a8492e6..ff2aacb89cf 100755
--- a/bin/fm-dash-serve.mjs
+++ b/bin/fm-dash-serve.mjs
@@ -10,8 +10,8 @@
  * firstmate-side consumption of the records this service writes.
  *
  * The service never executes fleet commands, calls only the read-mostly capacity
- * producer and quota probe, and never mutates any state
- * outside state/dash-inbox/ and the producer-owned dashboard file. A clicked
+ * producer and quota probe, and mutates only state/dash-inbox/ plus the
+ * producer-owned dashboard and private refs sidecar. A clicked
  * CAP action becomes one durable fm-dash-command.v1 record in state/dash-inbox/;
  * the running firstmate consumes it through its registered fm-dash watcher check
  * (bin/fm-dash-inbox.sh claim). Delivery therefore rides the sanctioned wake
diff --git a/docs/configuration.md b/docs/configuration.md
index cbb185f50ea..63b2a42f2c5 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -105,7 +105,7 @@ See [`wedge-alarm.md`](wedge-alarm.md) for the channel reference and macOS verif
 ## Capacity dashboard service (config/dash.json)
 
 The optional persistent dashboard service publishes `data/capacity-dashboard.html` tailnet-only at one stable HTTPS URL, adds one-click `CAP-NN` dispatch, clickable de-anonymized work-item and decision detail views, idea verdicts over `data/ideas/`, and a server-side refresh, and delivers clicked commands to the running Firstmate through durable `state/dash-inbox/` records surfaced by the registered `fm-dash` watcher check.
-`config/dash.json` (local, gitignored, written by `bin/fm-dash-install.sh`) holds `port` (loopback service port, default 8847), `serve_port` (active tailnet HTTPS port, default 8443), `captain_logins` (the tailnet logins allowed to reach the service), `read_only` (serve and auto-render without any mutation route), and `auto_refresh_seconds` (producer rerun interval, default 900, 0 disables); the service fails closed without a matching `Tailscale-User-Login` identity.
+`config/dash.json` (local, gitignored, written by `bin/fm-dash-install.sh`) holds `port` (loopback service port, default 8847), `serve_port` (active tailnet HTTPS port, default 8443), `captain_logins` (the tailnet logins allowed to reach the service), `read_only` (serve, refresh, and auto-render without command dispatch), and `auto_refresh_seconds` (producer rerun interval, default 900, 0 disables); the service fails closed without a matching `Tailscale-User-Login` identity.
 The service reads the producer's opt-in `state/dash-refs.json` identity sidecar (`fm-capacity.mjs --refs`) to enrich the served page; the on-disk dashboard itself stays identity-opaque.
 `bin/fm-dash-serve.mjs --help` owns routes and the one-click allowlist, `bin/fm-dash-install.sh --help` owns launchd persistence and the never-Funnel tailscale serve wiring, `bin/fm-dash-inbox.sh --help` owns command consumption, and [`dashboard-service.md`](dashboard-service.md) owns the architecture and trust design.
 
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index 42f9e71e534..20bf9148f25 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -1,14 +1,14 @@
 # Persistent tailnet-only capacity dashboard service
 
 This document owns the architecture narrative, trust design, and verification evidence for the always-on capacity dashboard.
-Mechanics live with their owners: `bin/fm-dash-serve.mjs --help` (routes, config schema, one-click allowlist), `bin/fm-dash-install.sh --help` (persistence and tailscale wiring), `bin/fm-dash-inbox.sh --help` (command consumption), and the capacity skill (handling semantics for delivered commands).
+Mechanics live with their owners: `docs/configuration.md` (config schema), `bin/fm-dash-serve.mjs --help` (routes and one-click allowlist), `bin/fm-dash-install.sh --help` (persistence and tailscale wiring), `bin/fm-dash-inbox.sh --help` (command consumption), and the capacity skill (handling semantics for delivered commands).
 
 ## What it is
 
 The service publishes the producer-generated `data/capacity-dashboard.html` at one stable tailnet HTTPS URL that survives reboots, and layers interactive abilities onto it:
 
 - Every current one-click-eligible `CAP-NN` action gets an "Approve & send" button.
-- A "Refresh capacity" button reruns `bin/fm-capacity.mjs` server-side and reloads the page; the producer also reruns automatically on the configured interval so the page never goes stale.
+- A "Refresh capacity" button reruns `bin/fm-capacity.mjs` server-side and reloads the page; the service also reruns the producer automatically on the configured interval.
 - The page is de-anonymized for the authenticated captain: opaque `item-NN`/`project-NN`/`home-NN` references become real names, and work items and decisions are clickable rich detail views (description, test plan, PR link, tailnet preview links, report excerpt, recent activity) assembled from task briefs, recorded metadata, the backlog, and scout reports.
 - Open decisions with `data/<origin>/decisions/<key>.md` records show each recorded option with its impact, a per-option Approve button, and a bounded custom-answer control.
 - An Ideas section renders `data/ideas/idea-backlog.md`; each idea opens its pitch (`data/ideas/pitches/IDEA-XX.md` when present, else the concept summary) with Approve, Deny, and Add-suggestions controls.
@@ -38,7 +38,7 @@ The design keeps the web process outside every fleet-mutation path:
 
 Consequences of that shape:
 
-- The service holds no session with firstmate, no terminal access, and no merge, dispatch, or teardown capability; compromise of the web process yields at most bogus `CAP-NN` approval records, which firstmate still re-resolves through every normal lifecycle authority check.
+- The service holds no session with firstmate, no terminal access, and no merge, dispatch, or teardown capability; compromise of the web process yields at most bogus dashboard command records, which firstmate still re-resolves through every normal lifecycle authority check.
 - Delivery is durable: a click made while firstmate is down waits in the inbox and is delivered on the next watcher cycle or session start sweep of pending checks.
 - Delivery latency is the watcher check cadence, not instantaneous; the page says "queued for firstmate" honestly rather than pretending immediacy.
 - Commands survive service restarts, firstmate restarts, and reboots because the inbox is plain durable state.
@@ -50,7 +50,7 @@ Identity is enforced at every layer that can fail:
 
 - `tailscale serve` terminates HTTPS on the tailnet and injects the `Tailscale-User-Login` header for the authenticated tailnet peer; Funnel traffic would carry no such identity.
 - The service refuses every route except `/healthz` unless that header matches a login in `config/dash.json` (`captain_logins`, recorded from the tailnet self login at install time or passed with `--captain`).
-- Authenticated browser POSTs must also carry a matching Origin and `Sec-Fetch-Site: same-origin`; headerless same-machine clients remain allowed because a local process is already inside the filesystem trust boundary.
+- Authenticated browser POSTs must also carry a matching Origin and `Sec-Fetch-Site: same-origin`; same-machine clients without Origin or `Sec-Fetch-Site` headers remain allowed because a local process is already inside the filesystem trust boundary.
 - With no configured captain login the service serves only a setup notice and refuses everything else.
 - The service binds 127.0.0.1, so the only remote path in is the tailscale proxy; a local process on the captain's machine is already inside the trust boundary because it could write `FM_HOME` state directly.
 
@@ -101,7 +101,7 @@ bin/fm-dash-install.sh status
 bin/fm-dash-install.sh uninstall
 ```
 
-A read-only install is the right shape for running the service ahead of command-consumption wiring: the page, detail views, refresh, and auto-render all work, every mutation route refuses, and any watcher registration from a prior writable install is removed.
+A read-only install is the right shape for running the service ahead of command-consumption wiring: the page, detail views, refresh, and auto-render all work, command dispatch refuses, and any watcher registration from a prior writable install is removed.
 
 Install is idempotent and prints the stable URL, `https://<machine>.<tailnet>.ts.net:8443/`.
 Changing `--serve-port` stages the full replacement, verifies it, removes the previous mapping, and restores the prior config, launchd state, watcher registration, and observed live mapping state if any step fails.

From 50bb3f56c0cbb200c4a286a2fa3a1a9f383dc40b Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 13:23:31 -0400
Subject: [PATCH 16/24] no-mistakes(lint): Captain: targeted ShellCheck notices
 silenced

---
 tests/fm-dash.test.sh | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index de69fe4f677..1e6343aa684 100644
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -366,6 +366,8 @@ test_decision_answers_are_qualified_by_home_and_origin() {
   cp "$HOME_DIR/data/active-task/decisions/runtime-policy.md" "$HOME_DIR/data/origin-alpha/decisions/shared-policy.md"
   cp "$HOME_DIR/data/active-task/decisions/rollout-policy.md" "$HOME_DIR/data/origin-beta/decisions/shared-policy.md"
   cp "$HOME_DIR/data/active-task/decisions/runtime-policy.md" "$HOME_DIR/design/data/design-origin/decisions/shared-policy.md"
+  # JavaScript template literals are intentionally single-quoted for the shell.
+  # shellcheck disable=SC2016
   node -e '
     const fs = require("node:fs");
     const file = process.argv[1];
@@ -402,6 +404,8 @@ EOF
 test_stale_refs_are_disabled() {
   local ref
   ref=$(ref_for "decision/main/active-task/runtime-policy") || fail "refs sidecar does not map the decision"
+  # JavaScript template literals are intentionally single-quoted for the shell.
+  # shellcheck disable=SC2016
   node -e '
     const fs = require("node:fs");
     const file = process.argv[1];
@@ -415,6 +419,8 @@ test_stale_refs_are_disabled() {
   [ "$REQ_STATUS" = 404 ] || fail "stale refs still resolved detail (got $REQ_STATUS)"
   req POST "http://127.0.0.1:$PORT/api/dispatch" "$CAPTAIN" "{\"ref\":\"$ref\",\"option\":0}"
   [ "$REQ_STATUS" = 400 ] || fail "stale refs still authorized an approval (got $REQ_STATUS)"
+  # JavaScript template literals are intentionally single-quoted for the shell.
+  # shellcheck disable=SC2016
   node -e '
     const fs = require("node:fs");
     const file = process.argv[1];
@@ -604,6 +610,8 @@ test_installer_plist_and_funnel_stance() {
   assert_contains "$funnel_check" 'could not verify Funnel state' "Funnel verification does not report unreadable status"
   assert_contains "$funnel_check" 'process.exit(1)' "Funnel verification does not fail closed"
   assert_contains "$(sed -n '/if ! assert_no_funnel/,/fi/p' "$INSTALL_SH")" 'fail_install' "failed Funnel verification does not enter transactional rollback"
+  # The single-quoted assertion is intentionally literal.
+  # shellcheck disable=SC2016
   assert_contains "$(sed -n '/^rollback_install()/,/^fail_install()/p' "$INSTALL_SH")" 'disable_serve_port "$TX_NEW_SERVE_PORT"' "transactional rollback does not tear down the replacement mapping"
   assert_contains "$(sed -n '/^cmd_install()/,/^cmd_uninstall()/p' "$INSTALL_SH")" 'unregister_check' "read-only install does not unregister a prior writable watcher"
   assert_contains "$(sed -n '/^cmd_uninstall()/,/^cmd_status()/p' "$INSTALL_SH")" 'unregister_check' "uninstall does not unregister the watcher"

From 761c3f0c91719efd16b1b6eddf657261288b2d21 Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 13:37:04 -0400
Subject: [PATCH 17/24] no-mistakes: apply CI fixes

---
 tests/fm-dash.test.sh | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 mode change 100644 => 100755 tests/fm-dash.test.sh

diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
old mode 100644
new mode 100755

From e7cbd851421d580819de672047c70c1ab192a9ed Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 14:10:31 -0400
Subject: [PATCH 18/24] fix(dash): honest prod rendering - launchd env, no
 fabricated decisions, blocker chains, zero copy

Two live-use defects and two dropped ordered requirements, found on the
deployed read-only service:

- The launchd agent ran the capacity generator with launchd's minimal PATH,
  so every state-reader tool (tmux, no-mistakes, tasks-axi, gh) was
  unresolvable and all worker states degraded silently to unknown. The
  installer now pins the installing shell's PATH into the agent, and the
  service marks a mostly-unknown render RENDER DEGRADED loudly on the page
  and in its log instead of presenting degraded data as truth.
- A keyless needs-decision status event was fabricated into a captain
  decision literally keyed 'default' with a dead-end detail view. Keyless
  fold entries now surface honestly as a worker question firstmate is
  handling in chat: no decision identity, no Decide row, no dead-end modal.
- Blocked rows now carry their plain-language blocker chain resolved
  recursively to the root cause (blocking task state, time gate, or captain
  decision) plus an explicit What-you-can-do line, kept privacy-safe in the
  offline artifact with opaque references that de-anonymize at serve time.
- The served page now has zero copy-prompt affordances: producer copy
  buttons are replaced by direct dispatch, or removed in read-only mode,
  while the offline file keeps them for file:// use.

Regression coverage in tests/fm-capacity.test.sh (keyless questions and
chains stay privacy-safe) and tests/fm-dash.test.sh (plist PATH pinning,
degraded banner, copy-affordance replacement).
---
 bin/fm-capacity.mjs       | 123 +++++++++++++++++++++++++++++++++++---
 bin/fm-dash-install.sh    |   9 ++-
 bin/fm-dash-serve.mjs     |  34 +++++++++--
 docs/dashboard-service.md |   3 +
 tests/fm-capacity.test.sh |  41 +++++++++++++
 tests/fm-dash.test.sh     |  31 ++++++++++
 6 files changed, 227 insertions(+), 14 deletions(-)

diff --git a/bin/fm-capacity.mjs b/bin/fm-capacity.mjs
index 50869275694..9168959a144 100755
--- a/bin/fm-capacity.mjs
+++ b/bin/fm-capacity.mjs
@@ -607,11 +607,18 @@ function classify(snapshot, environment) {
       markUnavailable(itemRef("main", task.id), "main", "in-flight work lacks project provenance");
     }
     const open = task.hints?.open_decisions || [];
+    // A keyless fold entry (key "default") is a worker question firstmate is
+    // handling in chat, never a fabricated captain decision: it gets no
+    // decision identity, no Decide row, and no dead-end detail view. Event
+    // summaries stay out of this privacy-bounded artifact; the authenticated
+    // dashboard service surfaces the concrete text in its detail views.
+    const chatQuestionCount = open.filter((decision) => !decision.key || decision.key === "default").length;
     for (const decision of open) {
+      if (!decision.key || decision.key === "default") continue;
       decisions.push({
         owner: "main",
         task: itemRef("main", task.id),
-        key: decisionRef("main", task.id, decision.key || task.id),
+        key: decisionRef("main", task.id, decision.key),
         reason: "Open decision raised by work already under way.",
       });
     }
@@ -622,6 +629,29 @@ function classify(snapshot, environment) {
       aging.push({ id: itemRef("main", task.id), owner: "main", age_days: ageDays, state: safeState(task.current_state?.state), evidence: `structured backlog age; current source ${safeSource(task.current_state?.source)}` });
     }
     const approvalReady = taskApprovalReady(task);
+    const keyedOpen = open.filter((decision) => decision.key && decision.key !== "default");
+    let taskWaits = null;
+    let taskCanDo = null;
+    if (stage === "blocked") {
+      const state = safeState(task.current_state?.state);
+      if (chatQuestionCount > 0) {
+        taskWaits = ["a worker question is being handled in chat"];
+        taskCanDo = "Nothing - firstmate is handling the worker's question in chat.";
+      } else if (keyedOpen.length > 0) {
+        const ref = decisionRef("main", task.id, keyedOpen[0].key);
+        taskWaits = [`waiting on your decision ${ref}`];
+        taskCanDo = `Answer decision ${ref} - it is the root cause.`;
+      } else if (state === "paused") {
+        taskWaits = ["waiting on a declared external delay expected to clear on its own"];
+        taskCanDo = "Nothing - this unblocks itself when the external wait clears.";
+      } else if (state === "unknown") {
+        taskWaits = ["its current state could not be read"];
+        taskCanDo = "Nothing yet - firstmate reconciles the unavailable state and escalates if your input is needed.";
+      } else {
+        taskWaits = [`the worker reports state: ${state}`];
+        taskCanDo = "Nothing yet - firstmate is on it and will escalate if your input is needed.";
+      }
+    }
     pipeline[stage].push({
       id: itemRef("main", task.id),
       title: `${STAGE_LABELS[stage]} work item`,
@@ -629,16 +659,70 @@ function classify(snapshot, environment) {
       repo: projectRef(taskRepo),
       kind: ["ship", "scout"].includes(task.kind) ? task.kind : null,
       stage,
-      reason: `Authoritative current state: ${safeState(task.current_state?.state)}`,
+      reason: chatQuestionCount > 0
+        ? "Worker question being handled in chat"
+        : `Authoritative current state: ${safeState(task.current_state?.state)}`,
       artifact: null,
       provenance: `current state from ${safeSource(task.current_state?.source)}`,
       age_days: ageDays,
       approval_ready: approvalReady,
       approval_authority: approvalReady ? (task.yolo === "on" ? "firstmate" : "captain") : null,
       captain_approval_required: approvalReady && task.yolo !== "on",
+      waits_on: taskWaits,
+      what_you_can_do: taskCanDo,
     });
   }
 
+  // Resolve a blocked backlog item's full blocker chain to its root cause in
+  // plain language, so no blocked row leaves the captain guessing what it
+  // waits on or whether anything is theirs to do.
+  const describeBlockedRecord = (startRecord) => {
+    const waits = [];
+    const seen = new Set();
+    let record = startRecord;
+    for (let hop = 0; hop < 5 && record; hop += 1) {
+      if (record !== startRecord && record.kind === "captain" && record.hold_kind === "captain") {
+        const identity = backlogDecisionIdentity(record);
+        const ref = decisionRef("main", identity.origin, identity.key);
+        waits.push(`waiting on your decision ${ref}`);
+        return { waits, action: `Answer decision ${ref} - it is the root cause.` };
+      }
+      const gate = futureTimeGate(record, now);
+      if (gate) {
+        waits.push(`waiting until ${gate}`);
+        return { waits, action: `Nothing - this unblocks itself when the ${gate} time gate passes.` };
+      }
+      if (!record.blocked_by) {
+        if (record.hold_reason) {
+          waits.push("held by a structured hold");
+          return { waits, action: "Nothing yet - firstmate watches this hold and escalates if your input is needed." };
+        }
+        break;
+      }
+      const blockerId = record.blocked_by;
+      if (seen.has(blockerId)) break;
+      seen.add(blockerId);
+      const blockerTask = taskById.get(blockerId);
+      const blockerRecord = mainRecords.find((entry) => entry.structured && entry.id === blockerId) || null;
+      const blockerRef = itemRef("main", blockerId);
+      if (blockerTask) {
+        waits.push(`blocked by ${blockerRef} which is currently ${safeState(blockerTask.current_state?.state)}`);
+      } else if (blockerRecord) {
+        const nextHop = blockerRecord.blocked_by || futureTimeGate(blockerRecord, now) || (blockerRecord.kind === "captain" && blockerRecord.hold_kind === "captain");
+        waits.push(`blocked by ${blockerRef} which is ${blockerRecord.state === "in_flight" ? "under way" : "queued and not started"}${nextHop ? "" : ""}`);
+      } else {
+        waits.push(`blocked by ${blockerRef} whose current state is unavailable`);
+        return { waits, action: "Nothing yet - firstmate reconciles that unavailable blocker and escalates if your input is needed." };
+      }
+      if (!blockerRecord || (!blockerRecord.blocked_by && !futureTimeGate(blockerRecord, now) && !(blockerRecord.kind === "captain" && blockerRecord.hold_kind === "captain"))) {
+        return { waits, action: `Nothing - this unblocks itself when ${blockerRef} finishes.` };
+      }
+      record = blockerRecord;
+    }
+    if (waits.length === 0) waits.push("its blocker could not be resolved from the structured queue");
+    return { waits, action: "Nothing yet - firstmate reconciles this blocker and escalates if your input is needed." };
+  };
+
   const queue = mainRecords.filter((record) => record.state === "queued");
   const candidates = [];
   for (const record of queue) {
@@ -650,27 +734,38 @@ function classify(snapshot, environment) {
     if (isSuperseded(record)) continue;
     if (record.kind === "captain" && record.hold_kind === "captain") {
       const decision = backlogDecisionIdentity(record);
+      const holdRef = decisionRef("main", decision.origin, decision.key);
       decisions.push({
         owner: "main",
         task: itemRef("main", record.id),
-        key: decisionRef("main", decision.origin, decision.key),
+        key: holdRef,
         reason: "A queued choice is held for your decision.",
       });
       blockedRows.push({ id: itemRef("main", record.id), owner: "main", reason: "captain hold" });
-      pipeline.blocked.push(cardFromBacklog(record, "main", "blocked", "Captain hold"));
+      pipeline.blocked.push(Object.assign(cardFromBacklog(record, "main", "blocked", "Captain hold"), {
+        waits_on: [`waiting on your decision ${holdRef}`],
+        what_you_can_do: `Answer decision ${holdRef} - it is the root cause.`,
+      }));
       continue;
     }
     if (record.blocked_by || record.hold_reason) {
       const reason = record.blocked_by ? `Blocked by ${itemRef("main", record.blocked_by)}` : "Structured hold";
+      const chain = describeBlockedRecord(record);
       blockedRows.push({ id: itemRef("main", record.id), owner: "main", reason });
-      pipeline.blocked.push(cardFromBacklog(record, "main", "blocked", reason));
+      pipeline.blocked.push(Object.assign(cardFromBacklog(record, "main", "blocked", reason), {
+        waits_on: chain.waits,
+        what_you_can_do: chain.action,
+      }));
       continue;
     }
     const timeGate = futureTimeGate(record, now);
     if (timeGate) {
       const reason = `time gate until ${timeGate}`;
       blockedRows.push({ id: itemRef("main", record.id), owner: "main", reason });
-      pipeline.blocked.push(cardFromBacklog(record, "main", "blocked", reason));
+      pipeline.blocked.push(Object.assign(cardFromBacklog(record, "main", "blocked", reason), {
+        waits_on: [`waiting until ${timeGate}`],
+        what_you_can_do: `Nothing - this unblocks itself when the ${timeGate} time gate passes.`,
+      }));
       continue;
     }
     const gaps = definitionGaps(record);
@@ -715,6 +810,7 @@ function classify(snapshot, environment) {
     if (!scopeAvailable) markUnavailable(opaqueRef("home", mate.id), "persistent secondmate", "registered routing scope unavailable");
     if (!runtime) markUnavailable(opaqueRef("home", mate.id), "persistent secondmate", "home-owned runtime lane evidence unavailable");
     for (const decision of mate.decisions_open || []) {
+      if ((decision.key || "default") === "default" && !decision.id) continue;
       decisions.push({
         owner: ownerRef(mate.id),
         task: itemRef(mate.id, decision.id || mate.id),
@@ -1236,12 +1332,21 @@ function artifact(value) {
   return `<a href="${h(safe)}">${h(safe)}</a>`;
 }
 
+// Plain-language blocker context: the recursive chain plus the explicit
+// captain action (or explicit nothing-to-do), rendered under a blocked row.
+function blockedContext(card) {
+  if (!card.waits_on || card.waits_on.length === 0) return "";
+  const chain = card.waits_on.map((wait) => h(wait)).join("; then ");
+  const action = card.what_you_can_do ? `<small class="cando">What you can do: ${h(card.what_you_can_do)}</small>` : "";
+  return `<small class="chain">${chain}.</small>${action}`;
+}
+
 function manifestRow(card) {
   const meta = [card.kind, card.age_days !== null && card.age_days !== undefined ? `${card.age_days}d` : null]
     .filter(Boolean).map((part) => h(part)).join(" · ");
   return `<li class="mrow">
     <span class="mid"><span class="item-id">${h(card.id)}</span><span class="mowner">${h(card.owner)}${card.repo ? ` · ${h(card.repo)}` : ""}</span></span>
-    <span class="mreason">${h(card.reason || "No additional gate detail.")}${card.artifact ? ` ${artifact(card.artifact)}` : ""}</span>
+    <span class="mreason">${h(card.reason || "No additional gate detail.")}${card.artifact ? ` ${artifact(card.artifact)}` : ""}${blockedContext(card)}</span>
     <span class="mmeta">${meta}</span>
   </li>`;
 }
@@ -1279,7 +1384,7 @@ function renderHtml(model, captainActions) {
     ...captainApprovalCards.map((card) => `<li><span class="verb verb-approve">Approve</span><span class="who"><span class="item-id">${h(card.id)}</span> ${h(card.owner)}${card.repo ? ` · ${h(card.repo)}` : ""}</span><span class="why">Finished work is ready for your approval.</span></li>`),
     ...captainActions.map((action) => `<li><span class="verb verb-decide">Decide</span><span class="who"><span class="item-id">${h(action.key)}</span> ${h(action.owner)} · work ${h(action.task)}</span><span class="why">${h(action.reason)}</span></li>`),
   ].join("");
-  const blockedRows = otherBlockedCards.map((card) => `<li><span class="verb verb-blocked">Stuck</span><span class="who"><span class="item-id">${h(card.id)}</span> ${h(card.owner)}${card.repo ? ` · ${h(card.repo)}` : ""}</span><span class="why">${h(card.reason || "Unspecified gate")}</span></li>`).join("");
+  const blockedRows = otherBlockedCards.map((card) => `<li><span class="verb verb-blocked">Stuck</span><span class="who"><span class="item-id">${h(card.id)}</span> ${h(card.owner)}${card.repo ? ` · ${h(card.repo)}` : ""}</span><span class="why">${h(card.reason || "Unspecified gate")}${blockedContext(card)}</span></li>`).join("");
 
   const blockedReasonCounts = new Map();
   for (const card of otherBlockedCards) {
@@ -1372,6 +1477,8 @@ function renderHtml(model, captainActions) {
     .verb-approve{color:var(--blue)}.verb-decide{color:var(--serious)}.verb-blocked{color:var(--crit)}
     .who{font-weight:650;min-width:0}.who .item-id{margin-right:.35rem}
     .why{color:var(--ink2);font-size:.92rem;min-width:0}
+    .chain{display:block;color:var(--muted);font-size:.8rem;margin-top:.25rem}
+    .cando{display:block;color:var(--ink);font-size:.8rem;font-weight:650;margin-top:.15rem}
     .item-id{font:700 .82rem ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--ink)}
     .next{margin-top:2rem;font-size:clamp(1.05rem,1.8vw,1.25rem)}
     .prompt{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:.7rem;align-items:center;margin-top:.9rem;border:1px solid var(--line);padding:.65rem .8rem;background:color-mix(in srgb,var(--bg) 55%,transparent)}
diff --git a/bin/fm-dash-install.sh b/bin/fm-dash-install.sh
index d02f5163fe9..22625297545 100755
--- a/bin/fm-dash-install.sh
+++ b/bin/fm-dash-install.sh
@@ -319,12 +319,18 @@ snapshot_file() {
 }
 
 render_plist() {
-  local label node_path log_dir fm_root fm_home
+  local label node_path log_dir fm_root fm_home path_env
   label=$(xml_escape "$1")
   node_path=$(xml_escape "$2")
   log_dir=$(xml_escape "$3")
   fm_root=$(xml_escape "$FM_ROOT")
   fm_home=$(xml_escape "$FM_HOME")
+  # launchd starts agents with a minimal PATH that cannot resolve the state
+  # reader tools (tmux, no-mistakes, tasks-axi, gh), which silently degrades
+  # every rendered state to unknown. Capture the installing shell's full PATH
+  # so the service and the generator it runs see the same tools the captain's
+  # interactive runs do.
+  path_env=$(xml_escape "$PATH")
   cat <<PLIST
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -339,6 +345,7 @@ render_plist() {
   <key>EnvironmentVariables</key>
   <dict>
     <key>FM_HOME</key><string>$fm_home</string>
+    <key>PATH</key><string>$path_env</string>
   </dict>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><true/>
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
index ff2aacb89cf..4c9e886cdc6 100755
--- a/bin/fm-dash-serve.mjs
+++ b/bin/fm-dash-serve.mjs
@@ -599,6 +599,7 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
     refs: extras?.refs || {},
     ideas: extras?.ideas || [],
     usage: extras?.usage || { status: "unavailable", providers: [] },
+    degraded: extras?.degraded === true,
   });
   return `<style>
   .fmdash-bar{display:flex;justify-content:space-between;align-items:center;gap:.6rem 1.5rem;flex-wrap:wrap;padding:.6rem clamp(1rem,6vw,5rem);border-bottom:1px solid var(--line);background:var(--bg)}
@@ -610,6 +611,7 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
   .fmdash-send{border:1px solid var(--ink);background:transparent;color:var(--ink);font-weight:700;padding:.5rem .9rem;cursor:pointer;font-size:.82rem;grid-column:2}
   .fmdash-send[disabled]{opacity:.55;cursor:default}
   .fmdash-chat{color:var(--muted);font-size:.76rem;align-self:center}
+  .fmdash-degraded{background:var(--crit);color:#fff;font-weight:800;font-size:.85rem;letter-spacing:.05em;padding:.7rem clamp(1rem,6vw,5rem)}
   .fmdash-click{cursor:pointer;text-decoration:underline;text-decoration-color:var(--muted);text-underline-offset:.22em}
   .fmdash-click:hover,.fmdash-click:focus-visible{color:var(--blue);text-decoration-color:var(--blue)}
   .fmdash-overlay{position:fixed;inset:0;background:color-mix(in srgb,var(--bg) 55%,transparent);backdrop-filter:blur(2px);display:grid;place-items:start center;overflow-y:auto;padding:clamp(1rem,6vh,4rem) 1rem;z-index:50}
@@ -645,6 +647,16 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
       + '<span class="fmdash-pending"></span>'
       + '<button type="button" class="fmdash-refresh">Refresh capacity</button>';
     document.body.prepend(bar);
+    if (cfg.degraded) {
+      const warn = document.createElement("div");
+      warn.className = "fmdash-degraded";
+      warn.setAttribute("role", "alert");
+      warn.textContent = "RENDER DEGRADED - most worker states read as unknown, so this page may not reflect reality. The service environment is likely missing its state-reader tools; fix the environment and refresh.";
+      bar.after(warn);
+    }
+    // Zero copy-prompt affordances on the served page: every producer copy
+    // button is removed here and, where eligible, replaced by direct dispatch.
+    const copyButtons = [...document.querySelectorAll("button[data-copy]")];
     const pendingEl = bar.querySelector(".fmdash-pending");
     const showPending = (n) => {
       pendingEl.textContent = cfg.readOnly
@@ -1055,15 +1067,18 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
         box.focus();
       });
     }
-    if (cfg.readOnly) return;
-    document.querySelectorAll("button[data-copy]").forEach((copyButton) => {
+    if (cfg.readOnly) {
+      copyButtons.forEach((copyButton) => copyButton.remove());
+      return;
+    }
+    copyButtons.forEach((copyButton) => {
       const id = ((copyButton.dataset.copy || "").match(/CAP-\\d{2}/) || [])[0];
-      if (!id) return;
+      if (!id) { copyButton.remove(); return; }
       if (!cfg.dispatchable.includes(id)) {
         const note = document.createElement("span");
         note.className = "fmdash-chat";
         note.textContent = "Raise in captain chat";
-        copyButton.after(note);
+        copyButton.replaceWith(note);
         return;
       }
       const send = document.createElement("button");
@@ -1086,7 +1101,7 @@ function interactiveLayer(dispatchable, pending, generated, readOnly, extras) {
           send.disabled = false;
         } catch { send.textContent = "Failed"; send.disabled = false; }
       });
-      copyButton.after(send);
+      copyButton.replaceWith(send);
     });
   })();
   </script>`;
@@ -1146,10 +1161,19 @@ async function handle(req, res) {
     const dispatchable = config.readOnly ? [] : [...dashboard.actions.keys()].filter((id) => ONE_CLICK_ACTIONS.has(id));
     const refsFile = readRefs(dashboard.generated);
     const usage = await probeUsage();
+    // Degraded-render self-check: when most worker states rendered as unknown,
+    // the generator likely ran without its state-reader tools (for example a
+    // stripped launchd environment). Say so loudly rather than presenting
+    // degraded data as truth.
+    const unknownStates = (dashboard.html.match(/Authoritative current state: unknown/g) || []).length;
+    const manifestRows = (dashboard.html.match(/class="mrow"/g) || []).length;
+    const degraded = unknownStates >= 3 && unknownStates * 2 >= manifestRows;
+    if (degraded) log(`degraded render detected: ${unknownStates} of ${manifestRows} manifest rows read unknown; check the service environment (PATH/tools)`);
     const layer = interactiveLayer(dispatchable, pendingRecords().length, dashboard.generated, config.readOnly, {
       refs: refsFile ? refDisplayMap(refsFile) : {},
       ideas: parseIdeas().map((idea) => ({ id: idea.id, title: idea.title })),
       usage,
+      degraded,
     });
     sendHtml(res, 200, dashboard.html.replace("</body>", `${layer}</body>`));
     return;
diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index 20bf9148f25..b5287530fed 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -14,6 +14,9 @@ The service publishes the producer-generated `data/capacity-dashboard.html` at o
 - An Ideas section renders `data/ideas/idea-backlog.md`; each idea opens its pitch (`data/ideas/pitches/IDEA-XX.md` when present, else the concept summary) with Approve, Deny, and Add-suggestions controls.
 - A service bar shows how many captain commands are queued for firstmate.
 - A Subscription usage band shows cached `quota-axi --json` windows for Claude, Codex, and Grok, including percent used and reset distance with reset time formatted by the captain's browser in local time.
+- Every blocked row carries its plain-language blocker chain resolved to the root cause plus an explicit "What you can do" line, so no blocked row leaves the captain guessing; chains stay privacy-safe in the on-disk file and de-anonymize at serve time like every other reference.
+- The served page has zero copy-prompt affordances: each producer copy button is replaced by direct dispatch, or removed outright in read-only mode, while the offline file keeps its copy buttons for `file://` use.
+- The installer pins the installing shell's `PATH` into the launchd agent so the generator's state-reader tools resolve, and the service marks a render `RENDER DEGRADED` loudly on the page and in its log when most worker states read unknown - degraded data is never presented as truth.
 
 `bin/fm-capacity.mjs` remains the single owner of the dashboard's content and look; the service injects its interactive layer at serve time and never modifies the file on disk, so the file keeps working offline exactly as before.
 The on-disk dashboard stays identity-opaque: the producer's opt-in `--refs` sidecar (`state/dash-refs.json`, `fm-capacity-refs.v1`, mode 0600) carries the opaque-to-real mapping, and only the captain-authenticated service reads it to enrich the served page.
diff --git a/tests/fm-capacity.test.sh b/tests/fm-capacity.test.sh
index f2fe60e9ac8..61334251f9d 100755
--- a/tests/fm-capacity.test.sh
+++ b/tests/fm-capacity.test.sh
@@ -913,6 +913,46 @@ test_unknown_project_is_a_definition_gap() {
   pass "unknown projects remain definition gaps despite safe delivery-mode fallback"
 }
 
+test_keyless_questions_and_blocker_chains() {
+  local home="$TMP_ROOT/chains-home" snapshot="$TMP_ROOT/chains-snapshot.json" environment="$TMP_ROOT/chains-environment.json" output json html
+  output="$home/data/chains.html"
+  make_fixture "$home" "$snapshot" "$environment"
+  jq '
+    .backlog.records = [
+      {"order":1,"state":"in_flight","structured":true,"id":"asker","title":"Build the exporter","repo":"alpha","project_resolved":true,"kind":"ship","since":"2026-07-16","body_excerpt":"Acceptance criteria: exporter ships."},
+      {"order":2,"state":"in_flight","structured":true,"id":"keyed-asker","title":"Build the API","repo":"beta","project_resolved":true,"kind":"ship","since":"2026-07-16","body_excerpt":"Acceptance criteria: API ships."},
+      {"order":3,"state":"queued","structured":true,"id":"dependent","title":"Publish the dependent release","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"asker","blocked_reason":"needs exporter","body_excerpt":"Acceptance criteria: release ships."},
+      {"order":4,"state":"queued","structured":true,"id":"policy-choice","title":"Choose the rollout policy","repo":"alpha","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"pick conservative or fast"},
+      {"order":5,"state":"queued","structured":true,"id":"after-policy","title":"Apply the rollout policy","repo":"delta","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: rollout applied."}
+    ]
+    | .tasks = [
+      {"id":"asker","kind":"ship","project":"alpha","current_state":{"state":"blocked","source":"status-fold","detail":"awaiting reply"},"endpoint":{"exists":true,"agent_alive":"not_checked"},"hints":{"open_decisions":[{"key":"default","verb":"needs-decision","summary":"which port should the exporter bind"}]},"pr":{"url":null},"paths":{"report":{"present":false}},"backlog":{"id":"asker","title":"Build the exporter","repo":"alpha","project_resolved":true,"kind":"ship","since":"2026-07-16"}},
+      {"id":"keyed-asker","kind":"ship","project":"beta","current_state":{"state":"blocked","source":"status-fold","detail":"awaiting decision"},"endpoint":{"exists":true,"agent_alive":"not_checked"},"hints":{"open_decisions":[{"key":"api-shape","verb":"needs-decision","summary":"choose v1 or v2 response shape"}]},"pr":{"url":null},"paths":{"report":{"present":false}},"backlog":{"id":"keyed-asker","title":"Build the API","repo":"beta","project_resolved":true,"kind":"ship","since":"2026-07-16"}}
+    ]
+    | .secondmate_current.registry.records = []
+    | .secondmate_current.records = []
+    | .secondmate_current.total = 0
+    | .secondmate_current.shown = 0
+  ' "$snapshot" > "$snapshot.tmp"
+  mv "$snapshot.tmp" "$snapshot"
+  json=$("$CAPACITY" --json --snapshot "$snapshot" --environment "$environment" --output "$output") ||
+    fail "keyless-question capacity run failed"
+  printf '%s' "$json" | jq -e '
+    (.pipeline.blocked | map(select(.reason | contains("Worker question being handled in chat"))) | length) == 1
+    and (.pipeline.blocked | map(select(.reason | contains("Worker question"))) | .[0].what_you_can_do | contains("firstmate is handling"))
+    and ([.pipeline.blocked[] | select(.waits_on != null) | .waits_on[0]] | any(contains("waiting on your decision")))
+    and ([.pipeline.blocked[] | .what_you_can_do // ""] | any(contains("unblocks itself when")))
+    and ([.pipeline.blocked[] | .waits_on // [] | join(" ")] | any(contains("blocked by") and contains("currently")))
+    and ([.pipeline.blocked[] | .waits_on // [] | join(" ")] | any(contains("which port")) | not)
+  ' >/dev/null || fail "keyless questions or blocker chains are wrong: $json"
+  html=$(cat "$output")
+  assert_contains "$html" 'What you can do:' "blocked rows omit the explicit captain action line"
+  case "$html" in
+    *'item-id">default'*) fail "a keyless worker question was fabricated into a decision identity" ;;
+  esac
+  pass "keyless worker questions stay chat-handled and blocked rows carry privacy-safe root-cause chains"
+}
+
 test_skill_discovery_and_read_mostly_contract
 test_classification_priority_overlap_and_idle_semantics
 test_cross_home_overlap_holds_supersession_and_active_count
@@ -933,3 +973,4 @@ test_html_is_private_escaped_accessible_and_responsive
 test_output_replacement_rejects_symlinks_and_enforces_mode
 test_fleet_snapshot_preserves_registered_scope_provenance
 test_unknown_project_is_a_definition_gap
+test_keyless_questions_and_blocker_chains
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index 1e6343aa684..918c7e73a86 100755
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -828,6 +828,35 @@ EOF
   pass "custom serve ports persist and old mappings are removed"
 }
 
+test_launchd_env_and_degraded_render_selfcheck() {
+  local plist rows
+  stop_server
+  start_server "$HOME_DIR" "$PORT"
+  plist=$(FM_HOME="$HOME_DIR" "$INSTALL_SH" print-plist) || fail "print-plist failed"
+  assert_contains "$plist" '<key>PATH</key>' "plist does not pin the installing PATH for launchd (states degrade to unknown without it)"
+  assert_contains "$plist" "$(dirname "$(command -v node)")" "plist PATH does not carry the node tool directory"
+  cp "$HOME_DIR/data/capacity-dashboard.html" "$TMP_ROOT/dashboard.bak"
+  rows=""
+  for _ in 1 2 3 4; do
+    rows="$rows<li class=\"mrow\"><span class=\"mreason\">Authoritative current state: unknown</span></li>"
+  done
+  printf '%s' "$(sed "s|</body>|$rows</body>|" "$TMP_ROOT/dashboard.bak")" > "$HOME_DIR/data/capacity-dashboard.html"
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  assert_contains "$RESP" 'RENDER DEGRADED' "a mostly-unknown render is presented as truth instead of loudly degraded"
+  cp "$TMP_ROOT/dashboard.bak" "$HOME_DIR/data/capacity-dashboard.html"
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  case "$RESP" in *'"degraded":true'*) fail "a healthy render is marked degraded" ;; esac
+  pass "launchd env is pinned and a mostly-unknown render is loudly marked degraded"
+}
+
+test_served_page_has_zero_copy_affordances() {
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  assert_contains "$RESP" 'copyButton.replaceWith(send)' "dispatch does not replace the copy button"
+  assert_contains "$RESP" 'copyButton.remove()' "read-only and non-action copy buttons are not removed"
+  case "$RESP" in *"copyButton.after(send)"*) fail "copy buttons are supplemented instead of replaced" ;; esac
+  pass "every copy-prompt affordance on the served page is replaced by direct dispatch"
+}
+
 test_service_contract_docs_and_ownership() {
   assert_present "$ROOT/docs/dashboard-service.md" "dashboard service doc is missing"
   assert_grep 'dash-inbox' "$ROOT/docs/dashboard-service.md" "service doc omits the inbound channel"
@@ -862,6 +891,8 @@ test_read_only_mode_fails_safe
 test_check_shim_wakes_only_when_pending
 test_installer_plist_and_funnel_stance
 test_installer_tracks_custom_serve_port
+test_launchd_env_and_degraded_render_selfcheck
+test_served_page_has_zero_copy_affordances
 test_service_contract_docs_and_ownership
 
 echo "fm-dash tests passed"

From 34751edb8a01e8a74086c0c6543432c0984ca4ef Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 14:18:38 -0400
Subject: [PATCH 19/24] no-mistakes(review): Fix captain decision, blocker, and
 degraded-state handling

---
 bin/fm-capacity.mjs       | 124 ++++++++++++++++++++++----------------
 bin/fm-dash-serve.mjs     |   6 +-
 tests/fm-capacity.test.sh |  19 ++++--
 tests/fm-dash.test.sh     |   8 ++-
 4 files changed, 97 insertions(+), 60 deletions(-)

diff --git a/bin/fm-capacity.mjs b/bin/fm-capacity.mjs
index 9168959a144..fd4f227dcd0 100755
--- a/bin/fm-capacity.mjs
+++ b/bin/fm-capacity.mjs
@@ -673,54 +673,56 @@ function classify(snapshot, environment) {
     });
   }
 
-  // Resolve a blocked backlog item's full blocker chain to its root cause in
-  // plain language, so no blocked row leaves the captain guessing what it
-  // waits on or whether anything is theirs to do.
-  const describeBlockedRecord = (startRecord) => {
-    const waits = [];
-    const seen = new Set();
-    let record = startRecord;
-    for (let hop = 0; hop < 5 && record; hop += 1) {
-      if (record !== startRecord && record.kind === "captain" && record.hold_kind === "captain") {
-        const identity = backlogDecisionIdentity(record);
-        const ref = decisionRef("main", identity.origin, identity.key);
-        waits.push(`waiting on your decision ${ref}`);
-        return { waits, action: `Answer decision ${ref} - it is the root cause.` };
+  const blockedByIds = (record) => String(record.blocked_by || "").split(",").map((id) => id.trim()).filter(Boolean);
+  const describeBlockedRecord = (startRecord, owner, records, tasks = []) => {
+    const recordById = new Map(records.filter((record) => record.structured !== false).map((record) => [record.id, record]));
+    const currentById = new Map(tasks.map((task) => [task.id, task.current_state?.state || task.state]));
+    const resolveBlocker = (blockerId, seen, depth) => {
+      const blockerRef = itemRef(owner, blockerId);
+      if (seen.has(blockerId) || depth >= 5) {
+        return [{ wait: `blocked by ${blockerRef}, whose blocker chain could not be resolved`, action: "Nothing yet - firstmate reconciles this blocker and escalates if your input is needed." }];
       }
-      const gate = futureTimeGate(record, now);
-      if (gate) {
-        waits.push(`waiting until ${gate}`);
-        return { waits, action: `Nothing - this unblocks itself when the ${gate} time gate passes.` };
+      const blockerRecord = recordById.get(blockerId) || null;
+      const currentState = currentById.get(blockerId);
+      if (!blockerRecord && !currentState) {
+        return [{ wait: `blocked by ${blockerRef}, whose current state is unavailable`, action: "Nothing yet - firstmate reconciles that unavailable blocker and escalates if your input is needed." }];
       }
-      if (!record.blocked_by) {
-        if (record.hold_reason) {
-          waits.push("held by a structured hold");
-          return { waits, action: "Nothing yet - firstmate watches this hold and escalates if your input is needed." };
-        }
-        break;
+      const prefix = currentState
+        ? `blocked by ${blockerRef}, which is currently ${safeState(currentState)}`
+        : `blocked by ${blockerRef}, which is ${blockerRecord.state === "in_flight" ? "under way" : "queued and not started"}`;
+      if (blockerRecord?.kind === "captain" && blockerRecord.hold_kind === "captain") {
+        const identity = backlogDecisionIdentity(blockerRecord);
+        const ref = decisionRef(owner, identity.origin, identity.key);
+        return [{ wait: `${prefix}; then waiting on your decision ${ref}`, action: `Answer decision ${ref} - it is the root cause.` }];
       }
-      const blockerId = record.blocked_by;
-      if (seen.has(blockerId)) break;
-      seen.add(blockerId);
-      const blockerTask = taskById.get(blockerId);
-      const blockerRecord = mainRecords.find((entry) => entry.structured && entry.id === blockerId) || null;
-      const blockerRef = itemRef("main", blockerId);
-      if (blockerTask) {
-        waits.push(`blocked by ${blockerRef} which is currently ${safeState(blockerTask.current_state?.state)}`);
-      } else if (blockerRecord) {
-        const nextHop = blockerRecord.blocked_by || futureTimeGate(blockerRecord, now) || (blockerRecord.kind === "captain" && blockerRecord.hold_kind === "captain");
-        waits.push(`blocked by ${blockerRef} which is ${blockerRecord.state === "in_flight" ? "under way" : "queued and not started"}${nextHop ? "" : ""}`);
-      } else {
-        waits.push(`blocked by ${blockerRef} whose current state is unavailable`);
-        return { waits, action: "Nothing yet - firstmate reconciles that unavailable blocker and escalates if your input is needed." };
+      const gate = blockerRecord && futureTimeGate(blockerRecord, now);
+      if (gate) {
+        return [{ wait: `${prefix}; then waiting until ${gate}`, action: `Nothing - this unblocks itself when the ${gate} time gate passes.` }];
+      }
+      const nestedIds = blockerRecord ? blockedByIds(blockerRecord) : [];
+      if (nestedIds.length > 0) {
+        const nextSeen = new Set(seen).add(blockerId);
+        return nestedIds.flatMap((id) => resolveBlocker(id, nextSeen, depth + 1).map((root) => ({
+          wait: `${prefix}; then ${root.wait}`,
+          action: root.action,
+        })));
       }
-      if (!blockerRecord || (!blockerRecord.blocked_by && !futureTimeGate(blockerRecord, now) && !(blockerRecord.kind === "captain" && blockerRecord.hold_kind === "captain"))) {
-        return { waits, action: `Nothing - this unblocks itself when ${blockerRef} finishes.` };
+      if (blockerRecord?.hold_reason) {
+        return [{ wait: `${prefix}; then held by a structured hold`, action: "Nothing yet - firstmate watches this hold and escalates if your input is needed." }];
       }
-      record = blockerRecord;
+      return [{ wait: prefix, action: `Nothing - this unblocks itself when ${blockerRef} finishes.` }];
+    };
+    const blockerIds = blockedByIds(startRecord);
+    if (blockerIds.length === 0) {
+      const gate = futureTimeGate(startRecord, now);
+      if (gate) return { waits: [`waiting until ${gate}`], action: `Nothing - this unblocks itself when the ${gate} time gate passes.` };
+      return { waits: ["held by a structured wait gate"], action: "Nothing yet - firstmate watches this hold and escalates if your input is needed." };
     }
-    if (waits.length === 0) waits.push("its blocker could not be resolved from the structured queue");
-    return { waits, action: "Nothing yet - firstmate reconciles this blocker and escalates if your input is needed." };
+    const roots = blockerIds.flatMap((id) => resolveBlocker(id, new Set(), 0));
+    return {
+      waits: roots.map((root) => root.wait),
+      action: [...new Set(roots.map((root) => root.action))].join(" "),
+    };
   };
 
   const queue = mainRecords.filter((record) => record.state === "queued");
@@ -749,8 +751,10 @@ function classify(snapshot, environment) {
       continue;
     }
     if (record.blocked_by || record.hold_reason) {
-      const reason = record.blocked_by ? `Blocked by ${itemRef("main", record.blocked_by)}` : "Structured hold";
-      const chain = describeBlockedRecord(record);
+      const reason = record.blocked_by
+        ? `Blocked by ${blockedByIds(record).map((id) => itemRef("main", id)).join(", ")}`
+        : "Structured hold";
+      const chain = describeBlockedRecord(record, "main", mainRecords, snapshot.tasks || []);
       blockedRows.push({ id: itemRef("main", record.id), owner: "main", reason });
       pipeline.blocked.push(Object.assign(cardFromBacklog(record, "main", "blocked", reason), {
         waits_on: chain.waits,
@@ -810,7 +814,7 @@ function classify(snapshot, environment) {
     if (!scopeAvailable) markUnavailable(opaqueRef("home", mate.id), "persistent secondmate", "registered routing scope unavailable");
     if (!runtime) markUnavailable(opaqueRef("home", mate.id), "persistent secondmate", "home-owned runtime lane evidence unavailable");
     for (const decision of mate.decisions_open || []) {
-      if ((decision.key || "default") === "default" && !decision.id) continue;
+      if (!decision.key || decision.key === "default") continue;
       decisions.push({
         owner: ownerRef(mate.id),
         task: itemRef(mate.id, decision.id || mate.id),
@@ -831,7 +835,11 @@ function classify(snapshot, environment) {
       }
       const ageDays = dateAgeDays(hold.since, now);
       blockedRows.push({ id: itemRef(mate.id, hold.id), owner: ownerRef(mate.id), reason: "structured wait gate" });
-      pipeline.blocked.push(cardFromBacklog(hold, mate.id, "blocked", "Structured wait gate"));
+      const chain = describeBlockedRecord(hold, mate.id, [...(mate.holds || []), ...(mate.queued || [])], mate.active_children || []);
+      pipeline.blocked.push(Object.assign(cardFromBacklog(hold, mate.id, "blocked", "Structured wait gate"), {
+        waits_on: chain.waits,
+        what_you_can_do: chain.action,
+      }));
       if (ageDays !== null && ageDays >= 7) {
         aging.push({ id: itemRef(mate.id, hold.id), owner: ownerRef(mate.id), age_days: ageDays, state: "held", evidence: "structured backlog age; structured wait gate" });
       }
@@ -870,21 +878,35 @@ function classify(snapshot, environment) {
       if (isSuperseded(record) || heldIds.has(record.id)) continue;
       secondmateQueuedConsidered += 1;
       if (record.kind === "captain" && record.hold_kind === "captain") {
+        const identity = backlogDecisionIdentity(record);
+        const ref = decisionRef(mate.id, identity.origin, identity.key);
         blockedRows.push({ id: itemRef(mate.id, record.id), owner: ownerRef(mate.id), reason: "captain hold" });
-        pipeline.blocked.push(cardFromBacklog(record, mate.id, "blocked", "Captain hold"));
+        pipeline.blocked.push(Object.assign(cardFromBacklog(record, mate.id, "blocked", "Captain hold"), {
+          waits_on: [`waiting on your decision ${ref}`],
+          what_you_can_do: `Answer decision ${ref} - it is the root cause.`,
+        }));
         continue;
       }
       if (record.blocked_by || record.hold_reason) {
-        const reason = record.blocked_by ? `Blocked by ${itemRef(mate.id, record.blocked_by)}` : "Structured hold";
+        const reason = record.blocked_by
+          ? `Blocked by ${blockedByIds(record).map((id) => itemRef(mate.id, id)).join(", ")}`
+          : "Structured hold";
+        const chain = describeBlockedRecord(record, mate.id, [...(mate.holds || []), ...(mate.queued || [])], mate.active_children || []);
         blockedRows.push({ id: itemRef(mate.id, record.id), owner: ownerRef(mate.id), reason });
-        pipeline.blocked.push(cardFromBacklog(record, mate.id, "blocked", reason));
+        pipeline.blocked.push(Object.assign(cardFromBacklog(record, mate.id, "blocked", reason), {
+          waits_on: chain.waits,
+          what_you_can_do: chain.action,
+        }));
         continue;
       }
       const timeGate = futureTimeGate(record, now);
       if (timeGate) {
         const reason = `time gate until ${timeGate}`;
         blockedRows.push({ id: itemRef(mate.id, record.id), owner: ownerRef(mate.id), reason });
-        pipeline.blocked.push(cardFromBacklog(record, mate.id, "blocked", reason));
+        pipeline.blocked.push(Object.assign(cardFromBacklog(record, mate.id, "blocked", reason), {
+          waits_on: [`waiting until ${timeGate}`],
+          what_you_can_do: `Nothing - this unblocks itself when the ${timeGate} time gate passes.`,
+        }));
         continue;
       }
       const gaps = definitionGaps(record, true);
@@ -1336,7 +1358,7 @@ function artifact(value) {
 // captain action (or explicit nothing-to-do), rendered under a blocked row.
 function blockedContext(card) {
   if (!card.waits_on || card.waits_on.length === 0) return "";
-  const chain = card.waits_on.map((wait) => h(wait)).join("; then ");
+  const chain = card.waits_on.map((wait) => h(wait)).join("; ");
   const action = card.what_you_can_do ? `<small class="cando">What you can do: ${h(card.what_you_can_do)}</small>` : "";
   return `<small class="chain">${chain}.</small>${action}`;
 }
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
index 4c9e886cdc6..91106d125c1 100755
--- a/bin/fm-dash-serve.mjs
+++ b/bin/fm-dash-serve.mjs
@@ -1166,9 +1166,9 @@ async function handle(req, res) {
     // stripped launchd environment). Say so loudly rather than presenting
     // degraded data as truth.
     const unknownStates = (dashboard.html.match(/Authoritative current state: unknown/g) || []).length;
-    const manifestRows = (dashboard.html.match(/class="mrow"/g) || []).length;
-    const degraded = unknownStates >= 3 && unknownStates * 2 >= manifestRows;
-    if (degraded) log(`degraded render detected: ${unknownStates} of ${manifestRows} manifest rows read unknown; check the service environment (PATH/tools)`);
+    const authoritativeStates = (dashboard.html.match(/Authoritative current state:/g) || []).length;
+    const degraded = unknownStates >= 3 && unknownStates * 2 >= authoritativeStates;
+    if (degraded) log(`degraded render detected: ${unknownStates} of ${authoritativeStates} authoritative worker states read unknown; check the service environment (PATH/tools)`);
     const layer = interactiveLayer(dispatchable, pendingRecords().length, dashboard.generated, config.readOnly, {
       refs: refsFile ? refDisplayMap(refsFile) : {},
       ideas: parseIdeas().map((idea) => ({ id: idea.id, title: idea.title })),
diff --git a/tests/fm-capacity.test.sh b/tests/fm-capacity.test.sh
index 61334251f9d..60b781adad9 100755
--- a/tests/fm-capacity.test.sh
+++ b/tests/fm-capacity.test.sh
@@ -547,20 +547,28 @@ test_secondmate_captain_holds_are_pipeline_waiting_work() {
     ]
     |
     .secondmate_current.records[0].decisions_open = [
+      {"id":"mate-question","key":"default","verb":"needs-decision","summary":"Sensitive question","source":"child-state"},
       {"id":"mate-choice","key":"mate-choice","verb":"captain-hold","summary":"Sensitive choice","source":"backlog"}
     ]
+    | .secondmate_current.records[0].holds = [
+      {"id":"mate-held","title":"Wait for external completion","repo":"delta","project_resolved":true,"kind":"ship","since":"2026-07-20","source":"child-state"}
+    ]
     | .secondmate_current.records[0].queued += [
-      {"id":"mate-choice","title":"Choose the secondmate rollout","repo":"delta","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"Sensitive reason"}
+      {"id":"mate-choice","title":"Choose the secondmate rollout","repo":"delta","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"Sensitive reason"},
+      {"id":"mate-structured","title":"Wait on a structured hold","repo":"delta","project_resolved":true,"kind":"ship","hold_reason":"Sensitive reason"},
+      {"id":"mate-time","title":"Resume after 2026-08-15","repo":"delta","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: resume safely."}
     ]
-    | .secondmate_current.records[0].counts = {"active_children":0,"decisions_open":1,"holds":0,"queued":2}
+    | .secondmate_current.records[0].counts = {"active_children":0,"decisions_open":2,"holds":1,"queued":4}
   ' "$snapshot" > "$snapshot.tmp"
   mv "$snapshot.tmp" "$snapshot"
   json=$("$CAPACITY" --json --snapshot "$snapshot" --environment "$environment" --output "$output") ||
     fail "secondmate captain-hold capacity run failed"
   printf '%s' "$json" | jq -e '
-    (.pipeline.blocked | length) == 5
+    (.pipeline.blocked | length) == 8
     and .measures.open_captain_actions == 4
     and (.recommendations[] | select(.id == "CAP-01") | .evidence | startswith("4 structured captain"))
+    and ([.pipeline.blocked[] | select(.owner | contains("persistent"))] | length) == 4
+    and ([.pipeline.blocked[] | select(.owner | contains("persistent")) | .what_you_can_do] | all(type == "string" and length > 0))
   ' >/dev/null || fail "secondmate captain hold was missing or double-counted: $json"
   [ "$(grep -o 'class="verb verb-decide"' "$output" | wc -l | tr -d ' ')" = 4 ] ||
     fail "captain decisions were collapsed or duplicated in the needs-you roll call"
@@ -923,7 +931,8 @@ test_keyless_questions_and_blocker_chains() {
       {"order":2,"state":"in_flight","structured":true,"id":"keyed-asker","title":"Build the API","repo":"beta","project_resolved":true,"kind":"ship","since":"2026-07-16","body_excerpt":"Acceptance criteria: API ships."},
       {"order":3,"state":"queued","structured":true,"id":"dependent","title":"Publish the dependent release","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"asker","blocked_reason":"needs exporter","body_excerpt":"Acceptance criteria: release ships."},
       {"order":4,"state":"queued","structured":true,"id":"policy-choice","title":"Choose the rollout policy","repo":"alpha","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"pick conservative or fast"},
-      {"order":5,"state":"queued","structured":true,"id":"after-policy","title":"Apply the rollout policy","repo":"delta","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: rollout applied."}
+      {"order":5,"state":"queued","structured":true,"id":"after-policy","title":"Apply the rollout policy","repo":"delta","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: rollout applied."},
+      {"order":6,"state":"queued","structured":true,"id":"multi-dependent","title":"Publish after two blockers","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"asker,missing-root","body_excerpt":"Acceptance criteria: both blockers clear."}
     ]
     | .tasks = [
       {"id":"asker","kind":"ship","project":"alpha","current_state":{"state":"blocked","source":"status-fold","detail":"awaiting reply"},"endpoint":{"exists":true,"agent_alive":"not_checked"},"hints":{"open_decisions":[{"key":"default","verb":"needs-decision","summary":"which port should the exporter bind"}]},"pr":{"url":null},"paths":{"report":{"present":false}},"backlog":{"id":"asker","title":"Build the exporter","repo":"alpha","project_resolved":true,"kind":"ship","since":"2026-07-16"}},
@@ -943,6 +952,8 @@ test_keyless_questions_and_blocker_chains() {
     and ([.pipeline.blocked[] | select(.waits_on != null) | .waits_on[0]] | any(contains("waiting on your decision")))
     and ([.pipeline.blocked[] | .what_you_can_do // ""] | any(contains("unblocks itself when")))
     and ([.pipeline.blocked[] | .waits_on // [] | join(" ")] | any(contains("blocked by") and contains("currently")))
+    and ([.pipeline.blocked[] | select((.waits_on // []) | length == 2)] | length) == 1
+    and ([.pipeline.blocked[] | select((.waits_on // []) | length == 2) | .waits_on | join(" ")] | .[0] | contains("unavailable"))
     and ([.pipeline.blocked[] | .waits_on // [] | join(" ")] | any(contains("which port")) | not)
   ' >/dev/null || fail "keyless questions or blocker chains are wrong: $json"
   html=$(cat "$output")
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index 918c7e73a86..a86423621ae 100755
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -829,7 +829,7 @@ EOF
 }
 
 test_launchd_env_and_degraded_render_selfcheck() {
-  local plist rows
+  local plist rows non_worker_rows
   stop_server
   start_server "$HOME_DIR" "$PORT"
   plist=$(FM_HOME="$HOME_DIR" "$INSTALL_SH" print-plist) || fail "print-plist failed"
@@ -837,10 +837,14 @@ test_launchd_env_and_degraded_render_selfcheck() {
   assert_contains "$plist" "$(dirname "$(command -v node)")" "plist PATH does not carry the node tool directory"
   cp "$HOME_DIR/data/capacity-dashboard.html" "$TMP_ROOT/dashboard.bak"
   rows=""
+  non_worker_rows=""
   for _ in 1 2 3 4; do
     rows="$rows<li class=\"mrow\"><span class=\"mreason\">Authoritative current state: unknown</span></li>"
   done
-  printf '%s' "$(sed "s|</body>|$rows</body>|" "$TMP_ROOT/dashboard.bak")" > "$HOME_DIR/data/capacity-dashboard.html"
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    non_worker_rows="$non_worker_rows<li class=\"mrow\"><span class=\"mreason\">Queued backlog item</span></li>"
+  done
+  printf '%s' "$(sed "s|</body>|$rows$non_worker_rows</body>|" "$TMP_ROOT/dashboard.bak")" > "$HOME_DIR/data/capacity-dashboard.html"
   req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
   assert_contains "$RESP" 'RENDER DEGRADED' "a mostly-unknown render is presented as truth instead of loudly degraded"
   cp "$TMP_ROOT/dashboard.bak" "$HOME_DIR/data/capacity-dashboard.html"

From 4d3cfd243ec33bad5fe767dc08be9030e6291a5c Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 14:24:17 -0400
Subject: [PATCH 20/24] no-mistakes(review): Preserve captain blocker roots and
 tiny-fleet degradation

---
 bin/fm-capacity.mjs                  | 12 ++++++-----
 bin/fm-dash-serve.mjs                |  2 +-
 bin/fm-fleet-snapshot.sh             | 30 +++++++++++++++++++++++-----
 tests/fm-capacity.test.sh            | 13 +++++++++++-
 tests/fm-dash.test.sh                |  6 ++++++
 tests/fm-fleet-snapshot-view.test.sh |  9 +++++----
 6 files changed, 56 insertions(+), 16 deletions(-)

diff --git a/bin/fm-capacity.mjs b/bin/fm-capacity.mjs
index fd4f227dcd0..5f9920f0b2a 100755
--- a/bin/fm-capacity.mjs
+++ b/bin/fm-capacity.mjs
@@ -673,13 +673,15 @@ function classify(snapshot, environment) {
     });
   }
 
-  const blockedByIds = (record) => String(record.blocked_by || "").split(",").map((id) => id.trim()).filter(Boolean);
+  const blockedByIds = (record) => (Array.isArray(record.blocked_by_all)
+    ? record.blocked_by_all
+    : String(record.blocked_by || "").split(",")).map((id) => String(id).trim()).filter(Boolean);
   const describeBlockedRecord = (startRecord, owner, records, tasks = []) => {
     const recordById = new Map(records.filter((record) => record.structured !== false).map((record) => [record.id, record]));
     const currentById = new Map(tasks.map((task) => [task.id, task.current_state?.state || task.state]));
-    const resolveBlocker = (blockerId, seen, depth) => {
+    const resolveBlocker = (blockerId, seen) => {
       const blockerRef = itemRef(owner, blockerId);
-      if (seen.has(blockerId) || depth >= 5) {
+      if (seen.has(blockerId)) {
         return [{ wait: `blocked by ${blockerRef}, whose blocker chain could not be resolved`, action: "Nothing yet - firstmate reconciles this blocker and escalates if your input is needed." }];
       }
       const blockerRecord = recordById.get(blockerId) || null;
@@ -702,7 +704,7 @@ function classify(snapshot, environment) {
       const nestedIds = blockerRecord ? blockedByIds(blockerRecord) : [];
       if (nestedIds.length > 0) {
         const nextSeen = new Set(seen).add(blockerId);
-        return nestedIds.flatMap((id) => resolveBlocker(id, nextSeen, depth + 1).map((root) => ({
+        return nestedIds.flatMap((id) => resolveBlocker(id, nextSeen).map((root) => ({
           wait: `${prefix}; then ${root.wait}`,
           action: root.action,
         })));
@@ -718,7 +720,7 @@ function classify(snapshot, environment) {
       if (gate) return { waits: [`waiting until ${gate}`], action: `Nothing - this unblocks itself when the ${gate} time gate passes.` };
       return { waits: ["held by a structured wait gate"], action: "Nothing yet - firstmate watches this hold and escalates if your input is needed." };
     }
-    const roots = blockerIds.flatMap((id) => resolveBlocker(id, new Set(), 0));
+    const roots = blockerIds.flatMap((id) => resolveBlocker(id, new Set()));
     return {
       waits: roots.map((root) => root.wait),
       action: [...new Set(roots.map((root) => root.action))].join(" "),
diff --git a/bin/fm-dash-serve.mjs b/bin/fm-dash-serve.mjs
index 91106d125c1..d3a8b7a9ff6 100755
--- a/bin/fm-dash-serve.mjs
+++ b/bin/fm-dash-serve.mjs
@@ -1167,7 +1167,7 @@ async function handle(req, res) {
     // degraded data as truth.
     const unknownStates = (dashboard.html.match(/Authoritative current state: unknown/g) || []).length;
     const authoritativeStates = (dashboard.html.match(/Authoritative current state:/g) || []).length;
-    const degraded = unknownStates >= 3 && unknownStates * 2 >= authoritativeStates;
+    const degraded = authoritativeStates > 0 && unknownStates * 2 >= authoritativeStates;
     if (degraded) log(`degraded render detected: ${unknownStates} of ${authoritativeStates} authoritative worker states read unknown; check the service environment (PATH/tools)`);
     const layer = interactiveLayer(dispatchable, pendingRecords().length, dashboard.generated, config.readOnly, {
       refs: refsFile ? refDisplayMap(refsFile) : {},
diff --git a/bin/fm-fleet-snapshot.sh b/bin/fm-fleet-snapshot.sh
index d21ad1279d6..432ef5f53b0 100755
--- a/bin/fm-fleet-snapshot.sh
+++ b/bin/fm-fleet-snapshot.sh
@@ -18,6 +18,8 @@
 #     Structured records with a repo include its resolved delivery_mode and
 #     project_resolved provenance from data/projects.md; unresolved projects
 #     retain the fail-safe no-mistakes mode while project_resolved stays false.
+#     blocked_by is the comma-compatible dependency string and blocked_by_all
+#     preserves every normalized dependency edge in source order.
 #     Structured rows preserve captain-hold metadata such as hold_kind and
 #     hold_reason when tasks-axi emits it.
 #   tasks[]: one row per state/<id>.meta, sorted by id.
@@ -294,6 +296,13 @@ backlog_json() {  # [<backlog-path>] - defaults to this home's $BACKLOG
       | if $reason == null then null
         else ($reason | clean_title | if . == "" then null else . end)
         end;
+    def blocked_by_all($rest):
+      [$rest
+       | scan("blocked-by:[[:space:]]*[^[:space:])]+")
+       | sub("^blocked-by:[[:space:]]*"; "")
+       | split(",")[]
+       | trim
+       | select(length > 0)];
     def local_note($rest):
       cap(($rest | strip_trailing_metadata); ".*(?:^|[[:space:]]+-[[:space:]]+|[[:space:]])(?<v>local main)$");
     def completion($rest):
@@ -317,6 +326,7 @@ backlog_json() {  # [<backlog-path>] - defaults to this home's $BACKLOG
           {order:$order,state:$section,structured:false,id:null,raw:$line,body_lines:[],body_excerpt:null}
         else
           ($m.rest) as $rest
+          | (blocked_by_all($rest)) as $blocked_by_all
           | {order:$order,
              state:$section,
              structured:true,
@@ -328,7 +338,8 @@ backlog_json() {  # [<backlog-path>] - defaults to this home's $BACKLOG
              priority:metadata($rest; "priority"),
              hold_reason:metadata($rest; "hold"),
              hold_kind:metadata($rest; "hold-kind"),
-             blocked_by:cap($rest; ".*blocked-by:[[:space:]]*(?<v>[^[:space:])]+).*"),
+             blocked_by:($blocked_by_all | if length == 0 then null else join(",") end),
+             blocked_by_all:$blocked_by_all,
              blocked_reason:blocked_reason($rest),
              since:metadata_word($rest; "since"),
              merged:metadata_word($rest; "merged"),
@@ -617,7 +628,9 @@ secondmate_home_summary_json() {  # <backlog-json> <tasks-json>
             repo:((.repo // null) | if . == null then null else trunc(120) end),
             kind:((.kind // null) | if . == null then null else trunc(40) end),
             since:((.since // null) | if . == null then null else trunc(20) end),
-            blocked_by:(.blocked_by | trunc(120)),reason:((.blocked_reason // "blocked") | trunc(120)),source:"backlog"} ]
+            blocked_by:(.blocked_by | trunc(120)),
+            blocked_by_all:((.blocked_by_all // []) | map(trunc(120))),
+            reason:((.blocked_reason // "blocked") | trunc(120)),source:"backlog"} ]
        + [ $owned_in_flight[] as $work
            | $tasks[]
            | select(.id == $work.id and (.current_state.state == "parked" or .current_state.state == "paused" or .current_state.state == "blocked"))
@@ -627,7 +640,7 @@ secondmate_home_summary_json() {  # <backlog-json> <tasks-json>
               delivery_mode:(($work.delivery_mode // null) | if . == null then null else trunc(40) end),
               project_resolved:($work.project_resolved == true),
               since:(($work.since // null) | if . == null then null else trunc(20) end),
-              blocked_by:null,
+              blocked_by:null,blocked_by_all:[],
               reason:((.current_state.detail // .current_state.state) | trunc(120)),source:"child-state"} ]) as $holds_all
     | ($backlog.present == true
        and ($unstructured_current | length) == 0
@@ -663,6 +676,7 @@ secondmate_home_summary_json() {  # <backlog-json> <tasks-json>
         holds:$holds_all[:$queued_n],
         queued:([$queued_all[] | {id:(.id | trunc(120)),title:(.title | trunc(120)),
           blocked_by:((.blocked_by // null) | if . == null then null else trunc(120) end),
+          blocked_by_all:((.blocked_by_all // []) | map(trunc(120))),
           blocked_reason:((.blocked_reason // null) | if . == null then null else trunc(160) end),
           hold_reason:((.hold_reason // null) | if . == null then null else trunc(160) end),
           hold_kind:((.hold_kind // null) | if . == null then null else trunc(40) end),
@@ -995,7 +1009,10 @@ parent_evidence_reconciliation_json() {  # <summary-json> <activities-json> <dec
                "active_children")
          elif $e.verb == "paused" then
            ([ $summary.holds[]
-              | select(if ($e.key | keyed) then .id == $e.key or .blocked_by == $e.key else true end)
+              | select(if ($e.key | keyed)
+                       then .id == $e.key
+                            or (((.blocked_by_all // ((.blocked_by // "") | split(","))) | index($e.key)) != null)
+                       else true end)
               | {surface:"holds",id,key:(.blocked_by // null),verb:"paused"}]) as $matches
            | result($e; $matches;
                $summary.counts.holds == ($summary.holds | length);
@@ -1018,7 +1035,10 @@ parent_evidence_reconciliation_json() {  # <summary-json> <activities-json> <dec
                 | select(if ($e.key | keyed) then .key == $e.key or .id == $e.key else true end)
                 | {surface:"decisions_open",id,key,verb}]
               + [ $summary.holds[]
-                  | select(if ($e.key | keyed) then .id == $e.key or .blocked_by == $e.key else true end)
+                  | select(if ($e.key | keyed)
+                           then .id == $e.key
+                                or (((.blocked_by_all // ((.blocked_by // "") | split(","))) | index($e.key)) != null)
+                           else true end)
                   | {surface:"holds",id,key:(.blocked_by // null),verb:"blocked"}]) as $matches
              | result($e; $matches;
                  ($summary.counts.decisions_open == ($summary.decisions_open | length)
diff --git a/tests/fm-capacity.test.sh b/tests/fm-capacity.test.sh
index 60b781adad9..8c3c29a05b4 100755
--- a/tests/fm-capacity.test.sh
+++ b/tests/fm-capacity.test.sh
@@ -932,7 +932,14 @@ test_keyless_questions_and_blocker_chains() {
       {"order":3,"state":"queued","structured":true,"id":"dependent","title":"Publish the dependent release","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"asker","blocked_reason":"needs exporter","body_excerpt":"Acceptance criteria: release ships."},
       {"order":4,"state":"queued","structured":true,"id":"policy-choice","title":"Choose the rollout policy","repo":"alpha","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"pick conservative or fast"},
       {"order":5,"state":"queued","structured":true,"id":"after-policy","title":"Apply the rollout policy","repo":"delta","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: rollout applied."},
-      {"order":6,"state":"queued","structured":true,"id":"multi-dependent","title":"Publish after two blockers","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"asker,missing-root","body_excerpt":"Acceptance criteria: both blockers clear."}
+      {"order":6,"state":"queued","structured":true,"id":"multi-dependent","title":"Publish after two blockers","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"missing-root","blocked_by_all":["asker","missing-root"],"body_excerpt":"Acceptance criteria: both blockers clear."},
+      {"order":7,"state":"queued","structured":true,"id":"deep-dependent","title":"Publish after a deep chain","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"deep-1","body_excerpt":"Acceptance criteria: the full chain clears."},
+      {"order":8,"state":"queued","structured":true,"id":"deep-1","title":"Deep dependency one","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"deep-2","body_excerpt":"Acceptance criteria: continue."},
+      {"order":9,"state":"queued","structured":true,"id":"deep-2","title":"Deep dependency two","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"deep-3","body_excerpt":"Acceptance criteria: continue."},
+      {"order":10,"state":"queued","structured":true,"id":"deep-3","title":"Deep dependency three","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"deep-4","body_excerpt":"Acceptance criteria: continue."},
+      {"order":11,"state":"queued","structured":true,"id":"deep-4","title":"Deep dependency four","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"deep-5","body_excerpt":"Acceptance criteria: continue."},
+      {"order":12,"state":"queued","structured":true,"id":"deep-5","title":"Deep dependency five","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"deep-6","body_excerpt":"Acceptance criteria: continue."},
+      {"order":13,"state":"queued","structured":true,"id":"deep-6","title":"Deep dependency six","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: choose policy."}
     ]
     | .tasks = [
       {"id":"asker","kind":"ship","project":"alpha","current_state":{"state":"blocked","source":"status-fold","detail":"awaiting reply"},"endpoint":{"exists":true,"agent_alive":"not_checked"},"hints":{"open_decisions":[{"key":"default","verb":"needs-decision","summary":"which port should the exporter bind"}]},"pr":{"url":null},"paths":{"report":{"present":false}},"backlog":{"id":"asker","title":"Build the exporter","repo":"alpha","project_resolved":true,"kind":"ship","since":"2026-07-16"}},
@@ -954,6 +961,10 @@ test_keyless_questions_and_blocker_chains() {
     and ([.pipeline.blocked[] | .waits_on // [] | join(" ")] | any(contains("blocked by") and contains("currently")))
     and ([.pipeline.blocked[] | select((.waits_on // []) | length == 2)] | length) == 1
     and ([.pipeline.blocked[] | select((.waits_on // []) | length == 2) | .waits_on | join(" ")] | .[0] | contains("unavailable"))
+    and any(.pipeline.blocked[];
+      ((.waits_on // [] | join(" ")) as $chain
+       | ([$chain | scan("blocked by")] | length) >= 6
+         and ($chain | contains("waiting on your decision"))))
     and ([.pipeline.blocked[] | .waits_on // [] | join(" ")] | any(contains("which port")) | not)
   ' >/dev/null || fail "keyless questions or blocker chains are wrong: $json"
   html=$(cat "$output")
diff --git a/tests/fm-dash.test.sh b/tests/fm-dash.test.sh
index a86423621ae..6a88b137ce2 100755
--- a/tests/fm-dash.test.sh
+++ b/tests/fm-dash.test.sh
@@ -847,6 +847,12 @@ test_launchd_env_and_degraded_render_selfcheck() {
   printf '%s' "$(sed "s|</body>|$rows$non_worker_rows</body>|" "$TMP_ROOT/dashboard.bak")" > "$HOME_DIR/data/capacity-dashboard.html"
   req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
   assert_contains "$RESP" 'RENDER DEGRADED' "a mostly-unknown render is presented as truth instead of loudly degraded"
+  printf '%s' "$(sed "s|</body>|<li class=\"mrow\"><span class=\"mreason\">Authoritative current state: unknown</span></li>$non_worker_rows</body>|" "$TMP_ROOT/dashboard.bak")" > "$HOME_DIR/data/capacity-dashboard.html"
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  assert_contains "$RESP" 'RENDER DEGRADED' "a one-worker all-unknown fleet is presented as healthy"
+  sed 's/Authoritative current state:/Observed worker state:/g' "$TMP_ROOT/dashboard.bak" > "$HOME_DIR/data/capacity-dashboard.html"
+  req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
+  case "$RESP" in *'"degraded":true'*) fail "an empty authoritative worker set is marked degraded" ;; esac
   cp "$TMP_ROOT/dashboard.bak" "$HOME_DIR/data/capacity-dashboard.html"
   req GET "http://127.0.0.1:$PORT/" "$CAPTAIN"
   case "$RESP" in *'"degraded":true'*) fail "a healthy render is marked degraded" ;; esac
diff --git a/tests/fm-fleet-snapshot-view.test.sh b/tests/fm-fleet-snapshot-view.test.sh
index 80c95113516..be91e85b16e 100755
--- a/tests/fm-fleet-snapshot-view.test.sh
+++ b/tests/fm-fleet-snapshot-view.test.sh
@@ -264,7 +264,7 @@ test_backlog_tasks_axi_forms_and_overrides() {
 ## Queued
 - [ ] queued-comma - Queued Comma Task (repo: beta, since 2026-07-08) (kind: ship)
 - [ ] parenthetical-title - Refresh sidebar (mobile) (repo: beta) (kind: ship)
-- [ ] blocked-reason - Blocked Reason (repo: beta) (kind: ship) blocked-by: queued-comma - waits on queued-comma
+- [ ] blocked-reason - Blocked Reason (repo: beta) (kind: ship) blocked-by: queued-comma blocked-by: missing-edge - waits on both blockers
 - [ ] sample-decision-route - Choose sample route (repo: sample) (kind: captain) (since 2026-07-14) (hold: captain route choice pending) (hold-kind: captain)
 
 ## Done
@@ -313,8 +313,9 @@ EOF
     .backlog.records[] | select(.id == "blocked-reason")
     | .title == "Blocked Reason"
       and .repo == "beta"
-      and .blocked_by == "queued-comma"
-      and .blocked_reason == "waits on queued-comma"
+      and .blocked_by == "queued-comma,missing-edge"
+      and .blocked_by_all == ["queued-comma","missing-edge"]
+      and .blocked_reason == "waits on both blockers"
   ' >/dev/null || fail "blocked suffix did not parse into title and reason"
   printf '%s' "$out" | jq -e '
     .backlog.records[] | select(.id == "sample-decision-route")
@@ -362,7 +363,7 @@ EOF
   view=$(PATH="$fakebin:$PATH" FM_HOME="$home" FM_DATA_OVERRIDE="$data" FM_PROJECTS_OVERRIDE="$projects" "$VIEW")
   assert_contains "$view" "| bold-task | done / status-log | scout | alpha | tmux | present | $data/bold-task/report.md" \
     "view should render bold in-flight row from snapshot"
-  assert_contains "$view" "| blocked-reason | Blocked Reason | beta | ship | queued-comma - waits on queued-comma | - |" \
+  assert_contains "$view" "| blocked-reason | Blocked Reason | beta | ship | queued-comma,missing-edge - waits on both blockers | - |" \
     "view should render blocked reason without title metadata"
   assert_contains "$view" "| done-bracket-pr | Done Bracket PR | gamma | ship | - | https://github.com/kunchenguid/firstmate/pull/43 |" \
     "view should render bracketed PR artifact outside the title"

From 4da546191bfd1ef1978dbcd61f9e2086e9197f6f Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 14:33:06 -0400
Subject: [PATCH 21/24] no-mistakes(review): Resolve captain blocker roots with
 bounded traversal

---
 bin/fm-capacity.mjs       | 184 +++++++++++++++++++++++++++++---------
 tests/fm-capacity.test.sh |  19 +++-
 2 files changed, 159 insertions(+), 44 deletions(-)

diff --git a/bin/fm-capacity.mjs b/bin/fm-capacity.mjs
index 5f9920f0b2a..b719743d82a 100755
--- a/bin/fm-capacity.mjs
+++ b/bin/fm-capacity.mjs
@@ -586,6 +586,53 @@ function classify(snapshot, environment) {
   if (registry?.available === false || registry?.complete === false) {
     markUnavailable("secondmate-registry", "main", "registry projection incomplete");
   }
+  const taskRootContext = (task, owner, dependency = false) => {
+    const open = task.hints?.open_decisions || [];
+    const state = safeState(task.current_state?.state || task.state);
+    const chatQuestion = open.some((decision) => !decision.key || decision.key === "default");
+    const keyedDecision = open.find((decision) => decision.key && decision.key !== "default");
+    if (dependency && ["done", "failed"].includes(state)) {
+      return {
+        kind: "stale",
+        wait: `it is already ${state}; the dependency edge is stale`,
+        action: "Nothing yet - firstmate reconciles this stale dependency",
+      };
+    }
+    if (chatQuestion) {
+      return {
+        kind: "chat",
+        wait: "a worker question is being handled in chat",
+        action: "Nothing - firstmate is handling the worker's question in chat.",
+      };
+    }
+    if (keyedDecision) {
+      const ref = decisionRef(owner, keyedDecision.origin || task.id, keyedDecision.key);
+      return {
+        kind: "decision",
+        wait: `waiting on your decision ${ref}`,
+        action: `Answer decision ${ref} - it is the root cause.`,
+      };
+    }
+    if (state === "paused") {
+      return {
+        kind: "paused",
+        wait: "waiting on a declared external delay expected to clear on its own",
+        action: "Nothing - this unblocks itself when the external wait clears.",
+      };
+    }
+    if (state === "unknown") {
+      return {
+        kind: "unknown",
+        wait: "its current state could not be read",
+        action: "Nothing yet - firstmate reconciles the unavailable state and escalates if your input is needed.",
+      };
+    }
+    return {
+      kind: "worker",
+      wait: `the worker reports state: ${state}`,
+      action: "Nothing yet - firstmate is on it and will escalate if your input is needed.",
+    };
+  };
   for (const record of mainRecords.filter((item) => item.state === "in_flight" && item.structured)) {
     const task = taskById.get(record.id);
     const repo = record.repo || task?.project || null;
@@ -629,28 +676,12 @@ function classify(snapshot, environment) {
       aging.push({ id: itemRef("main", task.id), owner: "main", age_days: ageDays, state: safeState(task.current_state?.state), evidence: `structured backlog age; current source ${safeSource(task.current_state?.source)}` });
     }
     const approvalReady = taskApprovalReady(task);
-    const keyedOpen = open.filter((decision) => decision.key && decision.key !== "default");
     let taskWaits = null;
     let taskCanDo = null;
     if (stage === "blocked") {
-      const state = safeState(task.current_state?.state);
-      if (chatQuestionCount > 0) {
-        taskWaits = ["a worker question is being handled in chat"];
-        taskCanDo = "Nothing - firstmate is handling the worker's question in chat.";
-      } else if (keyedOpen.length > 0) {
-        const ref = decisionRef("main", task.id, keyedOpen[0].key);
-        taskWaits = [`waiting on your decision ${ref}`];
-        taskCanDo = `Answer decision ${ref} - it is the root cause.`;
-      } else if (state === "paused") {
-        taskWaits = ["waiting on a declared external delay expected to clear on its own"];
-        taskCanDo = "Nothing - this unblocks itself when the external wait clears.";
-      } else if (state === "unknown") {
-        taskWaits = ["its current state could not be read"];
-        taskCanDo = "Nothing yet - firstmate reconciles the unavailable state and escalates if your input is needed.";
-      } else {
-        taskWaits = [`the worker reports state: ${state}`];
-        taskCanDo = "Nothing yet - firstmate is on it and will escalate if your input is needed.";
-      }
+      const context = taskRootContext(task, "main");
+      taskWaits = [context.wait];
+      taskCanDo = context.action;
     }
     pipeline[stage].push({
       id: itemRef("main", task.id),
@@ -678,52 +709,114 @@ function classify(snapshot, environment) {
     : String(record.blocked_by || "").split(",")).map((id) => String(id).trim()).filter(Boolean);
   const describeBlockedRecord = (startRecord, owner, records, tasks = []) => {
     const recordById = new Map(records.filter((record) => record.structured !== false).map((record) => [record.id, record]));
-    const currentById = new Map(tasks.map((task) => [task.id, task.current_state?.state || task.state]));
-    const resolveBlocker = (blockerId, seen) => {
-      const blockerRef = itemRef(owner, blockerId);
-      if (seen.has(blockerId)) {
-        return [{ wait: `blocked by ${blockerRef}, whose blocker chain could not be resolved`, action: "Nothing yet - firstmate reconciles this blocker and escalates if your input is needed." }];
+    const blockerTaskById = new Map(tasks.map((task) => [task.id, task]));
+    const roots = new Map();
+    const parentById = new Map();
+    const segmentById = new Map();
+    const scheduled = new Set();
+    const stack = [];
+    const chainFor = (blockerId, suffix = null) => {
+      const segments = [];
+      let current = blockerId;
+      while (current !== null) {
+        if (segmentById.has(current)) segments.push(segmentById.get(current));
+        current = parentById.get(current) ?? null;
+      }
+      segments.reverse();
+      if (suffix) segments.push(suffix);
+      return segments.join("; then ");
+    };
+    const addRoot = (key, blockerId, suffix, action) => {
+      if (!roots.has(key)) roots.set(key, { wait: chainFor(blockerId, suffix), action });
+    };
+    const isAncestor = (blockerId, candidate) => {
+      let current = blockerId;
+      while (current !== null) {
+        if (current === candidate) return true;
+        current = parentById.get(current) ?? null;
       }
+      return false;
+    };
+    const schedule = (blockerId, parent) => {
+      if (scheduled.has(blockerId)) return;
+      scheduled.add(blockerId);
+      parentById.set(blockerId, parent);
+      stack.push(blockerId);
+    };
+    for (const blockerId of [...blockedByIds(startRecord)].reverse()) schedule(blockerId, null);
+    while (stack.length > 0) {
+      const blockerId = stack.pop();
+      const blockerRef = itemRef(owner, blockerId);
       const blockerRecord = recordById.get(blockerId) || null;
-      const currentState = currentById.get(blockerId);
-      if (!blockerRecord && !currentState) {
-        return [{ wait: `blocked by ${blockerRef}, whose current state is unavailable`, action: "Nothing yet - firstmate reconciles that unavailable blocker and escalates if your input is needed." }];
+      const blockerTask = blockerTaskById.get(blockerId) || null;
+      const currentState = blockerTask ? safeState(blockerTask.current_state?.state || blockerTask.state) : null;
+      if (!blockerRecord && !blockerTask) {
+        segmentById.set(blockerId, `blocked by ${blockerRef}, whose current state is unavailable`);
+        addRoot(`missing:${blockerId}`, blockerId, null, "Nothing yet - firstmate reconciles that unavailable blocker and escalates if your input is needed.");
+        continue;
+      }
+      const terminalState = ["done", "failed"].includes(currentState)
+        ? currentState
+        : (["done", "failed"].includes(blockerRecord?.state) ? blockerRecord.state : null);
+      if (terminalState) {
+        segmentById.set(blockerId, `blocked by ${blockerRef}, but it is already ${terminalState}; the dependency edge is stale`);
+        addRoot(`stale:${blockerId}`, blockerId, null, "Nothing yet - firstmate reconciles this stale dependency");
+        continue;
       }
       const prefix = currentState
         ? `blocked by ${blockerRef}, which is currently ${safeState(currentState)}`
         : `blocked by ${blockerRef}, which is ${blockerRecord.state === "in_flight" ? "under way" : "queued and not started"}`;
+      segmentById.set(blockerId, prefix);
+      const taskContext = blockerTask ? taskRootContext(blockerTask, owner, true) : null;
+      if (taskContext && ["chat", "decision", "paused", "unknown"].includes(taskContext.kind)) {
+        const rootKey = taskContext.kind === "decision"
+          ? `decision:${taskContext.wait}`
+          : `${taskContext.kind}:${blockerId}`;
+        addRoot(rootKey, blockerId, taskContext.wait, taskContext.action);
+        continue;
+      }
       if (blockerRecord?.kind === "captain" && blockerRecord.hold_kind === "captain") {
         const identity = backlogDecisionIdentity(blockerRecord);
         const ref = decisionRef(owner, identity.origin, identity.key);
-        return [{ wait: `${prefix}; then waiting on your decision ${ref}`, action: `Answer decision ${ref} - it is the root cause.` }];
+        addRoot(`decision:${ref}`, blockerId, `waiting on your decision ${ref}`, `Answer decision ${ref} - it is the root cause.`);
+        continue;
       }
       const gate = blockerRecord && futureTimeGate(blockerRecord, now);
       if (gate) {
-        return [{ wait: `${prefix}; then waiting until ${gate}`, action: `Nothing - this unblocks itself when the ${gate} time gate passes.` }];
+        addRoot(`gate:${blockerId}`, blockerId, `waiting until ${gate}`, `Nothing - this unblocks itself when the ${gate} time gate passes.`);
+        continue;
       }
       const nestedIds = blockerRecord ? blockedByIds(blockerRecord) : [];
       if (nestedIds.length > 0) {
-        const nextSeen = new Set(seen).add(blockerId);
-        return nestedIds.flatMap((id) => resolveBlocker(id, nextSeen).map((root) => ({
-          wait: `${prefix}; then ${root.wait}`,
-          action: root.action,
-        })));
+        for (const nestedId of [...nestedIds].reverse()) {
+          if (isAncestor(blockerId, nestedId)) {
+            addRoot(`cycle:${[blockerId, nestedId].sort().join(":")}`, blockerId, `blocked by ${itemRef(owner, nestedId)}, whose blocker chain contains a cycle`, "Nothing yet - firstmate reconciles this blocker and escalates if your input is needed.");
+          } else {
+            schedule(nestedId, blockerId);
+          }
+        }
+        continue;
       }
       if (blockerRecord?.hold_reason) {
-        return [{ wait: `${prefix}; then held by a structured hold`, action: "Nothing yet - firstmate watches this hold and escalates if your input is needed." }];
+        addRoot(`hold:${blockerId}`, blockerId, "held by a structured hold", "Nothing yet - firstmate watches this hold and escalates if your input is needed.");
+        continue;
       }
-      return [{ wait: prefix, action: `Nothing - this unblocks itself when ${blockerRef} finishes.` }];
-    };
+      if (taskContext?.kind === "worker" && currentState === "blocked") {
+        addRoot(`worker:${blockerId}`, blockerId, taskContext.wait, taskContext.action);
+        continue;
+      }
+      addRoot(`finish:${blockerId}`, blockerId, null, `Nothing - this unblocks itself when ${blockerRef} finishes.`);
+    }
     const blockerIds = blockedByIds(startRecord);
     if (blockerIds.length === 0) {
       const gate = futureTimeGate(startRecord, now);
       if (gate) return { waits: [`waiting until ${gate}`], action: `Nothing - this unblocks itself when the ${gate} time gate passes.` };
       return { waits: ["held by a structured wait gate"], action: "Nothing yet - firstmate watches this hold and escalates if your input is needed." };
     }
-    const roots = blockerIds.flatMap((id) => resolveBlocker(id, new Set()));
+    const resolvedRoots = [...roots.values()];
     return {
-      waits: roots.map((root) => root.wait),
-      action: [...new Set(roots.map((root) => root.action))].join(" "),
+      waits: resolvedRoots.map((root) => root.wait),
+      action: [...new Set(resolvedRoots.map((root) => root.action))].join(" "),
     };
   };
 
@@ -824,6 +917,13 @@ function classify(snapshot, environment) {
         reason: "Open decision raised by work already under way.",
       });
     }
+    const mateTaskEvidence = (mate.active_children || []).map((child) => ({
+      ...child,
+      hints: {
+        ...(child.hints || {}),
+        open_decisions: (mate.decisions_open || []).filter((decision) => decision.id === child.id),
+      },
+    }));
     const heldIds = new Set();
     for (const hold of mate.holds || []) {
       heldIds.add(hold.id);
@@ -837,7 +937,7 @@ function classify(snapshot, environment) {
       }
       const ageDays = dateAgeDays(hold.since, now);
       blockedRows.push({ id: itemRef(mate.id, hold.id), owner: ownerRef(mate.id), reason: "structured wait gate" });
-      const chain = describeBlockedRecord(hold, mate.id, [...(mate.holds || []), ...(mate.queued || [])], mate.active_children || []);
+      const chain = describeBlockedRecord(hold, mate.id, [...(mate.holds || []), ...(mate.queued || [])], mateTaskEvidence);
       pipeline.blocked.push(Object.assign(cardFromBacklog(hold, mate.id, "blocked", "Structured wait gate"), {
         waits_on: chain.waits,
         what_you_can_do: chain.action,
@@ -893,7 +993,7 @@ function classify(snapshot, environment) {
         const reason = record.blocked_by
           ? `Blocked by ${blockedByIds(record).map((id) => itemRef(mate.id, id)).join(", ")}`
           : "Structured hold";
-        const chain = describeBlockedRecord(record, mate.id, [...(mate.holds || []), ...(mate.queued || [])], mate.active_children || []);
+        const chain = describeBlockedRecord(record, mate.id, [...(mate.holds || []), ...(mate.queued || [])], mateTaskEvidence);
         blockedRows.push({ id: itemRef(mate.id, record.id), owner: ownerRef(mate.id), reason });
         pipeline.blocked.push(Object.assign(cardFromBacklog(record, mate.id, "blocked", reason), {
           waits_on: chain.waits,
diff --git a/tests/fm-capacity.test.sh b/tests/fm-capacity.test.sh
index 8c3c29a05b4..6627e40acb1 100755
--- a/tests/fm-capacity.test.sh
+++ b/tests/fm-capacity.test.sh
@@ -939,7 +939,13 @@ test_keyless_questions_and_blocker_chains() {
       {"order":10,"state":"queued","structured":true,"id":"deep-3","title":"Deep dependency three","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"deep-4","body_excerpt":"Acceptance criteria: continue."},
       {"order":11,"state":"queued","structured":true,"id":"deep-4","title":"Deep dependency four","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"deep-5","body_excerpt":"Acceptance criteria: continue."},
       {"order":12,"state":"queued","structured":true,"id":"deep-5","title":"Deep dependency five","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"deep-6","body_excerpt":"Acceptance criteria: continue."},
-      {"order":13,"state":"queued","structured":true,"id":"deep-6","title":"Deep dependency six","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: choose policy."}
+      {"order":13,"state":"queued","structured":true,"id":"deep-6","title":"Deep dependency six","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: choose policy."},
+      {"order":14,"state":"queued","structured":true,"id":"behind-keyed-worker","title":"Publish after the API decision","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"keyed-asker","body_excerpt":"Acceptance criteria: the API decision clears."},
+      {"order":15,"state":"done","structured":true,"id":"finished-root","title":"Already finished dependency","repo":"gamma","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: finished."},
+      {"order":16,"state":"queued","structured":true,"id":"stale-dependent","title":"Reconcile a stale dependency","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"finished-root","body_excerpt":"Acceptance criteria: stale edge clears."},
+      {"order":17,"state":"queued","structured":true,"id":"branching-dependent","title":"Publish after converging branches","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"branch-a,branch-b","blocked_by_all":["branch-a","branch-b"],"body_excerpt":"Acceptance criteria: both branches clear."},
+      {"order":18,"state":"queued","structured":true,"id":"branch-a","title":"First decision branch","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: choose policy."},
+      {"order":19,"state":"queued","structured":true,"id":"branch-b","title":"Second decision branch","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: choose policy."}
     ]
     | .tasks = [
       {"id":"asker","kind":"ship","project":"alpha","current_state":{"state":"blocked","source":"status-fold","detail":"awaiting reply"},"endpoint":{"exists":true,"agent_alive":"not_checked"},"hints":{"open_decisions":[{"key":"default","verb":"needs-decision","summary":"which port should the exporter bind"}]},"pr":{"url":null},"paths":{"report":{"present":false}},"backlog":{"id":"asker","title":"Build the exporter","repo":"alpha","project_resolved":true,"kind":"ship","since":"2026-07-16"}},
@@ -957,7 +963,6 @@ test_keyless_questions_and_blocker_chains() {
     (.pipeline.blocked | map(select(.reason | contains("Worker question being handled in chat"))) | length) == 1
     and (.pipeline.blocked | map(select(.reason | contains("Worker question"))) | .[0].what_you_can_do | contains("firstmate is handling"))
     and ([.pipeline.blocked[] | select(.waits_on != null) | .waits_on[0]] | any(contains("waiting on your decision")))
-    and ([.pipeline.blocked[] | .what_you_can_do // ""] | any(contains("unblocks itself when")))
     and ([.pipeline.blocked[] | .waits_on // [] | join(" ")] | any(contains("blocked by") and contains("currently")))
     and ([.pipeline.blocked[] | select((.waits_on // []) | length == 2)] | length) == 1
     and ([.pipeline.blocked[] | select((.waits_on // []) | length == 2) | .waits_on | join(" ")] | .[0] | contains("unavailable"))
@@ -965,6 +970,16 @@ test_keyless_questions_and_blocker_chains() {
       ((.waits_on // [] | join(" ")) as $chain
        | ([$chain | scan("blocked by")] | length) >= 6
          and ($chain | contains("waiting on your decision"))))
+    and any(.pipeline.blocked[];
+      ((.waits_on // [] | join(" ")) | contains("currently blocked")
+       and contains("waiting on your decision")))
+    and any(.pipeline.blocked[];
+      ((.waits_on // [] | join(" ")) | contains("dependency edge is stale"))
+      and .what_you_can_do == "Nothing yet - firstmate reconciles this stale dependency")
+    and any(.pipeline.blocked[];
+      (.reason | contains(","))
+      and ((.waits_on // []) | length) == 1
+      and ((.waits_on | join(" ")) | contains("waiting on your decision")))
     and ([.pipeline.blocked[] | .waits_on // [] | join(" ")] | any(contains("which port")) | not)
   ' >/dev/null || fail "keyless questions or blocker chains are wrong: $json"
   html=$(cat "$output")

From d5604adca664c02dd321550a794eba3cb85f4045 Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 14:41:49 -0400
Subject: [PATCH 22/24] no-mistakes(review): Complete captain blocker roots
 across cycles and holds

---
 bin/fm-capacity.mjs                | 160 +++++++++++++++--------------
 bin/fm-fleet-snapshot.sh           |   1 +
 tests/fm-bearings-snapshot.test.sh |   2 +-
 tests/fm-capacity.test.sh          |  39 +++++--
 4 files changed, 113 insertions(+), 89 deletions(-)

diff --git a/bin/fm-capacity.mjs b/bin/fm-capacity.mjs
index b719743d82a..245bb6dc7b4 100755
--- a/bin/fm-capacity.mjs
+++ b/bin/fm-capacity.mjs
@@ -586,52 +586,60 @@ function classify(snapshot, environment) {
   if (registry?.available === false || registry?.complete === false) {
     markUnavailable("secondmate-registry", "main", "registry projection incomplete");
   }
-  const taskRootContext = (task, owner, dependency = false) => {
+  const taskRootContexts = (task, owner, dependency = false) => {
     const open = task.hints?.open_decisions || [];
     const state = safeState(task.current_state?.state || task.state);
     const chatQuestion = open.some((decision) => !decision.key || decision.key === "default");
-    const keyedDecision = open.find((decision) => decision.key && decision.key !== "default");
+    const keyedDecisions = open.filter((decision) => decision.key && decision.key !== "default");
     if (dependency && ["done", "failed"].includes(state)) {
-      return {
+      return [{
         kind: "stale",
+        key: `stale:${task.id}`,
         wait: `it is already ${state}; the dependency edge is stale`,
         action: "Nothing yet - firstmate reconciles this stale dependency",
-      };
+      }];
     }
+    const contexts = [];
     if (chatQuestion) {
-      return {
+      contexts.push({
         kind: "chat",
+        key: `chat:${task.id}`,
         wait: "a worker question is being handled in chat",
         action: "Nothing - firstmate is handling the worker's question in chat.",
-      };
+      });
     }
-    if (keyedDecision) {
+    for (const keyedDecision of keyedDecisions) {
       const ref = decisionRef(owner, keyedDecision.origin || task.id, keyedDecision.key);
-      return {
+      contexts.push({
         kind: "decision",
+        key: `decision:${ref}`,
         wait: `waiting on your decision ${ref}`,
         action: `Answer decision ${ref} - it is the root cause.`,
-      };
+      });
     }
+    if (contexts.length > 0) return [...new Map(contexts.map((context) => [context.key, context])).values()];
     if (state === "paused") {
-      return {
+      return [{
         kind: "paused",
+        key: `paused:${task.id}`,
         wait: "waiting on a declared external delay expected to clear on its own",
         action: "Nothing - this unblocks itself when the external wait clears.",
-      };
+      }];
     }
     if (state === "unknown") {
-      return {
+      return [{
         kind: "unknown",
+        key: `unknown:${task.id}`,
         wait: "its current state could not be read",
         action: "Nothing yet - firstmate reconciles the unavailable state and escalates if your input is needed.",
-      };
+      }];
     }
-    return {
+    return [{
       kind: "worker",
+      key: `worker:${task.id}`,
       wait: `the worker reports state: ${state}`,
       action: "Nothing yet - firstmate is on it and will escalate if your input is needed.",
-    };
+    }];
   };
   for (const record of mainRecords.filter((item) => item.state === "in_flight" && item.structured)) {
     const task = taskById.get(record.id);
@@ -679,9 +687,9 @@ function classify(snapshot, environment) {
     let taskWaits = null;
     let taskCanDo = null;
     if (stage === "blocked") {
-      const context = taskRootContext(task, "main");
-      taskWaits = [context.wait];
-      taskCanDo = context.action;
+      const contexts = taskRootContexts(task, "main");
+      taskWaits = contexts.map((context) => context.wait);
+      taskCanDo = [...new Set(contexts.map((context) => context.action))].join(" ");
     }
     pipeline[stage].push({
       id: itemRef("main", task.id),
@@ -711,109 +719,104 @@ function classify(snapshot, environment) {
     const recordById = new Map(records.filter((record) => record.structured !== false).map((record) => [record.id, record]));
     const blockerTaskById = new Map(tasks.map((task) => [task.id, task]));
     const roots = new Map();
-    const parentById = new Map();
-    const segmentById = new Map();
-    const scheduled = new Set();
+    const expandedEdges = new Set();
     const stack = [];
-    const chainFor = (blockerId, suffix = null) => {
-      const segments = [];
-      let current = blockerId;
-      while (current !== null) {
-        if (segmentById.has(current)) segments.push(segmentById.get(current));
-        current = parentById.get(current) ?? null;
-      }
-      segments.reverse();
-      if (suffix) segments.push(suffix);
-      return segments.join("; then ");
-    };
-    const addRoot = (key, blockerId, suffix, action) => {
-      if (!roots.has(key)) roots.set(key, { wait: chainFor(blockerId, suffix), action });
-    };
-    const isAncestor = (blockerId, candidate) => {
-      let current = blockerId;
-      while (current !== null) {
-        if (current === candidate) return true;
-        current = parentById.get(current) ?? null;
-      }
-      return false;
-    };
-    const schedule = (blockerId, parent) => {
-      if (scheduled.has(blockerId)) return;
-      scheduled.add(blockerId);
-      parentById.set(blockerId, parent);
-      stack.push(blockerId);
+    const addRoot = (key, segments, suffix, action) => {
+      if (roots.has(key)) return;
+      roots.set(key, {
+        wait: [...segments, ...(suffix ? [suffix] : [])].join("; then "),
+        action,
+      });
     };
-    for (const blockerId of [...blockedByIds(startRecord)].reverse()) schedule(blockerId, null);
+    const blockerIds = blockedByIds(startRecord);
+    const startTask = blockerTaskById.get(startRecord.id);
+    if (blockerIds.length === 0 && startTask) {
+      const contexts = taskRootContexts(startTask, owner, true);
+      return {
+        waits: contexts.map((context) => context.wait),
+        action: [...new Set(contexts.map((context) => context.action))].join(" "),
+      };
+    }
+    for (const blockerId of [...blockerIds].reverse()) {
+      stack.push({ blockerId, segments: [], ancestors: new Set() });
+    }
     while (stack.length > 0) {
-      const blockerId = stack.pop();
+      const { blockerId, segments, ancestors } = stack.pop();
       const blockerRef = itemRef(owner, blockerId);
       const blockerRecord = recordById.get(blockerId) || null;
       const blockerTask = blockerTaskById.get(blockerId) || null;
       const currentState = blockerTask ? safeState(blockerTask.current_state?.state || blockerTask.state) : null;
       if (!blockerRecord && !blockerTask) {
-        segmentById.set(blockerId, `blocked by ${blockerRef}, whose current state is unavailable`);
-        addRoot(`missing:${blockerId}`, blockerId, null, "Nothing yet - firstmate reconciles that unavailable blocker and escalates if your input is needed.");
+        addRoot(`missing:${blockerId}`, [...segments, `blocked by ${blockerRef}, whose current state is unavailable`], null, "Nothing yet - firstmate reconciles that unavailable blocker and escalates if your input is needed.");
         continue;
       }
       const terminalState = ["done", "failed"].includes(currentState)
         ? currentState
         : (["done", "failed"].includes(blockerRecord?.state) ? blockerRecord.state : null);
       if (terminalState) {
-        segmentById.set(blockerId, `blocked by ${blockerRef}, but it is already ${terminalState}; the dependency edge is stale`);
-        addRoot(`stale:${blockerId}`, blockerId, null, "Nothing yet - firstmate reconciles this stale dependency");
+        addRoot(`stale:${blockerId}`, [...segments, `blocked by ${blockerRef}, but it is already ${terminalState}; the dependency edge is stale`], null, "Nothing yet - firstmate reconciles this stale dependency");
         continue;
       }
       const prefix = currentState
         ? `blocked by ${blockerRef}, which is currently ${safeState(currentState)}`
         : `blocked by ${blockerRef}, which is ${blockerRecord.state === "in_flight" ? "under way" : "queued and not started"}`;
-      segmentById.set(blockerId, prefix);
-      const taskContext = blockerTask ? taskRootContext(blockerTask, owner, true) : null;
-      if (taskContext && ["chat", "decision", "paused", "unknown"].includes(taskContext.kind)) {
-        const rootKey = taskContext.kind === "decision"
-          ? `decision:${taskContext.wait}`
-          : `${taskContext.kind}:${blockerId}`;
-        addRoot(rootKey, blockerId, taskContext.wait, taskContext.action);
+      const nextSegments = [...segments, prefix];
+      const taskContexts = blockerTask ? taskRootContexts(blockerTask, owner, true) : [];
+      const applicableContexts = taskContexts.filter((context) => ["chat", "decision", "paused", "unknown"].includes(context.kind));
+      if (applicableContexts.length > 0) {
+        for (const context of applicableContexts) addRoot(context.key, nextSegments, context.wait, context.action);
         continue;
       }
       if (blockerRecord?.kind === "captain" && blockerRecord.hold_kind === "captain") {
         const identity = backlogDecisionIdentity(blockerRecord);
         const ref = decisionRef(owner, identity.origin, identity.key);
-        addRoot(`decision:${ref}`, blockerId, `waiting on your decision ${ref}`, `Answer decision ${ref} - it is the root cause.`);
+        addRoot(`decision:${ref}`, nextSegments, `waiting on your decision ${ref}`, `Answer decision ${ref} - it is the root cause.`);
         continue;
       }
       const gate = blockerRecord && futureTimeGate(blockerRecord, now);
       if (gate) {
-        addRoot(`gate:${blockerId}`, blockerId, `waiting until ${gate}`, `Nothing - this unblocks itself when the ${gate} time gate passes.`);
+        addRoot(`gate:${blockerId}`, nextSegments, `waiting until ${gate}`, `Nothing - this unblocks itself when the ${gate} time gate passes.`);
         continue;
       }
       const nestedIds = blockerRecord ? blockedByIds(blockerRecord) : [];
       if (nestedIds.length > 0) {
+        const nextAncestors = new Set(ancestors).add(blockerId);
         for (const nestedId of [...nestedIds].reverse()) {
-          if (isAncestor(blockerId, nestedId)) {
-            addRoot(`cycle:${[blockerId, nestedId].sort().join(":")}`, blockerId, `blocked by ${itemRef(owner, nestedId)}, whose blocker chain contains a cycle`, "Nothing yet - firstmate reconciles this blocker and escalates if your input is needed.");
+          if (nextAncestors.has(nestedId)) {
+            addRoot(`cycle:${[...nextAncestors, nestedId].sort().join(":")}`, nextSegments, `circular dependency through ${itemRef(owner, nestedId)}`, "Nothing yet - firstmate reconciles this circular dependency.");
           } else {
-            schedule(nestedId, blockerId);
+            const edgeKey = `${blockerId}\0${nestedId}`;
+            if (!expandedEdges.has(edgeKey)) {
+              expandedEdges.add(edgeKey);
+              stack.push({ blockerId: nestedId, segments: nextSegments, ancestors: nextAncestors });
+            }
           }
         }
         continue;
       }
       if (blockerRecord?.hold_reason) {
-        addRoot(`hold:${blockerId}`, blockerId, "held by a structured hold", "Nothing yet - firstmate watches this hold and escalates if your input is needed.");
+        addRoot(`hold:${blockerId}`, nextSegments, "held by a structured hold", "Nothing yet - firstmate watches this hold and escalates if your input is needed.");
         continue;
       }
-      if (taskContext?.kind === "worker" && currentState === "blocked") {
-        addRoot(`worker:${blockerId}`, blockerId, taskContext.wait, taskContext.action);
+      const workerContext = taskContexts.find((context) => context.kind === "worker");
+      if (workerContext && currentState === "blocked") {
+        addRoot(workerContext.key, nextSegments, workerContext.wait, workerContext.action);
         continue;
       }
-      addRoot(`finish:${blockerId}`, blockerId, null, `Nothing - this unblocks itself when ${blockerRef} finishes.`);
+      addRoot(`finish:${blockerId}`, nextSegments, null, `Nothing - this unblocks itself when ${blockerRef} finishes.`);
     }
-    const blockerIds = blockedByIds(startRecord);
     if (blockerIds.length === 0) {
       const gate = futureTimeGate(startRecord, now);
       if (gate) return { waits: [`waiting until ${gate}`], action: `Nothing - this unblocks itself when the ${gate} time gate passes.` };
       return { waits: ["held by a structured wait gate"], action: "Nothing yet - firstmate watches this hold and escalates if your input is needed." };
     }
     const resolvedRoots = [...roots.values()];
+    if (resolvedRoots.length === 0) {
+      return {
+        waits: ["circular dependency could not be resolved from the blocker graph"],
+        action: "Nothing yet - firstmate reconciles this circular dependency.",
+      };
+    }
     return {
       waits: resolvedRoots.map((root) => root.wait),
       action: [...new Set(resolvedRoots.map((root) => root.action))].join(" "),
@@ -917,13 +920,14 @@ function classify(snapshot, environment) {
         reason: "Open decision raised by work already under way.",
       });
     }
-    const mateTaskEvidence = (mate.active_children || []).map((child) => ({
-      ...child,
-      hints: {
-        ...(child.hints || {}),
-        open_decisions: (mate.decisions_open || []).filter((decision) => decision.id === child.id),
-      },
-    }));
+    const mateTaskEvidence = [...(mate.active_children || []), ...(mate.holds || []).filter((hold) => hold.source === "child-state" && hold.state)]
+      .map((child) => ({
+        ...child,
+        hints: {
+          ...(child.hints || {}),
+          open_decisions: (mate.decisions_open || []).filter((decision) => decision.id === child.id),
+        },
+      }));
     const heldIds = new Set();
     for (const hold of mate.holds || []) {
       heldIds.add(hold.id);
diff --git a/bin/fm-fleet-snapshot.sh b/bin/fm-fleet-snapshot.sh
index 432ef5f53b0..8eff211aadb 100755
--- a/bin/fm-fleet-snapshot.sh
+++ b/bin/fm-fleet-snapshot.sh
@@ -640,6 +640,7 @@ secondmate_home_summary_json() {  # <backlog-json> <tasks-json>
               delivery_mode:(($work.delivery_mode // null) | if . == null then null else trunc(40) end),
               project_resolved:($work.project_resolved == true),
               since:(($work.since // null) | if . == null then null else trunc(20) end),
+              state:.current_state.state,
               blocked_by:null,blocked_by_all:[],
               reason:((.current_state.detail // .current_state.state) | trunc(120)),source:"child-state"} ]) as $holds_all
     | ($backlog.present == true
diff --git a/tests/fm-bearings-snapshot.test.sh b/tests/fm-bearings-snapshot.test.sh
index 68d66de761b..1a4819a46df 100755
--- a/tests/fm-bearings-snapshot.test.sh
+++ b/tests/fm-bearings-snapshot.test.sh
@@ -664,7 +664,7 @@ EOF
     .secondmate_current.records[] | select(.id == "states")
     | .current.state == "captain_decision"
       and .active_children == []
-      and (.holds | any(.id == "parked" and .source == "child-state"))
+      and (.holds | any(.id == "parked" and .source == "child-state" and .state == "parked"))
   ' >/dev/null || fail "parked child was classified as active work: $canonical"
   cat > "$mate/data/backlog.md" <<'EOF'
 ## In flight
diff --git a/tests/fm-capacity.test.sh b/tests/fm-capacity.test.sh
index 6627e40acb1..6f7c99600cc 100755
--- a/tests/fm-capacity.test.sh
+++ b/tests/fm-capacity.test.sh
@@ -542,6 +542,7 @@ test_secondmate_captain_holds_are_pipeline_waiting_work() {
   make_fixture "$home" "$snapshot" "$environment"
   jq '
     .tasks[0].hints.open_decisions = [
+      {"key":"default"},
       {"key":"build-choice-one"},
       {"key":"build-choice-two"}
     ]
@@ -551,24 +552,27 @@ test_secondmate_captain_holds_are_pipeline_waiting_work() {
       {"id":"mate-choice","key":"mate-choice","verb":"captain-hold","summary":"Sensitive choice","source":"backlog"}
     ]
     | .secondmate_current.records[0].holds = [
-      {"id":"mate-held","title":"Wait for external completion","repo":"delta","project_resolved":true,"kind":"ship","since":"2026-07-20","source":"child-state"}
+      {"id":"mate-held","title":"Wait for external completion","repo":"delta","project_resolved":true,"kind":"ship","since":"2026-07-20","state":"blocked","source":"child-state"}
     ]
     | .secondmate_current.records[0].queued += [
       {"id":"mate-choice","title":"Choose the secondmate rollout","repo":"delta","project_resolved":true,"kind":"captain","hold_kind":"captain","hold_reason":"Sensitive reason"},
       {"id":"mate-structured","title":"Wait on a structured hold","repo":"delta","project_resolved":true,"kind":"ship","hold_reason":"Sensitive reason"},
-      {"id":"mate-time","title":"Resume after 2026-08-15","repo":"delta","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: resume safely."}
+      {"id":"mate-time","title":"Resume after 2026-08-15","repo":"delta","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: resume safely."},
+      {"id":"after-mate-held","title":"Continue after held work","repo":"delta","project_resolved":true,"kind":"ship","blocked_by":"mate-held","body_excerpt":"Acceptance criteria: held work clears."}
     ]
-    | .secondmate_current.records[0].counts = {"active_children":0,"decisions_open":2,"holds":1,"queued":4}
+    | .secondmate_current.records[0].decisions_open[0].id = "mate-held"
+    | .secondmate_current.records[0].counts = {"active_children":0,"decisions_open":2,"holds":1,"queued":5}
   ' "$snapshot" > "$snapshot.tmp"
   mv "$snapshot.tmp" "$snapshot"
   json=$("$CAPACITY" --json --snapshot "$snapshot" --environment "$environment" --output "$output") ||
     fail "secondmate captain-hold capacity run failed"
   printf '%s' "$json" | jq -e '
-    (.pipeline.blocked | length) == 8
+    (.pipeline.blocked | length) == 9
     and .measures.open_captain_actions == 4
     and (.recommendations[] | select(.id == "CAP-01") | .evidence | startswith("4 structured captain"))
-    and ([.pipeline.blocked[] | select(.owner | contains("persistent"))] | length) == 4
+    and ([.pipeline.blocked[] | select(.owner | contains("persistent"))] | length) == 5
     and ([.pipeline.blocked[] | select(.owner | contains("persistent")) | .what_you_can_do] | all(type == "string" and length > 0))
+    and ([.pipeline.blocked[] | select(.owner | contains("persistent")) | .waits_on // [] | join(" ")] | map(select(contains("worker question"))) | length) == 2
   ' >/dev/null || fail "secondmate captain hold was missing or double-counted: $json"
   [ "$(grep -o 'class="verb verb-decide"' "$output" | wc -l | tr -d ' ')" = 4 ] ||
     fail "captain decisions were collapsed or duplicated in the needs-you roll call"
@@ -945,11 +949,17 @@ test_keyless_questions_and_blocker_chains() {
       {"order":16,"state":"queued","structured":true,"id":"stale-dependent","title":"Reconcile a stale dependency","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"finished-root","body_excerpt":"Acceptance criteria: stale edge clears."},
       {"order":17,"state":"queued","structured":true,"id":"branching-dependent","title":"Publish after converging branches","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"branch-a,branch-b","blocked_by_all":["branch-a","branch-b"],"body_excerpt":"Acceptance criteria: both branches clear."},
       {"order":18,"state":"queued","structured":true,"id":"branch-a","title":"First decision branch","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: choose policy."},
-      {"order":19,"state":"queued","structured":true,"id":"branch-b","title":"Second decision branch","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: choose policy."}
+      {"order":19,"state":"queued","structured":true,"id":"branch-b","title":"Second decision branch","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"policy-choice","body_excerpt":"Acceptance criteria: choose policy."},
+      {"order":20,"state":"in_flight","structured":true,"id":"mixed-asker","title":"Resolve several worker questions","repo":"alpha","project_resolved":true,"kind":"ship","body_excerpt":"Acceptance criteria: all questions resolve."},
+      {"order":21,"state":"queued","structured":true,"id":"behind-mixed-worker","title":"Publish after every worker question","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"mixed-asker","body_excerpt":"Acceptance criteria: all roots clear."},
+      {"order":22,"state":"queued","structured":true,"id":"cycle-dependent","title":"Reconcile sibling cycle","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"cycle-a,cycle-b","blocked_by_all":["cycle-a","cycle-b"],"body_excerpt":"Acceptance criteria: cycle clears."},
+      {"order":23,"state":"queued","structured":true,"id":"cycle-a","title":"Cycle side A","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"cycle-b","body_excerpt":"Acceptance criteria: cycle clears."},
+      {"order":24,"state":"queued","structured":true,"id":"cycle-b","title":"Cycle side B","repo":"gamma","project_resolved":true,"kind":"ship","blocked_by":"cycle-a","body_excerpt":"Acceptance criteria: cycle clears."}
     ]
     | .tasks = [
       {"id":"asker","kind":"ship","project":"alpha","current_state":{"state":"blocked","source":"status-fold","detail":"awaiting reply"},"endpoint":{"exists":true,"agent_alive":"not_checked"},"hints":{"open_decisions":[{"key":"default","verb":"needs-decision","summary":"which port should the exporter bind"}]},"pr":{"url":null},"paths":{"report":{"present":false}},"backlog":{"id":"asker","title":"Build the exporter","repo":"alpha","project_resolved":true,"kind":"ship","since":"2026-07-16"}},
-      {"id":"keyed-asker","kind":"ship","project":"beta","current_state":{"state":"blocked","source":"status-fold","detail":"awaiting decision"},"endpoint":{"exists":true,"agent_alive":"not_checked"},"hints":{"open_decisions":[{"key":"api-shape","verb":"needs-decision","summary":"choose v1 or v2 response shape"}]},"pr":{"url":null},"paths":{"report":{"present":false}},"backlog":{"id":"keyed-asker","title":"Build the API","repo":"beta","project_resolved":true,"kind":"ship","since":"2026-07-16"}}
+      {"id":"keyed-asker","kind":"ship","project":"beta","current_state":{"state":"blocked","source":"status-fold","detail":"awaiting decision"},"endpoint":{"exists":true,"agent_alive":"not_checked"},"hints":{"open_decisions":[{"key":"api-shape","verb":"needs-decision","summary":"choose v1 or v2 response shape"}]},"pr":{"url":null},"paths":{"report":{"present":false}},"backlog":{"id":"keyed-asker","title":"Build the API","repo":"beta","project_resolved":true,"kind":"ship","since":"2026-07-16"}},
+      {"id":"mixed-asker","kind":"ship","project":"alpha","current_state":{"state":"blocked","source":"status-fold","detail":"awaiting several answers"},"endpoint":{"exists":true,"agent_alive":"not_checked"},"hints":{"open_decisions":[{"key":"default","verb":"needs-decision"},{"key":"route-one","verb":"needs-decision"},{"key":"route-two","verb":"needs-decision"}]},"pr":{"url":null},"paths":{"report":{"present":false}},"backlog":{"id":"mixed-asker","title":"Resolve several worker questions","repo":"alpha","project_resolved":true,"kind":"ship"}}
     ]
     | .secondmate_current.registry.records = []
     | .secondmate_current.records = []
@@ -960,12 +970,14 @@ test_keyless_questions_and_blocker_chains() {
   json=$("$CAPACITY" --json --snapshot "$snapshot" --environment "$environment" --output "$output") ||
     fail "keyless-question capacity run failed"
   printf '%s' "$json" | jq -e '
-    (.pipeline.blocked | map(select(.reason | contains("Worker question being handled in chat"))) | length) == 1
+    (.pipeline.blocked | map(select(.reason | contains("Worker question being handled in chat"))) | length) == 2
     and (.pipeline.blocked | map(select(.reason | contains("Worker question"))) | .[0].what_you_can_do | contains("firstmate is handling"))
     and ([.pipeline.blocked[] | select(.waits_on != null) | .waits_on[0]] | any(contains("waiting on your decision")))
     and ([.pipeline.blocked[] | .waits_on // [] | join(" ")] | any(contains("blocked by") and contains("currently")))
-    and ([.pipeline.blocked[] | select((.waits_on // []) | length == 2)] | length) == 1
-    and ([.pipeline.blocked[] | select((.waits_on // []) | length == 2) | .waits_on | join(" ")] | .[0] | contains("unavailable"))
+    and any(.pipeline.blocked[];
+      ((.waits_on // []) | length) == 2
+      and ((.waits_on | join(" ")) | contains("worker question"))
+      and ((.waits_on | join(" ")) | contains("unavailable")))
     and any(.pipeline.blocked[];
       ((.waits_on // [] | join(" ")) as $chain
        | ([$chain | scan("blocked by")] | length) >= 6
@@ -980,6 +992,13 @@ test_keyless_questions_and_blocker_chains() {
       (.reason | contains(","))
       and ((.waits_on // []) | length) == 1
       and ((.waits_on | join(" ")) | contains("waiting on your decision")))
+    and any(.pipeline.blocked[];
+      ((.waits_on // []) | length) == 3
+      and ((.waits_on | join(" ")) | contains("worker question"))
+      and (([.waits_on[] | select(contains("waiting on your decision"))] | length) == 2))
+    and any(.pipeline.blocked[];
+      ((.waits_on // [] | join(" ")) | contains("circular dependency"))
+      and (.what_you_can_do | contains("firstmate reconciles this circular dependency")))
     and ([.pipeline.blocked[] | .waits_on // [] | join(" ")] | any(contains("which port")) | not)
   ' >/dev/null || fail "keyless questions or blocker chains are wrong: $json"
   html=$(cat "$output")

From 6d7b2b1ec21251abe9f6e2005ab82c9506be185f Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 15:07:26 -0400
Subject: [PATCH 23/24] no-mistakes(document): Document dashboard command
 handling and keyless questions

---
 docs/dashboard-service.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/dashboard-service.md b/docs/dashboard-service.md
index b5287530fed..3a9c652b358 100644
--- a/docs/dashboard-service.md
+++ b/docs/dashboard-service.md
@@ -15,6 +15,7 @@ The service publishes the producer-generated `data/capacity-dashboard.html` at o
 - A service bar shows how many captain commands are queued for firstmate.
 - A Subscription usage band shows cached `quota-axi --json` windows for Claude, Codex, and Grok, including percent used and reset distance with reset time formatted by the captain's browser in local time.
 - Every blocked row carries its plain-language blocker chain resolved to the root cause plus an explicit "What you can do" line, so no blocked row leaves the captain guessing; chains stay privacy-safe in the on-disk file and de-anonymize at serve time like every other reference.
+- A keyless `needs-decision` status event renders honestly as a worker question that Firstmate is handling in chat, with no fabricated decision identity, `Decide` framing, or dead-end decision detail view.
 - The served page has zero copy-prompt affordances: each producer copy button is replaced by direct dispatch, or removed outright in read-only mode, while the offline file keeps its copy buttons for `file://` use.
 - The installer pins the installing shell's `PATH` into the launchd agent so the generator's state-reader tools resolve, and the service marks a render `RENDER DEGRADED` loudly on the page and in its log when most worker states read unknown - degraded data is never presented as truth.
 
@@ -34,10 +35,10 @@ The on-disk dashboard stays identity-opaque: the producer's opt-in `--refs` side
 Button clicks never execute anything.
 The design keeps the web process outside every fleet-mutation path:
 
-1. The captain clicks "Send to firstmate" on a `CAP-NN` action.
+1. The captain clicks a send or verdict control for a `CAP-NN` action, structured decision answer, or idea verdict.
 2. The service validates the request (see trust design) and writes one durable `fm-dash-command.v1` record into `state/dash-inbox/` with an atomic temp-file rename, mode 0600.
 3. The registered `fm-dash` watcher check notices the pending record on its normal cadence (`FM_CHECK_INTERVAL`, default 300 seconds) and wakes the running firstmate through the standard durable wake queue.
-4. Firstmate claims the records with `bin/fm-dash-inbox.sh claim` and handles each prompt as the captain's approval of that action ID under the capacity skill's section 4 semantics.
+4. Firstmate claims the records with `bin/fm-dash-inbox.sh claim` and handles each record by its kind under the capacity skill's dashboard-command semantics.
 
 Consequences of that shape:
 

From 00a5b57fb14c3db5f323e206e0220e9046029a63 Mon Sep 17 00:00:00 2001
From: Matt McCarthy <matttmccarthy66@gmail.com>
Date: Tue, 28 Jul 2026 15:11:31 -0400
Subject: [PATCH 24/24] no-mistakes(document): Correct dashboard claim handling
 reminder

---
 bin/fm-dash-inbox.sh | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/bin/fm-dash-inbox.sh b/bin/fm-dash-inbox.sh
index d0875a8f649..04c9364a4fb 100755
--- a/bin/fm-dash-inbox.sh
+++ b/bin/fm-dash-inbox.sh
@@ -114,7 +114,8 @@ EOF
     fi
     printf 'delivered: %s captain dashboard command(s)\n' "$delivered"
     printf 'archived: %s captain dashboard command(s)\n' "$archived"
-    echo "apply idempotency checks to every delivered prompt, then handle it as the captain's approval of that action ID under the capacity skill; its authority limits apply and nothing here authorizes a merge, discard, or other destructive act."
+    echo "apply idempotency checks to every delivered prompt, then handle it by kind under the capacity skill; its authority limits apply and nothing here authorizes a merge, discard, or other destructive act."
+    echo "CAP records approve that action ID; decision records answer the named owner-qualified decision through the decision lifecycle, with destructive consequences re-confirmed in chat; idea records are captain verdicts: approve creates work through the normal backlog lifecycle, deny records the outcome, and suggestions are captain input."
     prune_archive
     ;;
   *)