@mmerterden/multi-agent-pipeline 20.30.0 → 20.34.0

package/pipeline/contract/types/index.d.ts

@@ -1,8 +1,8 @@
 // Generated by pipeline/contract/build.mjs from pipeline/schemas/*.schema.json.
 // Do not edit: change the schema and run `node pipeline/contract/build.mjs --write`.
 
-export type ContractVersion = "1.4.0";
-export type SurfaceId = "runs" | "run" | "commands" | "questions" | "issues" | "worktrees" | "launch-spec" | "repos" | "launch" | "answer" | "run-log" | "resume" | "kill" | "gc" | "autopilot" | "autopilot-off" | "phone-runs" | "phone-run" | "phone-answer" | "phone-launch" | "autopilot-on" | "steer" | "activity" | "activity-stream" | "agent-chat" | "routines" | "routine-delete" | "stack" | "stack-set" | "ledger" | "run-results" | "run-evidence" | "review-verdict" | "issue-maturity" | "prs" | "tools" | "tool-call" | "service-confluence" | "service-crashlytics" | "service-figma" | "permissions";
+export type ContractVersion = "1.6.0";
+export type SurfaceId = "runs" | "run" | "commands" | "questions" | "issues" | "worktrees" | "launch-spec" | "repos" | "repo-add" | "repo-remove" | "launch" | "answer" | "run-log" | "resume" | "kill" | "gc" | "autopilot" | "autopilot-off" | "phone-runs" | "phone-run" | "phone-answer" | "phone-launch" | "autopilot-on" | "steer" | "activity" | "activity-stream" | "agent-chat" | "routines" | "routine-delete" | "jobs" | "job-start" | "stack" | "stack-set" | "ledger" | "system" | "prune-logs" | "settings" | "settings-set" | "credentials" | "memory" | "run-results" | "run-evidence" | "review-verdict" | "issue-maturity" | "prs" | "tools" | "tool-call" | "service-confluence" | "service-crashlytics" | "service-figma" | "permissions";
 
 /** What `runs-index.mjs --json` prints: every run under the log root and the unattended log root (one record per task id), grouped per status/SKILL.md 3b. Fields are only ever added - a decoder ignores keys it does not know. `--redact` drops every x-sensitivity local field (and `logsRoot`) and scrubs the free text in the title, `now`, sub-step names, task subjects and the pending question. */
 export interface RunsIndex {
@@ -51,6 +51,8 @@ export interface RunsIndexRun {
   };
   estUsd: number;
   unlockedWrites: number;
+  /** agent-state.json mode as the run recorded it (analysis, test-gen, review...), so a reader can name the command; null when none was recorded. */
+  mode?: string | null;
   /** autopilot when the run is in autopilot mode; analysis for an analysis-family run (agent-state mode analysis, or a tracker with no agent state); development otherwise. Added in 1.2.0. */
   runType?: "analysis" | "development" | "autopilot";
   /** The issue summary Phase 0 recorded (agent-state title), else the input the run was launched with (launchRequest.input), else null. Scrubbed under --redact. Added in 1.2.0. */
@@ -64,6 +66,27 @@ export interface RunsIndexRun {
     subject: string;
     activeForm: string | null;
   } | null;
+  /** Where the work came from: a Jira key, a GitHub issue (owner/repo#N) or free text; a GitHub issue that got a Jira has both. Null when the run recorded neither. Added in 1.3.0. */
+  source?: {
+    kind: "jira" | "github" | "text";
+    jira: string | null;
+    issue: string | null;
+  } | null;
+  /** The pull request's number, from the state or its URL; the URL itself is prUrl (local). Added in 1.3.0. */
+  prNumber?: number | null;
+  /** Where Phase 5 sent the report, per adapter (state.channelResults); empty before then. Added in 1.3.0. */
+  channels?: Array<{
+    channel: "pr" | "jira" | "confluence" | "wiki" | "issue";
+    status: "posted" | "skipped" | "failed";
+  }>;
+  /** The address each adapter posted to, https only; dropped from a redacted answer. Added in 1.3.0. */
+  channelUrls?: {
+    pr?: string;
+    jira?: string;
+    confluence?: string;
+    wiki?: string;
+    issue?: string;
+  };
 }
 
 export interface RunsIndexQuestion {
@@ -490,7 +513,7 @@ export interface AutopilotOff {
   stoppedInFlight: boolean;
 }
 
-/** What GET /v1/repos returns and `launch-request.mjs repos` prints: the repositories POST /v1/launch?repo= accepts, by real path. source autopilot is a configured autopilot repo (config.json repos[], named by nameWithOwner); registered is one added with `launch-request.mjs register-repo` (launch-repos.json, named by its directory). path is dropped under redact. */
+/** What GET /v1/repos returns and `launch-request.mjs repos` prints: the repositories POST /v1/launch?repo= accepts, by real path. source autopilot is a configured autopilot repo (config.json repos[], named by nameWithOwner); registered is one added with `launch-request.mjs register-repo` (launch-repos.json, named by its directory). path is dropped under redact. With --all (?all=1): suggested lists checkouts earlier runs worked in that launch does not accept yet, and missing lists registered entries that are no longer a directory; each carries an id that POST /v1/repos and DELETE /v1/repos/{id} take. */
 export interface Repos {
   contractVersion: string;
   repos: Array<{
@@ -498,6 +521,97 @@ export interface Repos {
     name: string;
     source: "autopilot" | "registered";
   }>;
+  suggested?: Array<{
+    id: string;
+    path?: string;
+    name: string;
+  }>;
+  missing?: Array<{
+    id: string;
+    path?: string;
+    name: string;
+  }>;
+}
+
+/** The body of POST /v1/repos. The first request names suggestion (an id from GET /v1/repos?all=1) or path (an absolute path to a git checkout); the second sends only confirmToken. */
+export interface RepoRequest {
+  contractVersion: string;
+  suggestion?: string;
+  path?: string;
+  confirmToken?: string;
+}
+
+/** What POST /v1/repos and DELETE /v1/repos/{id} return. Without a token: preview (the repository's name) with confirmToken and expiresAt. With it: registered or removed, by name. Paths never leave the server here. */
+export interface RepoChange {
+  contractVersion: string;
+  preview?: {
+    name: string;
+  };
+  confirmToken?: string;
+  expiresAt?: string;
+  registered?: {
+    name: string;
+  };
+  removed?: {
+    name: string;
+  };
+}
+
+/** The catalog of jobs the office can start (office-jobs.json), read by job-launch.mjs and served by GET /v1/jobs. */
+export interface OfficeJobs {
+  $schema?: string;
+  contractVersion: string;
+  description?: string;
+  jobs: Array<{
+    id: string;
+    command: string;
+    role: string;
+    team: boolean;
+    launch?: "development" | "analysis" | "autopilot";
+    available?: boolean;
+    reason?: string | null;
+    params: Array<{
+      name: string;
+      kind: "work-item" | "pull-request" | "branch" | "run-id" | "jira-key" | "github-issue" | "enum" | "repo-path";
+      values?: Array<string>;
+      required: boolean;
+    }>;
+    writes: "none" | "branch" | "branch-pr" | "pr-comments" | "issue-comment";
+  }>;
+}
+
+/** The body of POST /v1/jobs. The first request names jobId (from GET /v1/jobs), repo (a name from GET /v1/repos or its path) and args (by parameter name), plus answers for a pipeline run; the second sends only confirmToken. */
+export interface JobRequest {
+  contractVersion: string;
+  jobId?: string;
+  repo?: string;
+  args?: {
+    [key: string]: string;
+  };
+  answers?: Record<string, unknown>;
+  confirmToken?: string;
+}
+
+/** What POST /v1/jobs returns. Without a token: preview (the job, the role that does it, team or solo, the repository by name, the exact prompt the session receives and what it writes outside the machine) with confirmToken and expiresAt. With it: started, the session the server began. */
+export interface JobChange {
+  contractVersion: string;
+  preview?: {
+    jobId: string;
+    role: string;
+    team: boolean;
+    repo: string;
+    prompt: string;
+    writes: "none" | "branch" | "branch-pr" | "pr-comments" | "issue-comment";
+  };
+  confirmToken?: string;
+  expiresAt?: string;
+  started?: {
+    sessionId: string;
+    jobId: string;
+    role: string;
+    team: boolean;
+    repo: string;
+  };
 }
 
 /** What GET /v1/activity returns and `activity-snapshot.mjs --json` prints, and what each GET /v1/activity/stream event carries: one room per repository, one table per run (its team; a session no run claims sits at a table of its own), one seat per agent seen in the recent window, the orchestrator at the head. Derived from disk on every call. No field is machine-local: there are no paths, seat labels come from allow-listed fields only (tool name, file basename, sidecar description), and every free-text string has been through the redactor, so the redacted and the full view are the same document. */
@@ -526,8 +640,12 @@ export interface Activity {
 
 export interface ActivityTable {
   id: string;
-  /** run: a pipeline run; session: a session no run claims (outside the pipeline); unmatched: a session more than one run could claim, kept apart rather than guessed. */
-  kind: "run" | "session" | "unmatched";
+  /** run: a pipeline run; session: a session no run claims (outside the pipeline); unmatched: a session more than one run could claim, kept apart rather than guessed. solo: a session the office started for a one-person job, seated at a desk. */
+  kind: "run" | "session" | "solo" | "unmatched";
+  /** The command the table runs, for its room sign: /multi-agent, /multi-agent:analysis, /multi-agent:test-gen. Null for a session no command owns. */
+  command: string | null;
+  /** Which pipeline the table runs: /multi-agent (development), /multi-agent:analysis, or an autopilot run. Null for a session no pipeline owns. The office names the room after it. */
+  runType: "development" | "analysis" | "autopilot" | null;
   taskId: string | null;
   title: string | null;
   host: "claude" | "copilot" | "codex";
@@ -543,6 +661,9 @@ export interface ActivityTable {
     /** The last phase id, for an n of last display. */
     last: number;
   } | null;
+  /** The task in progress in the phase in progress, from the mirrored task list. */
+  currentTask: string | null;
+  progress: number | null;
   now: string | null;
   status: string | null;
   waitingForYou: boolean;
@@ -570,6 +691,13 @@ export interface ActivityTable {
   branch: string | null;
   phaseHistory: Array<{
     id: number | null;
+    /** How far the phase is, from its mirrored task list; null when it has none. */
+    progress: number | null;
+    /** The phase's task list as the host task widget shows it (mirrored by phase-tracker.sh task), redacted and cut short. */
+    tasks: Array<{
+      subject: string;
+      status: "pending" | "in_progress" | "completed";
+    }>;
     name: string;
     status: string;
     startedAt: string | null;
@@ -582,9 +710,45 @@ export interface ActivityTable {
   /** The last seat of an earlier phase, for drawing the handoff. */
   previousHolder: string | null;
   seats: Array<ActivitySeat>;
+  /** The office job a session was started for (run tables carry none). */
+  job?: null | {
+    id: string;
+    role: string;
+    team: boolean;
+  };
+  /** Where the run's work came from, for the table sign: a Jira key, a GitHub issue or free text. Null for a session or a run that recorded neither. */
+  source: {
+    kind: "jira" | "github" | "text";
+    jira: string | null;
+    issue: string | null;
+  } | null;
+  /** The pull request the run opened, by number only. */
+  pr: {
+    number: number;
+  } | null;
+  /** What a waiting run waits for: a step it paused at (the run's waitingFor), or terminal when its session holds a question open in its own window. */
+  waitingFor: "maturity" | "user-channels-choice" | "local-test" | "attended-reply" | "question" | "terminal" | null;
+  /** Where the run's report went, per adapter, for the run window; empty for a session or before Phase 5. */
+  channels: Array<{
+    channel: "pr" | "jira" | "confluence" | "wiki" | "issue";
+    status: "posted" | "skipped" | "failed";
+  }>;
 }
 
 export interface ActivitySeat {
+  /** The desk's own task list from its transcript (TaskCreate / TaskUpdate / TodoWrite), phase tiles left out, redacted and cut short. */
+  tasks: Array<{
+    subject: string;
+    status: "pending" | "in_progress" | "completed";
+  }>;
+  /** The desk's last MCP calls, newest last: server, tool, whether it is still running, failed or answered, and how long it took. No input or result. */
+  mcp: Array<{
+    server: string;
+    tool: string;
+    state: "running" | "ok" | "error";
+    ms: number | null;
+    at: string | null;
+  }>;
   id: string;
   sessionId: string | null;
   /** null for the session's own (orchestrator) desk. */
@@ -837,6 +1001,105 @@ export interface LedgerWindow {
   byPhase: Array<LedgerRow>;
 }
 
+/** What GET /v1/system returns and `system-status.mjs --json` prints: CPU load, memory, free disk and what the pipeline itself uses. Numbers only: no path, process argument, user name or host name. A value that could not be measured is null, never 0. */
+export interface SystemStatus {
+  contractVersion: string;
+  generatedAt: string;
+  cpu: {
+    cores: number;
+    /** Busy share of all cores over a short sampling window. */
+    usage: number | null;
+    /** Load average over 1, 5 and 15 minutes. */
+    load: Array<number>;
+  };
+  memory: {
+    totalMb: number;
+    /** Total minus what the OS reports free; on macOS that counts the file cache as used. */
+    usedMb: number;
+  };
+  disk: {
+    home: SystemStatusDisk;
+    /** The disk the run logs live on, when it is not the home disk; null when it is the same disk. */
+    logs: SystemStatusDisk;
+  };
+  pipeline: {
+    /** Claude Code processes running. */
+    sessions: number | null;
+    /** multi-agent-toolkit server processes running. */
+    toolkit: number | null;
+    /** Their resident memory together. */
+    rssMb: number | null;
+    /** Size of the run log folder; null when it could not be measured in time. */
+    logsMb: number | null;
+  };
+  /** disk-low: under 10 percent of the home disk is free. cpu-busy: the 5-minute load is above the core count. */
+  warnings: (Array<"disk-low" | "cpu-busy">);
+}
+
+export type SystemStatusDisk = {
+  totalMb: number;
+  freeMb: number;
+} | null;
+
+/** What GET /v1/credentials returns and `office-credentials.mjs --json` prints: for each credential the pipeline knows by logical name, whether the store holds it and, with probe, whether its service accepted it. Never a value: lib/credential-inventory.sh reads each through the store with stdout discarded. Renewal stays in the terminal (/multi-agent:setup). */
+export interface OfficeCredentials {
+  contractVersion: string;
+  generatedAt: string;
+  probed: boolean;
+  /** False when the inventory could not run on this host. */
+  available: boolean;
+  credentials: Array<{
+    logical: string;
+    state: "present" | "mapped-but-missing" | "unmapped";
+    reachability: "not-probed" | "reachable" | "auth-rejected" | "unreachable" | "no-host-configured" | "well-formed" | "not-probeable" | "malformed" | "no-credential" | "probe-error" | "server-error" | "tier-1-ready" | "tier-2-ready" | "tier-1-no-grant" | "unknown";
+    capability: string | null;
+  }>;
+}
+
+/** What GET /v1/memory returns and `office-memory.mjs --json` prints: per repository, the code graph's age and size and how many learnings, past review findings and session notes the learning loop holds, with the newest learnings redacted and cut short. An empty shelf is reported, never left out. */
+export interface OfficeMemory {
+  contractVersion: string;
+  generatedAt: string;
+  shelves: Array<{
+    repo: string;
+    graph: null | {
+      builtAt: string | null;
+      ageDays: number;
+      sizeKb: number;
+    };
+    learnings: number;
+    findings: number;
+    sessionNotes: number;
+    recent: Array<{
+      kind: string | null;
+      statement: string;
+      at: string | null;
+    }>;
+    lastWrite: string | null;
+  }>;
+}
+
+/** What POST /v1/prune-logs returns. The preview (body {olderThanDays}) is prune-logs.sh's dry run for that age with a confirm token; the confirmation (body {confirmToken}) runs it again with the same age and --yes. The audit trail, the metrics corpus and task counters are never removed, and a folder written in the last minutes is spared. */
+export interface PruneLogs {
+  contractVersion: string;
+  olderThanDays: 7 | 30 | 90;
+  applied: boolean;
+  count: number;
+  freedMb: number;
+  /** project/task folders, at most 200 listed. */
+  folders: Array<string>;
+  confirmToken?: string;
+  expiresAt?: string;
+}
+
+/** The body of POST /v1/prune-logs. Step 1 names the age in days (7, 30 or 90); step 2 sends only the confirmToken step 1 returned. */
+export interface PruneLogsRequest {
+  contractVersion: string;
+  olderThanDays?: 7 | 30 | 90;
+  /** The confirmToken the preview returned. Single use, bound to the route. */
+  confirmToken?: string;
+}
+
 /** What GET /v1/runs/{id}/results returns (`run-results.mjs <id> --json`): what a run produced, read from its own files. diff from agent-state diffRisk or .review-diff.txt; findings from triage-output.json or agent-state review; tests from the test-summary gate and uiTest; evidence the screenshot names under .pipeline/evidence; analysis the documents an analysis run wrote. A part with no source is null. Text is scrubbed and redacted; paths are reduced to file names. */
 export interface RunResults {
   contractVersion: string;
@@ -921,6 +1184,8 @@ export interface Prs {
   contractVersion: string;
   items: Array<{
     source: "github" | "bitbucket";
+    /** The GitHub login the pull request was listed under, when gh is logged in to more than one account (personal and corporate). Null for Bitbucket. */
+    account?: string | null;
     repo: string;
     number: number;
     title: string;
@@ -973,6 +1238,8 @@ export interface Tools {
     allowed: boolean;
     reason: string | null;
   }>;
+  /** The exact toolkit version the panel starts: the registration's own when it names one, else the version the install recorded from the release. */
+  version?: string | null;
 }
 
 /** The body of POST /v1/tools/{name}/call: the tool's arguments, which must satisfy its inputSchema. At most 64 KiB. */
@@ -1030,10 +1297,41 @@ export interface Permissions {
 /** Every non-2xx body contract-server.mjs sends, on the desktop and the phone routes alike. `error` is a fixed code a client switches on; `message` is for a person and names no path, host or token. `errors` lists schema or rule violations for invalid-body and invalid-request; `supported` lists the majors ?v= accepts for unsupported-version. run-active and not-resumable answer POST /v1/runs/{id}/resume; confirm-expired and confirm-mismatch answer the confirming request of a kill or gc. */
 export interface ContractError {
   contractVersion: string;
-  error: "unauthorized" | "forbidden-host" | "forbidden-origin" | "not-found" | "method-not-allowed" | "invalid-query" | "unsupported-version" | "unsupported-media-type" | "invalid-body" | "invalid-request" | "no-launch-shape" | "not-waiting" | "wrong-question" | "wrong-arity" | "not-an-option" | "state-moved" | "unsigned" | "unknown-device" | "revoked-device" | "bad-signature" | "stale-request" | "replayed" | "replay-store-full" | "unknown-verb" | "forbidden-scope" | "launch-disabled" | "repo-not-allowed" | "run-active" | "not-resumable" | "confirm-expired" | "confirm-mismatch" | "unattended-profile-missing" | "workspace-not-trusted" | "no-selection" | "repo-not-configured" | "invalid-config" | "not-installed" | "repo-ambiguous" | "unreadable-settings" | "not-removable" | "not-steerable" | "too-many-streams" | "no-review" | "upstream-failed" | "tool-not-allowed" | "busy" | "review-incomplete" | "host-not-allowed" | "internal";
+  error: "unauthorized" | "forbidden-host" | "forbidden-origin" | "not-found" | "method-not-allowed" | "invalid-query" | "unsupported-version" | "unsupported-media-type" | "invalid-body" | "invalid-request" | "no-launch-shape" | "not-waiting" | "wrong-question" | "wrong-arity" | "not-an-option" | "state-moved" | "unsigned" | "unknown-device" | "revoked-device" | "bad-signature" | "stale-request" | "replayed" | "replay-store-full" | "unknown-verb" | "forbidden-scope" | "launch-disabled" | "repo-not-allowed" | "run-active" | "not-resumable" | "confirm-expired" | "confirm-mismatch" | "unattended-profile-missing" | "workspace-not-trusted" | "no-selection" | "repo-not-configured" | "invalid-config" | "not-installed" | "repo-ambiguous" | "unreadable-settings" | "not-removable" | "not-steerable" | "too-many-streams" | "no-review" | "upstream-failed" | "tool-not-allowed" | "busy" | "review-incomplete" | "host-not-allowed" | "internal" | "unknown-job" | "command-not-installed" | "invalid-repo" | "invalid-args" | "room-busy" | "sandbox-unavailable" | "launch-failed" | "guard-missing" | "name-taken" | "already-registered" | "not-registered";
   message: string;
   errors?: Array<string>;
   supported?: Array<number>;
   /** What fixes the refusal: for unattended-profile-missing the installer step that writes the unattended permission profile; for workspace-not-trusted opening Claude Code once in the repository to accept the trust prompt (the path is left out under redact). */
   remedy?: string;
 }
+
+/** What GET /v1/settings returns and POST /v1/settings returns after a change: the output language, the fable rung and model routing. A preview (the first POST) adds the change it would make and a confirmToken. */
+export interface OfficeSettings {
+  contractVersion: string;
+  language: "en" | "tr";
+  /** Whether the fable rung is in play. */
+  model: "on" | "off";
+  /** Whether model routing is on. */
+  route: "on" | "off";
+  change?: {
+    setting: "language" | "model" | "route";
+    from: string;
+    to: string;
+    /** Present when turning routing on brings back a saved free provider chain: the confirmation names it. */
+    freeChain?: {
+      enabled: true;
+      allowTraining: boolean;
+    };
+  };
+  confirmToken?: string;
+  expiresAt?: string;
+}
+
+/** The body of POST /v1/settings. Step 1 names the setting and its new value; step 2 sends only the confirmToken step 1 returned. */
+export interface OfficeSettingsRequest {
+  contractVersion: string;
+  setting?: "language" | "model" | "route";
+  value?: "en" | "tr" | "on" | "off";
+  /** The confirmToken the preview returned. Single use, bound to the route. */
+  confirmToken?: string;
+}

package/pipeline/lib/bg-launch.mjs

@@ -0,0 +1,106 @@
+/**
+ * bg-launch.mjs  -  start one unattended `claude --bg` session.
+ *
+ * The autopilot runner and the office both start background sessions, and
+ * both go through here so there is one way to do it: the caller's
+ * precondition (the unattended sandbox check) runs first and a failing one
+ * starts nothing; the binary is started without a shell, with the argv and
+ * environment the caller built; `claude --bg` prints the session and returns,
+ * so a bounded synchronous wait is enough.
+ *
+ * @module pipeline/lib/bg-launch
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+
+import { resolveClaudeBin } from "./claude-sessions.mjs";
+
+export const LAUNCH_TIMEOUT_MS = 2 * 60 * 1000;
+
+/**
+ * @param {{argv: string[], cwd: string, env: Record<string,string|undefined>,
+ *   precondition?: (o: {cwd: string}) => {ok: boolean, reason?: string},
+ *   bin?: string, timeoutMs?: number}} args
+ * @returns {{status: number|null, stdout?: string, stderr?: string, error?: Error, blocked?: string}}
+ */
+export function startBackground({
+  argv,
+  cwd,
+  env,
+  precondition,
+  bin = resolveClaudeBin(env),
+  timeoutMs = LAUNCH_TIMEOUT_MS,
+}) {
+  if (!Array.isArray(argv) || !argv.every((a) => typeof a === "string")) {
+    throw new TypeError("argv is a list of strings");
+  }
+  if (precondition) {
+    const check = precondition({ cwd });
+    if (!check.ok) return { status: 1, stderr: check.reason, blocked: check.reason };
+  }
+  return spawnSync(bin, argv, {
+    cwd,
+    env,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: timeoutMs,
+    shell: false,
+  });
+}
+
+/**
+ * startBackground for a caller that must not block, such as the contract
+ * server answering other requests meanwhile. It settles when the launcher
+ * exits rather than when its output pipes close, and keeps draining them
+ * afterwards, so a process left holding a pipe never writes into a closed one.
+ *
+ * @param {Parameters<typeof startBackground>[0]} args
+ * @returns {Promise<ReturnType<typeof startBackground>>}
+ */
+export function startBackgroundAsync({
+  argv,
+  cwd,
+  env,
+  precondition,
+  bin = resolveClaudeBin(env),
+  timeoutMs = LAUNCH_TIMEOUT_MS,
+}) {
+  if (!Array.isArray(argv) || !argv.every((a) => typeof a === "string")) {
+    throw new TypeError("argv is a list of strings");
+  }
+  if (precondition) {
+    const check = precondition({ cwd });
+    if (!check.ok)
+      return Promise.resolve({ status: 1, stderr: check.reason, blocked: check.reason });
+  }
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const child = spawn(bin, argv, { cwd, env, stdio: ["ignore", "pipe", "pipe"], shell: false });
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      for (const s of [child.stdout, child.stderr]) {
+        s?.removeAllListeners("data");
+        s?.resume();
+      }
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      done({
+        status: null,
+        stdout,
+        stderr,
+        error: new Error("the launcher timed out"),
+        timedOut: true,
+      });
+    }, timeoutMs);
+    child.stdout.setEncoding("utf-8").on("data", (d) => (stdout += d));
+    child.stderr.setEncoding("utf-8").on("data", (d) => (stderr += d));
+    child.on("error", (error) => done({ status: null, stdout, stderr, error }));
+    child.on("exit", (status) => setImmediate(() => done({ status, stdout, stderr })));
+  });
+}

package/pipeline/lib/code-digest.mjs

@@ -0,0 +1,49 @@
+/**
+ * code-digest.mjs  -  one digest for the code a long-lived server loaded.
+ *
+ * The contract server imports modules from scripts/ and lib/, and an ES module
+ * keeps the copy it loaded at start. A digest of the server file alone misses
+ * a release that changed only an imported module, so this hashes every .mjs
+ * file in the server's directory and in the lib/ directory beside it, by name
+ * and content. office-control compares it with the digest the running server
+ * recorded; the server compares it with its own start-up value for
+ * /office/version.
+ *
+ * @module pipeline/lib/code-digest
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * @param {string} scriptsDir the directory holding contract-server.mjs
+ * @returns {string|null} 16 hex characters, or null when nothing could be read
+ */
+export function codeDigest(scriptsDir) {
+  const hash = createHash("sha256");
+  let read = 0;
+  for (const dir of [scriptsDir, join(dirname(scriptsDir), "lib")]) {
+    let names;
+    try {
+      names = readdirSync(dir)
+        .filter((n) => n.endsWith(".mjs"))
+        .sort();
+    } catch {
+      continue;
+    }
+    for (const n of names) {
+      try {
+        const body = readFileSync(join(dir, n));
+        hash
+          .update(`${dir === scriptsDir ? "scripts" : "lib"}/${n}\0`)
+          .update(body)
+          .update("\0");
+        read += 1;
+      } catch {
+        // A file that vanished mid-read changes the digest by its absence.
+      }
+    }
+  }
+  return read ? hash.digest("hex").slice(0, 16) : null;
+}

package/pipeline/lib/credential-resolve.mjs

@@ -10,7 +10,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { execFile, spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -27,7 +27,7 @@ export function resolveToken(name, envVar) {
     try {
       const key = JSON.parse(readFileSync(prefsPath, "utf8"))?.global?.keychainMapping?.[name];
       if (key) {
-        const r = spawnSync("bash", [store, "get", key], { encoding: "utf8" });
+        const r = spawnSync("bash", [store, "get", key], { encoding: "utf8", timeout: 10_000 });
         const token = (r.stdout || "").trim();
         if (r.status === 0 && token) return token;
       }
@@ -37,3 +37,43 @@ export function resolveToken(name, envVar) {
   }
   return process.env[envVar] || null;
 }
+
+/**
+ * resolveToken for a request path: the store is read without blocking the
+ * event loop and given a deadline, so a store waiting on an unlock prompt
+ * yields "no token" instead of stalling the caller.
+ *
+ * @param {string} name
+ * @param {string} envVar
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<string|null>}
+ */
+export async function resolveTokenAsync(
+  name,
+  envVar,
+  { timeoutMs = 5000, env = process.env } = {},
+) {
+  const home = env.HOME || homedir();
+  const store = join(home, ".claude", "lib", "credential-store.sh");
+  const prefsPath = env.MULTI_AGENT_PREFS || join(home, ".claude", "multi-agent-preferences.json");
+  if (existsSync(store) && existsSync(prefsPath)) {
+    let key = null;
+    try {
+      key = JSON.parse(readFileSync(prefsPath, "utf8"))?.global?.keychainMapping?.[name] ?? null;
+    } catch {
+      key = null;
+    }
+    if (key) {
+      const token = await new Promise((resolve) => {
+        execFile(
+          "bash",
+          [store, "get", key],
+          { encoding: "utf8", timeout: timeoutMs, killSignal: "SIGKILL", env },
+          (err, stdout) => resolve(err ? "" : String(stdout || "").trim()),
+        );
+      });
+      if (token) return token;
+    }
+  }
+  return env[envVar] || null;
+}