@mmerterden/multi-agent-pipeline 20.29.0 → 20.33.0

package/pipeline/scripts/contract-server.mjs

@@ -20,15 +20,61 @@
  *   GET  /v1/issues          issues.mjs --json [--source S] [--project K]... [--max N]
  *   GET  /v1/worktrees       worktrees.mjs --json [--measure] [--redact]
  *   GET  /v1/launch-spec     launch-request.mjs spec
- *   GET  /v1/repos           launch-request.mjs repos [--redact]
+ *   GET  /v1/repos           launch-request.mjs repos [--redact]; ?all=1 adds
+ *                            the suggested and the missing registered ones
+ *   POST /v1/repos           launch-request.mjs register-repo (two steps)
+ *   DELETE /v1/repos/{id}    remove a registered repository (two steps)
  *   POST /v1/launch?repo=P   write a launch request, return launch-request.mjs plan
  *   POST /v1/runs/{id}/answer  answer-question.mjs --question Q --answer IDS
  *   GET  /v1/runs/{id}/log     run-log.mjs {id} --tail N
  *   POST /v1/runs/{id}/resume  launch-request.mjs resume: the plan that resumes it
  *   POST /v1/runs/{id}/kill    run-kill.mjs preview, then apply (two steps)
  *   POST /v1/gc                gc-plan.mjs preview, then apply (two steps)
+ *   POST /v1/prune-logs        office-prune.mjs preview, then apply the listed folders (two steps)
+ *   GET  /v1/settings          office-settings.mjs --json
+ *   POST /v1/settings          office-settings.mjs set S V, after a preview (two steps)
  *   GET  /v1/autopilot         autopilot-control.mjs status
  *   POST /v1/autopilot/off     autopilot-control.mjs off [--now]
+ *   POST /v1/autopilot/on      autopilot-control.mjs on-preview, then on (two steps)
+ *   POST /v1/runs/{id}/steer   steer-run.mjs: queue one instruction for the next phase
+ *   GET  /v1/activity          activity-snapshot.mjs --json
+ *   GET  /v1/activity/stream   the same document as server-sent events, on change
+ *   GET  /v1/agents/{sessionId}/{agentId}/chat   activity-snapshot.mjs chat
+ *   GET  /v1/ledger            office-ledger.mjs --json
+ *   GET  /v1/system            system-status.mjs --json
+ *   GET  /v1/credentials       office-credentials.mjs --json [--probe]
+ *   GET  /v1/memory            office-memory.mjs --json
+ *   GET  /v1/runs/{id}/results run-results.mjs: diff, findings, tests, evidence, analysis
+ *   GET  /v1/runs/{id}/evidence/{name}  run-results.mjs --evidence: one screenshot
+ *   POST /v1/runs/{id}/review-verdict   work-items.mjs verdict, then --post (two steps)
+ *   GET  /v1/issues/{key}/maturity      work-items.mjs maturity (lib/issue-fetcher.sh)
+ *   GET  /v1/prs               work-items.mjs prs
+ *   GET  /v1/tools             toolkit-tools.mjs list (the registered toolkit MCP server)
+ *   POST /v1/tools/{name}/call toolkit-tools.mjs call
+ *   GET  /v1/services/{confluence,crashlytics,figma}  service-read.mjs
+ *   GET  /v1/permissions       pending host permission prompts (none can be read yet)
+ *   GET  /v1/routines          routine-registry.mjs list --json
+ *   DELETE /v1/routines/{name} routine-registry.mjs remove (two steps)
+ *   GET  /v1/stack?repo=R      stack-toggle.mjs status
+ *   POST /v1/stack             stack-toggle.mjs set (two steps)
+ *   GET  /v1/jobs              job-launch.mjs list: the jobs the office can start
+ *   POST /v1/jobs              start one in the background (two steps)
+ *
+ * Every route carries two tags for a remote carrier to enforce later, and
+ * manifest.json repeats them: `remote` is the scope it would need (read,
+ * answer, launch, or local-only for anything that widens what runs on this
+ * machine: autopilot on, stack, routine removal, kill, gc), and `risk` is the
+ * confirmation tier it would need (read, low, high). Locally the bearer token
+ * is the only credential either way.
+ *
+ * GET /office serves the browser panel from MA_OFFICE_PAGE, else
+ * prefs.global.office.page, else the installed copy (office/index.html next
+ * to this scripts directory), and is 404 when none exists. The page carries
+ * no token: it trades a one-time code from its URL fragment for one. It and
+ * its sprites under /office/assets/ are the only routes that need none (with
+ * /favicon.ico, an empty 204, because a browser asks for it on its own), and
+ * its response carries a per-response CSP nonce for its inline script and
+ * style.
  *
  * Phone routes, the same handlers behind a device signature instead of the
  * bearer token, always redacted (features/phone-api.md):
@@ -38,14 +84,19 @@
  *   POST /v1/phone/runs/{id}/answer  scope answer
  *   POST /v1/phone/launch?repo=P     scope launch, and only after `phone-devices.mjs launch on`
  *
- * There is deliberately no route that merges, marks ready, runs a command or
- * starts a host. POST /v1/launch and POST /v1/runs/{id}/resume return the argv
- * and environment launch.json declares; the client starts the process, and
- * nothing here starts a session. The only `claude` this process runs is
- * `claude agents --json` (read, for processAlive) and `claude stop <session>`,
- * for a kill or `autopilot/off` with now.
+ * There is deliberately no route that merges, marks ready, runs a shell
+ * command or takes a prompt. POST /v1/launch and POST /v1/runs/{id}/resume
+ * return the argv and environment launch.json declares for a client to start.
+ * POST /v1/jobs is the one route that starts a session itself, for the office:
+ * a job from schemas/office-jobs.json with typed arguments, two requests, the
+ * unattended profile, workspace trust and the autopilot runner's sandbox check
+ * first, then `claude --bg` without a shell (lib/bg-launch.mjs), never from a
+ * phone. Besides that the only `claude` this process runs is `claude agents
+ * --json` (read, for processAlive) and `claude stop <session>`, for a kill or
+ * `autopilot/off` with now.
  *
- * Kill and gc remove things, so each takes two requests. The first returns a
+ * Kill, gc, autopilot on, stack and routine removal change what this machine
+ * keeps or runs, so each takes two requests. The first returns a
  * preview and a confirm token: 32 random bytes, kept in this process's memory
  * only, bound to the route and the run id, valid for CONFIRM_TTL_MS and for one
  * use. The second sends the token back and acts on exactly what the preview
@@ -63,8 +114,11 @@
  *
  *   1. Host must be 127.0.0.1:<port> or localhost:<port>, which is what stops
  *      a DNS-rebound page from reaching the socket under another name (403);
- *   2. an Origin header must be one of --allow-origin; without the flag no
- *      Origin is accepted and no CORS header is ever sent (403);
+ *   2. an Origin header must be this server's own origin (the panel it
+ *      serves) or one of --allow-origin; any other is refused, and no CORS
+ *      header is sent to it (403). A write (POST, DELETE) and the chat route
+ *      accept no Origin but the server's own: a page somewhere else can never
+ *      drive one, even an allowed one;
  *   3. an allowed preflight is answered, before authentication, since a
  *      browser sends no credentials on one (204);
  *   4. a path under /v1/phone/ leaves here for the device-signature checks in
@@ -79,21 +133,37 @@
  *
  * `?redact=1` is `--redact`. A request that carries an Origin is a browser
  * page, which can relay what it reads anywhere, so it is always served
- * redacted whatever the query says.
+ * redacted whatever the query says. The bearer token is read from the
+ * Authorization header only: never a cookie, never a query parameter.
+ *
+ * Every write route appends one line (who, what, when, outcome; never a
+ * body or a token) to ~/.claude/logs/multi-agent/office-actions.jsonl.
  *
  * Lifetime. The server exits after --idle-minutes without a request (15 by
- * default) and on SIGTERM, SIGINT or SIGHUP, removing its token file either
- * way. It is started on demand by `/multi-agent:serve` or by a client, and is
+ * default, 0 never), after --max-hours however busy it is (8 by default, 0 no
+ * limit; an open event stream does not extend it), and on SIGTERM, SIGINT or
+ * SIGHUP, removing its token file either way. office-on starts it with both at
+ * 0, so the panel runs until office-off.
+ *
+ * Panel bootstrap. `POST /office/code` (bearer, no Origin) mints a code that
+ * is valid for 10 seconds and one use; office-control.mjs opens the browser
+ * with it in the URL fragment. The page trades it for the token with
+ * `POST /office/exchange` (no bearer, own Origin only); a second use, an
+ * expired code or an unknown one is 401. The token itself never appears in a
+ * URL. `GET /office/version` gives the installed page's build id and whether
+ * this server's code changed on disk since it started; `POST /office/reload`
+ * mints a fresh code for the page itself, so it can reload onto a newly
+ * installed page. It is started on demand by `/multi-agent:serve` or by a client, and is
  * never installed as a service.
  *
  * Zero runtime dependencies (ADR-0004): node:http, node:crypto and the
  * producers' own modules.
  *
  * Usage:
- *   node contract-server.mjs [--port N] [--idle-minutes N] [--allow-origin <origin>]... [--print-token]
+ *   node contract-server.mjs [--port N] [--idle-minutes N] [--max-hours N] [--allow-origin <origin>]... [--print-token]
  *
  * Stdout: one JSON line once listening - {contractVersion, url, port, pid,
- * tokenFile, idleMinutes[, token]}.
+ * tokenFile, idleMinutes, maxHours[, token]}.
  * Exit: 0 stopped (idle or signal), 1 could not listen, 2 usage error.
  *
  * @module pipeline/scripts/contract-server
