@mmerterden/multi-agent-pipeline 20.28.0 → 20.29.0

package/pipeline/multi-agent-refs/phases/phase-4-commit.md

@@ -25,7 +25,7 @@ Progress emission per `$HOME/.claude/multi-agent-refs/progress-contract.md`  -
 
 #### Input contract
 
-Phase 4 consumes the latest Phase 3 triage output object conforming to `$HOME/.claude/schemas/triage-output.schema.json` (`accepted`, `deferred`, `rejected` buckets) plus the working-tree mutations from Phase 2. The commit body cites only `accepted` findings that were resolved; `deferred` items must be linked in the PR description as follow-up work, never silently dropped. If the triage output reports any unresolved blocking accepted finding, Phase 4 refuses to commit  -  the pipeline returns to Phase 2 for rework.
+Phase 4 consumes the latest Phase 3 triage output (`$HOME/.claude/schemas/triage-output.schema.json` (`accepted`, `deferred`, `rejected` buckets) and the Phase 2 working tree. The commit body cites only `accepted` findings that were resolved; `deferred` items must be linked in the PR description as follow-up work, never silently dropped. An unresolved blocking accepted finding sends the run back to Phase 2.
 
 "Build passes" below is evidence-gated: Phase 4 trusts the `buildStatus.ok` Phase 2 / Phase 3 recorded through `$HOME/.claude/scripts/evidence-gate.mjs` (a pass with no build/test log behind it is unverified and blocks the commit). The secret scanner (`pre-commit-check.sh`) runs on the staged diff as the final pre-commit gate.
 
@@ -44,7 +44,7 @@ Exit 0 passes. Exit 2 with `.verdict` `not-applicable` in `$PC` is `COVERAGE_NA`
 
 A step is accounted for when `completed`, `skipped` + `skipReason`, or `failed` + `failureReason`; a bare `pending` / `in_progress` is the gap. Every Section 14 `Add new` row must name a file in the tree; an empty `docPath[]` reports that half `skipped`, never `passed`.
 
-`COVERAGE_GAP` (a gap, a zero-step plan, unreadable input): show `$PC` verbatim, then return to Phase 2 or have the user mark each step deliberately (`plan-todos.sh` writes the reason); never proceed without that decision. `COVERAGE_NA`: log `plan-coverage: n/a` and continue. Gated runs: `$HOME/.claude/multi-agent-refs/features/unattended-gates.md`.
+`COVERAGE_GAP` (a gap, a zero-step plan, unreadable input): show `$PC` verbatim, then return to Phase 2 or have the user mark each step deliberately (`plan-todos.sh` writes the reason); never proceed without that decision, and re-run the gate once the steps are marked. `COVERAGE_NA`: log `plan-coverage: n/a` and continue. Gated runs: `$HOME/.claude/multi-agent-refs/features/unattended-gates.md`.
 
 #### Step 0  -  Multi-Repo Integration Build
 
@@ -84,7 +84,7 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
 
 **Instruction-driven path:**
 
-1. Ask: "Want to commit?" (skip in autopilot)
+1. Ask: "Want to commit?" (skip in autopilot; operations.md "Attended waits")
 2. Read commit instruction file (e.g. `.instructions/figma/figma-iteration-commit/SKILL.md`)
 3. Follow its flow (build validation, test, submodule commits, push, PR, issue management)
 4. Log: "Phase 4: instruction-driven commit  -  file={instructionFiles.commit}"
@@ -111,8 +111,9 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
    - Commit message uses same convention but scope reflects submodule: `{type}({submodule-scope}): {description} [{jiraId}]`
 6. Commit with convention: `{type}({scope}): {description} [{jiraId}]` or `[#{shortId}]`. When `node $HOME/.claude/scripts/repo-profile.mjs resolve commit.format --repo "$PROJECT_ROOT"` returns `use: true`, its `ticketPosition` places the ticket (`prefix` first, `suffix` last; `none` keeps this default unless confirmed or manual), `ticketStyle` its form and `scopeRequired` the scope. A profile hook with `amends-commit` or `writes-files` rewrites the commit: re-read the SHA after committing ([`features/repo-profile.md`]($HOME/.claude/multi-agent-refs/features/repo-profile.md)). **Local-only repos** (`projects[i].provider == "local"`) have no ticket, and that wins over any profile placement: the subject keeps the conventional prefix with no ticket, and the taskId (`LOCAL-...`) goes in the body footer: `Local-Task: {taskId}`.
 6a. **Valven (required):** `features/valven.md`.
+6b. **Record the commit**: operations.md "Completion evidence".
 7. Push to remote  -  **skip per-repo when `projects[i].provider == "local"`** (no `git push`, no upstream config). Log `Phase 4: local-only commit {sha} (no push)` for that repo.
-8. Ask: "Want to open a Pull Request?"
+8. Ask: "Want to open a Pull Request?" (attended wait, as in step 1)
    - **Skip the prompt entirely when `state.offlineOnly == true`** (all repos local  -  no PR target exists). Proceed to Phase 5 with `pr.status = "skipped-offline"` for each project.
    - In mixed mode (some local, some remote), only prompt for the remote-backed repos; local ones auto-skip.
    - No -> Phase 5
@@ -126,7 +127,7 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
      --task-id "$TASK_ID" --project "$PROJECT" --branch "$BRANCH")
    ```
 
-   The script salvages before removing, keeps the branch, and does **not** check it out  -  the user's HEAD and uncommitted work stay put. On success it stamps `worktreeRemovedAt`, `artifactsPath` and `worktreePath: null` into the **salvaged** `agent-state.json` itself. Do NOT write those via `write-state.mjs "$STATE_FILE"`: in single-repo mode that path went away with the worktree, so the write fails, the fields land nowhere, and Phase 5 reads a dead path and silently skips the triage ingest. After a removal re-point `STATE_FILE` at `$(jq -r .artifactsPath <<< "$FIN")/agent-state.json`. Exit 3 is a safe skip (uncommitted changes, unpushed or detached HEAD, `--local`, cwd inside the tree, preference off): report and continue. Never `--force`. Contract: [`features/worktree-finalize.md`]($HOME/.claude/multi-agent-refs/features/worktree-finalize.md).
+   The script salvages before removing, keeps the branch, and does **not** check it out  -  the user's HEAD and uncommitted work stay put. On success it stamps `worktreeRemovedAt`, `artifactsPath` and `worktreePath: null` into the **salvaged** `agent-state.json` itself. Do NOT write those via `write-state.mjs "$STATE_FILE"`: that path left with the worktree, and Phase 5 would skip the triage ingest. After a removal re-point `STATE_FILE` at `$(jq -r .artifactsPath <<< "$FIN")/agent-state.json`. Exit 3 is a safe skip (uncommitted changes, unpushed or detached HEAD, `--local`, cwd inside the tree, preference off): report and continue. Never `--force`. Contract: [`features/worktree-finalize.md`]($HOME/.claude/multi-agent-refs/features/worktree-finalize.md).
 
 10. **Issue body update** (GitHub Issue only): if the issue body has a `### Pull Requests` section and/or a `### Progress` table, fill in the PR URL(s) (one row per submodule  -  e.g. `- **common:** {url}`, `- **uicomponents:** {url}`) and flip the Implementation / Testing / Code Connect flags from Pending to Done using whatever marker the template uses (match in place, do NOT introduce new markers). Apply it with `gh issue edit {issueNo} --body-file <file>`, preserving every other section unchanged.
 11. **NEVER close or resolve the issue**  -  neither GitHub Issue nor Jira. Issues require team review (4 approvals) before closing. Only post a comment with commit/PR URLs.
