@delegance/claude-autopilot 7.9.1 → 7.10.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 - v5.6 Phase 7 (docs reconciliation) — pending.
 
+## 7.10.0 — 2026-05-13
+
+### Added
+- **Retry-loop sameness detector** (`src/core/run-state/sameness-detector.ts`) — new pure-TS module exporting `computeFingerprint`, `isSameFailure`, `shouldEscalate`, and `stripVolatileTokens`. A failure fingerprint is `{ phase, errorType, errorLocation, errorMessage, hash }` where `hash` is `sha256(JSON.stringify([phase, errorType, errorLocation, normalize(message[:200])]))`. JSON encoding is delimiter-safe — pipes, quotes, and embedded JSON in fields cannot produce cross-tuple collisions. `shouldEscalate(history)` returns `{ escalate: true }` when the last two entries have identical hashes — the signal that retries are making no progress.
+- **Volatile-token stripping built into the detector.** Both `errorLocation` and `errorMessage` are scrubbed of UUIDs, ISO timestamps, 13-digit epoch ms, sha1/sha256 hex digests, /tmp + /var/folders paths, and localhost:port before hashing — so a retry whose message differs only in a per-run UUID or temp directory still hashes to the same fingerprint. Exported as `stripVolatileTokens()` for callers that want to scrub before constructing a fingerprint.
+- **Public package subpath export.** `package.json` adds `./run-state/sameness-detector` pointing at `dist/src/core/run-state/sameness-detector.{js,d.ts}` so consumers can `import { computeFingerprint, shouldEscalate } from '@delegance/claude-autopilot/run-state/sameness-detector'` without deep-importing into compiled paths.
+- **Pipeline halts when retries make no progress, even if you have retries remaining.** `skills/autopilot/SKILL.md` Step 4 (validate), Step 7 (Codex PR review), and Step 8 (bugbot) now consult the detector before consuming a retry. If the same failure fingerprint fires twice in a row inside any retry loop, the pipeline stops and surfaces the matching fingerprint to the user instead of burning the remaining retry budget. This catches the class of bug where validate retries fix nothing because the underlying type error is unreachable from the change set.
+- Tests: `tests/run-state/sameness-detector.test.ts` (32 cases) covers the three issue-#181 acceptance scenarios (same × 2 escalates, same × 1 continues, different × 3 continues), edge cases (empty history, ABA pattern, message truncation, all three phases), delimiter-safety (fields containing `|`), and volatile-token scrubbing (UUIDs, timestamps, tmpdirs). `tests/run-state/sameness-detector-integration.test.ts` (7 cases) verifies SKILL.md retry-block references and that the compiled subpath export is importable + functional.
+
+### Notes
+- Persistence is intentionally in-memory only in v7.10.0. Per-retry-loop history is held in the autopilot skill execution scope; bugbot and validate do not share a history. The v6 run-state events.ndjson integration is tracked separately as issue #180.
+- Released as v7.10.0 even though issue #181 was originally labeled v7.11.0 — this ships before #178 and #179, so it gets the next minor.
+
+### Out of scope (still pending)
+- Expand/contract migration classification (additive vs destructive enforcement) — v7.11.0 candidate
+- v6 run-state engine integration into the autopilot skill (4,873 LOC of checkpoint/resume infra currently unused by the skill) — issue #180
+
 ## 7.9.1 — 2026-05-13 (correctness hotfix)
 
 ### Fixed

package/dist/src/core/run-state/sameness-detector.d.ts

