@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/contract/manifest.json

@@ -0,0 +1,263 @@
+{
+  "contractVersion": "1.2.0",
+  "supportedMajors": [1],
+  "description": "The pipeline's client contract: every surface a client reads or writes, the CLI invocation and the HTTP route that carry it, and the schema its JSON follows. Schemas are not copied here; schemasDir points at the one tree the producers validate against. Paths in cli are relative to the pipeline directory (installed: ~/.claude).",
+  "schemasDir": "../schemas",
+  "types": "types/index.d.ts",
+  "errorSchema": "contract-error.schema.json",
+  "server": {
+    "cli": ["node", "scripts/contract-server.mjs"],
+    "bind": "127.0.0.1",
+    "auth": "Authorization: Bearer <token>, token in ~/.claude/logs/multi-agent/contract-server/<pid>.json (0600). Not accepted under phone.pathPrefix, which takes a device signature instead.",
+    "query": {
+      "redact": "1 drops every x-sensitivity local field, as --redact does; forced for a request that carries an Origin",
+      "v": "the major to serve; see README.md"
+    }
+  },
+  "phone": {
+    "description": "Routes a phone reaches through a forwarder (a private network or a local relay; see multi-agent-refs/features/phone-api.md). Every request is signed with an enrolled device's Ed25519 key; the bearer token is neither needed nor accepted here, and a signature opens no desktop route. Responses are always the redacted view.",
+    "pathPrefix": "/v1/phone/",
+    "envelopeSchema": "phone-signed-request.schema.json",
+    "registrySchema": "phone-devices.schema.json",
+    "enrol": [
+      "node",
+      "scripts/phone-devices.mjs",
+      "add",
+      "--name",
+      "<name>",
+      "--public-key",
+      "<base64url>",
+      "--scopes",
+      "<read,answer,launch>"
+    ],
+    "signature": {
+      "version": "MA-PHONE-SIG-1",
+      "algorithm": "Ed25519",
+      "headers": {
+        "device": "X-MA-Device",
+        "timestamp": "X-MA-Timestamp",
+        "nonce": "X-MA-Nonce",
+        "signature": "X-MA-Signature"
+      },
+      "payload": ["version", "method", "target", "bodySha256", "deviceId", "timestamp", "nonce"],
+      "join": "\n",
+      "windowSeconds": 60,
+      "futureSkewSeconds": 5
+    },
+    "scopes": ["read", "answer", "launch"],
+    "launch": "POST /v1/phone/launch is refused with launch-disabled until `phone-devices.mjs launch on`, whatever scopes the device holds. Its input is a structured reference only (a Jira key, a GitHub issue URL, repo#N, #N, or a Jira URL on the configured host), and its repo must be a configured or registered one (repo-not-allowed otherwise)",
+    "notOffered": ["pause", "resume", "stop", "steer", "shell", "prompt", "run", "merge", "ready"]
+  },
+  "schemas": [
+    "runs-index.schema.json",
+    "command-parameters.schema.json",
+    "run-questions.schema.json",
+    "issues.schema.json",
+    "worktrees.schema.json",
+    "launch.schema.json",
+    "launch-request.schema.json",
+    "launch-plan.schema.json",
+    "answer-request.schema.json",
+    "answer-result.schema.json",
+    "phone-signed-request.schema.json",
+    "phone-devices.schema.json",
+    "contract-error.schema.json"
+  ],
+  "surfaces": [
+    {
+      "id": "runs",
+      "method": "GET",
+      "path": "/v1/runs",
+      "query": ["group", "redact"],
+      "cli": ["node", "scripts/runs-index.mjs", "--json", "[--group <group>]", "[--redact]"],
+      "schema": "runs-index.schema.json",
+      "version": "1.1.0"
+    },
+    {
+      "id": "run",
+      "method": "GET",
+      "path": "/v1/runs/{id}",
+      "query": ["redact"],
+      "cli": ["node", "scripts/runs-index.mjs", "--json", "--task-id", "{id}", "[--redact]"],
+      "schema": "runs-index.schema.json",
+      "version": "1.1.0"
+    },
+    {
+      "id": "commands",
+      "method": "GET",
+      "path": "/v1/commands",
+      "query": ["redact"],
+      "cli": ["node", "scripts/commands.mjs", "--json"],
+      "schema": "command-parameters.schema.json",
+      "version": "1.0.0"
+    },
+    {
+      "id": "questions",
+      "method": "GET",
+      "path": "/v1/questions",
+      "query": ["redact"],
+      "cli": ["node", "scripts/launch-request.mjs", "questions"],
+      "schema": "run-questions.schema.json",
+      "version": "1.0.0"
+    },
+    {
+      "id": "issues",
+      "method": "GET",
+      "path": "/v1/issues",
+      "query": ["source", "project", "max", "redact"],
+      "cli": [
+        "node",
+        "scripts/issues.mjs",
+        "--json",
+        "[--source jira|github|all]",
+        "[--project <KEY>]...",
+        "[--max <n>]"
+      ],
+      "schema": "issues.schema.json",
+      "version": "1.0.0"
+    },
+    {
+      "id": "worktrees",
+      "method": "GET",
+      "path": "/v1/worktrees",
+      "query": ["measure", "redact"],
+      "cli": ["node", "scripts/worktrees.mjs", "--json", "[--measure]", "[--redact]"],
+      "schema": "worktrees.schema.json",
+      "version": "1.0.0"
+    },
+    {
+      "id": "launch-spec",
+      "method": "GET",
+      "path": "/v1/launch-spec",
+      "query": ["redact"],
+      "cli": ["node", "scripts/launch-request.mjs", "spec"],
+      "schema": "launch.schema.json",
+      "version": "1.1.0"
+    },
+    {
+      "id": "launch",
+      "method": "POST",
+      "path": "/v1/launch",
+      "query": ["repo", "redact"],
+      "body": "launch-request.schema.json",
+      "cli": [
+        "node",
+        "scripts/launch-request.mjs",
+        "plan",
+        "<request-file>",
+        "--repo",
+        "<repo>",
+        "--session-id",
+        "<uuid>",
+        "[--redact]"
+      ],
+      "schema": "launch-plan.schema.json",
+      "version": "1.0.0",
+      "note": "The server writes the request file (0600, named for a session id it mints) and returns the plan; the CLI plans a file the client wrote. Neither starts the host."
+    },
+    {
+      "id": "answer",
+      "method": "POST",
+      "path": "/v1/runs/{id}/answer",
+      "query": [],
+      "body": "answer-request.schema.json",
+      "cli": [
+        "node",
+        "scripts/answer-question.mjs",
+        "<agent-state.json>",
+        "--question",
+        "<questionId>",
+        "--answer",
+        "<optionId>[,<optionId>...]"
+      ],
+      "schema": "answer-result.schema.json",
+      "version": "1.0.0"
+    },
+    {
+      "id": "phone-runs",
+      "method": "GET",
+      "path": "/v1/phone/runs",
+      "query": ["group", "redact"],
+      "auth": "device-signature",
+      "scope": "read",
+      "cli": ["node", "scripts/runs-index.mjs", "--json", "[--group <group>]", "--redact"],
+      "schema": "runs-index.schema.json",
+      "version": "1.1.0",
+      "note": "Always redacted; redact=0 is refused."
+    },
+    {
+      "id": "phone-run",
+      "method": "GET",
+      "path": "/v1/phone/runs/{id}",
+      "query": ["redact"],
+      "auth": "device-signature",
+      "scope": "read",
+      "cli": ["node", "scripts/runs-index.mjs", "--json", "--task-id", "{id}", "--redact"],
+      "schema": "runs-index.schema.json",
+      "version": "1.1.0",
+      "note": "Always redacted; redact=0 is refused."
+    },
+    {
+      "id": "phone-answer",
+      "method": "POST",
+      "path": "/v1/phone/runs/{id}/answer",
+      "query": [],
+      "auth": "device-signature",
+      "scope": "answer",
+      "body": "answer-request.schema.json",
+      "cli": [
+        "node",
+        "scripts/answer-question.mjs",
+        "<agent-state.json>",
+        "--question",
+        "<questionId>",
+        "--answer",
+        "<optionId>[,<optionId>...]"
+      ],
+      "schema": "answer-result.schema.json",
+      "version": "1.0.0",
+      "note": "The same refusals as POST /v1/runs/{id}/answer: only an option id the pending question offered is recorded."
+    },
+    {
+      "id": "phone-launch",
+      "method": "POST",
+      "path": "/v1/phone/launch",
+      "query": ["repo", "redact"],
+      "auth": "device-signature",
+      "scope": "launch",
+      "body": "launch-request.schema.json",
+      "cli": [
+        "node",
+        "scripts/launch-request.mjs",
+        "plan",
+        "<request-file>",
+        "--repo",
+        "<repo>",
+        "--session-id",
+        "<uuid>",
+        "--channel",
+        "phone",
+        "--redact"
+      ],
+      "schema": "launch-plan.schema.json",
+      "version": "1.0.0",
+      "note": "Off until `phone-devices.mjs launch on`. Writes the request file and returns the redacted plan; nothing starts the host."
+    }
+  ],
+  "fixtures": {
+    "runs-running.json": "runs-index.schema.json",
+    "runs-awaiting-question.json": "runs-index.schema.json",
+    "runs-failed.json": "runs-index.schema.json",
+    "runs-pr-opened.json": "runs-index.schema.json",
+    "runs-pr-opened-redacted.json": "runs-index.schema.json",
+    "runs-empty.json": "runs-index.schema.json",
+    "runs-old-schema.json": "runs-index.schema.json",
+    "worktrees-empty.json": "worktrees.schema.json",
+    "issues-empty.json": "issues.schema.json",
+    "launch-plan.json": "launch-plan.schema.json",
+    "answer-result.json": "answer-result.schema.json",
+    "error-unauthorized.json": "contract-error.schema.json",
+    "error-invalid-request.json": "contract-error.schema.json",
+    "error-unsigned.json": "contract-error.schema.json"
+  }
+}

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