@@ -271,7 +272,7 @@ For each repo in `state.projects[]` (sequentially, in dependency order from Phas
    `repo-scope` is the repo's short name (e.g. `common`, `uicomponents`). The subject and `[tracker-id]` are identical across all repos.
 3. `git add` (specific files only  -  same rules as single-repo Step 5)
 4. `git -C "$WT_PATH" commit -m "$MESSAGE"` (heredoc body)  -  using identity already pinned in Phase 0 Step 8.
-5. Capture `state.projects[i].commit = "<sha>"`.
+5. Capture `state.projects[i].commit = {"sha": "<sha>"}`.
 
 ##### Push-must-succeed policy (gated by `prefs.global.settings.pushMustSucceed`, default `true`)
 

package/pipeline/multi-agent-refs/phases/phase-5-report.md

@@ -215,12 +215,13 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 5 task.completed \
 
 ```bash
 STATE_FILE="${STATE_FILE:-$(node $HOME/.claude/scripts/usage-report.mjs --task-id "$TASK_ID" --print-state)}"
-printf '{"status":"complete","currentPhase":5,"finishedAt":"%s"}' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-  | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE" >/dev/null 2>&1 || true
-node $HOME/.claude/scripts/usage-report.mjs --task-id "$TASK_ID" --event completed >/dev/null 2>&1 || true
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+WS_ERR=$(printf '{"status":"complete","currentPhase":5,"finishedAt":"%s"}' "$TS" \
+  | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE" 2>&1 >/dev/null); WS_RC=$?
+[ "$WS_RC" = 0 ] && node $HOME/.claude/scripts/usage-report.mjs --task-id "$TASK_ID" --event completed >/dev/null 2>&1
 ```
 
-Parked on the channels choice instead: emit `--event parked` and leave `status` alone.
+`WS_RC` 6: `$WS_ERR` names what `complete` still lacks; record it (operations.md "Completion evidence") and write again, or halt. Parked on the channels choice instead: emit `--event parked` and leave `status` alone.
 
 **Aggregate before reporting**: run `aggregate-metrics.mjs --since=$(date -u -v-30d +%Y-%m-%d)` and embed output in agent-log.md. Use `--json` for Jira; missing files are skipped.
 

package/pipeline/preferences-template.json

@@ -109,6 +109,13 @@
     },
     "testGen": {
       "revisionCap": 20
+    },
+    "attendedCommitGate": {
+      "mode": "warn"
+    },
+    "readOnlyRepos": [],
+    "stopGuard": {
+      "enabled": true
     }
   },
   "projects": {},

