@yagni-app/code-staging 0.0.0 → 0.1.0-staging.1002.1

package/dist/extension/pipeline/personas.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Grounded persona system-prompt bodies as DATA (spec §5).
+ *
+ * Each body is the pi `subagent` sample role (scout / planner / worker /
+ * reviewer) PLUS the explicit grounding clauses that make every node of the
+ * pipeline aware of how THIS company works — the only-YAGNI differentiator:
+ *   - scout / planner: call `ask_yagni` before inferring a convention,
+ *   - worker: call `record_decision` for any product-intent call,
+ *   - reviewer (business-fit lens): call `review_business_match` and treat a
+ *     conflict with a recorded decision as at least High.
+ *
+ * The reviewer also carries the strict, parseable findings output contract so
+ * the `{previous}` handoff into the fix stage parses (see `findings.ts`).
+ *
+ * Model + tools are NOT in the persona — the stage config (`stages.ts`) owns
+ * those. The body here is exactly the text written to the child's
+ * `--append-system-prompt` temp file. Inline TS constants (no .md copy step)
+ * keep the whole thing pure and unit-testable.
+ */
+import type { PipelineStage } from "./types.js";
+/** Persona body keyed by the agent name referenced in `stages.ts`. */
+export declare const PERSONA_BODIES: Record<string, string>;
+/**
+ * Grounding-free persona bodies, keyed by agent name (M6 blind lane only).
+ *
+ * `advisor` is present for completeness rather than use: no eval lane runs an
+ * advisor today, but `personaBody` throws on an unknown agent, so omitting it
+ * would turn any future blind-lane consult into a crash instead of a degraded
+ * measurement.
+ */
+export declare const BLIND_PERSONA_BODIES: Record<string, string>;
+/**
+ * Resolve the system-prompt body for a stage. For non-review stages this is the
+ * role body; for the review stage it appends the lens-specific clause and the
+ * required findings output contract so the reviewer's output parses.
+ *
+ * `grounded` defaults true (every real /go stage). The M6 eval passes
+ * `grounded: false` to select the grounding-free bodies + lens clauses for the
+ * blind lane; nothing else in the pipeline ever sets it.
+ */
+export declare function personaBody(stage: PipelineStage, opts?: {
+    grounded?: boolean;
+}): string;
+//# sourceMappingURL=personas.d.ts.map

package/dist/extension/pipeline/personas.js

