@delegance/claude-autopilot 7.9.1 → 7.10.1

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 - v5.6 Phase 7 (docs reconciliation) — pending.
 
+## 7.10.1 — 2026-05-13
+
+**v7.10.1 — `examples` verb.** Patch release. Closes the discoverability
+gap a new user hits between `setup` and `scaffold --from-spec`: the
+new `claude-autopilot examples` verb prints sample specs for each
+supported stack (node / python / fastapi / go / rust) so an operator
+can pipe one to a file and feed it back into the scaffolder.
+
+**New:** `claude-autopilot examples` lists all five stacks with a
+5-line preview. `claude-autopilot examples <stack>` prints the full
+spec for one stack to stdout — pipe-friendly:
+
+```bash
+claude-autopilot examples fastapi > docs/specs/my-api.md
+# edit the spec...
+claude-autopilot scaffold --from-spec docs/specs/my-api.md
+```
+
+**Bundled examples.** Five spec markdown files ship in
+`examples/specs/{node-cli,python-cli,fastapi,go-cli,rust-cli}.md` —
+one per supported scaffold target. Each shows the `## Files` section
+shape the scaffolder reads, plus a `## Goal` and `## How to use`
+section for human readers.
+
+**Package shape.** `examples/` is added to the published `files:`
+array in package.json so the directory ships in the npm tarball — the
+verb resolves spec paths via `findPackageRoot` and works under both
+source and globally installed CLI invocations.
+
+## 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
@@ -74,7 +120,6 @@ usage except for the bundled `tsx` deprecation warning.
   A1-A8 covering ESM/CJS safety, CLI parser scope, PATH self-pointer,
   AST audit, type-only imports, hand-rolled PATH lookup dropping the
   `which` dep, XDG state dir, npm-only --omit=optional documentation).
-
 ## 7.7.0 (2026-05-11)
 
 **v7.7.0 — Rust scaffold support.** Minor release. Promotes Rust from

package/README.md

@@ -17,8 +17,11 @@ claude-autopilot brainstorm "add SSO with SAML for enterprise tenants"
 # → writes spec (reviewed by Codex) → writes plan (reviewed by Codex) →
 # → creates branch → implements with subagents → runs migrations →
 # → runs full test + lint + type + security gate → opens PR →