@@ -0,0 +1,82 @@
+/** Which loop in the autopilot pipeline produced the failure. The three
+ *  Step-4 / Step-7 / Step-8 retry loops in `skills/autopilot/SKILL.md` are
+ *  the call sites that consult the detector before consuming a retry. */
+export type FailurePhase = 'validate' | 'codex-review' | 'bugbot';
+/** A normalized identity for a single failure occurrence. Two fingerprints
+ *  are "the same failure" iff their `hash` is equal — phase, errorType,
+ *  errorLocation, and the truncated/normalized errorMessage all feed into
+ *  the hash, so any meaningful change between retries produces a new hash. */
+export interface FailureFingerprint {
+    phase: FailurePhase;
+    /** Discriminator inside the phase. Examples:
+     *   - validate: 'tsc_error' | 'test_failure' | 'lint_error'
+     *   - codex-review: 'codex_critical' | 'codex_warning'
+     *   - bugbot: 'bugbot_high' | 'bugbot_medium' */
+    errorType: string;
+    /** Where the failure points. `file:line` for tsc/lint, test name for tests,
+     *  finding-id for codex, comment-id for bugbot. Whatever uniquely locates
+     *  the problem within the phase. */
+    errorLocation: string;
+    /** First 200 chars of the canonical message, whitespace-collapsed. The
+     *  truncation is what makes the fingerprint stable across runs that differ
+     *  only in trailing stack-frame noise. */
+    errorMessage: string;
+    /** sha256 hex of `${phase}|${errorType}|${errorLocation}|${errorMessage}`.
+     *  This is the equality key. */
+    hash: string;
+}
+/** Maximum length of the normalized error message that feeds the hash.
+ *  Anything beyond this is dropped — picked to match the issue spec and to
+ *  keep the hash stable across runs that differ only in trailing noise. */
+export declare const FINGERPRINT_MESSAGE_MAX = 200;
+export interface ComputeFingerprintInput {
+    phase: FailurePhase;
+    errorType: string;
+    errorLocation: string;
+    errorMessage: string;
+}
+/** Strip known volatile / per-run tokens from a free-form string so that two
+ *  retries that differ only in transient data (UUIDs, ports, epoch
+ *  timestamps, ISO timestamps, hex SHAs, absolute temp paths) produce the
+ *  same canonical form. Order matters — broader patterns run first so they
+ *  can swallow embedded delimiters before narrower patterns see them.
+ *
+ *  Exported because callers building locations/messages outside this module
+ *  may want to apply the same scrubbing before constructing a fingerprint
+ *  (e.g. when assembling an `errorLocation` from a tool output that embeds
+ *  a run-id). */
+export declare function stripVolatileTokens(s: string): string;
+/** Compute a stable fingerprint for a single failure occurrence. The
+ *  returned `hash` is the equality key — two failures with equal hashes
+ *  are considered "the same failure" for retry-loop escalation purposes. */
+export declare function computeFingerprint(input: ComputeFingerprintInput): FailureFingerprint;
+/** Compare two fingerprints. They are "the same failure" iff their hashes
+ *  match — phase/type/location/message all feed the hash, so equal hash
+ *  means equal across all observable identity. */
+export declare function isSameFailure(a: FailureFingerprint, b: FailureFingerprint): boolean;
+export interface EscalationDecision {
+    /** True iff the caller should STOP consuming retries and surface to a
+     *  human, because the last two recorded attempts produced the same
+     *  failure (no progress between retries). */
+    escalate: boolean;
+    /** Set when `escalate` is true — human-readable explanation. */
+    reason?: string;
+    /** Set when `escalate` is true — the offending fingerprint that fired
+     *  twice. Callers should display this to the operator so they can see
+     *  what's stuck. */
+    fingerprint?: FailureFingerprint;
+}
+/** Decide whether to escalate a retry loop to a human, given the history
+ *  of failure fingerprints recorded so far in this retry loop.
+ *
+ *  Rule (per issue #181): escalate iff `history.length >= 2` AND the last
+ *  two fingerprints have identical hashes. Anything else — first failure,
+ *  different failures across retries, longer streak of different failures
+ *  — returns `{ escalate: false }`.
+ *
+ *  Rationale: a single retry on the SAME failure means we tried, fixed
+ *  nothing, and failed identically. Retries that keep failing on
+ *  *different* things are still making progress (each one is a new fix).
+ *  Only no-progress retries should consume the escalation budget. */
+export declare function shouldEscalate(history: readonly FailureFingerprint[]): EscalationDecision;
+//# sourceMappingURL=sameness-detector.d.ts.map