@@ -0,0 +1,248 @@
+/**
+ * Grounded persona system-prompt bodies as DATA (spec §5).
+ *
+ * Each body is the pi `subagent` sample role (scout / planner / worker /
+ * reviewer) PLUS the explicit grounding clauses that make every node of the
+ * pipeline aware of how THIS company works — the only-YAGNI differentiator:
+ *   - scout / planner: call `ask_yagni` before inferring a convention,
+ *   - worker: call `record_decision` for any product-intent call,
+ *   - reviewer (business-fit lens): call `review_business_match` and treat a
+ *     conflict with a recorded decision as at least High.
+ *
+ * The reviewer also carries the strict, parseable findings output contract so
+ * the `{previous}` handoff into the fix stage parses (see `findings.ts`).
+ *
+ * Model + tools are NOT in the persona — the stage config (`stages.ts`) owns
+ * those. The body here is exactly the text written to the child's
+ * `--append-system-prompt` temp file. Inline TS constants (no .md copy step)
+ * keep the whole thing pure and unit-testable.
+ */
+const SCOUT_BODY = `You are a scout. Quickly investigate this codebase and return compressed, structured findings another agent can act on without re-reading everything. Your output is handed to an agent who has NOT seen the files you explored.
+
+You are grounded in how THIS company works. Before inferring a convention, an ownership rule, or "the way we do it here" from the repo alone, call ask_yagni and fold the cited answer into your map. Prefer recorded company conventions over guesses.
+
+Strategy:
+1. grep/find to locate the relevant code.
+2. Read only the key sections (not whole files).
+3. Identify the types, interfaces, and functions in play.
+4. Note dependencies between files and any conventions ask_yagni surfaces.
+
+Output:
+## Files
+\`path\` (lines) - what is here
+## Key code
+The critical types/functions, quoted from the files.
+## Conventions
+Anything ask_yagni confirmed about how this is done here.
+## Start here
+Which file to open first, and why.`;
+const PLANNER_BODY = `You are a planning specialist. You receive a scout's map plus the ticket and produce a concrete, ordered implementation plan. You must NOT change any files — only read, analyze, and plan.
+
+You are grounded. Call ask_yagni before inferring a convention or making any organization- or codebase-specific assumption; build the plan on cited company decisions, not priors.
+
+Output:
+## Goal
+One sentence.
+## Plan
+Numbered, small, actionable steps — each names the file/function to touch.
+## Files to modify / create
+- \`path\` - what changes and why
+## Risks
+What to watch for, including any decision the worker will be forced to make.
+
+Finish the job in ONE turn: do not end your turn on an interstitial like "now let me check X". Your FINAL message MUST be the complete plan in the format above (## Goal / ## Plan / ## Files to modify or create / ## Risks). Keep exploring with your tools until you can write the whole plan, then write it as your last message.
+
+Budget discipline: you have a hard output budget, and a plan that gets cut off mid-thought is worth less than a short plan that ships. Explore only until you can name the files and the steps — do not read broadly for completeness, and do not re-verify what you have already established. Aim for 5-10 short steps; the worker fills small gaps from the ticket. When in doubt, write the plan NOW.
+
+Keep it concrete; the worker executes it verbatim.`;
+const WORKER_BODY = `You are a worker with full capabilities, operating in an isolated context to implement a plan. Work autonomously and use the tools as needed.
+
+You are grounded. Call ask_yagni before guessing about anything organization- or codebase-specific. Critically: for ANY product-intent call you are forced to make that the plan did not settle — a behavior choice, a tradeoff, an interpretation of intent — call record_decision so the company's decision corpus captures it and the next agent inherits the call instead of re-litigating it.
+
+You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code, calling record_decision for any intent you infer. Ending your turn with no write/edit is a failure.
+
+Output:
+## Completed
+What was done.
+## Files changed
+- \`path\` - what changed
+## Decisions recorded
+Any record_decision calls you made, and why.
+## Notes
+Anything the reviewer should know (exact file paths, key functions touched).`;
+const REVIEWER_BODY = `You are a senior, adversarial code reviewer. Analyze the change for real problems, not style nits. Bash is read-only here (\`git diff\`, \`git log\`, \`git show\`); do NOT modify files or run builds.
+
+You are grounded in how THIS company works — that context is your edge over a repo-only reviewer.
+
+Strategy:
+1. \`git diff\` to see the change.
+2. Read the modified files and their surroundings.
+3. Judge the change through your assigned lens (below).`;
+const ADVISOR_BODY = `You are a senior advisor, brought in on ONE hard call by an agent that is already working the problem. You are the strongest model in this system and you are expensive, so you are consulted, not driven — the caller does the work, you supply the judgment.
+
+Do NOT take the caller's framing on trust. They have told you what they think the question is; half your value is looking where they did not think to look. Read the relevant code yourself before forming a view.
+
+You are grounded. Call ask_yagni before guessing about anything organization- or codebase-specific — conventions, prior decisions, product intent, ownership. The caller's brief may not include the company context that decides this question, and a strong model guessing about how this company works is exactly the failure mode you exist to avoid.
+
+You are READ-ONLY. You have read, grep, find and ls. You must not write, edit, build, or run anything — the caller applies whatever you recommend.
+
+Output, and nothing else:
+## Recommendation
+The call, stated plainly. Take a position; "it depends" is not an answer unless you then say what it depends on and how to check.
+## Why
+The reasoning, grounded in what you actually read. Cite files and lines.
+## What would change my mind
+The specific evidence that would flip this. If you were not able to verify something load-bearing, say so here rather than hedging the recommendation.
+
+Be terse and decisive. The caller is mid-task and paying peak rates for your turn.`;
+/** Persona body keyed by the agent name referenced in `stages.ts`. */
+export const PERSONA_BODIES = {
+    scout: SCOUT_BODY,
+    planner: PLANNER_BODY,
+    worker: WORKER_BODY,
+    reviewer: REVIEWER_BODY,
+    advisor: ADVISOR_BODY,
+};
+/**
+ * Grounding-FREE persona bodies for the M6 grounded-vs-blind eval ONLY. These are
+ * the same capable roles with every "you are grounded / call ask_yagni /
+ * record_decision / consult the decision corpus" clause removed, so the blind lane
+ * measures what the model produces WITHOUT this company's captured judgment in
+ * front of it. They are never used by the real /go path (which is always grounded);
+ * the eval pairs them with grounding-tool-stripped stages (see eval.ts). Kept
+ * separate from PERSONA_BODIES so the grounded prompt text stays byte-identical.
+ */
+const SCOUT_BLIND = `You are a scout. Quickly investigate this codebase and return compressed, structured findings another agent can act on without re-reading everything. Your output is handed to an agent who has NOT seen the files you explored.
+
+Strategy:
+1. grep/find to locate the relevant code.
+2. Read only the key sections (not whole files).
+3. Identify the types, interfaces, and functions in play.
+4. Note dependencies between files and any conventions you can infer from the code.
+
+Output:
+## Files
+\`path\` (lines) - what is here
+## Key code
+The critical types/functions, quoted from the files.
+## Conventions
+Anything you infer about how this is done here.
+## Start here
+Which file to open first, and why.`;
+const PLANNER_BLIND = `You are a planning specialist. You receive a scout's map plus the ticket and produce a concrete, ordered implementation plan. You must NOT change any files — only read, analyze, and plan.
+
+Output:
+## Goal
+One sentence.
+## Plan
+Numbered, small, actionable steps — each names the file/function to touch.
+## Files to modify / create
+- \`path\` - what changes and why
+## Risks
+What to watch for, including any decision the worker will be forced to make.
+
+Finish the job in ONE turn: do not end your turn on an interstitial like "now let me check X". Your FINAL message MUST be the complete plan in the format above (## Goal / ## Plan / ## Files to modify or create / ## Risks). Keep exploring with your tools until you can write the whole plan, then write it as your last message.
+
+Budget discipline: you have a hard output budget, and a plan that gets cut off mid-thought is worth less than a short plan that ships. Explore only until you can name the files and the steps — do not read broadly for completeness, and do not re-verify what you have already established. Aim for 5-10 short steps; the worker fills small gaps from the ticket. When in doubt, write the plan NOW.
+
+Keep it concrete; the worker executes it verbatim.`;
+const WORKER_BLIND = `You are a worker with full capabilities, operating in an isolated context to implement a plan. Work autonomously and use the tools as needed.
+
+You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code. Ending your turn with no write/edit is a failure.
+
+Output:
+## Completed
+What was done.
+## Files changed
+- \`path\` - what changed
+## Notes
+Anything the reviewer should know (exact file paths, key functions touched).`;
+const REVIEWER_BLIND = `You are a senior, adversarial code reviewer. Analyze the change for real problems, not style nits. Bash is read-only here (\`git diff\`, \`git log\`, \`git show\`); do NOT modify files or run builds.
+
+Strategy:
+1. \`git diff\` to see the change.
+2. Read the modified files and their surroundings.
+3. Judge the change through your assigned lens (below).`;
+const ADVISOR_BLIND = `You are a senior advisor, brought in on ONE hard call by an agent that is already working the problem. You are the strongest model in this system and you are expensive, so you are consulted, not driven — the caller does the work, you supply the judgment.
+
+Do NOT take the caller's framing on trust. They have told you what they think the question is; half your value is looking where they did not think to look. Read the relevant code yourself before forming a view.
+
+You are READ-ONLY. You have read, grep, find and ls. You must not write, edit, build, or run anything — the caller applies whatever you recommend.
+
+Output, and nothing else:
+## Recommendation
+The call, stated plainly. Take a position; "it depends" is not an answer unless you then say what it depends on and how to check.
+## Why
+The reasoning, grounded in what you actually read. Cite files and lines.
+## What would change my mind
+The specific evidence that would flip this. If you were not able to verify something load-bearing, say so here rather than hedging the recommendation.
+
+Be terse and decisive. The caller is mid-task and paying peak rates for your turn.`;
+/**
+ * Grounding-free persona bodies, keyed by agent name (M6 blind lane only).
+ *
+ * `advisor` is present for completeness rather than use: no eval lane runs an
+ * advisor today, but `personaBody` throws on an unknown agent, so omitting it
+ * would turn any future blind-lane consult into a crash instead of a degraded
+ * measurement.
+ */
+export const BLIND_PERSONA_BODIES = {
+    scout: SCOUT_BLIND,
+    planner: PLANNER_BLIND,
+    worker: WORKER_BLIND,
+    reviewer: REVIEWER_BLIND,
+    advisor: ADVISOR_BLIND,
+};
+/** The lens-specific clause appended to the reviewer body, one per review angle. */
+const LENS_CLAUSES = {
+    correctness: "Lens: CORRECTNESS. Hunt bugs, broken logic, unhandled edge cases, race conditions, and incorrect error handling. A real defect that can ship is at least High.",
+    business_fit: "Lens: BUSINESS-FIT. This is the only-YAGNI lens. Call review_business_match and consult the decision corpus: does this change match the recorded decisions, conventions, and current priorities of this company? Right code doing the wrong thing is exactly the failure you exist to catch. A conflict with a recorded decision is at least High.",
+    does_it_hold: "Lens: DOES-IT-HOLD. Does the change actually accomplish the ticket, and does it build/test as far as read-only bash lets you verify? Missing tests for new behavior, or a change that does not do the task, is at least High.",
+};
+/**
+ * The machine-readable findings contract every reviewer must emit so the
+ * orchestrator can parse the handoff (kept in lockstep with `parseFindings`).
+ */
+const FINDINGS_CONTRACT = `=== Findings output contract (required) ===
+End your review with a fenced block in EXACTLY this form, one line per finding:
+
+\`\`\`findings
+SEVERITY | file:line | message
+\`\`\`
+
+SEVERITY is one of: critical, high, medium, low. Use \`file:line\` when you can point to a location; otherwise give a short location or omit it. Put one finding per line and nothing else inside the block. If you found no problems, emit an empty \`\`\`findings block. Only critical and high findings block the change.
+
+Be terse. Do not narrate your process, restate the diff, or quote code back at length — spend your output on the findings themselves, at most a few short paragraphs before the block. Cap the block at the 12 most important findings, most severe first; a review cut off by its own length limit helps nobody.`;
+/**
+ * The blind lens clauses (M6): correctness + does_it_hold are not grounding
+ * specific, so they are reused verbatim; business_fit drops review_business_match
+ * and the decision-corpus instruction, judging only against apparent product
+ * intent, so the blind lane has no path to this company's captured judgment.
+ */
+const BLIND_LENS_CLAUSES = {
+    correctness: LENS_CLAUSES.correctness,
+    business_fit: "Lens: BUSINESS-FIT. Does this change match the apparent product intent and the conventions visible in the code? Right code doing the wrong thing is exactly the failure you exist to catch. A clear mismatch is at least High.",
+    does_it_hold: LENS_CLAUSES.does_it_hold,
+};
+/**
+ * Resolve the system-prompt body for a stage. For non-review stages this is the
+ * role body; for the review stage it appends the lens-specific clause and the
+ * required findings output contract so the reviewer's output parses.
+ *
+ * `grounded` defaults true (every real /go stage). The M6 eval passes
+ * `grounded: false` to select the grounding-free bodies + lens clauses for the
+ * blind lane; nothing else in the pipeline ever sets it.
+ */
+export function personaBody(stage, opts = {}) {
+    const grounded = opts.grounded !== false;
+    const bodies = grounded ? PERSONA_BODIES : BLIND_PERSONA_BODIES;
+    const base = bodies[stage.agent];
+    if (!base)
+        throw new Error(`No persona body for agent "${stage.agent}"`);
+    if (stage.id !== "review")
+        return base;
+    const lens = stage.lens ?? "correctness";
+    const clause = (grounded ? LENS_CLAUSES : BLIND_LENS_CLAUSES)[lens];
+    return [base, clause, FINDINGS_CONTRACT].join("\n\n");
+}
+//# sourceMappingURL=personas.js.map