@@ -102,6 +172,7 @@
 import { Buffer } from "node:buffer";
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import {
+  appendFileSync,
   chmodSync,
   existsSync,
   mkdirSync,
@@ -113,15 +184,63 @@ import {
 } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
-import { isAbsolute, join, sep } from "node:path";
-import { clearTimeout, setTimeout } from "node:timers";
+import { basename, dirname, isAbsolute, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { clearInterval, clearTimeout, setInterval, setTimeout } from "node:timers";
 import { answerStateFile } from "./answer-question.mjs";
+import { CONTRACT_VERSION as AUTOPILOT_VERSION, ControlError } from "./autopilot-control.mjs";
+import { spawnAsync } from "./_spawn-async.mjs";
+import {
+  CONTRACT_VERSION as ACTIVITY_VERSION,
+  activitySnapshot,
+  agentChat,
+  createActivityCache,
+} from "./activity-snapshot.mjs";
+import { RoutineError, listRoutines, removeRoutine } from "./routine-registry.mjs";
+import {
+  CONTRACT_VERSION as STACK_VERSION,
+  StackError,
+  stackSet,
+  stackStatus,
+} from "./stack-toggle.mjs";
+import { CONTRACT_VERSION as STEER_VERSION, SteerError, queueSteer } from "./steer-run.mjs";
+import { officeLedger } from "./office-ledger.mjs";
+import { systemStatus } from "./system-status.mjs";
+import { officeCredentials } from "./office-credentials.mjs";
+import { officeMemory } from "./office-memory.mjs";
+import { AGES as PRUNE_AGES, pruneApply, prunePreview } from "./office-prune.mjs";
+import {
+  CHOICES,
+  SettingsError,
+  applySetting,
+  freeChainOf,
+  readSettings,
+} from "./office-settings.mjs";
+import { EVIDENCE_NAME, ResultsError, runEvidence, runResults } from "./run-results.mjs";
+import {
+  WorkError,
+  issueMaturity,
+  postReviewVerdict,
+  pullRequests,
+  reviewVerdictPreview,
+} from "./work-items.mjs";
 import {
-  CONTRACT_VERSION as AUTOPILOT_VERSION,
-  autopilotOff,
-  autopilotStatus,
-  ControlError,
-} from "./autopilot-control.mjs";
+  CONTRACT_VERSION as TOOLS_VERSION,
+  activeToolkitVersion,
+  TOOL_NAME,
+  ToolError,
+  createToolkitClient,
+} from "./toolkit-tools.mjs";
+import {
+  FIGMA_KEY,
+  FIGMA_NODE,
+  PAGE_ID,
+  ServiceError,
+  confluencePage,
+  crashlyticsIssue,
+  figmaFrame,
+} from "./service-read.mjs";
+import { listSessions } from "../lib/claude-sessions.mjs";
 import { catalog } from "./commands.mjs";
 import { collect } from "./issues.mjs";
 import {
@@ -132,16 +251,31 @@ import {
 } from "./gc-plan.mjs";
 import {
   launchRepoAllowed,
+  launchRepos,
   launchSpec,
   planLaunch,
   planResume,
   questionsDocument,
+  registerRepo,
   reposDocument,
+  repoId,
   requestsDir,
+  suggestedRepos,
+  unregisterRepo,
+  missingRepos,
   workingTreeState,
   writeRequestFile,
 } from "./launch-request.mjs";
 import { GROUP_NAMES, envelope, selectRuns } from "./runs-index.mjs";
+import {
+  CONTRACT_VERSION as JOBS_VERSION,
+  JobError,
+  jobsDocument,
+  previewJob,
+  startJob,
+} from "./job-launch.mjs";
+import { guardRegistration, sandboxPrecondition } from "./autopilot-runner.mjs";
+import { codeDigest } from "../lib/code-digest.mjs";
 import { CONTRACT_VERSION as KILL_VERSION, KillError, killPreview, killRun } from "./run-kill.mjs";
 import {
   CONTRACT_VERSION as LOG_VERSION,
@@ -171,7 +305,7 @@ import { runMain } from "../lib/fatal.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 /** The contract as a whole; pipeline/contract/manifest.json carries the same. */
-export const CONTRACT_VERSION = "1.3.0";
+export const CONTRACT_VERSION = "1.6.0";
 /** The majors `?v=` accepts. A new major keeps the previous one here for one minor. */
 export const SUPPORTED_MAJORS = [1];
 export const BIND_HOST = "127.0.0.1";
@@ -180,12 +314,36 @@ export const MAX_BODY_BYTES = 64 * 1024;
 const MAX_DRAIN_BYTES = 1024 * 1024;
 const DEFAULT_IDLE_MINUTES = 15;
 const MAX_IDLE_MINUTES = 24 * 60;
+/** Absolute lifetime: the server exits after this however busy it is. */
+const DEFAULT_MAX_HOURS = 8;
+const MAX_HOURS = 24;
+/** Confirm tokens held at once; the oldest is dropped past this. */
+export const MAX_CONFIRMS = 256;
+/** Connections at once, and how long a phone request may take to send its body. */
+const MAX_CONNECTIONS = 64;
+const PHONE_BODY_TIMEOUT_MS = 5000;
+/** A panel code: single use, valid this long, at most this many outstanding. */
+export const CODE_TTL_MS = 10 * 1000;
+const MAX_CODES = 16;
+const PANEL_CODE = /^[A-Za-z0-9_-]{16,128}$/;
 const RUN_ID = /^[A-Za-z0-9#][A-Za-z0-9#._-]{0,127}$/;
 const PROJECT_KEY = /^[A-Z][A-Z0-9_]*$/;
 const QUESTION_ID = /^[a-z][a-z0-9-]*$/;
 const OPTION_ID = /^[a-z0-9][a-z0-9+_-]*$/;
 const CONTRACT_VERSION_PATTERN = /^1\.[0-9]+\.[0-9]+$/;
 const CONFIRM_TOKEN = /^[A-Za-z0-9_-]{16,128}$/;
+const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const AGENT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const ROUTINE_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const REPO_NAME = /^[A-Za-z0-9._-]{1,100}(?:\/[A-Za-z0-9._-]{1,100})?$/;
+const REPO_ID = /^[0-9a-f]{16}$/;
+/** Server-sent event streams open at once; one more is refused. */
+export const MAX_STREAMS = 4;
+const STREAM_POLL_MS = 2000;
+const STREAM_HEARTBEAT_MS = 15000;
+const SESSIONS_TTL_MS = 10000;
+const MAX_CHAT_LIMIT = 500;
+const HERE = dirname(fileURLToPath(import.meta.url));
 /** How long a kill or gc confirm token stays valid. */
 export const CONFIRM_TTL_MS = 120 * 1000;
 
@@ -201,6 +359,13 @@ const confirmTtlMs = (() => {
   return n >= 1 && n <= CONFIRM_TTL_MS ? n : CONFIRM_TTL_MS;
 })();
 
+/** As confirmTtlMs, for panel codes: MA_OFFICE_CODE_TTL_MS can only shorten it (tests). */
+const codeTtlMs = (() => {
+  const raw = process.env.MA_OFFICE_CODE_TTL_MS;
+  const n = /^[0-9]{1,9}$/.test(raw ?? "") ? Number(raw) : NaN;
+  return n >= 1 && n <= CODE_TTL_MS ? n : CODE_TTL_MS;
+})();
+
 /** Where token files live. Fixed under HOME, never under LOGS_ROOT. */
 export function tokenDir() {
   return join(homedir(), ".claude", "logs", "multi-agent", "contract-server");
@@ -226,10 +391,20 @@ const Q = {
   redact: { check: (v) => v === "0" || v === "1" },
   group: { check: (v) => GROUP_NAMES.includes(v) },
   measure: { check: (v) => v === "0" || v === "1" },
+  all: { check: (v) => v === "0" || v === "1" },
   source: { check: (v) => ["jira", "github", "all"].includes(v) },
   project: { repeat: true, check: (v) => PROJECT_KEY.test(v) },
   max: { check: (v) => /^[0-9]{1,3}$/.test(v) && Number(v) >= 1 && Number(v) <= 200 },
-  repo: { check: (v) => v.length <= 4096 && isAbsolute(v) },
+  repo: { check: (v) => v.length <= 4096 && (isAbsolute(v) || REPO_NAME.test(v)) },
+  before: { check: (v) => /^[0-9]{1,15}$/.test(v) },
+  limit: {
+    check: (v) => /^[0-9]{1,3}$/.test(v) && Number(v) >= 1 && Number(v) <= MAX_CHAT_LIMIT,
+  },
+  confirm: { check: (v) => CONFIRM_TOKEN.test(v) },
+  page: { check: (v) => PAGE_ID.test(v) || (v.length <= 2048 && /^https:\/\//.test(v)) },
+  issue: { check: (v) => v.length <= 2048 && /^https:\/\//.test(v) },
+  file: { check: (v) => FIGMA_KEY.test(v) },
+  node: { check: (v) => FIGMA_NODE.test(v) },
   tail: { check: (v) => /^[0-9]{1,4}$/.test(v) && Number(v) >= 1 && Number(v) <= MAX_TAIL },
 };
 
@@ -336,8 +511,11 @@ function requireWorkspaceTrust(repoPath, redact) {
  * only. Either way the repo must be a configured or registered one.
  */
 function launchRun({ q, body, redact, channel = "desktop" }) {
-  const repoPath = one(q, "repo");
+  let repoPath = one(q, "repo");
   if (!repoPath) throw new HttpError(400, "invalid-query", "repo is required");
+  // A name from GET /v1/repos is accepted too: a browser reads that list
+  // redacted, without paths. Either way the repository must be an allowed one.
+  if (!isAbsolute(repoPath)) repoPath = resolveRepo(repoPath);
   if (!existsSync(repoPath) || !statSync(repoPath).isDirectory()) {
     throw new HttpError(400, "invalid-query", "repo is not a directory");
   }
@@ -430,6 +608,7 @@ const confirms = new Map();
 function mintConfirm(route, id, payload) {
   const now = Date.now();
   for (const [t, c] of confirms) if (c.expires <= now) confirms.delete(t);
+  while (confirms.size >= MAX_CONFIRMS) confirms.delete(confirms.keys().next().value);
   const token = randomBytes(32).toString("base64url");
   const expires = now + confirmTtlMs;
   confirms.set(token, { route, id, expires, payload });
@@ -585,6 +764,87 @@ async function killRoute({ params, body, redact }) {
   }
 }
 
+/**
+ * POST /v1/prune-logs: what prune-logs.sh would remove for an age, and a token
+ * bound to that age and folder list; then a prune of exactly that list
+ * (pruneApply), refused with 409 changed when the folders moved. The age is
+ * one of a fixed set.
+ */
+async function pruneRoute({ body }) {
+  requireBody(
+    body,
+    { confirmToken: isToken, olderThanDays: (v) => PRUNE_AGES.includes(v) },
+    "prune-logs-request.schema.json",
+  );
+  if (body.confirmToken === undefined) {
+    if (body.olderThanDays === undefined)
+      throw new HttpError(400, "invalid-body", "olderThanDays is required for the preview");
+    const { all, ...doc } = await prunePreview(body.olderThanDays, process.env, {
+      keepAll: true,
+    });
+    return {
+      ...doc,
+      ...mintConfirm("prune-logs", "", { days: body.olderThanDays, all, count: doc.count }),
+    };
+  }
+  if (body.olderThanDays !== undefined)
+    throw new HttpError(
+      400,
+      "invalid-body",
+      "olderThanDays belongs to the preview, not the confirmation",
+    );
+  const { days, all, count } = redeemConfirm(body.confirmToken, "prune-logs", "");
+  try {
+    return await pruneApply(days, process.env, { all, count });
+  } catch (e) {
+    if (e.code === "changed") throw new HttpError(409, "changed", e.message);
+    throw e;
+  }
+}
+
+/**
+ * POST /v1/settings: the change a setting would make and a token, then the
+ * same script the terminal command runs. The token is bound to that setting
+ * and value.
+ */
+async function settingsRoute({ body }) {
+  requireBody(
+    body,
+    {
+      confirmToken: isToken,
+      setting: (v) => Object.hasOwn(CHOICES, v),
+      value: (v) => typeof v === "string",
+    },
+    "office-settings-request.schema.json",
+  );
+  if (body.confirmToken === undefined) {
+    if (!body.setting || !CHOICES[body.setting].includes(body.value))
+      throw new HttpError(400, "invalid-body", "setting and one of its values are required");
+    const now = readSettings();
+    return {
+      ...now,
+      change: {
+        setting: body.setting,
+        from: now[body.setting],
+        to: body.value,
+        ...(body.setting === "route" && body.value === "on" && freeChainOf()
+          ? { freeChain: freeChainOf() }
+          : {}),
+      },
+      ...mintConfirm("settings", "", { setting: body.setting, value: body.value }),
+    };
+  }
+  if (body.setting !== undefined || body.value !== undefined)
+    throw new HttpError(400, "invalid-body", "the confirmation carries only its token");
+  const { setting, value } = redeemConfirm(body.confirmToken, "settings", "");
+  try {
+    return await applySetting(setting, value);
+  } catch (e) {
+    if (e instanceof SettingsError) throw new HttpError(409, "not-applied", e.message);
+    throw e;
+  }
+}
+
 function gcRoute({ body, redact }) {
   requireBody(
     body,
@@ -617,9 +877,72 @@ function gcRoute({ body, redact }) {
   return { contractVersion: GC_VERSION, ...out, failed };
 }
 
-function autopilotGet() {
+/**
+ * autopilot-control.mjs run as a child process: its status script, credential
+ * probes and launchctl calls are synchronous, and must not hold up every
+ * other route while they run. The child reports a refusal as
+ * {error: {code, message}} on stdout (MA_CONTROL_JSON_ERRORS).
+ */
+async function control(args) {
+  const r = await spawnAsync(process.execPath, [join(HERE, "autopilot-control.mjs"), ...args], {
+    env: { ...process.env, MA_CONTROL_JSON_ERRORS: "1" },
+    timeoutMs: 180_000,
+    maxBytes: 4 * 1024 * 1024,
+  });
+  let doc;
+  try {
+    doc = JSON.parse(r.stdout);
+  } catch {
+    doc = null;
+  }
+  if (doc?.error && typeof doc.error.code === "string") {
+    throw new ControlError(String(doc.error.message ?? "refused"), doc.error.code);
+  }
+  if (r.status !== 0 || !doc || typeof doc !== "object") {
+    throw new ControlError("autopilot-control did not finish");
+  }
+  return doc;
+}
+
+/**
+ * For a read whose answer is the same for every caller: a request that
+ * arrives while one runs gets that one's answer instead of starting another.
+ */
+const inFlight = new Map();
+const shared = (keyOf, fn) => (ctx) => {
+  const key = keyOf(ctx);
+  if (!inFlight.has(key)) {
+    inFlight.set(
+      key,
+      Promise.resolve()
+        .then(() => fn(ctx))
+        .finally(() => inFlight.delete(key)),
+    );
+  }
+  return inFlight.get(key);
+};
+
+/** One request at a time per key; a second one while the first runs is 429. */
+const running = new Set();
+const oneAtATime = (key, fn) => async (ctx) => {
+  if (running.has(key)) {
+    throw new HttpError(
+      429,
+      "busy",
+      "the same request is still running; try again when it finishes",
+    );
+  }
+  running.add(key);
+  try {
+    return await fn(ctx);
+  } finally {
+    running.delete(key);
+  }
+};
+
+async function autopilotGet() {
   try {
-    return { ...autopilotStatus(), contractVersion: AUTOPILOT_VERSION };
+    return { ...(await control(["status"])), contractVersion: AUTOPILOT_VERSION };
   } catch (err) {
     if (err instanceof ControlError) throw new HttpError(500, "internal", err.message);
     throw err;
@@ -628,184 +951,1132 @@ function autopilotGet() {
 
 async function autopilotOffRoute({ body }) {
   requireBody(body, { now: (v) => typeof v === "boolean" }, "autopilot-off-request.schema.json");
-  return {
-    contractVersion: AUTOPILOT_VERSION,
-    ...(await autopilotOff({ now: body.now === true })),
-  };
+  try {
+    return {
+      contractVersion: AUTOPILOT_VERSION,
+      ...(await control(body.now === true ? ["off", "--now"] : ["off"])),
+    };
+  } catch (err) {
+    if (err instanceof ControlError) throw new HttpError(500, "internal", err.message);
+    throw err;
+  }
 }
 
-const listRuns = ({ q, redact }) =>
-  envelope(selectRuns({ group: one(q, "group") }).records, { redact });
-const oneRun = ({ params, redact }) => envelope(runRecordFor(params.id), { redact });
+const repoArgs = (repos) => repos.flatMap((r) => ["--repo", r]);
 
 /**
- * Every route. `query` names the parameters beyond `v` and `redact` that a
- * route accepts; `body` marks a route that reads a JSON body. A route with
- * `scope` is a phone route: it is reached only with a device signature, never
- * with the bearer token, and is always served redacted.
+ * POST /v1/autopilot/on. Without confirmToken: what would be kept, dropped and
+ * probed, and a token bound to exactly that selection. With it: the mode is
+ * turned on for that selection (autopilot-control.mjs on).
  */
-export const ROUTES = [
-  { method: "GET", path: "/v1/runs", query: ["group"], handle: listRuns },
-  { method: "GET", path: "/v1/runs/{id}", query: [], handle: oneRun },
-  {
-    method: "GET",
-    path: "/v1/commands",
-    query: [],
-    handle: () => {
-      const out = catalog();
-      if (!out) throw new HttpError(500, "internal", "no command tree found");
-      return out;
+async function autopilotOnRoute({ body }) {
+  requireBody(
+    body,
+    {
+      confirmToken: isToken,
+      repos: (v) =>
+        Array.isArray(v) &&
+        v.length >= 1 &&
+        v.length <= 50 &&
+        v.every((x) => typeof x === "string" && REPO_NAME.test(x)),
+      configureOnly: (v) => typeof v === "boolean",
     },
-  },
-  { method: "GET", path: "/v1/questions", query: [], handle: () => questionsDocument() },
-  {
-    method: "GET",
-    path: "/v1/issues",
-    query: ["source", "project", "max"],
-    handle: ({ q }) =>
-      collect({
-        source: one(q, "source") ?? "all",
-        projects: q.project ?? [],
-        max: Number(one(q, "max") ?? 50),
-      }),
-  },
-  {
-    method: "GET",
-    path: "/v1/worktrees",
-    query: ["measure"],
-    handle: ({ q, redact }) => buildList({ doMeasure: flag(one(q, "measure")), redact }),
-  },
-  { method: "GET", path: "/v1/launch-spec", query: [], handle: () => launchSpec() },
-  {
-    method: "GET",
-    path: "/v1/repos",
-    query: [],
-    handle: ({ redact }) => reposDocument({ redact }),
-  },
-  { method: "POST", path: "/v1/launch", query: ["repo"], body: true, handle: launchRun },
-  { method: "POST", path: "/v1/runs/{id}/answer", query: [], body: true, handle: answerRun },
-  { method: "GET", path: "/v1/runs/{id}/log", query: ["tail"], handle: logRun },
-  { method: "POST", path: "/v1/runs/{id}/resume", query: [], body: true, handle: resumeRun },
-  { method: "POST", path: "/v1/runs/{id}/kill", query: [], body: true, handle: killRoute },
-  { method: "POST", path: "/v1/gc", query: [], body: true, handle: gcRoute },
-  { method: "GET", path: "/v1/autopilot", query: [], handle: autopilotGet },
-  { method: "POST", path: "/v1/autopilot/off", query: [], body: true, handle: autopilotOffRoute },
-  { method: "GET", path: "/v1/phone/runs", query: ["group"], scope: "read", handle: listRuns },
-  { method: "GET", path: "/v1/phone/runs/{id}", query: [], scope: "read", handle: oneRun },
-  {
-    method: "POST",
-    path: "/v1/phone/runs/{id}/answer",
-    query: [],
-    body: true,
-    scope: "answer",
-    handle: answerRun,
-  },
-  {
-    method: "POST",
-    path: "/v1/phone/launch",
-    query: ["repo"],
-    body: true,
-    scope: "launch",
-    handle: (ctx) => {
-      if (!ctx.registry.launchEnabled) {
-        throw new HttpError(403, "launch-disabled", "launch from a phone is not enabled here");
+    "autopilot-on-request.schema.json",
+  );
+  try {
+    if (body.confirmToken === undefined) {
+      if (!body.repos) throw new HttpError(400, "invalid-body", "repos is required");
+      const plan = await control(["on-preview", ...repoArgs(body.repos)]);
+      const payload = { repos: plan.keep, configureOnly: body.configureOnly === true };
+      return {
+        contractVersion: AUTOPILOT_VERSION,
+        preview: { ...plan, configureOnly: payload.configureOnly },
+        ...mintConfirm("autopilot-on", "", payload),
+      };
+    }
+    if (body.repos !== undefined || body.configureOnly !== undefined) {
+      throw new HttpError(
+        400,
+        "invalid-body",
+        "the selection belongs to the preview, not the confirmation",
+      );
+    }
+    const payload = redeemConfirm(body.confirmToken, "autopilot-on", "");
+    return {
+      contractVersion: AUTOPILOT_VERSION,
+      ...(await control([
+        "on",
+        ...repoArgs(payload.repos),
+        ...(payload.configureOnly ? ["--configure-only"] : []),
+      ])),
+    };
+  } catch (err) {
+    if (err instanceof ControlError) {
+      if (err.code === "internal" || err.code === "launchd-refused") {
+        throw new HttpError(500, "internal", err.message);
       }
-      return launchRun({ ...ctx, channel: "phone" });
-    },
-  },
-].map((r) => ({
-  ...r,
-  phone: r.path.startsWith(PHONE_PREFIX),
-  pattern: new RegExp(`^${r.path.replace("{id}", "(?<id>[^/]+)")}$`),
-}));
-
-/**
- * The route for a path and method, or the HttpError that says why not. A phone
- * path is looked up among phone routes only and a desktop path among desktop
- * routes only, so neither credential can reach the other family.
- */
-export function match(method, pathname) {
-  const phone = isPhonePath(pathname);
-  const hits = [];
-  for (const r of ROUTES) {
-    if (r.phone !== phone) continue;
-    const m = r.pattern.exec(pathname);
-    if (m) hits.push({ route: r, params: m.groups ?? {} });
-  }
-  if (!hits.length) {
-    if (phone) throw new HttpError(404, "unknown-verb", "the phone API has no such verb");
-    throw new HttpError(404, "not-found", "no such route");
-  }
-  const hit = hits.find((h) => h.route.method === method);
-  if (!hit) {
-    throw new HttpError(
-      405,
-      "method-not-allowed",
-      `use ${hits.map((h) => h.route.method).join(", ")}`,
-      {
-        allow: hits.map((h) => h.route.method).join(", "),
-      },
-    );
-  }
-  if (hit.params.id !== undefined) {
-    try {
-      hit.params.id = decodeURIComponent(hit.params.id);
-    } catch {
-      throw new HttpError(404, "not-found", "no such run");
+      throw new HttpError(409, err.code, err.message);
     }
+    throw err;
   }
-  return hit;
 }
 
-/** Query parameters as {name: [values]}, after every rule a route declares. */
-export function parseQuery(route, searchParams) {
-  const q = {};
-  for (const [k, v] of searchParams) {
-    if (k !== "v" && k !== "redact" && !route.query.includes(k)) {
-      throw new HttpError(400, "invalid-query", `unknown query parameter ${k}`);
-    }
-    (q[k] ??= []).push(v);
-  }
-  for (const [k, values] of Object.entries(q)) {
-    if (k === "v") {
-      if (
-        values.length !== 1 ||
-        !SUPPORTED_MAJORS.includes(Number(values[0])) ||
-        !/^[0-9]+$/.test(values[0])
-      ) {
-        throw new HttpError(400, "unsupported-version", "this server does not serve that major", {
-          supported: SUPPORTED_MAJORS,
-        });
+/** POST /v1/runs/{id}/steer: one instruction for the run's next phase. */
+/**
+ * POST /v1/runs/{id}/steer. Free text for an unattended agent, so it takes
+ * two requests like every high-risk write: the first names the text and gets
+ * a preview (the run, its phase, the unconsumed instruction it would replace)
+ * and a token bound to this run and exactly this text; the second sends only
+ * the token.
+ */
+async function steerRoute({ params, body }) {
+  requireBody(
+    body,
+    { text: (v) => typeof v === "string", confirmToken: isToken },
+    "steer-request.schema.json",
+  );
+  const [record] = runRecordFor(params.id);
+  const file = stateFileOf(record);
+  if (!file) throw new HttpError(409, "not-steerable", "this run has no agent state to steer");
+  try {
+    if (body.confirmToken === undefined) {
+      if (typeof body.text !== "string" || !body.text.trim() || body.text.length > 4000) {
+        throw new HttpError(400, "invalid-body", "text is required, 1 to 4000 characters");
       }
-      continue;
+      const { state } = readState(record);
+      if (["complete", "completed", "done"].includes(state.status)) {
+        throw new HttpError(
+          409,
+          "not-steerable",
+          "the run is finished; nothing would read the instruction",
+        );
+      }
+      const prev = state.pendingSteer;
+      return {
+        contractVersion: STEER_VERSION,
+        taskId: record.taskId,
+        preview: {
+          text: scrub(body.text),
+          status: typeof state.status === "string" ? state.status : null,
+          currentPhase: Number.isFinite(Number(state.currentPhase))
+            ? Number(state.currentPhase)
+            : null,
+          replaces:
+            prev && !prev.appliedAt && typeof prev.text === "string" ? scrub(prev.text) : null,
+        },
+        ...mintConfirm("steer", record.taskId, { text: body.text }),
+      };
     }
-    const rule = Q[k];
-    if (values.length > 1 && !rule.repeat)
-      throw new HttpError(400, "invalid-query", `${k} is given twice`);
-    for (const v of values) {
-      if (!rule.check(v)) throw new HttpError(400, "invalid-query", `${k} has an invalid value`);
+    if (body.text !== undefined) {
+      throw new HttpError(
+        400,
+        "invalid-body",
+        "the text belongs to the preview, not the confirmation",
+      );
+    }
+    const { text } = redeemConfirm(body.confirmToken, "steer", record.taskId);
+    return { ...(await queueSteer(file, text)), taskId: record.taskId };
+  } catch (err) {
+    if (err instanceof SteerError) {
+      if (err.code === "finished") throw new HttpError(409, "not-steerable", err.message);
+      throw new HttpError(400, "invalid-body", err.message);
     }
+    throw err;
   }
-  return q;
 }
 
-const sha = (s) => createHash("sha256").update(s).digest();
+/** The sessions `claude agents --json` lists, read at most every SESSIONS_TTL_MS. */
+let sessionsCache = { at: 0, list: undefined };
+function cachedSessions() {
+  if (Date.now() - sessionsCache.at > SESSIONS_TTL_MS) {
+    sessionsCache = { at: Date.now(), list: listSessions() };
+  }
+  return sessionsCache.list;
+}
 
-/** Does this path belong to the phone family? */
-export const isPhonePath = (pathname) =>
-  pathname === PHONE_PREFIX.slice(0, -1) || pathname.startsWith(PHONE_PREFIX);
+const activityCache = createActivityCache();
+const activityNow = () => activitySnapshot({ sessions: cachedSessions(), cache: activityCache });
 
-/** Constant-time bearer check: equal-length digests, whatever the input. */
-export function authorized(header, tokenDigest) {
-  const m = /^Bearer ([A-Za-z0-9_-]{1,512})$/.exec(String(header ?? ""));
-  return timingSafeEqual(sha(m ? m[1] : ""), tokenDigest) && Boolean(m);
+async function chatRoute({ params, q }) {
+  if (!SESSION_ID.test(params.sessionId)) throw new HttpError(404, "not-found", "no such agent");
+  const agentId = params.agentId === "main" ? null : params.agentId;
+  if (agentId !== null && !AGENT_ID.test(agentId)) {
+    throw new HttpError(404, "not-found", "no such agent");
+  }
+  const page = await agentChat({
+    sessionId: params.sessionId,
+    agentId,
+    before: one(q, "before") === null ? null : Number(one(q, "before")),
+    limit: one(q, "limit") === null ? 200 : Number(one(q, "limit")),
+  });
+  if (!page) throw new HttpError(404, "not-found", "no such agent");
+  return page;
 }
 
-function readRawBody(req) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
+const routinesDocument = () => ({
+  contractVersion: ACTIVITY_VERSION,
+  routines: listRoutines(homedir()).map((r) => ({
+    name: String(r?.name ?? ""),
+    description: typeof r?.description === "string" ? scrub(r.description) : "",
+    createdAt: typeof r?.createdAt === "string" ? r.createdAt : null,
+    source: typeof r?.source === "string" ? scrub(r.source) : null,
+  })),
+});
+
+const routinesGet = () => {
+  try {
+    return routinesDocument();
+  } catch (err) {
+    if (err instanceof RoutineError) throw new HttpError(500, "internal", err.message);
+    throw err;
+  }
+};
+
+/** DELETE /v1/routines/{name}: a preview and token, then ?confirm=<token> removes it. */
+function routineDeleteRoute({ params, q }) {
+  const name = params.name;
+  if (!ROUTINE_NAME.test(name)) throw new HttpError(404, "not-found", "no such routine");
+  try {
+    const token = one(q, "confirm");
+    if (token === null) {
+      const entry = routinesDocument().routines.find((r) => r.name === name);
+      if (!entry) throw new HttpError(404, "not-found", "no such routine");
+      return {
+        contractVersion: ACTIVITY_VERSION,
+        preview: entry,
+        ...mintConfirm("routine-delete", name, null),
+      };
+    }
+    redeemConfirm(token, "routine-delete", name);
+    return { contractVersion: ACTIVITY_VERSION, removed: removeRoutine(homedir(), name) };
+  } catch (err) {
+    if (err instanceof RoutineError) throw new HttpError(409, "not-removable", err.message);
+    throw err;
+  }
+}
+
+const notAllowed = () =>
+  new HttpError(
+    403,
+    "repo-not-allowed",
+    "repo is neither a configured autopilot repo nor one registered with launch-request.mjs register-repo",
+  );
+
+/**
+ * The checkout a panel request names: an absolute path or a name from
+ * GET /v1/repos, and either way one of the repositories launch accepts.
+ */
+function resolveRepo(ref) {
+  if (!ref) throw new HttpError(400, "invalid-query", "repo is required");
+  if (isAbsolute(ref)) {
+    if (!launchRepoAllowed(ref)) throw notAllowed();
+    return realOr(ref);
+  }
+  const hits = launchRepos().filter((r) => r.name === ref);
+  if (hits.length > 1) {
+    throw new HttpError(409, "repo-ambiguous", "more than one repository has that name");
+  }
+  if (!hits.length) throw notAllowed();
+  return hits[0].path;
+}
+
+/**
+ * POST /v1/repos: add a checkout launch accepts. The first request names a
+ * suggestion (an id from GET /v1/repos?all=1) or an absolute path; the
+ * preview says what would be stored and mints a token; the second request
+ * sends only the token. Only a git checkout is accepted from here.
+ */
+function repoAddRoute({ body }) {
+  requireBody(
+    body,
+    {
+      confirmToken: isToken,
+      suggestion: (v) => typeof v === "string" && REPO_ID.test(v),
+      path: (v) => typeof v === "string" && v.length <= 4096 && isAbsolute(v),
+    },
+    "repo-request.schema.json",
+  );
+  if (body.confirmToken === undefined) {
+    let path;
+    if (body.suggestion !== undefined && body.path !== undefined) {
+      throw new HttpError(400, "invalid-body", "name a suggestion or a path, not both");
+    }
+    if (body.suggestion !== undefined) {
+      const hit = suggestedRepos().find((r) => r.id === body.suggestion);
+      if (!hit) throw new HttpError(404, "not-found", "no such suggestion");
+      path = hit.path;
+    } else if (body.path !== undefined) {
+      path = realOr(body.path);
+    } else {
+      throw new HttpError(400, "invalid-body", "suggestion or path is required");
+    }
+    if (launchRepoAllowed(path)) {
+      throw new HttpError(409, "already-registered", "launch already accepts that repository");
+    }
+    let real;
+    try {
+      real = registerRepoCheck(path);
+    } catch (err) {
+      throw new HttpError(400, "invalid-body", err.message);
+    }
+    // The page picks a repository by folder name; a second one with the same
+    // name could never be told apart there.
+    if (launchRepos().some((r) => r.name.split("/").pop() === basename(real))) {
+      throw new HttpError(
+        409,
+        "name-taken",
+        "a repository with that folder name is already on the list",
+      );
+    }
+    return {
+      contractVersion: ACTIVITY_VERSION,
+      preview: { name: basename(real) },
+      ...mintConfirm("repo-add", "", { path: real }),
+    };
+  }
+  if (body.suggestion !== undefined || body.path !== undefined) {
+    throw new HttpError(
+      400,
+      "invalid-body",
+      "the selection belongs to the preview, not the confirmation",
+    );
+  }
+  const { path } = redeemConfirm(body.confirmToken, "repo-add", "");
+  try {
+    const stored = registerRepo(path, process.env, { requireCheckout: true });
+    return { contractVersion: ACTIVITY_VERSION, registered: { name: basename(stored) } };
+  } catch (err) {
+    // registerRepo's own refusals name no path; anything else (a lock timeout,
+    // a disk error) can, so it stays in the server's log.
+    if (REGISTER_REFUSALS.has(err.message)) throw new HttpError(409, "not-registered", err.message);
+    process.stderr.write(`contract-server: repo-add: ${err.message}\n`);
+    throw new HttpError(409, "not-registered", "the repository could not be stored");
+  }
+}
+const REGISTER_REFUSALS = new Set([
+  "the path must be absolute",
+  "the path is not a directory",
+  "the home directory or the root is not a repository",
+  "the path is not a git checkout",
+]);
+
+// What registerRepo would refuse, checked without writing.
+function registerRepoCheck(path) {
+  const real = realOr(path);
+  let st;
+  try {
+    st = statSync(real);
+  } catch {
+    throw new Error("the path is not a directory");
+  }
+  if (!st.isDirectory()) throw new Error("the path is not a directory");
+  if (real === "/" || real === realOr(homedir())) {
+    throw new Error("the home directory or the root is not a repository");
+  }
+  if (!existsSync(join(real, ".git"))) throw new Error("the path is not a git checkout");
+  return real;
+}
+
+/** DELETE /v1/repos/{id}: a registered entry, preview then ?confirm=<token>. */
+function repoRemoveRoute({ params, q }) {
+  const id = params.id;
+  if (!REPO_ID.test(id)) throw new HttpError(404, "not-found", "no such repository");
+  const entry = [
+    ...launchRepos()
+      .filter((r) => r.source === "registered")
+      .map((r) => ({ id: repoId(r.path), name: r.name })),
+    ...missingRepos().map((r) => ({ id: r.id, name: r.name })),
+  ].find((r) => r.id === id);
+  const token = one(q, "confirm");
+  if (token === null) {
+    if (!entry) throw new HttpError(404, "not-found", "no registered repository has that id");
+    return {
+      contractVersion: ACTIVITY_VERSION,
+      preview: { name: entry.name },
+      ...mintConfirm("repo-remove", id, null),
+    };
+  }
+  redeemConfirm(token, "repo-remove", id);
+  const removed = unregisterRepo(id);
+  if (!removed) throw new HttpError(404, "not-found", "no registered repository has that id");
+  return { contractVersion: ACTIVITY_VERSION, removed: { name: basename(removed) } };
+}
+
+const JOB_STATUS = {
+  "unknown-job": 404,
+  "command-not-installed": 409,
+  "invalid-repo": 400,
+  "invalid-args": 400,
+  "invalid-request": 400,
+  "no-launch-shape": 422,
+  "room-busy": 409,
+  "sandbox-unavailable": 409,
+  "launch-failed": 502,
+};
+
+function jobError(err) {
+  if (!(err instanceof JobError)) return err;
+  return new HttpError(JOB_STATUS[err.code] ?? 400, err.code, err.message, {
+    ...(err.extra.errors ? { errors: err.extra.errors } : {}),
+  });
+}
+
+const knownRun = (id) => selectRuns({ taskId: id }).found;
+
+/** A session started without agent-guard has no second layer; the office starts none. */
+function requireGuard(repoPath) {
+  if (guardRegistration({ cwd: repoPath }).ok) return;
+  throw new HttpError(
+    409,
+    "guard-missing",
+    "agent-guard.sh is not registered for every tool, so nothing starts unattended",
+  );
+}
+
+/**
+ * POST /v1/jobs: hand a job to someone in the office. The first request names
+ * jobId, repo and args (and answers for a pipeline run); the preview says
+ * which command starts, with what, and what it writes outside this machine,
+ * and mints a token. The second request sends only the token: the server then
+ * checks the unattended profile, the workspace trust and the unattended
+ * sandbox, starts the session in the background and records it for the floor.
+ */
+async function jobsPost({ body }) {
+  requireBody(
+    body,
+    {
+      confirmToken: isToken,
+      jobId: (v) => typeof v === "string" && /^[a-z][a-z0-9-]{1,40}$/.test(v),
+      repo: (v) =>
+        typeof v === "string" && v.length <= 4096 && (isAbsolute(v) || REPO_NAME.test(v)),
+      args: (v) => v !== null && typeof v === "object" && !Array.isArray(v),
+      answers: (v) => v !== null && typeof v === "object" && !Array.isArray(v),
+    },
+    "job-request.schema.json",
+  );
+  try {
+    if (body.confirmToken === undefined) {
+      if (!body.jobId || !body.repo) {
+        throw new HttpError(400, "invalid-body", "jobId and repo are required");
+      }
+      const repoPath = resolveRepo(body.repo);
+      requireUnattendedProfile();
+      requireGuard(repoPath);
+      const sessions = cachedSessions();
+      const { job, prompt } = previewJob({
+        jobId: body.jobId,
+        args: body.args ?? {},
+        answers: body.answers,
+        repoPath,
+        knownRun,
+        sessions,
+      });
+      return {
+        contractVersion: JOBS_VERSION,
+        preview: {
+          jobId: job.id,
+          role: job.role,
+          team: job.team,
+          repo: basename(repoPath),
+          prompt,
+          writes: job.writes,
+        },
+        ...mintConfirm("job", "", {
+          jobId: job.id,
+          args: body.args ?? {},
+          answers: body.answers,
+          repoPath,
+        }),
+      };
+    }
+    if (["jobId", "repo", "args", "answers"].some((k) => body[k] !== undefined)) {
+      throw new HttpError(
+        400,
+        "invalid-body",
+        "the job belongs to the preview, not the confirmation",
+      );
+    }
+    const p = redeemConfirm(body.confirmToken, "job", "");
+    if (!launchRepoAllowed(p.repoPath)) throw notAllowed();
+    requireUnattendedProfile();
+    requireWorkspaceTrust(p.repoPath, true);
+    requireGuard(p.repoPath);
+    const record = await startJob({
+      jobId: p.jobId,
+      args: p.args,
+      answers: p.answers,
+      repoPath: p.repoPath,
+      repoName: basename(p.repoPath),
+      knownRun,
+      sessions: cachedSessions(),
+      precondition: sandboxPrecondition,
+    });
+    return {
+      contractVersion: JOBS_VERSION,
+      started: {
+        sessionId: record.sessionId,
+        jobId: record.jobId,
+        role: record.role,
+        team: record.team,
+        repo: record.repo,
+      },
+    };
+  } catch (err) {
+    throw jobError(err);
+  }
+}
+
+function stackError(err) {
+  if (!(err instanceof StackError)) return err;
+  if (err.code === "unreadable-settings") {
+    return new HttpError(409, "unreadable-settings", err.message);
+  }
+  return new HttpError(400, "invalid-body", err.message);
+}
+
+function stackGet({ q }) {
+  const repo = resolveRepo(one(q, "repo"));
+  try {
+    return stackStatus(repo);
+  } catch (err) {
+    throw stackError(err);
+  }
+}
+
+/** POST /v1/stack: the planned enabledPlugins and a token, then the write. */
+function stackPost({ body }) {
+  requireBody(
+    body,
+    {
+      confirmToken: isToken,
+      repo: (v) =>
+        typeof v === "string" && v.length <= 4096 && (isAbsolute(v) || REPO_NAME.test(v)),
+      stacks: (v) =>
+        Array.isArray(v) &&
+        v.length >= 1 &&
+        v.length <= 8 &&
+        v.every((x) => typeof x === "string" && /^[a-z]{2,16}$/.test(x)),
+    },
+    "stack-request.schema.json",
+  );
+  try {
+    if (body.confirmToken === undefined) {
+      if (!body.repo || !body.stacks) {
+        throw new HttpError(400, "invalid-body", "repo and stacks are required");
+      }
+      const repo = resolveRepo(body.repo);
+      const plan = stackSet(repo, body.stacks, { dryRun: true });
+      return {
+        contractVersion: STACK_VERSION,
+        preview: {
+          stacks: plan.stacks,
+          changed: plan.changed,
+          enabledPlugins: plan.enabledPlugins,
+          dropped: plan.dropped,
+        },
+        ...mintConfirm("stack", "", { repo, stacks: body.stacks }),
+      };
+    }
+    if (body.repo !== undefined || body.stacks !== undefined) {
+      throw new HttpError(
+        400,
+        "invalid-body",
+        "the selection belongs to the preview, not the confirmation",
+      );
+    }
+    const { repo, stacks } = redeemConfirm(body.confirmToken, "stack", "");
+    return { ...stackSet(repo, stacks), contractVersion: STACK_VERSION };
+  } catch (err) {
+    throw stackError(err);
+  }
+}
+
+function resultsRoute({ params }) {
+  if (!RUN_ID.test(params.id)) throw new HttpError(404, "not-found", "no such run");
+  try {
+    return runResults(params.id);
+  } catch (err) {
+    if (err instanceof ResultsError) throw new HttpError(404, "not-found", "no such run");
+    throw err;
+  }
+}
+
+function evidenceRoute({ params }) {
+  if (!RUN_ID.test(params.id) || !EVIDENCE_NAME.test(params.name)) {
+    throw new HttpError(404, "not-found", "no such image");
+  }
+  try {
+    return runEvidence(params.id, params.name);
+  } catch (err) {
+    if (err instanceof ResultsError) throw new HttpError(404, "not-found", "no such image");
+    throw err;
+  }
+}
+
+function workError(err) {
+  if (!(err instanceof WorkError)) return err;
+  if (err.code === "no-run" || err.code === "bad-key")
+    return new HttpError(404, "not-found", err.message);
+  if (err.code === "no-review" || err.code === "no-findings") {
+    return new HttpError(409, "no-review", err.message);
+  }
+  if (err.code === "not-installed") return new HttpError(409, "not-installed", err.message);
+  if (err.code === "review-incomplete") return new HttpError(409, "review-incomplete", err.message);
+  if (err.code === "changed") return new HttpError(409, "confirm-mismatch", err.message);
+  return new HttpError(502, "upstream-failed", err.message);
+}
+
+async function maturityRoute({ params }) {
+  try {
+    return await issueMaturity(params.key);
+  } catch (err) {
+    throw workError(err);
+  }
+}
+
+/**
+ * POST /v1/runs/{id}/review-verdict: the verdict post-pr-review.sh would post
+ * and a token, then the post itself. The verdict follows from the findings the
+ * review recorded; no request chooses it. Only a finished review whose every
+ * finding is triaged can be previewed, and the token is bound to the decision
+ * and the findings digest it showed: when either changed before the
+ * confirmation, it is refused with confirm-mismatch.
+ */
+async function reviewVerdictRoute({ params, body }) {
+  requireBody(body, { confirmToken: isToken }, "review-verdict-request.schema.json");
+  try {
+    const [record] = runRecordFor(params.id);
+    if (body.confirmToken === undefined) {
+      const preview = reviewVerdictPreview(record.taskId);
+      const bound = { decision: preview.decision, findingsDigest: preview.findingsDigest };
+      return { ...preview, ...mintConfirm("review-verdict", record.taskId, bound) };
+    }
+    const expected = redeemConfirm(body.confirmToken, "review-verdict", record.taskId);
+    return await postReviewVerdict(record.taskId, process.env, expected);
+  } catch (err) {
+    throw workError(err);
+  }
+}
+
+/** The toolkit MCP client of this server, started on first use, closed on stop. */
+let toolkit = null;
+const toolkitClient = () => (toolkit ??= createToolkitClient());
+export const closeToolkit = () => {
+  toolkit?.close();
+  toolkit = null;
+};
+
+function toolError(err) {
+  if (!(err instanceof ToolError)) return err;
+  if (err.code === "unknown-tool") return new HttpError(404, "not-found", "no such tool");
+  if (err.code === "tool-not-allowed") return new HttpError(403, "tool-not-allowed", err.message);
+  if (err.code === "unpinned") return new HttpError(409, "not-installed", err.message);
+  if (err.code === "invalid-arguments") {
+    return new HttpError(400, "invalid-body", err.message, { errors: err.extra?.errors ?? [] });
+  }
+  if (err.code === "not-registered") return new HttpError(409, "not-installed", err.message);
+  return new HttpError(502, "upstream-failed", err.message);
+}
+
+async function toolsRoute() {
+  try {
+    const tools = await toolkitClient().listTools();
+    return { contractVersion: TOOLS_VERSION, version: activeToolkitVersion(), tools };
+  } catch (err) {
+    throw toolError(err);
+  }
+}
+
+async function toolCallRoute({ params, body }) {
+  requireBody(
+    body,
+    { arguments: (v) => v && typeof v === "object" && !Array.isArray(v) },
+    "tool-call-request.schema.json",
+  );
+  if (!TOOL_NAME.test(params.name)) throw new HttpError(404, "not-found", "no such tool");
+  try {
+    return await toolkitClient().callTool(params.name, body.arguments ?? {});
+  } catch (err) {
+    throw toolError(err);
+  }
+}
+
+function serviceError(err) {
+  if (!(err instanceof ServiceError)) return err;
+  if (err.code === "bad-input") return new HttpError(400, "invalid-query", err.message);
+  if (err.code === "not-installed" || err.code === "not-configured") {
+    return new HttpError(409, "not-installed", err.message);
+  }
+  if (err.code === "host-not-allowed") return new HttpError(409, "host-not-allowed", err.message);
+  return new HttpError(502, "upstream-failed", err.message);
+}
+
+const serviceRoute = (key, fn) =>
+  oneAtATime(key, async (ctx) => {
+    try {
+      return await fn(ctx);
+    } catch (err) {
+      throw serviceError(err);
+    }
+  });
+
+/**
+ * GET /v1/permissions. Claude Code offers no mechanism that records a pending
+ * permission prompt outside the session that shows it, so there is nothing to
+ * list yet. The shape is fixed now so a client can render it, and `available`
+ * says plainly that nothing is forwarded; pipeline questions are answered
+ * through POST /v1/runs/{id}/answer.
+ */
+const permissionsDocument = () => ({
+  contractVersion: TOOLS_VERSION,
+  available: false,
+  reason:
+    "the host does not record pending permission prompts where another process can read them; pipeline questions are in GET /v1/activity and answered with POST /v1/runs/{id}/answer",
+  requests: [],
+});
+
+const listRuns = ({ q, redact }) =>
+  envelope(selectRuns({ group: one(q, "group") }).records, { redact });
+const oneRun = ({ params, redact }) => envelope(runRecordFor(params.id), { redact });
+
+/**
+ * Every route. `query` names the parameters beyond `v` and `redact` that a
+ * route accepts; `body` marks a route that reads a JSON body. A route with
+ * `scope` is a phone route: it is reached only with a device signature, never
+ * with the bearer token, and is always served redacted.
+ *
+ * `remote` and `risk` are the tags a remote carrier would enforce: the scope a
+ * caller would need (read, answer, launch, local-only) and the confirmation
+ * tier (read, low, high). `stream` marks the server-sent event route,
+ * `selfOrigin` a route a foreign page may never read even when its origin is
+ * allowed (the chat transcript), and `write` a route whose call is logged.
+ */
+export const ROUTES = [
+  { method: "GET", path: "/v1/runs", query: ["group"], handle: listRuns },
+  { method: "GET", path: "/v1/runs/{id}", query: [], handle: oneRun },
+  {
+    method: "GET",
+    path: "/v1/commands",
+    query: [],
+    handle: () => {
+      const out = catalog();
+      if (!out) throw new HttpError(500, "internal", "no command tree found");
+      return out;
+    },
+  },
+  { method: "GET", path: "/v1/questions", query: [], handle: () => questionsDocument() },
+  {
+    method: "GET",
+    path: "/v1/issues",
+    query: ["source", "project", "max"],
+    handle: ({ q }) =>
+      collect({
+        source: one(q, "source") ?? "all",
+        projects: q.project ?? [],
+        max: Number(one(q, "max") ?? 50),
+      }),
+  },
+  {
+    method: "GET",
+    path: "/v1/worktrees",
+    query: ["measure"],
+    handle: ({ q, redact }) => buildList({ doMeasure: flag(one(q, "measure")), redact }),
+  },
+  { method: "GET", path: "/v1/launch-spec", query: [], handle: () => launchSpec() },
+  {
+    method: "GET",
+    path: "/v1/repos",
+    query: ["all"],
+    handle: ({ q, redact }) => reposDocument({ redact, extras: flag(one(q, "all")) }),
+  },
+  {
+    method: "POST",
+    path: "/v1/repos",
+    query: [],
+    body: true,
+    remote: "local-only",
+    risk: "high",
+    handle: repoAddRoute,
+  },
+  {
+    method: "DELETE",
+    path: "/v1/repos/{id}",
+    query: ["confirm"],
+    remote: "local-only",
+    risk: "high",
+    handle: repoRemoveRoute,
+  },
+  {
+    method: "POST",
+    path: "/v1/launch",
+    query: ["repo"],
+    body: true,
+    remote: "launch",
+    risk: "high",
+    handle: launchRun,
+  },
+  {
+    method: "POST",
+    path: "/v1/runs/{id}/answer",
+    query: [],
+    body: true,
+    remote: "answer",
+    risk: "low",
+    handle: answerRun,
+  },
+  { method: "GET", path: "/v1/runs/{id}/log", query: ["tail"], handle: logRun },
+  {
+    method: "POST",
+    path: "/v1/runs/{id}/resume",
+    query: [],
+    body: true,
+    remote: "launch",
+    risk: "high",
+    handle: resumeRun,
+  },
+  {
+    method: "POST",
+    path: "/v1/runs/{id}/steer",
+    query: [],
+    body: true,
+    remote: "launch",
+    risk: "high",
+    handle: steerRoute,
+  },
+  {
+    method: "POST",
+    path: "/v1/runs/{id}/kill",
+    query: [],
+    body: true,
+    remote: "local-only",
+    risk: "high",
+    handle: killRoute,
+  },
+  {
+    method: "POST",
+    path: "/v1/gc",
+    query: [],
+    body: true,
+    remote: "local-only",
+    risk: "high",
+    handle: gcRoute,
+  },
+  {
+    method: "POST",
+    path: "/v1/prune-logs",
+    query: [],
+    body: true,
+    remote: "local-only",
+    risk: "high",
+    handle: oneAtATime("prune-logs", pruneRoute),
+  },
+  {
+    method: "GET",
+    path: "/v1/settings",
+    query: [],
+    remote: "local-only",
+    handle: () => readSettings(),
+  },
+  {
+    method: "POST",
+    path: "/v1/settings",
+    query: [],
+    body: true,
+    remote: "local-only",
+    risk: "high",
+    handle: oneAtATime("settings", settingsRoute),
+  },
+  {
+    method: "GET",
+    path: "/v1/autopilot",
+    query: [],
+    handle: oneAtATime("autopilot-status", autopilotGet),
+  },
+  {
+    method: "POST",
+    path: "/v1/autopilot/off",
+    query: [],
+    body: true,
+    remote: "launch",
+    risk: "low",
+    handle: oneAtATime("autopilot", autopilotOffRoute),
+  },
+  {
+    method: "POST",
+    path: "/v1/autopilot/on",
+    query: [],
+    body: true,
+    remote: "local-only",
+    risk: "high",
+    handle: oneAtATime("autopilot", autopilotOnRoute),
+  },
+  { method: "GET", path: "/v1/activity", query: [], handle: () => activityNow() },
+  {
+    method: "GET",
+    path: "/v1/activity/stream",
+    query: [],
+    stream: true,
+    handle: () => activityNow(),
+  },
+  {
+    method: "GET",
+    path: "/v1/agents/{sessionId}/{agentId}/chat",
+    query: ["before", "limit"],
+    selfOrigin: true,
+    handle: chatRoute,
+  },
+  { method: "GET", path: "/v1/ledger", query: [], handle: () => officeLedger() },
+  {
+    method: "GET",
+    path: "/v1/system",
+    query: [],
+    handle: shared(
+      () => "system",
+      () => systemStatus(),
+    ),
+  },
+  {
+    method: "GET",
+    path: "/v1/credentials",
+    query: ["probe"],
+    remote: "local-only",
+    handle: shared(
+      ({ q }) => "credentials:" + (one(q, "probe") === "1"),
+      ({ q }) => officeCredentials({ probe: one(q, "probe") === "1" }),
+    ),
+  },
+  {
+    method: "GET",
+    path: "/v1/memory",
+    query: [],
+    remote: "local-only",
+    handle: shared(
+      () => "memory",
+      () => officeMemory(),
+    ),
+  },
+  { method: "GET", path: "/v1/runs/{id}/results", query: [], handle: resultsRoute },
+  { method: "GET", path: "/v1/runs/{id}/evidence/{name}", query: [], handle: evidenceRoute },
+  {
+    method: "POST",
+    path: "/v1/runs/{id}/review-verdict",
+    query: [],
+    body: true,
+    remote: "launch",
+    risk: "high",
+    handle: oneAtATime("review-verdict", reviewVerdictRoute),
+  },
+  {
+    method: "GET",
+    path: "/v1/issues/{key}/maturity",
+    query: [],
+    handle: oneAtATime("maturity", maturityRoute),
+  },
+  {
+    method: "GET",
+    path: "/v1/prs",
+    query: [],
+    handle: oneAtATime("prs", ({ redact }) => pullRequests({ redact })),
+  },
+  { method: "GET", path: "/v1/tools", query: [], handle: toolsRoute },
+  {
+    method: "POST",
+    path: "/v1/tools/{name}/call",
+    query: [],
+    body: true,
+    remote: "local-only",
+    risk: "high",
+    handle: toolCallRoute,
+  },
+  {
+    method: "GET",
+    path: "/v1/services/confluence",
+    query: ["page"],
+    handle: serviceRoute("confluence", ({ q }) => {
+      if (one(q, "page") === null) throw new HttpError(400, "invalid-query", "page is required");
+      return confluencePage(one(q, "page"));
+    }),
+  },
+  {
+    method: "GET",
+    path: "/v1/services/crashlytics",
+    query: ["issue"],
+    handle: serviceRoute("crashlytics", ({ q }) => {
+      if (one(q, "issue") === null) throw new HttpError(400, "invalid-query", "issue is required");
+      return crashlyticsIssue(one(q, "issue"));
+    }),
+  },
+  {
+    method: "GET",
+    path: "/v1/services/figma",
+    query: ["file", "node"],
+    handle: serviceRoute("figma", ({ q }) => {
+      if (one(q, "file") === null || one(q, "node") === null) {
+        throw new HttpError(400, "invalid-query", "file and node are required");
+      }
+      return figmaFrame(one(q, "file"), one(q, "node"));
+    }),
+  },
+  { method: "GET", path: "/v1/permissions", query: [], handle: permissionsDocument },
+  { method: "GET", path: "/v1/routines", query: [], handle: routinesGet },
+  {
+    method: "DELETE",
+    path: "/v1/routines/{name}",
+    query: ["confirm"],
+    remote: "local-only",
+    risk: "high",
+    handle: routineDeleteRoute,
+  },
+  { method: "GET", path: "/v1/stack", query: ["repo"], handle: stackGet },
+  { method: "GET", path: "/v1/jobs", query: [], handle: () => jobsDocument() },
+  {
+    method: "POST",
+    path: "/v1/jobs",
+    query: [],
+    body: true,
+    remote: "local-only",
+    risk: "high",
+    handle: jobsPost,
+  },
+  {
+    method: "POST",
+    path: "/v1/stack",
+    query: [],
+    body: true,
+    remote: "local-only",
+    risk: "high",
+    handle: stackPost,
+  },
+  { method: "GET", path: "/v1/phone/runs", query: ["group"], scope: "read", handle: listRuns },
+  { method: "GET", path: "/v1/phone/runs/{id}", query: [], scope: "read", handle: oneRun },
+  {
+    method: "POST",
+    path: "/v1/phone/runs/{id}/answer",
+    query: [],
+    body: true,
+    scope: "answer",
+    risk: "low",
+    handle: answerRun,
+  },
+  {
+    method: "POST",
+    path: "/v1/phone/launch",
+    query: ["repo"],
+    body: true,
+    scope: "launch",
+    risk: "high",
+    handle: (ctx) => {
+      if (!ctx.registry.launchEnabled) {
+        throw new HttpError(403, "launch-disabled", "launch from a phone is not enabled here");
+      }
+      return launchRun({ ...ctx, channel: "phone" });
+    },
+  },
+].map((r) => ({
+  ...r,
+  remote: r.remote ?? r.scope ?? "read",
+  risk: r.risk ?? "read",
+  write: r.method !== "GET",
+  phone: r.path.startsWith(PHONE_PREFIX),
+  params: [...r.path.matchAll(/\{([A-Za-z]+)\}/g)].map((m) => m[1]),
+  pattern: new RegExp(`^${r.path.replace(/\{([A-Za-z]+)\}/g, "(?<$1>[^/]+)")}$`),
+}));
+
+/**
+ * The route for a path and method, or the HttpError that says why not. A phone
+ * path is looked up among phone routes only and a desktop path among desktop
+ * routes only, so neither credential can reach the other family.
+ */
+export function match(method, pathname) {
+  const phone = isPhonePath(pathname);
+  const hits = [];
+  for (const r of ROUTES) {
+    if (r.phone !== phone) continue;
+    const m = r.pattern.exec(pathname);
+    if (m) hits.push({ route: r, params: m.groups ?? {} });
+  }
+  if (!hits.length) {
+    if (phone) throw new HttpError(404, "unknown-verb", "the phone API has no such verb");
+    throw new HttpError(404, "not-found", "no such route");
+  }
+  const hit = hits.find((h) => h.route.method === method);
+  if (!hit) {
+    throw new HttpError(
+      405,
+      "method-not-allowed",
+      `use ${hits.map((h) => h.route.method).join(", ")}`,
+      {
+        allow: hits.map((h) => h.route.method).join(", "),
+      },
+    );
+  }
+  for (const [k, v] of Object.entries(hit.params)) {
+    try {
+      hit.params[k] = decodeURIComponent(v);
+    } catch {
+      throw new HttpError(404, "not-found", k === "id" ? "no such run" : "no such resource");
+    }
+  }
+  return hit;
+}
+
+/** Query parameters as {name: [values]}, after every rule a route declares. */
+export function parseQuery(route, searchParams) {
+  const q = {};
+  for (const [k, v] of searchParams) {
+    if (k !== "v" && k !== "redact" && !route.query.includes(k)) {
+      throw new HttpError(400, "invalid-query", `unknown query parameter ${k}`);
+    }
+    (q[k] ??= []).push(v);
+  }
+  for (const [k, values] of Object.entries(q)) {
+    if (k === "v") {
+      if (
+        values.length !== 1 ||
+        !SUPPORTED_MAJORS.includes(Number(values[0])) ||
+        !/^[0-9]+$/.test(values[0])
+      ) {
+        throw new HttpError(400, "unsupported-version", "this server does not serve that major", {
+          supported: SUPPORTED_MAJORS,
+        });
+      }
+      continue;
+    }
+    const rule = Q[k];
+    if (values.length > 1 && !rule.repeat)
+      throw new HttpError(400, "invalid-query", `${k} is given twice`);
+    for (const v of values) {
+      if (!rule.check(v)) throw new HttpError(400, "invalid-query", `${k} has an invalid value`);
+    }
+  }
+  return q;
+}
+
+const sha = (s) => createHash("sha256").update(s).digest();
+
+/** Does this path belong to the phone family? */
+export const isPhonePath = (pathname) =>
+  pathname === PHONE_PREFIX.slice(0, -1) || pathname.startsWith(PHONE_PREFIX);
+
+/** Constant-time bearer check: equal-length digests, whatever the input. */
+export function authorized(header, tokenDigest) {
+  const m = /^Bearer ([A-Za-z0-9_-]{1,512})$/.exec(String(header ?? ""));
+  return timingSafeEqual(sha(m ? m[1] : ""), tokenDigest) && Boolean(m);
+}
+
+function readRawBody(req, timeoutMs = 0) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
     let size = 0;
     let over = false;
+    if (timeoutMs > 0) {
+      const timer = setTimeout(
+        () => reject(new HttpError(408, "invalid-body", "the body did not arrive in time")),
+        timeoutMs,
+      );
+      req.on("end", () => clearTimeout(timer));
+      req.on("close", () => clearTimeout(timer));
+    }
     req.on("data", (chunk) => {
       size += chunk.length;
       if (size > MAX_BODY_BYTES) over = true;
@@ -846,7 +2117,13 @@ function drain(req) {
 }
 
 function parseArgs(argv) {
-  const opts = { port: 0, idleMinutes: DEFAULT_IDLE_MINUTES, origins: [], printToken: false };
+  const opts = {
+    port: 0,
+    idleMinutes: DEFAULT_IDLE_MINUTES,
+    maxHours: DEFAULT_MAX_HOURS,
+    origins: [],
+    printToken: false,
+  };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     const value = () => {
@@ -863,10 +2140,16 @@ function parseArgs(argv) {
       opts.port = Number(p);
     } else if (a === "--idle-minutes") {
       const n = Number(value());
-      if (!Number.isFinite(n) || n <= 0 || n > MAX_IDLE_MINUTES) {
-        throw new Error(`--idle-minutes is more than 0 and at most ${MAX_IDLE_MINUTES}`);
+      if (!Number.isFinite(n) || n < 0 || n > MAX_IDLE_MINUTES) {
+        throw new Error(`--idle-minutes is 0 (never) to ${MAX_IDLE_MINUTES}`);
       }
       opts.idleMinutes = n;
+    } else if (a === "--max-hours") {
+      const n = Number(value());
+      if (!Number.isFinite(n) || n < 0 || n > MAX_HOURS) {
+        throw new Error(`--max-hours is 0 (no limit) to ${MAX_HOURS}`);
+      }
+      opts.maxHours = n;
     } else if (a === "--allow-origin") {
       const o = value();
       let parsed;
@@ -904,6 +2187,154 @@ function writeTokenFile(record) {
   return file;
 }
 
+export const OFFICE_PATH = "/office";
+/** Bearer, no Origin: mints a one-time panel code (office-control.mjs). */
+export const OFFICE_CODE_PATH = "/office/code";
+/** No bearer, own Origin only: trades a panel code for the token, once. */
+export const OFFICE_EXCHANGE_PATH = "/office/exchange";
+/** Bearer, own Origin or none: the installed page's build and whether this server is stale. */
+export const OFFICE_VERSION_PATH = "/office/version";
+/** Bearer, own Origin or none: a fresh panel code, so the page can reload itself. */
+export const OFFICE_RELOAD_PATH = "/office/reload";
+
+const serverDigest = () => codeDigest(dirname(fileURLToPath(import.meta.url)));
+/** The server's code (scripts/ and lib/) as it was at start; a reinstall changes the files, not the process. */
+const SERVER_DIGEST = serverDigest();
+
+/** The build id office-build.mjs stamps into the installed page, or null. */
+export function officeBuild(env = process.env) {
+  const file = officePage(env);
+  if (!file) return null;
+  try {
+    return /const BUILD = "([0-9a-f]{12})";/.exec(readFileSync(file, "utf8"))?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function readPrefs(env) {
+  try {
+    return JSON.parse(
+      readFileSync(
+        env.MULTI_AGENT_PREFS || join(homedir(), ".claude", "multi-agent-preferences.json"),
+        "utf8",
+      ),
+    );
+  } catch {
+    return null;
+  }
+}
+
+function prefsOfficePage(env) {
+  return readPrefs(env)?.global?.office?.page ?? null;
+}
+
+/**
+ * The page language: "tr" when prefs.global.outputLanguage is Turkish, else
+ * "en". Only these two values ever reach the page, so the stamp needs no
+ * escaping.
+ */
+export function officeLang(env = process.env) {
+  const lang = readPrefs(env)?.global?.outputLanguage;
+  return typeof lang === "string" && /^tr\b/i.test(lang) ? "tr" : "en";
+}
+
+/**
+ * The panel page, when one is on disk: MA_OFFICE_PAGE, else
+ * prefs.global.office.page, else (neither set) the copy beside this package.
+ * A configured path is the only candidate, so pointing it elsewhere never
+ * falls back. Absolute, regular files only; none is not an error, the route
+ * is 404.
+ */
+export function officePage(env = process.env) {
+  const configured = env.MA_OFFICE_PAGE || prefsOfficePage(env);
+  const candidates = configured ? [configured] : [join(HERE, "..", "office", "index.html")];
+  for (const p of candidates) {
+    if (typeof p !== "string" || !isAbsolute(p)) continue;
+    try {
+      if (statSync(p).isFile()) return p;
+    } catch {
+      // Not there: the route answers 404.
+    }
+  }
+  return null;
+}
+
+/** Sprites of the office floor, served beside the page under this prefix. */
+export const OFFICE_ASSET_PREFIX = "/office/assets/";
+const OFFICE_ASSET_NAME = /^[A-Za-z0-9_]{1,48}\.png$/;
+const OFFICE_ASSET_MAX_BYTES = 256 * 1024;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * A sprite of the installed page: the raw name matches a plain file name
+ * pattern (no separator, no escape), the file is a regular PNG of at most
+ * 256 KiB whose real path is directly inside the page's assets directory.
+ * Anything else is null, which the route answers with 404.
+ */
+export function officeAsset(name, env = process.env) {
+  if (!OFFICE_ASSET_NAME.test(name)) return null;
+  const page = officePage(env);
+  if (!page) return null;
+  try {
+    const dir = realpathSync(join(dirname(page), "assets"));
+    const file = realpathSync(join(dir, name));
+    if (dirname(file) !== dir) return null;
+    const st = statSync(file);
+    if (!st.isFile() || st.size > OFFICE_ASSET_MAX_BYTES) return null;
+    const body = readFileSync(file);
+    return body.subarray(0, 8).equals(PNG_SIGNATURE) ? body : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The panel's CSP: nothing but its own nonce'd inline code, same-origin calls and images. */
+export const officeCsp = (nonce) =>
+  [
+    "default-src 'none'",
+    `script-src 'nonce-${nonce}'`,
+    `style-src 'nonce-${nonce}'`,
+    "img-src 'self' data:",
+    "connect-src 'self'",
+    "frame-ancestors 'none'",
+    "base-uri 'none'",
+    "form-action 'none'",
+  ].join("; ");
+
+/** Where every write route leaves its line. */
+export function actionsLog() {
+  return join(homedir(), ".claude", "logs", "multi-agent", "office-actions.jsonl");
+}
+
+/**
+ * One line per write: who (the local bearer holder, and whether the request
+ * came from the panel page), what (route, path parameters, preview or
+ * confirm), when and the outcome; a tool call adds the sha256 of its
+ * arguments. Never a body, a query value or a token.
+ * A log that cannot be written does not fail the request.
+ */
+function logAction({ route, params, own, confirm, status, error, argsSha256 }) {
+  const line = {
+    at: new Date().toISOString(),
+    who: "local",
+    via: own ? "panel" : "client",
+    route,
+    params,
+    step: confirm ? "confirm" : "request",
+    status,
+    ...(argsSha256 ? { argsSha256 } : {}),
+    ...(error ? { error } : {}),
+  };
+  try {
+    const file = actionsLog();
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    appendFileSync(file, JSON.stringify(line) + "\n", { mode: 0o600 });
+  } catch {
+    // The action itself already happened or was refused; the log is best effort.
+  }
+}
+
 /**
  * Start listening. Resolves with the ready record once the port is known.
  *
@@ -915,11 +2346,28 @@ export function serve(opts) {
   const origins = new Set(opts.origins ?? []);
   const idleMs = Math.round((opts.idleMinutes ?? DEFAULT_IDLE_MINUTES) * 60000);
   let hosts = new Set();
+  let selfOrigins = new Set();
+  const streams = new Set();
   let startSec = Infinity;
   const nonces = createNonceStore({ file: noncesPath() });
   let tokenFile = null;
   let idleTimer = null;
+  let lifeTimer = null;
   let stopping = false;
+  const codes = new Map();
+  const mintCode = () => {
+    const now = Date.now();
+    for (const [c, exp] of codes) if (exp <= now) codes.delete(c);
+    while (codes.size >= MAX_CODES) codes.delete(codes.keys().next().value);
+    const code = randomBytes(32).toString("base64url");
+    codes.set(code, now + codeTtlMs);
+    return { code, expiresAt: new Date(now + codeTtlMs).toISOString() };
+  };
+  const redeemCode = (code) => {
+    const exp = typeof code === "string" && PANEL_CODE.test(code) ? codes.get(code) : undefined;
+    if (exp !== undefined) codes.delete(code);
+    return exp !== undefined && exp > Date.now();
+  };
 
   // requireHostHeader off: a request without Host reaches the Host check below
   // and is refused there with a contract error body, like any other wrong Host.
@@ -929,6 +2377,7 @@ export function serve(opts) {
     requireHostHeader: false,
   });
   server.maxHeadersCount = 50;
+  server.maxConnections = MAX_CONNECTIONS;
 
   const send = (res, status, obj, extra = {}) => {
     const body = serialize(obj);
@@ -937,11 +2386,37 @@ export function serve(opts) {
       "Content-Length": Buffer.byteLength(body),
       "Cache-Control": "no-store",
       "X-Content-Type-Options": "nosniff",
+      "Referrer-Policy": "no-referrer",
+      "Content-Security-Policy": "default-src 'none'; frame-ancestors 'none'",
       "X-Contract-Version": CONTRACT_VERSION,
       ...extra,
     });
     res.end(body);
   };
+
+  /**
+   * The panel, with a fresh nonce in its CSP and in each inline script and
+   * style tag, so no other inline code runs, and its language stamped in.
+   * 404 when no page is installed.
+   */
+  const serveOffice = (res, headOnly) => {
+    const file = officePage();
+    if (!file) throw new HttpError(404, "not-found", "no panel is installed on this machine");
+    const nonce = randomBytes(18).toString("base64url");
+    const html = readFileSync(file, "utf8")
+      .replaceAll("{{NONCE}}", nonce)
+      .replaceAll("{{LANG}}", officeLang());
+    res.writeHead(200, {
+      "Content-Type": "text/html; charset=utf-8",
+      "Content-Length": Buffer.byteLength(html),
+      "Cache-Control": "no-store",
+      "X-Content-Type-Options": "nosniff",
+      "Referrer-Policy": "no-referrer",
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Content-Security-Policy": officeCsp(nonce),
+    });
+    res.end(headOnly ? undefined : html);
+  };
   const fail = (res, err, extra) => {
     const body = { contractVersion: CONTRACT_VERSION, error: err.code, message: err.message };
     if (err.extra?.errors) body.errors = err.extra.errors;
@@ -957,7 +2432,10 @@ export function serve(opts) {
     if (stopping) return;
     stopping = true;
     clearTimeout(idleTimer);
+    clearTimeout(lifeTimer);
     removeTokenFile();
+    for (const st of streams) clearInterval(st.timer);
+    closeToolkit();
     process.stderr.write(`contract-server: stopping (${why})\n`);
     server.close(() => process.exit(0));
     server.closeAllConnections();
@@ -965,7 +2443,7 @@ export function serve(opts) {
   };
   const arm = () => {
     clearTimeout(idleTimer);
-    idleTimer = setTimeout(() => stop("idle"), idleMs);
+    if (idleMs > 0) idleTimer = setTimeout(() => stop("idle"), idleMs);
   };
 
   /**
@@ -977,7 +2455,7 @@ export function serve(opts) {
     const audit = { deviceId: null, method: req.method, verb: verbOf(url.pathname) };
     let insecure = null;
     try {
-      const raw = await readRawBody(req);
+      const raw = await readRawBody(req, PHONE_BODY_TIMEOUT_MS);
       const registry = readRegistry();
       insecure = registry.insecure;
       const v = verifyRequest({
@@ -1019,6 +2497,7 @@ export function serve(opts) {
       if (!(err instanceof HttpError))
         process.stderr.write(`contract-server: ${err?.message ?? err}\n`);
       fail(res, e, cors);
+      if (e.status === 408) req.destroy();
       const outcome = e.code === "unknown-device" && insecure ? insecure : e.code;
       appendAudit({ ...audit, status: e.status, outcome });
     }
@@ -1028,22 +2507,24 @@ export function serve(opts) {
     arm();
     res.on("finish", arm);
     const origin = req.headers.origin;
+    const own = origin !== undefined && selfOrigins.has(origin);
     const cors =
-      origin && origins.has(origin)
+      origin && !own && origins.has(origin)
         ? { "Access-Control-Allow-Origin": origin, Vary: "Origin" }
         : {};
+    let audit = null;
     try {
       if (!hosts.has(String(req.headers.host ?? "").toLowerCase())) {
         throw new HttpError(403, "forbidden-host", "the Host header does not name this server");
       }
-      if (origin !== undefined && !origins.has(origin)) {
+      if (origin !== undefined && !own && !origins.has(origin)) {
         throw new HttpError(403, "forbidden-origin", "this origin is not allowed");
       }
       if (req.method === "OPTIONS" && origin !== undefined) {
         drain(req);
         res.writeHead(204, {
           ...cors,
-          "Access-Control-Allow-Methods": "GET, POST",
+          "Access-Control-Allow-Methods": "GET",
           "Access-Control-Allow-Headers": "Authorization, Content-Type",
           "Access-Control-Max-Age": "600",
           "Cache-Control": "no-store",
@@ -1056,10 +2537,110 @@ export function serve(opts) {
         await servePhone(req, res, url, cors);
         return;
       }
+      if (url.pathname === OFFICE_PATH && (req.method === "GET" || req.method === "HEAD")) {
+        drain(req);
+        if (url.search) throw new HttpError(400, "invalid-query", "the panel takes no query");
+        serveOffice(res, req.method === "HEAD");
+        return;
+      }
+      if (url.pathname === "/favicon.ico" && (req.method === "GET" || req.method === "HEAD")) {
+        drain(req);
+        res.writeHead(204, {
+          "Cache-Control": "max-age=86400",
+          "X-Content-Type-Options": "nosniff",
+        });
+        res.end();
+        return;
+      }
+      if (url.pathname.startsWith(OFFICE_ASSET_PREFIX)) {
+        drain(req);
+        if (req.method !== "GET" && req.method !== "HEAD") {
+          throw new HttpError(405, "method-not-allowed", "use GET", { allow: "GET" });
+        }
+        if (url.search) throw new HttpError(400, "invalid-query", "an asset takes no query");
+        const body = officeAsset(url.pathname.slice(OFFICE_ASSET_PREFIX.length));
+        if (!body) throw new HttpError(404, "not-found", "no such asset");
+        res.writeHead(200, {
+          "Content-Type": "image/png",
+          "Content-Length": body.length,
+          "Cache-Control": "max-age=3600",
+          "X-Content-Type-Options": "nosniff",
+          "Cross-Origin-Resource-Policy": "same-origin",
+          "Content-Security-Policy": "default-src 'none'",
+        });
+        res.end(req.method === "HEAD" ? undefined : body);
+        return;
+      }
+      if (url.pathname === OFFICE_EXCHANGE_PATH) {
+        if (req.method !== "POST" || url.search) {
+          drain(req);
+          throw new HttpError(405, "method-not-allowed", "use POST", { allow: "POST" });
+        }
+        if (!own) {
+          drain(req);
+          throw new HttpError(403, "forbidden-origin", "only the panel page exchanges a code");
+        }
+        if (!/^application\/json(\s*;.*)?$/i.test(String(req.headers["content-type"] ?? ""))) {
+          drain(req);
+          throw new HttpError(415, "unsupported-media-type", "the body must be application/json");
+        }
+        const b = await readBody(req);
+        if (!redeemCode(b?.code)) {
+          throw new HttpError(
+            401,
+            "unauthorized",
+            "the code is unknown, used or expired; run /multi-agent:office-on again",
+          );
+        }
+        send(res, 200, { contractVersion: CONTRACT_VERSION, token });
+        return;
+      }
       if (!authorized(req.headers.authorization, tokenDigest)) {
         throw new HttpError(401, "unauthorized", "a bearer token is required");
       }
+      if (url.pathname === OFFICE_VERSION_PATH || url.pathname === OFFICE_RELOAD_PATH) {
+        drain(req);
+        if (origin !== undefined && !own) {
+          throw new HttpError(403, "forbidden-origin", "only the panel page asks this");
+        }
+        if (url.pathname === OFFICE_VERSION_PATH) {
+          if (req.method !== "GET") {
+            throw new HttpError(405, "method-not-allowed", "use GET", { allow: "GET" });
+          }
+          send(res, 200, {
+            contractVersion: CONTRACT_VERSION,
+            build: officeBuild(),
+            serverStale: serverDigest() !== SERVER_DIGEST,
+          });
+          return;
+        }
+        if (req.method !== "POST") {
+          throw new HttpError(405, "method-not-allowed", "use POST", { allow: "POST" });
+        }
+        // The page already holds the token; a code lets it reload itself onto
+        // the page now installed without the token ever entering a URL.
+        send(res, 200, { contractVersion: CONTRACT_VERSION, ...mintCode() });
+        return;
+      }
+      if (url.pathname === OFFICE_CODE_PATH) {
+        drain(req);
+        if (req.method !== "POST") {
+          throw new HttpError(405, "method-not-allowed", "use POST", { allow: "POST" });
+        }
+        if (origin !== undefined) {
+          throw new HttpError(403, "forbidden-origin", "a page may not mint a panel code");
+        }
+        send(res, 200, { contractVersion: CONTRACT_VERSION, ...mintCode() });
+        return;
+      }
       const { route, params } = match(req.method, url.pathname);
+      // A write, and a read of a transcript, are refused to every page but the
+      // panel this server serves: an allowed origin may read the contract, it
+      // may not drive this machine or read what an agent said.
+      if ((route.write || route.selfOrigin) && origin !== undefined && !own) {
+        throw new HttpError(403, "forbidden-origin", "this origin may not call this route");
+      }
+      if (route.write) audit = { route: `${route.method} ${route.path}`, params, own };
       const q = parseQuery(route, url.searchParams);
       const redact = flag(one(q, "redact")) || origin !== undefined;
       let body = null;
@@ -1073,34 +2654,109 @@ export function serve(opts) {
       } else {
         drain(req);
       }
-      send(res, 200, await route.handle({ q, params, body, redact }), cors);
-    } catch (err) {
-      if (err instanceof HttpError) {
-        fail(res, err, cors);
+      if (audit) audit.confirm = Boolean(body?.confirmToken ?? one(q, "confirm"));
+      if (audit && route.path === "/v1/tools/{name}/call") {
+        audit.argsSha256 = createHash("sha256")
+          .update(JSON.stringify(body?.arguments ?? {}))
+          .digest("hex");
+      }
+      if (route.stream) {
+        serveStream(req, res, route, cors);
         return;
       }
-      process.stderr.write(`contract-server: ${err?.message ?? err}\n`);
-      fail(res, new HttpError(500, "internal", "internal error"), cors);
+      const doc = await route.handle({ q, params, body, redact });
+      if (audit) logAction({ ...audit, status: 200 });
+      send(res, 200, doc, cors);
+    } catch (err) {
+      const e = err instanceof HttpError ? err : new HttpError(500, "internal", "internal error");
+      if (!(err instanceof HttpError))
+        process.stderr.write(`contract-server: ${err?.message ?? err}\n`);
+      if (audit) logAction({ ...audit, status: e.status, error: e.code });
+      fail(res, e, cors);
     }
   });
 
+  /**
+   * GET /v1/activity/stream: the activity document as server-sent events, sent
+   * when it changes and checked every STREAM_POLL_MS, with a comment line as a
+   * heartbeat. Each event re-arms the idle clock, so an open panel keeps the
+   * server up and a closed one lets it stop. At most MAX_STREAMS at once.
+   */
+  const serveStream = (req, res, route, cors) => {
+    if (streams.size >= MAX_STREAMS) {
+      throw new HttpError(429, "too-many-streams", `at most ${MAX_STREAMS} streams at once`);
+    }
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-store",
+      Connection: "keep-alive",
+      "X-Content-Type-Options": "nosniff",
+      "Referrer-Policy": "no-referrer",
+      "X-Contract-Version": CONTRACT_VERSION,
+      ...cors,
+    });
+    let last = null;
+    let busy = false;
+    let lastSent = Date.now();
+    const tick = async () => {
+      if (busy) return;
+      busy = true;
+      try {
+        const doc = await route.handle({});
+        const { generatedAt: _g, ...stable } = doc;
+        const key = JSON.stringify(stable);
+        if (key !== last) {
+          last = key;
+          res.write(`event: activity\ndata: ${JSON.stringify(doc)}\n\n`);
+          lastSent = Date.now();
+          arm();
+        } else if (Date.now() - lastSent >= STREAM_HEARTBEAT_MS) {
+          res.write(": keep-alive\n\n");
+          lastSent = Date.now();
+          arm();
+        }
+      } catch (err) {
+        process.stderr.write(`contract-server: stream: ${err?.message ?? err}\n`);
+        res.write(`event: error\ndata: {"error":"internal"}\n\n`);
+      } finally {
+        busy = false;
+      }
+    };
+    const timer = setInterval(tick, STREAM_POLL_MS);
+    const entry = { res, timer };
+    streams.add(entry);
+    const close = () => {
+      clearInterval(timer);
+      streams.delete(entry);
+    };
+    // The response's close, not the request's: a request emits close as soon
+    // as its (empty) body has been read.
+    res.on("close", close);
+    tick();
+  };
+
   return new Promise((resolve, reject) => {
     server.once("error", reject);
     server.listen(opts.port ?? 0, BIND_HOST, () => {
       const { port } = server.address();
       hosts = new Set([`${BIND_HOST}:${port}`, `localhost:${port}`]);
+      selfOrigins = new Set([`http://${BIND_HOST}:${port}`, `http://localhost:${port}`]);
       const record = {
         contractVersion: CONTRACT_VERSION,
         url: `http://${BIND_HOST}:${port}`,
         port,
         pid: process.pid,
         idleMinutes: opts.idleMinutes ?? DEFAULT_IDLE_MINUTES,
+        maxHours: opts.maxHours ?? DEFAULT_MAX_HOURS,
       };
       const started = new Date();
       startSec = Math.floor(started.getTime() / 1000);
       tokenFile = writeTokenFile({ ...record, token, startedAt: started.toISOString() });
       for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(sig, () => stop(sig));
       arm();
+      const maxHours = opts.maxHours ?? DEFAULT_MAX_HOURS;
+      if (maxHours > 0)
+        lifeTimer = setTimeout(() => stop("lifetime"), Math.round(maxHours * 3600000));
       resolve({ ...record, tokenFile, ...(opts.printToken ? { token } : {}) });
     });
   });
@@ -1116,7 +2772,7 @@ async function main(argv) {
   }
   if (opts.help) {
     process.stdout.write(
-      "Usage: contract-server.mjs [--port N] [--idle-minutes N] [--allow-origin <origin>]... [--print-token]\n",
+      "Usage: contract-server.mjs [--port N] [--idle-minutes N] [--max-hours N] [--allow-origin <origin>]... [--print-token]\n",
     );
     return 0;
   }