package/dist/src/core/run-state/sameness-detector.js

@@ -0,0 +1,146 @@
+// src/core/run-state/sameness-detector.ts
+//
+// Retry-loop sameness detector — escalates when the same failure fingerprint
+// fires twice in a row during a retry loop (validate, codex PR review, or
+// bugbot). The pipeline halts when retries make no progress, even if you have
+// retries remaining.
+//
+// Issue: #181 (v7.11.0 — released as v7.10.0).
+//
+// Design:
+//   - `FailureFingerprint` is a hashable identity for a failure. Same hash
+//     across two attempts means "we tried, failed for the same reason, fixed
+//     nothing". That is the signal to stop burning retries and surface to a
+//     human.
+//   - Storage is in-memory only. The v6 run-state events.ndjson integration
+//     is tracked separately as issue #180; explicitly deferred here so the
+//     pipeline can adopt the detector without waiting on persistence.
+//   - All functions are pure (modulo `crypto.createHash`), making this easy
+//     to unit-test under node:test.
+//
+// Who calls this:
+//   The detector is consumed by the autopilot skill agent (an LLM following
+//   `skills/autopilot/SKILL.md`), NOT by the `scripts/validate.ts`,
+//   `scripts/codex-pr-review.ts`, or `scripts/bugbot.ts` CLI scripts. Those
+//   scripts are stateless per-invocation; the retry loop lives one layer
+//   above them, inside the skill execution. Wiring this into the CLIs would
+//   not catch repeated failures because each CLI invocation is a clean
+//   process. The skill agent is the durable retry-loop scope.
+import { createHash } from 'node:crypto';
+/** Maximum length of the normalized error message that feeds the hash.
+ *  Anything beyond this is dropped — picked to match the issue spec and to
+ *  keep the hash stable across runs that differ only in trailing noise. */
+export const FINGERPRINT_MESSAGE_MAX = 200;
+/** Strip known volatile / per-run tokens from a free-form string so that two
+ *  retries that differ only in transient data (UUIDs, ports, epoch
+ *  timestamps, ISO timestamps, hex SHAs, absolute temp paths) produce the
+ *  same canonical form. Order matters — broader patterns run first so they
+ *  can swallow embedded delimiters before narrower patterns see them.
+ *
+ *  Exported because callers building locations/messages outside this module
+ *  may want to apply the same scrubbing before constructing a fingerprint
+ *  (e.g. when assembling an `errorLocation` from a tool output that embeds
+ *  a run-id). */
+export function stripVolatileTokens(s) {
+    if (typeof s !== 'string')
+        return '';
+    return (s
+        // ISO-8601 timestamps (e.g. 2026-05-13T07:00:00.000Z)
+        .replace(/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:?\d{2})?\b/g, '<ts>')
+        // 13-digit epoch ms
+        .replace(/\b\d{13}\b/g, '<ts>')
+        // UUIDs (v1-v5)
+        .replace(/\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/g, '<uuid>')
+        // 40-char (sha1) or 64-char (sha256) hex digests
+        .replace(/\b[0-9a-fA-F]{40}\b/g, '<sha>')
+        .replace(/\b[0-9a-fA-F]{64}\b/g, '<sha>')
+        // macOS / Linux temp paths (/tmp, /var/folders) up to the next whitespace
+        .replace(/\/(?:tmp|var\/folders)\/[^\s'"`]+/g, '<tmpdir>')
+        // localhost ports like :49213
+        .replace(/\b(?:127\.0\.0\.1|localhost):\d{2,5}\b/g, '<host:port>'));
+}
+/** Normalize a free-form error message: strip volatile tokens, trim, collapse
+ *  all runs of whitespace (including newlines/tabs) to single spaces, and
+ *  truncate to `FINGERPRINT_MESSAGE_MAX` characters. The truncation is what
+ *  makes the fingerprint stable across runs whose messages differ only in
+ *  trailing stack-frame noise. */
+function normalizeMessage(msg) {
+    if (typeof msg !== 'string') {
+        return '';
+    }
+    const scrubbed = stripVolatileTokens(msg);
+    const collapsed = scrubbed.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= FINGERPRINT_MESSAGE_MAX) {
+        return collapsed;
+    }
+    return collapsed.slice(0, FINGERPRINT_MESSAGE_MAX);
+}
+/** Normalize an `errorLocation` (file path / test name / etc.) by applying
+ *  the same volatile-token scrubbing as the message, plus whitespace trim.
+ *  Does NOT truncate — locations are short by construction. */
+function normalizeLocation(loc) {
+    if (typeof loc !== 'string')
+        return '';
+    return stripVolatileTokens(loc).trim();
+}
+/** Compute a stable fingerprint for a single failure occurrence. The
+ *  returned `hash` is the equality key — two failures with equal hashes
+ *  are considered "the same failure" for retry-loop escalation purposes. */
+export function computeFingerprint(input) {
+    const phase = input.phase;
+    const errorType = (input.errorType ?? '').toString();
+    const errorLocation = normalizeLocation((input.errorLocation ?? '').toString());
+    const errorMessage = normalizeMessage(input.errorMessage ?? '');
+    // Use JSON.stringify of a 4-tuple as the canonical pre-hash serialization.
+    // This is unambiguous under any field content — pipe characters, quotes,
+    // braces, embedded JSON, etc. all serialize unambiguously and cannot
+    // produce collisions across different `[phase, type, location, message]`
+    // tuples. (Earlier drafts used a pipe-delimited string; that was vulnerable
+    // to delimiter ambiguity when, e.g., a test name legitimately contained
+    // '|'. The JSON form has no such edge case.)
+    const canonical = JSON.stringify([phase, errorType, errorLocation, errorMessage]);
+    const hash = createHash('sha256').update(canonical).digest('hex');
+    return { phase, errorType, errorLocation, errorMessage, hash };
+}
+/** Compare two fingerprints. They are "the same failure" iff their hashes
+ *  match — phase/type/location/message all feed the hash, so equal hash
+ *  means equal across all observable identity. */
+export function isSameFailure(a, b) {
+    if (!a || !b)
+        return false;
+    return a.hash === b.hash;
+}
+/** Decide whether to escalate a retry loop to a human, given the history
+ *  of failure fingerprints recorded so far in this retry loop.
+ *
+ *  Rule (per issue #181): escalate iff `history.length >= 2` AND the last
+ *  two fingerprints have identical hashes. Anything else — first failure,
+ *  different failures across retries, longer streak of different failures
+ *  — returns `{ escalate: false }`.
+ *
+ *  Rationale: a single retry on the SAME failure means we tried, fixed
+ *  nothing, and failed identically. Retries that keep failing on
+ *  *different* things are still making progress (each one is a new fix).
+ *  Only no-progress retries should consume the escalation budget. */
+export function shouldEscalate(history) {
+    if (!Array.isArray(history) || history.length < 2) {
+        return { escalate: false };
+    }
+    const last = history[history.length - 1];
+    const prev = history[history.length - 2];
+    if (!last || !prev) {
+        return { escalate: false };
+    }
+    if (isSameFailure(prev, last)) {
+        return {
+            escalate: true,
+            reason: `Retry loop produced the same failure twice in a row ` +
+                `(phase=${last.phase}, errorType=${last.errorType}, ` +
+                `errorLocation=${last.errorLocation}). The pipeline is not making ` +
+                `progress — surfacing to human instead of consuming another retry.`,
+            fingerprint: last,
+        };
+    }
+    return { escalate: false };
+}
+//# sourceMappingURL=sameness-detector.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delegance/claude-autopilot",
-  "version": "7.9.1",
+  "version": "7.10.0",
   "type": "module",
   "publishConfig": {
     "tag": "next"
@@ -39,6 +39,10 @@
       "types": "./dist/src/index.d.ts",
       "default": "./dist/src/index.js"
     },