package/dist/extension/pipeline/resilience.d.ts

@@ -0,0 +1,85 @@
+/**
+ * R1 - in-loop resilience for the /go pipeline.
+ *
+ * `withResilience(runStage, policy)` is a composable higher-order function that
+ * wraps the per-stage child spawn (`runner.ts#runStage`) with the one axis the
+ * roadmap calls the whole competitive gap: a per-stage IDLE timeout (no NDJSON
+ * event for N ms) and a total WALL-CLOCK timeout, both firing the runner's
+ * existing SIGTERM -> SIGKILL abort; bounded exponential backoff with jitter; and
+ * retry of CLASSIFIED-TRANSIENT outcomes only. One structured telemetry record is
+ * emitted per attempt.
+ *
+ * It is net-new vs the crash-resume work (#1225): that resumed a /go ACROSS
+ * invocations; this survives a transient blip IN-loop so a single 429/5xx/socket
+ * reset across the up-to-8 child spawns no longer terminates the run.
+ *
+ * Load-bearing corrections (from the design deep-dive):
+ *  - The wrapper passes the base a COMPOSED signal (the caller's signal + a
+ *    per-attempt timeout controller) so a timeout reuses the runner's real
+ *    SIGTERM/SIGKILL path rather than a second kill mechanism.
+ *  - A WRITE stage (implement / fix) is retried ONLY when it failed BEFORE its
+ *    first event. Once it has emitted an event a partial edit may exist, so a
+ *    re-run could double-apply; we let the no_changes / diff guard + review loop
+ *    catch it instead. Read-only stages (map / plan / review) retry freely.
+ *  - A genuine user abort (the CALLER's signal aborted) is never retried.
+ *
+ * Pure-ish: all impurity (timers, sleep, clock, randomness) sits behind injectable
+ * seams so the wrapper is unit-tested without real waits.
+ */
+import type { RunStageDeps } from "./runner.js";
+import { type PipelineStage, type ResiliencePolicy, type ReviewLens, type StageResult } from "./types.js";
+export type { ResiliencePolicy } from "./types.js";
+/** The exact shape of `runner.ts#runStage` (the seam this HOF wraps and returns). */
+export type RunStageFn = (stage: PipelineStage, ctx: {
+    ticket: string;
+    previous?: string;
+    lens?: ReviewLens;
+    grounded?: boolean;
+}, deps: RunStageDeps) => Promise<StageResult>;
+/** One telemetry record per attempt (routed through the orchestrator logger). */
+export interface ResilienceAttemptRecord {
+    stageId: string;
+    lens?: ReviewLens;
+    /** 1-based attempt number. */
+    attempt: number;
+    outcome: "ok" | "transient" | "fatal" | "timeout" | "aborted";
+    exitCode: number;
+    stopReason?: string;
+    elapsedMs: number;
+    willRetry: boolean;
+}
+/** Injectable seams so the wrapper is deterministic and fast in tests. */
+export interface ResilienceSeams {
+    /** Backoff sleep (default: real setTimeout). */
+    sleep?: (ms: number) => Promise<void>;
+    /** Monotonic-ish clock for elapsed timing (default: Date.now). */
+    now?: () => number;
+    /** Jitter source in [0, 1) (default: Math.random). */
+    random?: () => number;
+}
+export interface WithResilienceOpts {
+    telemetry?: (rec: ResilienceAttemptRecord) => void;
+    seams?: ResilienceSeams;
+}
+/**
+ * Compose a caller signal (possibly undefined) with one or more internal signals
+ * into a single AbortSignal that fires when ANY of them fires. Exported so the
+ * verify gate (P4) can reuse the same idle/wall composition for its deterministic
+ * command. A single signal is returned as-is (no needless wrapper).
+ */
+export declare function composeAbortSignal(caller: AbortSignal | undefined, ...others: AbortSignal[]): AbortSignal;
+/**
+ * PURE retry classifier: is this stage outcome a transient blip worth retrying?
+ * Transient iff it timed out, OR exited non-zero with a stopReason of `error`, OR
+ * its stderr carries a transient transport fingerprint. NEVER transient on a user
+ * abort (`stopReason === "aborted"` with no timeout) or a clean non-transient
+ * failure, so a deterministic bug is surfaced honestly instead of retried.
+ */
+export declare function classifyTransient(result: StageResult, timedOut: boolean): boolean;
+/**
+ * Wrap a `runStage` with idle + wall timeout and transient-only retry. The
+ * returned function is drop-in compatible with the bare runner, so it slots into
+ * the orchestrator's `deps.runStage ?? withResilience(defaultRunStage, …)` seam.
+ */
+export declare function withResilience(base: RunStageFn, policy: ResiliencePolicy, opts?: WithResilienceOpts): RunStageFn;
+//# sourceMappingURL=resilience.d.ts.map

