@mmerterden/multi-agent-pipeline 17.5.1 → 18.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "17.5.1",
+  "version": "18.0.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",
@@ -14,7 +14,7 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "npm run format:check && node --test test/*.test.mjs && node pipeline/scripts/run-smokes.mjs && node pipeline/scripts/lint-skills.mjs && node pipeline/scripts/lint-personas.mjs && node pipeline/scripts/lint-mcp-refs.mjs && node pipeline/scripts/eval-triage.mjs && node pipeline/scripts/eval-golden-tasks.mjs && node pipeline/scripts/eval-intent.mjs && node pipeline/scripts/eval-recall.mjs && node pipeline/scripts/validate-schemas.mjs && node pipeline/scripts/validate-prefs.mjs && node pipeline/scripts/scorecard.mjs",
+    "test": "npm run format:check && npm run lint && node --test test/*.test.mjs && node pipeline/scripts/run-smokes.mjs && node pipeline/scripts/lint-skills.mjs && node pipeline/scripts/lint-personas.mjs && node pipeline/scripts/lint-mcp-refs.mjs && node pipeline/scripts/eval-triage.mjs && node pipeline/scripts/eval-golden-tasks.mjs && node pipeline/scripts/eval-intent.mjs && node pipeline/scripts/eval-recall.mjs && node pipeline/scripts/validate-schemas.mjs && node pipeline/scripts/validate-prefs.mjs && node pipeline/scripts/scorecard.mjs",
     "test:unit": "node --test test/*.test.mjs",
     "test:smoke": "node pipeline/scripts/run-smokes.mjs",
     "lint:skills": "node pipeline/scripts/lint-skills.mjs",
@@ -25,6 +25,7 @@
     "format": "prettier --write \"**/*.{js,mjs,json,yml}\" --ignore-path .gitignore --ignore-path .prettierignore",
     "format:check": "prettier --check \"**/*.{js,mjs,json,yml}\" --ignore-path .gitignore --ignore-path .prettierignore",
     "scorecard": "node pipeline/scripts/scorecard.mjs",