+    "./run-state/sameness-detector": {
+      "types": "./dist/src/core/run-state/sameness-detector.d.ts",
+      "default": "./dist/src/core/run-state/sameness-detector.js"
+    },
     "./bin/claude-autopilot.js": "./bin/claude-autopilot.js",
     "./bin/guardrail.js": "./bin/guardrail.js",
     "./package.json": "./package.json"

package/skills/autopilot/SKILL.md

@@ -226,6 +226,13 @@ The `validate.ts` Phase 1 includes a **tsc regression check**: it runs `npx tsc
 If either FAIL:
 - Read findings / validation report at `.claude/validation-report.json`
 - Fix the blocking issues
+- **Before consuming a retry, compute the failure fingerprint** with `computeFingerprint({ phase: 'validate', errorType, errorLocation, errorMessage })` from `src/core/run-state/sameness-detector.ts`:
+  - `errorType`: `tsc_error` | `test_failure` | `lint_error` (whichever class caused the FAIL)
+  - `errorLocation`: prefer stable identifiers — `<repo-relative-path>:<line>` for tsc/lint, test-suite-name+test-name for tests. Avoid absolute paths and transient temp dirs; use the repo-relative form so the hash survives across working-tree moves.
+  - `errorMessage`: first 200 chars of the canonical message. Strip any embedded UUIDs, ports, or epoch timestamps from the message before computing — those rotate per run and will mask true sameness.
+
+  **Known limitation:** if the underlying fix shifts line numbers, two retries can produce different fingerprints even when the root cause is identical (false negative — no escalation). The current behavior is conservative: it never falsely escalates, but it may let the loop run its full retry budget on a shifting-line-number failure. If you see this pattern, prefer test name + diagnostic code over `file:line`.
+- Append the fingerprint to an in-memory list for this retry loop, then call `shouldEscalate(history)`. If `escalate === true` (the last two attempts produced the same fingerprint), STOP — do not consume another retry. Surface the matching fingerprint to the user and stop the pipeline.
 - Re-run the failing check
 - Max 3 retry iterations
 
@@ -313,6 +320,7 @@ npx tsx scripts/codex-pr-review.ts <pr-number>
 Posts Codex review as a GitHub PR comment. **This serves as the second risk-tiered pass for medium-risk specs and the third pass for high-risk specs.** Remediate CRITICAL findings:
 - Fix on the branch
 - Push
+- **Before consuming a re-review iteration, compute the failure fingerprint** with `computeFingerprint({ phase: 'codex-review', errorType: 'codex_critical', errorLocation, errorMessage })` from `src/core/run-state/sameness-detector.ts`. For `errorLocation` prefer a stable composite — `${normalized-title}::${repo-relative-path}` — over the transport-level finding ID (Codex regenerates finding IDs on each review run, so the raw ID is not stable). For `errorMessage` use the first sentence of the finding body, stripping any per-run identifiers (run-id, timestamps, file SHAs). Append to an in-memory list for this retry loop and call `shouldEscalate(history)`. If `escalate === true` — the same critical finding fired twice after a remediation attempt — STOP and surface to the user. Do not consume another re-review.
 - Re-run Codex review
 - Max 2 iterations
 
@@ -327,6 +335,7 @@ npx tsx scripts/bugbot.ts --pr <pr-number>
 Triages each finding (real bug vs false positive), auto-fixes real bugs, dismisses false positives with GitHub replies. If fixes applied:
 - Push
 - Wait for new bugbot comments (30s)
+- **Before consuming a bugbot retry, compute the failure fingerprint** with `computeFingerprint({ phase: 'bugbot', errorType: <'bugbot_high' | 'bugbot_medium'>, errorLocation, errorMessage })` from `src/core/run-state/sameness-detector.ts`. For `errorLocation` prefer the stable `<repo-relative-path>:<line>` rather than the GitHub comment ID — Cursor reposts findings with fresh comment IDs after each push, so comment ID is not stable across retries. The comment ID can be surfaced as metadata for human inspection but should not enter the hash. For `errorMessage` use the first 200 chars of the finding body. Append to an in-memory list for this retry loop and call `shouldEscalate(history)`. If `escalate === true` — a "fixed" finding re-fired identically — STOP and surface the fingerprint to the user. Do not consume another round.
 - Re-run /bugbot
 - Max 3 rounds
 
@@ -340,6 +349,33 @@ Tell the user:
 - Bugbot triage summary (fixed / dismissed / needs-human)
 - Any human-required items that couldn't be auto-resolved
 
+## Retry-loop sameness detector (Steps 4, 7, 8)
+
+As of v7.10.0, the three retry loops (Step 4 validate, Step 7 Codex PR review, Step 8 bugbot) MUST consult `src/core/run-state/sameness-detector.ts` before consuming a retry. The pipeline halts when retries make no progress — even if you have retries remaining.
+
+**The detector is consumed by the autopilot skill agent itself** (the LLM following this skill), not by the underlying `scripts/validate.ts` / `scripts/codex-pr-review.ts` / `scripts/bugbot.ts` CLI scripts. Those scripts are stateless per-invocation; the retry loop with its history lives inside this skill execution scope. That is why the integration is in this document and not in the CLI source.
+
+```ts
+// Public package import (uses the subpath export added in v7.10.0):
+import {
+  computeFingerprint,
+  shouldEscalate,
+} from '@delegance/claude-autopilot/run-state/sameness-detector';
+
+// Or from a local checkout:
+import { computeFingerprint, shouldEscalate } from './src/core/run-state/sameness-detector.ts';
+```
+
+How to use inside each retry loop:
+
+1. On a FAIL, derive `{ phase, errorType, errorLocation, errorMessage }` for the most salient blocker.
+2. `const fp = computeFingerprint({...})`.
+3. Append `fp` to an in-memory list for THIS retry loop (no cross-loop state — bugbot and validate keep separate histories).
+4. `const decision = shouldEscalate(history)` — if `decision.escalate === true`, STOP. Surface `decision.fingerprint` and `decision.reason` to the user. Do not consume another retry attempt even if the per-loop max isn't reached.
+5. Otherwise apply the fix, run again.
+
+Persistence is in-memory only in v7.10.0. The v6 run-state events.ndjson integration is tracked as issue #180.
+
 ## Error Recovery
 
 - **Preflight failure:** Surface the specific check, exit. Do not partially run.
@@ -347,9 +383,10 @@ Tell the user:
 - **Subagent failure:** Re-dispatch with more context or implement directly.
 - **Migration failure (Step 5 — dev only):** Fix SQL, re-run Step 4 (validate) against corrected code, then re-run Step 5 (migrate dev). Prod stays untouched. Max 3 retries.
 - **Prod migration:** Out of scope for autopilot. Handed off to user's CI/CD pipeline via `migrate.policy` (require_manual_approval, require_dry_run_first).
-- **Validate failure:** Fix issues, re-run (max 3 retries).
-- **Codex CRITICAL findings:** REMEDIATE (apply fix), push, re-review (max 2 retries). Do NOT continue past unremediated CRITICALs.
-- **Bugbot findings:** `/bugbot` handles triage + fix automatically (max 3 rounds).
+- **Validate failure:** Fix issues, re-run (max 3 retries, sameness-detector may halt earlier).
+- **Codex CRITICAL findings:** REMEDIATE (apply fix), push, re-review (max 2 retries, sameness-detector may halt earlier). Do NOT continue past unremediated CRITICALs.
+- **Bugbot findings:** `/bugbot` handles triage + fix automatically (max 3 rounds, sameness-detector may halt earlier).
+- **Sameness detector halt:** The same failure fingerprint fired in two consecutive retry attempts — the loop is not making progress. Stop, surface the fingerprint, ask the human to inspect.
 - **External hard-block** (TCC, network, etc.): Stop, report what was completed, surface the blocker.
 
 ## When NOT to use