@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/contract/README.md

@@ -0,0 +1,126 @@
+# Client contract kit
+
+What a client (the macOS toolbox, a web page, a script) needs to read the
+pipeline's state and start or answer a run without a terminal conversation.
+Nothing in here is a UI and nothing here runs on its own.
+
+| File | What it is |
+|------|------------|
+| `manifest.json` | Every surface: its CLI invocation, its HTTP route, its schema and version. |
+| `../schemas/*.schema.json` | The schemas. The kit points at them; it never copies them. |
+| `types/index.d.ts` | TypeScript declarations generated from those schemas by `build.mjs`. |
+| `fixtures/*.json` | Real producer output for every state a client renders, generated by `build.mjs`. |
+| `frozen/toolbox.json` | The fields the macOS toolbox decodes today, held by `test/toolbox-compat.test.mjs`. |
+| `CHANGELOG.md` | What changed in the contract, by contract version. |
+
+`node pipeline/contract/build.mjs --write` regenerates the types and fixtures;
+`--check` fails on drift. `npm pack` runs `--write` first, so a published kit
+always matches its schemas.
+
+From the npm package: `@mmerterden/multi-agent-pipeline/contract` resolves to
+the types (and to `manifest.json` at runtime), `/contract/*` to any kit file
+and `/schemas/*` to a schema.
+
+## Two carriers, one contract
+
+Every surface is reachable two ways, and for the same input both print the
+same bytes (`test/contract-parity.test.mjs`):
+
+1. **CLI.** The scripts under `pipeline/scripts/` (installed: `~/.claude/scripts/`)
+   print JSON on stdout. `--redact` drops every field a schema marks
+   `x-sensitivity: local`.
+2. **HTTP.** `contract-server.mjs`, started on demand with `/multi-agent:serve`
+   or by the client itself. Routes are in `manifest.json`; `?redact=1` is
+   `--redact`.
+
+| Surface | CLI | HTTP |
+|---------|-----|------|
+| Runs | `runs-index.mjs --json [--group G] [--redact]` | `GET /v1/runs` |
+| One run | `runs-index.mjs --json --task-id ID` | `GET /v1/runs/{id}` |
+| Commands | `commands.mjs --json` | `GET /v1/commands` |
+| Run questions | `launch-request.mjs questions` | `GET /v1/questions` |
+| Assigned issues | `issues.mjs --json [--source S] [--project K] [--max N]` | `GET /v1/issues` |
+| Worktrees | `worktrees.mjs --json [--measure] [--redact]` | `GET /v1/worktrees` |
+| Launch shape | `launch-request.mjs spec` | `GET /v1/launch-spec` |
+| Start a run | write the request file, then `launch-request.mjs plan FILE --repo P --session-id U [--channel phone]` | `POST /v1/launch?repo=P` |
+| Answer a question | `answer-question.mjs STATE --question Q --answer IDS` | `POST /v1/runs/{id}/answer` |
+
+Starting a run is always the client's act. `POST /v1/launch` validates the
+request, writes it (0600) and returns the argv, environment and working
+directory from `launch.json`; it never starts `claude`. Spawn the argv without
+a shell. `launch.json` is marked `verified: false` until a live launch trial, so
+treat the shape as provisional.
+
+The run starts with no permission prompts, so its input is held to a shape: a
+Jira key, a GitHub issue URL, `repo#N`, `#N`, or a Jira URL on the configured
+host passes as it is; free text (desktop only) becomes one quoted argument; a
+newline, a control character, a leading `-` or a first token that is a pipeline
+op or mode keyword is refused (`launch-request.schema.json`). `repo` must be a
+configured autopilot repo or one registered with
+`launch-request.mjs register-repo <path>`, else `403 repo-not-allowed`.
+
+To answer, read `pendingQuestion` from the run (present when `waitingFor` is
+`question`) and send its `id` with one or more of its `options[].id`. Anything
+else is refused, and a run that has moved to another question refuses an
+answer to the old one.
+
+## Talking to the server
+
+- It listens on `127.0.0.1` only, on the port its ready line names, and refuses
+  any other `--host`.
+- The ready line (stdout, one JSON object) names `tokenFile`, a 0600 file under
+  `~/.claude/logs/multi-agent/contract-server/` holding the token. A client
+  that spawned the server can pass `--print-token` to get it on the ready line.
+- Every request sends `Authorization: Bearer <token>` and a `Host` of
+  `127.0.0.1:<port>` or `localhost:<port>`.
+- A browser page is allowed only from an origin passed with `--allow-origin`;
+  CORS is off without one. A request carrying an `Origin` is always served
+  redacted.
+- Bodies are JSON, at most 64 KiB, and must satisfy the route's schema.
+- Errors follow `contract-error.schema.json`; switch on `error`, never on
+  `message`.
+- The server exits after 15 idle minutes (`--idle-minutes`) or on SIGTERM. It
+  is never a service; start it when you need it.
+
+A client that relays anything off this machine uses `redact=1` (or
+`--redact`) for every read.
+
+## Phone routes
+
+A phone does not use the bearer token. It holds an Ed25519 key enrolled locally
+with `phone-devices.mjs add` and signs every request; `manifest.json` `phone`
+names the headers, the signed fields, the 60 second window and the scopes, and
+`phone-signed-request.schema.json` describes the signed text.
+
+| Surface | Scope | HTTP |
+|---------|-------|------|
+| Runs, redacted | `read` | `GET /v1/phone/runs` |
+| One run, redacted | `read` | `GET /v1/phone/runs/{id}` |
+| Answer a question | `answer` | `POST /v1/phone/runs/{id}/answer` |
+| Queue a launch (off until `phone-devices.mjs launch on`) | `launch` | `POST /v1/phone/launch?repo=P` |
+
+The bearer token does not open these routes and a signature opens no other
+route. Responses are always redacted; `redact=0` is refused. There is no pause,
+resume, stop, steer, shell, prompt, run, merge or ready verb; each is `404
+unknown-verb`. Threat model, transport and residual risks:
+`multi-agent-refs/features/phone-api.md`.
+
+## Versioning and breaking changes
+
+The kit carries one `contractVersion` (`manifest.json`, and the
+`X-Contract-Version` header on every response); each surface also stamps its
+own version in its output.
+
+- **Adding** a field, a surface, a query parameter or an error code is a
+  **minor** bump. Decoders ignore keys they do not know, so nothing breaks.
+- **Removing** or renaming a field, changing a field's type, narrowing what a
+  request accepts, or changing what an error code means is a **major** bump.
+  `frozen/toolbox.json` makes the toolbox's fields fail a test before such a
+  change can land by accident.
+- **After a major bump the previous major stays served for one minor**,
+  selected with `?v=<major>` on any route. The minor after that removes it.
+  `?v=` with a major the server does not serve is a 400 `unsupported-version`
+  whose `supported` lists the ones it does. Without `?v=` the current major is
+  served.
+- Every version change gets a section in `CHANGELOG.md` saying what a client
+  has to do.