package/pipeline/rules/figma-pipeline.md

@@ -98,6 +98,8 @@ Re-fetching Figma in dev phases:
 
 The repo carries `pipeline/scripts/smoke-no-mcp-in-dev-phases.sh`, which reads a state file's `state.telemetry.mcpCalls[]`: a Figma tool entry with `phase >= 2` fails it, and a Figma entry with no phase is rejected as unjudgeable. It is a maintainer-side regression check: it runs locally as part of `npm test` and the pre-push hook, not in CI (the CI workflow is dormant) and not after every pipeline run.
 
+During a run on Claude Code the rule is enforced by a hook: `run-scope-guard.sh` is registered on PreToolUse `mcp__.*[Ff]igma.*` (`install/templates/claude-hooks.json`). For the run bound to the session it denies a Figma call above `thresholds.mcpAllowedThroughPhase` of `schemas/phases.json` (Phase 1, where Step 1.4 captures the evidence record) unless the run is in `analysis` mode, and it appends every allowed call to `telemetry.mcpCalls[]` itself. Copilot CLI and Codex have no equivalent hook; there the record is still the phase's own write.
+
 Memory: [[mcp-only-in-analysis]]
 
 ### Phase Order (platform-agnostic)

package/pipeline/schemas/agent-state.schema.json

@@ -38,6 +38,10 @@
       "type": ["string", "null"],
       "description": "The Claude Code session id this run was launched under, copied by Phase 0 from MULTI_AGENT_SESSION_ID when the launcher set it. Continuous mode sets it to the id it passed as --session-id, and matches this field to find ITS run's state rather than another run in the same repo. Absent or null on an attended run: nothing sets the variable there."
     },