-# → dispatches multi-model review → auto-fixes bugbot findings →
-# → ready to merge
+# → runs risk-tiered Codex PR review (1/2/3 passes by spec risk) →
+# → triages bugbot findings, auto-fixes real bugs, re-runs validate →
+# → merges with your configured permissions (default is admin-squash;
+#   configure branch protection + required checks if you need to enforce
+#   reviews/CI gates that the autopilot agent should not bypass)
 ```
 
 *No hosted agent. No per-seat subscription. Runs locally on your machine, against your real repo, using your API keys. Every phase is a Claude Code skill you can intervene in, rewire, or run by itself.*
@@ -50,13 +53,14 @@ Every finding came with a concrete remediation (often a code patch or named libr
 | **Cursor BugBot / CodeRabbit** | Hosted | Per-PR or seat | Vendor's model | Review only | Post-hoc |
 | **Aider / Cline** | Local CLI | Free + your API key | User's choice | None | Continuous |
 | **OpenHands / SWE-agent** | Local research | Free | User's choice | Agent decides | Rare |
-| **claude-autopilot** | **Local CLI, your repo** | **Free + your existing Claude subscription** | **Multi-model per role (Claude + Codex + Gemini)** | **Skill-per-phase, rewireable** | **Every phase, all state on disk** |
+| **claude-autopilot** | **Local CLI, your repo** | **Open source CLI + your model/API costs (Claude / Codex / Gemini / Groq / Ollama-local)** | **Multi-model per role (Claude + Codex + Gemini)** | **Skill-per-phase, rewireable** | **Every phase, all state on disk** |
 
-Three things only this product gives you:
+Four things only this product gives you:
 
-1. **Multi-model council.** Same design question goes to Claude + Codex + Gemini in parallel; a fourth model synthesizes the consensus. Different blind spots, different recommendations, one merged answer. **No other tool dispatches multi-model on a per-decision basis.**
-2. **Your code never leaves your machine.** No cloud sandbox. No SaaS markup. The `git push` that happens at the end is from your laptop. For private repos, regulated industries, or anyone who doesn't want their unfinished code on someone else's servers — this is the only autonomous-agent shape that fits.
+1. **No hosted workspace or remote sandbox.** Your repo stays on your machine. No third-party agent runtime, no SaaS-side orchestration, no per-seat markup. Model prompts (diffs, file context, design questions) are sent to whichever LLM providers you've configured (Anthropic / OpenAI / Google / Groq / Ollama-local). For a truly local-only setup, you must point _every_ model used by the entire execution path at a local endpoint: that includes the Claude Code agent runtime itself (configure a local Claude Code provider) AND the autopilot review adapter (`openai-compatible` pointed at Ollama). Pointing only the review adapter at Ollama still ships prompts/diffs to Anthropic via Claude Code. For most teams, local-only isn't the goal; "no hosted orchestration + your existing provider keys" is.
+2. **Risk-tiered review depth (policy-driven).** Specs declare `risk: low | medium | high` in frontmatter. The autopilot skill runs 1 / 2 / 3 sequential Codex passes accordingly, each with a remediation cycle in between. Enforcement is encoded in the skill (an LLM-driven instruction set, not a hard CLI gate) so it's auditable and editable: read `.claude/skills/autopilot/SKILL.md`, swap the tier rules for your codebase, expand the auto-escalation keyword list. Designed for teams that want review depth to scale with change risk instead of running forensic-grade review on every typo.
 3. **Ships as a Claude Code skill, not a competing IDE.** `/brainstorm`, `/autopilot`, `/migrate`, `/validate` are first-class Claude Code commands. As Claude Code grows, autopilot rides that adoption. You don't switch tools to use it; it's already there.
+4. **Multi-model council, available as a verb.** `claude-autopilot council` dispatches the same diff or design question to Claude + Codex + Gemini in parallel and synthesizes the consensus. Wire it into the autopilot pipeline by editing `.claude/skills/autopilot/SKILL.md` Step 7, or invoke standalone for one-off design decisions. The default pipeline uses sequential Codex review (cheaper, faster, often sufficient for routine changes); council is the higher-rigor option when you want broader model diversity.
 
 Plus the four practical differences:
 
@@ -128,9 +132,9 @@ Each phase is a Claude Code skill (`.claude/skills/<name>/SKILL.md`). You can in
 | **Migrate** | `migrate` | Dispatches to the configured migration skill (see [Migrate phase](#migrate-phase)) — runs your migration tool dev → QA → prod with per-env validation | Deterministic |
 | **Validate** | `validate` | Static rules + tests + type check + security scan + LLM review | Any |
 | **PR** | `commit-push-pr` | Opens the PR with auto-generated title, summary, and test plan | Claude |
-| **Review** | `review-2pass` / `council` | Multi-model review of the diff (critical pass + informational pass) | Multiple |
+| **Review** | `codex-pr-review` (default) or `council` (opt-in) | Sequential Codex pass on the diff with risk-tiered iteration count (1/2/3 passes for low/medium/high). Swap in `council` for parallel multi-model dispatch if you want higher rigor. | Codex (default) or multi-model |
 | **Triage** | `bugbot` | Fetches automated reviewer findings, auto-fixes real bugs, dismisses false positives | Claude |
-| **Deploy** | `deploy` | Deploys via configured adapter (`vercel` \| `fly` \| `render` \| `generic`) with optional log streaming, health check, and bounded auto-rollback (see [Deploy phase](#deploy-phase)) | Deterministic |
+| **Deploy** (opt-in) | `deploy` | Deploys via configured adapter (`vercel` \| `fly` \| `render` \| `generic`) with optional log streaming, health check, and bounded auto-rollback (see [Deploy phase](#deploy-phase)). Not on the default `/autopilot` critical path: the autopilot loop ends at merge, and your CI/CD handles prod. Invoke `claude-autopilot deploy` directly, or wire it into the autopilot skill as Step 10. | Deterministic |
 
 ### Migrate phase
 
@@ -181,11 +185,13 @@ deploy:
 
 Features that are hard or impossible to find in the competitive set:
 
-- **Multi-model council review** — dispatch the same diff to 3+ models in parallel, synthesize agreement. Catches blind spots no single model sees.
-- **Fix with test verification** — `claude-autopilot fix` runs your full test suite after every patch and reverts on failure. Safer than any tool that proposes fixes without running your tests.
-- **Bug-bot auto-triage** — watches Cursor BugBot / Copilot comments on your PR, triages each (real bug vs false positive), auto-fixes confirmed bugs, dismisses noise with explanations.
-- **Schema alignment rule** — ensures DB migrations, backend types, and frontend types stay in sync. Custom static rule, not something any competitor ships.
-- **SARIF output + GitHub Code Scanning integration** — findings appear as annotations in the PR and in the Security tab.
+- **Risk-tiered review depth (policy-driven).** Specs are tagged `risk: low | medium | high` in their frontmatter, with auto-escalation by keyword detection for sensitive categories (auth, multi-tenancy, sandboxing, billing, secrets, migrations, RLS, deploy/IAM, vector-DB tenancy — extend the list in the skill for your codebase). The pipeline runs 1 / 2 / 3 sequential Codex passes accordingly, each with a remediation cycle in between. Enforcement is encoded in `.claude/skills/autopilot/SKILL.md` (LLM-driven instructions, not a hard CLI gate), so it's auditable and editable. For teams that need hard enforcement, gate the merge step on the configured pass count by extending the skill or wrapping the CLI.
+- **Retry-loop sameness detector.** Validate / Codex / bugbot retry loops compute a failure fingerprint before consuming each retry. If the same fingerprint fires twice in a row, the pipeline halts and surfaces it to you — instead of burning the remaining retry budget on attempts that are making no progress. Available as a public subpath import (`@delegance/claude-autopilot/run-state/sameness-detector`) for embedding into your own retry loops.
+- **Multi-model council, available as a verb.** `claude-autopilot council` dispatches the same prompt to 3+ models in parallel and synthesizes the consensus. Opt-in for the autopilot pipeline (wire it into Step 7 of the autopilot skill), or invoke standalone for design decisions and architecture questions.
+- **Fix with test verification.** `claude-autopilot fix --verify` runs your full test suite after every patch and reverts on failure. Safer than any tool that proposes fixes without running your tests.
+- **Bug-bot auto-triage.** Watches Cursor BugBot / Copilot comments on your PR, triages each (real bug vs false positive), auto-fixes confirmed bugs, dismisses noise with explanations.
+- **Schema alignment rule.** Ensures DB migrations, backend types, and frontend types stay in sync. Custom static rule, not something any competitor ships.
+- **SARIF output + GitHub Code Scanning integration.** Findings appear as annotations in the PR and in the Security tab.
 
 ## Just the review layer
 

package/dist/src/cli/examples.d.ts

@@ -0,0 +1,15 @@
+/** Supported stack id → relative path under `examples/specs/`. */
+export declare const EXAMPLE_STACKS: Record<string, string>;
+/** Public stack ids in the order we want them listed. */
+export declare const EXAMPLE_STACK_IDS: readonly ["node", "python", "fastapi", "go", "rust"];
+/** Resolve the absolute on-disk path for a stack's spec file. */
+export declare function resolveExamplePath(stack: string): string | null;
+/**
+ * Run the `examples` verb. With no `stack`, prints an intro + a summary card
+ * for each stack (path + first ~5 lines of the spec). With a stack id, prints
+ * the full spec content to stdout (suitable for piping into a file).
+ *
+ * Returns the exit code so the dispatcher can `process.exit(code)`.
+ */
+export declare function runExamples(stack?: string): number;
+//# sourceMappingURL=examples.d.ts.map

package/dist/src/cli/examples.js

@@ -0,0 +1,108 @@
+// v7.7.1 — `claude-autopilot examples [<stack>]`
+//
+// Discoverability bridge between `setup` and `scaffold --from-spec`. A new
+// user runs `setup`, then `scaffold --from-spec ???` and has no idea what a
+// spec looks like. This verb prints sample specs — one per supported stack —
+// straight to stdout so the operator can pipe to a file, edit, and feed back
+// into `scaffold`.
+//
+//   claude-autopilot examples                   → list all 5 stacks
+//   claude-autopilot examples node              → print just the Node spec
+//   claude-autopilot examples fastapi > foo.md  → spec-as-template via shell
+//
+// The spec files ship in the published tarball via the `files: ["examples/"]`
+// entry in package.json. At runtime we resolve them relative to the package
+// root (found by `findPackageRoot`), so `examples` works whether the CLI is
+// run from source, the built dist/, or a globally installed `npm i -g`
+// invocation.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { findPackageRoot } from "./_pkg-root.js";
+/** Supported stack id → relative path under `examples/specs/`. */
+export const EXAMPLE_STACKS = {
+    node: 'examples/specs/node-cli.md',
+    python: 'examples/specs/python-cli.md',
+    fastapi: 'examples/specs/fastapi.md',
+    go: 'examples/specs/go-cli.md',
+    rust: 'examples/specs/rust-cli.md',
+};
+/** Public stack ids in the order we want them listed. */
+export const EXAMPLE_STACK_IDS = ['node', 'python', 'fastapi', 'go', 'rust'];
+const BOLD = (t) => `\x1b[1m${t}\x1b[0m`;
+const DIM = (t) => `\x1b[2m${t}\x1b[0m`;
+/** Resolve the absolute on-disk path for a stack's spec file. */
+export function resolveExamplePath(stack) {
+    const rel = EXAMPLE_STACKS[stack];
+    if (!rel)
+        return null;
+    const root = findPackageRoot(import.meta.url);
+    if (!root)
+        return null;
+    return path.join(root, rel);
+}
+/** Print the first N non-empty lines of a file for the listing summary. */
+function previewHead(absPath, n) {
+    try {
+        const body = fs.readFileSync(absPath, 'utf8');
+        const lines = body.split('\n');
+        const head = [];
+        for (const line of lines) {
+            head.push(line);
+            if (head.length >= n)
+                break;
+        }
+        return head.join('\n');
+    }
+    catch {
+        return '(failed to read example file)';
+    }
+}
+/**
+ * Run the `examples` verb. With no `stack`, prints an intro + a summary card
+ * for each stack (path + first ~5 lines of the spec). With a stack id, prints
+ * the full spec content to stdout (suitable for piping into a file).
+ *
+ * Returns the exit code so the dispatcher can `process.exit(code)`.
+ */
+export function runExamples(stack) {
+    if (!stack) {
+        console.log('');
+        console.log(BOLD('Sample specs for each supported stack.'));
+        console.log(DIM('Pass `examples <stack>` to print just one. Pipe to a file to use as a template:'));
+        console.log(DIM('  claude-autopilot examples node > docs/specs/my-feature.md'));
+        console.log(DIM('  claude-autopilot scaffold --from-spec docs/specs/my-feature.md'));
+        console.log('');
+        for (const id of EXAMPLE_STACK_IDS) {
+            const abs = resolveExamplePath(id);
+            if (!abs || !fs.existsSync(abs)) {
+                console.log(`${BOLD(id)}  ${DIM('(example file not found)')}`);
+                console.log('');
+                continue;
+            }
+            console.log(BOLD(id));
+            console.log(DIM(`  ${abs}`));
+            const head = previewHead(abs, 5);
+            for (const line of head.split('\n')) {
+                console.log(`  ${line}`);
+            }
+            console.log('');
+        }
+        return 0;
+    }
+    const abs = resolveExamplePath(stack);
+    if (!abs) {
+        process.stderr.write(`\x1b[31m[claude-autopilot] unknown stack "${stack}" — valid: ${EXAMPLE_STACK_IDS.join(', ')}\x1b[0m\n`);
+        return 1;
+    }
+    if (!fs.existsSync(abs)) {
+        process.stderr.write(`\x1b[31m[claude-autopilot] example file missing on disk: ${abs}\x1b[0m\n`);
+        process.stderr.write(`\x1b[2m  Did the published tarball include the "examples/" directory? See package.json "files".\x1b[0m\n`);
+        return 1;
+    }
+    const body = fs.readFileSync(abs, 'utf8');
+    process.stdout.write(body);
+    if (!body.endsWith('\n'))
+        process.stdout.write('\n');
+    return 0;
+}
+//# sourceMappingURL=examples.js.map

package/dist/src/cli/help-text.js

@@ -29,6 +29,7 @@ export const HELP_GROUPS = [
             { verb: 'init', summary: 'Scaffold guardrail.config.yaml + auto-detect migrate stack (writes .autopilot/stack.md)' },
             { verb: 'setup', summary: 'Auto-detect stack, write config, install pre-push hook' },
             { verb: 'scaffold', summary: 'Scaffold project skeleton from a spec markdown (--from-spec <path> [--stack node|python|fastapi|go|rust])' },
+            { verb: 'examples', summary: 'Print sample specs for each supported stack (use as starter templates for `scaffold --from-spec`)' },
             { verb: 'autopilot', summary: 'Multi-phase orchestrator — run scan → spec → plan → implement under one runId (v6.2.0)' },
             { verb: 'brainstorm', summary: 'Pipeline entry point (Claude Code skill — see /brainstorm)' },
             { verb: 'spec', summary: 'Spec-writing pointer (Claude Code skill — see /brainstorm)' },
@@ -213,6 +214,18 @@ export const HELP_OPTIONS = {
     claude-autopilot autopilot
     claude-autopilot autopilot --budget 25
     claude-autopilot autopilot --phases=scan,spec,plan`,
+    examples: `Options (examples):
+  [<stack>]            Optional: print only the spec for one stack (node|python|fastapi|go|rust)
+                       With no arg, lists all supported stacks with a 5-line preview each.
+
+  Behavior: read-only. Reads bundled spec files from the package's
+            \`examples/specs/\` directory and prints them to stdout. Pipe
+            to a file to use as a starter template:
+
+              claude-autopilot examples node > docs/specs/my-feature.md
+              claude-autopilot scaffold --from-spec docs/specs/my-feature.md
+
+  Exit codes: 0 success, 1 unknown stack id or missing bundled file.`,
     dashboard: `Options (dashboard):
   login                Open browser, mint API key via loopback callback
   logout               Revoke server-side, delete local config

package/dist/src/cli/index.js

@@ -226,7 +226,7 @@ These are aliases for the flat subcommands; they still work without the 'advance
 // gc, delete, doctor) are dispatched inside its case block. The singular
 // `run resume` form is handled BEFORE the default `run` -> review dispatch
 // kicks in (see disambiguation block just below).
-const SUBCOMMANDS = ['init', 'run', 'runs', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'migrate-v4', 'migrate', 'migrate-doctor', 'deploy', 'brainstorm', 'spec', 'plan', 'implement', 'review', 'validate', 'autopilot', 'internal', 'help', '--help', '-h'];
+const SUBCOMMANDS = ['init', 'run', 'runs', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'migrate-v4', 'migrate', 'migrate-doctor', 'deploy', 'brainstorm', 'spec', 'plan', 'implement', 'review', 'validate', 'autopilot', 'examples', 'internal', 'help', '--help', '-h'];
 const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce', 'ask', 'focus', 'fail-on', 'note', 'reason', 'expires', 'profile', 'severity', 'prompt', 'context-file', 'path', 'adapter', 'ref', 'sha', 'spec', 'context', 'mode', 'phases', 'budget', 'stack'];
 // Bare invocation — no subcommand, no flags → show welcome guide
 if (args.length === 0) {
@@ -993,6 +993,17 @@ switch (subcommand) {
         process.exit(0);
         break;
     }
+    case 'examples': {
+        // v7.7.1 — `claude-autopilot examples [<stack>]`. Bridges the
+        // discoverability gap between `setup` and `scaffold --from-spec` —
+        // new users don't know what a spec looks like. Optional positional
+        // arg selects a single stack; no arg lists all five.
+        const { runExamples } = await import("./examples.js");
+        const target = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
+        const code = runExamples(target);
+        process.exit(code);
+        break;
+    }
     case 'council': {
         const config = flag('config');
         const prompt = flag('prompt');

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/examples/specs/fastapi.md

@@ -0,0 +1,37 @@
+# tasks-api — FastAPI service
+
+## Goal
+
+A small FastAPI HTTP service exposing a `/tasks` CRUD endpoint with
+in-memory storage. Demonstrates the FastAPI scaffold path:
+`pyproject.toml` + `src/<pkg>/main.py` layout, dependencies on
+`fastapi` and `uvicorn[standard]`, and pytest with `httpx.AsyncClient`
+for endpoint tests.
+
+The scaffolder auto-classifies as FastAPI when prose mentions
+`fastapi` AND a `main.py` is listed.
+
+## Files
+
+* `pyproject.toml` — hatchling build backend, depends on `fastapi`, `uvicorn[standard]`, and `httpx` (test-only)
+* `requirements.txt` — Pinned lock file
+* `.gitignore` — `__pycache__/`, `.venv/`, `dist/`, `*.egg-info/`, `.pytest_cache/`
+* `src/tasks_api/__init__.py` — Package marker
+* `src/tasks_api/main.py` — FastAPI app (`app = FastAPI()`), defines `GET/POST/DELETE /tasks`
+* `src/tasks_api/models.py` — Pydantic `Task` model
+* `tests/test_api.py` — Async pytest tests using `httpx.AsyncClient(app=app)`
+* `README.md` — Usage: `uvicorn tasks_api.main:app --reload`
+
+## How to use
+
+```bash
+claude-autopilot examples fastapi > spec.md
+claude-autopilot scaffold --from-spec spec.md
+python -m pip install -e .
+pytest
+uvicorn tasks_api.main:app --reload
+```
+
+The scaffolder writes a FastAPI skeleton with one working endpoint as
+a starting point. Replace the in-memory dict with a real backing
+store (SQLite, Postgres, Redis) when you outgrow it.

package/examples/specs/go-cli.md

@@ -0,0 +1,32 @@
+# greet — Go 1.22 CLI
+
+## Goal
+
+A small Go CLI that prints a greeting. Demonstrates the standard Go
+module layout: `go.mod` at the repo root, `main.go` with a `main()`
+function, and table-driven tests in `main_test.go`. No external
+dependencies — uses only `fmt`, `os`, `flag` from the standard library.
+
+This is the simplest Go scaffold target. For a multi-binary repo,
+add `cmd/<name>/main.go` paths to the spec instead of root `main.go`.
+
+## Files
+
+* `go.mod` — `module greet`, `go 1.22`, no `require` block (stdlib only)
+* `.gitignore` — `vendor/`, `*.test`, `*.out`, binary output names
+* `main.go` — `package main`, defines `main()` and a pure `greet(name string) string`
+* `main_test.go` — Table-driven tests for `greet()` plus a smoke test for `main()`
+* `README.md` — Usage example: `go run . --name=World`
+
+## How to use
+
+```bash
+claude-autopilot examples go > spec.md
+claude-autopilot scaffold --from-spec spec.md
+go test ./...
+go run . --name=World
+```
+
+The scaffolder writes a working "hello, name" skeleton with a
+table-driven test you can extend. Edit `go.mod`'s module path before
+publishing (e.g. `module github.com/you/greet`).

package/examples/specs/node-cli.md

@@ -0,0 +1,36 @@
+# url-summarizer — Node 22 ESM CLI
+
+## Goal
+
+A small Node 22 ESM CLI that takes a URL on the command line, fetches
+the page, calls an LLM for a 3-bullet markdown summary, and prints the
+result to stdout. Demonstrates the v7.1.6 benchmark layout: a thin
+`bin/` entry that imports a pure handler from `src/`, JS-only with
+`tsconfig.json` set up for `allowJs + checkJs + noEmit` typechecking.
+
+This is the simplest scaffold target — it lights up the Node ESM path
+in `claude-autopilot scaffold --from-spec`.
+
+## Files
+
+* `package.json` — Node 22 ESM, `type: "module"`, bin: { url-summarizer: bin/url-summarizer.js }, scripts: { test: "node --test --import=tsx tests/", typecheck: "tsc --noEmit" }
+* `tsconfig.json` — `allowJs + checkJs + noEmit`, `types: ["node"]`
+* `.gitignore` — `node_modules/`, `.env.local`, `.guardrail-cache/`
+* `bin/url-summarizer.js` — CLI entry; parses `argv`, calls handler, prints result
+* `src/handler.js` — Pure async function `summarize(url): Promise<string>` (fetch + LLM call)
+* `tests/handler.test.js` — Unit tests with mocked fetch + LLM
+* `tests/cli.test.js` — CLI subprocess tests (uses `child_process.spawn`, NOT `spawnSync`)
+* `README.md` — Usage example: `node bin/url-summarizer.js https://example.com`
+
+## How to use
+
+```bash
+claude-autopilot examples node > spec.md
+claude-autopilot scaffold --from-spec spec.md
+npm test
+```
+
+The scaffolder writes a working skeleton; you (or your impl agent) fill
+in the handler body. The pre-existing tests should fail until the
+handler is implemented — that's intentional, it gives the impl agent a
+clear target.

package/examples/specs/python-cli.md

@@ -0,0 +1,35 @@
+# wordcount — Python 3.11+ CLI
+
+## Goal
+
+A bare Python CLI that counts words in a text file. Demonstrates the
+modern `pyproject.toml` + `src/<pkg>/` layout (the import-isolation
+pattern that pytest + hatchling both recommend), with a console
+script entry point and pytest-driven tests.
+
+No FastAPI, no web framework — this is the path for "Python script /
+library / CLI" specs. For HTTP services see `fastapi.md`.
+
+## Files
+
+* `pyproject.toml` — `[project]` table with hatchling build backend, `requires-python = ">=3.11"`, `dependencies = []`, `[project.scripts] wordcount = "wordcount.cli:main"`
+* `requirements.txt` — Lock file; pinned via `pip-compile` or `uv pip compile`
+* `.gitignore` — `__pycache__/`, `.venv/`, `dist/`, `*.egg-info/`, `.pytest_cache/`
+* `src/wordcount/__init__.py` — Package marker
+* `src/wordcount/cli.py` — `main()` entry; parses `argv`, calls counter, prints result
+* `src/wordcount/counter.py` — Pure function `count_words(text: str) -> int`
+* `tests/test_counter.py` — Unit tests for the counter
+* `tests/test_cli.py` — CLI smoke test via `subprocess.run`
+* `README.md` — Usage example: `wordcount path/to/file.txt`
+
+## How to use
+
+```bash
+claude-autopilot examples python > spec.md
+claude-autopilot scaffold --from-spec spec.md
+python -m pip install -e .
+pytest
+```
+
+The scaffolder writes the package skeleton + a pinned `requirements.txt`
+stub. Add your runtime deps to `pyproject.toml` then re-lock.

package/examples/specs/rust-cli.md

@@ -0,0 +1,34 @@
+# greet — Rust 2021 binary crate
+
+## Goal
+
+A small Rust binary crate that prints a greeting. Demonstrates the
+default `cargo init` layout: `Cargo.toml` + `src/main.rs` for the
+binary target + `tests/integration_test.rs` for the integration
+smoke test. No external crate dependencies — uses only `std`.
+
+This is the v7.7.0 binary-only path. For a library, list ONLY
+`src/lib.rs` (no `main.rs`) and the scaffolder switches to library
+mode and excludes `Cargo.lock` from `.gitignore` per Cargo's
+documented convention.
+
+## Files
+
+* `Cargo.toml` — `[package]` name = "greet", edition = "2021", no `[dependencies]` block (stdlib only)
+* `.gitignore` — `target/` (Cargo.lock NOT excluded — binary crate commits it)
+* `src/main.rs` — `fn main()` plus a pure `fn greet(name: &str) -> String`
+* `tests/integration_test.rs` — Integration smoke test that invokes the binary via `assert_cmd` (or `std::process::Command` for stdlib-only)
+* `README.md` — Usage example: `cargo run -- --name=World`
+
+## How to use
+
+```bash
+claude-autopilot examples rust > spec.md
+claude-autopilot scaffold --from-spec spec.md
+cargo test
+cargo run -- --name=World
+```
+
+The scaffolder writes a working "hello, name" binary skeleton with an
+integration test stub you can extend. Rename the `[package].name` in
+`Cargo.toml` before publishing to crates.io.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delegance/claude-autopilot",
-  "version": "7.9.1",
+  "version": "7.10.1",
   "type": "module",
   "publishConfig": {
     "tag": "next"
@@ -15,7 +15,17 @@
     "llm",
     "sarif",
     "cli",
-    "pipeline"
+    "pipeline",
+    "coding-agent",
+    "devin-alternative",
+    "cursor-alternative",
+    "autonomous-coding",
+    "multi-model",
+    "codex",
+    "mit-license",
+    "local-first",
+    "developer-tools",
+    "ci-cd"
   ],
   "license": "MIT",
   "workspaces": [
@@ -39,6 +49,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"
@@ -48,6 +62,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.json",
+    "examples/",
     "presets/",
     "skills/",
     "scripts/test-runner.mjs",
@@ -80,7 +95,7 @@
     "ulid": "^3.0.2"
   },
   "optionalDependencies": {
-    "@anthropic-ai/sdk": "^0.91.1",
+    "@anthropic-ai/sdk": "^0.96.0",
     "@google/generative-ai": "^0.24.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@supabase/supabase-js": "^2.97.0",

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