@kylecheng3146/agent-ops 0.8.0 → 0.8.3

package/dist/packages/cli/src/args.js

@@ -75,6 +75,12 @@ export function parseArgs(argv) {
     let targetVersion;
     let title;
     let intent;
+    let taskGoal;
+    let debug = false;
+    let debugAction;
+    let payloadFile;
+    let commandId;
+    let eventId;
     let sessionId;
     let base;
     let parentBase;
@@ -210,6 +216,40 @@ export function parseArgs(argv) {
                 index += 1;
                 break;
             }
+            case "--goal":
+                if (taskGoal !== undefined)
+                    duplicate(token);
+                taskGoal = readOptionValue(argv, index++, token);
+                break;
+            case "--debug":
+                if (debug)
+                    duplicate(token);
+                debug = true;
+                break;
+            case "--debug-action": {
+                if (debugAction !== undefined)
+                    duplicate(token);
+                const value = readOptionValue(argv, index++, token);
+                if (!["status", "hypothesis", "strategy", "investigate", "checkpoint", "resume", "extend"].includes(value))
+                    invalidValue(token, value);
+                debugAction = value;
+                break;
+            }
+            case "--payload-file":
+                if (payloadFile !== undefined)
+                    duplicate(token);
+                payloadFile = readOptionValue(argv, index++, token);
+                break;
+            case "--command-id":
+                if (commandId !== undefined)
+                    duplicate(token);
+                commandId = readOptionValue(argv, index++, token);
+                break;
+            case "--event-id":
+                if (eventId !== undefined)
+                    duplicate(token);
+                eventId = readOptionValue(argv, index++, token);
+                break;
             case "--tree": {
                 if (tree)
                     duplicate(token);
@@ -453,7 +493,7 @@ export function parseArgs(argv) {
                         "complete",
                         "create",
                         "export",
-                        "status", "revise", "replan", "pin-finding"
+                        "status", "revise", "replan", "pin-finding", "debug"
                     ].includes(token)) {
                     action = token;
                     break;
@@ -635,6 +675,15 @@ export function parseArgs(argv) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--worktree may be used only with init or update.");
     }
     const revisionAction = command === "task" && ["revise", "replan", "pin-finding"].includes(action ?? "");
+    if ((taskGoal !== undefined || debug) && !(command === "task" && action === "create"))
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--goal and --debug apply only to task create.");
+    if ((debugAction !== undefined || commandId !== undefined || eventId !== undefined || payloadFile !== undefined) && !(command === "task" && action === "debug"))
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Debug operation options apply only to task debug.");
+    if (command === "task" && action === "debug" && (taskId === undefined || debugAction === undefined || title !== undefined || intent !== undefined ||
+        parentTaskId !== undefined || criteria.length > 0 || evidence.length > 0 ||
+        ((debugAction === "hypothesis" || debugAction === "strategy") !== (payloadFile !== undefined)) ||
+        ((debugAction === "investigate") !== (commandId !== undefined)) || ((debugAction === "extend") !== (eventId !== undefined))))
+        throw new CliArgumentError("CLI_MISSING_VALUE", "Task debug requires --task, --debug-action and the operation's exact payload/command/event options.");
     if ((criterionFiles.length > 0 && !(command === "task" && (action === "create" || action === "pin-finding"))) ||
         (criteriaFile !== undefined && !(command === "task" && action === "revise")) ||
         (planFile !== undefined && !(command === "task" && action === "replan")) ||
@@ -805,6 +854,12 @@ export function parseArgs(argv) {
         ...(targetVersion === undefined ? {} : { targetVersion }),
         ...(title === undefined ? {} : { title }),
         ...(intent === undefined ? {} : { intent }),
+        ...(taskGoal === undefined ? {} : { goal: taskGoal }),
+        ...(debug ? { debug: true } : {}),
+        ...(debugAction === undefined ? {} : { debugAction }),
+        ...(payloadFile === undefined ? {} : { payloadFile }),
+        ...(commandId === undefined ? {} : { commandId }),
+        ...(eventId === undefined ? {} : { eventId }),
         ...(reviewTargets.length === 0 ? {} : { reviewTargets }),
         ...(completionGate === undefined ? {} : { completionGate }),
         ...(office === undefined ? {} : { office }),

package/dist/packages/cli/src/bin.js

@@ -488,6 +488,7 @@ else {
                     return await runTaskCommand({
                         args,
                         service: taskService,
+                        ...(args.action !== "debug" ? {} : { trusted: await (async () => { const binding = await plannedTrustBinding(root, (await loadEffectiveConfig(root, "project")).config); return binding !== null && (await trustStore().status(binding)).status === "TRUSTED"; })() }),
                         ...(policyConfigHash === undefined ? {} : { policyConfigHash }),
                         ...(sessionId === undefined ? {} : { sessionId }),
                         ...(fromMain
@@ -545,16 +546,41 @@ else {
                             reviewActivity = undefined;
                         }
                     });
+                    const debugRecord = reviewArgs.taskId === undefined ? undefined : await taskService.status({ taskId: reviewArgs.taskId });
+                    const inDebug = (executor) => debugRecord?.task.debug === undefined ? executor : async (request) => await taskService.debugService().review(debugRecord.task.id, () => executor(request));
                     const inSlot = (executor) => slotDir === undefined
-                        ? executor
+                        ? inDebug(executor)
                         : async (request) => await withReviewSlot({
                             dir: slotDir,
                             signal,
                             holder: { root, ...(reviewArgs.taskId === undefined ? {} : { taskId: reviewArgs.taskId }) },
+                            ...(debugRecord?.task.debug === undefined || reviewSessionId === undefined
+                                ? {}
+                                : (() => {
+                                    let paused = false;
+                                    const debug = taskService.debugService();
+                                    return {
+                                        onWaitStart: async () => {
+                                            if (paused)
+                                                return;
+                                            const current = await debug.root(debugRecord.task.id).catch(() => null);
+                                            if (current?.debug.foreground?.sessionId !== reviewSessionId)
+                                                return;
+                                            await debug.foregroundStop(debugRecord.task.id, reviewSessionId);
+                                            paused = true;
+                                        },
+                                        onWaitEnd: async () => {
+                                            if (!paused)
+                                                return;
+                                            await debug.foregroundStart(debugRecord.task.id, reviewSessionId);
+                                            paused = false;
+                                        }
+                                    };
+                                })()),
                             onWait: (line) => {
                                 process.stderr.write(`${progressPrefix}${line}\n`);
                             }
-                        }, async () => await executor(request));
+                        }, async () => await inDebug(executor)(request));
                     return {
                         args: reviewArgs,
                         authorized: reviewArgs.yes,
@@ -574,6 +600,7 @@ else {
                         config: reviewConfig,
                         evidenceStore: new FileEvidenceStore(root, root),
                         execute: inActivity(inSlot(createReviewExecutor({
+                            ...(debugRecord?.task.debug === undefined ? {} : { remainingBudgetMs: () => taskService.debugService().remaining(debugRecord.task.id) }),
                             runner: registeredRunProofRunner(),
                             targets: configuredReviewTargets,
                             cwd: root,

package/dist/packages/cli/src/cli.js

@@ -25,7 +25,7 @@ Commands:
   doctor     Diagnose an installation
   update     Update managed artifacts
   uninstall  Remove managed artifacts
-  task <create|status|attach|revise|replan|pin-finding|advance|complete|archive|export>
+  task <create|status|attach|revise|replan|pin-finding|debug|advance|complete|archive|export>
              Manage independent task acceptance state
   verify     Run configured verification
   review     Run an independent review or show recorded reports
@@ -170,13 +170,19 @@ Options:
   --json
   --yes
 `,
-    task: `Usage: agent-ops task <create|status|attach|revise|replan|pin-finding|advance|complete|archive|export> [options]
+    task: `Usage: agent-ops task <create|status|attach|revise|replan|pin-finding|debug|advance|complete|archive|export> [options]
 
 Manage independent task acceptance state. Task commands accept none of
 --harness, --profile or --dry-run. Only advance accepts --yes.
 
 Options:
   --title <text>                        create
+  --goal <text>                         create: immutable original issue/goal
+  --debug                               create: task-level investigation tag
+  --debug-action <status|hypothesis|strategy|investigate|checkpoint|resume|extend>
+  --payload-file <path>                 debug hypothesis/strategy: bounded JSON
+  --command-id <id>                     debug investigate: trusted configured command
+  --event-id <native-event-id|latest>    debug extend: authentic human continue event
   --intent <text>                       create: intended behavior and constraints before editing
   --criterion <json>                    create, repeatable, two to five total
   --criterion-file <path>               create: one criterion object, repeatable; pin-finding: exactly one
@@ -188,7 +194,7 @@ Options:
   --baseline <git-ref>                  create/revise: baseline for new mechanical requirements
   --parent <task-id>                    create: record a subtask; status: list subtasks
   --task <id>                           status, attach, revise, replan, pin-finding, complete, archive, export, advance
-  --session <id>                        create, attach, status, advance
+  --session <id>                        create, attach, status, advance, debug
   --evidence <criterion-id=reference>   complete, repeatable
   --base <git-ref>                      complete: a clean committed range
   --yes                                 advance: authorize the two review sessions

package/dist/packages/cli/src/codex-loop-process.js

@@ -1,5 +1,6 @@
 import { PROJECT_LOOP_EVENTS, resolveProjectLoopRoot, runProjectLoop } from "../../../runtime/src/hooks/codex-loop.js";
 import { officeEnabled, officeLoopPhaseHint } from "./office-entry.js";
+import { routeDebugPrompt } from "./debug-intake.js";
 const MAX_LOOP_INPUT_BYTES = 64 * 1024;
 function isLoopHarness(value) {
     return value === "claude" || value === "codex";
@@ -73,6 +74,11 @@ export async function runLoopProcess(argv, io, dependencies = {}) {
                 ? {}
                 : { telemetryMaxBytes: dependencies.telemetryMaxBytes })
         });
+        if (event === "UserPromptSubmit" && managedRoot !== null && result.exitCode === 0 && result.stdout === "" && result.stderr === "") {
+            const context = await routeDebugPrompt(managedRoot, input, harness).catch(error => `DEBUG intake unavailable: ${error instanceof Error ? error.message : "preserve current state"}`);
+            if (context !== null)
+                io.writeStdout(harness === "claude" ? JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: context } }) : context + "\n");
+        }
         if (result.stdout.length > 0) {
             io.writeStdout(result.stdout);
         }

package/dist/packages/cli/src/commands/hook.js

@@ -28,7 +28,9 @@ export async function runHookCommand(options) {
         const { capabilities } = options.config.profiles.length === 0
             ? { capabilities: [] }
             : resolveCapabilities(options.config);
-        const input = JSON.parse(options.stdin);
+        const input = options.input === undefined
+            ? JSON.parse(options.stdin)
+            : options.input;
         const descriptor = harnessDescriptor(options.harness);
         const normalized = normalizeHookInput(options.harness, input);
         if (normalized === null ||
@@ -55,6 +57,7 @@ export async function runHookCommand(options) {
                 ? {}
                 : { worktreeEnter: options.worktreeEnter })
         });
+        options.onResult?.(result);
         return descriptor.runtime.formatOutput(options.event, result);
     }
     catch {

package/dist/packages/cli/src/commands/review.js

@@ -15,6 +15,7 @@ import { assertSafeSupportingPaths, isReviewerPolicyPath, resolveReviewScope, re
 import { calculateSourceFingerprint } from "../../../../runtime/src/verify/source-fingerprint.js";
 import { calculateConfigHash, isPassingVerificationEvidence } from "../../../../runtime/src/verify/evidence.js";
 import { validateEvidence } from "../../../../runtime/src/schema/validate.js";
+import { loadDebugProof, debugProofDigest } from "../../../../runtime/src/task/debug-state.js";
 import { okEnvelope } from "../output.js";
 /**
  * Review runs against one target. Argument parsing already rejects a
@@ -640,6 +641,7 @@ export async function runReviewCommand(options) {
         }
         context.coverage = rows;
         context.binding = {
+            ...(context.records.every(r => r.task.debug === undefined) || options.root === undefined ? {} : { debugProofs: Object.fromEntries(await Promise.all(context.records.filter(r => r.task.debug !== undefined).map(async (r) => [r.task.id, debugProofDigest(await loadDebugProof(options.root, r.task.debug.rootTaskId))]))) }),
             taskContractHash: taskContractHash(context.records.find(r => r.task.id === context.taskId).task),
             taskContracts: Object.fromEntries(context.records.map(r => [r.task.id, taskContractHash(r.task)])),
             ...(context.treeTasks === undefined ? {} : { treeContractHash: treeContractHash(context.records.map(r => r.task)) }),
@@ -682,7 +684,8 @@ export async function runReviewCommand(options) {
             const content = redactSecrets(JSON.stringify({ binding: context.binding, coverage: context.coverage,
                 executionPolicy: options.config,
                 artifacts: contractArtifacts.map(({ path, digest }) => ({ path, digest })),
-                tasks: context.records.map(r => ({ task: r.task, revisions: r.revisions ?? [] })),
+                tasks: await Promise.all(context.records.map(async (r) => ({ task: r.task, revisions: r.revisions ?? [],
+                    ...(r.task.debug === undefined ? {} : { debugProof: await loadDebugProof(options.root, r.task.debug.rootTaskId) }) }))),
                 superseded: context.historyRecords ?? [] }, null, 2));
             const digest = sha256(content);
             const path = ".agent-ops/tasks/review-contracts/" + digest + ".json";
@@ -719,7 +722,7 @@ export async function runReviewCommand(options) {
     const priorFindings = options.root === undefined || context === undefined
         ? []
         : await findPriorFailingFindings(options.root, context.taskId);
-    const result = await runIndependentReview({
+    const executeReview = async () => await runIndependentReview({
         invocation: {
             harness: target,
             plannedTargets,
@@ -738,6 +741,7 @@ export async function runReviewCommand(options) {
             reason: "missing-cli"
         }))
     });
+    const result = await executeReview();
     if (scope !== undefined && result.report !== undefined && options.root !== undefined) {
         try {
             if (result.report.changedFilesInspected.length !== scope.changedFiles.length ||
@@ -781,7 +785,9 @@ export async function runReviewCommand(options) {
                     await options.tasks.treeContract(context.taskId) !== context.binding.treeContractHash) ||
                 (context !== undefined && options.tasks !== undefined &&
                     (await Promise.all(context.records.map(async (r) => taskContractHash((await options.tasks.status({ taskId: r.task.id })).task))))
-                        .some((hash, i) => hash !== taskContractHash(context.records[i].task)))) {
+                        .some((hash, i) => hash !== taskContractHash(context.records[i].task))) ||
+                (context?.binding?.debugProofs !== undefined && options.root !== undefined &&
+                    (await Promise.all(context.records.filter(r => r.task.debug !== undefined).map(async (r) => debugProofDigest(await loadDebugProof(options.root, r.task.debug.rootTaskId)) !== context.binding.debugProofs[r.task.id]))).some(Boolean))) {
                 const changed = await persistReviewEvidence(options, sourceChangedResult(result), sourceFingerprint, context);
                 return notRunEnvelope(changed);
             }

package/dist/packages/cli/src/commands/task.js

@@ -60,7 +60,7 @@ function taskAction(args) {
             "complete",
             "create",
             "export",
-            "status", "revise", "replan", "pin-finding"
+            "status", "revise", "replan", "pin-finding", "debug"
         ].includes(args.action)) {
         throw new AgentOpsError("TASK_ACTION_INVALID", "A supported task action is required.");
     }
@@ -72,7 +72,7 @@ function taskEnvelope(action, code, message, record) {
         message,
         record,
         contractHash: taskContractHash(record.task),
-        text: renderTaskMarkdown(record) + "\nContract: " + taskContractHash(record.task)
+        text: renderTaskMarkdown(record) + "\nContract: " + taskContractHash(record.task) + (record.debug === undefined ? "" : "\nDEBUG: " + JSON.stringify(record.debug))
     });
 }
 function renderTaskList(records) {
@@ -91,11 +91,15 @@ export async function runTaskCommand(options) {
             if (options.args.title === undefined) {
                 throw new AgentOpsError("TASK_TITLE_REQUIRED", "Task creation requires --title.");
             }
+            if (options.args.debug)
+                await options.service.assertDebugBaseline();
             const worktree = sessionId === undefined || options.sessionWorktree === undefined
                 ? undefined
                 : await options.sessionWorktree(sessionId);
             const record = await (worktree?.service ?? options.service).create({
                 title: options.args.title,
+                ...(options.args.goal === undefined ? {} : { goal: options.args.goal }),
+                ...(options.args.debug ? { debug: {} } : {}),
                 ...(options.args.intent === undefined ? {} : { intent: options.args.intent }),
                 criteria: [...(options.args.criteria ?? []).map(parseCriterion),
                     ...await Promise.all((options.args.criterionFiles ?? []).map(async (path) => await jsonFile(path)))]
@@ -109,6 +113,12 @@ export async function runTaskCommand(options) {
                     : { parentTaskId: options.args.parentTaskId }),
                 ...(sessionId === undefined ? {} : { sessionId })
             });
+            // An explicit CLI DEBUG intake may be the only start signal on hosts
+            // without a prompt hook (notably agy). The native session owns the clock;
+            // foregroundStart is idempotent for a repeated hook or command.
+            if (options.args.debug && sessionId !== undefined) {
+                await (worktree?.service ?? options.service).debugService().foregroundStart(record.task.id, sessionId);
+            }
             const created = taskEnvelope(action, "TASK_CREATED", sessionId === undefined
                 ? `Created task ${record.task.id}.`
                 : record.task.parentTaskId === undefined
@@ -134,6 +144,38 @@ export async function runTaskCommand(options) {
                 }
             };
         }
+        if (action === "debug") {
+            const id = requireTaskId(options.args), service = options.service.debugService();
+            switch (options.args.debugAction) {
+                case "hypothesis":
+                    await service.hypothesis(id, await jsonFile(options.args.payloadFile));
+                    break;
+                case "strategy":
+                    await service.strategy(id, await jsonFile(options.args.payloadFile));
+                    break;
+                case "investigate":
+                    await service.investigate(id, options.args.commandId, options.trusted === true);
+                    break;
+                case "checkpoint":
+                    if (sessionId === undefined)
+                        throw new AgentOpsError("TASK_SESSION_REQUIRED", "Debug checkpoint requires a session.");
+                    await service.checkpoint(id, sessionId);
+                    break;
+                case "resume":
+                    if (sessionId === undefined)
+                        throw new AgentOpsError("TASK_SESSION_REQUIRED", "Debug resume requires a session.");
+                    await service.resume(id, sessionId);
+                    break;
+                case "extend":
+                    if (sessionId === undefined)
+                        throw new AgentOpsError("TASK_SESSION_REQUIRED", "Debug extension requires a native session.");
+                    await service.extend(id, sessionId, options.args.eventId);
+                    break;
+                case "status": break;
+                default: throw new AgentOpsError("TASK_DEBUG_ACTION_INVALID", "A supported debug operation is required.");
+            }
+            return taskEnvelope(action, "TASK_DEBUG_UPDATED", "Original issue debug state preserved.", await service.root(id));
+        }
         if (action === "revise") {
             const payload = await jsonFile(options.args.criteriaFile);
             if (!Array.isArray(payload))

package/dist/packages/cli/src/debug-intake.js

@@ -0,0 +1,245 @@
+import { join } from "node:path";
+import { TaskService } from "../../../runtime/src/task/service.js";
+import { FileTaskStore } from "../../../runtime/src/task/store.js";
+import { calculateConfigHash } from "../../../runtime/src/config/hash.js";
+import { evaluateGuardrail } from "../../../runtime/src/guardrails/evaluate.js";
+import { isDebugIssue } from "../../../runtime/src/task/debug-intake.js";
+import { ensureSessionWorktree, readWorktreeRecord, sessionWorktreeName } from "../../../runtime/src/parallel/service.js";
+import { listWorktrees, resumeWorktree } from "../../../runtime/src/parallel/manage.js";
+import { collectChangeSurface } from "../../../runtime/src/verify/change-surface.js";
+import { calculateSourceFingerprint } from "../../../runtime/src/verify/source-fingerprint.js";
+import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
+import { loadEffectiveConfig } from "./context.js";
+import { gitRunner, worktreeDependencies } from "./parallel-deps.js";
+const foregroundClockSupported = (host) => host !== "opencode";
+function nativeSessionId(input) {
+    const fromInput = [input.session_id, input.sessionId, input.conversationId, input.thread_id, input.threadId]
+        .find((value) => typeof value === "string" && value.length > 0);
+    return fromInput ?? [process.env.AGENT_OPS_SESSION_ID, process.env.CODEX_THREAD_ID]
+        .find((value) => value !== undefined && value.length > 0);
+}
+/** Start only an already attached DEBUG issue; native hooks never create work. */
+export async function startDebugSession(root, sessionId, host) {
+    if (!foregroundClockSupported(host) || sessionId.length === 0)
+        return;
+    const config = (await loadEffectiveConfig(root, "project")).config;
+    const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(sessionId)));
+    const contextRoot = saved?.mainRoot === root && saved.sessionId === sessionId ? saved.path : root;
+    const contextConfig = contextRoot === root ? config : (await loadEffectiveConfig(contextRoot, "project")).config;
+    const tasks = new TaskService(new FileTaskStore(join(contextRoot, ".agent-ops/tasks/state.json"), contextRoot), { completion: { root: contextRoot, gitRunner: gitRunner(contextRoot), loadConfig: async () => contextConfig } });
+    const attached = await tasks.status({ sessionId }).catch(() => null);
+    if (attached?.status === "active" && attached.task.debug !== undefined)
+        await tasks.debugService().foregroundStart(attached.task.id, sessionId);
+}
+export async function routeDebugPrompt(root, input, host = "claude") {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return null;
+    const fields = input;
+    if (typeof fields.prompt !== "string")
+        return null;
+    const continuation = /^(?:繼續|继续|continue)[。.!！]?$/iu.test(fields.prompt.trim());
+    const debugIssue = isDebugIssue(fields.prompt);
+    const config = (await loadEffectiveConfig(root, "project")).config;
+    if (config.features.debug?.enabled !== true)
+        return null;
+    if (evaluateGuardrail({ kind: "content", content: fields.prompt, scope: root }).action === "block")
+        return null;
+    const session = nativeSessionId(fields);
+    if (session === undefined) {
+        if (!debugIssue && !continuation)
+            return null;
+        return "DEBUG intake unsupported: this hook has no reliable native session identity. Use task create --debug --goal with the original issue in the native conversation.";
+    }
+    const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(session)));
+    const contextRoot = saved?.mainRoot === root && saved.sessionId === session ? saved.path : root;
+    const contextConfig = contextRoot === root ? config : (await loadEffectiveConfig(contextRoot, "project")).config;
+    const original = new TaskService(new FileTaskStore(join(contextRoot, ".agent-ops/tasks/state.json"), contextRoot), { completion: { root: contextRoot, gitRunner: gitRunner(contextRoot), loadConfig: async () => contextConfig } });
+    const attached = await original.status({ sessionId: session }).catch(() => null);
+    if (attached?.status === "active" && attached.task.debug !== undefined) {
+        await original.debugService().syncNativeControl(attached.task.id, session);
+        const control = (await original.debugService().root(attached.task.id)).debug.control;
+        if (control?.paused === true)
+            return `DEBUG original issue ${attached.task.id} is paused by the human. Preserve its task, evidence and remaining budget; stop after saving progress. Only a native human continue event resumes it.`;
+        if (continuation) {
+            let message = `DEBUG continue preserved original issue ${attached.task.id}: native user event did not extend time; other limits remain authoritative.`;
+            try {
+                await original.debugService().extend(attached.task.id, session, "latest");
+                message = `DEBUG original issue ${attached.task.id}: native human time grant applied once; other limits remain authoritative.`;
+            }
+            catch (error) {
+                message = `DEBUG continue preserved original issue ${attached.task.id}: ${error instanceof Error ? error.message : "Native user approval unavailable"}`;
+            }
+            if (foregroundClockSupported(host)) {
+                try {
+                    await original.debugService().foregroundStart(attached.task.id, session);
+                }
+                catch (error) {
+                    message += ` Foreground clock unavailable: ${error instanceof Error ? error.message : "host lifecycle is unsupported"}`;
+                }
+            }
+            else
+                message += " Foreground clock unsupported on this host; preserve the issue and use a host with a trustworthy end-of-turn signal.";
+            if (control?.mode === "diagnose")
+                message += " Diagnosis-only scope remains active; continue discriminating evidence without product repairs until a proven diagnosis or runtime blocker. Only a native human resume repair event restores the full loop.";
+            return message;
+        }
+        if (foregroundClockSupported(host)) {
+            try {
+                await original.debugService().foregroundStart(attached.task.id, session);
+            }
+            catch (error) {
+                return `DEBUG original issue ${attached.task.id}: foreground clock unavailable: ${error instanceof Error ? error.message : "host lifecycle is unsupported"}`;
+            }
+        }
+        if (control?.mode === "diagnose")
+            return `DEBUG original issue ${attached.task.id}: diagnosis only. Continue reproduction and hypothesis evidence until a supported diagnosis or a runtime blocker. Do not repair product behavior. A failure to reproduce is not a stop condition; a human resume repair event restores the full loop.`;
+        if (!debugIssue)
+            return null;
+        return `Continue original DEBUG issue ${attached.task.id}; retain its existing budget, evidence and hypotheses.`;
+    }
+    if (!debugIssue && !continuation)
+        return null;
+    if (continuation) {
+        if (attached?.status !== "active" || attached.task.debug === undefined)
+            return null;
+        try {
+            await original.debugService().extend(attached.task.id, session, "latest");
+            return `DEBUG original issue ${attached.task.id}: native human time grant applied once; other limits remain authoritative.`;
+        }
+        catch (error) {
+            return `DEBUG continue preserved original issue ${attached.task.id}: ${error instanceof Error ? error.message : "Native user approval unavailable"}`;
+        }
+    }
+    if (attached?.status === "active")
+        return attached.task.debug === undefined ? null : `Continue original DEBUG issue ${attached.task.id}; retain its existing budget, evidence and hypotheses.`;
+    // Another session's worktree may already hold this issue; reusing it keeps
+    // its consumed budget and rounds instead of starting a fresh task.
+    const holders = await listWorktrees(worktreeDependencies(), root).catch(() => []);
+    for (const { record: held } of holders) {
+        if (held.sessionId === session)
+            continue;
+        const heldConfig = (await loadEffectiveConfig(held.path, "project").catch(() => null))?.config;
+        if (heldConfig === undefined)
+            continue;
+        const issue = await new TaskService(new FileTaskStore(join(held.path, ".agent-ops/tasks/state.json"), held.path), { completion: { root: held.path, gitRunner: gitRunner(held.path), loadConfig: async () => heldConfig } }).activeDebugRoot(fields.prompt).catch(() => null);
+        if (issue === null)
+            continue;
+        try {
+            await resumeWorktree(worktreeDependencies(), { cwd: root, name: held.name, sessionId: session });
+        }
+        catch (error) {
+            return `DEBUG original issue ${issue.task.id} is still active in ${held.path}; a new task would reset its budget. ${error instanceof Error ? error.message : "Resume needs confirmation."} After the user confirms, run agent-ops worktree resume ${held.name} --session ${session}.`;
+        }
+        return `Continue original DEBUG issue ${issue.task.id} in ${held.path}; its budget, rounds and evidence are preserved.`;
+    }
+    await original.assertDebugBaseline();
+    const record = config.worktree?.mode === "auto" && await readWorktreeRecord(root) === null ?
+        await ensureSessionWorktree(worktreeDependencies(), { cwd: root, sessionId: session }) : null;
+    const path = record?.path ?? root;
+    const effective = (await loadEffectiveConfig(path, "project")).config;
+    const tasks = new TaskService(new FileTaskStore(join(path, ".agent-ops/tasks/state.json"), path), { completion: { root: path, gitRunner: gitRunner(path), loadConfig: async () => effective } });
+    const existing = await tasks.status({ sessionId: session }).catch(() => null);
+    if (existing?.status === "active")
+        return existing.task.debug === undefined ? null : `Continue original DEBUG issue ${existing.task.id}.`;
+    const held = await tasks.activeDebugRoot(fields.prompt);
+    if (held !== null) {
+        await tasks.attach(session, held.task.id);
+        let message = `Continue original DEBUG issue ${held.task.id}; its budget, rounds and evidence are preserved.`;
+        if (foregroundClockSupported(host)) {
+            try {
+                await tasks.debugService().foregroundStart(held.task.id, session);
+            }
+            catch (error) {
+                message += ` Foreground clock unavailable: ${error instanceof Error ? error.message : "host lifecycle is unsupported"}`;
+            }
+        }
+        return message;
+    }
+    const ids = effective.verification.commands.filter(c => c.required).map(c => c.id);
+    const baseline = (await gitRunner(path).run(["rev-parse", "--verify", "HEAD"])).stdout.toString().trim();
+    const criteria = ["issue-regression", "related-checks"].map(id => ({ id, description: id === "issue-regression" ? "Reproduce and fix the original reported issue with relevant regression evidence." : "Pass necessary related checks and two fresh independent reviews.", verifierIds: ids,
+        acceptance: { mode: "review-only", baselineCommit: baseline, bindings: [], reviewOnlyReason: "Provisional investigation intake only. Identify and revise to executable original-issue regression before debug success; this criterion cannot prove reproduction." } }));
+    const created = await tasks.create({ title: fields.prompt.split("\n")[0].slice(0, 160), goal: fields.prompt, intent: "Investigate and fix the original issue through authoritative task debug evidence.", debug: { facts: ["User-reported symptom is unverified."], unknowns: ["Baseline reproduction", "Root cause", "Relevant regression and related checks"] }, criteria, sessionId: session, policyConfigHash: calculateConfigHash(effective) });
+    let clockNote = "";
+    if (foregroundClockSupported(host)) {
+        try {
+            await tasks.debugService().foregroundStart(created.task.id, session);
+        }
+        catch (error) {
+            return `DEBUG issue ${created.task.id} created in ${path}, but its foreground clock is unavailable: ${error instanceof Error ? error.message : "host lifecycle is unsupported"}. Preserve the issue and do not claim timed completion.`;
+        }
+    }
+    else
+        clockNote = " Native foreground timing is unsupported on this host; controlled operations remain evidence-timed and do not claim a complete active-time budget.";
+    return `DEBUG issue ${created.task.id} created in ${path}. Preserve the original goal. Investigate, record falsifiable hypotheses, revise provisional criteria to relevant behavioral regression, repair, verify, obtain two fresh independent reviews, then finish. A clean HEAD baseline is fixed automatically; do not ask permission for it or offer diagnosis-only as a fallback. Failure to reproduce alone is not a stop condition: continue discriminating checks within the budget. Defaults: 60 active minutes / 5 material repair candidates. No user-authored debug plan is required.${clockNote}`;
+}
+export async function interruptDebugSession(root, sessionId, nativeInput) {
+    const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(sessionId)));
+    const path = saved?.mainRoot === root && saved.sessionId === sessionId ? saved.path : root;
+    const tasks = new TaskService(new FileTaskStore(join(path, ".agent-ops/tasks/state.json"), path), { completion: { root: path, gitRunner: gitRunner(path), loadConfig: async () => (await loadEffectiveConfig(path, "project")).config } });
+    const attached = await tasks.status({ sessionId }).catch(error => {
+        if (error instanceof AgentOpsError && error.code === "TASK_SESSION_UNATTACHED")
+            return null;
+        throw error;
+    });
+    if (attached?.status === "active" && attached.task.debug !== undefined)
+        await tasks.debugService().interrupt(attached.task.id, sessionId, nativeInput);
+}
+/** Close only the task attached to a native host's verified session. */
+export async function closeDebugSession(root, sessionId, host = "claude") {
+    if (!foregroundClockSupported(host))
+        return;
+    if (sessionId.length === 0)
+        return;
+    const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(sessionId)));
+    const contextRoot = saved?.mainRoot === root && saved.sessionId === sessionId ? saved.path : root;
+    const tasks = new TaskService(new FileTaskStore(join(contextRoot, ".agent-ops/tasks/state.json"), contextRoot), { completion: { root: contextRoot, gitRunner: gitRunner(contextRoot), loadConfig: async () => (await loadEffectiveConfig(contextRoot, "project")).config } });
+    const attached = await tasks.status({ sessionId }).catch(() => null);
+    if (attached?.status === "active" && attached.task.debug !== undefined)
+        await tasks.debugService().foregroundStop(attached.task.id, sessionId);
+}
+/**
+ * Without the completion gate, an active DEBUG issue still cannot end a turn
+ * unless a current runtime stop checkpoint exists. Sessions without one pass.
+ */
+export function debugStopGate(root, rootConfig) {
+    return { handle: async (event) => {
+            if (event.event !== "stop" || event.sessionId === undefined || event.sessionId.length === 0 ||
+                event.terminationReason !== "model_stop" || event.fullyIdle !== true)
+                return null;
+            const sessionId = event.sessionId;
+            const evaluate = async (attempt) => {
+                const saved = await readWorktreeRecord(join(root, ".worktrees", sessionWorktreeName(sessionId))).catch(() => null);
+                const contextRoot = saved?.mainRoot === root && saved.sessionId === sessionId ? saved.path : root;
+                const config = contextRoot === root && attempt === 0 ? rootConfig : (await loadEffectiveConfig(contextRoot, "project")).config;
+                const runner = gitRunner(contextRoot);
+                const tasks = new TaskService(new FileTaskStore(join(contextRoot, ".agent-ops/tasks/state.json"), contextRoot), { completion: { root: contextRoot, gitRunner: runner, loadConfig: async () => config } });
+                const attached = await tasks.status({ sessionId }).catch(error => {
+                    if (error instanceof AgentOpsError && error.code === "TASK_SESSION_UNATTACHED")
+                        return null;
+                    throw error;
+                });
+                if (attached?.status !== "active" || attached.task.debug === undefined)
+                    return null;
+                await tasks.debugService().prepareStop(attached.task.id, sessionId);
+                const surface = await collectChangeSurface(runner);
+                const fingerprint = await calculateSourceFingerprint(contextRoot, { mode: "worktree", changedFiles: surface.paths }, runner);
+                return await tasks.debugService().validCheckpoint(attached.task.id, sessionId, fingerprint)
+                    ? { action: "continue", status: "UNKNOWN", code: "COMPLETION_GATE_TASK_DEBUG_STOPPED", remedy: "Original issue remains active with a runtime-bound non-success checkpoint." }
+                    : { action: "block", status: "FAIL", code: "COMPLETION_GATE_TASK_DEBUG_ACTIVE", remedy: "Continue the original DEBUG investigation, repair, verification and review loop. Failure to reproduce and an arbitrary checkpoint do not permit stopping. Preserve the task and budgets; record a current runtime stop checkpoint only for a proven blocker or exhausted limits." };
+            };
+            // Reload the task/config once for a transient gate fault; never rewrite bad evidence.
+            for (let attempt = 0; attempt < 2; attempt++) {
+                try {
+                    return await evaluate(attempt);
+                }
+                catch (error) {
+                    if (attempt === 0)
+                        continue;
+                    const code = error instanceof AgentOpsError ? error.code : "IO_ERROR";
+                    return { action: "continue", status: "UNKNOWN", code: "TASK_DEBUG_GATE_UNAVAILABLE", remedy: `DEBUG remains incomplete: gate ${code} failed after one targeted reload. Preserve the original task, evidence and budgets; run agent-ops doctor and restore readable task/config evidence before resuming. No completion is attested.` };
+                }
+            }
+            return null;
+        } };
+}