+    "prepack": "node pipeline/scripts/make-manifest.mjs",
     "gate": "bash pipeline/scripts/pre-push-check.sh --run"
   },
   "keywords": [
@@ -69,6 +70,8 @@
   ],
   "files": [
     "index.js",
+    "manifest.json",
+    "manifest.sig",
     "install.js",
     "install/**/*",
     "pipeline/**/*",

package/pipeline/commands/multi-agent/SKILL.md

@@ -48,7 +48,7 @@ Classification schema lives in `$HOME/.claude/multi-agent-refs/_input-parser.md`
 | 7 | `issue` | full picker | account → repo (multi) → issue → maturity → dev-context |
 | 8 | Free-text | `freetext` | account → repo (single) → dev-context (maturity skip) |
 
-**Rule**: Whatever the type, **account is always asked** (autopilot picks a default). After issue fetch, **maturity check is mandatory**  -  blockers halt the pipeline. Picker `header` renders in English (the 12-char chip); the `question`, each option's `label` and each option's `description` render in `outputLanguage`, per the canonical matrix in `multi-agent-refs/rules.md`.
+**Rule**: Whatever the type, **account is always asked** (autopilot picks a default). After issue fetch, **maturity check is mandatory**  -  a blocker asks before it halts, and an autopilot run can be told to ask on the item itself (`$HOME/.claude/multi-agent-refs/features/maturity-followup.md`). Picker `header` renders in English (the 12-char chip); the `question`, each option's `label` and each option's `description` render in `outputLanguage`, per the canonical matrix in `multi-agent-refs/rules.md`.
 
 Lib scripts (`~/.claude/lib/`):
 - `account-resolver.sh`  -  keychain account inventory

package/pipeline/commands/multi-agent/feedback/SKILL.md

@@ -44,7 +44,13 @@ One message, sent to the maintainer's admin panel. This exists because the alter
 
 ## Auth and reachability
 
-Reuses the usage ingest token (`prefs.global.keychainMapping.usage_ingest`), so nothing extra has to be onboarded - `/multi-agent:update` registers one on first run. With no token, the command says so and names the command that fixes it rather than failing quietly.
+Reuses the usage ingest token (`prefs.global.keychainMapping.usage_ingest`), so nothing extra has to be onboarded. When none resolves, register one first and then send:
+
+```bash
+node "$HOME/.claude/scripts/usage-register.mjs" --feedback --quiet
+```
+
+`--feedback` is what makes this work for a machine that opted out of telemetry: it mints the token and leaves `usageLog.enabled` untouched. If registration is unavailable (offline, endpoint down), the command says so and names the command that fixes it rather than failing quietly.
 
 `usageLog.optOut` does **not** silence this. Telemetry is passive collection and opting out of it is a real choice; feedback is a deliberate act by the person typing the command, and dropping a message somebody chose to send would be worse than not offering the command at all.
 

package/pipeline/commands/multi-agent/graph/SKILL.md

@@ -25,7 +25,7 @@ No worktree, no branch, no commit, no pipeline chaining.
 | `refresh` | same as `build` | A full rebuild takes seconds, so there is no separate incremental path |
 | `ask "<question>"` | `graph-query.mjs "<question>" --budget N` | Token-budgeted traversal; default budget 2000 |
 | `affected "<symbol>"` | `graph-affected.mjs "<symbol>" --depth N` | Reverse traversal: the blast radius of a change |
-| `report` | `graph-report.mjs` | Writes `GRAPH_REPORT.md` beside the graph |
+| `report` | `graph-report.mjs` | Writes `GRAPH_REPORT.md` beside the graph: hubs, modules, external dependencies, unconnected files, and symbols no other file references (candidates only - the extractor is regex, not a parser, so nothing gates on that list) |
 | `status` | `graph-report.mjs --status` | One line: stack, scale, build time and whether `baseCommit` still matches HEAD. Never read the graph file yourself - it is 22MB on a large repo |
 
 With no argument, run `status`, then offer `build` when no graph exists and

package/pipeline/commands/multi-agent/issue/SKILL.md

@@ -56,10 +56,22 @@ After selection, inspect `maturity` from `~/.claude/lib/issue-fetcher.sh` (same
 
 | Outcome | Behavior |
 |---|---|
-| `blockers` non-empty (e.g. `description_empty`, `status_closed`) | **Halt** (autopilot too): show summary, advise "fix the issue first" |
+| `blockers` non-empty (e.g. `description_empty`, `status_closed`) | **Ask, then halt** - see "Blockers" below. Default is still the halt |
 | only `warnings` | AskUserQuestion: show summary + "Continue?". Autopilot auto-continues; warnings logged to `agent-log.md` |
 | both empty | Continue silently |
 
+**Blockers: ask, do not just stop.** `$HOME/.claude/multi-agent-refs/features/maturity-followup.md`
+owns this. In short: an interactive run asks at this step (open the item and fix it /
+continue without it, recording which gap was waved through / abort) instead of ending
+with a summary; an autopilot run with `prefs.global.maturityFollowup.autopilotCommentsOnIssue`
+on posts ONE comment on the item asking for what is missing, then halts on the circuit
+breaker with `state.waitingFor = "maturity"` so `resume` re-enters THIS step with the item
+re-fetched. Both defaults keep today's behaviour: the comment is off, the halt is the halt.
+An edit is a reason to re-check, never proof the gap closed - the check re-runs on the new
+content, and only a DIFFERENT gap set ever earns a second comment. Read the item's existing
+comments FIRST and derive the prior ask from the newest one of ours (`priorFromComments`):
+a scan is a new run with a fresh state file, so state alone would make every scan a first ask.
+
 `PROMPT_LANG=en` is passed to `issue-fetcher.sh` (`promptLanguage` is locked to `"en"`).
 
 ### [4/4] Dev context (`_dev-context`)

package/pipeline/commands/multi-agent/jira/SKILL.md

@@ -90,12 +90,24 @@ After issue selection, inspect `maturity` from `~/.claude/lib/issue-fetcher.sh`:
 
 | Outcome | Behavior |
 |---|---|
-| `blockers` non-empty | **Halt** (autopilot too): show summary, advise "fix the issue first" |
+| `blockers` non-empty | **Ask, then halt** - see "Blockers" below. Default is still the halt |
 | `warnings` contains `description_empty_parent_available` | Tailored parent-description question above (not the generic one) |
 | `warnings` contains `description_empty_sibling_available` | Same question, sibling key substituted for the parent's |
 | other `warnings` only | AskUserQuestion: show summary + "Continue?". Autopilot auto-continues; warnings logged to `agent-log.md` |
 | both empty (score ≥ 90) | Continue silently |
 
+**Blockers: ask, do not just stop.** `$HOME/.claude/multi-agent-refs/features/maturity-followup.md`
+owns this. In short: an interactive run asks at this step (open the item and fix it /
+continue without it, recording which gap was waved through / abort) instead of ending
+with a summary; an autopilot run with `prefs.global.maturityFollowup.autopilotCommentsOnIssue`
+on posts ONE comment on the item asking for what is missing, then halts on the circuit
+breaker with `state.waitingFor = "maturity"` so `resume` re-enters THIS step with the item
+re-fetched. Both defaults keep today's behaviour: the comment is off, the halt is the halt.
+An edit is a reason to re-check, never proof the gap closed - the check re-runs on the new
+content, and only a DIFFERENT gap set ever earns a second comment. Read the item's existing
+comments FIRST and derive the prior ask from the newest one of ours (`priorFromComments`):
+a scan is a new run with a fresh state file, so state alone would make every scan a first ask.
+
 > **Resolution check**: If Jira `resolution` is set (`Fixed`, `Done`, `Won't Do`, `Resolved`...), `already_resolved` is added  -  the issue was closed already. To reopen, clear `resolution` in Jira first.
 
 > **fixVersions**: When `descriptor.fixVersions` is non-empty (e.g. `["v1.48.0"]`) and a matching `release/v1.48.0` branch exists in `prefs.projects[*].branches`, suggest that branch. Otherwise fall back to `develop`/cwd current.

package/pipeline/commands/multi-agent/resume/SKILL.md

@@ -38,6 +38,21 @@ Resume a paused or failed task from the last successful phase.
    - Claude Code: `TaskCreate` every phase from the state file in phase order, then `TaskUpdate` each to its stored status, and replace every `tasklist_id` meta with the new IDs.
    - Other CLIs: a single `bash $HOME/.claude/scripts/phase-tracker.sh render`.
 
-5. **Continue the pipeline**  -  start from the next phase (same pipeline as the main multi-agent command).
+5. **Continue the pipeline.** Read `state.waitingFor` FIRST: when it names a step, the
+   run re-enters THAT step rather than the next phase. `currentPhase + 1` is the fallback,
+   not the rule - a run that stopped mid-phase to ask a human has `currentPhase` pointing at
+   the phase it is still inside, so resuming past it skips the question permanently. That
+   was already true of Phase 7's channels pause, which documented itself as resumable
+   through this field while this file never mentioned it.
+
+   | `waitingFor` | Re-entry |
+   |---|---|
+   | `maturity` | Phase 0, the maturity step, with the item **re-fetched** and re-scored - an edit is a reason to look again, never proof the gap closed (`$HOME/.claude/multi-agent-refs/features/maturity-followup.md`) |
+   | `user-channels-choice` | Phase 7, the channels multi-select, with the stored `channelsInput` |
+   | absent | `currentPhase + 1`, as before (same pipeline as the main multi-agent command) |
+
+   Clear `waitingFor` in the same write that records the answer, the moment the step is
+   re-entered. A field that outlives the question it asked sends every later resume back
+   to the step the user already answered.
 
 6. **Log**: `🔄 Resumed {JIRA-KEY}-{id} from Phase {N}`

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -209,9 +209,7 @@ Full key list and shape: `$HOME/.claude/multi-agent-refs/keychain.md`.
 
 `null` = not mapped (missing or skipped). Pipeline phases read this mapping to retrieve tokens dynamically  -  never hardcoded key names.
 
-### Step 2.7  -  Operational reporting token (optional, opt-in)
-
-Only relevant when the admin has issued this user a token. Since v15.8.0, `/multi-agent:update` self-registers a per-machine token automatically when none is onboarded (opt-out: `usageLog.optOut=true`), so Skip here is never a dead end; an admin-issued token pasted now simply takes precedence.
+### Step 2.7  -  Operational reporting
 
 Ask (in `outputLanguage`), and proceed only on an explicit yes:
 
@@ -220,27 +218,27 @@ Do you have an operational-reporting token from your admin?
 [ Paste token / Skip ]
 ```
 
-On paste, store the secret in the credential store ONLY - never in a file, prefs value, git, or any synced/published tree. Use the standard per-user key name so it is revocable independently and consistent across the user's machines:
+On paste, store it in the credential store ONLY - never in a file, prefs value,
+git or any synced tree - under the standard per-user name, so it is revocable on
+its own:
 
 ```bash
 ~/.claude/lib/credential-store.sh set "${USER}_Usage_Ingest_Token" "<pasted-token>"
 ```
 
-Then map it and enable logging (the token itself stays in the credential store; only the logical mapping + the on-switch land in prefs):
+Then, **whether they pasted or skipped**, run:
 
 ```bash
-node -e '
-  const fs=require("fs"),os=require("os"),p=os.homedir()+"/.claude/multi-agent-preferences.json";
-  const j=JSON.parse(fs.readFileSync(p,"utf8"));
-  j.global=j.global||{}; j.global.keychainMapping=j.global.keychainMapping||{};
-  j.global.keychainMapping.usage_ingest=process.argv[1];
-  j.global.usageLog=Object.assign({enabled:true},j.global.usageLog||{},{enabled:true});
-  fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");
-' "${USER}_Usage_Ingest_Token"
-echo "  -> operational reporting configured (token in credential store)"
+node "$HOME/.claude/scripts/usage-register.mjs"
 ```
 
-Security notes to surface to the user: the token is **write-only** (append-only to the endpoint - no read access, no other scope), stored **only in the OS credential store**, and **per-user** so the admin can revoke this one token without affecting anyone else. `usage-report.mjs` reads it from the credential store at runtime via the `usage_ingest` mapping; it is never written to a file or transmitted except over TLS to the ingest endpoint.
+It maps whatever token exists and switches reporting on, and requests a
+per-machine write-only one when none resolves. This call is why the step exists:
+registration used to happen only inside `/multi-agent:update`, so a user who
+installed, ran setup and never ran update never registered and never reported -
+which reads in the panel exactly like nobody using the pipeline. What is sent,
+what never is, and `usageLog.optOut`:
+`$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
 
 ### Auto-learned fields (no setup step needed)
 
@@ -802,7 +800,7 @@ All tokens are optional in the sense that every service can be answered with Ski
 
 ### Step 8  -  Enforcement hooks (optional, Claude Code)
 
-Offer to merge `$HOME/.claude/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus two capture hooks that block nothing (`SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
+Offer to merge `$HOME/.claude/templates/claude-hooks.json`: three `PreToolUse` gates that block on a non-zero exit (secret scan, agent-guard, read-size) plus three capture hooks that block nothing (`PreCompact`, `SessionEnd`, `SessionStart`). What each does: `$HOME/.claude/multi-agent-refs/picker-contract.md`.
 
 - Ask (picker): "Install the pipeline's hooks into `~/.claude/settings.json`?" Default Yes.
 - On Yes, deep-merge EVERY event in the template's `hooks` object, not `PreToolUse` alone - merging one event silently drops the capture hooks, and a run killed before Phase 7 then loses its findings exactly as it did before they existed. Preserve existing hooks; never duplicate a matcher already calling the same script.

package/pipeline/commands/multi-agent/status/SKILL.md

@@ -9,36 +9,49 @@ Show every active and completed task as a table.
 
 ## Steps
 
-1. **Detect the project**  -  find the repo root from cwd (otherwise scan every known repo):
-   - `~/my-ios-app/.worktrees/`
-   - `~/my-figma-app/.worktrees/`
-   - `~/my-ui-components/.worktrees/`
+1. **Ask the producer, do not go looking.** One command answers the whole
+   question:
 
-2. **Scan worktrees**  -  read `agent-state.json` in each worktree dir. **Also scan the log dir**, because a task whose PR is open has no worktree any more (Phase 6 removes it and salvages its state): `find $HOME/.claude/logs/multi-agent -maxdepth 4 -name agent-state.json -path '*/artifacts/*'`. (`-maxdepth 4`, not 3: Phase 6 always passes `--project`, so the salvaged copy lands at `<project>/<task-id>/artifacts/agent-state.json`, which a depth-3 scan can never reach.) Merge both sets by `taskId`, preferring the worktree copy when both exist, and render a finalized task with its `worktreeRemovedAt` rather than omitting it  -  a task that shipped should not vanish from status.
    ```bash
-   find {repo}/.worktrees/ -name "agent-state.json" -maxdepth 2
+   node "$HOME/.claude/scripts/runs-index.mjs"          # grouped table
+   node "$HOME/.claude/scripts/runs-index.mjs" --json   # the same records
    ```
 
-3. **Parse state**  -  for each task:
-   - `taskId`, `branch`, `currentPhase`, `status`, `startedAt`, `autopilot`
-
-3b. **Sort into three groups, and label them.** `in_progress` alone cannot tell
-   a run that is waiting for you from one that died, and on this machine that
-   difference covered 20 runs: 3 were holding at Phase 6/7 with their PR already
-   open, 11 were left at a Phase 0 question with nothing built, 6 stopped
-   mid-development. One "in progress" label for all three is what made a
-   finished job and a crashed one share a row.
+   `runs-index.mjs` resolves through `lib/run-paths.sh` / `scripts/_run-paths.mjs`,
+   so it sees both directory layouts (`<project>/<id>/` and the flat `<id>/`),
+   the salvaged `artifacts/` copy Phase 6 leaves behind, and every spelling of a
+   task id - and it counts a run that exists in both layouts once. Do NOT
+   re-scan the tree by hand: the earlier instruction here listed three
+   hard-coded `.worktrees/` paths and a single `find` depth, and on a real
+   install that combination missed a quarter of the runs and double-counted
+   others. It also scanned worktrees for `agent-state.json`, which Phase 0 has
+   never written there ("never inside the worktree", `phases/phase-0-init.md`).
+
+   The JSON and the table are rendered from the same records, so a dashboard and
+   this command cannot disagree.
+
+2. **Fields per run** (already in the output): `taskId`, `project`, `branch`,
+   `currentPhase`, `status`, `startedAt`, `worktreePath`, `prUrl`, `autopilot`,
+   `phases[]`, `tokens`, `estUsd`, `group`, plus `duplicateOf` when the run also
+   exists in the other layout and `salvaged` when its state is the Phase 6 copy.
+
+3. **Groups are computed, not judged.** `runs-index.mjs` assigns `group` by the
+   table below; report what it returns rather than re-deriving it. `in_progress`
+   alone cannot tell a run that is waiting for you from one that died, and on
+   this machine that difference covered 21 runs.
 
    | Group | Test | Action offered |
    |---|---|---|
-   | Waiting on you | `status == "awaiting_input"`, or a `pr.url`, or phase 6/7 | `resume #N` - the work landed, it needs your answer |
-   | Stopped mid-development | anything else past phase 0 | `resume #N` or `kill #N` |
-   | Left at a question | phase 0 | `garbage-collect --abandoned` - nothing was built |
+   | `waiting` - Waiting on you | `status == "awaiting_input"`, or a `pr.url`, or phase >= 6 | `resume #N` - the work landed, it needs your answer |
+   | `stopped` - Stopped mid-development | anything else past phase 0 | `resume #N` or `kill #N` |
+   | `question` - Left at a question | phase 0 | `garbage-collect --abandoned` - nothing was built |
+   | `unknown` - Status not recorded | no `status` field | say so; offer nothing |
 
-   A run with no `status` is **not** placed in any group. Unknown is not a
-   finding, and calling it dead is the same false claim in the other direction.
+   A run with no `status` is **not** placed in an actionable group. Unknown is
+   not a finding, and calling it dead is the same false claim in the other
+   direction.
 
-4. **Render as a table**, grouped per 3b, with the group as a section heading:
+4. **Render as a table**, grouped per step 3, with the group as a section heading:
    ```
    🤖 Multi-Agent Tasks
 
@@ -59,6 +72,24 @@ Show every active and completed task as a table.
 
    Report `N lesson(s) minable from transcripts  -  /multi-agent:refactor to review` and `N open pipeline observation(s)` when either count is above zero, and print nothing when both are zero. Neither runs a model and neither writes anything: the miner is dry-run by default. Zero candidates alongside a non-zero `toolResultsExamined` means there is nothing to find; zero of both means the read is broken, and that is worth saying rather than reporting a clean queue.
 
+7. **What the spend is doing** (one line, and only when there is something to
+   say). `cost-budget-check.mjs` watches ONE run against ONE ceiling, which is
+   blind to the two ways a budget actually empties: a drift no single run trips,
+   and one pathological session that burns a week in an hour while every run
+   stays under its cap.
+
+   ```bash
+   node "$HOME/.claude/scripts/cost-analyze.mjs" burn --json 2>/dev/null
+   node "$HOME/.claude/scripts/cost-analyze.mjs" anomaly --days 30 --json 2>/dev/null
+   ```
+
+   Report a line only when either exits 10 - an accelerating day, or a day out
+   of family - and say nothing otherwise. The figures are estimates priced from
+   `cost-table.json` at LIST price, so on a subscription they are the right
+   number for comparing days to each other and the wrong number to call a bill;
+   say which when quoting one. `UNMEASURED` means the transcripts could not be
+   read, and it is reported as that rather than as zero.
+
 5. **Quick command hints**  -  based on state:
    - Paused task → suggest `resume #N`
    - Done task → suggest `log #N`

package/pipeline/commands/multi-agent/update/SKILL.md

@@ -111,65 +111,22 @@ A git clone of the pipeline repo is a maintainer workspace, kept in sync by `/mu
    fi
    ```
 
-5b. **Auto-configure operational reporting.** Off means silent: the emitter still
-   no-ops unless `enabled` is true AND a token resolves. This step never SHIPS a
-   secret; when no token is onboarded it REQUESTS a per-machine write-only token
-   from the reporting endpoint's `/register` route (self-registration, v15.8.0+),
-   stores it only in the credential store, and flips `usageLog.enabled` on. It
-   reports coarse run metadata only - never prompts, code, diffs, or paths.
-   Resolution order: env `MULTI_AGENT_USAGE_TOKEN`, then `usageLog.token`, then
-   the Keychain item named by `keychainMapping.usage_ingest`, then
-   self-registration. Registration failing (offline, endpoint down, admin turned
-   ingest off) leaves reporting off with one status line - never an error.
-   **Opt-out is `usageLog.optOut: true`**: it blocks both the auto-enable and the
-   self-registration permanently; print the opt-out hint on first auto-enable.
+5b. **Auto-configure operational reporting.** One call, and it is the same call
+   `/multi-agent:setup` and a first run make - the registration used to live here
+   as forty lines of shell, so a user who installed, ran setup and never ran
+   update was never registered and never reported, which reads in the panel
+   exactly like nobody using the pipeline.
+
    ```bash
-   PREFS="$HOME/.claude/multi-agent-preferences.json"
-   # Reads go through node, not jq. node is a declared engine (>=20.11) so it
-   # is always there; jq is not, and gating this block on it meant a machine
-   # without jq silently never registered and never reported - which reads in
-   # the panel exactly like nobody using the pipeline.
-   if [ -f "$PREFS" ]; then
-     pref() { node -e 'const fs=require("fs");let v;try{v=process.argv[2].split(".").reduce((a,k)=>a?.[k],JSON.parse(fs.readFileSync(process.argv[1],"utf8")))}catch{};process.stdout.write(v==null?"":String(v))' "$PREFS" "$1" 2>/dev/null; }
-     ENABLED=$(pref global.usageLog.enabled)
-     OPTOUT=$(pref global.usageLog.optOut)
-     if [ "$ENABLED" != "true" ] && [ "$OPTOUT" != "true" ]; then
-       TOK="${MULTI_AGENT_USAGE_TOKEN:-}"
-       [ -z "$TOK" ] && TOK=$(pref global.usageLog.token)
-       if [ -z "$TOK" ]; then
-         KNAME=$(pref global.keychainMapping.usage_ingest)
-         [ -n "$KNAME" ] && TOK=$(bash "$HOME/.claude/lib/credential-store.sh" get "$KNAME" 2>/dev/null)
-       fi
-       if [ -z "$TOK" ]; then
-         EP=$(pref global.usageLog.endpoint); [ -z "$EP" ] && EP="https://mmerterden.vercel.app/api/usage/ingest"
-         REG_EP="${EP%/ingest}/register"
-         # Telemetry identity is the GitHub account name, never the git
-         # identity.name (which can carry a corporate title). username -> live
-         # gh login -> OS user.
-         RUSER=$(pref global.identities.0.username)
-         [ -z "$RUSER" ] && RUSER=$(gh api user --jq .login 2>/dev/null || echo "")
-         [ -z "$RUSER" ] && RUSER="$USER"
-         RESP=$(curl -sSL -m 10 -X POST -H "Content-Type: application/json" \
-           --data "{\"u\":\"$RUSER\",\"c\":\"$(hostname -s 2>/dev/null || echo unknown)\"}" \
-           "$REG_EP" 2>/dev/null)
-         TOK=$(printf '%s' "$RESP" | node -e 'let b="";process.stdin.on("data",d=>b+=d).on("end",()=>{try{process.stdout.write(String(JSON.parse(b).token||""))}catch{}})' 2>/dev/null)
-         if [ -n "$TOK" ]; then
-           printf '%s' "$TOK" | bash "$HOME/.claude/lib/credential-store.sh" set "${USER}_Usage_Ingest_Token" "$(cat)"
-           node -e 'const fs=require("fs"),p=process.argv[1];const j=JSON.parse(fs.readFileSync(p,"utf8"));j.global=j.global||{};j.global.keychainMapping=j.global.keychainMapping||{};j.global.keychainMapping.usage_ingest=process.argv[2];fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");' "$PREFS" "${USER}_Usage_Ingest_Token"
-           echo "  -> operational reporting: registered this machine (write-only token in credential store)"
-           echo "     opt out any time: set global.usageLog.optOut=true in multi-agent-preferences.json"
-         fi
-       fi
-       if [ -n "$TOK" ]; then
-         node -e 'const fs=require("fs"),p=process.argv[1];const j=JSON.parse(fs.readFileSync(p,"utf8"));j.global=j.global||{};j.global.usageLog=j.global.usageLog||{};j.global.usageLog.enabled=true;fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");' "$PREFS"
-         echo "  -> operational reporting configured"
-       else
-         echo "  -> operational reporting left off (no token; registration unreachable or disabled)"
-       fi
-     fi
-   fi
+   node "$HOME/.claude/scripts/usage-register.mjs"
    ```
 
+   It requests a per-machine **write-only** token when none resolves, stores it
+   only in the credential store, and flips `usageLog.enabled` on. `usageLog.optOut:
+   true` blocks it permanently. Offline, endpoint down or ingest disabled leaves
+   reporting off with one status line - never an error. Contract and the data it
+   sends: `$HOME/.claude/multi-agent-refs/features/usage-reporting.md`.
+
 6. **Show the new version and its changes** (from the packaged CHANGELOG - there is no git history on this channel):
    ```bash
    NEW=$(tr -d '[:space:]' < "$HOME/.claude/.pipeline-version" 2>/dev/null)

package/pipeline/lib/_jira-auth.sh

@@ -40,6 +40,14 @@ JIRA_AUTH_PREFS="${JIRA_AUTH_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
 
 _jira_auth_pref() {  # _jira_auth_pref <jq path> -> value or empty
   [ -f "$JIRA_AUTH_PREFS" ] || { printf ''; return 0; }
+  # Without jq this printed empty and returned 0, so "no jq" and "key not set"
+  # were the same answer and the caller went on to authenticate with nothing -
+  # surfacing much later as a 401 that blames the credential.
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "jq not found - cannot read $JIRA_AUTH_PREFS (install: brew install jq)" >&2
+    printf ''
+    return 3
+  fi
   jq -r "$1 // empty" "$JIRA_AUTH_PREFS" 2>/dev/null || printf ''
 }
 

package/pipeline/lib/analysis-jira-write.sh

@@ -125,6 +125,30 @@ fi
 # back in CREATED_KEY. Returning the key on stdout too meant a caller using
 # command substitution swallowed the report - the first dry run printed a header
 # and nothing else, and the tree looked empty.
+# Same gate, same five candidate paths, same refusal as jira-publish.sh and
+# post-pr-review.sh. This file is the only ISSUE-CREATION path in the tree, and
+# a summary plus a description is outbound text like any other - it was the one
+# writer the gate did not cover.
+ma_outbound_gate_text() {
+  local text="$1" og="" tmp rc
+  for c in "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/outbound-gate.mjs" \
+           "$HOME/.claude/lib/outbound-gate.mjs" \
+           "$HOME/.copilot/lib/outbound-gate.mjs" \
+           "$HOME/.codex/lib/outbound-gate.mjs"; do
+    [ -f "$c" ] && { og="$c"; break; }
+  done
+  if [ -z "$og" ]; then
+    echo "outbound-gate.mjs not found - refusing to create unchecked issues." >&2
+    return 7
+  fi
+  tmp="$(mktemp)"
+  printf '%s' "$text" > "$tmp"
+  node "$og" --file "$tmp"
+  rc=$?
+  rm -f "$tmp"
+  return $rc
+}
+
 CREATED_KEY=""
 create_issue() {  # create_issue <label> <summary> <issuetype> <parentKey|""> <description>
   local label="$1" summary="$2" itype="$3" parent="$4" desc="$5" body key existing
@@ -146,6 +170,14 @@ create_issue() {  # create_issue <label> <summary> <issuetype> <parentKey|""> <d
     echo "  create  $itype  $summary   [$label]"
     return 0
   fi
+  # After the dry-run branch, because a dry run publishes nothing, and before
+  # the ledger line, because an intent recorded for a POST that never happens
+  # is a false entry in the only record of what was attempted.
+  if ! ma_outbound_gate_text "$summary
+$desc"; then
+    echo "ERR: outbound gate refused '$summary'; nothing was created" >&2
+    return 1
+  fi
   ledger intent "$label"
   local resp
   resp="$(printf '%s' "$body" | jira_api POST "/rest/api/2/issue" --data @- || echo "")"

package/pipeline/lib/ask-choice.sh

@@ -14,6 +14,9 @@
 #
 # Non-interactive / autopilot / CI:
 #   - ASK_CHOICE_DEFAULT=<label-or-1based-index>  picks without prompting.
+#   - MULTI_AGENT_UNATTENDED=1 means nobody is watching even if a terminal is
+#     attached (screen, tmux, a login shell on a server). Same resolution as
+#     the no-TTY case.
 #   - If stdin is not a TTY and no default is set, the FIRST option is chosen
 #     and a notice is written to stderr (never blocks an automated run).
 #
@@ -64,8 +67,16 @@ if [ -n "${ASK_CHOICE_DEFAULT:-}" ]; then
 fi
 
 # Non-interactive with no usable default: pick the first option, don't block.
-if [ ! -t 0 ]; then
-  echo "ask-choice: no TTY and no ASK_CHOICE_DEFAULT - selecting first option '${OPTIONS[0]}'" >&2
+#
+# "No TTY" is the usual shape of that, but it is not the only one. A server run
+# under screen, tmux or a login shell HAS a terminal and still has nobody in
+# front of it, and there the TTY test says "ask" and the process waits forever.
+# MULTI_AGENT_UNATTENDED=1 is the operator saying so out loud; see
+# refs/unattended-contract.md. Unset, nothing below changes.
+if [ ! -t 0 ] || [ "${MULTI_AGENT_UNATTENDED:-}" = "1" ]; then
+  why="no TTY"
+  [ "${MULTI_AGENT_UNATTENDED:-}" = "1" ] && why="MULTI_AGENT_UNATTENDED=1"
+  echo "ask-choice: $why and no ASK_CHOICE_DEFAULT - selecting first option '${OPTIONS[0]}'" >&2
   printf '%s\n' "${OPTIONS[0]}"
   exit 0
 fi

package/pipeline/lib/autopilot-state.sh

@@ -133,6 +133,14 @@ ma_ap_read() { # $1 = filename; empty and exit 1 when absent
 # jq with a default, so a caller never has to distinguish "key absent" from
 # "file absent" from "file unparseable" - all three mean "use the default".
 ma_ap_cfg() { # $1 = jq path, $2 = default
+  # An unreadable queue must not read as an EMPTY queue. Without this, a
+  # machine with no jq made the runner conclude there was no work and go
+  # quiet - the worst failure this mode can have, because it looks like
+  # success.
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "jq not found - cannot read the autopilot config (install: brew install jq)" >&2
+    return 3
+  fi
   local v
   v=$(ma_ap_read config.json 2>/dev/null | jq -r "$1 // empty" 2>/dev/null)
   [ -n "$v" ] && printf '%s\n' "$v" || printf '%s\n' "$2"

package/pipeline/lib/fatal.mjs

@@ -0,0 +1,129 @@
+/**
+ * fatal.mjs  -  one line instead of a stack dump, and whatever was held gets
+ * released.
+ *
+ * Node's default for an uncaught throw or a rejected promise nobody awaited is
+ * a stack trace on stderr and exit 1. That is the right default for a library
+ * and the wrong one here for two reasons.
+ *
+ * The first is legibility. Every script in this tree reports its own failures
+ * as `name: what went wrong`, one line, and a caller - a shell gate, a phase
+ * step, a person reading a run log - is written against that shape. A stack
+ * dump in the middle of it reads as a crash of the pipeline rather than as a
+ * failure of one step, and the actual message sits four frames down.
+ *
+ * The second is state, and it is the one that costs something. A script that
+ * dies between acquiring an advisory lock and releasing it leaves the lock on
+ * disk. The next writer then waits out the full acquire window before deciding
+ * the holder is stale - and if it judges wrong it takes a lock a LIVE writer
+ * holds. `cleanup` exists for exactly that: the handler releases before it
+ * exits, so the abnormal path leaves the same state behind as the normal one.
+ *
+ * What this does NOT do is swallow anything. Every path still exits non-zero,
+ * and the message still names the error; only the stack goes, and only when
+ * the error carries a message worth reading on its own.
+ *
+ * Usage:
+ *   import { runMain } from "../lib/fatal.mjs";
+ *   runMain("write-state", main, { cleanup: releaseLock });
+ *
+ * @module pipeline/lib/fatal
+ */
+
+/** Guards against a cleanup that runs twice when a throw follows a rejection. */
+let cleanedUp = false;
+
+/**
+ * Run `cleanup` at most once, and never let it become the failure it is
+ * cleaning up after: a cleanup that throws inside a fatal handler replaces the
+ * original error with its own, which is how a lock bug ends up reported as a
+ * permissions bug.
+ *
+ * @param {(() => void)|undefined} cleanup
+ */
+function runCleanup(cleanup) {
+  if (cleanedUp || typeof cleanup !== "function") return;
+  cleanedUp = true;
+  try {
+    cleanup();
+  } catch {
+    // Deliberately silent. The caller is already exiting with the real error.
+  }
+}
+
+/**
+ * The message a human should see. An Error with a message prints the message;
+ * anything else (a thrown string, a rejected non-Error) prints its own
+ * stringification, because dropping it would leave the line with nothing in it.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function describe(err) {
+  if (err instanceof Error && err.message) return err.message;
+  if (typeof err === "string" && err) return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
+/**
+ * Catch what escapes: a rejected promise nobody awaited, and a throw from a
+ * callback that no try/catch surrounds. Both are invisible to a try/catch
+ * around main(), which is why wrapping main() alone is not enough.
+ *
+ * MULTI_AGENT_FATAL_STACK=1 restores the stack for debugging. It is off by
+ * default because the line is for the person running the pipeline, not for the
+ * person maintaining it.
+ *
+ * @param {{name:string, cleanup?:()=>void, code?:number}} opts
+ */
+export function installFatalHandlers({ name, cleanup, code = 1 }) {
+  const report = (kind, err) => {
+    runCleanup(cleanup);
+    // `runs-index.mjs --json | head` is not a failure: head closes the pipe and
+    // the next write raises EPIPE. Reporting it as a fatal would turn the most
+    // ordinary way of looking at a large output into a red line and a non-zero
+    // exit, and the reader that went away is not listening to the complaint
+    // anyway. Quiet, zero, the way every other CLI treats it.
+    if (err && err.code === "EPIPE") process.exit(0);
+    process.stderr.write(`${name}: ${kind}  -  ${describe(err)}\n`);
+    if (process.env.MULTI_AGENT_FATAL_STACK === "1" && err instanceof Error && err.stack) {
+      process.stderr.write(`${err.stack}\n`);
+    }
+    // exit(), not exitCode: the event loop may hold a listener that would keep
+    // the process alive after the failure, and a script that has already
+    // reported a fatal must not go on to do more work.
+    process.exit(code);
+  };
+  process.on("unhandledRejection", (err) => report("unhandled rejection", err));
+  process.on("uncaughtException", (err) => report("uncaught exception", err));
+}
+
+/**
+ * Install the handlers and run main, sync or async, with the same contract for
+ * both. A successful run is untouched: no exit call, so `process.exitCode` set
+ * inside main survives, and stdout drains the way it would have.
+ *
+ * @param {string} name        script name as it should appear in the message
+ * @param {() => unknown} main
+ * @param {{cleanup?:()=>void, code?:number}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function runMain(name, main, opts = {}) {
+  const { cleanup, code = 1 } = opts;
+  installFatalHandlers({ name, cleanup, code });
+  try {
+    await main();
+  } catch (err) {
+    runCleanup(cleanup);
+    if (err && err.code === "EPIPE") process.exit(0);
+    process.stderr.write(`${name}: ${describe(err)}\n`);
+    if (process.env.MULTI_AGENT_FATAL_STACK === "1" && err instanceof Error && err.stack) {
+      process.stderr.write(`${err.stack}\n`);
+    }
+    process.exit(code);
+  }
+}