@@ -0,0 +1,343 @@
+// 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.2.0";
+export type SurfaceId = "runs" | "run" | "commands" | "questions" | "issues" | "worktrees" | "launch-spec" | "launch" | "answer" | "phone-runs" | "phone-run" | "phone-answer" | "phone-launch";
+
+/** What `runs-index.mjs --json` prints: every run under the log root, 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 `now`, sub-step names and the pending question. */
+export interface RunsIndex {
+  contractVersion: string;
+  /** Absent under --redact. */
+  logsRoot?: string;
+  count: number;
+  runs: Array<RunsIndexRun>;
+}
+
+export interface RunsIndexRun {
+  taskId: string;
+  project: string | null;
+  /** The run directory. */
+  dir?: string;
+  layout: "nested" | "flat";
+  /** The other layout's directory for the same task id, when both exist. */
+  duplicateOf?: string | null;
+  salvaged: boolean;
+  kind: "pipeline" | "tracker-only" | "empty";
+  stateReadable: boolean;
+  status: string | null;
+  currentPhase: number | null;
+  branch: string | null;
+  baseBranch: string | null;
+  startedAt: string | null;
+  worktreePath?: string | null;
+  /** Carries the host, so it stays on this machine. */
+  prUrl?: string | null;
+  autopilot: boolean;
+  /** The run's agent-state schemaVersion. Always a string; a number in a hand-edited state is printed as its string. */
+  schemaVersion: string | null;
+  rev: number | null;
+  /** The session id the run was launched under (agent-state sessionId). A client that launched a run through launch.json finds it by this id. Added in 1.1.0. */
+  sessionId?: string | null;
+  /** The step a paused run re-enters (agent-state waitingFor): maturity, user-channels-choice or question. Added in 1.1.0. */
+  waitingFor?: string | null;
+  /** The question the run stopped on, present only with waitingFor question. Answer it with one of options[].id through `answer-question.mjs` or POST /v1/runs/{id}/answer. text and labels are scrubbed under --redact. Added in 1.1.0. */
+  pendingQuestion?: null | RunsIndexQuestion;
+  group: "waiting" | "stopped" | "question" | "unknown";
+  phases: Array<RunsIndexPhase>;
+  tokens: {
+    in: number;
+    out: number;
+    cached: number;
+  };
+  estUsd: number;
+  unlockedWrites: number;
+}
+
+export interface RunsIndexQuestion {
+  id: string;
+  stepId: string;
+  text: string;
+  kind: "single-select" | "multi-select";
+  options: Array<{
+    id: string;
+    label: string;
+  }>;
+}
+
+export interface RunsIndexPhase {
+  id: string;
+  name: string;
+  status: string;
+  model: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  /** The phase's one-line current activity, as phase-tracker.sh recorded it. Scrubbed under --redact. */
+  now: string | null;
+  /** How many sub-steps the phase has. Kept as a count for existing readers; the sub-steps are subList. */
+  subs: number;
+  subList: Array<{
+    id: string;
+    name: string;
+    status: string;
+  }>;
+}
+
+/** What `commands.mjs --json` prints: every /multi-agent:<id> command with the parameters, surface and confirmation it declares in its SKILL.md frontmatter, defaults filled in. A client renders a button or a form from this without hard-coding a command. The frontmatter is the source; `_command-contract.mjs` holds it to `argument-hint`. Every field is `x-sensitivity: none`: nothing here is specific to a machine or a person. */
+export interface CommandParameters {
+  /** Major 1. A minor bump adds fields; a consumer ignores keys it does not know. */
+  contractVersion: string;
+  commands: Array<CommandParametersCommand>;
+}
+
+export interface CommandParametersCommand {
+  /** The command directory name; invoked as /multi-agent:<id>. */
+  id: string;
+  /** The human hint, verbatim. Empty when the command declares none. */
+  argumentHint: string;
+  parameters: Array<CommandParametersParameter>;
+  /** button: runs with no input. form: collect parameters first. hidden: not offered as an action (maintainer tooling, help text). Independent of disable-model-invocation, which only stops the model invoking the command itself. */
+  gui: "button" | "form" | "hidden";
+  /** Removes something that is not trivially recreated: a worktree, a branch, logs, an install, user instruction lines. */
+  destructive: boolean;
+  /** required: a client asks before launching. Always required when destructive. The command keeps its own in-session confirmation either way. */
+  confirm: "required" | "none";
+}
+
+export interface CommandParametersParameter {
+  /** `--name` for a flag, typed as written. Otherwise a positional, in order; a positional of kind flag is a literal keyword typed as its name. */
+  name: string;
+  /** run-id: #N or a task id. pull-request: a PR number or URL. issue-key: a Jira key or a GitHub issue reference. flag: present or absent, no value. */
+  kind: "run-id" | "branch" | "pull-request" | "issue-key" | "path" | "text" | "enum" | "flag";
+  /** Omitted in frontmatter means false; the catalog always carries it. */
+  required?: boolean;
+  /** More than one value: space-separated for a positional, comma-separated for a flag. */
+  repeat?: boolean;
+  /** The allowed values. Present exactly when kind is enum. */
+  enum?: Array<string>;
+}
+
+/** Shape of run-questions.json: the Phase 0 pickers of a /multi-agent run as data. Every field is x-sensitivity none - the file ships with the package and describes questions, never a machine's answers. */
+export interface RunQuestions {
+  contractVersion: string;
+  description?: string;
+  questions: Array<RunQuestionsQuestion>;
+}
+
+export interface RunQuestionsQuestion {
+  /** The key a launch request answers under. */
+  id: string;
+  /** dynamic: the questions themselves are produced during the run and cannot be answered in advance. */
+  kind: "single-select" | "multi-select" | "dynamic";
+  /** Where in phase-0-init.md (or the file it names) the picker lives. */
+  "asked-at": string;
+  /** Whether a launch request may pre-fill it. false: the run always asks. */
+  answerable: boolean;
+  /** Static options. An answer is one option id. Absent when the options are enumerated at run time; then `answer` constrains the value. */
+  options?: Array<{
+    id: string;
+    label: string;
+  }>;
+  /** For options enumerated at run time: every answered value must match `pattern`. Phase 0 still checks the value is one of the options it enumerated, and asks when it is not. */
+  answer?: {
+    pattern: string;
+    description?: string;
+    /** A neutral value the pattern admits. */
+    example?: string;
+  };
+  /** The option id the picker marks recommended. */
+  default?: string;
+  /** The agent-state.json field the answer ends up in. */
+  stateField?: string;
+  /** Conditions under which Phase 0 resolves the step without asking. */
+  "skippable-when"?: Array<string>;
+  /** An option that may not be chosen under a condition. A launch request choosing it is rejected, not downgraded. */
+  "disabled-when"?: Array<{
+    option: string;
+    mode?: "interactive" | "autopilot";
+    workingTree?: "dirty";
+  }>;
+  /** A command that prints the options as redacted JSON. null when none ships. */
+  source: string | null;
+  sourceNote?: string;
+}
+
+/** What `issues.mjs --json` prints: open items assigned to the current user, Jira and GitHub in one list. No field carries a URL, a host, a person or a path - summaries are scrubbed before they are printed - so every field is x-sensitivity none and --redact changes nothing. */
+export interface Issues {
+  contractVersion: string;
+  /** Priority first, then status, then newest. */
+  items: Array<{
+    /** A Jira key, or owner/repo#N for GitHub. */
+    key: string;
+    summary: string;
+    status: string | null;
+    type: string | null;
+    /** Jira's priority name. Always null for GitHub, which has none. */
+    priority: string | null;
+    source: "jira" | "github";
+  }>;
+  sources: Array<{
+    source: "jira" | "github";
+    ok: boolean;
+    count: number;
+    /** Why a source contributed nothing. A fixed code, never the tool's own message. */
+    reason?: "not-onboarded" | "unavailable" | "failed";
+  }>;
+}
+
+/** What `worktrees.mjs --json` prints: one entry per run that owns a worktree, with its size when --measure was passed. --redact removes every x-sensitivity local field. */
+export interface Worktrees {
+  contractVersion: string;
+  worktrees: Array<{
+    taskId: string;
+    project?: string | null;
+    /** Absolute path on this machine. */
+    worktreePath?: string;
+    /** The directory is on disk. false: removed by Phase 4 or by hand, and the run still names it. */
+    exists: boolean;
+    /** Disk usage from du -sk. null unless --measure ran and the directory exists. */
+    sizeBytes: number | null;
+    /** When sizeBytes was taken; null when it was not. */
+    measuredAt: string | null;
+  }>;
+}
+
+/** Shape of launch.json: per host CLI, the argv template and environment that start a run, and where the launch request file goes. Templates use {placeholder} tokens named in `placeholders`. Every field is x-sensitivity none: the file ships with the package and holds templates, never a machine's values. */
+export interface Launch {
+  contractVersion: string;
+  /** false until a live launch trial confirmed the shape on a real host. */
+  verified: boolean;
+  note: string;
+  requestFile: {
+    env: "MA_LAUNCH_REQUEST";
+    directory: string;
+    directoryDefault: string;
+    name: string;
+    fileMode: string;
+    schema: string;
+    lifetime: string;
+  };
+  placeholders: {
+    [key: string]: string;
+  };
+  hosts: {
+    [key: string]: LaunchHost;
+  };
+}
+
+export interface LaunchHost {
+  supported: boolean;
+  bin?: string;
+  cwd?: string;
+  note: string;
+  modes?: {
+    [key: string]: {
+      argv: Array<string>;
+      env: {
+        [key: string]: string;
+      };
+    };
+  };
+}
+
+/** The file MA_LAUNCH_REQUEST names: what a client asked for before the run started. Phase 0 reads it through `launch-request.mjs resolve` and pre-fills the matching pickers; with the variable unset nothing changes. Answers are data, never instructions: each one is an option id from run-questions.json or a value its `answer.pattern` admits, and anything else rejects the whole request. The file lives on the machine that runs the pipeline, so every field is x-sensitivity local - a client that relays a request elsewhere strips it first. */
+export interface LaunchRequest {
+  /** Major 1. A request for another major is rejected rather than half-understood. */
+  contractVersion: string;
+  /** What the run works on. A structured reference - a Jira key (^[A-Z][A-Z0-9]+-[0-9]+$), https://github.com/<owner>/<repo>/issues/<n>, repo#N, #N, or a Jira URL on the configured Jira host - reaches the prompt as it is. Free text is accepted on the desktop channel only (never on /v1/phone/launch): one line of at most 500 printable characters with no quote, backslash, backtick or URL, reaching the prompt as one double-quoted argument. On every channel a newline, a control or format character, a leading '-', a flag-like token, or a first token naming a pipeline op or mode keyword rejects the request; a later word is not held to that rule, because a quoted argument cannot route on it. launch-request.mjs inputErrors is the rule. */
+  input: string;
+  /** Whether the run confirms anything. The workspace is a separate answer, and autopilot never runs local. */
+  mode: "interactive" | "autopilot";
+  /** questionId -> optionId (single-select) or optionId[] (multi-select). Keys come from run-questions.json; an unknown or unanswerable key rejects the request. */
+  answers: {
+    [key: string]: string | Array<string>;
+  };
+}
+
+/** What `launch-request.mjs plan` prints, and POST /v1/launch returns: the command a client runs to start a validated launch request unattended, with launch.json's placeholders filled. Neither carrier runs it. argv is an argument vector for a process spawned without a shell (shell is always false): the input is one element, never a string to be split or interpreted. `verified` repeats launch.json's flag; until it is true the shape is provisional. Under redact every x-sensitivity local field is dropped, leaving the session id a client tracks the run by. */
+export interface LaunchPlan {
+  contractVersion: string;
+  valid: true;
+  verified: boolean;
+  host: "claude";
+  mode: "autopilot";
+  /** Phase 0 records it as sessionId; the runs index carries it, which is how the client finds this run. */
+  sessionId: string;
+  /** The request file, mode 0600, named for the session. */
+  requestFile?: string;
+  bin: string;
+  cwd?: string;
+  /** Carries the request's input, which is local. */
+  argv?: Array<string>;
+  /** Variables to add to the client's own environment for the launched process. */
+  env?: {
+    [key: string]: string;
+  };
+  shell: false;
+}
+
+/** The body of POST /v1/runs/{id}/answer: the answer to the question a run stopped on, as `answer-question.mjs <state> --question <questionId> --answer <optionIds>` takes it. questionId is the pendingQuestion.id the client read from the runs index; a run that has moved on to another question refuses the answer. Every option id must be one the question offered. Nothing here is free text, so nothing here can become an instruction. */
+export interface AnswerRequest {
+  questionId: string;
+  optionIds: Array<string>;
+}
+
+/** What `answer-question.mjs` prints, and POST /v1/runs/{id}/answer returns, once an answer is recorded: the lastAnswer written to the run's state in the same write that cleared pendingQuestion. */
+export interface AnswerResult {
+  contractVersion: string;
+  answered: {
+    questionId: string;
+    stepId: string;
+    optionIds: Array<string>;
+    answeredAt: string;
+  };
+}
+
+/** What a phone signs for every request under /v1/phone/ (features/phone-api.md). The device sends deviceId, timestamp, nonce and signature as the headers X-MA-Device, X-MA-Timestamp, X-MA-Nonce and X-MA-Signature; the server rebuilds the other fields from the request itself. The signed text is the seven fields `version`, `method`, `target`, `bodySha256`, `deviceId`, `timestamp`, `nonce`, in that order, joined by a single \n with no trailing newline, UTF-8, signed with the device's Ed25519 private key. No field may contain a newline, which is what makes the join unambiguous. The server refuses a timestamp more than 60 seconds behind its clock, more than 5 seconds ahead of it or earlier than its own start, and a nonce it has seen inside the window (manifest.json phone.signature windowSeconds and futureSkewSeconds). */
+export interface PhoneSignedRequest {
+  /** The scheme; a different version is a different signed text. */
+  version: "MA-PHONE-SIG-1";
+  /** The HTTP method as sent. */
+  method: string;
+  /** The request target exactly as sent: path plus query string, percent-encoding untouched. A forwarder must pass it unchanged. */
+  target: string;
+  /** Lowercase hex SHA-256 of the raw body bytes; an empty body hashes to e3b0c442...b855. */
+  bodySha256: string;
+  /** The id phone-devices.mjs add printed at enrolment. Header X-MA-Device. */
+  deviceId: string;
+  /** Unix seconds, as decimal digits. Header X-MA-Timestamp. */
+  timestamp: string;
+  /** Fresh random base64url per request. Header X-MA-Nonce. */
+  nonce: string;
+  /** Unpadded base64url of the 64-byte Ed25519 signature over the signed text. Header X-MA-Signature. Never logged. */
+  signature: string;
+}
+
+/** <autopilot root>/phone/devices.json, mode 0600 in a 0700 directory, written only by phone-devices.mjs on this machine. Public keys only: a private key never reaches this file. contract-server.mjs reads it on every phone request, so a revocation or a launch toggle applies to the next request, and a file other users can write is treated as empty. A revoked device stays listed so its id is never reissued and the audit log still resolves. */
+export interface PhoneDevices {
+  schemaVersion: "1.0.0";
+  /** POST /v1/phone/launch is refused (launch-disabled) unless this is true, whatever scopes a device holds. Off by default; `phone-devices.mjs launch on|off` sets it. */
+  launchEnabled: boolean;
+  devices: Array<PhoneDevicesDevice>;
+}
+
+export interface PhoneDevicesDevice {
+  id: string;
+  /** A label for a person reading `list`; never used for a decision. */
+  name: string;
+  /** The raw 32-byte Ed25519 public key, unpadded base64url. */
+  publicKey: string;
+  /** read: GET /v1/phone/runs and /v1/phone/runs/{id}. answer: POST /v1/phone/runs/{id}/answer. launch: POST /v1/phone/launch, and only while launchEnabled is true. */
+  scopes: (Array<"read" | "answer" | "launch">);
+  addedAt: string;
+  /** Set by `phone-devices.mjs revoke`; a revoked device is refused on its next request. */
+  revokedAt: string | null;
+}
+
+/** 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. */
+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" | "internal";
+  message: string;
+  errors?: Array<string>;
+  supported?: Array<number>;
+}

