@kylecheng3146/agent-ops 0.10.0 → 0.11.0

package/dist/packages/cli/src/run-entry.js

@@ -8,7 +8,7 @@ import { recordNativeRunAuthorization } from "../../../runtime/src/run/authoriza
 import { observeRunFailure } from "../../../runtime/src/run/verification.js";
 import { criteriaProgress, recordRunPhase } from "../../../runtime/src/run/phase.js";
 import { compareFailureObservations } from "../../../runtime/src/run/convergence.js";
-import { RunControlService } from "../../../runtime/src/run/controls.js";
+import { RunControlService, nativeResumeTime } from "../../../runtime/src/run/controls.js";
 import { beginPolicyTransition, markPolicyTransitionStage, completePolicyTransition, discoverPendingPolicyTransition } from "../../../runtime/src/run/policy-transition.js";
 import { readReviewReportArtifact } from "../../../runtime/src/review/attestation.js";
 import { execFile, spawn } from "node:child_process";
@@ -17,6 +17,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { setTimeout as delay } from "node:timers/promises";
 import { AgentOpsError, resolveContainedPath } from "../../../runtime/src/fs/paths.js";
+import { ensureRunPolicy } from "./context.js";
 import { bindRunPolicy, readRunPolicy, runRuntimeHash, validateRunPolicyChange } from "../../../runtime/src/run/policy.js";
 import { sha256 } from "../../../runtime/src/fs/hash.js";
 import { calculateConfigHash, canonicalJson } from "../../../runtime/src/config/hash.js";
@@ -27,7 +28,7 @@ import { RunSupervisor } from "../../../runtime/src/run/supervisor.js";
 import { NativeRunTransport, nativeProcessIdentity } from "../../../runtime/src/run/transport.js";
 import { workerPlan } from "../../../runtime/src/run/planning.js";
 import { RunScheduler } from "../../../runtime/src/run/scheduler.js";
-import { activeWallTimeMs } from "../../../runtime/src/run/scheduler.js";
+import { activeWallTimeMs, remainingRunTimeMs } from "../../../runtime/src/run/scheduler.js";
 import { readBootIdentity, readGuiLoginIdentity, LaunchdController } from "../../../runtime/src/run/macOS.js";
 import { readPrivateFile, writePrivateFile, withPrivateFileLock } from "../../../runtime/src/security/permissions.js";
 import { TaskService } from "../../../runtime/src/task/service.js";
@@ -42,6 +43,75 @@ const exec = promisify(execFile);
 const plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const active = (worker) => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status);
 const cli = fileURLToPath(new URL("./bin.js", import.meta.url));