package/pipeline/contract/build.mjs

@@ -0,0 +1,427 @@
+#!/usr/bin/env node
+/**
+ * @file build.mjs  -  generate the client kit's TypeScript declarations and
+ * fixtures from the things they describe.
+ *
+ * Two outputs, both derived, both checked in so a reader of the repository
+ * sees what a client gets:
+ *
+ *   types/index.d.ts  one exported type per schema manifest.json lists, read
+ *                     from pipeline/schemas/ (the single copy of each schema);
+ *   fixtures/*.json   what the producers print for a fixed set of runs, one
+ *                     per state a client renders, made by calling the same
+ *                     functions the CLI and contract-server.mjs call.
+ *
+ * `--write` regenerates both (package.json prepack runs it, so a packed kit
+ * never carries stale types). `--check` regenerates in memory and exits 1
+ * naming every file that differs; test/contract-kit.test.mjs runs it.
+ *
+ * The schema-to-TypeScript translation covers the subset the contract schemas
+ * use: type (and type unions), enum, const, properties/required,
+ * additionalProperties, items, anyOf/oneOf and local $defs references.
+ * Conditionals (if/then) narrow nothing TypeScript can express and are left
+ * to the schema. Zero dependencies (ADR-0004).
+ *
+ * Usage:
+ *   node pipeline/contract/build.mjs --write | --check
+ *
+ * Exit: 0 written or up to date, 1 drift found by --check, 2 usage error.
+ */
+
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const KIT = fileURLToPath(new URL(".", import.meta.url));
+const MANIFEST = JSON.parse(readFileSync(join(KIT, "manifest.json"), "utf8"));
+const SCHEMAS = join(KIT, MANIFEST.schemasDir);
+
+// ---------------------------------------------------------------------------
+// TypeScript declarations
+
+const pascal = (s) =>
+  s
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join("");
+
+export const typeNameFor = (file) => pascal(file.replace(/\.schema\.json$/, ""));
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const key = (k) => (IDENT.test(k) ? k : JSON.stringify(k));
+const literal = (v) => JSON.stringify(v);
+
+function doc(text, pad) {
+  if (!text) return "";
+  const clean = String(text).replace(/\*\//g, "* /").replace(/\s+/g, " ").trim();
+  return `${pad}/** ${clean} */\n`;
+}
+
+function tsType(node, ctx, pad) {
+  if (!node || typeof node !== "object") return "unknown";
+  if (node.$ref) {
+    const m = /^#\/\$defs\/(.+)$/.exec(node.$ref);
+    return m ? ctx.base + pascal(m[1]) : "unknown";
+  }
+  if ("const" in node) return literal(node.const);
+  if (Array.isArray(node.enum)) return node.enum.map(literal).join(" | ");
+  const alts = node.oneOf ?? node.anyOf;
+  if (Array.isArray(alts)) {
+    return alts.map((a) => wrap(tsType(a, ctx, pad))).join(" | ");
+  }
+  const types = node.type === undefined ? [] : [].concat(node.type);
+  if (!types.length) return node.properties ? objectType(node, ctx, pad) : "unknown";
+  return types.map((t) => wrap(single(t, node, ctx, pad))).join(" | ");
+}
+
+const wrap = (t) => (/^[^{]*\|/.test(t) && !t.startsWith("(") ? `(${t})` : t);
+
+function single(t, node, ctx, pad) {
+  switch (t) {
+    case "string":
+      return "string";
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "null":
+      return "null";
+    case "array":
+      return node.items ? `Array<${tsType(node.items, ctx, pad)}>` : "unknown[]";
+    case "object":
+      return objectType(node, ctx, pad);
+    default:
+      return "unknown";
+  }
+}
+
+function objectType(node, ctx, pad) {
+  const props = node.properties ?? {};
+  const required = new Set(node.required ?? []);
+  const inner = `${pad}  `;
+  const lines = [];
+  for (const [k, v] of Object.entries(props)) {
+    lines.push(
+      doc(v.description, inner) +
+        `${inner}${key(k)}${required.has(k) ? "" : "?"}: ${tsType(v, ctx, inner)};`,
+    );
+  }
+  const extra = node.additionalProperties;
+  if (extra && typeof extra === "object") {
+    lines.push(`${inner}[key: string]: ${tsType(extra, ctx, inner)};`);
+  } else if (!Object.keys(props).length) {
+    return "Record<string, unknown>";
+  }
+  return `{\n${lines.join("\n")}\n${pad}}`;
+}
+
+function declare(name, node, ctx) {
+  const isObject = [].concat(node.type ?? []).join() === "object" && node.properties;
+  const head = doc(node.description ?? node.title, "");
+  return isObject
+    ? `${head}export interface ${name} ${objectType(node, ctx, "")}\n`
+    : `${head}export type ${name} = ${tsType(node, ctx, "")};\n`;
+}
+
+export function renderTypes() {
+  const out = [
+    "// 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 = ${literal(MANIFEST.contractVersion)};`,
+    `export type SurfaceId = ${MANIFEST.surfaces.map((s) => literal(s.id)).join(" | ")};`,
+    "",
+  ];
+  for (const file of MANIFEST.schemas) {
+    const schema = JSON.parse(readFileSync(join(SCHEMAS, file), "utf8"));
+    const base = typeNameFor(file);
+    const ctx = { base };
+    out.push(declare(base, schema, ctx));
+    for (const [defName, def] of Object.entries(schema.$defs ?? {})) {
+      out.push(declare(base + pascal(defName), def, ctx));
+    }
+  }
+  return out.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Fixtures
+
+const FIXED_NOW = "2026-09-17T10:30:00.000Z";
+const SHOWN_ROOT = "/Users/example/.claude/logs/multi-agent";
+const QUESTION = {
+  id: "maturity",
+  stepId: "phase-0/maturity",
+  text: "The item has no acceptance criteria. How should the run continue?",
+  kind: "single-select",
+  options: [
+    { id: "fix", label: "Open the item and fix it" },
+    { id: "continue", label: "Continue without it" },
+    { id: "abort", label: "Abort" },
+  ],
+};
+const tracker = (taskId, phases) => ({
+  task_id: taskId,
+  started_at: "2026-09-17T10:00:00Z",
+  phases,
+});
+const phase = (id, name, status, extra = {}) => ({ id, name, status, ...extra });
+const DONE = (id, name) =>
+  phase(id, name, "completed", {
+    model: "opus",
+    started_at: "2026-09-17T10:00:00Z",
+    completed_at: "2026-09-17T10:05:00Z",
+    tokens_in: 1200,
+    tokens_out: 340,
+    tokens_cached: 900,
+  });
+
+/** One run per state: [agent-state, tracker-state] under example-app/<taskId>. */
+const RUN_STATES = {
+  running: [
+    {
+      taskId: "PROJ-101",
+      schemaVersion: "2.2.0",
+      rev: 7,
+      status: "in_progress",
+      currentPhase: 2,
+      branch: "feature/PROJ-101",
+      baseBranch: "develop",
+      startedAt: "2026-09-17T10:00:00Z",
+      sessionId: "00000000-0000-4000-8000-000000000101",
+      autopilot: true,
+      project: "example-app",
+      projectRoot: "/Users/example/example-app",
+      worktreePath: "/Users/example/example-app/.worktrees/PROJ-101",
+    },
+    tracker("PROJ-101", [
+      DONE("0", "Init"),
+      DONE("1", "Plan"),
+      phase("2", "Dev", "in_progress", {
+        model: "opus",
+        started_at: "2026-09-17T10:06:00Z",
+        now: "writing tests",
+        subs: [
+          { id: "2.1", name: "failing test", status: "completed" },
+          { id: "2.2", name: "implementation", status: "in_progress" },
+        ],
+      }),
+    ]),
+  ],
+  "awaiting-question": [
+    {
+      taskId: "PROJ-102",
+      schemaVersion: "2.2.0",
+      rev: 3,
+      status: "awaiting_input",
+      currentPhase: 0,
+      startedAt: "2026-09-17T10:00:00Z",
+      sessionId: "00000000-0000-4000-8000-000000000102",
+      autopilot: true,
+      project: "example-app",
+      waitingFor: "question",
+      pendingQuestion: QUESTION,
+    },
+    tracker("PROJ-102", [phase("0", "Init", "in_progress", { now: "waiting for an answer" })]),
+  ],
+  failed: [
+    {
+      taskId: "PROJ-103",
+      schemaVersion: "2.2.0",
+      rev: 12,
+      status: "failed",
+      currentPhase: 3,
+      branch: "bugfix/PROJ-103",
+      baseBranch: "develop",
+      startedAt: "2026-09-17T10:00:00Z",
+      project: "example-app",
+      worktreePath: "/Users/example/example-app/.worktrees/PROJ-103",
+    },
+    tracker("PROJ-103", [
+      DONE("0", "Init"),
+      DONE("1", "Plan"),
+      DONE("2", "Dev"),
+      phase("3", "Review", "failed", { model: "fable", started_at: "2026-09-17T10:20:00Z" }),
+    ]),
+  ],
+  "pr-opened": [
+    {
+      taskId: "PROJ-104",
+      schemaVersion: "2.2.0",
+      rev: 21,
+      status: "awaiting_input",
+      currentPhase: 5,
+      branch: "feature/PROJ-104",
+      baseBranch: "develop",
+      startedAt: "2026-09-17T10:00:00Z",
+      project: "example-app",
+      worktreePath: "/Users/example/example-app/.worktrees/PROJ-104",
+      pr: { url: "https://github.com/example-org/example-app/pull/104" },
+    },
+    tracker(
+      "PROJ-104",
+      ["Init", "Plan", "Dev", "Review", "Commit", "Report"].map((n, i) => DONE(String(i), n)),
+    ),
+  ],
+  "old-schema": [
+    {
+      taskId: "PROJ-105",
+      schemaVersion: "2.0.0",
+      status: "paused",
+      currentPhase: 2,
+      branchName: "feature/PROJ-105",
+    },
+    tracker("PROJ-105", [DONE("0", "Init"), DONE("1", "Plan"), phase("2", "Dev", "pending")]),
+  ],
+};
+
+/** Fields runs-index added after contract 1.0.0; the old-schema fixture has none. */
+const ADDED_SINCE_1_0 = ["sessionId", "waitingFor", "pendingQuestion"];
+
+async function withLogsRoot(fn) {
+  const base = mkdtempSync(join(tmpdir(), "ma-kit-"));
+  const saved = process.env.LOGS_ROOT;
+  process.env.LOGS_ROOT = base;
+  try {
+    return await fn(base);
+  } finally {
+    if (saved === undefined) delete process.env.LOGS_ROOT;
+    else process.env.LOGS_ROOT = saved;
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+const shown = (obj, root) => {
+  let text = JSON.stringify(obj);
+  for (const r of new Set([root, realpathSync(root)])) text = text.split(r).join(SHOWN_ROOT);
+  return JSON.parse(text);
+};
+
+export async function renderFixtures() {
+  const runsIndex = await import("../scripts/runs-index.mjs");
+  const worktrees = await import("../scripts/worktrees.mjs");
+  const issues = await import("../scripts/issues.mjs");
+  const launch = await import("../scripts/launch-request.mjs");
+  const answer = await import("../scripts/answer-question.mjs");
+  const out = {};
+
+  const indexOf = (states, { redact = false } = {}) =>
+    withLogsRoot((root) => {
+      for (const [state, trackerState] of states) {
+        const dir = join(root, "example-app", state.taskId);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "agent-state.json"), JSON.stringify(state));
+        writeFileSync(join(dir, "tracker-state.json"), JSON.stringify(trackerState));
+      }
+      return shown(runsIndex.envelope(runsIndex.selectRuns().records, { redact }), root);
+    });
+
+  for (const [name, pair] of Object.entries(RUN_STATES)) {
+    const doc = await indexOf([pair]);
+    if (name === "old-schema") {
+      doc.contractVersion = "1.0.0";
+      for (const run of doc.runs) for (const k of ADDED_SINCE_1_0) delete run[k];
+    }
+    out[`runs-${name}.json`] = doc;
+  }
+  out["runs-pr-opened-redacted.json"] = await indexOf([RUN_STATES["pr-opened"]], { redact: true });
+  out["runs-empty.json"] = await indexOf([]);
+  out["worktrees-empty.json"] = await withLogsRoot(() => worktrees.buildList());
+  out["issues-empty.json"] = issues.collect({
+    env: {
+      PATH: process.env.PATH,
+      HOME: tmpdir(),
+      MA_JIRA_SEARCH: "/nonexistent/jira-search.sh",
+      MA_GH_BIN: "/nonexistent/gh",
+    },
+  });
+
+  const sessionId = "00000000-0000-4000-8000-000000000201";
+  out["launch-plan.json"] = launch.planLaunch({
+    request: {
+      contractVersion: "1.0.0",
+      input: "PROJ-201",
+      mode: "autopilot",
+      answers: { workspace: "worktree" },
+    },
+    requestFile: `/Users/example/.claude/autopilot/requests/${sessionId}.json`,
+    repoPath: "/Users/example/example-app",
+    settingsFile: "/Users/example/.claude/multi-agent-unattended.settings.json",
+    runLogsRoot: "/Users/example/.multi-agent-unattended/logs",
+    sessionId,
+    workingTree: "clean",
+  }).out;
+  const answered = answer.applyAnswer(
+    { waitingFor: "question", pendingQuestion: QUESTION },
+    ["continue"],
+    new Date(FIXED_NOW),
+  );
+  out["answer-result.json"] = {
+    contractVersion: answer.CONTRACT_VERSION,
+    answered: answered.state.lastAnswer,
+  };
+  out["error-unauthorized.json"] = {
+    contractVersion: MANIFEST.contractVersion,
+    error: "unauthorized",
+    message: "a bearer token is required",
+  };
+  out["error-unsigned.json"] = {
+    contractVersion: MANIFEST.contractVersion,
+    error: "unsigned",
+    message: "a device signature is required",
+  };
+  out["error-invalid-request.json"] = {
+    contractVersion: MANIFEST.contractVersion,
+    error: "invalid-request",
+    message: "the launch request was refused",
+    errors: ['answers.workspace: "local" is not allowed in autopilot mode'],
+  };
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+
+async function main(argv) {
+  const mode = argv[0];
+  if (argv.length !== 1 || (mode !== "--write" && mode !== "--check")) {
+    process.stderr.write("usage: build.mjs --write | --check\n");
+    return 2;
+  }
+  const files = { "types/index.d.ts": renderTypes() };
+  for (const [name, doc] of Object.entries(await renderFixtures())) {
+    files[`fixtures/${name}`] = JSON.stringify(doc, null, 2) + "\n";
+  }
+  const drift = [];
+  for (const [rel, text] of Object.entries(files)) {
+    const path = join(KIT, rel);
+    let current;
+    try {
+      current = readFileSync(path, "utf8");
+    } catch {
+      current = null;
+    }
+    if (current === text) continue;
+    if (mode === "--write") {
+      mkdirSync(join(path, ".."), { recursive: true });
+      writeFileSync(path, text);
+      process.stdout.write(`wrote ${rel}\n`);
+    } else drift.push(rel);
+  }
+  if (drift.length) {
+    process.stdout.write(
+      `contract kit drift (run build.mjs --write):\n${drift.map((d) => `  ${d}\n`).join("")}`,
+    );
+    return 1;
+  }
+  return 0;
+}
+
+if (
+  process.argv[1] &&
+  realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/pipeline/contract/fixtures/answer-result.json

@@ -0,0 +1,11 @@
+{
+  "contractVersion": "1.0.0",
+  "answered": {
+    "questionId": "maturity",
+    "stepId": "phase-0/maturity",
+    "optionIds": [
+      "continue"
+    ],
+    "answeredAt": "2026-09-17T10:30:00.000Z"
+  }
+}

package/pipeline/contract/fixtures/error-invalid-request.json

@@ -0,0 +1,8 @@
+{
+  "contractVersion": "1.2.0",
+  "error": "invalid-request",
+  "message": "the launch request was refused",
+  "errors": [
+    "answers.workspace: \"local\" is not allowed in autopilot mode"
+  ]
+}

package/pipeline/contract/fixtures/error-unauthorized.json

@@ -0,0 +1,5 @@
+{
+  "contractVersion": "1.2.0",
+  "error": "unauthorized",
+  "message": "a bearer token is required"
+}

package/pipeline/contract/fixtures/error-unsigned.json

@@ -0,0 +1,5 @@
+{
+  "contractVersion": "1.2.0",
+  "error": "unsigned",
+  "message": "a device signature is required"
+}

package/pipeline/contract/fixtures/issues-empty.json

@@ -0,0 +1,18 @@
+{
+  "contractVersion": "1.0.0",
+  "items": [],
+  "sources": [
+    {
+      "source": "jira",
+      "ok": false,
+      "count": 0,
+      "reason": "failed"
+    },
+    {
+      "source": "github",
+      "ok": false,
+      "count": 0,
+      "reason": "unavailable"
+    }
+  ]
+}

package/pipeline/contract/fixtures/launch-plan.json

@@ -0,0 +1,31 @@
+{
+  "contractVersion": "1.0.0",
+  "valid": true,
+  "verified": false,
+  "host": "claude",
+  "mode": "autopilot",
+  "sessionId": "00000000-0000-4000-8000-000000000201",
+  "requestFile": "/Users/example/.claude/autopilot/requests/00000000-0000-4000-8000-000000000201.json",
+  "bin": "claude",
+  "cwd": "/Users/example/example-app",
+  "argv": [
+    "--bg",
+    "--session-id",
+    "00000000-0000-4000-8000-000000000201",
+    "--permission-prompts",
+    "none",
+    "--settings",
+    "/Users/example/.claude/multi-agent-unattended.settings.json",
+    "-p",
+    "/multi-agent PROJ-201 autopilot"
+  ],
+  "env": {
+    "MULTI_AGENT_UNATTENDED": "1",
+    "MULTI_AGENT_SESSION_ID": "00000000-0000-4000-8000-000000000201",
+    "MCP_TOOLKIT_URL_POLICY": "strict",
+    "MCP_TOOLKIT_INDEX_DENY": "~/.ssh,~/.aws,~/.gnupg,~/Library/Keychains",
+    "LOGS_ROOT": "/Users/example/.multi-agent-unattended/logs",
+    "MA_LAUNCH_REQUEST": "/Users/example/.claude/autopilot/requests/00000000-0000-4000-8000-000000000201.json"
+  },
+  "shell": false
+}