@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/pipeline/lib/hook-registration.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * hook-registration.mjs  -  are the hooks the template ships actually
+ * registered where Claude Code will run them, and which preferences do
+ * nothing because their hook is not?
+ *
+ * Read the way Claude Code reads it, as autopilot-runner.mjs guardRegistration
+ * does for agent-guard: the user settings (CLAUDE_CONFIG_DIR, else ~/.claude:
+ * settings.json and settings.local.json) and the macOS managed settings. A
+ * template entry is registered when an entry of the same event runs the same
+ * command (the $HOME / ${HOME} and quoting spellings are one command) and its
+ * matcher covers every tool name the template's matcher lists. A matcher is a
+ * regex over the tool name; an alternative that is itself a regex
+ * (`mcp__.*[Ff]igma.*`) is covered only by the identical alternative or a
+ * match-all matcher. The command's script has to exist under
+ * ~/.claude/scripts: a hook whose script is missing exits non-zero and blocks
+ * nothing. `disableAllHooks` in any of the files turns every hook off, and
+ * `allowManagedHooksOnly` limits the source to the managed file.
+ *
+ * Inert preferences: a preference whose only effect is through a hook does
+ * nothing while that hook is unregistered (INERT_PREFS).
+ *
+ * Usage:
+ *   hook-registration.mjs check [--json] [--template <claude-hooks.json>]
+ *
+ * Exit: 0 every template hook registered and no inert preference, 1 a gap,
+ * 3 the template could not be read.
+ *
+ * @module pipeline/lib/hook-registration
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { invokedDirectly } from "./invoked-directly.mjs";
+import { globalPref } from "./prefs-value.mjs";
+
+const MANAGED_SETTINGS = "/Library/Application Support/ClaudeCode/managed-settings.json";
+const SIMPLE_TOOL = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Preferences that act only through a hook: the check that says whether the
+ * preference is set to something a hook would act on, and the script.
+ */
+export const INERT_PREFS = [
+  {
+    pref: "editSyntaxGate.enabled",
+    active: (v) => v === true,
+    script: "edit-syntax-gate.sh",
+  },
+  {
+    pref: "bulkRead.mode",
+    active: (v) => v === "observe" || v === "enforce",
+    script: "check-read-size.sh",
+  },
+  {
+    pref: "attendedCommitGate.mode",
+    active: (v) => v === undefined || v === "warn" || v === "block",
+    script: "pre-commit-check.sh",
+  },
+  {
+    pref: "readOnlyRepos",
+    active: (v) => Array.isArray(v) && v.length > 0,
+    script: "agent-guard.sh",
+  },
+];
+
+function readJson(p) {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** The template this install ships: the installed copy, else the source tree's. */
+export function defaultTemplatePath(home = homedir()) {
+  const installed = join(home, ".claude", "templates", "claude-hooks.json");
+  if (existsSync(installed)) return installed;
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, "..", "..", "install", "templates", "claude-hooks.json");
+}
+
+/** The script file name a pipeline hook command runs, or null. */
+export function scriptOf(command) {
+  const m = /scripts\/([\w.-]+\.(?:sh|mjs|py))/.exec(String(command || ""));
+  return m ? m[1] : null;
+}
+
+function normCommand(c) {
+  return String(c || "")
+    .replaceAll("${HOME}", "$HOME")
+    .replaceAll('"', "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Every (event, matcher, command) the template registers. */
+export function templateEntries(template) {
+  const out = [];
+  for (const [event, groups] of Object.entries(template?.hooks || {})) {
+    for (const g of Array.isArray(groups) ? groups : []) {
+      for (const h of Array.isArray(g?.hooks) ? g.hooks : []) {
+        if (h && typeof h.command === "string") {
+          out.push({ event, matcher: g.matcher ?? null, command: h.command });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function matcherCovers(have, want) {
+  const h = typeof have === "string" ? have : "";
+  if (h === "" || h === "*" || h === ".*") return true;
+  if (want === null || want === undefined || want === "") return h === "" || h === "*";
+  if (h === want) return true;
+  return String(want)
+    .split("|")
+    .every((alt) => {
+      if (!SIMPLE_TOOL.test(alt)) return h.split("|").includes(alt);
+      try {
+        return new RegExp(`^(?:${h})$`).test(alt);
+      } catch {
+        return false;
+      }
+    });
+}
+
+/**
+ * Which template hooks are not registered.
+ *
+ * @param {{template: object, home?: string, env?: Record<string,string|undefined>, managedPath?: string}} opts
+ * @returns {{disabled: string|null, missing: {event: string, matcher: string|null, command: string, script: string|null, why: string}[], registeredScripts: Set<string>}}
+ */
+export function registrationGaps({
+  template,
+  home = homedir(),
+  env = process.env,
+  managedPath = MANAGED_SETTINGS,
+}) {
+  const userDir = env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+  const docs = [join(userDir, "settings.json"), join(userDir, "settings.local.json"), managedPath]
+    .map(readJson)
+    .filter((d) => d && typeof d === "object");
+  const wanted = templateEntries(template);
+  const off = docs.find((d) => d.disableAllHooks === true);
+  if (off) {
+    return {
+      disabled: "disableAllHooks is set",
+      missing: wanted.map((w) => ({ ...w, script: scriptOf(w.command), why: "hooks disabled" })),
+      registeredScripts: new Set(),
+    };
+  }
+  const managed = readJson(managedPath);
+  const sources = managed?.allowManagedHooksOnly === true ? [managed] : docs;
+  const scriptsDir = join(home, ".claude", "scripts");
+  const registeredScripts = new Set();
+  const missing = [];
+  for (const w of wanted) {
+    const script = scriptOf(w.command);
+    const groups = sources.flatMap((d) =>
+      Array.isArray(d?.hooks?.[w.event]) ? d.hooks[w.event] : [],
+    );
+    const hit = groups.some(
+      (g) =>
+        g &&
+        matcherCovers(g.matcher, w.matcher) &&
+        Array.isArray(g.hooks) &&
+        g.hooks.some((h) => h && normCommand(h.command) === normCommand(w.command)),
+    );
+    if (!hit) {
+      missing.push({ ...w, script, why: "not registered" });
+      continue;
+    }
+    if (script && !existsSync(join(scriptsDir, script))) {
+      missing.push({ ...w, script, why: `registered, but ~/.claude/scripts/${script} is missing` });
+      continue;
+    }
+    if (script) registeredScripts.add(script);
+  }
+  // A script registered on one matcher still counts as reachable for a
+  // preference; the per-matcher gap is reported in `missing`.
+  return { disabled: null, missing, registeredScripts };
+}
+
+/**
+ * Preferences set to act while their hook is not registered at all.
+ *
+ * @param {Set<string>} registeredScripts
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {{pref: string, script: string}[]}
+ */
+export function inertPrefs(registeredScripts, env = process.env) {
+  return INERT_PREFS.filter((e) => e.active(globalPref(e.pref, undefined, env)))
+    .filter((e) => !registeredScripts.has(e.script))
+    .map(({ pref, script }) => ({ pref, script }));
+}
+
+/** The whole report for one machine. */
+export function hookReport({
+  templatePath,
+  home = homedir(),
+  env = process.env,
+  managedPath,
+} = {}) {
+  const path = templatePath || defaultTemplatePath(home);
+  const template = readJson(path);
+  if (!template)
+    return { ok: false, error: `cannot read the hooks template at ${path}`, templatePath: path };
+  const gaps = registrationGaps({ template, home, env, managedPath });
+  const inert = inertPrefs(gaps.registeredScripts, env);
+  return {
+    ok: gaps.missing.length === 0 && inert.length === 0,
+    templatePath: path,
+    disabled: gaps.disabled,
+    missing: gaps.missing,
+    inert,
+  };
+}
+
+function main(argv) {
+  if (argv[0] !== "check") {
+    process.stderr.write("usage: hook-registration.mjs check [--json] [--template <path>]\n");
+    return 3;
+  }
+  const i = argv.indexOf("--template");
+  const r = hookReport({ templatePath: i === -1 ? undefined : argv[i + 1] });
+  if (argv.includes("--json")) {
+    process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+  } else if (r.error) {
+    process.stderr.write(`hook-registration: ${r.error}\n`);
+  } else {
+    for (const m of r.missing) {
+      process.stdout.write(
+        `missing  ${m.event}${m.matcher ? ` ${m.matcher}` : ""}  ${m.script || m.command}  (${m.why})\n`,
+      );
+    }
+    for (const p of r.inert) {
+      process.stdout.write(
+        `inert    prefs.global.${p.pref} needs ${p.script}, which is not registered\n`,
+      );
+    }
+    if (r.ok) process.stdout.write("hook-registration: every template hook is registered\n");
+  }
+  if (r.error) return 3;
+  return r.ok ? 0 : 1;
+}
+
+if (invokedDirectly(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/pipeline/lib/prefs-value.mjs

@@ -0,0 +1,44 @@
+/**
+ * prefs-value.mjs  -  one `prefs.global.*` value, read the way the hooks read
+ * it: from the first preferences file that exists, MULTI_AGENT_PREFS first,
+ * then ~/.claude, then ~/.config/multi-agent-pipeline. A file that does not
+ * parse yields the fallback rather than an error, because the callers are
+ * hooks that must not fail a tool call over a malformed preference.
+ *
+ * @module pipeline/lib/prefs-value
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** The preferences files a hook consults, in order. */
+export function prefsCandidates(env = process.env) {
+  const home = env.HOME || homedir();
+  return [
+    env.MULTI_AGENT_PREFS,
+    join(home, ".claude", "multi-agent-preferences.json"),
+    join(home, ".config", "multi-agent-pipeline", "multi-agent-preferences.json"),
+  ].filter(Boolean);
+}
+
+/**
+ * `prefs.global.<dotted>` from the first preferences file that exists.
+ *
+ * @param {string} dotted  e.g. "attendedCommitGate.mode"
+ * @param {unknown} fallback
+ * @param {Record<string,string|undefined>} [env]
+ */
+export function globalPref(dotted, fallback, env = process.env) {
+  for (const p of prefsCandidates(env)) {
+    if (!existsSync(p)) continue;
+    try {
+      let node = JSON.parse(readFileSync(p, "utf8"))?.global;
+      for (const key of dotted.split(".")) node = node?.[key];
+      return node === undefined ? fallback : node;
+    } catch {
+      return fallback;
+    }
+  }
+  return fallback;
+}

package/pipeline/lib/run-completion.mjs

@@ -0,0 +1,148 @@
+/**
+ * run-completion.mjs  -  where a run stands against its mode's phase list, and
+ * whether it has earned `status: complete`.
+ *
+ * `complete` is the word every reader trusts: runs-index shows the run as
+ * done, the autopilot runner files it as finished and never queues it again.
+ * So it is held to evidence that is already in the state, not to the claim:
+ *
+ *   1. `currentPhase` is the last phase of the run's mode (schemas/phases.json).
+ *   2. Phase 4 left a trace, unless the mode declares `commits: false`:
+ *      `commit.sha`, a `pr`, a runner `publish` record, a `projects[].commit`
+ *      or `projects[].pr`, or an explicit no-commit decision
+ *      (`phases["4"].status: "skipped"` with a `notes` reason).
+ *   3. The plan's coverage was judged, unless the mode declares
+ *      `commits: false`: a `plan-coverage` entry in `gates[]` with a passing
+ *      verdict. plan-coverage-gate.mjs records it attended and unattended.
+ *
+ * A mode phases.json does not declare is not judged here: such a command runs
+ * its own flow and its own definition of done.
+ *
+ * Writers: write-state.mjs refuses a transition into `complete` that fails
+ * this; the autopilot runner files such a state as `stopped-incomplete`.
+ *
+ * @module pipeline/lib/run-completion
+ */
+
+import { readFileSync } from "node:fs";
+
+const PHASES_URL = new URL("../schemas/phases.json", import.meta.url);
+const PASSING = new Set(["pass", "not-applicable"]);
+
+let contractCache = null;
+
+/** schemas/phases.json, read once per process. */
+export function phaseContract() {
+  if (!contractCache) contractCache = JSON.parse(readFileSync(PHASES_URL, "utf8"));
+  return contractCache;
+}
+
+/**
+ * The mode a state runs in, as phases.json names it. No `mode` is the full
+ * pipeline, or autopilot when the state carries `autopilot: true`.
+ *
+ * @param {object} state
+ * @returns {string}
+ */
+export function modeOf(state) {
+  if (state && typeof state.mode === "string" && state.mode) return state.mode;
+  return state && state.autopilot === true ? "autopilot" : "full";
+}
+
+/** The phases.json entry of the state's mode, or null when it is undeclared. */
+export function modeEntry(state) {
+  const m = phaseContract().modes?.[modeOf(state)];
+  return m && Array.isArray(m.phases) && m.phases.length ? m : null;
+}
+
+/** The ordered phase ids of the state's mode, or null for an undeclared mode. */
+export function modePhases(state) {
+  return modeEntry(state)?.phases ?? null;
+}
+
+/** The last phase of the state's mode, or null for an undeclared mode. */
+export function finalPhaseOf(state) {
+  const list = modePhases(state);
+  return list ? list[list.length - 1] : null;
+}
+
+/** The name phases.json gives a phase id. */
+export function phaseName(id) {
+  const entry = (phaseContract().phases || []).find((p) => p.id === Number(id));
+  return entry?.name || `Phase ${id}`;
+}
+
+/**
+ * The phase a run at `currentPhase` enters next, or null at or past its last
+ * phase, or for an undeclared mode.
+ *
+ * @param {object} state
+ * @returns {{id: number, name: string}|null}
+ */
+export function nextPhaseOf(state) {
+  const list = modePhases(state);
+  const cur = Number(state?.currentPhase);
+  if (!list || !Number.isInteger(cur)) return null;
+  const id = list.find((p) => p > cur);
+  return id === undefined ? null : { id, name: phaseName(id) };
+}
+
+const hasSha = (c) => Boolean(c && typeof c.sha === "string" && c.sha.length >= 7);
+const hasPr = (p) =>
+  Boolean(p && ((typeof p.url === "string" && p.url) || Number.isInteger(p.number)));
+
+/** True when Phase 4 left evidence of delivering, or of deciding not to. */
+export function phase4Evidence(state) {
+  if (hasSha(state.commit) || hasPr(state.pr)) return true;
+  if (state.publish && typeof state.publish === "object") return true;
+  const projects = Array.isArray(state.projects) ? state.projects : [];
+  if (projects.some((p) => p && (hasSha(p.commit) || hasPr(p.pr)))) return true;
+  const p4 = state.phases?.["4"];
+  return Boolean(p4 && p4.status === "skipped" && typeof p4.notes === "string" && p4.notes.trim());
+}
+
+/** True when a passing plan-coverage verdict is in the gate ledger. */
+export function planCoverageRecorded(state) {
+  const gates = Array.isArray(state.gates) ? state.gates : [];
+  let latest = null;
+  for (const e of gates) {
+    if (!e || e.gate !== "plan-coverage") continue;
+    if (!latest || (Date.parse(e.at) || 0) >= (Date.parse(latest.at) || 0)) latest = e;
+  }
+  return Boolean(latest && PASSING.has(latest.verdict));
+}
+
+/**
+ * What stands between this state and `status: complete`. Empty means it may
+ * complete (or its mode is not judged here).
+ *
+ * @param {object} state  the document as it would be written
+ * @returns {string[]}
+ */
+export function completionGaps(state) {
+  if (!state || typeof state !== "object") return ["the state is not an object"];
+  const entry = modeEntry(state);
+  if (!entry) return [];
+  const mode = modeOf(state);
+  const final = entry.phases[entry.phases.length - 1];
+  const gaps = [];
+  const cur = Number(state.currentPhase);
+  if (!Number.isInteger(cur) || cur !== final) {
+    gaps.push(
+      `currentPhase is ${state.currentPhase ?? "unset"}, and mode ${mode} ends at Phase ${final} (${phaseName(final)})`,
+    );
+  }
+  if (entry.commits !== false) {
+    if (!phase4Evidence(state)) {
+      gaps.push(
+        'no Phase 4 evidence: record commit.sha (or pr), or the no-commit decision as phases["4"] = {status: "skipped", notes: "<why>"}',
+      );
+    }
+    if (!planCoverageRecorded(state)) {
+      gaps.push(
+        "no passing plan-coverage verdict in gates[]: run plan-coverage-gate.mjs --state <agent-state.json> (Phase 4 Step 0a)",
+      );
+    }
+  }
+  return gaps;
+}

package/pipeline/multi-agent-refs/analysis/render.md

@@ -23,7 +23,7 @@
      content: <markdown>
    ```
 
-   **Explicit punctuation policy** (enforced by `stripFancyPunctuation: true`): no em-dash (U+2014), no en-dash (U+2013), no horizontal ellipsis (U+2026), no curly quotes (U+2018, U+2019, U+201C, U+201D), no section sign (U+00A7). The humanizer replaces these with ASCII equivalents (`-`, `:`, `,`, `...`, `'`, `"`, and `bölüm` / `section` for the section sign per `outputLanguage`) before emit. Tables, code blocks, URLs, and front-matter YAML are exempt. Verify with `node $HOME/.claude/scripts/validate-analysis-doc.mjs <file>`, not a Perl-regex grep (BSD grep lacks it, so "zero matches" is trivially true). Readability rules live in the humanizer skill; this paragraph owns only the punctuation policy. **Diacritics are PRESERVED: only the listed codepoints are replaced. Turkish letters (ş, ç, ğ, ı, İ, ö, ü) stay verbatim; never ASCII-fold (`Geliştirme Özeti`, not `Gelistirme Ozeti`). ASCII-folded Turkish fails review.**
+   **Explicit punctuation policy** (enforced by `stripFancyPunctuation: true`): no em-dash (U+2014), no en-dash (U+2013), no horizontal ellipsis (U+2026), no curly quotes (U+2018, U+2019, U+201C, U+201D), no section sign (U+00A7). The humanizer replaces these with ASCII equivalents (`-`, `:`, `,`, `...`, `'`, `"`, and `bölüm` / `section` for the section sign per `outputLanguage`) before emit. Tables, code blocks, URLs, and front-matter YAML are exempt. Verify with `node $HOME/.claude/scripts/validate-analysis-doc.mjs <file>`. **Diacritics are PRESERVED: only the listed codepoints are replaced. Turkish letters (ş, ç, ğ, ı, İ, ö, ü) stay verbatim; never ASCII-fold (`Geliştirme Özeti`, not `Gelistirme Ozeti`). ASCII-folded Turkish fails review.**
 
 3b. **Build Section 21 References** (Locked 33). Fingerprint the sources first (`features/analysis-sources.md`), then emit the table:
 
@@ -131,7 +131,7 @@ for f in /tmp/analysis-<feature-slug>-<ts>/*.md; do
 done
 ```
 
-`validate-analysis-doc.mjs` enforces the mechanically-checkable Locked decisions on the emitted markdown itself (front-matter completeness, never-omitted sections per Locked 2, humanizer punctuation per Locked 7, Full-mode business-rule traceability per Locked 30, and in the corporate profile the backbone presence and `EKLENECEK`-to-Section-20 pairing per Locked 32). `build-references.mjs --check` runs the References coverage gate (Locked 33): a source the run consumed but did not list, or a listed row with no evidence behind it, blocks dispatch. `verify-citations.mjs` resolves each claimed `file:line` at HEAD with `git cat-file`, so `Foo.swift:9999` in a repo with no Foo.swift blocks dispatch (Locked 3, Locked 36). Any ERROR blocks dispatch: fix the draft and re-validate. Warnings are advisory (run with `--strict` to treat them as blocking). This turns the "fails the dispatch gate" prose into a real, model-independent check.
+`validate-analysis-doc.mjs` enforces the mechanically-checkable Locked decisions on the emitted markdown itself (front-matter completeness, never-omitted sections per Locked 2, humanizer punctuation per Locked 7, Full-mode business-rule traceability per Locked 30, and in the corporate profile the backbone presence and `EKLENECEK`-to-Section-20 pairing per Locked 32). `build-references.mjs --check` runs the References coverage gate (Locked 33): a source the run consumed but did not list, or a listed row with no evidence behind it, blocks dispatch. `verify-citations.mjs` resolves each claimed `file:line` at HEAD with `git cat-file`, so `Foo.swift:9999` in a repo with no Foo.swift blocks dispatch (Locked 3, Locked 36). Any ERROR blocks dispatch: fix the draft and re-validate. Warnings are advisory (run with `--strict` to treat them as blocking).
 
 Iterate `state.analysisSpec.outputs.requested`. For each target:
 
@@ -155,12 +155,12 @@ After dispatch, print a summary to the user (in `outputLanguage`). Example shape
 STATE="$HOME/.claude/logs/multi-agent/$TASK_ID/agent-state.json"
 mkdir -p "$(dirname "$STATE")"
 STATUS=complete   # or failed when the run could not emit its document
-printf '%s' "{\"taskId\":\"$TASK_ID\",\"command\":\"/multi-agent:analysis\",\"mode\":\"analysis\",\"project\":${PROJECT_JSON:-null},\"status\":\"$STATUS\",\"finishedAt\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" \
+printf '%s' "{\"taskId\":\"$TASK_ID\",\"command\":\"/multi-agent:analysis\",\"mode\":\"analysis\",\"project\":${PROJECT_JSON:-null},\"status\":\"$STATUS\",\"currentPhase\":5,\"finishedAt\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" \
   | node "$HOME/.claude/scripts/write-state.mjs" "$STATE" >/dev/null 2>&1 || true
 node "$HOME/.claude/scripts/usage-report.mjs" --state "$STATE" >/dev/null 2>&1 || true
 ```
 
-`mode` is `analysis`, one of the modes `schemas/phases.json` declares; the reporter sends only those, and anything else as `unknown`. `status` is `complete` or `failed` (agent-state.schema.json), which the reporter turns into the completed or failed run status. `project` is digested by the reporter before it leaves the machine, and is `null` on a stack-optional run - there is no repository to name. A failure here never affects the run: the reporter is best-effort and the summary above is already printed.
+`mode` is `analysis`, one of the modes `schemas/phases.json` declares; the reporter sends only those, and anything else as `unknown`. `status` is `complete` or `failed` (agent-state.schema.json), which the reporter turns into the completed or failed run status. `project` is digested by the reporter before it leaves the machine, and is `null` on a stack-optional run - there is no repository to name. A failure here never affects the run: the reporter is best-effort.
 
 ```
 Feature: <featureName>

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -1,7 +1,7 @@
 # Cross-CLI Contract (Claude Code · Copilot CLI · Codex CLI)
 
 <!-- toc -->
-- [1. Command Inventory (66 commands)](#1-command-inventory-66-commands)
+- [1. Command Inventory (69 commands)](#1-command-inventory-69-commands)
 - [2. Canonical Placeholder Vocabulary](#2-canonical-placeholder-vocabulary)
 - [2.6 Intentional structural divergence  -  thin dispatcher vs inlined orchestrator](#26-intentional-structural-divergence---thin-dispatcher-vs-inlined-orchestrator)
 - [2.7 One command, three different meanings: `/multi-agent:model`](#27-one-command-three-different-meanings-multi-agentmodel)
@@ -20,14 +20,15 @@
 
 ---
 
-## 1. Command Inventory (66 commands)
+## 1. Command Inventory (69 commands)
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
 autopilot-on, autopilot-status, bug-bash, build-optimize, channels, complaint-analysis,
 create-jira, design-check, diff-explain, doctor, estimate, feedback, forget,
 garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
-language, log, manual-test, model, postmortem, prune-logs,
+language, log, manual-test, model, office-off, office-on, office-status,
+postmortem, prune-logs,
 prune-prompts, purge, refactor, research, resume, review,
 review-analysis, review-issue, review-jira, route-off, route-on,
 route-status, routines, save, scaffold, scan, scenario-audit, search,
@@ -42,7 +43,7 @@ Categories:
 - **Issue generator** (one-shot, no worktree, asks type Task/Bug/Story, hard approval gate before create): `create-jira`
 - **Pipeline entries**: `autopilot` (plus the bare `/multi-agent` in the dispatcher). The phase set is a property of the command, and every mode runs its whole set.
 - **Tail path** (the pipeline tail over work already on a branch, no run behind it): `resume`
-- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `steer`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `research`, `scaffold`, `complaint-analysis`, `bug-bash`, `test-gen`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `graph`, `postmortem`, `prune-logs`, `prune-prompts`, `serve`
+- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `steer`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `research`, `scaffold`, `complaint-analysis`, `bug-bash`, `test-gen`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `graph`, `postmortem`, `prune-logs`, `prune-prompts`, `serve`, `office-on`, `office-off`, `office-status`
 - **Local audits** (worktree only to build; no commit, push, PR or channels): `design-check`, `testflight-validation`, `ios-coding-standard`. `testflight-validation` additionally never invokes `altool --upload-app`  -  a validation run must not be able to ship a build by accident.
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
 - **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`

package/pipeline/multi-agent-refs/features/doctor.md

@@ -164,6 +164,17 @@ after the user has already answered the pickers.
 A git identity resolves for the account the run would commit as. WARN: the run
 reaches Phase 4 and stops there.
 
+### hook-reachability
+
+What Claude Code will actually run, read the way the autopilot runner reads the
+agent-guard registration (`lib/hook-registration.mjs`): every template hook has
+an entry of the same event whose matcher covers the template's tool names, runs
+the same command, and finds its script under `~/.claude/scripts`; no
+`disableAllHooks`; and no preference is set to act through a hook that is not
+registered (`editSyntaxGate.enabled`, `bulkRead.mode`, `attendedCommitGate.mode`,
+`readOnlyRepos`). WARN, with each gap in `--explain`. SKIP when the template is
+not installed.
+
 ### hook-coverage
 
 The blocking `PreToolUse` gates from `templates/claude-hooks.json` are present in

package/pipeline/multi-agent-refs/features/office-threat-model.md

@@ -0,0 +1,91 @@
+# Office routes: threat model
+
+The office routes of `scripts/contract-server.mjs` let a client watch the
+agents on this machine, read what they said, answer and steer runs, and change
+what runs here (autopilot, stacks, routines). A browser panel may be served at
+`GET /office`. This file names what is protected, from whom, by which control,
+and which test performs the attack.
+
+Scope: the local server only. A remote carrier (a private network or a relay to
+a phone) is a later stage; its additional threats are listed at the end and are
+not mitigated here.
+
+## Assets
+
+| Asset | Where it lives | Why it matters |
+|---|---|---|
+| Bearer token | the server's memory and a 0600 file under `~/.claude/logs/multi-agent/contract-server/` | holds every desktop route |
+| Transcripts | `~/.claude/projects/**.jsonl` | everything a session read, including file contents and command output |
+| Credentials | the credential store (keychain), read only by the pipeline's own scripts | a leak is an account takeover |
+| Run state | `agent-state.json`, `tracker-state.json` | an answer or steer written here changes what a run does |
+| Machine configuration | autopilot `config.json` and launchd jobs, a repo's `.claude/settings.json`, routine commands | widening any of them changes what runs unattended |
+| PR verdicts | posted to GitHub or Bitbucket with the user's own credential | an approval in the user's name |
+
+## Attackers
+
+1. **A malicious web page** in the user's browser, while the server runs.
+2. **Another local user or process** that can reach 127.0.0.1.
+3. **Hostile transcript content**: text an agent read (a web page, an issue, a
+   file) written to make the panel run script or leak data.
+4. **Later, with a remote carrier**: a compromised relay or site, a stolen
+   phone.
+
+## Threats and controls
+
+| # | Threat | Control | Proof |
+|---|---|---|---|
+| T1 | DNS rebinding: a page on an attacker host resolves to 127.0.0.1 and calls the API under its own name | Every request, `/office` and the event stream included, must carry `Host: 127.0.0.1:<port>` or `localhost:<port>`; anything else is 403 before routing | `smoke-office-security.sh` T1, `test/office-routes.test.mjs` "403 under a rebound Host" |
+| T2 | CSRF: a page posts to a write route | Writes (POST, DELETE) accept no `Origin` but the server's own, even an origin allowed with `--allow-origin`; a foreign preflight is 403 and no CORS header is ever sent to a foreign page; writes that widen what runs here take a second request with a single-use, route-bound confirm token | `smoke-office-security.sh` T2, `office-routes.test.mjs` "a write from a foreign page is refused" |
+| T3 | Token theft or replay | The token is read from the `Authorization` header only (never a cookie or a query parameter), compared in constant time over digests, never written into a response, an error or a log line. It never appears in a URL: `office-on` opens the page with a one-time code in the fragment (10 seconds, one use, minted by the bearer holder at `POST /office/code` with no Origin), and the page trades it at `POST /office/exchange`, which accepts only the server's own Origin; a second use, an expired or an unknown code is 401. The code never reaches a command line, which every local user can read (`ps`): the browser is opened on a 0600 launcher page in the 0700 state directory that carries the code and forwards with `location.replace`, under a CSP that allows only its own script by hash; the launcher is removed after 15 seconds. An Origin header can be forged by a non-browser client, so the code's secrecy and its 10 second, single-use life are what protect the exchange. The page keeps the token in memory and strips the fragment. The server exits after 8 hours however busy it is, so a token cannot outlive a working day | `office-control.test.mjs` "the opener's argv carries no code", "the launcher page has a strict CSP", "the launcher is deleted"; `office-routes.test.mjs` "a panel code trades for the token once", "a code is refused from a foreign page", "an expired code is 401", "exits at its absolute lifetime"; `smoke-office-page.sh` "the code trades once" |
+| T4 | Secret exposure through a response | Transcripts are read through `_transcript-tail.mjs`, which never parses api-request records and drops thinking blocks; every string passes the credential redactor and the scrubber; the finished office and chat documents are checked by the outbound gate; seat labels come from allow-listed fields (tool name, file basename, sidecar description), never a command line; credentials are read only by the service scripts and never returned | `smoke-office-privacy.sh`, `smoke-office-security.sh` T4, `test/office-activity.test.mjs` "carries no credential" |
+| T5 | Path traversal into arbitrary files | Session, agent, run, routine, tool and evidence ids are matched against safe character sets after decoding; transcripts are looked up by name under the projects root only; a screenshot must resolve (real path) inside the run's evidence directory; an analysis document named in run state is read only when its real path is inside the run's log directory, its artifacts or a worktree git lists under the state's projectRoot, and only when it is Markdown or HTML | `smoke-office-security.sh` T5, `test/office-work.test.mjs` "nothing outside its directory", "analysis documents are read only inside the run's roots", "a worktreePath counts only when git lists it" |
+| T6 | Oversized or malformed input | Bodies are capped at 64 KiB and validated against the route's schema; tool arguments are checked against the tool's inputSchema; launch input goes through `launch-request.mjs` validation only; chat paging is capped at 500 | `smoke-office-security.sh` T6, `office-work.test.mjs` "refuses an unknown tool, invalid arguments and an oversized body" |
+| T7 | Resource exhaustion | At most four event streams and 64 connections; a phone request has five seconds to send its body before any signature work; at most 256 confirm tokens, the oldest dropped first; service clients, the work list and autopilot control run as child processes, never blocking the event loop, one at a time per service (429 `busy` for a second one); one snapshot is computed per poll from bounded tail reads; the session list is cached for ten seconds; the server exits after its idle time, after 8 hours in any case, and on SIGTERM | `smoke-office-security.sh` T7; `office-routes.test.mjs` "connections past the cap are dropped", "never sends its body", "confirm tokens are capped"; `office-work.test.mjs` "a slow service read neither blocks other routes nor runs twice at once" |
+| T8 | XSS from hostile transcript or issue text | The panel renders every server string with `textContent` or canvas text; markdown is shown as plain text; server images only as `data:` URLs of image types; the office sprites are same-origin PNGs from `/office/assets/`, which answers only a plain file name (no separator or escape) whose real path is a PNG directly in the installed assets directory, and 404 otherwise; the page language the server stamps comes from a two-value set (`en`, `tr`), whatever the preferences file holds; the page's CSP allows only its per-response nonce for script and style, `connect-src 'self'`, no framing, no base URI, no form action | `smoke-office-page.sh`, `office-routes.test.mjs` "stamps the page language from outputLanguage", "serves a sprite and nothing else under /office/assets/", `office-build.test.mjs`, `smoke-office-runtime.sh` |
+| T9 | Clickjacking | `frame-ancestors 'none'` on the page and on every API response | `office-routes.test.mjs` "serves the page without a token, with a nonce CSP" |
+| T10 | An action nobody can account for | Every write leaves one line (who, route, step, status; never a body or token) in `office-actions.jsonl` | `office-routes.test.mjs` "every write leaves a line" |
+| T11 | The panel widening the machine silently | Autopilot on, stack changes and routine removal are tagged `local-only` and `high`, take two requests, and run the same scripts as the terminal commands | `smoke-office-routes.sh`, `smoke-office-single-source.sh` |
+| T12 | A toolkit tool used as a reader of local files or services (a path, a `file://` or loopback URL, a shared browser page, an index of files) | Tool calls are denied by default: only a tool that declares readOnlyHint, is not destructive, is not in the `web` or `context` family and whose inputSchema takes no location (a property named for a path, URL, file, directory, output, project, root and similar, or a uri format, at any depth) is callable; everything else is 403 `tool-not-allowed` and never reaches the server. A `confirm` argument is refused, so a tool's own preview is never skipped. The toolkit child always runs with `MULTI_AGENT_UNATTENDED=1` and `MCP_TOOLKIT_URL_POLICY=strict`, applied after the registration's own environment. An `@latest` registration is pinned to a configured version or refused. The route is `local-only`, and its audit line names the tool and carries a SHA-256 of the arguments, never the arguments | `office-work.test.mjs` "refuses every tool outside the allowlist with 403 and never runs it", "refuses a confirm argument", "runs unattended with the strict URL policy", "pinned to a known version or refused", "the audit line names the tool and hashes the arguments" |
+| T13 | A steer instruction injected into an unattended run | Steering is tagged `launch` and `high` and takes two requests: the first shows the text, the run's phase and the unread instruction it replaces, and returns a token bound to that run and exactly that text; the second carries only the token. A finished run cannot be steered | `office-routes.test.mjs` "previews first, then queues on confirm", "a steer token is single use, bound to its run and cannot carry new text" |
+| T14 | A review verdict posted from a stale or unfinished review | A verdict is previewed only for a finished review whose every finding is accepted, rejected or deferred (409 `review-incomplete` otherwise); the confirm token is bound to the decision and a digest of the findings, and a confirmation after either changed is 409 `confirm-mismatch` | `office-work.test.mjs` "a running review or one with an untriaged finding cannot be previewed", "refused when the findings changed after the preview" |
+| T15 | A service read pointed at another host | A Confluence URL is accepted only on the configured Confluence host, and with no host configured only a page id is accepted (409 `host-not-allowed`), before the client script runs; Crashlytics takes only a Firebase console URL | `office-work.test.mjs` "a Confluence URL on another host is refused before the client runs", "only a page id is accepted" |
+| T16 | Machine paths leaking through errors, or `office-off` signalling a reused pid | Error bodies name no absolute path (the launchd refusal and the unreadable settings message say what failed, not where); `office-off` sends SIGTERM only when the recorded pid's token file still names it, its command is `contract-server.mjs` and its start time matches the token file's | `office-routes.test.mjs` "refused without naming its path", "reported without the plist path"; `smoke-office-control.sh` "off never signals a pid that is not its server" |
+
+## Residual risks
+
+- **Figma REST from the panel**: `GET /v1/services/figma` renders a frame
+  with the user's Figma token through `figma-screenshot.sh`. It runs only for
+  a panel request, in the server's own process, never inside a pipeline run's
+  context; the pipeline's own rule that Figma is fetched only in the analysis
+  phase is about runs and is unaffected. The Figma MCP is never called here.
+
+- **Another process of the same user** can read the token file and call the
+  API. The server does not defend against code already running as the user;
+  nothing local does.
+- **A page on the server's own origin** is trusted. Only the page this server
+  serves can be there, and its CSP keeps other code out.
+- **Starting a session**: the server returns the launch plan and never starts
+  a host process, so a panel without a local process to run the plan cannot
+  start work by itself. That is a deliberate boundary of the contract.
+- **Host permission prompts** are not forwarded: the host records none where
+  another process can read them (`GET /v1/permissions` says `available:
+  false`).
+
+## Later, with a remote carrier
+
+Not mitigated by this server alone; the carrier must add them before any route
+leaves the machine:
+
+- a compromised relay or site: end-to-end encryption with keys only on the
+  phone and the machine, a separate locked origin with a strict CSP;
+- a stolen phone: device keys bound to a passkey, revocation
+  (`phone-devices.mjs revoke`), and per-operation passkey signatures for every
+  `high` route;
+- the `remote` and `risk` tags on every route are the input for that
+  enforcement; `local-only` routes are never offered remotely;
+- steering from a phone takes a closed set of canned templates (for example
+  "stop after the current phase", "keep the change minimal", "skip the UI
+  test"), chosen by id and expanded on the machine, never free text typed on
+  the phone; free-text steer stays a desktop route;
+- toolkit tool calls stay `local-only`; a phone gets their results only
+  through a run.

package/pipeline/multi-agent-refs/help/en.md

@@ -86,6 +86,9 @@ Status & Resume:
   /multi-agent:autopilot-status  Running, queued, awaiting an answer, today's PRs
   /multi-agent:autopilot-off  Stop picking work up (running work finishes; --now stops it)
   /multi-agent:serve          Contract server for a client: 127.0.0.1, token, stops when idle
+  /multi-agent:office-on      Open the office panel in your browser: agents at work, chats, ledger, runs
+  /multi-agent:office-status  Is the panel running, its URL (never the token), its last actions
+  /multi-agent:office-off     Close the panel now (it also stops by itself when idle)
 
 Post-Hoc & Side-Channel: