@sema-ai/core 1.275.1

package/dist/agents/repair-loop.d.ts

@@ -0,0 +1,236 @@
+import type { Runner } from "../core/runner/runtask.js";
+import type { TaskSpec } from "../core/types.js";
+import type { ExecutionEnv } from "../internal/harness.js";
+import type { VerificationResult } from "./verify.js";
+import type { Checkpoint } from "../core/checkpoint-store.js";
+import { type OracleIsolationVerdict } from "../core/oracle-isolation.js";
+/**
+ * SAFE-tier oracle self-repair loop (design/76 D1 命门, design/78 Slice-1). Given an implementation spec
+ * and an **injected, trusted oracle**, this runs the worker, grades it with the oracle, and — on failure —
+ * loops a fix turn (and a bounded clean-restart) until the oracle passes or the loop gives up. The terminal
+ * is then projected through the {@link terminalForTier} table, which **caps every PASS at `candidate_only`**:
+ * this layer NEVER auto-accepts. Auto-accept (`fixed`) requires the OFF Gate-1 out-of-process
+ * `oracleIsolation` boundary that this slice deliberately does not build — SAFE-tier escalates to a human
+ * (`needs_human_oracle`) or surfaces a candidate, but never clears its own work.
+ *
+ * Like {@link verifyCompleted}, this is a **thin composition** over `runner.runTask` (verify.ts:18-21 posture)
+ * — it adds no Runner-core surface, touches no vendored code, and is called by a leader/profile (the sibling
+ * of {@link runWithVerification}). The oracle internals (which gate/judge/property-harness to compose) live
+ * in the PROFILE-injected {@link RepairOracle} closure; core only fixes the {@link OracleResult} shape and the
+ * read-only / identity contract (§1 裁决①). N-parallel candidate fan-out + a robustness-first selection ranker
+ * are PROFILE concerns (§3 裁决②) — core stays single-candidate.
+ */
+/**
+ * The provenance/strength tier of the oracle that produced a verdict. The control plane assigns this — it is
+ * NEVER derived from agent-visible state (not a {@link TaskSpec} field), mirroring design/44 §7 Q4. Drives the
+ * {@link terminalForTier} projection.
+ * - `trusted_hidden` — a hidden, spec-derived held-out oracle (strongest; still candidate_only here).
+ * - `trusted_visible` — a visible trusted oracle (must be paired with an anchor + no property-harness regression + L3).
+ * - `property_harness_weak` — derived property invariants only (a weak signal).
+ * - `l3_judge_advisory` — an L3 read-only judge that advises but does not clear.
+ * - `none` — no oracle available → only a human can adjudicate.
+ */
+export type OracleTier = "trusted_hidden" | "trusted_visible" | "property_harness_weak" | "l3_judge_advisory" | "none";
+/**
+ * The terminal state the repair loop resolves to. SAFE-tier (this slice) can reach every value EXCEPT `fixed`:
+ * `fixed` is reserved for auto-accept, which needs the OFF Gate-1 out-of-process oracleIsolation boundary and
+ * is therefore unreachable here (terminal-by-tier §2 caps PASS at `candidate_only`).
+ * - `fixed` — auto-accepted (NOT reachable SAFE-tier; reserved for a future Gate-1 slice).
+ * - `candidate_only` — the oracle passed; surface the candidate for human acceptance, do not auto-accept.
+ * - `needs_human_oracle` — no usable oracle (`tier: "none"`) → only a human can adjudicate.
+ * - `gave_up` — attempts exhausted without a passing oracle (a first-class abstain, never "satisfy the test").
+ * - `conflict` — the spec and the oracle disagree (escalate; never rewrite the work to satisfy the test).
+ *   Slice-1 core does NOT synthesize this (the test-tampering diff-monitor is §6-deferred to the profile —
+ *   core honestly `gave_up`s rather than under-detect a conflict); it is in the vocabulary for the profile.
+ * - `oracle.unprotected` — fail-closed: the grader env was not isolated from the worker env (identity check).
+ *
+ * `needs_human_oracle` is disjoint from `needs_review` (a future dry-run gate) and `irreversible_ask` (shipped).
+ */
+export type RepairTerminal = "fixed" | "candidate_only" | "needs_human_oracle" | "gave_up" | "conflict" | "oracle.unprotected";
+/**
+ * One oracle verdict. Produced by the injected {@link RepairOracle} closure. `flaky` records that the oracle
+ * was non-deterministic across `retries` (a flaky verdict is NEVER projected to `fixed` — §5 / §6 flakyK).
+ * `trace` is the raw failure output fed back into the next fix turn; it is treated as untrusted worker-adjacent
+ * data (delimited into context, sanitized into the objective) but its INNER text is NEVER rewritten (§5.5 #8a)
+ * — rewriting it would destroy the real-trace feedback lever.
+ */
+export interface OracleResult {
+    tier: OracleTier;
+    passed: boolean;
+    /** Raw failure trace (on a failed verdict). Untrusted; fed back verbatim into the fix turn (never inner-rewritten). */
+    trace?: string;
+    /** The oracle's verdict was non-deterministic across `retries` re-isolations. A flaky verdict never → `fixed`. */
+    flaky: boolean;
+    /** How many re-isolation retries the oracle ran to settle the verdict. */
+    retries: number;
+}
+/**
+ * The PROFILE-injected oracle (§1 裁决①). The profile composes the actual grading inside this closure —
+ * `runExecGate(graderEnv, steps)` (exec-gate.ts:185, env is the FIRST param = L2 provenance bound to the
+ * grader) → `verifyCompleted` (verify.ts:212, the read-only L3 judge) → `checkInvariants`
+ * (property-harness.ts:217, explore-only) — and maps the composite to an {@link OracleResult}. Core never
+ * composes these internals (so the oracle type can't grow a long discriminated union); it only fixes the
+ * `OracleResult` shape and the read-only/identity contract. `graderEnv` is the isolated grader env; `evidence`
+ * is the diff/results to judge (recompute it from the post-resume working tree on a resume — verify.ts:328 BUG5).
+ */
+export type RepairOracle = (graderEnv: ExecutionEnv, evidence: string | undefined) => Promise<OracleResult>;
+/**
+ * The durable, JSON-safe repair state carried across an orthogonal durable suspend (§4). Serialized ONLY when
+ * an unrelated resource/HITL suspend interleaves the loop (happy-path is in-memory) and re-seeded on resume so
+ * `attemptCount` advances MONOTONICALLY (never reset). Contains NO functions/Dates (epoch ms if a timestamp is
+ * ever needed) so `structuredClone`/`JSON.stringify` round-trip it on the checkpoint. `baselinePassTests` is
+ * DELIBERATELY ABSENT (§4 MAJOR-C): the anchor is grader-computed out-of-process so a worker can't shrink it.
+ */
+export interface RepairBundle {
+    /** The latest failure trace (untrusted; fed back into the fix turn). */
+    failureTrace: string;
+    /** Reflexion-style diagnoses accumulated across attempts (≤3, Reflexion cap — §1). */
+    diagnostics: string[];
+    /** Hypotheses tried and rejected (so a re-seed doesn't re-explore them). */
+    rejectedHypotheses: string[];
+    /** The in-loop attempt counter — re-seeded MONOTONICALLY on resume, never reset/max/downscaled (§4 / §5). */
+    attemptCount: number;
+    /** The tier of the last oracle verdict (for the resumed loop's projection). */
+    oracleTier: OracleTier;
+}
+export interface RepairLoopConfig {
+    /** The PROFILE-injected, trusted oracle (§1 裁决①). Core calls it; it never composes the oracle internals. */
+    oracle: RepairOracle;
+    /**
+     * The ISOLATED grader env the oracle grades in. MUST be a distinct object from {@link workerEnv}: if they
+     * are the SAME reference the loop fails closed to `oracle.unprotected` BEFORE running anything (§5.1 —
+     * necessary-not-sufficient; the real out-of-process boundary is the OFF Gate-1).
+     */
+    graderEnv: ExecutionEnv;
+    /**
+     * The worker's execution env (the env `runner.runTask` runs the impl in), passed by the trusted caller so
+     * the §5.1 identity check can run: `graderEnv === workerEnv` → fail-closed `oracle.unprotected`. `TaskSpec`
+     * deliberately has NO `executionEnv` (the worker env is wired on the Runner deps / `executionEnvFactory`, not
+     * reachable from `implSpec`), so the caller must supply the reference here for the check to be meaningful.
+     * Omit it only when the worker env genuinely can't collide with the grader (e.g. distinct factories) — the
+     * check is then skipped (no reference to compare) and isolation is the caller's deployment contract.
+     */
+    workerEnv?: ExecutionEnv;
+    /**
+     * design/77 §1 Gate-1 (oracleIsolation): the paths the oracle/spec lives behind that the worker must NOT be
+     * able to corrupt (e.g. a hidden held-out test dir). When supplied **together with** {@link workerEnv}, the
+     * loop runs the FULL structural {@link assertOracleIsolation} (identity + structural-class + bash write-probe)
+     * instead of the bare reference-identity check, and surfaces {@link RepairResult.isolationClass}. Omit it (the
+     * default) to keep the existing necessary-not-sufficient reference-identity check (the merged Slice-1 posture).
+     *
+     * The real isolated grader env is SERVICE-provided ({@link import("../core/types.js").RunnerDeps.graderEnvFactory});
+     * `graderEnv` here is its `.env`, and the control-plane `provenance` brand is reattached internally for the
+     * assertion. The assertion only matters for the (mandate-OFF) auto-accept path: `isolationClass` caps a
+     * non-`out_of_process` grader at `candidate_only`. SAFE-tier never auto-accepts regardless.
+     */
+    immutableOraclePaths?: string[];
+    /**
+     * In-loop attempt ceiling (the loop runs at most this many GENERATE/oracle attempts). Profile validates this
+     * to 2-3; core only enforces it as a ceiling, it does not fence the value. This counter is DISTINCT from
+     * `suspendCount`(maxSuspends) and `sliceCount`(maxSlices) — it never borrows those budgets (§5 / §7).
+     */
+    maxAttempts: number;
+    /**
+     * On a resume after an orthogonal durable suspend, the restored {@link RepairBundle} (from
+     * `PrepareResume.seed.repairBundle`). `attemptCount` is re-seeded from it MONOTONICALLY (§4) — never reset.
+     */
+    resumeBundle?: RepairBundle;
+    /** Stop the loop once cumulative cost (generate + fix + oracle nested) reaches this (verify.ts:278 backstop). */
+    costCeilingMicroUsd?: number;
+    /** Overall wall-clock ceiling for the whole loop (verify.ts:277 backstop). */
+    totalTimeoutMs?: number;
+    /** Per-attempt callback (observability). */
+    onAttempt?: (info: {
+        attempt: number;
+        terminal?: RepairTerminal;
+        oracle: OracleResult;
+    }) => void;
+    /**
+     * Operational-warning sink (observability). MINOR-2: the §5.1 isolation identity check is SKIPPED when
+     * `workerEnv` is undefined (no reference to compare). An ACCIDENTAL omission — `graderEnv` supplied but
+     * `workerEnv` forgotten — would then disable the check silently. When wired, that case is surfaced here
+     * once at loop start so the gap is observable; the posture stays necessary-not-sufficient (no hard-fail).
+     */
+    onWarn?: (warning: Error) => void;
+}
+export interface RepairResult extends VerificationResult {
+    /** The projected terminal (§2). SAFE-tier never returns `fixed`. */
+    terminal: RepairTerminal;
+    /** The final repair state (in-memory unless an orthogonal suspend serialized it — §4). */
+    bundle: RepairBundle;
+    /**
+     * design/77 §1 Gate-1: the structural isolation class of the grader env, when the full
+     * {@link assertOracleIsolation} ran (i.e. {@link RepairLoopConfig.immutableOraclePaths} + `workerEnv` were
+     * supplied). `"out_of_process"` is the ONLY class the (mandate-OFF) auto-accept path may consider;
+     * `"in_process_probe_only"` CAPS the run at `candidate_only`. Undefined when only the bare reference-identity
+     * check ran. SAFE-tier never auto-accepts regardless of this value.
+     */
+    isolationClass?: OracleIsolationVerdict["isolationClass"];
+}
+/**
+ * design/77 §1 Gate-1 invariant — auto-accept (`fixed`) is UNREACHABLE here. The terminal-by-tier projection
+ * (§2) already caps every PASS at `candidate_only`, so `isolationClass` only ever matters for the (OFF)
+ * auto-accept path. This guard makes the invariant load-bearing rather than caller discipline: a non-isolated
+ * (`in_process_probe_only`) or unprotected verdict can NEVER carry a `fixed` terminal — at most
+ * `candidate_only` / `oracle.unprotected`. It is a pure assertion over the projected terminal; it never
+ * upgrades anything (auto-accept stays OFF — only a future Gate-1 slice running on an `out_of_process` grader
+ * may even consider it).
+ */
+export declare function isolationPermitsAutoAccept(verdict: OracleIsolationVerdict): boolean;
+/**
+ * CONSUMER seam (design/78 Slice-1, MAJOR-3 wiring — the re-entry side of the round-trip). Read the durable
+ * {@link RepairBundle} a resumed checkpoint carries, so a leader/profile resuming a repair-interleaved
+ * suspend can re-seed a FRESH {@link runRepairLoop} call with it.
+ *
+ * ## The contract (core vs profile)
+ * - **CORE owns the persistence + restore.** When an orthogonal durable suspend (resource/HITL) interleaves a
+ *   `runRepairLoop` attempt, the Runner serializes the live bundle onto the minted checkpoint
+ *   (`prepareTask.serializeCheckpointState` sources `internals.repairBundle`), and on resume re-seeds it back
+ *   into `prepareTask` from `cp.state.repairBundle`. So `cp.state.repairBundle` is round-trip-true after a
+ *   `runner.resume(token, …)`: it survives the suspend with `attemptCount` intact (never reset — §4 / MAJOR-A).
+ * - **PROFILE owns the re-entry loop.** The leader that resumes the worker (`runner.resume`) is a PROFILE
+ *   concern — core does NOT build the "resume → grade → re-seed `runRepairLoop`" loop. The profile reads the
+ *   restored bundle (via this accessor) off the SAME checkpoint it resumed, and on its NEXT repair attempt
+ *   passes it as {@link RepairLoopConfig.resumeBundle}. `runRepairLoop` then re-seeds `attemptCount`
+ *   MONOTONICALLY from it (`config.resumeBundle` → the loop's `bundle`), so the repair ratchet is preserved
+ *   across the durable suspend rather than starting the attempt budget over.
+ *
+ * Returns `undefined` when the checkpoint carries no repair state (a non-repair task, or a repair attempt that
+ * suspended on its very first GENERATE before any oracle verdict — the re-seed treats `undefined` as a clean
+ * start). The returned object is the checkpoint's own (already an independent `structuredClone` from the
+ * store); pass it straight into `resumeBundle` — `runRepairLoop` copies its arrays defensively on re-seed.
+ */
+export declare function repairBundleFromCheckpoint(cp: Checkpoint): RepairBundle | undefined;
+/**
+ * The terminal-by-tier projection (§2) — a PURE function, the core invariant. **SAFE-tier caps every PASS at
+ * `candidate_only`**; `fixed` (auto-accept) is unreachable here because it needs the OFF Gate-1 out-of-process
+ * boundary. Enforced HERE (in the projection table), not as caller discipline, so no consumer can promote a
+ * PASS to `fixed`.
+ *
+ * - any tier, `passed: true` → `candidate_only` (trusted_hidden/trusted_visible/property_harness_weak alike).
+ * - `l3_judge_advisory` → advisory only; even a "pass" can't clear → `candidate_only` (it never self-clears).
+ * - `none` → `needs_human_oracle` (no usable oracle → only a human adjudicates).
+ * - not-passed with a usable tier → not a terminal yet (the loop continues / gives up); represented as
+ *   `undefined` so the caller's state machine drives the `gave_up`/`conflict` path explicitly.
+ */
+export declare function terminalForTier(oracle: OracleResult): RepairTerminal | undefined;
+/**
+ * Run the SAFE-tier oracle self-repair loop over `implSpec` (design/78 §1 state machine — a DETERMINISTIC
+ * switch, no LLM in the control flow):
+ *
+ * `ASSERT_ISOLATION` (identity check → fail-closed `oracle.unprotected`) → `GENERATE` (`runner.runTask`) →
+ * `ORACLE` (the injected closure) → { passed → terminal-by-tier projection } | { failed & attempt<max → REPAIR
+ * (a fix turn) → loop } | { failed & attempt==max → CLEAN_RESTART once, else `gave_up` } | { conflict → terminal }.
+ *
+ * `ASSERT_ISOLATION` is the design/77 §1 Gate-1 seam: when {@link RepairLoopConfig.immutableOraclePaths} +
+ * `workerEnv` are supplied it runs the FULL {@link assertOracleIsolation} (identity + structural-class + bash
+ * write-probe) and surfaces {@link RepairResult.isolationClass}; otherwise it runs the bare reference-identity
+ * check (the merged Slice-1 posture). Either way a failed assertion fails closed to `oracle.unprotected` before
+ * any work runs, and the result NEVER reaches `fixed` — `isolationClass` only gates the (mandate-OFF) auto-accept
+ * path that this SAFE-tier loop does not take.
+ *
+ * SAFE-tier: the projection caps every PASS at `candidate_only` — this NEVER auto-accepts. `runRepairLoop` is a
+ * SIBLING of {@link verifyCompleted}: it composes over `runner.runTask` and never touches the Runner core.
+ */
+export declare function runRepairLoop(runner: Runner, implSpec: TaskSpec, config: RepairLoopConfig): Promise<RepairResult>;
+//# sourceMappingURL=repair-loop.d.ts.map

