@ai-dossier/sched 0.2.1 → 0.4.0

package/README.md

@@ -3,11 +3,15 @@
 [![npm](https://img.shields.io/npm/v/@ai-dossier/sched.svg)](https://www.npmjs.com/package/@ai-dossier/sched)
 
 Deterministic scheduler core for dossier batch cycles — queue, worker slots, typed state
-machines, crash-safe persistence, and (since #464) the **dispatch engine**: spawning agent
-processes, verifying their completion against ground truth, and mechanizing the
-stall/escalation ladder. The scheduler itself **never invokes an LLM** — it spawns the
-agent process the operator configured and reconciles the durable record
-(`ai-dossier runstate` / `gh` / `git`) that the spawned run leaves behind.
+machines, crash-safe persistence, the **dispatch engine** (#464: spawning agent
+processes, verifying their completion against ground truth, mechanizing the
+stall/escalation ladder), and since #468 the **PR watcher + tail work** (parked-PR
+watching, script-based teardown, cheap-tier report dispatch — retiring the fleet
+pattern of re-dispatching a full-cycle run for the tail), and since #472 **batch failure
+recovery** (attribution, bisect, one bounded fix, eviction, dissolve). The scheduler itself **never
+invokes an LLM** — it spawns the agent process the operator configured and reconciles
+the durable record (`ai-dossier runstate` / `gh` / `git`) that the spawned run leaves
+behind.
 
 Design: RFC-0001 *Batch Cycles* §B/C.1/D (the RFC lives on branch `docs/batch-cycles-rfc`,
 not yet merged to `main`; the §D state machines are frozen verbatim into the types below).
@@ -17,14 +21,14 @@ this state machine makes impossible to forget.
 
 ## CLI surface
 
-Consumed through the monorepo CLI (`@ai-dossier/cli` ≥ 0.18.0):
+Consumed through the monorepo CLI (`@ai-dossier/cli` ≥ 0.19.0):
 
 ```bash
 ai-dossier sched enqueue --issues 101,105..109 --deps 100 --tier strong   # flags
 ai-dossier sched enqueue --from-manifest batch-prep.json                  # batch-prep output
-ai-dossier sched start            # the dispatch engine: spawn, verify, escalate (Ctrl-C stops it)
+ai-dossier sched start            # the dispatch engine: spawn, verify, escalate, watch parked PRs (Ctrl-C stops it)
 ai-dossier sched start --once     # a single reconcile+refill tick (cron-style)
-ai-dossier sched status           # queue, slots (pid/phase/last-progress), batches, blocked/failed
+ai-dossier sched status           # queue (+pr/cleanup), parked PRs, slots, batches, blocked/failed
 ai-dossier sched pause            # stop NEW assignments; live units keep running
 ai-dossier sched resume
 ai-dossier sched abandon --issue 42 --reason "operator abort"
@@ -82,6 +86,77 @@ Two engine-safety policies were explicit product decisions on #464:
 Only `issue:<n>` units are dispatched today — batch member sequencing is a follow-up
 (#464 non-goal).
 
+## Batch failure recovery (#472)
+
+What happens when a batch's aggregate suite goes red, or its PR will not merge
+(RFC-0001 §F.2/F.8/F.9).
+
+**Not yet wired into `sched start`** — `tick()` still dispatches only `issue:<n>` units
+(the batch execution loop is a follow-up, see above). These modules are the library
+surface that loop will call, and they are tested standalone against real scratch repos.
+
+```
+validating → attributing → fixing (ONE bounded attempt) → validating
+                         → evicting (revert the member's commits) → validating
+  > ⅓ of members evicted, or a revert conflict → dissolving → members requeued
+awaiting-merge (CONFLICTING | auto-merge-blocked)
+                         → rebasing → re-validating → shipping
+                         → (2nd occurrence) dissolving into two half-batches
+```
+
+1. **Attribution (AC1)** — `attributeByOverlap` maps each failing test to a member by
+   focused-test match, then by changed-path overlap. Exactly one candidate attributes;
+   more than one is AMBIGUOUS and none is UNATTRIBUTED — neither is ever guessed. When
+   the caller supplies a `BisectSpec`, both go to `runAttributionBisect`: a real
+   `git bisect run` over the branch's `good..bad` range executing ONLY the failing tests,
+   whose first-bad commit is mapped to a member through the `(#N)` subject trailer on the
+   branch's issue-boundary commits (every unresolved test is then attributed to that
+   member). A first-bad commit with no trailer, or an abbreviated sha matching two
+   commits, reports `unattributable` rather than blaming a neighbour. The bisect refuses
+   to run at all unless the test command actually discriminates — it must fail at `bad`
+   AND pass at `good`, so a missing runner cannot silently convict the earliest member —
+   and it always resets the checkout to where it found it. Without a `BisectSpec`,
+   overlap is the whole verdict and unresolved tests stay unattributed.
+2. **One bounded fix attempt (AC2)** — `beginFixAttempt` returns the mid-tier command and
+   prompt for the CALLER to spawn (sched never invokes an LLM) and records the attempt.
+   A second call for the same member returns `null`: the next step is eviction, so a
+   batch cannot burn its budget on one broken member.
+3. **Eviction (AC2)** — `evictMembers` reverts the member's commits newest-first across
+   members (an eviction group reverts together), requeues it as full-cycle with
+   `failure_evidence` attached (batch, reason, failing tests, attribution method, reverted
+   commits), re-runs the suite and checks the dissolve trigger. A conflicting revert is
+   aborted so the worktree is clean and the batch dissolves — the reverts that already
+   landed ride along on the abandoned branch, which is why it is abandoned rather than
+   reused. An eviction group that reaches an already-shipped member dissolves instead of
+   reverting merged work.
+4. **Dissolve (AC3)** — `dissolveBatch` marks the batch `dissolved` and requeues every
+   UNSHIPPED member: `full` (each as its own full-cycle run) or `halved` (one or two fresh
+   `forming` half-batches — a single remaining member yields one — entries retagged,
+   eviction groups inherited where they survive the split). Shipped and terminal members
+   keep their outcome; nothing green is discarded, and no git runs — the batch branch is
+   simply left behind unmerged, since sched deletes nothing.
+5. **PR conflict (AC4)** — `handlePrConflict` rebases the batch branch, re-runs the suite
+   and re-ships ONCE. A second occurrence, a conflicting rebase, a failed fetch, an
+   unusable `base_branch`, a checkout that is not on the batch branch, or a red suite
+   after a clean rebase dissolves into two half-batches.
+6. **Milestones (AC5)** — every eviction and dissolve posts a `batch-validate` /
+   `batch-ship` milestone to the batch ANCHOR issue via `ai-dossier runstate post`, with
+   the reason, the evicted/requeued/preserved members and the attribution method (a
+   successful re-ship posts `batch-ship awaiting-merge`); each per-member outcome is
+   journaled and kept in the batch's `evictions` (the classifier feedback signal). A batch
+   with no `anchor` or no `run_id` cannot post — the CLI requires both — so the milestone
+   it could not post is journaled in full instead of vanishing.
+
+Ten journal events carry the detail: `suite-failed`, `attributed`, `fix-dispatched`,
+`fix-resolved`, `member-evicted`, `revert-conflict`, `batch-rebased`, `batch-dissolved`,
+`batch-split` and `milestone-post-failed`, plus `git-failed` for any git command that
+returned non-zero (the injected `ExecFn` collapses every git failure into `null`, so the
+command that produced one is always recorded).
+
+Schema 1.3.0 carries the new state: `BatchEntry` gains `anchor`, `branch`, `run_id`,
+`eviction_groups`, `evictions`, `fix_attempts` and `rebase_attempts`; `QueueEntry` gains
+`failure_evidence`. 1.2.0 states migrate on load.
+
 ## API surface
 
 ```ts
@@ -91,13 +166,46 @@ import {
   parseManifest,         // batch-prep JSON → EnqueueInput[]
   computeAssignments,    // pure: fill idle slots with runnable units, bounded by max_slots
   runnableUnits,         // pure: which units may run right now (dep-gated)
-  tick,                  // one engine cycle: reconcile + verify + refill + spawn
+  tick,                  // one engine cycle: reconcile + verify + refill + spawn,
+                         //   and since #468: park-watch, teardown, report dispatch
   runLoop,               // the sched start loop (tick, sleep, repeat)
-  type TickResult,       // what one tick did (spawned/completed/redispatched/failed/blocked)
-  type EngineDeps,       // inject everything the engine touches (store/journal/spawn/ground truth/clock)
+  type TickResult,       // what one tick did (spawned/parked/merge-accepted/report-dispatched/
+                         //   teardown/completed/redispatched/failed/blocked)
+  type EngineDeps,       // inject everything the engine touches (store/journal/spawn/ground
+                         //   truth/clock/repoDir/teardownExec)
   createSpawnDeps,       // real detached-spawn process I/O
-  createExecGroundTruth, // runstate/gh/git ground truth via subprocesses (injectable exec)
-  resolveDispatch,       // config → resolved command/prompt/tier-models/timers
+  createExecGroundTruth, // runstate/gh/git ground truth via subprocesses (injectable exec);
+                         //   since #468 also gh pr view PR state + setup info from comments
+  resolveDispatch,       // config → resolved command/prompt/report-prompt/tier-models/timers
+  buildReportPrompt,     // report-agent prompt ({issue}/{pr}/{cleanup} substituted)
+  reportTierFor,         // report (re)dispatch tier after N escalations
+  isParkedMilestone,     // ship-phase awaiting-merge + pr= → the park signal
+  prOfMilestone,         // a milestone's pr= key as a positive integer
+  parsePrViewJson,       // gh pr view --json → PR truth (mergedAt/mergeable/blocked label)
+  parseSetupInfo,        // gh issue view --json comments → teardown inputs
+  runTeardown,           // #468 script teardown for a merged unit (pool return / worktree remove)
+  isSafeWorktree,        // worktree-path containment check (CWE-22)
+  TEARDOWN_TIMEOUT_MS,   // teardown subprocess timeout (120 s)
+  attributeByOverlap,    // #472 pure stage-1 attribution: failing tests → members
+  parseVitestJson,       // vitest --reporter=json → failing tests
+  parseBoundaryCommits,  // git log → issue-boundary commits via the (#N) trailer
+  memberRanges,          // boundary commits → each member's commit list
+  runAttributionBisect,  // stage-2: real git bisect over the failing tests only
+  beginAttribution,      // validating → attributing (overlap, then bisect if needed)
+  beginFixAttempt,       // the ONE bounded mid-tier fix dispatch instruction
+  resolveFixAttempt,     // record its outcome, back to validating
+  evictMembers,          // revert + requeue with evidence + suite re-run + dissolve check
+  checkDissolveTrigger,  // pure: > ⅓ of members evicted
+  dissolveBatch,         // full or halved dissolve; preserves everything green
+  handlePrConflict,      // rebase + re-ship once, then dissolve into halves
+  createExecMilestonePoster, // batch milestones via `ai-dossier runstate post`
+  expandEvictionGroups,  // members that must revert together (§E.4 eviction groups)
+  requeueMember,         // the one requeue path abandon/evict/dissolve all take
+  isPreservedMember,     // the single definition of "already green"
+  createBatch,           // the single BatchEntry constructor
+  type RecoveryDeps,     // inject exec/repoDir/journal/milestone-poster/suite-runner/clock
+  type SuiteRunner,      // re-runs the aggregate suite after a revert or rebase
+  type BatchMilestonePoster, // batch-milestone sink (createExecMilestonePoster is default)
   Journal,               // append-only events.jsonl
   transitionIssue, transitionBatch, transitionSlot,  // typed §D transitions
   TRANSITIONS,           // the transition tables themselves (for previews)
@@ -119,7 +227,8 @@ fake agents and stub ground truth; no LLM calls anywhere.
 ```
 ~/.dossier/sched/<project>/
 ├── state.json     # hot operational truth — atomic tmp+fsync+rename writes;
-├── config.json    # durable intent: max_slots, stall_timeout_ms, reconcile_interval_ms, dispatch
+├── config.json    # durable intent: max_slots, stall_timeout_ms, reconcile_interval_ms,
+│                  # pr_poll_interval_ms, dispatch (incl. report_prompt)
 ├── events.jsonl   # append-only event journal (the operator's flight recorder)
 ├── runs/          # per-unit agent output logs (issue-<n>.log)
 └── .sched-lock/   # cross-process directory mutex (pid; stolen from dead holders)
@@ -133,14 +242,65 @@ fake agents and stub ground truth; no LLM calls anywhere.
 - **Corrupt state is loud**: `load()` throws `CorruptStateError` naming the file —
   never a silent queue reset. `state.json` is deletable and rebuildable from GitHub,
   which remains the system of record.
-- **Schema**: state/config files from #460 (schema 1.0.0) load and migrate to 1.1.0
-  automatically (slot `branch`/`last_head` backfill to null).
+- **Schema**: state/config files from #460 (schema 1.0.0), #464 (1.1.0) and #468 (1.2.0)
+  load and migrate to 1.3.0 automatically (slot `branch`/`last_head`/`pid_start`, entry
+  `pr`/`cleanup`/`failure_evidence`, batch `anchor`/`branch`/`run_id`/`eviction_groups`/
+  `evictions`/`fix_attempts`/`rebase_attempts`,
+  and state-level `last_pr_poll_at` backfill to null).
 - **`max_slots`** bounds live units (`assigned | running | recovering`); dependency
   edges gate readiness — an issue with an unmerged dependency, and a batch behind an
   unmerged batch, are never runnable.
 - **Pause** stops new assignments only; abandon routes through the typed failure rails
   (`evicted → requeued{full}` for batch members — nothing green is discarded).
 
+## The PR watcher + tail work (#468)
+
+Dispatched runs park their PR on `auto-merge` (detached ship mode — the default
+prompt instructs it) and exit. The engine owns everything after the park:
+
+1. **Park detection (AC1)** — an agent exit whose latest milestone is the ship
+   phase's `awaiting-merge` (with `pr=`) is a VERIFIED park, not an unverified
+   exit: the entry moves to `parked`, the slot is released (a waiting unit
+   consumes zero slots), and the watcher takes over.
+2. **PR watching (AC1)** — parked PRs are polled every `pr_poll_interval_ms`
+   (default 150 s — "every 2–3 min", persisted `last_pr_poll_at` so a restart
+   honors the cadence; checked on each reconcile tick when due, so a
+   `reconcile_interval_ms` longer than the interval slows the effective cadence)
+   via `gh pr view --json state,mergedAt,mergeable,labels`.
+   A merge is accepted only when state is MERGED **and** `mergedAt` is non-null
+   **and** the issue is closed — never inferred from an agent exit. An
+   unreachable poll pauses the watcher (decision 2, option A).
+3. **Failure states (AC3)** — `CONFLICTING`, closed-unmerged, or the
+   `auto-merge-blocked` label fail the unit with the reason and block its
+   TRANSITIVE dependents. The engine never merges anything itself.
+4. **Gating on MERGE, not park (AC4)** — `parked` is not a satisfied status:
+   dependents stay blocked until the merge lands (`parked → shipped`).
+5. **Teardown as a script (AC2)** — on merge, the run's setup milestone
+   (recovered once from the issue's comments — collaborator-authored only, and
+   the worktree path must pass a containment check before any destructive
+   subprocess) chooses the script: pool-claimed worktrees run
+   `worktree-pool return --path <wt> --json` (the pool's own self-check is the
+   verification); cold worktrees run
+   `git worktree remove --force <wt>` with a path-gone check. Both are
+   verify-first idempotent; a failed step records `cleanup=failed-<step>` on
+   the entry and in the journal — degradation, never unit failure.
+6. **Report dispatch (AC2)** — once teardown is recorded (when a slot is
+   free — a waiting report consumes zero slots), a **mechanical-tier** report
+   agent is spawned with the report-phase prompt (`dispatch.report_prompt`;
+   `{issue}`/`{pr}`/`{cleanup}` substituted — the cleanup status rides into
+   the report). It completes like any agent; a report that stalls climbs the
+   same ladder (mechanical → mid → strong, cap 2), and at the cap the unit
+   completes (`done`, reason `report-escalation-cap`) with a `report-failed`
+   journal event — the work is merged, so dependents are never re-blocked.
+   The full-cycle tail-run pattern (re-dispatching a whole run for
+   teardown+report) is retired.
+
+`sched status` shows parked PRs (zero slots, with the last poll's age), a
+`pr` column and a `cleanup` column on the queue; every watcher decision lands
+in `events.jsonl` (`pr-parked`, `merge-accepted`, `pr-watch-failed`,
+`pr-watch-waiting`, `teardown-done`/`teardown-failed`, `report-dispatched`,
+`report-failed`, `ground-truth-unreachable`).
+
 ## Development
 
 ```bash
@@ -152,4 +312,6 @@ npm test         # vitest — state machines, persistence, crash/restart, engine
 
 No network, no GitHub in unit tests — persistence tests run on temp directories; the
 integration tests spawn fake-agent fixtures against a scratch git repo with stubbed
-ground truth.
+ground truth. The #468 integration tests run the full detached-ship tail
+(park → watch → merge → REAL worktree removal → report) end-to-end, including a
+sched restart mid-watch.

package/dist/attribution.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Failure attribution, stage 1 (#472 AC1): map failing tests to batch members
+ * without an LLM, using only what the batch run already recorded.
+ *
+ * Two overlap signals, in order of confidence:
+ *   1. **focused tests** — the member's own plan/implement phase named these
+ *      test files; a failure in one of them is that member's.
+ *   2. **changed paths** — the failing test file was changed by the member, or
+ *      sits under a directory the member changed (the `src/x.ts` →
+ *      `src/__tests__/x.test.ts` relationship, expressed structurally rather
+ *      than by naming convention).
+ *
+ * A test with exactly one candidate member is ATTRIBUTED; more than one is
+ * AMBIGUOUS and none is UNATTRIBUTED. Both of those go to stage 2 (`bisect.ts`)
+ * — this module never guesses, because a wrong attribution evicts innocent
+ * work. Everything here is pure; `recovery.ts` owns the effects.
+ */
+/** One failing test, as the aggregate suite reported it. */
+export interface FailingTest {
+    /** Test file path, repo-relative where the runner reports it that way. */
+    file: string;
+    /** Full test name (describe path + title). */
+    name: string;
+    /** Stable id used in evidence and journal lines: `<file>::<name>`. */
+    id: string;
+}
+/** What one batch member touched — the attribution surface, recorded as it ran. */
+export interface MemberFootprint {
+    issue: number;
+    /** Repo-relative paths the member's commits changed. */
+    changedPaths: string[];
+    /** Test files the member's own phases ran focused (strongest signal). */
+    focusedTests: string[];
+}
+/** A failing test that could belong to more than one member. */
+export interface AmbiguousTest {
+    test: FailingTest;
+    /** Member issue numbers that all overlap it, ascending. */
+    candidates: number[];
+}
+/** Stage-1 attribution verdict for one suite run. */
+export interface OverlapAttribution {
+    /** Member issue → the failing tests uniquely attributed to it. */
+    attributed: Map<number, FailingTest[]>;
+    /** Tests overlapping several members — bisect decides. */
+    ambiguous: AmbiguousTest[];
+    /** Tests overlapping no member at all — bisect decides. */
+    unattributed: FailingTest[];
+}
+/** Build a `FailingTest` with the derived id, so the id format exists once. */
+export declare function failingTest(file: string, name: string): FailingTest;
+/**
+ * Stage-1 attribution: overlap only, no git, no LLM (AC1). Deterministic —
+ * candidates are compared in ascending issue order so the same inputs always
+ * produce the same verdict.
+ */
+export declare function attributeByOverlap(failing: readonly FailingTest[], footprints: readonly MemberFootprint[]): OverlapAttribution;
+/** Members with at least one failing test attributed to them, ascending. */
+export declare function offendersOf(attributed: ReadonlyMap<number, unknown>): number[];
+/**
+ * Failing tests from `vitest run --reporter=json` output. Tolerates the
+ * surrounding noise a real run prints around the JSON document (vitest writes
+ * the report to stdout alongside its own banner), and skips any record it
+ * cannot read rather than throwing — an unparseable suite report degrades to
+ * "no attributable tests", which routes to bisect, never to a guess.
+ */
+export declare function parseVitestJson(stdout: string | null): FailingTest[];
+/** One commit on the batch branch, with the member it belongs to. */
+export interface BoundaryCommit {
+    sha: string;
+    subject: string;
+    /** Member issue from the `(#N)` subject trailer; null when the commit has none. */
+    issue: number | null;
+}
+/**
+ * A full or abbreviated sha as git prints it — 7 to 40 hex characters. Bisect
+ * endpoints and revert argv are validated against this before they become git
+ * arguments (CWE-88).
+ */
+export declare const SHA_RE: RegExp;
+/**
+ * A git ref name safe to interpolate into argv (CWE-88) — the pattern
+ * `groundtruth.ts` established for branch names off untrusted milestone text.
+ * Defined here, beside `SHA_RE`, so the package has one "validate before it
+ * becomes a git argument" home rather than a copy per module.
+ */
+export declare const SAFE_REF_RE: RegExp;
+/**
+ * Parse `git log --reverse --format=%H%x09%s <base>..<head>` — OLDEST FIRST,
+ * which is the order eviction ranges and bisect boundaries are built in.
+ * Malformed lines are skipped; a line whose subject has no `(#N)` trailer
+ * still yields a commit, with `issue: null`.
+ */
+export declare function parseBoundaryCommits(gitLogOutput: string | null): BoundaryCommit[];
+/** The commits one member contributed to the batch branch, oldest first. */
+export interface MemberRange {
+    issue: number;
+    /** Oldest commit of the member. */
+    from: string;
+    /** Newest commit of the member. */
+    to: string;
+    /** Every commit of the member, oldest first. */
+    commits: string[];
+    /**
+     * Each commit's index in the boundary list, parallel to `commits`. Grouping
+     * by member loses branch order; eviction needs it back to revert newest-first
+     * ACROSS members (see `memberRanges`).
+     */
+    positions: number[];
+}
+/**
+ * Group boundary commits (oldest first) by member.
+ *
+ * `from`/`to` describe the member's span for reporting; `commits` is what a
+ * revert actually walks. They differ when members interleave — reverting the
+ * literal `from^..to` range would then revert a neighbour's commits too, so
+ * eviction reverts the explicit commits instead, ordered by `positions`:
+ * for a branch `A1 B1 A2 B2`, evicting both members must revert
+ * `B2 A2 B1 A1`, not each member's commits as a block.
+ */
+export declare function memberRanges(boundary: readonly BoundaryCommit[]): MemberRange[];
+/**
+ * The member owning `sha`, or null when the commit carries no `(#N)` trailer.
+ *
+ * Either side may be abbreviated (bisect reports a short sha; boundary commits
+ * are full), so matching is prefix-based — but an AMBIGUOUS prefix returns null
+ * rather than the first hit. Attribution feeds eviction, and eviction reverts
+ * work: a wrong answer here destroys an innocent member's commits, so "cannot
+ * tell" must never collapse into "probably this one".
+ */
+export declare function memberOfCommit(boundary: readonly BoundaryCommit[], sha: string): number | null;
+//# sourceMappingURL=attribution.d.ts.map

package/dist/attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,yEAAyE;IACzE,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IACvC,0DAA0D;IAC1D,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAEnE;AAqCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,kBAAkB,CAwBpB;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAE9E;AAID;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,EAAE,CA0BpE;AAiCD,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AASD;;;;GAIG;AACH,eAAO,MAAM,MAAM,QAAsB,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,EAAE,CAalF;AAED,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,WAAW,EAAE,CAgB/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS9F"}

package/dist/attribution.js

@@ -0,0 +1,268 @@
+"use strict";
+/**
+ * Failure attribution, stage 1 (#472 AC1): map failing tests to batch members
+ * without an LLM, using only what the batch run already recorded.
+ *
+ * Two overlap signals, in order of confidence:
+ *   1. **focused tests** — the member's own plan/implement phase named these
+ *      test files; a failure in one of them is that member's.
+ *   2. **changed paths** — the failing test file was changed by the member, or
+ *      sits under a directory the member changed (the `src/x.ts` →
+ *      `src/__tests__/x.test.ts` relationship, expressed structurally rather
+ *      than by naming convention).
+ *
+ * A test with exactly one candidate member is ATTRIBUTED; more than one is
+ * AMBIGUOUS and none is UNATTRIBUTED. Both of those go to stage 2 (`bisect.ts`)
+ * — this module never guesses, because a wrong attribution evicts innocent
+ * work. Everything here is pure; `recovery.ts` owns the effects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAFE_REF_RE = exports.SHA_RE = void 0;
+exports.failingTest = failingTest;
+exports.attributeByOverlap = attributeByOverlap;
+exports.offendersOf = offendersOf;
+exports.parseVitestJson = parseVitestJson;
+exports.parseBoundaryCommits = parseBoundaryCommits;
+exports.memberRanges = memberRanges;
+exports.memberOfCommit = memberOfCommit;
+/** Build a `FailingTest` with the derived id, so the id format exists once. */
+function failingTest(file, name) {
+    return { file, name, id: `${file}::${name}` };
+}
+/** Normalize a path for comparison: strip `./`, collapse `\` to `/`, drop a trailing `/`. */
+function normalizePath(p) {
+    const slashed = p.replaceAll('\\', '/').replace(/^\.\//, '');
+    return slashed.endsWith('/') ? slashed.slice(0, -1) : slashed;
+}
+/** The directory part of a path, or `''` for a top-level file. */
+function dirOf(p) {
+    const idx = p.lastIndexOf('/');
+    return idx === -1 ? '' : p.slice(0, idx);
+}
+/** Whether `member` explicitly ran `normalizedFile` focused — the strongest signal. */
+function focusesOn(member, normalizedFile) {
+    return member.focusedTests.some((t) => normalizePath(t) === normalizedFile);
+}
+/**
+ * Whether `member` overlaps `testFile`. Focused tests win outright; otherwise
+ * the file must be one the member changed, or live under a directory it
+ * changed. A member that changed only top-level files (dir `''`) never matches
+ * by directory — an empty prefix would otherwise own the entire repo.
+ */
+function overlaps(member, testFile) {
+    const file = normalizePath(testFile);
+    if (focusesOn(member, file))
+        return true;
+    for (const raw of member.changedPaths) {
+        const changed = normalizePath(raw);
+        if (changed === file)
+            return true;
+        const dir = dirOf(changed);
+        if (dir !== '' && file.startsWith(`${dir}/`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Stage-1 attribution: overlap only, no git, no LLM (AC1). Deterministic —
+ * candidates are compared in ascending issue order so the same inputs always
+ * produce the same verdict.
+ */
+function attributeByOverlap(failing, footprints) {
+    const attributed = new Map();
+    const ambiguous = [];
+    const unattributed = [];
+    const members = [...footprints].sort((a, b) => a.issue - b.issue);
+    for (const test of failing) {
+        // A focused-test match is the stronger signal: when any member claims the
+        // file explicitly, members that merely changed a neighbouring path are not
+        // candidates — otherwise the strong signal could never break a tie.
+        const file = normalizePath(test.file);
+        const focused = members.filter((m) => focusesOn(m, file));
+        const candidates = focused.length > 0 ? focused : members.filter((m) => overlaps(m, test.file));
+        if (candidates.length === 1) {
+            const issue = candidates[0].issue;
+            attributed.set(issue, [...(attributed.get(issue) ?? []), test]);
+        }
+        else if (candidates.length > 1) {
+            ambiguous.push({ test, candidates: candidates.map((m) => m.issue) });
+        }
+        else {
+            unattributed.push(test);
+        }
+    }
+    return { attributed, ambiguous, unattributed };
+}
+/** Members with at least one failing test attributed to them, ascending. */
+function offendersOf(attributed) {
+    return [...attributed.keys()].sort((a, b) => a - b);
+}
+// --- Parsers ---
+/**
+ * Failing tests from `vitest run --reporter=json` output. Tolerates the
+ * surrounding noise a real run prints around the JSON document (vitest writes
+ * the report to stdout alongside its own banner), and skips any record it
+ * cannot read rather than throwing — an unparseable suite report degrades to
+ * "no attributable tests", which routes to bisect, never to a guess.
+ */
+function parseVitestJson(stdout) {
+    if (stdout === null)
+        return [];
+    const parsed = extractJsonObject(stdout);
+    if (parsed === null)
+        return [];
+    const results = parsed.testResults;
+    if (!Array.isArray(results))
+        return [];
+    const out = [];
+    for (const raw of results) {
+        if (raw === null || typeof raw !== 'object')
+            continue;
+        const suite = raw;
+        const file = typeof suite.name === 'string' ? suite.name : null;
+        if (file === null || !Array.isArray(suite.assertionResults))
+            continue;
+        for (const rawAssertion of suite.assertionResults) {
+            if (rawAssertion === null || typeof rawAssertion !== 'object')
+                continue;
+            const assertion = rawAssertion;
+            if (assertion.status !== 'failed')
+                continue;
+            const name = typeof assertion.fullName === 'string'
+                ? assertion.fullName
+                : typeof assertion.title === 'string'
+                    ? assertion.title
+                    : '';
+            out.push(failingTest(file, name));
+        }
+    }
+    return out;
+}
+/** The first balanced `{...}` document in `text`, parsed; null when there is none. */
+function extractJsonObject(text) {
+    const start = text.indexOf('{');
+    if (start === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                try {
+                    return JSON.parse(text.slice(start, i + 1));
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * The established commit ↔ member key: the `(#N)` trailer a squash-merge (and
+ * this project's commit convention) leaves at the end of the subject. A commit
+ * WITHOUT one maps to `issue: null` — unattributable, never a guess.
+ */
+const ISSUE_TRAILER_RE = /\(#(\d+)\)\s*$/;
+/**
+ * A full or abbreviated sha as git prints it — 7 to 40 hex characters. Bisect
+ * endpoints and revert argv are validated against this before they become git
+ * arguments (CWE-88).
+ */
+exports.SHA_RE = /^[0-9a-f]{7,40}$/i;
+/**
+ * A git ref name safe to interpolate into argv (CWE-88) — the pattern
+ * `groundtruth.ts` established for branch names off untrusted milestone text.
+ * Defined here, beside `SHA_RE`, so the package has one "validate before it
+ * becomes a git argument" home rather than a copy per module.
+ */
+exports.SAFE_REF_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+/**
+ * Parse `git log --reverse --format=%H%x09%s <base>..<head>` — OLDEST FIRST,
+ * which is the order eviction ranges and bisect boundaries are built in.
+ * Malformed lines are skipped; a line whose subject has no `(#N)` trailer
+ * still yields a commit, with `issue: null`.
+ */
+function parseBoundaryCommits(gitLogOutput) {
+    if (gitLogOutput === null)
+        return [];
+    const out = [];
+    for (const line of gitLogOutput.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const tab = line.indexOf('\t');
+        const sha = (tab === -1 ? line : line.slice(0, tab)).trim();
+        if (!exports.SHA_RE.test(sha))
+            continue;
+        const subject = tab === -1 ? '' : line.slice(tab + 1);
+        const match = ISSUE_TRAILER_RE.exec(subject);
+        out.push({ sha, subject, issue: match ? Number.parseInt(match[1], 10) : null });
+    }
+    return out;
+}
+/**
+ * Group boundary commits (oldest first) by member.
+ *
+ * `from`/`to` describe the member's span for reporting; `commits` is what a
+ * revert actually walks. They differ when members interleave — reverting the
+ * literal `from^..to` range would then revert a neighbour's commits too, so
+ * eviction reverts the explicit commits instead, ordered by `positions`:
+ * for a branch `A1 B1 A2 B2`, evicting both members must revert
+ * `B2 A2 B1 A1`, not each member's commits as a block.
+ */
+function memberRanges(boundary) {
+    const byIssue = new Map();
+    boundary.forEach((commit, position) => {
+        if (commit.issue === null)
+            return;
+        const group = byIssue.get(commit.issue) ?? { commits: [], positions: [] };
+        group.commits.push(commit.sha);
+        group.positions.push(position);
+        byIssue.set(commit.issue, group);
+    });
+    return [...byIssue.entries()].map(([issue, group]) => ({
+        issue,
+        from: group.commits[0],
+        to: group.commits[group.commits.length - 1],
+        commits: group.commits,
+        positions: group.positions,
+    }));
+}
+/**
+ * The member owning `sha`, or null when the commit carries no `(#N)` trailer.
+ *
+ * Either side may be abbreviated (bisect reports a short sha; boundary commits
+ * are full), so matching is prefix-based — but an AMBIGUOUS prefix returns null
+ * rather than the first hit. Attribution feeds eviction, and eviction reverts
+ * work: a wrong answer here destroys an innocent member's commits, so "cannot
+ * tell" must never collapse into "probably this one".
+ */
+function memberOfCommit(boundary, sha) {
+    const needle = sha.toLowerCase();
+    const matches = boundary.filter((c) => {
+        const candidate = c.sha.toLowerCase();
+        return candidate.startsWith(needle) || needle.startsWith(candidate);
+    });
+    const issues = new Set(matches.map((m) => m.issue));
+    if (matches.length === 0 || issues.size > 1)
+        return null;
+    return matches[0].issue;
+}
+//# sourceMappingURL=attribution.js.map