+    "hostSessionId": {
+      "type": ["string", "null"],
+      "description": "The host session that made this run's last phase transition: write-state.mjs copies CLAUDE_CODE_SESSION_ID from its environment when a write creates the state or sets currentPhase, and never otherwise, so a second session editing the state (steer) does not take the run over. run-stop-guard.mjs and run-scope-guard.mjs match it against a hook payload's session_id to find the run a hook call belongs to. Absent on a host that sets no such variable."
+    },
     "title": {
       "type": ["string", "null"],
       "description": "The issue title Phase 0 fetched (GitHub title, Jira summary). runs-index.mjs carries it as the run's title; absent when the input was free text or nothing was fetched."
@@ -275,9 +279,16 @@
       }
     },
     "waitingFor": {
-      "type": "string",
-      "enum": ["maturity", "user-channels-choice", "question"],
-      "description": "The step a paused run must RE-ENTER, as opposed to the phase it should continue past. resume reads this first and falls back to currentPhase + 1 when it is absent. maturity: Phase 0's maturity step, with the item re-fetched (refs/features/maturity-followup.md). user-channels-choice: Phase 5's channels menu, with the stored channelsInput. question: the step named by pendingQuestion.stepId, answered by `resume <id> --answer <optionId>`; open-questions-gate.mjs writes it as the last step of Phase 1 with stepId phase-1/open-questions."
+      "type": ["string", "null"],
+      "enum": [
+        "maturity",
+        "user-channels-choice",
+        "local-test",
+        "attended-reply",
+        "question",
+        null
+      ],
+      "description": "The step a paused run must RE-ENTER, as opposed to the phase it should continue past. resume reads this first and falls back to currentPhase + 1 when it is absent or null (null is how a wait is cleared through write-state). maturity: Phase 0's maturity step, with the item re-fetched (refs/features/maturity-followup.md). user-channels-choice: Phase 5's channels menu, with the stored channelsInput. local-test: Phase 3's user-test gate. attended-reply: a typed reply asked for in plain text inside currentPhase; resume re-enters currentPhase and asks again. question: the step named by pendingQuestion.stepId, answered by `resume <id> --answer <optionId>`, and never written without that pendingQuestion; open-questions-gate.mjs writes it as the last step of Phase 1 with stepId phase-1/open-questions. write-state clears every value but question when a write advances currentPhase."
     },
     "workspaceSource": {
       "type": "string",
@@ -497,7 +508,7 @@
     "status": {
       "type": "string",
       "enum": ["in_progress", "awaiting_input", "paused", "complete", "failed", "abandoned"],
-      "description": "Overall task status. `abandoned` is written through the locked state writer by the autopilot runner, for a run its session launched that ended with neither a PR nor a parked question, and by a kill; `abandonedBy` names the writer. `awaiting_input` is deliberately distinct from both `in_progress` and `paused`: the run is not broken and not resumable by a retry - it is finished with what it can do alone and is holding for a human answer, which is what Phase 5 does by design after the PR is open. Without a word for it, a run whose work had landed read exactly like one that crashed mid-development, and a state file in the wild had already invented `awaiting-user-test-main-checkout` to say it. `paused` stays what it was: stopped deliberately, resumable, nothing expected from anyone."
+      "description": "Overall task status. `complete` is earned, not claimed: write-state.mjs refuses a write that moves the run into it unless currentPhase is the mode's last phase and, for a mode that commits, Phase 4 left evidence (commit.sha, pr, publish, projects[].commit, or phases.4 skipped with notes) and gates[] holds a passing plan-coverage verdict (lib/run-completion.mjs); the autopilot runner files a complete state without that evidence as stopped-incomplete. `abandoned` is written through the locked state writer by the autopilot runner, for a run its session launched that ended with neither a PR nor a parked question, and by a kill; `abandonedBy` names the writer. `awaiting_input` is deliberately distinct from both `in_progress` and `paused`: the run is not broken and not resumable by a retry - it is finished with what it can do alone and is holding for a human answer, which is what Phase 5 does by design after the PR is open. Without a word for it, a run whose work had landed read exactly like one that crashed mid-development, and a state file in the wild had already invented `awaiting-user-test-main-checkout` to say it. `paused` stays what it was: stopped deliberately, resumable, nothing expected from anyone."
     },
     "abandonedBy": {
       "type": "string",
@@ -2059,7 +2070,7 @@
     },
     "gates": {
       "type": "array",
-      "description": "Gate ledger, written while the quality gates are active (lib/unattended.mjs gatesActive: MULTI_AGENT_UNATTENDED=1, or state.autopilot true): one entry per verdict, appended by gate-ledger.mjs under the write-state lock. With MULTI_AGENT_UNATTENDED=1 in its environment, pre-commit-check.sh blocks a commit unless the latest entry of every mandatory gate for HEAD is pass or not-applicable. Absent in a run with neither.",
+      "description": "Gate ledger, written while the quality gates are active (lib/unattended.mjs gatesActive: MULTI_AGENT_UNATTENDED=1, or state.autopilot true): one entry per verdict, appended by gate-ledger.mjs under the write-state lock. With MULTI_AGENT_UNATTENDED=1 in its environment, pre-commit-check.sh blocks a commit unless the latest entry of every mandatory gate for HEAD is pass or not-applicable. A run with neither records only the gates in gate-ledger.mjs ATTENDED_RECORDED, each entry marked attended: true, which the unattended commit check never counts.",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -2082,6 +2093,10 @@
             "type": ["string", "null"],
             "description": "Repository HEAD the gate ran against."
           },
+          "attended": {
+            "type": "boolean",
+            "description": "True on an entry written while the quality gates were off (an attended run). lib/run-completion.mjs and the attended commit check read it; gate-ledger.mjs checkCommit ignores it."
+          },
           "detail": {
             "type": "object",
             "additionalProperties": true

package/pipeline/schemas/phases.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/phases.json",
-  "description": "The phase contract, in one place: the phase ids and names, which phases each mode runs, the per-phase token ceilings and the phase numbers other code compares against. gen-mode-dispatch.mjs, render-work-summary.sh, the autopilot runner, runs-index.mjs, usage-report.mjs and gen-facts.mjs read it; smoke-phase-contract.sh holds every copy that cannot read it (the phase docs and prose counts, agent-state.schema.json, token-budget.json, phase-tracker.sh, phase-banner.sh, gc-abandoned.sh) to it. Adding or merging a phase means editing here. Ceilings are measured against the current phase documents, never summed from earlier ones: smoke-token-budget.sh fails a ceiling more than 25% above the measurement.",
+  "description": "The phase contract, in one place: the phase ids and names, which phases each mode runs, the per-phase token ceilings and the phase numbers other code compares against. gen-mode-dispatch.mjs, render-work-summary.sh, the autopilot runner, runs-index.mjs, usage-report.mjs and gen-facts.mjs read it; smoke-phase-contract.sh holds every copy that cannot read it (the phase docs and prose counts, agent-state.schema.json, token-budget.json, phase-tracker.sh, phase-banner.sh, gc-abandoned.sh) to it. Adding or merging a phase means editing here. A mode with `commits: false` delivers no commit in its Phase 4 (analysis publishes a document), so lib/run-completion.mjs asks it for no commit evidence before `status: complete`; any other mode commits. Ceilings are measured against the current phase documents, never summed from earlier ones: smoke-token-budget.sh fails a ceiling more than 25% above the measurement.",
   "contractVersion": "2.0.0",
   "phaseSchema": 2,
   "phaseSchemaNote": "The phase vocabulary generation. metrics.jsonl is append-only and v19.0.0 renumbered the phases, so every line written from v19.0.0 on carries this number and a line without the field is generation 1. Aggregators pick their name table from it; without it phase 3 means Dev in old rows and Review in new ones and no reader can tell them apart.",
@@ -72,7 +72,8 @@
     },
     "analysis": {
       "phases": [0, 1, 3, 4, 5],
-      "autopilot": false
+      "autopilot": false,
+      "commits": false
     }
   },
   "thresholds": {

package/pipeline/schemas/phases.schema.json

@@ -50,7 +50,11 @@
             "items": { "type": "integer", "minimum": 0 },
             "uniqueItems": true
           },