package/dist/agents/repair-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair-loop.d.ts","sourceRoot":"","sources":["../../src/agents/repair-loop.ts"],"names":[],"mappings":"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"}

package/dist/agents/repair-loop.js

@@ -0,0 +1,293 @@
+import { isDurablePause } from "./suspend-guard.js";
+import { delimitUntrusted, sanitizeUntrustedText } from "../core/untrusted-text.js";
+import { assertOracleIsolation } from "../core/oracle-isolation.js";
+/**
+ * design/77 §1 Gate-1 invariant — auto-accept (`fixed`) is UNREACHABLE here. The terminal-by-tier projection
+ * (§2) already caps every PASS at `candidate_only`, so `isolationClass` only ever matters for the (OFF)
+ * auto-accept path. This guard makes the invariant load-bearing rather than caller discipline: a non-isolated
+ * (`in_process_probe_only`) or unprotected verdict can NEVER carry a `fixed` terminal — at most
+ * `candidate_only` / `oracle.unprotected`. It is a pure assertion over the projected terminal; it never
+ * upgrades anything (auto-accept stays OFF — only a future Gate-1 slice running on an `out_of_process` grader
+ * may even consider it).
+ */
+export function isolationPermitsAutoAccept(verdict) {
+    return verdict.protected && verdict.isolationClass === "out_of_process";
+}
+/**
+ * CONSUMER seam (design/78 Slice-1, MAJOR-3 wiring — the re-entry side of the round-trip). Read the durable
+ * {@link RepairBundle} a resumed checkpoint carries, so a leader/profile resuming a repair-interleaved
+ * suspend can re-seed a FRESH {@link runRepairLoop} call with it.
+ *
+ * ## The contract (core vs profile)
+ * - **CORE owns the persistence + restore.** When an orthogonal durable suspend (resource/HITL) interleaves a
+ *   `runRepairLoop` attempt, the Runner serializes the live bundle onto the minted checkpoint
+ *   (`prepareTask.serializeCheckpointState` sources `internals.repairBundle`), and on resume re-seeds it back
+ *   into `prepareTask` from `cp.state.repairBundle`. So `cp.state.repairBundle` is round-trip-true after a
+ *   `runner.resume(token, …)`: it survives the suspend with `attemptCount` intact (never reset — §4 / MAJOR-A).
+ * - **PROFILE owns the re-entry loop.** The leader that resumes the worker (`runner.resume`) is a PROFILE
+ *   concern — core does NOT build the "resume → grade → re-seed `runRepairLoop`" loop. The profile reads the
+ *   restored bundle (via this accessor) off the SAME checkpoint it resumed, and on its NEXT repair attempt
+ *   passes it as {@link RepairLoopConfig.resumeBundle}. `runRepairLoop` then re-seeds `attemptCount`
+ *   MONOTONICALLY from it (`config.resumeBundle` → the loop's `bundle`), so the repair ratchet is preserved
+ *   across the durable suspend rather than starting the attempt budget over.
+ *
+ * Returns `undefined` when the checkpoint carries no repair state (a non-repair task, or a repair attempt that
+ * suspended on its very first GENERATE before any oracle verdict — the re-seed treats `undefined` as a clean
+ * start). The returned object is the checkpoint's own (already an independent `structuredClone` from the
+ * store); pass it straight into `resumeBundle` — `runRepairLoop` copies its arrays defensively on re-seed.
+ */
+export function repairBundleFromCheckpoint(cp) {
+    return cp.state.repairBundle;
+}
+/**
+ * The terminal-by-tier projection (§2) — a PURE function, the core invariant. **SAFE-tier caps every PASS at
+ * `candidate_only`**; `fixed` (auto-accept) is unreachable here because it needs the OFF Gate-1 out-of-process
+ * boundary. Enforced HERE (in the projection table), not as caller discipline, so no consumer can promote a
+ * PASS to `fixed`.
+ *
+ * - any tier, `passed: true` → `candidate_only` (trusted_hidden/trusted_visible/property_harness_weak alike).
+ * - `l3_judge_advisory` → advisory only; even a "pass" can't clear → `candidate_only` (it never self-clears).
+ * - `none` → `needs_human_oracle` (no usable oracle → only a human adjudicates).
+ * - not-passed with a usable tier → not a terminal yet (the loop continues / gives up); represented as
+ *   `undefined` so the caller's state machine drives the `gave_up`/`conflict` path explicitly.
+ */
+export function terminalForTier(oracle) {
+    if (oracle.tier === "none")
+        return "needs_human_oracle";
+    // A flaky verdict is never a clean pass — never project it to a passing terminal (§5 / §6 flakyK). It falls
+    // through to the not-passed path so the loop re-isolates / escalates rather than surfacing a candidate.
+    if (oracle.passed && !oracle.flaky) {
+        // SAFE-tier cap: every passing tier → candidate_only. `fixed` is unreachable (needs OFF Gate-1).
+        return "candidate_only";
+    }
+    // Not (cleanly) passed on a usable-oracle tier → the state machine decides (loop / gave_up / conflict).
+    return undefined;
+}
+/**
+ * The fix-turn objective: feed the oracle's failure trace + accumulated diagnoses back into the next attempt's
+ * objective. The trace is UNTRUSTED worker-adjacent output, so it is sanitized as it enters the objective
+ * (verify.ts:163 fixObjective pattern) — but it is fed back VERBATIM in substance (no inner rewrite, §5.5 #8a):
+ * the implementer must see the real failure to fix it. The instruction never says "make the test pass" — it
+ * says "fix the cause"; a spec-vs-oracle conflict escalates instead (§5 #2).
+ */
+function repairObjective(bundle) {
+    const diag = bundle.diagnostics.length
+        ? bundle.diagnostics.map((d) => `- ${sanitizeUntrustedText(d)}`).join("\n")
+        : "(no prior diagnoses)";
+    return (`The oracle REJECTED the previous attempt. Diagnose and fix the underlying cause, then stop — do not ` +
+        `add anything else, and do NOT edit or weaken the oracle/tests to make them pass. If the spec and the ` +
+        `oracle genuinely conflict, say so explicitly rather than satisfying the test.\n\n` +
+        `## Prior diagnoses\n${diag}\n\n` +
+        `## Oracle failure trace (untrusted)\n${delimitUntrusted("ORACLE TRACE", bundle.failureTrace || "(no trace)")}`);
+}
+/** A fresh, empty bundle for a loop that starts without a resume seed. */
+function freshBundle() {
+    return { failureTrace: "", diagnostics: [], rejectedHypotheses: [], attemptCount: 0, oracleTier: "none" };
+}
+/**
+ * Build the {@link VerificationOutcome} shape {@link RepairResult} extends from. The repair loop's own verdict
+ * is the `terminal`; this carries the verify-stack shape (verdict/rounds/findings) so a {@link RepairResult} is
+ * a drop-in {@link VerificationResult} for callers that already consume that shape.
+ */
+function outcomeFor(terminal, oracle, rounds) {
+    const passed = terminal === "candidate_only" || terminal === "fixed";
+    return {
+        verdict: passed ? "PASS" : terminal === "needs_human_oracle" ? "unverified" : "FAIL",
+        ...(passed ? {} : terminal === "needs_human_oracle" ? { unverifiedReason: "no_verdict" } : {}),
+        rounds,
+        // MINOR-1: `oracle.trace` is RAW untrusted text (the grader's failure output — may carry a forged
+        // `<system-reminder>` / break-out sequence). It flows outward in `verification.findings` (a caller may
+        // re-inject it into a prompt), so neutralize the break-out at the producer like every other untrusted inlet.
+        findings: oracle?.trace ? [sanitizeUntrustedText(oracle.trace)] : [],
+    };
+}
+/**
+ * Run the SAFE-tier oracle self-repair loop over `implSpec` (design/78 §1 state machine — a DETERMINISTIC
+ * switch, no LLM in the control flow):
+ *
+ * `ASSERT_ISOLATION` (identity check → fail-closed `oracle.unprotected`) → `GENERATE` (`runner.runTask`) →
+ * `ORACLE` (the injected closure) → { passed → terminal-by-tier projection } | { failed & attempt<max → REPAIR
+ * (a fix turn) → loop } | { failed & attempt==max → CLEAN_RESTART once, else `gave_up` } | { conflict → terminal }.
+ *
+ * `ASSERT_ISOLATION` is the design/77 §1 Gate-1 seam: when {@link RepairLoopConfig.immutableOraclePaths} +
+ * `workerEnv` are supplied it runs the FULL {@link assertOracleIsolation} (identity + structural-class + bash
+ * write-probe) and surfaces {@link RepairResult.isolationClass}; otherwise it runs the bare reference-identity
+ * check (the merged Slice-1 posture). Either way a failed assertion fails closed to `oracle.unprotected` before
+ * any work runs, and the result NEVER reaches `fixed` — `isolationClass` only gates the (mandate-OFF) auto-accept
+ * path that this SAFE-tier loop does not take.
+ *
+ * SAFE-tier: the projection caps every PASS at `candidate_only` — this NEVER auto-accepts. `runRepairLoop` is a
+ * SIBLING of {@link verifyCompleted}: it composes over `runner.runTask` and never touches the Runner core.
+ */
+export async function runRepairLoop(runner, implSpec, config) {
+    // ── ASSERT_ISOLATION (§5.1): the grader env MUST be a distinct object from the worker env, else the oracle
+    // is grading in the same env the worker can corrupt → fail closed BEFORE running anything. The worker env is
+    // supplied via `config.workerEnv` (TaskSpec has no `executionEnv` — types.ts:911 — so it isn't reachable from
+    // `implSpec`; see the design/78 deviation note). necessary-not-sufficient: the real boundary is the OFF Gate-1.
+    if (config.workerEnv === undefined && config.immutableOraclePaths === undefined) {
+        // MINOR-2: `workerEnv` omitted AND no full structural assertion requested → the bare identity check below
+        // can't run (no reference to compare), so it is skipped. That is LEGITIMATE only when the worker env
+        // genuinely can't collide with the grader (distinct factories). An ACCIDENTAL omission would silently
+        // disable the §5.1 check, so surface it once — observable, not fatal (necessary-not-sufficient: the real
+        // boundary is the OFF Gate-1 out-of-process isolation). The `immutableOraclePaths`-set case is NOT a warn:
+        // it fails closed below (adversarial round MINOR — a requested-but-unrunnable assertion must not be skipped).
+        config.onWarn?.(new Error("repair-loop §5.1: graderEnv was supplied but workerEnv is undefined — the grader/worker env identity " +
+            "check is SKIPPED. Pass config.workerEnv (the env runner.runTask runs the impl in) so an accidental " +
+            "shared-env misconfiguration is caught; omit it only when the envs provably cannot collide."));
+    }
+    // Build the fail-closed synthetic result for a failed isolation assertion (no work ran — before GENERATE).
+    const unprotectedResult = (reason, isolationClass) => {
+        const oracle = { tier: "none", passed: false, flaky: false, retries: 0 };
+        return {
+            taskId: implSpec.taskId ?? "",
+            status: "failed",
+            result: `oracle isolation check failed: ${reason}`,
+            errorCode: "oracle.unprotected",
+            sessionId: "",
+            stats: { tokens: 0, turns: 0, costUsd: 0, costMicroUsd: 0 },
+            terminal: "oracle.unprotected",
+            ...(isolationClass ? { isolationClass } : {}),
+            bundle: { ...freshBundle(), attemptCount: config.resumeBundle?.attemptCount ?? 0 },
+            verification: outcomeFor("oracle.unprotected", oracle, 0),
+        };
+    };
+    // design/77 §1 Gate-1: when the FULL structural assertion is requested (immutableOraclePaths supplied) AND a
+    // worker env is present, run `assertOracleIsolation` (identity + structural-class + bash write-probe) and
+    // capture the isolationClass to surface on the result. A non-`protected` verdict fails closed to
+    // `oracle.unprotected` BEFORE any work runs — identical terminal to the bare reference check, plus the class.
+    // The class only gates the (mandate-OFF) auto-accept path; it never lets this SAFE-tier loop reach `fixed`.
+    let isolationClass;
+    if (config.immutableOraclePaths !== undefined && config.workerEnv === undefined) {
+        // 🔴 Adversarial round MINOR: the caller opted into the FULL structural assertion (`immutableOraclePaths`)
+        // but supplied no `workerEnv`. The assertion fundamentally REQUIRES it — the identity check compares against
+        // workerEnv, and the bash write-probe runs via `workerEnv.exec()`. We cannot honor the requested guarantee,
+        // so fail CLOSED (oracle.unprotected) rather than silently skipping the assertion the caller asked for.
+        return unprotectedResult("immutableOraclePaths requested the structural isolation assertion but workerEnv is undefined — cannot run it (fail-closed)");
+    }
+    if (config.immutableOraclePaths !== undefined && config.workerEnv !== undefined) {
+        const grader = {
+            env: config.graderEnv,
+            immutableOraclePaths: config.immutableOraclePaths,
+            // provenance is reattached here (the trusted caller side) — never derived from worker state.
+            provenance: "control_plane",
+        };
+        const verdict = await assertOracleIsolation(config.workerEnv, grader);
+        isolationClass = verdict.isolationClass;
+        if (!verdict.protected) {
+            return unprotectedResult(verdict.reason ?? "grader env failed the structural isolation assertion", isolationClass);
+        }
+    }
+    else if (config.workerEnv !== undefined && config.workerEnv === config.graderEnv) {
+        // Bare reference-identity check (the merged Slice-1 posture) when the full assertion isn't requested.
+        return unprotectedResult("graderEnv must not be the worker env");
+    }
+    const maxAttempts = Math.max(1, Math.floor(config.maxAttempts));
+    // ── attemptCount is an IN-LOOP counter, DISTINCT from suspendCount(maxSuspends)/sliceCount(maxSlices). On a
+    // resume it is re-seeded from the restored bundle MONOTONICALLY — never reset/max/downscaled (§4 / §5 #b).
+    const bundle = config.resumeBundle
+        ? { ...config.resumeBundle, diagnostics: [...config.resumeBundle.diagnostics], rejectedHypotheses: [...config.resumeBundle.rejectedHypotheses] }
+        : freshBundle();
+    const startedAt = Date.now();
+    let spend = 0;
+    let lastResult;
+    let lastOracle;
+    let restartedOnce = false; // a pending one-shot clean-restart (consumed by the next loop iteration)
+    let restartUsed = false; // the clean restart is allowed AT MOST once per loop call
+    // The spec for a clean restart: a FRESH `runTask({...implSpec})` with a NEW session (no sessionId), in-memory
+    // bundle, no checkpoint hop — the failed transcript is discarded so the restart carries no Contextual Drag
+    // (§5 #d / §3). The objective is the ORIGINAL task PLUS the accumulated diagnoses (Reflexion carry) so a
+    // fresh implementer still knows what to build, just not the stuck transcript.
+    const cleanRestartSpec = () => {
+        const { sessionId: _drop, ...rest } = implSpec;
+        return { ...rest, objective: `${implSpec.objective}\n\n${repairObjective(bundle)}` };
+    };
+    while (true) {
+        // ── GENERATE / REPAIR: `runner.runTask` reuses the whole engine (budget gate / turn loop / assembleResult).
+        // First attempt runs implSpec verbatim; a repair attempt continues the SAME session with the fix objective
+        // (prefix-cache preserved, verify.ts:280-285), so diagnostics feed the running implementer; a clean restart
+        // is a FRESH session (failed transcript discarded).
+        const isRepair = bundle.attemptCount > 0 && lastResult !== undefined && !restartedOnce;
+        const spec = restartedOnce
+            ? cleanRestartSpec()
+            : isRepair
+                ? { ...implSpec, sessionId: lastResult.sessionId, objective: repairObjective(bundle) }
+                : implSpec;
+        restartedOnce = false; // consume the one-shot restart flag
+        // design/78 Slice-1 (MAJOR-3 wiring): thread the CURRENT live bundle through the Runner's TRUSTED
+        // internal channel (NOT a TaskSpec field). If this attempt hits an ORTHOGONAL durable suspend
+        // (resource/HITL) mid-run, the checkpoint the Runner mints serializes THIS live bundle — the accumulated
+        // failureTrace/diagnostics/rejectedHypotheses + the in-loop attemptCount — instead of `undefined`. A
+        // resume then re-seeds `RepairLoopConfig.resumeBundle` from it so `attemptCount` advances MONOTONICALLY
+        // (§4). The bundle is only meaningful once a repair attempt is in flight (attemptCount>0 = a prior oracle
+        // failure recorded diagnostics); on the very first GENERATE it is the fresh/empty bundle (a suspend there
+        // legitimately carries attemptCount 0 — no verdict yet — which the re-seed treats as a clean start).
+        const result = await runner.runTask(spec, { repairBundle: bundle });
+        spend += (result.stats.costMicroUsd ?? 0) + (result.stats.nested?.costMicroUsd ?? 0);
+        lastResult = result;
+        bundle.attemptCount += 1;
+        // An orthogonal durable suspend (resource/HITL) inside the worker run — surface it via the EXISTING
+        // suspend mechanism (verify.ts:288 / §4): `status: "suspended"` + `checkpointToken` carries the resume
+        // capability and `verification.unverifiedReason: "suspended"` disambiguates it. A consumer MUST branch on
+        // `status === "suspended"` FIRST (the verify-stack contract), exactly like {@link runWithVerification}.
+        // `terminal` is NOT a verdict here (the loop reached no oracle verdict — the worker paused mid-attempt);
+        // it is set to `gave_up` only as the typed placeholder (RepairTerminal has no "suspended" member by spec).
+        // The repairBundle is carried on that checkpoint by the suspend path (§4) so a resume re-seeds attemptCount
+        // monotonically; we do NOT re-grade a half-done result here (no false candidate on an unfinished run).
+        if (isDurablePause(result.status)) {
+            return {
+                ...result,
+                terminal: "gave_up",
+                bundle,
+                ...(isolationClass ? { isolationClass } : {}),
+                verification: { verdict: "unverified", unverifiedReason: result.status === "needs_review" ? "needs_review" : "suspended", rounds: bundle.attemptCount, findings: [] },
+            };
+        }
+        // ── ORACLE: the injected, trusted closure grades the candidate in the ISOLATED grader env. The repair loop
+        // never composes its internals; it only reads the OracleResult. Recompute evidence from the worker result
+        // (the oracle owns the post-resume freshness — verify.ts:328 BUG5; here `evidence` is the worker report).
+        const oracle = await config.oracle(config.graderEnv, result.result);
+        lastOracle = oracle;
+        bundle.oracleTier = oracle.tier;
+        const projected = terminalForTier(oracle);
+        config.onAttempt?.({ attempt: bundle.attemptCount, terminal: projected, oracle });
+        if (projected !== undefined) {
+            // PASS → candidate_only (or needs_human_oracle for tier "none"). SAFE-tier never returns `fixed`.
+            // design/77 §1 Gate-1: the projection caps at `candidate_only`, so even an `out_of_process` grader can't
+            // make this loop auto-accept — `isolationClass` is surfaced for the (OFF) auto-accept path to consult,
+            // but `terminal` is NEVER `fixed` here (terminalForTier provably can't return it). Auto-accept stays OFF.
+            return {
+                ...result,
+                terminal: projected,
+                bundle,
+                ...(isolationClass ? { isolationClass } : {}),
+                verification: outcomeFor(projected, oracle, bundle.attemptCount),
+            };
+        }
+        // ── Failed verdict on a usable-oracle tier. Record the trace/diagnosis (monotonic scheduling only — a
+        // failing trace NEVER becomes an accept gate, §5 #3). The raw trace is fed back verbatim (no inner rewrite).
+        if (oracle.trace && oracle.trace.trim() !== "") {
+            bundle.failureTrace = oracle.trace;
+            if (bundle.diagnostics.length < 3)
+                bundle.diagnostics.push(oracle.trace); // Reflexion cap ≤3 (§1)
+        }
+        // Budget backstops (verify.ts:277-278): stop before issuing another attempt; gave_up with the findings.
+        const overTime = config.totalTimeoutMs != null && Date.now() - startedAt >= config.totalTimeoutMs;
+        const overCost = config.costCeilingMicroUsd != null && spend >= config.costCeilingMicroUsd;
+        // Attempts exhausted (or budget hit): try ONE clean restart (fresh session, discard the failed transcript),
+        // else give up. give_up/conflict are first-class abstains — NEVER "satisfy the test" (§5 #2).
+        if (bundle.attemptCount >= maxAttempts || overTime || overCost) {
+            if (bundle.attemptCount >= maxAttempts && !overTime && !overCost && lastResult !== undefined && !restartUsed) {
+                // CLEAN_RESTART one-shot: a fresh runTask with a NEW session, in-memory bundle, no checkpoint hop.
+                // Flag it; the next loop iteration consumes the flag and runs cleanRestartSpec(). Allow exactly one.
+                restartUsed = true;
+                restartedOnce = true;
+                continue;
+            }
+            // give_up: attempts exhausted (and the clean restart, if any, also failed). A first-class abstain.
+            const terminal = "gave_up";
+            return { ...lastResult, terminal, bundle, ...(isolationClass ? { isolationClass } : {}), verification: outcomeFor(terminal, lastOracle, bundle.attemptCount) };
+        }
+        // else: REPAIR — loop again with the fix objective on the same session.
+    }
+}
+//# sourceMappingURL=repair-loop.js.map