package/pipeline/lib/_jira-auth.sh

@@ -33,6 +33,8 @@
 # Exit contract: `jira_auth_resolve` returns 0 when both resolved, 4 when either
 # did not, having already said which on stderr. 4 is the same code both callers
 # already used for "could not resolve", so nothing downstream changes meaning.
+# It returns 3 when a value had to come from prefs and jq is not installed, so
+# a missing tool is not reported as a missing host or token.
 
 # shellcheck shell=bash
 
@@ -62,7 +64,9 @@ _jira_auth_store() {  # locate credential-store.sh from lib/ or the install
 
 jira_auth_resolve() {
   JIRA_API_HOST="${JIRA_HOST:-${ACCOUNT_JIRA_HOST:-}}"
-  [ -n "$JIRA_API_HOST" ] || JIRA_API_HOST="$(_jira_auth_pref '.global.hosts.jira')"
+  # `|| return $?`: the pref reader runs in a subshell, and its 3 ("no jq")
+  # must reach the caller instead of being reported as a missing value.
+  [ -n "$JIRA_API_HOST" ] || JIRA_API_HOST="$(_jira_auth_pref '.global.hosts.jira')" || return $?
   if [ -z "$JIRA_API_HOST" ]; then
     echo "ERR: no Jira host: set JIRA_HOST or prefs .global.hosts.jira" >&2
     return 4
@@ -76,7 +80,7 @@ jira_auth_resolve() {
   if [ -z "$JIRA_API_TOKEN" ]; then
     local key store
     key="${JIRA_TOKEN_KEY:-${ACCOUNT_JIRA_TOKEN_KEY:-}}"
-    [ -n "$key" ] || key="$(_jira_auth_pref '.global.keychainMapping.jira')"
+    [ -n "$key" ] || key="$(_jira_auth_pref '.global.keychainMapping.jira')" || return $?
     if [ -z "$key" ]; then
       echo "ERR: no Jira token: set JIRA_TOKEN or map prefs .global.keychainMapping.jira" >&2
       return 4

package/pipeline/lib/account-resolver.sh

@@ -66,7 +66,7 @@ except Exception:
 
 # 1. Pull every credential entry that looks like one of our token services.
 #    Includes token entries AND username entries (BB needs the user keychain key).
-#    Uses cross-platform credential-store wrapper (macOS/Windows/Linux backends),
+#    Uses the credential-store wrapper over the macOS Keychain,
 #    located via the shared resolver (repo checkout or either install tree)  -
 #    never a hardcoded path. A missing helper degrades to an empty inventory.
 # A pre-set CRED_STORE (tests, custom installs) is honored as-is.