+const pendingChildren = (state) => state.tasks.filter(task => task.taskId !== state.rootTaskId && !["delivered", "complete", "blocked"].includes(task.status));
+// Only a coordinator wait stops the coordinator with a handoff reason; it never delivers itself.
+const yielded = (worker) => worker.status === "stopped" && worker.stopIntent?.reason === "handoff";
+/**
+ * Stop a coordinator that asked to wait for its children, instead of letting it
+ * poll run status. Its native thread is dropped so the wake starts fresh.
+ */
+export async function waitForChildren(repository, supervisor, runId, workerId, generation) {
+    const current = await repository.read(runId);
+    if (current === null || workerId !== current.coordinatorId)
+        throw new AgentOpsError("RUN_COORDINATOR_REQUIRED", "Only the coordinator can wait for child deliveries.");
+    if (current.rootTaskId === null || pendingChildren(current).length === 0)
+        throw new AgentOpsError("RUN_WAIT_NOTHING_PENDING", "Wait requires at least one planned child that has not finished.");
+    await yieldCoordinator(repository, supervisor, runId, workerId, generation, current.rootTaskId);
+}
+async function yieldCoordinator(repository, supervisor, runId, workerId, generation, taskId) {
+    await supervisor.stopWorker(runId, workerId, generation, "handoff");
+    await repository.mutate(runId, saved => ({ ...saved, workers: saved.workers.map(w => w.workerId === workerId && w.generation === generation && w.status === "stopped" ? { ...w, nativeSessionId: null, nativeJobId: null } : w) }));
+    await repository.appendEvent(runId, { type: "diagnostic", code: "RUN_COORDINATOR_YIELDED", workerId, taskId,
+        detail: "Coordinator waited; process death confirmed and its slot released until every child finishes." });
+}
+/** Finish an unconfirmed wait, then return the stopped coordinator once every child has finished. */
+export async function prepareSerialSchedule(repository, supervisor, runId) {
+    const current = await repository.read(runId);
+    if (current === null || current.rootTaskId === null || current.status !== "active" || current.disableRestart || current.awaitingResume)
+        return null;
+    const coordinator = current.workers.find(worker => worker.workerId === current.coordinatorId);
+    if (coordinator?.status === "handing-off" && coordinator.stopIntent?.reason === "handoff") {
+        try {
+            await yieldCoordinator(repository, supervisor, runId, coordinator.workerId, coordinator.generation, current.rootTaskId);
+        }
+        catch (cause) {
+            // The slot stays held until death is confirmed; retry on the next supervisor pass.
+            if (cause instanceof AgentOpsError && ["RUN_HANDOFF_PROCESS_ALIVE", "RUN_WRITER_STILL_ALIVE"].includes(cause.code))
+                return null;
+            throw cause;
+        }
+        return null;
+    }
+    if (coordinator === undefined || current.tasks.every(task => task.taskId === current.rootTaskId) || pendingChildren(current).length > 0)
+        return null;
+    return coordinator.status === "stopped" && !current.workers.some(worker => worker.workerId !== coordinator.workerId && active(worker)) ? coordinator : null;
+}
+/** Recovery leaves a waiting coordinator stopped, and with jobs=1 starts only a child whose dependencies are delivered. */
+export function recoverySkips(state, worker) {
+    if (state.rootTaskId === null)
+        return false;
+    const pending = pendingChildren(state);
+    if (pending.length === 0)
+        return false;
+    if (worker.workerId === state.coordinatorId)
+        return yielded(worker);
+    const node = pending.find(task => task.taskId === worker.taskId);
+    return state.jobs === 1 && (node === undefined ||
+        node.dependencies.some(id => !state.tasks.some(task => task.taskId === id && ["delivered", "complete"].includes(task.status))));
+}
+/** Child status handed to a woken coordinator, which may have lost its conversation. */
+export function coordinatorWakeNote(state, coordinator) {
+    const children = state.tasks.filter(task => task.taskId !== state.rootTaskId)
+        .map(task => `${task.taskId} ${task.status}${task.sourceCommit === null ? "" : " " + task.sourceCommit}`);
+    return (coordinator.nativeSessionId === null ? "Fresh native session after wait; the earlier conversation is unavailable. " : "") +
+        `Children: ${children.join("; ")}. Review deliveries, then plan follow-up workers and wait again, or request finalization.`;
+}
+/** Retain the structured child failure instead of hiding it behind recovery text. */
+export function runStepError(result, fallback) {
+    const details = Array.isArray(result.errors) ? result.errors.filter(plain)
+        .map(error => typeof error.message === "string" ? error.message : "").filter(Boolean).join("; ") : "";
+    return new AgentOpsError(typeof result.code === "string" ? result.code : "RUN_INTEGRATION_RECOVERY_REQUIRED", `${fallback}${details.length === 0 ? "" : ": " + details.slice(0, 4096)}`);
+}
 /** Recheck after confirmed death and after verification, before publishing the frozen SHA. */
 export async function assertRunDeliverySnapshot(root, taskId, head, contract, tasks) {
     const runner = gitRunner(root);
@@ -104,6 +174,15 @@ export async function superviseNativeRun(root, runId) {
             await blockStartup("RUN_RESTART_STORM");
             return;
         }
+        let manualResumeAt;
+        await repository.mutate(runId, current => {
+            manualResumeAt = nativeResumeTime(current);
+            if (manualResumeAt === undefined)
+                return current;
+            // Consume the latest control durably; bounded event history is not a one-shot fence.
+            return { ...current, controls: current.controls.map((control, index) => index === current.controls.length - 1
+                    ? { ...control, appliedAt: new Date().toISOString() } : control) };
+        });
         await repository.appendEvent(runId, { type: "status", code: "RUN_SUPERVISOR_START", workerId: null, taskId: null, detail: null });
         let version;
         try {
@@ -165,13 +244,13 @@ export async function superviseNativeRun(root, runId) {
                     "Requests require requestId (unique alphanumeric or hyphen, max 64), workerId, generation and current contractHash.",
                     "Plan fields: action=plan,title,intent,criteria,surface (the EVIDENCE-SURFACE-001 audit object, same shape as task create --surface-file). Worker fields: action=worker,title,intent,criteria,dependencies (known worker task IDs; omit all acceptance baselines until dependencies are delivered),covers (parent included surface IDs this worker delivers; every included surface needs one worker).",
                     "Only the coordinator may change execution policy: submit action=policy, configFile (relative proposed JSON), expectedPolicyHash, approvals (each changed capabilityId command:<id>/runner:<id>/setup:<index>, classification=non-dangerous, reason assessing the entire fixed definition including setup/build). Commit source changes and wait until every writer is clean before requesting policy synchronization. Never use init/update/trust grant to create permanent execution authorization. Explicit native or organization denial must not be bypassed.",
-                    "Worker task baselines are frozen after dependency commits enter its checkout. Handoff fields: action=handoff,sourceFiles (explicit existing source paths when unchanged). Question fields: action=question,prompt. Coordinator finalize fields: action=finalize.",
+                    "Worker task baselines are frozen after dependency commits enter its checkout. Handoff fields: action=handoff,sourceFiles (explicit existing source paths when unchanged). Question fields: action=question,prompt. Coordinator wait fields: action=wait, sent once every worker is planned instead of polling run status; the supervisor stops the coordinator and starts it again, in a fresh session with a child-status diagnostic, after every child is delivered, complete or blocked. Coordinator finalize fields: action=finalize.",
                     "The supervisor, after stopping writers, runs final verification, two fresh reviews and finish. A native completed goal is never final proof."], diagnostic };
             const path = join(worker.worktree, ".agent-ops", "tasks", "run-instructions.json");
             await writePrivateFile(path, JSON.stringify(content, null, 2), worker.worktree);
-            return "Read .agent-ops/tasks/run-instructions.json and carry its immutable original goal through the evidence loop. Submit a plan if rootTaskId is null; otherwise implement and repair the assigned task. A child requests handoff after local green; the coordinator waits for all child deliveries, then requests finalization. Never substitute native goal completion for agent-ops evidence.";
+            return "Read .agent-ops/tasks/run-instructions.json and carry its immutable original goal through the evidence loop. Submit a plan if rootTaskId is null; otherwise implement and repair the assigned task. A child requests handoff after local green; the coordinator submits action=wait after planning its children, then requests finalization once all have delivered. Never substitute native goal completion for agent-ops evidence.";
         }
