@kylecheng3146/agent-ops 0.10.2 → 0.11.1

package/dist/runtime/src/task/debug.js

@@ -1,632 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { canonicalJson, calculateConfigHash } from "../config/hash.js";
-import { sha256 } from "../fs/hash.js";
-import { AgentOpsError } from "../fs/paths.js";
-import { readPrivateFile } from "../security/permissions.js";
-import { validateEvidence } from "../schema/validate.js";
-import { FileEvidenceStore } from "../verify/evidence.js";
-import { acceptanceCoverage } from "../verify/acceptance-coverage.js";
-import { collectBaseChangePaths, collectChangeSurface } from "../verify/change-surface.js";
-import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
-import { resolveReviewScope } from "../review/scope.js";
-import { runVerificationCommand } from "../verify/spawn.js";
-import { checkTaskVerificationEvidence } from "./completion.js";
-import { taskContractHash, criterionContractHash } from "./contract.js";
-import { DEBUG_EXTENSION_MS, debugSpentMs, debugProofDigest, debugRemainingMs, debugRounds, debugStopCause } from "./debug-state.js";
-import { FileTaskStore } from "./store.js";
-import { debugUserControl, readDebugUserEvent } from "./debug-user-event.js";
-import { readWorktreeRecord } from "../parallel/service.js";
-import { evaluateGuardrail } from "../guardrails/evaluate.js";
-import { sameDebugText } from "./debug-intake.js";
-import { nativeProcessIdentity } from "../run/transport.js";
-import { declareEscape, LEDGER_DIRECTORY, removeEscapeRecord, resolveOrigin } from "../escape/link.js";
-function fail(code, message) { throw new AgentOpsError(code, message); }
-const bounded = (v) => typeof v === "string" && v.trim().length > 0 && v.length <= 4096 && !v.includes("\0");
-const session = (v) => bounded(v) && v.length <= 256;
-async function processState(operation) {
-    if (operation.processId === undefined || operation.processIdentity === undefined)
-        return "unknown";
-    try {
-        process.kill(operation.processId, 0);
-    }
-    catch (error) {
-        const code = error.code;
-        if (code === "ESRCH")
-            return "dead";
-        if (code !== "EPERM")
-            return "unknown";
-    }
-    const identity = await nativeProcessIdentity(operation.processId);
-    if (identity === null)
-        return "unknown";
-    return identity === operation.processIdentity ? "alive" : "dead";
-}
-export class DebugService {
-    options;
-    constructor(options) {
-        this.options = options;
-    }
-    async root(taskId) {
-        const state = await this.options.store.read();
-        const task = state.tasks.find(r => r.task.id === taskId);
-        let root = state.tasks.find(r => r.task.id === task?.task.debug?.rootTaskId);
-        if (root?.debug !== undefined && root.debug.ownerRoot !== this.options.root) {
-            const owner = root.debug.ownerRoot;
-            root = (await new FileTaskStore(join(owner, ".agent-ops/tasks/state.json"), owner).read()).tasks.find(r => r.task.id === task?.task.debug?.rootTaskId);
-            if (root?.debug?.ownerRoot !== owner)
-                fail("TASK_DEBUG_ROOT_MISMATCH", "Original issue owner is unavailable; never recreate its counters.");
-        }
-        if (task === undefined || root?.debug === undefined)
-            return fail("TASK_DEBUG_REQUIRED", "This task is not attached to an original debug issue.");
-        if (root.debug.rootTaskId !== root.task.id || root.task.goal !== task.task.goal)
-            return fail("TASK_DEBUG_ROOT_MISMATCH", "Debug root identity and original goal must match.");
-        return root;
-    }
-    async #mutate(previous, next) {
-        const owner = previous.debug.ownerRoot;
-        const store = owner === this.options.root ? this.options.store : new FileTaskStore(join(owner, ".agent-ops/tasks/state.json"), owner);
-        await store.mutate(state => {
-            const index = state.tasks.findIndex(r => r.task.id === previous.task.id);
-            if (index < 0 || canonicalJson(state.tasks[index]) !== canonicalJson(previous))
-                fail("TASK_DEBUG_STATE_CHANGED", "Concurrent state preserved; reload the debug issue.");
-            state.tasks[index] = { ...previous, debug: next, updatedAt: new Date().toISOString() };
-        });
-    }
-    async #scope(taskId) {
-        const task = await this.options.tasks.status({ taskId });
-        const config = await this.options.loadConfig();
-        const surface = await collectChangeSurface(this.options.gitRunner);
-        let scope;
-        try {
-            scope = surface.paths.length > 0 ? { mode: "worktree", changedFiles: surface.paths } : await resolveReviewScope({ root: this.options.root, runner: this.options.gitRunner,
-                ...(this.options.base === undefined ? {} : { base: this.options.base }), ...(task.noChangePaths === undefined ? {} : { noChangePaths: task.noChangePaths }) });
-        }
-        catch (error) {
-            if (!(error instanceof AgentOpsError) || error.code !== "REVIEW_NO_CHANGE_SURFACE")
-                throw error;
-            scope = { mode: "worktree", changedFiles: surface.paths };
-        }
-        return { task, config, sourceFingerprint: await calculateSourceFingerprint(this.options.root, scope, this.options.gitRunner) };
-    }
-    async #productDigest(state) {
-        const records = await this.options.tasks.list();
-        const materials = new Set(records.flatMap(r => r.task.criteria.flatMap(c => c.acceptance?.bindings.flatMap(b => b.materials.map(m => m.path)) ?? [])));
-        const paths = new Set([...await collectBaseChangePaths(this.options.gitRunner, state.baselineCommit), ...(await collectChangeSurface(this.options.gitRunner)).paths]);
-        // The escape ledger is data about the fix, not a repair candidate.
-        const product = [...paths].filter(path => !materials.has(path) && !path.startsWith(LEDGER_DIRECTORY + "/") && !/(?:^|\/)(?:tests?|fixtures)(?:\/|$)|(?:\.test|\.spec)\./u.test(path)).sort();
-        const entries = [];
-        for (const path of product) {
-            try {
-                entries.push({ path, hash: sha256(await readFile(join(this.options.root, path))) });
-            }
-            catch (error) {
-                if (error.code !== "ENOENT")
-                    throw error;
-                entries.push({ path, hash: sha256("deleted") });
-            }
-        }
-        return sha256(canonicalJson(entries));
-    }
-    /** Seal an operation only after its persisted process identity proves death. */
-    async #recoverInterrupted(root) {
-        const operation = root.debug.operation;
-        if (operation === null)
-            return root;
-        const state = await processState(operation);
-        if (state === "alive")
-            fail("TASK_DEBUG_OPERATION_RUNNING", "The previous debug operation is still alive; preserve its checkpoint and do not take it over.");
-        if (state === "unknown")
-            fail("TASK_DEBUG_OPERATION_RECOVERY_REQUIRED", "The previous debug operation has no trustworthy process-death proof; preserve it and obtain host reconciliation.");
-        const finishedAt = Date.now();
-        const durationMs = Math.max(0, finishedAt - operation.startedAt);
-        const foreground = root.debug.foreground;
-        const foregroundBeforeOperation = foreground === undefined || foreground === null ? 0 : Math.max(0, Math.min(finishedAt, operation.startedAt) - foreground.startedAt);
-        const receipt = {
-            id: operation.id,
-            taskId: operation.taskId,
-            kind: operation.kind,
-            contractHash: operation.contractHash,
-            configHash: operation.configHash,
-            sourceFingerprint: operation.sourceFingerprint,
-            productDigest: operation.productDigest,
-            durationMs,
-            finishedAt,
-            round: false,
-            progress: [],
-            references: [`operation:${operation.id}`],
-            outcome: "UNKNOWN",
-            cause: "environment"
-        };
-        const next = { ...root.debug, operation: null, foreground: null, consumedMs: root.debug.consumedMs + foregroundBeforeOperation + durationMs,
-            receipts: [...root.debug.receipts, receipt], checkpoint: null };
-        await this.#mutate(root, next);
-        return await this.root(root.task.id);
-    }
-    /**
-     * `sealed` admits a strategy switch's citation of this issue's own sealed
-     * regression history: a scope revision stales every current reference while
-     * verification stays stopped until the switch is recorded. Hypotheses and
-     * delivery still need evidence for the current contract and candidate.
-     */
-    async #evidence(taskId, reference, sealed = false) {
-        const { task, config, sourceFingerprint } = await this.#scope(taskId);
-        const store = new FileEvidenceStore(this.options.root, this.options.root);
-        const checked = validateEvidence(await store.load(reference));
-        if (!checked.ok)
-            return fail("TASK_DEBUG_EVIDENCE_INVALID", "Use an actual current acceptance execution reference.");
-        const e = checked.value, p = e.acceptance;
-        const root = await this.root(taskId);
-        const head = await this.options.gitRunner.run(["rev-parse", "HEAD"]);
-        const candidate = new TextDecoder().decode(head.stdout).trim();
-        const current = p !== undefined && e.taskContractHash === taskContractHash(task.task) && e.configHash === calculateConfigHash(config) &&
-            e.sourceFingerprint === sourceFingerprint && p.pairedCommit === (p.phase === "baseline" ? candidate : root.debug.baselineCommit) &&
-            p.commit === (p.phase === "baseline" ? root.debug.baselineCommit : candidate);
-        const historical = sealed && p !== undefined && (p.phase === "baseline" ? p.commit : p.pairedCommit) === root.debug.baselineCommit &&
-            root.debug.receipts.some(r => r.kind === "verify" && r.taskId === taskId && r.references.includes(reference));
-        if (head.exitCode !== 0 || e.taskId !== taskId || p === undefined || !(current || historical) ||
-            !task.task.criteria.some(c => c.id === e.criterionId && c.acceptance?.mode === "behavioral" && c.acceptance.baselineCommit === root.debug.baselineCommit &&
-                (current
-                    ? p.criterionContractHash === criterionContractHash(c) && c.acceptance.bindings.some(b => b.runnerId === e.commandId && sha256(canonicalJson({ runnerId: b.runnerId, materials: b.materials })) === p.bindingHash)
-                    : c.acceptance.bindings.some(b => b.runnerId === e.commandId))))
-            return fail("TASK_DEBUG_EVIDENCE_STALE", "Evidence must discriminate the original issue at its immutable baseline and current candidate.");
-        const source = await readPrivateFile(join(this.options.root, p.executionArtifact), this.options.root);
-        if (source === null || p.executionArtifact !== ".agent-ops/tasks/acceptance/" + sha256(source) + ".json")
-            return fail("TASK_DEBUG_EVIDENCE_INVALID", "Execution artifact is missing or modified.");
-        const actual = JSON.parse(source);
-        if (actual.run?.completed !== true || actual.aggregate?.status === "UNKNOWN" || actual.commit !== p.commit || actual.pairedCommit !== p.pairedCommit || actual.runner?.id !== e.commandId || actual.phase !== p.phase ||
-            actual.materialDigest !== p.materialDigest || actual.executionDigest !== p.executionDigest ||
-            p.checks.some(check => !actual.run.results?.some((r) => r.checkId === check.checkId && r.status === check.status && r.attempts === 1 &&
-                (r.failureClass === "assertion-failed" ? "assertion" : r.failureClass) === check.failureClass)))
-            return fail("TASK_DEBUG_EVIDENCE_INVALID", "Only completed, single-attempt assertion execution can resolve a hypothesis.");
-        return e;
-    }
-    async hypothesis(taskId, input) {
-        if (Object.keys(input).some(k => !["id", "statement", "method", "expected", "reason", "reference", "checkId", "expectedStatus", "action"].includes(k)) ||
-            ![input.id, input.statement, input.method, input.expected, input.checkId].every(bounded) || !["PASS", "FAIL"].includes(input.expectedStatus ?? "") ||
-            (input.action !== undefined && (!["investigate", "observe"].includes(input.action) || input.reference !== undefined)))
-            fail("TASK_DEBUG_HYPOTHESIS_INVALID", "A hypothesis needs a bounded statement, verification method and expected result; status is runtime-derived.");
-        if (evaluateGuardrail({ kind: "content", content: JSON.stringify(input), scope: this.options.root }).action === "block")
-            fail("TASK_DEBUG_SENSITIVE_INPUT", "Do not save literal credentials in hypothesis proof.");
-        const root = await this.root(taskId), next = structuredClone(root.debug);
-        if (root.status !== "active" || next.operation !== null)
-            fail("TASK_DEBUG_BUSY", "Hypothesis changes need an active idle issue.");
-        let h = next.hypotheses.find(h => h.id === input.id);
-        if (h === undefined) {
-            const resolved = next.hypotheses.find(o => ["confirmed", "rejected"].includes(o.status) && sameDebugText(o.statement, input.statement) && sameDebugText(o.method, input.method));
-            if (resolved !== undefined)
-                fail("TASK_DEBUG_REJECTED_CAUSE", `Hypothesis ${resolved.id} already resolved this cause; reopen it with new discriminating evidence instead of a new id.`);
-            if (next.hypotheses.length >= 32)
-                fail("TASK_DEBUG_HISTORY_LIMIT", "Hypothesis history is full; preserve it and report the blocker.");
-            h = { id: input.id, statement: input.statement, method: input.method, expected: input.expected, checkId: input.checkId, expectedStatus: input.expectedStatus, status: "proposed", supporting: [], opposing: [], actual: "", history: [] };
-            next.hypotheses.push(h);
-        }
-        else if (h.statement !== input.statement || h.method !== input.method || h.expected !== input.expected || h.checkId !== input.checkId || h.expectedStatus !== input.expectedStatus)
-            fail("TASK_DEBUG_HYPOTHESIS_IMMUTABLE", "Retain the hypothesis and create a distinct falsifiable alternative.");
-        if (input.action !== undefined) {
-            if (["confirmed", "rejected"].includes(h.status))
-                fail("TASK_DEBUG_REJECTED_CAUSE", "Resolved hypotheses need new discriminating evidence, not another identical investigation.");
-            const { task, config, sourceFingerprint } = await this.#scope(taskId);
-            if (!task.task.criteria.some(c => c.acceptance?.mode === "behavioral" && c.acceptance.bindings.some(b => (b.redCheckIds ?? []).includes(input.checkId))))
-                fail("TASK_DEBUG_HYPOTHESIS_UNPROVEN", "Investigation must name a declared original-issue regression check.");
-            if (input.action === "investigate") {
-                h.status = "investigating";
-                h.actual = "Selected original-issue check for investigation; no cause is confirmed.";
-            }
-            else {
-                const receipt = next.receipts.at(-1);
-                if (h.status !== "investigating" || receipt?.kind !== "verify" || receipt.outcome !== "UNKNOWN" || receipt.taskId !== taskId ||
-                    receipt.contractHash !== taskContractHash(task.task) || receipt.configHash !== calculateConfigHash(config) || receipt.sourceFingerprint !== sourceFingerprint)
-                    fail("TASK_DEBUG_HYPOTHESIS_UNPROVEN", "Inconclusive needs the current runtime-recorded UNKNOWN verification for this investigating hypothesis.");
-                h.status = "inconclusive";
-                h.actual = "Verification could not establish the hypothesis: UNKNOWN";
-            }
-            const references = input.action === "observe" ? next.receipts.at(-1).references : [];
-            if (h.history.at(-1)?.status !== h.status || h.history.at(-1)?.actual !== h.actual)
-                h.history.push({ status: h.status, actual: h.actual, references: [...references], reason: input.reason ?? "Runtime-derived investigation state; unresolved evidence cannot confirm a cause." });
-        }
-        else if (input.reference !== undefined) {
-            const e = await this.#evidence(taskId, input.reference);
-            const check = e.acceptance.checks.find(c => c.checkId === input.checkId);
-            if (!root.debug.regressionChecks.includes(e.commandId + ":" + input.checkId) || check === undefined || !["PASS", "FAIL"].includes(check.status) || !["PASS", "FAIL"].includes(input.expectedStatus ?? "") ||
-                (check.status === "FAIL" && check.failureClass !== "assertion"))
-                fail("TASK_DEBUG_HYPOTHESIS_UNPROVEN", "Name a real discriminating check and its expected outcome.");
-            if (h.status === "rejected" && (!bounded(input.reason) || [...h.supporting, ...h.opposing].includes(input.reference)))
-                fail("TASK_DEBUG_REJECTED_CAUSE", "A rejected cause needs new discriminating evidence and a preserved reopening reason.");
-            const matches = check.status === input.expectedStatus;
-            if ((matches ? h.supporting : h.opposing).includes(input.reference))
-                return structuredClone(h);
-            h.actual = `${e.acceptance.phase}:${check.checkId}:${check.status}`;
-            h.status = matches ? "confirmed" : "rejected";
-            (matches ? h.supporting : h.opposing).push(input.reference);
-            h.history.push({ status: h.status, actual: h.actual, references: [input.reference], reason: input.reason ?? "Runtime-reloaded discriminating assertion result." });
-        }
-        else if (h.status === "rejected")
-            fail("TASK_DEBUG_REJECTED_CAUSE", "Rejected hypotheses cannot reopen without new evidence.");
-        next.checkpoint = null;
-        await this.#mutate(root, next);
-        return structuredClone(h);
-    }
-    async strategy(taskId, input) {
-        const root = await this.root(taskId);
-        if (Object.keys(input).some(k => !["from", "to", "reason", "reference"].includes(k)) || !Object.values(input).every(bounded) ||
-            input.to.trim().length < 20 || input.reason.trim().length < 20 || input.from.replace(/\W/gu, "").toLowerCase() === input.to.replace(/\W/gu, "").toLowerCase())
-            fail("TASK_DEBUG_STRATEGY_INVALID", "Document a substantive different verification method and evidence-backed reason.");
-        if (debugStopCause(root.debug) !== "strategy-required" || root.debug.strategy !== null || root.debug.operation !== null)
-            fail("TASK_DEBUG_STRATEGY_NOT_ALLOWED", "Exactly one strategy switch is allowed after two stagnant repair rounds.");
-        await this.#evidence(taskId, input.reference, true);
-        await this.#mutate(root, { ...root.debug, strategy: { from: input.from, to: input.to, reason: input.reason, references: [input.reference], afterRound: debugRounds(root.debug) }, checkpoint: null });
-    }
-    /** Escape Loop: where the confirmed cause came from, bound into the contract before review. */
-    async origin(taskId, input) {
-        const root = await this.root(taskId);
-        if (root.task.id !== taskId)
-            fail("ESCAPE_ORIGIN_INVALID", "Declare the origin on the original issue task.");
-        if (root.status !== "active" || root.debug.operation !== null)
-            fail("TASK_DEBUG_BUSY", "Origin needs an active idle issue.");
-        if (debugRemainingMs(root.debug) === 0)
-            fail("TASK_DEBUG_BUDGET_EXHAUSTED", "The original issue's active budget is exhausted.");
-        if (!root.debug.hypotheses.some(h => h.status === "confirmed"))
-            fail("ESCAPE_ORIGIN_EARLY", "Declare the origin only after discriminating evidence confirms a hypothesis.");
-        const origin = await resolveOrigin(this.options.gitRunner, input);
-        const record = await this.options.tasks.revise(taskId, { expectedContractHash: taskContractHash(root.task), origin, debugOrigin: true,
-            reason: `Declare issue origin: ${origin.kind === "escape-of" ? "escape-of " + origin.commit : origin.kind}.` });
-        if (origin.kind !== "escape-of") {
-            await removeEscapeRecord(this.options.root, taskId);
-            return { record };
-        }
-        return { record, escape: await declareEscape({ root: this.options.root, git: this.options.gitRunner, taskId, origin,
-                base: root.debug.baselineCommit, now: new Date().toISOString() }) };
-    }
-    async remaining(taskId) { return debugRemainingMs((await this.root(taskId)).debug); }
-    async #userEvent(sessionId, home, kind = "latest") {
-        const record = await readWorktreeRecord(this.options.root);
-        const origin = record?.mainRoot ?? this.options.root;
-        try {
-            return await readDebugUserEvent(origin, sessionId, home, kind, origin === this.options.root ? undefined : this.options.root);
-        }
-        catch (error) {
-            if (origin === this.options.root || !(error instanceof AgentOpsError) || error.code !== "TASK_DEBUG_GRANT_UNSUPPORTED")
-                throw error;
-            return await readDebugUserEvent(this.options.root, sessionId, home, kind);
-        }
-    }
-    /** Only the native transcript can change the human's investigation scope. */
-    async syncNativeControl(taskId, sessionId, home) {
-        let event;
-        try {
-            event = await this.#userEvent(sessionId, home, "control");
-        }
-        catch (error) {
-            if (error instanceof AgentOpsError && error.code === "TASK_DEBUG_GRANT_UNSUPPORTED")
-                return;
-            throw error;
-        }
-        let root = await this.root(taskId);
-        if (event.timestamp < Date.parse(root.createdAt) || root.debug.control?.eventId === event.id ||
-            event.timestamp <= (root.debug.control?.timestamp ?? 0))
-            return;
-        const action = debugUserControl(event.text);
-        if (action === null)
-            return;
-        const attached = await this.options.tasks.status({ sessionId });
-        if (attached.task.debug?.rootTaskId !== root.task.id || root.status !== "active")
-            fail("TASK_DEBUG_CONTROL_INVALID", "Human control must belong to the active attached original issue.");
-        if (action === "unlimited" || ((action === "resume" || action === "repair") && debugRemainingMs(root.debug) === 0)) {
-            try {
-                await this.extend(taskId, sessionId, event.id, home);
-            }
-            catch (error) {
-                if (!(error instanceof AgentOpsError) || !["TASK_DEBUG_GRANT_INVALID", "TASK_DEBUG_GRANT_UNSUPPORTED"].includes(error.code))
-                    throw error;
-            }
-            root = await this.root(taskId);
-        }
-        if (action === "pause") {
-            await this.foregroundStop(taskId, sessionId);
-            root = await this.root(taskId);
-        }
-        await this.#mutate(root, { ...root.debug, control: {
-                mode: action === "diagnose" ? "diagnose" : action === "repair" ? "full" : root.debug.control?.mode ?? "full",
-                paused: action === "pause", sessionId, eventId: event.id, sourceDigest: event.sourceDigest, timestamp: event.timestamp
-            }, checkpoint: null });
-        if (action === "pause" && (await this.root(taskId)).debug.operation === null)
-            await this.checkpoint(taskId, sessionId);
-    }
-    /** A native Interrupt is itself a human pause signal; no CLI actor flag exists. */
-    async interrupt(taskId, sessionId, nativeInput) {
-        const attached = await this.options.tasks.status({ sessionId });
-        let root = await this.root(taskId);
-        if (attached.task.debug?.rootTaskId !== root.task.id || root.status !== "active")
-            fail("TASK_DEBUG_CONTROL_INVALID", "Interrupt must belong to the attached original issue.");
-        await this.foregroundStop(taskId, sessionId);
-        root = await this.root(taskId);
-        const sourceDigest = sha256(nativeInput);
-        await this.#mutate(root, { ...root.debug, control: { mode: root.debug.control?.mode ?? "full", paused: true, sessionId,
-                eventId: sha256("Interrupt:" + sessionId + ":" + sourceDigest), sourceDigest, timestamp: Date.now() }, checkpoint: null });
-        if ((await this.root(taskId)).debug.operation === null)
-            await this.checkpoint(taskId, sessionId);
-    }
-    async diagnosisProven(taskId) {
-        const root = await this.root(taskId);
-        if (root.debug.control?.mode !== "diagnose" || root.debug.operation !== null)
-            return false;
-        for (const h of root.debug.hypotheses.filter(h => h.status === "confirmed" && h.expectedStatus === "FAIL" && h.actual === `baseline:${h.checkId}:FAIL`)) {
-            const reference = h.supporting.at(-1);
-            if (reference === undefined)
-                continue;
-            try {
-                const evidence = await this.#evidence(taskId, reference);
-                if (root.debug.regressionChecks.includes(evidence.commandId + ":" + h.checkId) && evidence.acceptance?.phase === "baseline" &&
-                    evidence.acceptance.checks.some(c => c.checkId === h.checkId && c.status === "FAIL" && c.failureClass === "assertion"))
-                    return true;
-            }
-            catch (error) {
-                if (!(error instanceof AgentOpsError) || !["TASK_DEBUG_EVIDENCE_INVALID", "TASK_DEBUG_EVIDENCE_STALE"].includes(error.code))
-                    throw error;
-            }
-        }
-        return false;
-    }
-    async prepareStop(taskId, sessionId) {
-        await this.syncNativeControl(taskId, sessionId);
-        const root = await this.root(taskId);
-        if (root.debug.operation === null && (root.debug.control?.paused === true || await this.diagnosisProven(taskId)))
-            await this.checkpoint(taskId, sessionId);
-    }
-    async #begin(taskId, kind) {
-        let root = await this.root(taskId);
-        root = await this.#recoverInterrupted(root);
-        const { task, config, sourceFingerprint } = await this.#scope(taskId);
-        if (root.status !== "active" || root.debug.operation !== null)
-            fail("TASK_DEBUG_BUSY", "The original issue has a running or interrupted operation; preserve its checkpoint.");
-        if (root.debug.receipts.length >= 256)
-            fail("TASK_DEBUG_HISTORY_LIMIT", "Execution history is full; retain it and report the blocker.");
-        const productDigest = await this.#productDigest(root.debug);
-        // EVIDENCE-SURFACE-001: intake may start without a surface, the first repair may not.
-        if (kind === "verify" && task.task.surfaceRequired === true && task.task.surface === undefined && productDigest !== sha256(canonicalJson([])))
-            fail("SURFACE_MISSING", "Add the surface audit with task revise --surface-file before verifying the first repair.");
-        const previousVerify = root.debug.receipts.filter(r => r.kind === "verify" && (r.outcome === "PASS" || r.outcome === "FAIL")).at(-1);
-        const previousCandidate = previousVerify?.productDigest ?? sha256("[]");
-        const cause = debugStopCause(root.debug);
-        // Recovery reruns the original verifier; changed product content still needs fresh proof.
-        // At the round limit an unchanged PASS candidate may be re-verified (not a new round), e.g. after an
-        // escape-ledger update moved the source fingerprint; a FAIL cannot be re-run into proof at the cap.
-        if (cause !== null && !(["environment", "permission"].includes(cause) && (kind === "investigate" || kind === "verify")) &&
-            !(cause === "iterations" && productDigest === previousCandidate && (kind === "review" || (kind === "verify" && previousVerify?.outcome === "PASS"))))
-            fail("TASK_DEBUG_STOP_REQUIRED", `Runtime stop predicate: ${cause}. Record a checkpoint; resume alone cannot reset it.`);
-        const processIdentity = await nativeProcessIdentity(process.pid);
-        if (processIdentity === null)
-            fail("TASK_DEBUG_PROCESS_IDENTITY_REQUIRED", "The host cannot prove the debug operation process identity; preserve the issue and report the unsupported environment.");
-        const operation = { id: randomUUID(), taskId, kind, startedAt: Date.now(), contractHash: taskContractHash(task.task), configHash: calculateConfigHash(config), sourceFingerprint, productDigest, processId: process.pid, processIdentity };
-        await this.#mutate(root, { ...root.debug, operation, checkpoint: null });
-        return operation;
-    }
-    async #end(operation, outcome, references, progress, cause) {
-        const finishedAt = Date.now();
-        const durationMs = Math.max(0, finishedAt - operation.startedAt);
-        for (let attempt = 0; attempt < 3; attempt += 1) {
-            try {
-                const root = await this.root(operation.taskId);
-                if (root.debug.operation?.id !== operation.id)
-                    fail("TASK_DEBUG_OPERATION_CHANGED", "The timed operation changed; its result cannot be adopted.");
-                const previous = root.debug.receipts.filter(r => r.kind === "verify" && (r.outcome === "PASS" || r.outcome === "FAIL")).at(-1)?.productDigest ?? sha256("[]");
-                const round = operation.kind === "verify" && (outcome === "PASS" || outcome === "FAIL") && operation.productDigest !== previous;
-                const receipt = { id: operation.id, taskId: operation.taskId, kind: operation.kind, contractHash: operation.contractHash, configHash: operation.configHash,
-                    sourceFingerprint: operation.sourceFingerprint, productDigest: operation.productDigest, durationMs, finishedAt, round, progress, references, outcome, cause };
-                const foreground = root.debug.foreground;
-                const operationBeforeForeground = foreground === undefined || foreground === null ? durationMs : Math.max(0, Math.min(finishedAt, foreground.startedAt) - operation.startedAt);
-                const next = { ...root.debug, operation: null, consumedMs: root.debug.consumedMs + operationBeforeForeground, receipts: [...root.debug.receipts, receipt], checkpoint: null };
-                await this.#mutate(root, next);
-                return;
-            }
-            catch (error) {
-                if (!(error instanceof AgentOpsError) || error.code !== "TASK_DEBUG_STATE_CHANGED" || attempt === 2)
-                    throw error;
-            }
-        }
-    }
-    /** Called only around the existing verifier; outcomes are reloaded from sealed evidence. */
-    async verification(taskId, execute) {
-        const initial = await this.root(taskId);
-        if (initial.debug.regressionChecks.length === 0) {
-            const record = await this.options.tasks.status({ taskId });
-            const checks = [...new Set(record.task.criteria.flatMap(c => c.acceptance?.mode === "behavioral" ? c.acceptance.bindings.flatMap(b => (b.redCheckIds ?? []).map(id => b.runnerId + ":" + id)) : []))];
-            if (checks.length > 0)
-                await this.#mutate(initial, { ...initial.debug, regressionChecks: checks });
-        }
-        const operation = await this.#begin(taskId, "verify");
-        try {
-            const result = await execute();
-            const { task, config, sourceFingerprint } = await this.#scope(taskId);
-            const store = new FileEvidenceStore(this.options.root, this.options.root);
-            const coverage = await acceptanceCoverage(task, config, sourceFingerprint, store);
-            const problem = await checkTaskVerificationEvidence(task, { root: this.options.root, config, sourceFingerprint, evidenceStore: store });
-            const root = await this.root(taskId);
-            const previousProgress = new Set(root.debug.receipts.flatMap(r => r.progress));
-            const proven = coverage.filter(row => row.mode === "behavioral" && row.status === "proven").flatMap(row => {
-                const criterion = task.task.criteria.find(c => c.id === row.criterionId);
-                return criterion?.acceptance?.bindings.flatMap(b => (b.redCheckIds ?? []).map(id => b.runnerId + ":" + id).filter(id => root.debug.regressionChecks.includes(id))) ?? [];
-            });
-            const resolved = root.debug.hypotheses.filter(h => ["confirmed", "rejected"].includes(h.status)).map(h => "hypothesis:" + h.actual);
-            const progress = [...proven, ...resolved].filter(id => !previousProgress.has(id));
-            const refs = [...new Set(Object.values(task.evidence).flat().filter(r => !r.startsWith("review:")))];
-            let environment = false;
-            for (const reference of refs) {
-                const checked = validateEvidence(await store.load(reference));
-                if (checked.ok && checked.value.sourceFingerprint === operation.sourceFingerprint && checked.value.taskContractHash === operation.contractHash && checked.value.status === "UNKNOWN" && checked.value.failureClass !== "debug-budget-exhausted" && !(checked.value.failureClass.includes("timeout") && await this.remaining(taskId) === 0))
-                    environment = true;
-            }
-            await this.#end(operation, problem === null ? "PASS" : environment ? "UNKNOWN" : "FAIL", refs, progress, environment ? "environment" : null);
-            return result;
-        }
-        catch (error) {
-            if ((await this.root(taskId)).debug.operation?.id === operation.id)
-                await this.#end(operation, "UNKNOWN", [], [], error instanceof AgentOpsError && error.code === "TASK_DEBUG_BUDGET_EXHAUSTED" ? null : error instanceof AgentOpsError && /TRUST|DENIED|PERMISSION/u.test(error.code) ? "permission" : "environment");
-            throw error;
-        }
-    }
-    async review(taskId, execute) {
-        const operation = await this.#begin(taskId, "review");
-        try {
-            const result = await execute();
-            await this.#end(operation, result.status === "PASS" ? "PASS" : result.status === "FAIL" ? "FAIL" : "UNKNOWN", [], [], null);
-            return result;
-        }
-        catch (error) {
-            if ((await this.root(taskId)).debug.operation?.id === operation.id)
-                await this.#end(operation, "UNKNOWN", [], [], "environment");
-            throw error;
-        }
-    }
-    async investigate(taskId, commandId, trusted) {
-        const current = await this.root(taskId);
-        if (current.debug.receipts.at(-1)?.cause !== null && current.debug.receipts.at(-1)?.cause !== undefined && current.debug.receipts.at(-1)?.references[0] !== "command:" + commandId)
-            fail("TASK_DEBUG_RECOVERY_COMMAND_REQUIRED", "Retry the same blocked command or original regression verifier; unrelated green commands cannot clear a blocker.");
-        const operation = await this.#begin(taskId, "investigate");
-        try {
-            const config = await this.options.loadConfig();
-            const command = config.verification.commands.find(c => c.id === commandId);
-            if (!trusted || command === undefined)
-                fail("TASK_DEBUG_COMMAND_DENIED", "Investigation executes only a currently trusted configured command.");
-            const result = await runVerificationCommand({ ...command, timeoutMs: Math.min(command.timeoutMs ?? 300_000, await this.remaining(taskId)) }, { cwd: command.cwd === "." ? this.options.root : join(this.options.root, command.cwd) });
-            await this.#end(operation, result.status, ["command:" + commandId], [], result.status === "UNKNOWN" && !(result.timedOut && await this.remaining(taskId) === 0) ? "environment" : null);
-            return result;
-        }
-        catch (error) {
-            if ((await this.root(taskId)).debug.operation?.id === operation.id)
-                await this.#end(operation, "UNKNOWN", [], [], error instanceof AgentOpsError && /DENIED/u.test(error.code) ? "permission" : "environment");
-            throw error;
-        }
-    }
-    /** Start measuring one native foreground turn; host hooks are the only callers. */
-    async foregroundStart(taskId, sessionId) {
-        if (!session(sessionId))
-            fail("TASK_DEBUG_SESSION_INVALID", "A native session identity is required for foreground timing.");
-        let root = await this.root(taskId);
-        root = await this.#recoverInterrupted(root);
-        if (root.status !== "active" || root.debug.operation !== null)
-            fail("TASK_DEBUG_BUSY", "Foreground timing requires an active idle debug issue.");
-        const current = root.debug.foreground;
-        if (current !== undefined && current !== null) {
-            const cause = debugStopCause(root.debug);
-            if (current.sessionId === sessionId && (cause === null || cause === "environment" || cause === "permission"))
-                return;
-            fail("TASK_DEBUG_CLOCK_CONTESTED", "A different or exhausted foreground turn owns the debug clock; preserve it and wait for its native stop event.");
-        }
-        const cause = debugStopCause(root.debug);
-        if (cause !== null && cause !== "environment" && cause !== "permission")
-            fail("TASK_DEBUG_STOP_REQUIRED", `Runtime stop predicate: ${cause}. Obtain the required checkpoint or human grant before starting another turn.`);
-        await this.#mutate(root, { ...root.debug, foreground: { sessionId, startedAt: Date.now() }, checkpoint: null });
-    }
-    /** Close a native foreground turn and account only time outside a running operation. */
-    async foregroundStop(taskId, sessionId) {
-        if (!session(sessionId))
-            return;
-        // A native stop is a trusted foreground boundary even when a controlled
-        // operation is still running.  Recovering first would reject the stop on
-        // a live operation and leave the foreground clock running forever.  Keep
-        // that operation intact; #end will account its complete controlled
-        // interval after the foreground has been closed.  Dead or unverifiable
-        // operations still use the fail-closed recovery path.  The short retry
-        // handles the expected race where the operation finishes while its host
-        // identity is being checked.
-        for (let attempt = 0; attempt < 3; attempt += 1) {
-            try {
-                let root = await this.root(taskId);
-                const operation = root.debug.operation;
-                if (operation === null) {
-                    root = await this.#recoverInterrupted(root);
-                }
-                else {
-                    const state = await processState(operation);
-                    // Reload after the host identity check: an operation can finish
-                    // while that check is running. Recover only when the same operation
-                    // is still persisted; otherwise retain the writer's newer state.
-                    root = await this.root(taskId);
-                    if (root.debug.operation?.id === operation.id && state !== "alive")
-                        root = await this.#recoverInterrupted(root);
-                }
-                const foreground = root.debug.foreground;
-                if (foreground === undefined || foreground === null)
-                    return;
-                if (foreground.sessionId !== sessionId)
-                    fail("TASK_DEBUG_CLOCK_OWNER_MISMATCH", "Only the native session that opened the debug clock may close it.");
-                const now = Date.now();
-                const end = root.debug.operation?.startedAt ?? now;
-                const durationMs = Math.max(0, Math.min(now, end) - foreground.startedAt);
-                await this.#mutate(root, { ...root.debug, foreground: null, consumedMs: root.debug.consumedMs + durationMs,
-                    checkpoint: root.debug.checkpoint?.cause == null ? null : root.debug.checkpoint });
-                return;
-            }
-            catch (error) {
-                if (!(error instanceof AgentOpsError) || error.code !== "TASK_DEBUG_STATE_CHANGED" || attempt === 2)
-                    throw error;
-            }
-        }
-    }
-    async checkpoint(taskId, sessionId) {
-        const recovered = await this.#recoverInterrupted(await this.root(taskId));
-        const root = recovered, { task, config } = await this.#scope(taskId);
-        const attached = await this.options.tasks.status({ sessionId });
-        if (attached.task.debug?.rootTaskId !== root.task.id || root.debug.operation !== null)
-            fail("TASK_DEBUG_CHECKPOINT_INVALID", "A stopped checkpoint must belong to this idle attached issue.");
-        const cause = debugStopCause(root.debug) ?? (await this.diagnosisProven(taskId) ? "diagnosed" : null);
-        const latest = root.debug.receipts.at(-1);
-        if ((cause === "environment" || cause === "permission") && (latest?.contractHash !== taskContractHash(task.task) || latest.configHash !== calculateConfigHash(config) || latest.sourceFingerprint !== (await this.#scope(taskId)).sourceFingerprint))
-            fail("TASK_DEBUG_CHECKPOINT_INVALID", "Blocked receipt must still match its current task, source and policy.");
-        const receiptId = root.debug.receipts.at(-1)?.id ?? "intake:" + root.task.id;
-        const surface = await collectChangeSurface(this.options.gitRunner);
-        const sourceFingerprint = await calculateSourceFingerprint(this.options.root, { mode: "worktree", changedFiles: surface.paths }, this.options.gitRunner);
-        const next = { ...root.debug, checkpoint: { taskId, sessionId, root: this.options.root, sourceFingerprint, contractHash: taskContractHash(task.task), configHash: calculateConfigHash(config), cause, receiptId } };
-        await this.#mutate(root, next);
-        return next;
-    }
-    async validCheckpoint(taskId, sessionId, sourceFingerprint) {
-        const root = await this.root(taskId), checkpoint = root.debug.checkpoint;
-        const { task, config } = await this.#scope(taskId);
-        return root.debug.operation === null && checkpoint !== null && checkpoint.taskId === taskId && checkpoint.sessionId === sessionId &&
-            checkpoint.root === this.options.root && checkpoint.sourceFingerprint === sourceFingerprint && checkpoint.contractHash === taskContractHash(task.task) &&
-            checkpoint.configHash === calculateConfigHash(config) && checkpoint.cause !== null &&
-            (checkpoint.cause === "diagnosed" ? await this.diagnosisProven(taskId) : checkpoint.cause === debugStopCause(root.debug)) &&
-            checkpoint.receiptId === (root.debug.receipts.at(-1)?.id ?? "intake:" + root.task.id);
-    }
-    async proofDigest(taskId) { return debugProofDigest((await this.root(taskId)).debug); }
-    async resume(taskId, sessionId) {
-        const root = await this.#recoverInterrupted(await this.root(taskId)), checkpoint = root.debug.checkpoint, record = await readWorktreeRecord(this.options.root);
-        const task = await this.options.tasks.status({ taskId }), config = await this.options.loadConfig();
-        const surface = await collectChangeSurface(this.options.gitRunner);
-        const fingerprint = await calculateSourceFingerprint(this.options.root, { mode: "worktree", changedFiles: surface.paths }, this.options.gitRunner);
-        if (root.debug.operation !== null || checkpoint === null || record === null || record.path !== this.options.root || record.sessionId !== checkpoint.sessionId ||
-            checkpoint.root !== record.path || checkpoint.taskId !== taskId || checkpoint.sourceFingerprint !== fingerprint ||
-            checkpoint.contractHash !== taskContractHash(task.task) || checkpoint.configHash !== calculateConfigHash(config))
-            fail("TASK_DEBUG_RECOVERY_CONFIRMATION_REQUIRED", "Owned debug checkpoint/path/source/contract/config mismatch. Preserve the checkout and obtain user confirmation before recovery.");
-        await this.options.tasks.attach(sessionId, root.task.id);
-    }
-    async extend(taskId, sessionId, eventId, home) {
-        const root = await this.root(taskId), attached = await this.options.tasks.status({ sessionId });
-        if (attached.task.debug?.rootTaskId !== root.task.id || root.debug.operation !== null)
-            fail("TASK_DEBUG_GRANT_INVALID", "Extension belongs to the original issue and its native session; a running operation cannot be extended.");
-        const event = await this.#userEvent(sessionId, home);
-        if (eventId !== "latest" && eventId !== event.id)
-            fail("TASK_DEBUG_GRANT_INVALID", "The requested event is not the current native human event.");
-        if (root.debug.grants.some(g => g.eventId === event.id))
-            return;
-        const otherCause = debugStopCause({ ...root.debug, consumedMs: 0, foreground: null, operation: null, budgetMs: 86_400_000,
-            ...(root.debug.control === undefined ? {} : { control: { ...root.debug.control, paused: false } }) });
-        const unlimited = debugUserControl(event.text) === "unlimited";
-        if (unlimited && (root.status !== "active" || event.timestamp < Date.parse(root.createdAt)))
-            fail("TASK_DEBUG_GRANT_INVALID", "Only a current native human event can waive the active original issue time limit.");
-        const foregroundActive = root.debug.foreground !== undefined && root.debug.foreground !== null;
-        const remainingAtEvent = debugRemainingMs(root.debug, event.timestamp);
-        const sealedAtCandidates = [Date.parse(root.updatedAt), root.debug.receipts.at(-1)?.finishedAt ?? Number.NaN].filter(Number.isFinite);
-        const lastSealedAt = sealedAtCandidates.length === 0 ? Number.POSITIVE_INFINITY : Math.max(...sealedAtCandidates);
-        const exhaustedAtEvent = foregroundActive
-            ? remainingAtEvent === 0
-            : debugRemainingMs(root.debug) === 0 && event.timestamp > lastSealedAt;
-        if ((!unlimited && !exhaustedAtEvent) || (otherCause !== null && !["environment", "permission"].includes(otherCause)) || !["resume", "repair", "unlimited"].includes(debugUserControl(event.text) ?? ""))
-            fail("TASK_DEBUG_GRANT_INVALID", "Only a contemporaneous human continue event extends exhausted time; other blockers remain authoritative.");
-        await this.#mutate(root, { ...root.debug, grants: [...root.debug.grants, { eventId: event.id, sessionId, sourceDigest: event.sourceDigest, grantedMs: unlimited ? null : DEBUG_EXTENSION_MS, spentAtGrantMs: debugSpentMs(root.debug, event.timestamp) }], checkpoint: null });
-    }
-}