-          "autopilot": { "type": "boolean" }
+          "autopilot": { "type": "boolean" },
+          "commits": {
+            "type": "boolean",
+            "description": "false when the mode delivers no commit in its Phase 4; lib/run-completion.mjs then asks for no commit evidence before status complete. Absent means the mode commits."
+          }
         }
       }
     },

package/pipeline/schemas/prefs.schema.json

@@ -1872,6 +1872,43 @@
             "enabled": false
           }
         },
+        "stopGuard": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "run-stop-guard.sh, the Claude Code Stop hook that holds the session driving a pipeline run from ending its turn mid-phase with no halt or wait recorded. Read first on every Stop; false lets every stop through. Removing the hook from settings.json works too, and install does not add it back.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true,
+              "description": "true = the hook judges a stop as documented. false = it never blocks."
+            }
+          },
+          "default": {
+            "enabled": true
+          }
+        },
+        "readOnlyRepos": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "default": [],
+          "description": "Absolute paths (a leading ~ is expanded) of checkouts kept as read-only references: agent-guard.sh refuses an Edit, Write or NotebookEdit whose target is inside one, and a git commit, push, merge, cherry-pick, revert, am, rebase or tag that runs in one (after any cd or git -C on the line). Attended and unattended alike. Empty means no repository is protected this way."
+        },
+        "attendedCommitGate": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "What pre-commit-check.sh does with an attended `git commit` inside a pipeline run whose gate ledger holds no passing build and test verdict (evidence-gate/build, evidence-gate/test) for HEAD. evidence-gate.mjs records both in an attended run, marked attended. Read by gate-ledger.mjs `evidence`; a commit outside a run, or in a mode that commits nothing, is never checked. Unattended commits are held to the full ledger regardless of this setting.",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["off", "warn", "block"],
+              "default": "warn",
+              "description": "warn = say so on stderr and let the commit through. block = refuse the commit (exit 2) until the evidence is recorded. off = no check."
+            }
+          },
+          "default": {
+            "mode": "warn"
+          }
+        },
         "mutationProbe": {
           "type": "object",
           "additionalProperties": false,

package/pipeline/schemas/runs-index.schema.json

@@ -87,7 +87,7 @@
         "waitingFor": {
           "type": ["string", "null"],
           "x-sensitivity": "none",
-          "description": "The step a paused run re-enters (agent-state waitingFor): maturity, user-channels-choice or question. Added in 1.1.0."
+          "description": "The step a paused run re-enters (agent-state waitingFor): maturity, user-channels-choice, local-test, attended-reply or question; null or absent when the run is not waiting. Added in 1.1.0."
         },
         "pendingQuestion": {
           "x-sensitivity": "none",

package/pipeline/scripts/_active-run.mjs

@@ -0,0 +1,158 @@
+/**
+ * @file _active-run.mjs  -  which pipeline run a hook call belongs to, and where
+ * that run stands against its mode's phase list.
+ *
+ * A hook receives the host's session id and working directory, never a task id.
+ * A run is bound to a session by one of three facts, strongest first:
+ *
+ *   1. `sessionId` equals MULTI_AGENT_SESSION_ID in the hook's environment: the
+ *      id a launcher started the run with (continuous mode, a client).
+ *   2. `hostSessionId` equals the payload's `session_id`: write-state.mjs stamps
+ *      the host session that made the run's last phase transition
+ *      (CLAUDE_CODE_SESSION_ID), so the session driving a run is the one bound
+ *      to it, and a resume in a new session rebinds it at its first transition.
+ *   3. A state with no `hostSessionId` whose `worktreePath` is the git toplevel
+ *      of the payload's cwd: a run written before the stamp existed. A state
+ *      that carries a different `hostSessionId` is another session's run and
+ *      never matches this way.
+ *
+ * Nothing here decides anything; callers (run-stop-guard, run-scope-guard)
+ * apply their own rule to the run this returns. Zero runtime dependencies.
+ *
+ * @module pipeline/scripts/_active-run
+ */
+
+import { spawnSync } from "node:child_process";
+import { appendFileSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { listRuns, logsRoot, resolveRunFile } from "./_run-paths.mjs";
+
+export {
+  finalPhaseOf,
+  modeOf,
+  modePhases,
+  nextPhaseOf,
+  phaseContract,
+  phaseName,
+} from "../lib/run-completion.mjs";
+
+function real(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/** The git toplevel of `dir`, real-pathed, or null outside a repository. */
+export function gitToplevel(dir) {
+  if (!dir) return null;
+  const r = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  return r.status === 0 ? real(r.stdout.trim()) : null;
+}
+
+function mtime(p) {
+  try {
+    return statSync(p).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+const LIVE_STATUSES = new Set(["in_progress", "awaiting_input"]);
+
+/**
+ * The run bound to this hook call, or null.
+ *
+ * @param {{sessionId?: string|null, cwd?: string|null, env?: Record<string,string|undefined>}} opts
+ * @returns {{statePath: string, state: object, matchedBy: "session"|"host-session"|"worktree"} | null}
+ *   with `unreadable` (count of state files that did not parse) on the returned
+ *   object or on the `findActiveRun.lastUnreadable` property when nothing matched
+ */
+export function findActiveRun({ sessionId = null, cwd = null, env = process.env } = {}) {
+  const launched = env.MULTI_AGENT_SESSION_ID || "";
+  let top;
+  const topOf = () => {
+    if (top === undefined) top = cwd ? gitToplevel(cwd) : null;
+    return top;
+  };
+  const hits = [];
+  let unreadable = 0;
+  const prevRoot = process.env.LOGS_ROOT;
+  if (env.LOGS_ROOT !== undefined) process.env.LOGS_ROOT = env.LOGS_ROOT;
+  try {
+    for (const run of listRuns()) {
+      const p = resolveRunFile(run.taskId, "agent-state.json", run.project);
+      if (!p) continue;
+      const doc = readRegularJson(p, null);
+      if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+        unreadable += 1;
+        continue;
+      }
+      let matchedBy = null;
+      if (launched && doc.sessionId === launched) matchedBy = "session";
+      else if (sessionId && doc.hostSessionId === sessionId) matchedBy = "host-session";
+      else if (
+        !doc.hostSessionId &&
+        typeof doc.worktreePath === "string" &&
+        doc.worktreePath &&
+        topOf() &&
+        real(doc.worktreePath) === topOf()
+      ) {
+        matchedBy = "worktree";
+      }
+      if (matchedBy) hits.push({ statePath: p, state: doc, matchedBy, t: mtime(p) });
+    }
+  } finally {
+    if (prevRoot === undefined) delete process.env.LOGS_ROOT;
+    else process.env.LOGS_ROOT = prevRoot;
+  }
+  findActiveRun.lastUnreadable = unreadable;
+  if (!hits.length) return null;
+  const rank = { session: 0, "host-session": 1, worktree: 2 };
+  hits.sort((a, b) => rank[a.matchedBy] - rank[b.matchedBy] || b.t - a.t);
+  const lead = hits.filter((h) => h.matchedBy === hits[0].matchedBy);
+  // A session can hold a finished run next to a live one. The run started
+  // last is the one the session is on: a live run started after the finished
+  // one wins however recently the finished file was touched, and a live run
+  // started before it was abandoned without a halt and does not hold the
+  // session. startedAt orders them; the state's mtime stands in without it.
+  const started = (h) => Date.parse(h.state?.startedAt) || h.t;
+  const isLive = (h) => LIVE_STATUSES.has(h.state?.status);
+  const liveRun = lead.find(isLive);
+  const finished = lead.filter((h) => !isLive(h));
+  const lastFinished = finished.sort((a, b) => started(b) - started(a))[0];
+  let pick = lead[0];
+  if (liveRun)
+    pick = lastFinished && started(lastFinished) > started(liveRun) ? lastFinished : liveRun;
+  const { t: _t, ...best } = pick;
+  return { ...best, unreadable };
+}
+findActiveRun.lastUnreadable = 0;
+
+/**
+ * Append one line to the hook failure log under the log root. A hook that
+ * fails open says why somewhere a person can read later; this never throws.
+ *
+ * @param {string} hook
+ * @param {string} reason
+ * @param {Record<string,string|undefined>} [env]
+ */
+export function logHookFailure(hook, reason, env = process.env) {
+  try {
+    const root = env.LOGS_ROOT || logsRoot();
+    mkdirSync(root, { recursive: true });
+    const line = `${new Date().toISOString()} ${hook}: ${String(reason).replace(/\s+/g, " ")}\n`;
+    appendFileSync(join(root, "hook-failures.log"), line);
+  } catch {
+    // Logging is best-effort; the hook's verdict never depends on it.
+  }
+}
+
+/** The run directory that holds a state file. */
+export const runDirOf = (statePath) => dirname(statePath);

package/pipeline/scripts/_autopilot-outcomes.mjs

@@ -27,6 +27,7 @@ export const OUTCOME = Object.freeze({
   MERGED: "merged",
   SKIPPED: "skipped",
   COMPLETED_NO_PR: "completed-no-pr",
+  STOPPED_INCOMPLETE: "stopped-incomplete",
   NEEDS_INPUT: "needs-input",
   AWAITING_ANSWER: "awaiting-answer",
   VERIFICATION_FAILED: "verification-failed",