-        async function start(worker, diagnostic) {
+        async function start(worker, diagnostic, resumeAt) {
             if (await discoverPendingPolicyTransition(repository, runId) !== null)
                 throw new AgentOpsError("RUN_POLICY_TRANSITION_PENDING", "Finish policy synchronization before acquiring a new writer generation.");
             if (worker.worktree === null)
@@ -195,7 +274,7 @@ export async function superviseNativeRun(root, runId) {
                 throw new AgentOpsError("RUN_WORKTREE_OWNERSHIP", "The worker checkout is not registered to this run.");
             await writeWorktreeRecord({ ...record, workerGeneration: worker.generation });
             const goal = await instructions(worker, diagnostic);
-            const running = await supervisor.startWorker(runId, worker.workerId, worker.generation, goal);
+            const running = await supervisor.startWorker(runId, worker.workerId, worker.generation, goal, resumeAt);
             await recordRunPhase(repository, runId, worker.workerId, (await repository.read(runId)).rootTaskId === null ? "planning" : "implementing");
             try {
                 await transport.activateRegistered(runId, running, goal);
@@ -206,14 +285,22 @@ export async function superviseNativeRun(root, runId) {
             }
         }
         async function schedule() {
+            const coordinator = await prepareSerialSchedule(repository, supervisor, runId);
+            if (coordinator !== null) {
+                await start(coordinator, coordinatorWakeNote((await repository.read(runId)), coordinator));
+                return;
+            }
             const current = (await repository.read(runId));
             for (const node of await scheduler.next(runId)) {
                 if (node.planDigest === undefined || node.taskId === current.rootTaskId)
                     continue;
                 const existing = current.workers.find(worker => worker.taskId === node.taskId);
                 if (existing !== undefined && existing.worktree !== null &&
-                    (await deps.tasks(existing.worktree).list()).some(r => r.task.id === node.taskId))
+                    (await deps.tasks(existing.worktree).list()).some(r => r.task.id === node.taskId)) {
+                    if (existing.status === "stopped")
+                        await start(existing);
                     continue;
+                }
                 const planPath = join(directory, runId, "plans", node.taskId + ".json");
                 const source = await readPrivateFile(planPath, commonDir);
                 if (source === null || sha256(source) !== node.planDigest)
@@ -291,12 +378,14 @@ export async function superviseNativeRun(root, runId) {
             if (absent)
                 return (await recoverRunIntegrationAfterCleanup(commonDir, runId, deps.git)).receiptPath;
             const result = await advance(saved);
-            if (result.status !== "ok" || !plain(result.data) || typeof result.data.receipt !== "string")
-                throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Recover the sealed transaction before allowing any writer to resume.");
+            if (result.status !== "ok")
+                throw runStepError(result, "Recover the sealed transaction before allowing any writer to resume");
+            if (!plain(result.data) || typeof result.data.receipt !== "string")
+                throw new AgentOpsError("RUN_INTEGRATION_RECOVERY_REQUIRED", "Recovery did not return the sealed receipt.");
             return result.data.receipt;
         }
         async function step(cwd, args, saved) {
-            const remaining = saved.budget.limitMs - activeWallTimeMs(saved.budget.activeIntervals, Date.now());
+            const remaining = remainingRunTimeMs(saved);
             if (remaining <= 0)
                 throw new AgentOpsError("RUN_BUDGET_EXHAUSTED", "No active time remains for final proof.");
             return await new Promise((resolve, reject) => {
@@ -327,7 +416,7 @@ export async function superviseNativeRun(root, runId) {
                             catch { }
                     }, 3000);
                 };
-                const timeout = setTimeout(terminate, remaining);
+                const timeout = Number.isFinite(remaining) ? setTimeout(terminate, remaining) : undefined;
                 const registration = (async () => {
                     const identity = child.pid === undefined ? null : await nativeProcessIdentity(child.pid);
                     if (identity === null || closed) {
@@ -637,11 +726,15 @@ export async function superviseNativeRun(root, runId) {
                 await synchronizePolicy();
             state = (await repository.read(runId));
             for (const worker of state.workers.filter(w => active(w) || w.status === "stopped")) {
+                if (recoverySkips(state, worker))
+                    continue;
                 if (worker.workerId !== state.coordinatorId && (worker.worktree === null ||
                     !(await deps.tasks(worker.worktree).list()).some(r => r.task.id === worker.taskId)))
                     continue;
                 try {
-                    await start(worker);
+                    await start(worker, worker.workerId === state.coordinatorId && yielded(worker) ? coordinatorWakeNote(state, worker) : undefined, manualResumeAt);
+                    if (state.jobs === 1)
+                        break;
                 }
                 catch (cause) {
                     await repository.appendEvent(runId, { type: "diagnostic", code: cause instanceof AgentOpsError ? cause.code : "RUN_RECOVERY_FAILED",
@@ -677,8 +770,9 @@ export async function superviseNativeRun(root, runId) {
                     await stopAll(state.status === "budget-limited" ? "budget" : "stop");
                     return;
                 }
+                state = await ensureRunPolicy(repository, state);
                 const elapsed = activeWallTimeMs(state.budget.activeIntervals, Date.now());
-                if (elapsed >= state.budget.limitMs) {
+                if (state.budget.limitMs !== null && elapsed >= state.budget.limitMs) {
                     await repository.mutate(runId, current => ({ ...current, status: "budget-limited", disableRestart: true }));
                     await launchd.disableRestart(runDescriptor(state), "active run time budget exhausted");
                     await stopAll("budget");
@@ -688,7 +782,12 @@ export async function superviseNativeRun(root, runId) {
                         accumulatedMs: activeWallTimeMs(current.budget.activeIntervals, Date.now()), lastObservedAt: new Date().toISOString() } }));
                 await schedule();
                 state = (await repository.read(runId));
-                for (const worker of state.workers.filter(w => ["running", "idle"].includes(w.status))) {
+                for (const candidateWorker of state.workers.filter(w => ["running", "idle"].includes(w.status))) {
+                    const freshState = (await repository.read(runId));
+                    const currentWorker = freshState.workers.find(w => w.workerId === candidateWorker.workerId);
+                    if (currentWorker === undefined || !["running", "idle"].includes(currentWorker.status))
+                        continue;
+                    const worker = currentWorker;
                     await supervisor.heartbeat(runId, worker.workerId, worker.generation);
                     const observation = await supervisor.observeWorker(runId, worker.workerId, worker.generation);
                     if (!observation.processAlive) {
@@ -867,6 +966,12 @@ export async function superviseNativeRun(root, runId) {
                                     { questionId: request.requestId, prompt: request.prompt, askedAt: new Date().toISOString(), answeredAt: null, answerDigest: null }] }));
                             response = { requestId: request.requestId, code: "RUN_AWAITING_INPUT" };
                         }
+                        else if (request.action === "wait") {
+                            if ((await collectChangeSurface(gitRunner(worker.worktree))).paths.length > 0)
+                                throw new AgentOpsError("RUN_WAIT_DIRTY", "Commit coordinator changes before waiting; a stopped checkout must be clean to restart.");
+                            await waitForChildren(repository, supervisor, runId, worker.workerId, worker.generation);
+                            response = { requestId: request.requestId, code: "RUN_COORDINATOR_WAITING" };
+                        }
                         else if (request.action === "finalize") {
                             if (worker.workerId !== current.coordinatorId || current.tasks.some(task => task.taskId !== current.rootTaskId && task.status !== "delivered"))
                                 throw new AgentOpsError("RUN_DELIVERIES_PENDING", "The coordinator must wait for every planned child delivery before final integration.");
@@ -888,7 +993,7 @@ export async function superviseNativeRun(root, runId) {
                             await recordRunPhase(repository, runId, worker.workerId, "verifying");
                             const result = await advance(current);
                             if (result.status !== "ok")
-                                throw new AgentOpsError(result.code, "Final proof failed; inspect saved verifier and fresh review reports before repair.");
+                                throw runStepError(result, "Final proof failed; inspect saved verifier and fresh review reports before repair");
                             const data = result.data;
                             if (!plain(data) || typeof data.receipt !== "string")
                                 throw new AgentOpsError("RUN_RECEIPT_REQUIRED", "Finalization requires the receipt returned by the existing finish gate.");
@@ -904,9 +1009,8 @@ export async function superviseNativeRun(root, runId) {
                         const stopped = latest.workers.find(w => w.workerId === worker.workerId);
                         if (request.action === "finalize" && latest.integration !== null && (latest.integration.status !== "prepared" ||
                             (await deps.git(root, ["rev-parse", latest.targetBranch + "^{commit}"])).stdout.trim() === latest.integration.candidate)) {
-                            const recovered = await recoverIntegration(latest);
-                            await acceptReceipt(latest, recovered);
-                            response = { requestId: request.requestId, code: "RUN_COMPLETE", receipt: recovered };
+                            // Preserve the failed step; a manual resume reconciles the sealed transaction after remediation.
+                            throw cause;
                         }
                         else if (request.action === "policy" && await discoverPendingPolicyTransition(repository, runId) !== null) {
                             await repository.appendEvent(runId, { type: "diagnostic", code: "RUN_POLICY_RECOVERY_REQUIRED", workerId: worker.workerId, taskId: worker.taskId,
@@ -936,7 +1040,7 @@ export async function superviseNativeRun(root, runId) {
         }
         catch (cause) {
             await repository.appendEvent(runId, { type: "diagnostic", code: cause instanceof AgentOpsError ? cause.code : "RUN_SUPERVISOR_FAILED",
-                workerId: null, taskId: null, detail: "Supervisor stopped; worktree and proof artifacts are preserved." });
+                workerId: null, taskId: null, detail: cause instanceof AgentOpsError ? cause.message : "Supervisor stopped; worktree and proof artifacts are preserved." });
             try {
                 await stopAll("crash");
             }

package/dist/packages/cli/src/run-setup-entry.js

@@ -1,6 +1,6 @@
 import { FileRunRepository } from "../../../runtime/src/run/service.js";
 import { readRunPolicy, runRuntimeHash } from "../../../runtime/src/run/policy.js";
-import { activeWallTimeMs } from "../../../runtime/src/run/scheduler.js";
+import { remainingRunTimeMs } from "../../../runtime/src/run/scheduler.js";
 import { runVerificationCommand, NodeVerificationProcessRunner } from "../../../runtime/src/verify/spawn.js";
 import { redactSecrets } from "../../../runtime/src/security/redact.js";
 import { join } from "node:path";
@@ -21,7 +21,7 @@ const policy = await readRunPolicy(state, await runRuntimeHash());
 const step = /^(?:0|[1-9][0-9]*)$/u.test(index) ? policy?.config.worktree?.setup?.[Number(index)] : undefined;
 if (step === undefined)
     throw new Error("Setup must select an authorized fixed policy command.");
-const remaining = state.budget.limitMs - activeWallTimeMs(state.budget.activeIntervals, Date.now());
+const remaining = remainingRunTimeMs(state);
 if (remaining <= 0)
     throw new Error("Run budget is exhausted.");
 const result = await runVerificationCommand({ id: "run-setup", ...step, cwd: ".", required: true,

package/dist/runtime/src/adapters/agy/config.js

@@ -54,7 +54,7 @@ export function buildAgyHookSettings(capabilities, runtimePath, platform = proce
         throw new AgentOpsError("AGY_HOOK_PATH_INVALID", "agy hook runtime path is invalid.");
     }
     const hooks = {};
-    if ((capabilities.includes("lifecycle-summary") || capabilities.includes("office-presence") || capabilities.includes("task-debug")) || capabilities.includes("project-loop")) {
+    if ((capabilities.includes("lifecycle-summary") || capabilities.includes("office-presence")) || capabilities.includes("project-loop")) {
         hooks.PreInvocation = [handler(runtimePath, "SessionStart", platform)];
     }
     if ((capabilities.includes("command-policy") || capabilities.includes("office-presence")) || capabilities.includes("project-loop")) {
@@ -62,8 +62,7 @@ export function buildAgyHookSettings(capabilities, runtimePath, platform = proce
     }
     if (capabilities.includes("office-presence") ||
         capabilities.includes("optional-stop-verify") ||
-        capabilities.includes("completion-gate") ||
-        capabilities.includes("task-debug")) {
+        capabilities.includes("completion-gate")) {
         hooks.Stop = [handler(runtimePath, "Stop", platform, capabilities.includes("completion-gate"))];
     }
     return { hooks };

package/dist/runtime/src/adapters/claude/config.js

@@ -115,7 +115,7 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
         }
         // The loop has its own prompt hook. Outside it, a prompt is both the
         // turn's start for Office and content for command policy.
-        if (capabilities.includes("command-policy") || capabilities.includes("office-presence") || capabilities.includes("task-debug")) {
+        if (capabilities.includes("command-policy") || capabilities.includes("office-presence")) {
             hooks.UserPromptSubmit = [matcherGroup("UserPromptSubmit", runtimePath)];
             if (capabilities.includes("command-policy") || capabilities.includes("office-presence"))
                 hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
@@ -126,7 +126,7 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
     if (capabilities.includes("completion-gate")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath, true)];
     }
-    else if (capabilities.includes("task-debug") || capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
+    else if (capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath)];
     }
     // Stop only ends a turn. SessionEnd is the one signal that the conversation

package/dist/runtime/src/adapters/codex/config.js

@@ -84,18 +84,15 @@ export function buildCodexHookConfig(capabilities, runtimePath) {
         }
         // The loop has its own prompt hook. Outside it, a prompt is both the
         // turn's start for Office and content for command policy.
-        if (capabilities.includes("command-policy") || capabilities.includes("office-presence") || capabilities.includes("task-debug")) {
+        if (capabilities.includes("command-policy") || capabilities.includes("office-presence")) {
             hooks.UserPromptSubmit = [matcherGroup("UserPromptSubmit", runtimePath)];
             if (capabilities.includes("command-policy") || capabilities.includes("office-presence"))
                 hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
         }
     }
-    if (capabilities.includes("task-debug") || capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
+    if (capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath)];
     }
-    if (capabilities.includes("task-debug")) {
-        hooks.Interrupt = [{ hooks: [{ ...commandHook("Interrupt", runtimePath), timeout: 3 }] }];
-    }
     if (capabilities.includes("office-presence") && hooks.PreToolUse !== undefined) {
         hooks.PreToolUse = hooks.PreToolUse.map(group => ({ ...group, matcher: "^(Bash|apply_patch)$" }));
     }

package/dist/runtime/src/hooks/completion-gate.js

@@ -260,9 +260,6 @@ export class CompletionGateService {
         }
     }
     async grantPermit(sessionId) {
-        const attached = await this.#options.taskService.status({ sessionId }).catch(() => null);
-        if (attached?.task.debug !== undefined && attached.status === "active")
-            throw new AgentOpsError("TASK_DEBUG_CHECKPOINT_REQUIRED", "Active debug issues require a runtime stop checkpoint; allow-stop does not grant budget or success.");
         const fingerprint = await this.#fingerprint();
         const granted = await this.#store.mutate(sessionId, (state) => {
             if (state === null) {
@@ -488,18 +485,6 @@ export class CompletionGateService {
             }
             return last;
         }
-        const debugTask = await this.#options.taskService.status({ sessionId }).catch(() => null);
-        if (debugTask?.task.debug !== undefined) {
-            if (debugTask.status === "active") {
-                await this.#options.taskService.debugService().prepareStop(debugTask.task.id, sessionId);
-                const valid = await this.#options.taskService.debugService().validCheckpoint(debugTask.task.id, sessionId, fingerprint);
-                return valid ? gateResult("continue", "UNKNOWN", "COMPLETION_GATE_TASK_DEBUG_STOPPED", "Original issue remains active with a runtime-bound non-success checkpoint.") :
-                    gateResult("block", "FAIL", "COMPLETION_GATE_TASK_DEBUG_ACTIVE", "Continue the investigation/evidence loop or record a current runtime stop checkpoint, even when Git has no net diff.");
-            }
-            const failure = await this.#validateTask(sessionId);
-            if (failure !== null)
-                return failure;
-        }
         if (changed) {
             const failure = await this.#validateTask(sessionId);
             if (failure !== null)

package/dist/runtime/src/install/harness.js

@@ -340,8 +340,11 @@ function autoRunInstruction(descriptor, context) {
         "`WORKTREE_NESTED`, say so in one line naming the code and fall back to",
         "the subtask flow (`task create --parent`, then batch or advance).",
         "`RUN_REPO_UNTRUSTED` means stop and ask the user; never work",
-        "around trust. If the run ends without completing (blocked, budget",
-        "exhausted, stopped, failing review), report the `agent-ops run status",
+        "around trust. New runs have no total time cap; legacy finite runs upgrade",
+        "only on manual resume, preserving accounting and independent blockers.",
+        "Command/review timeouts and provider limits remain effective.",
+        "If the run ends without completing (blocked, stopped, failing review),",
+        "report the `agent-ops run status",
         "<id>` state and code, the last `agent-ops run logs <id>` events, and the",
         "exact `agent-ops run resume <id>` and `agent-ops run stop <id>` commands,",
         "then stop: never resume automatically or take over the run's work.",
@@ -361,8 +364,8 @@ export function managedRules(descriptor, context) {
             : [`Toolkit version: ${context.toolkitVersion}`]),
         ""
     ];
-    if (context.capabilities.includes("task-debug"))
-        lines.push("Task DEBUG routing is enabled for investigation/bugfix issues. Native prompt hooks create the issue task when a session identity is available; otherwise use agent-ops task create --debug --goal <verbatim issue> with two to five issue-specific criteria. Explain/read-only, feature and refactor requests use the existing normal task flow.", "For DEBUG: understand the issue, investigate with task debug --debug-action investigate --command-id <trusted verifier>, record falsifiable hypotheses with --debug-action hypothesis --payload-file <json>, reproduce, fix, then once a hypothesis is confirmed declare the origin with --debug-action origin --payload-file <json> (escape-of <commit> with the earliest-gate label, or pre-existing/external with a reason; finish refuses ESCAPE_ORIGIN_MISSING without it; a surface label also needs a tracked .agent-ops-escapes/rules/<id>.json rule that replays at the escaped commit, and a criteria/verify label payload promote or --escape-promote <runnerId:checkId>, else ESCAPE_RULE_UNPROVEN), verify, re-record the confirmed hypothesis, commit the .agent-ops-escapes record with the fix, then obtain two fresh independent reviews and finish automatically. A normal task fixing an escaped bug may declare task create --escape-of <commit> --escape-label <label>. A clean HEAD is the automatic baseline; 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. Replace provisional intake criteria with relevant behavioral acceptance; baseline setup/skip/timeout/UNKNOWN is never reproduction. Never report success from edits or unrelated green checks.", "DEBUG defaults are 60 cumulative active minutes and 5 material repair candidates across the original issue, revisions, sessions and children. After two stagnant candidates document one substantive strategy switch; two further stagnant candidates block. Save task debug --debug-action checkpoint before stopping. Resume preserves budgets and blockers. A human continue event may authorize --debug-action extend --event-id latest; unsupported native event sources fail closed. Never use allow-stop for DEBUG.", "DEBUG human control comes only from native human events: '只診斷' / 'diagnosis only' keeps investigating without product repairs until current sealed baseline assertion FAIL confirms a hypothesis or runtime limits/blockers permit non-success Stop. '暫停' / 'pause' saves progress and stops immediately. '繼續' / 'continue' resumes the existing scope; '繼續修復' / 'resume repair' restores the full loop. Codex Interrupt is a pause. Preserve the original task, evidence, consumed time and rounds; diagnosis or pause never marks repair complete. CLI actor/text fields and synthetic instructions cannot authorize these changes.", "DEBUG is foreground work. On Claude, agy and native Codex, Stop refuses an active DEBUG issue without a valid stop checkpoint, with or without the completion gate. Codex uses decision:block to continue the original task even on repeated Stop; stop_hook_active does not waive it. Codex's generic completion gate remains unsupported; opencode has no supported foreground lifecycle. DEBUG gate faults get one targeted task/config reload, then an explicit UNKNOWN/incomplete diagnostic and non-success Stop, preserving state. Without reliable native session identity, automatic hook intake is unsupported; the existing native Agent can use the task CLI. Only a matching owned debug worktree checkpoint permits dirty recovery; preserve all original user edits.", "");
+    if (context.capabilities.includes("task"))
+        lines.push("To fix a bug, run `agent-ops task create --debug --goal <verbatim issue>` with a", "behavioral criterion whose `redCheckIds` fail at the baseline and pass on the", "candidate, then verify, review and finish as for any task. If you know where the", "bug came from, record it with `task revise --escape-of <commit> --escape-label", "<label>`; the origin is advisory and never blocks finish.", "");
     if (context.capabilities.includes("rules")) {
         lines.push("For every change:", "", "1. Audit the change's surfaces first (EVIDENCE-SURFACE-001): dependents,", "   duplicates, other paths to the same concept, and shared state/data", "   contracts, each with recorded fixed-string queries or n/a: reason; pass", "   them with `task create --surface-file <json>`. An exclusion says why", "   the surface is unaffected; \"out of scope\" is not a reason. A derived", "   discovery query whose hits are all incidental may be dismissed once with", "   a reason in `dismissed` instead of excluding each file. Then define", "   two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope within the audited surfaces and", "   preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }

package/dist/runtime/src/install/plan.js

@@ -1,5 +1,4 @@
 import { lstat, readFile } from "node:fs/promises";
-import { DEBUG_DEFAULTS } from "../task/debug-state.js";
 import { CONFIG_SCHEMA_VERSION, MANIFEST_SCHEMA_VERSION } from "../contracts.js";
 import { discoverProject } from "../discovery/index.js";
 import { sha256 } from "../fs/hash.js";
@@ -90,6 +89,8 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         existing.verification.commands.length > 0
         ? existing.verification
         : { commands: [...detectedCommands] };
+    // Pre-0.11 DEBUG budget settings are dropped on rewrite.
+    const existingFeatures = existing === undefined ? undefined : (({ debug: _legacyDebug, ...rest }) => rest)(existing.features);
     const effectiveWorktree = worktree !== undefined
         ? (worktree === null ? undefined : structuredClone(worktree))
         : (existing?.worktree === undefined ? undefined : structuredClone(existing.worktree));
@@ -98,8 +99,7 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         profiles: [...profiles],
         verification,
         features: {
-            debug: existing?.features.debug ?? { ...DEBUG_DEFAULTS },
-            ...(existing?.features ?? {
+            ...(existingFeatures ?? {
                 stopVerification: { enabled: false },
                 completionGate: { enabled: completionGateEnabled }
             }),

package/dist/runtime/src/install/profiles.js

@@ -34,8 +34,6 @@ export function resolveProfiles(inputProfiles) {
 }
 export function resolveCapabilities(config) {
     const resolved = resolveProfiles(config.profiles);
-    if (config.features.debug?.enabled === true)
-        resolved.capabilities.push("task-debug");
     if (config.features.office?.enabled === true)
         resolved.capabilities.push("office-presence");
     if (config.features.stopVerification.enabled) {

package/dist/runtime/src/office/scene.js

@@ -122,7 +122,7 @@ export function sceneModel(snapshot) {
         return { key, sourceIndex: index, kind: "run", title: titled(repo, run.title), top: 0, props, actors, phaseAreas: makeAreas(), questions, criteria,
             activities: activitiesOf(optional(run).activities),
             board: boardFor(rootProgress, run.status, taskId, questions.length), papers, books: { lit: rootProgress?.passed ?? 0, total: rootProgress?.total ?? 0 },
-            clock: run.budget.limitMs > 0 ? run.budget.remainingMs / run.budget.limitMs : 0, phase: run.phase, status: run.status,
+            clock: run.budget.limitMs !== null && run.budget.remainingMs !== null && run.budget.limitMs > 0 ? run.budget.remainingMs / run.budget.limitMs : 1, phase: run.phase, status: run.status,
             completedAt, repo, overview: { x: 0, y: 0, width: 0, height: 0 } };
     };
     const activitiesOf = (value) => (Array.isArray(value) ? value : []).map(raw => {

package/dist/runtime/src/office/server.js

@@ -25,7 +25,7 @@ function send(res, status, type, body, headers = {}) {
 }
 /** Loopback-only, token-gated, GET-only view of the building. */
 export function createOfficeServer(options) {
-    const token = options.token ?? randomBytes(24).toString("base64url");
+    let token = options.token ?? randomBytes(24).toString("base64url");
     const now = options.now ?? Date.now;
     const idleMs = options.idleMs ?? OFFICE_IDLE_MS;
     let lastActive = now();
@@ -40,6 +40,8 @@ export function createOfficeServer(options) {
         const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
         if (!same(url.searchParams.get("token") ?? "", token))
             return send(res, 403, "text/plain", "Forbidden\n");
+        if (url.pathname === "/health")
+            return send(res, 200, "text/plain", "ok\n");
         if (url.pathname === "/") {
             const nonce = randomBytes(16).toString("base64");
             return send(res, 200, "text/html; charset=utf-8", officePage(nonce), { "Content-Security-Policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; form-action 'none'` });
@@ -54,16 +56,25 @@ export function createOfficeServer(options) {
         else
             res.end(); });
     });
+    const bind = (candidate) => new Promise((resolve, reject) => {
+        const onError = (error) => { server.removeListener("listening", onListening); reject(error); };
+        const onListening = () => {
+            server.removeListener("error", onError);
+            const address = server.address();
+            port = typeof address === "object" && address !== null ? address.port : 0;
+            resolve(port);
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(candidate, "127.0.0.1");
+    });
     return {
-        server, token,
-        listen: async () => await new Promise((resolve, reject) => {
-            server.once("error", reject);
-            server.listen(0, "127.0.0.1", () => {
-                const address = server.address();
-                port = typeof address === "object" && address !== null ? address.port : 0;
-                resolve(port);
-            });
-        }),
+        server,
+        get token() { return token; },
+        set token(value) { token = value; },
+        listen: async (preferredPort = 0) => preferredPort > 0
+            ? await bind(preferredPort).catch(async () => await bind(0))
+            : await bind(0),
         tick: async () => {
             const snapshot = await options.snapshot().catch(() => null);
             const sessionIsPresent = snapshot?.lobby.some(desk => (desk.sessionActive ?? desk.status === "active") && (desk.completedAt === undefined || desk.completedAt === null)) ?? false;
@@ -86,16 +97,29 @@ function alive(pid) {
         return error.code === "EPERM";
     }
 }
-/** A recorded server counts only if its process lives and it answers with its own token. */
-export async function readLiveOffice(home) {
+export async function readOfficeRecord(home) {
     const source = await readPrivateFile(officeRecordPath(home), home.anchor).catch(() => null);
     if (source === null)
         return null;
     try {
         const record = JSON.parse(source);
-        if (!Number.isSafeInteger(record.pid) || !Number.isSafeInteger(record.port) || typeof record.token !== "string" || !alive(record.pid))
-            return null;
-        const response = await fetch(`http://127.0.0.1:${record.port}/snapshot.json?token=${encodeURIComponent(record.token)}`, { signal: AbortSignal.timeout(2000) });
+        return Number.isSafeInteger(record.pid) && Number.isSafeInteger(record.port) &&
+            record.port > 0 && record.port <= 65535 &&
+            typeof record.token === "string" && record.token.length > 0
+            ? record
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A recorded server counts only if its process lives and it answers with its own token. */
+export async function readLiveOffice(home) {
+    const record = await readOfficeRecord(home);
+    if (record === null || !alive(record.pid))
+        return null;
+    try {
+        const response = await fetch(`http://127.0.0.1:${record.port}/health?token=${encodeURIComponent(record.token)}`, { signal: AbortSignal.timeout(2000) });
         await response.body?.cancel();
         return response.status === 200 ? record : null;
     }
@@ -111,7 +135,10 @@ export async function claimOffice(home, office, pid = process.pid) {
     return await withPrivateFileLock(officeRecordPath(home), home.anchor, async () => {
         if (await readLiveOffice(home) !== null)
             return null;
-        const record = { pid, port: await office.listen(), token: office.token, startedAt: new Date().toISOString() };
+        const previous = await readOfficeRecord(home);
+        if (previous !== null)
+            office.token = previous.token;
+        const record = { pid, port: await office.listen(previous?.port), token: office.token, startedAt: new Date().toISOString() };
         await writePrivateFile(officeRecordPath(home), JSON.stringify(record) + "\n", home.anchor);
         return record;
     });

package/dist/runtime/src/office/snapshot.js

@@ -1,6 +1,9 @@
 import { activeWallTimeMs } from "../run/scheduler.js";
 const COMPLETED_RETENTION_MS = 2 * 60 * 60 * 1000;
 const LIVE = new Set(["assigned", "starting", "running", "idle", "handing-off", "fenced", "delivered", "blocked"]);
+// Every other run status is idle: nothing moves a paused, stopping, blocked or
+// budget-limited run on, so it leaves the Office like a finished one.
+const RUNNING = new Set(["active", "awaiting-input"]);
 const PHASES = new Set(["planning", "implementing", "verifying", "reviewing", "integrating", "unknown"]);
 function phaseOf(value) {
     return value !== undefined && PHASES.has(value) ? value : "unknown";
@@ -23,7 +26,7 @@ function quote(text) {
 export function buildOfficeSnapshot(input) {
     const byPath = new Map(input.worktrees.map(w => [w.path, w]));
     const claimed = new Set();
-    const runs = input.runs.filter(run => !["complete", "failed"].includes(run.status) || input.now - Date.parse(run.updatedAt) < COMPLETED_RETENTION_MS)
+    const runs = input.runs.filter(run => RUNNING.has(run.status) || input.now - Date.parse(run.updatedAt) < COMPLETED_RETENTION_MS)
         .map((run) => {
         const roots = new Set(run.workers.map(w => w.worktree).filter((p) => p !== null));
         const reviewers = input.reviews.filter(r => r.root !== null && roots.has(r.root)).slice(0, 2);
@@ -52,7 +55,7 @@ export function buildOfficeSnapshot(input) {
             ...(rootTaskId === null ? {} : { progress: rootTree?.progress ?? rootTask?.progress ?? null,
                 ...(rootTree?.criteria === undefined ? {} : { criteria: rootTree.criteria }) }),
             status: run.status, phase: run.phase ?? "unknown",
-            budget: { limitMs: run.budget.limitMs, usedMs, remainingMs: Math.max(0, run.budget.limitMs - usedMs) },
+            budget: { limitMs: run.budget.limitMs, usedMs, remainingMs: run.budget.limitMs === null ? null : Math.max(0, run.budget.limitMs - usedMs) },
             questions, agents, reviewers,
             ...(run.status === "complete" || run.status === "failed" ? { completedAt: run.updatedAt } : {}),
             commands: [`agent-ops run status ${run.runId}`, `agent-ops run logs ${run.runId}`,