package/dist/agents/repair-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair-loop.js","sourceRoot":"","sources":["../../src/agents/repair-loop.ts"],"names":[],"mappings":"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"}

package/dist/agents/session-util.d.ts

@@ -0,0 +1,8 @@
+import type { Runner } from "../core/runner/runtask.js";
+/**
+ * Release a throwaway session, swallowing errors — best-effort cleanup for the verifier/cascade-rung
+ * sessions that agents spin up and discard. Always call this in a `finally` so a throwing `runTask`
+ * result handler or caller hook (`onRung`/`onRound`) can't leak the session.
+ */
+export declare function releaseSession(runner: Runner, sessionId: string): Promise<void>;
+//# sourceMappingURL=session-util.d.ts.map

package/dist/agents/session-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-util.d.ts","sourceRoot":"","sources":["../../src/agents/session-util.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAExD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErF"}

package/dist/agents/session-util.js

@@ -0,0 +1,9 @@
+/**
+ * Release a throwaway session, swallowing errors — best-effort cleanup for the verifier/cascade-rung
+ * sessions that agents spin up and discard. Always call this in a `finally` so a throwing `runTask`
+ * result handler or caller hook (`onRung`/`onRound`) can't leak the session.
+ */
+export async function releaseSession(runner, sessionId) {
+    await runner.sessions.release(sessionId).catch(() => undefined);
+}
+//# sourceMappingURL=session-util.js.map

package/dist/agents/session-util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-util.js","sourceRoot":"","sources":["../../src/agents/session-util.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAc,EAAE,SAAiB;IACpE,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;AAClE,CAAC"}