package/dist/extension/pipeline/resilience.js

@@ -0,0 +1,166 @@
+/**
+ * R1 - in-loop resilience for the /go pipeline.
+ *
+ * `withResilience(runStage, policy)` is a composable higher-order function that
+ * wraps the per-stage child spawn (`runner.ts#runStage`) with the one axis the
+ * roadmap calls the whole competitive gap: a per-stage IDLE timeout (no NDJSON
+ * event for N ms) and a total WALL-CLOCK timeout, both firing the runner's
+ * existing SIGTERM -> SIGKILL abort; bounded exponential backoff with jitter; and
+ * retry of CLASSIFIED-TRANSIENT outcomes only. One structured telemetry record is
+ * emitted per attempt.
+ *
+ * It is net-new vs the crash-resume work (#1225): that resumed a /go ACROSS
+ * invocations; this survives a transient blip IN-loop so a single 429/5xx/socket
+ * reset across the up-to-8 child spawns no longer terminates the run.
+ *
+ * Load-bearing corrections (from the design deep-dive):
+ *  - The wrapper passes the base a COMPOSED signal (the caller's signal + a
+ *    per-attempt timeout controller) so a timeout reuses the runner's real
+ *    SIGTERM/SIGKILL path rather than a second kill mechanism.
+ *  - A WRITE stage (implement / fix) is retried ONLY when it failed BEFORE its
+ *    first event. Once it has emitted an event a partial edit may exist, so a
+ *    re-run could double-apply; we let the no_changes / diff guard + review loop
+ *    catch it instead. Read-only stages (map / plan / review) retry freely.
+ *  - A genuine user abort (the CALLER's signal aborted) is never retried.
+ *
+ * Pure-ish: all impurity (timers, sleep, clock, randomness) sits behind injectable
+ * seams so the wrapper is unit-tested without real waits.
+ */
+/** Stages whose value is landed edits: a re-run after a partial write can double-apply. */
+const WRITE_STAGE_IDS = ["implement", "fix"];
+/** Honest message stamped on a stage we aborted for exceeding its time budget. */
+const TIMEOUT_MESSAGE = "stage exceeded its idle or wall-clock timeout";
+/** stderr fingerprints of a transient transport/provider blip worth retrying. */
+const TRANSIENT_STDERR = /\b429\b|\b5\d\d\b|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket hang up/i;
+/**
+ * Compose a caller signal (possibly undefined) with one or more internal signals
+ * into a single AbortSignal that fires when ANY of them fires. Exported so the
+ * verify gate (P4) can reuse the same idle/wall composition for its deterministic
+ * command. A single signal is returned as-is (no needless wrapper).
+ */
+export function composeAbortSignal(caller, ...others) {
+    const signals = [caller, ...others].filter((s) => s != null);
+    if (signals.length === 1)
+        return signals[0];
+    return AbortSignal.any(signals);
+}
+/**
+ * PURE retry classifier: is this stage outcome a transient blip worth retrying?
+ * Transient iff it timed out, OR exited non-zero with a stopReason of `error`, OR
+ * its stderr carries a transient transport fingerprint. NEVER transient on a user
+ * abort (`stopReason === "aborted"` with no timeout) or a clean non-transient
+ * failure, so a deterministic bug is surfaced honestly instead of retried.
+ */
+export function classifyTransient(result, timedOut) {
+    if (timedOut)
+        return true;
+    if (result.stopReason === "aborted")
+        return false;
+    if (result.exitCode !== 0 && result.stopReason === "error")
+        return true;
+    if (result.stderr && TRANSIENT_STDERR.test(result.stderr))
+        return true;
+    return false;
+}
+/** A stage outcome the wrapper should consider for retry (mirror of the orchestrator's isFailed, minus R3-a). */
+function stageFailed(result, timedOut) {
+    return timedOut || result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
+}
+/** Bounded exponential backoff with +/- jitter, never negative. */
+function backoffDelay(policy, attempt, random) {
+    const raw = Math.min(policy.backoffMaxMs, policy.backoffBaseMs * 2 ** (attempt - 1));
+    const jitter = raw * policy.jitterRatio * (random() * 2 - 1);
+    return Math.max(0, Math.round(raw + jitter));
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Wrap a `runStage` with idle + wall timeout and transient-only retry. The
+ * returned function is drop-in compatible with the bare runner, so it slots into
+ * the orchestrator's `deps.runStage ?? withResilience(defaultRunStage, …)` seam.
+ */
+export function withResilience(base, policy, opts = {}) {
+    const sleep = opts.seams?.sleep ?? defaultSleep;
+    const now = opts.seams?.now ?? Date.now;
+    const random = opts.seams?.random ?? Math.random;
+    const telemetry = opts.telemetry;
+    return async (stage, ctx, deps) => {
+        const callerSignal = deps.signal;
+        const isWriteStage = WRITE_STAGE_IDS.includes(stage.id);
+        let last;
+        for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
+            // A caller abort during a backoff window: stop before spending another attempt.
+            if (callerSignal?.aborted && last)
+                return last;
+            const timeoutController = new AbortController();
+            const composed = composeAbortSignal(callerSignal, timeoutController.signal);
+            let timedOut = false;
+            let sawAnyEvent = false;
+            const fireTimeout = () => {
+                timedOut = true;
+                if (!timeoutController.signal.aborted)
+                    timeoutController.abort();
+            };
+            let idleTimer;
+            const armIdle = () => {
+                if (idleTimer)
+                    clearTimeout(idleTimer);
+                idleTimer = setTimeout(fireTimeout, policy.idleTimeoutMs);
+                idleTimer.unref?.();
+            };
+            const wallTimer = setTimeout(fireTimeout, policy.wallTimeoutMs);
+            wallTimer.unref?.();
+            armIdle();
+            const originalOnEvent = deps.onEvent;
+            const onEvent = (ev) => {
+                sawAnyEvent = true;
+                armIdle(); // reset the idle window on every live event
+                originalOnEvent?.(ev);
+            };
+            const startedAt = now();
+            try {
+                last = await base(stage, ctx, { ...deps, signal: composed, onEvent });
+            }
+            finally {
+                clearTimeout(wallTimer);
+                if (idleTimer)
+                    clearTimeout(idleTimer);
+            }
+            const elapsedMs = now() - startedAt;
+            const callerAborted = callerSignal?.aborted === true;
+            const record = (outcome, willRetry) => {
+                telemetry?.({
+                    stageId: stage.id,
+                    ...(ctx.lens ? { lens: ctx.lens } : {}),
+                    attempt,
+                    outcome,
+                    exitCode: last.exitCode,
+                    ...(last.stopReason ? { stopReason: last.stopReason } : {}),
+                    elapsedMs,
+                    willRetry,
+                });
+            };
+            // Genuine user cancel: surface honestly, never retry.
+            if (callerAborted) {
+                record("aborted", false);
+                return last;
+            }
+            if (!stageFailed(last, timedOut)) {
+                record("ok", false);
+                return last;
+            }
+            if (timedOut)
+                last.errorMessage = TIMEOUT_MESSAGE;
+            const transient = classifyTransient(last, timedOut);
+            // No double-apply: a write stage that already started working is never re-run.
+            const blockedByWriteGate = isWriteStage && sawAnyEvent;
+            const willRetry = transient && !blockedByWriteGate && attempt < policy.maxAttempts;
+            record(timedOut ? "timeout" : transient ? "transient" : "fatal", willRetry);
+            if (!willRetry)
+                return last;
+            await sleep(backoffDelay(policy, attempt, random));
+        }
+        // Exhausted maxAttempts on a retryable failure: return the last honest result.
+        return last;
+    };
+}
+//# sourceMappingURL=resilience.js.map

package/dist/extension/pipeline/resume.d.ts

@@ -0,0 +1,18 @@
+/**
+ * PURE resume-decision core — the analogue of `findings.ts#shouldStop`.
+ *
+ * Given the append-only checkpoint journal for a run key and a LIVE workspace
+ * snapshot, decide whether /go can safely resume the bounded review→fix loop,
+ * must warn about a partially-built / diverged tree, or should just run fresh.
+ *
+ * Safety boundary (the whole point): we only auto-resume the EXPENSIVE half (the
+ * review→fix loop) and only when the build half fully completed AND the live git
+ * tree still matches the boundary we checkpointed. A crash mid-build, or a tree
+ * that drifted since the checkpoint, would risk double-applying edits if we
+ * replayed — so those resolve to `warn_partial` (warn + run fresh), never a
+ * silent replay. Anything unknowable fails OPEN to `fresh` (mirrors
+ * `workspaceChanged`). The fold never throws.
+ */
+import type { CheckpointRecord, ResumePlan, WorkspaceSnapshot } from "./types.js";
+export declare function planResume(records: CheckpointRecord[], liveSnapshot: WorkspaceSnapshot): ResumePlan;
+//# sourceMappingURL=resume.d.ts.map