@kylecheng3146/agent-ops 0.8.0 → 0.8.4

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

@@ -6,6 +6,7 @@ import { validateEvidence, validateTask, validateTaskAgainstConfig } from "../sc
 import { renderTaskMarkdown } from "./render.js";
 import { checkTaskCompletionEvidence, findIncompleteSubtask } from "./completion.js";
 import { calculateConfigHash, FileEvidenceStore, isPassingVerificationEvidence } from "../verify/evidence.js";
+import { collectChangeSurface } from "../verify/change-surface.js";
 import { resolveReviewScope } from "../review/scope.js";
 import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
 import { acceptanceCoverage } from "../verify/acceptance-coverage.js";
@@ -14,6 +15,9 @@ import { findReviewAttestation } from "../review/attestation.js";
 import { advanceFailureFingerprint } from "../verify/fingerprint.js";
 import { taskContractHash, treeContractHash } from "./contract.js";
 import { commitIdentity } from "../schema/acceptance.js";
+import { createDebugState, DEBUG_DEFAULTS } from "./debug-state.js";
+import { DebugService } from "./debug.js";
+import { sameDebugText } from "./debug-intake.js";
 const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
 function defaultTaskId() {
     return `task-${randomUUID()}`;
@@ -84,6 +88,15 @@ export class TaskService {
         this.#now = options.now ?? (() => new Date().toISOString());
         this.#completion = options.completion;
     }
+    debugService() {
+        if (this.#completion === undefined)
+            throw taskError("TASK_DEBUG_CONTEXT_REQUIRED", "Debug operations require repository context.");
+        return new DebugService({ store: this.#store, tasks: this, ...this.#completion });
+    }
+    async assertDebugBaseline() {
+        if (this.#completion === undefined || (await collectChangeSurface(this.#completion.gitRunner)).paths.length > 0)
+            throw taskError("TASK_DEBUG_BASELINE_DIRTY", "Preserve user edits; debug intake needs a clean committed baseline before worktree allocation.");
+    }
     async create(input) {
         if (input.policyConfigHash !== undefined &&
             !/^[a-f0-9]{64}$/u.test(input.policyConfigHash)) {
@@ -92,6 +105,12 @@ export class TaskService {
         if (input.sessionId !== undefined) {
             assertSessionId(input.sessionId);
         }
+        // A new session must not restart an active issue's budget and rounds.
+        if (input.debug !== undefined && input.parentTaskId === undefined && input.goal !== undefined) {
+            const existing = await this.activeDebugRoot(input.goal);
+            if (existing !== null)
+                return input.sessionId === undefined ? existing : await this.attach(input.sessionId, existing.task.id);
+        }
         let createdSourceCommit = input.createdSourceCommit;
         if (createdSourceCommit === undefined && this.#completion !== undefined) {
             const head = await this.#completion.gitRunner.run(["rev-parse", "--verify", "HEAD"]);
@@ -115,6 +134,18 @@ export class TaskService {
                 ? {}
                 : { parentTaskId: input.parentTaskId })
         };
+        let debugSettings;
+        if (input.debug !== undefined) {
+            if (input.goal === undefined || createdSourceCommit === undefined || this.#completion === undefined)
+                throw taskError("TASK_DEBUG_CONTEXT_REQUIRED", "Debug intake requires the original issue and a committed baseline.");
+            if ((await collectChangeSurface(this.#completion.gitRunner)).paths.length > 0)
+                throw taskError("TASK_DEBUG_BASELINE_DIRTY", "Preserve original user edits; investigate read-only or ask for an explicit committed baseline.");
+            const config = await this.#completion.loadConfig();
+            if (config.features.debug?.enabled === false)
+                throw taskError("TASK_DEBUG_DISABLED", "Task debug routing is explicitly disabled.");
+            debugSettings = config.features.debug ?? DEBUG_DEFAULTS;
+            task.debug = { rootTaskId: task.id, facts: [...(input.debug.facts ?? [])], unknowns: [...(input.debug.unknowns ?? [])] };
+        }
         const validation = validateTask(task);
         if (!validation.ok) {
             throw taskError("TASK_INVALID", validation.errors[0]?.message ?? "Task input is invalid.");
@@ -149,9 +180,15 @@ export class TaskService {
                         throw taskError("TASK_GOAL_IMMUTABLE", "Subtasks must retain their parent original goal.");
                     validation.value.goal = parent.task.goal;
                 }
+                if (parent.task.debug !== undefined) {
+                    if (input.debug !== undefined)
+                        throw taskError("TASK_DEBUG_ROOT_IMMUTABLE", "A child cannot create a new issue budget.");
+                    validation.value.debug = structuredClone(parent.task.debug);
+                }
             }
             const record = {
                 task: validation.value,
+                ...(input.debug === undefined ? {} : { debug: createDebugState(task.id, createdSourceCommit, debugSettings, this.#completion.root) }),
                 ...(createdSourceCommit === undefined ? {} : { createdSourceCommit }),
                 status: "active",
                 evidence: {},
@@ -326,6 +363,8 @@ export class TaskService {
             const task = { schemaVersion: TASK_SCHEMA_VERSION, id: planned.id ?? this.#generateId(),
                 title: planned.title, intent: planned.intent, goal: root.task.goal ?? root.task.intent ?? root.task.title,
                 criteria: structuredClone(planned.criteria), parentTaskId: taskId };
+            if (root.task.debug !== undefined)
+                task.debug = structuredClone(root.task.debug);
             const checked = config === undefined ? validateTask(task) : validateTaskAgainstConfig(task, config);
             if (!checked.ok)
                 throw taskError("TASK_INVALID", checked.errors[0]?.message ?? "Invalid split task.");
@@ -388,6 +427,8 @@ export class TaskService {
                 if (record.policyConfigHash !== parent.policyConfigHash || !validateTask(task).ok) {
                     throw taskError("TASK_DELIVERY_INVALID", `Task ${task.id} has an incompatible policy or definition.`);
                 }
+                if (parent.task.debug !== undefined && (task.goal !== parent.task.goal || JSON.stringify(task.debug) !== JSON.stringify(parent.task.debug) || record.debug !== undefined))
+                    throw taskError("TASK_DEBUG_ROOT_MISMATCH", "A delivery must retain the original issue identity and cannot import an independent debug budget.");
                 const existing = state.tasks.find((item) => item.task.id === task.id);
                 if (existing !== undefined) {
                     if (JSON.stringify(existing.task) !== JSON.stringify(task)) {
@@ -413,6 +454,11 @@ export class TaskService {
             }
         });
     }
+    /** The active DEBUG root already holding this original issue, if any. */
+    async activeDebugRoot(goal) {
+        return (await this.list()).find((record) => record.status === "active" && record.task.debug?.rootTaskId === record.task.id &&
+            record.task.goal !== undefined && sameDebugText(record.task.goal, goal)) ?? null;
+    }
     async list(filter = {}) {
         const state = await this.#store.read();
         return state.tasks

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

@@ -4,6 +4,7 @@ import { AgentOpsError } from "../fs/paths.js";
 import { validateTask } from "../schema/validate.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
 import { taskContractHash } from "./contract.js";
+import { assertDebugState } from "./debug-state.js";
 import { commitIdentity, acceptanceSourcePath } from "../schema/acceptance.js";
 const DEFAULT_MAX_BYTES = 1024 * 1024;
 const SESSION_ID_PATTERN = /^[^\0\r\n]{1,256}$/u;
@@ -68,7 +69,7 @@ function parseTaskRecord(value) {
     ];
     // Every record written before an optional field existed must still parse, so
     // the accepted shapes are every combination of them.
-    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash", "reviewBase", "createdSourceCommit", "revisions", "supersededBy", "noChangePaths"];
+    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash", "reviewBase", "createdSourceCommit", "revisions", "supersededBy", "noChangePaths", "debug"];
     if (!isRecord(value) || !baseKeys.every(k => Object.hasOwn(value, k)) ||
         Object.keys(value).some(k => !baseKeys.includes(k) && !optionalKeys.includes(k))) {
         return invalidState("Task state contains an invalid task record.");
@@ -77,6 +78,11 @@ function parseTaskRecord(value) {
     if (!task.ok) {
         return invalidState("Task state contains an invalid task.");
     }
+    if (value.debug !== undefined) {
+        assertDebugState(value.debug);
+        if (value.debug.rootTaskId !== task.value.id || task.value.debug?.rootTaskId !== task.value.id)
+            return invalidState("Debug counters belong only to the original issue root.");
+    }
     if (!["active", "archived", "complete"].includes(String(value.status)) ||
         !isTimestamp(value.createdAt) ||
         !isTimestamp(value.updatedAt) ||
@@ -182,6 +188,7 @@ function parseTaskRecord(value) {
     }
     return {
         task: task.value,
+        ...(value.debug === undefined ? {} : { debug: value.debug }),
         ...(value.noChangePaths === undefined ? {} : { noChangePaths: value.noChangePaths }),
         ...(value.createdSourceCommit === undefined ? {} : { createdSourceCommit: value.createdSourceCommit }),
         ...(value.revisions === undefined ? {} : { revisions: value.revisions }),

package/dist/runtime/src/verify/acceptance-replay.js

@@ -113,9 +113,14 @@ export async function replayAcceptance(options) {
             const temp = await mkdtemp(join(tmpdir(), "agent-ops-acceptance-"));
             const checkout = join(temp, "repository");
             const env = replayEnvironment(checkout, phase, executionId);
-            const command = async (executable, args, cwd, timeoutMs = 60_000) => await runVerificationCommand({ id: group.runner.id, command: executable, args: [...args], cwd: ".", required: true,
-                evidence: { kind: "exit-code" }, timeoutMs }, { cwd, runner: options.processRunner, env, replaceEnv: true,
-                outputLimitBytes: 1024 * 1024, ...(options.signal === undefined ? {} : { signal: options.signal }) });
+            const command = async (executable, args, cwd, timeoutMs = 60_000) => {
+                const remaining = await options.remainingMs?.();
+                if (remaining === 0)
+                    throw new AgentOpsError("TASK_DEBUG_BUDGET_EXHAUSTED", "The original issue's active budget is exhausted.");
+                return await runVerificationCommand({ id: group.runner.id, command: executable, args: [...args], cwd: ".", required: true,
+                    evidence: { kind: "exit-code" }, timeoutMs: Math.min(timeoutMs, remaining ?? Infinity) }, { cwd, runner: options.processRunner, env, replaceEnv: true,
+                    outputLimitBytes: 1024 * 1024, ...(options.signal === undefined ? {} : { signal: options.signal }) });
+            };
             let aggregate;
             let failure = "replay-unavailable";
             let output;
@@ -200,7 +205,7 @@ export async function replayAcceptance(options) {
                 failure = aggregate?.failureClass ?? output.failureClass;
             }
             catch (error) {
-                failure = error instanceof Error && /^[a-z-]+$/u.test(error.message) ? error.message : "replay-unavailable";
+                failure = error instanceof AgentOpsError && error.code === "TASK_DEBUG_BUDGET_EXHAUSTED" ? "debug-budget-exhausted" : error instanceof Error && /^[a-z-]+$/u.test(error.message) ? error.message : "replay-unavailable";
             }
             finally {
                 await rm(temp, { recursive: true, force: true });

package/dist/runtime/src/verify/change-surface.js

@@ -1,6 +1,7 @@
 import { TextDecoder } from "node:util";
 import { AgentOpsError } from "../fs/paths.js";
 const WINDOWS_RESERVED_SEGMENT = /^(?:aux|com[1-9]|con|lpt[1-9]|nul|prn)(?:\..*)?$/i;
+const HARNESS_PROCESS_HEARTBEAT = /^\.(?:claude|codex)\/\.agent-ops-process-[1-9]\d*-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
 function sortedUnique(values) {
     return [...new Set(values)].sort();
 }
@@ -91,7 +92,9 @@ export async function collectChangeSurface(runner) {
     ])).filter(
     // Indexed runtime was rejected above; only generated, untracked output is excluded.
     (path) => !path.startsWith(".agent-ops/tasks/") &&
-        !path.startsWith(".agent-ops/reviews/"));
+        !path.startsWith(".agent-ops/reviews/") &&
+        // Private marker locks keep these runtime heartbeats until process exit.
+        !HARNESS_PROCESS_HEARTBEAT.test(path));
     return {
         staged,
         unstaged,

package/dist/runtime/src/verify/service.js

@@ -70,7 +70,10 @@ export class VerificationService {
     }
     async #runCommand(task, command) {
         const startedAt = (this.#options.now ?? (() => new Date().toISOString()))();
-        const result = await executeConfiguredCommand(command, {
+        const remaining = task.debug === undefined ? undefined : await this.#options.taskService.debugService().remaining(task.id);
+        if (remaining === 0)
+            throw verificationError("TASK_DEBUG_BUDGET_EXHAUSTED", "The original issue's active budget is exhausted.");
+        const result = await executeConfiguredCommand(remaining === undefined ? command : { ...command, timeoutMs: Math.min(command.timeoutMs ?? 300_000, remaining) }, {
             cwd: await this.#commandCwd(command),
             runner: this.#options.processRunner,
             trusted: this.#options.trusted
@@ -107,6 +110,11 @@ export class VerificationService {
         };
     }
     async verify(taskId) {
+        const stored = await this.#options.taskService.status({ taskId });
+        return stored.task.debug === undefined ? await this.#verify(taskId) :
+            await this.#options.taskService.debugService().verification(taskId, () => this.#verify(taskId));
+    }
+    async #verify(taskId) {
         const stored = await this.#options.taskService.status({ taskId });
         if (stored.status === "archived") {
             throw verificationError("TASK_NOT_ACTIVE", "An archived task cannot be verified.");
@@ -145,7 +153,8 @@ export class VerificationService {
             results.push(await this.#runCommand(validation.value, commandById(this.#options.config, commandId)));
         }
         const acceptance = validation.value.criteria.some(c => c.acceptance !== undefined && c.acceptance.mode !== "review-only")
-            ? await replayAcceptance({ ...this.#options, task: validation.value, sourceFingerprint }) : [];
+            ? await replayAcceptance({ ...this.#options, task: validation.value, sourceFingerprint,
+                ...(stored.task.debug === undefined ? {} : { remainingMs: () => this.#options.taskService.debugService().remaining(taskId) }) }) : [];
         let status = aggregateVerificationStatus([...results, ...acceptance.map(a => ({ required: true, status: a.status }))]);
         let sourceChanged = false;
         const postflightScope = await resolveReviewScope({
@@ -188,6 +197,16 @@ export class VerificationService {
             }
         }
         else {
+            if (stored.task.debug !== undefined && !sourceChanged) {
+                const failures = {};
+                for (const result of results) {
+                    const references = await this.#persistEvidence(validation.value, commandById(this.#options.config, result.commandId), result.startedAt, result.finishedAt, result, sourceFingerprint);
+                    relevantCriteria(validation.value, result.commandId).forEach((criterion, index) => { const reference = references[index]; if (reference !== undefined)
+                        failures[criterion.id] = [...(failures[criterion.id] ?? []), reference]; });
+                }
+                if (Object.keys(failures).length > 0)
+                    await this.#options.taskService.recordEvidence(taskId, failures);
+            }
             const required = [...results.filter((result) => result.required), ...acceptance.map(a => ({ commandId: a.runnerId, required: true,
                     status: a.status, failureClass: a.failureClass, exitCode: null, timedOut: false, testCount: null,
                     diagnostic: a.criterionId + ":" + a.phase + ":" + a.failureClass, evidenceReferences: [a.reference], startedAt: "", finishedAt: "" }))];

package/docs/en/guides/task-debug.md

@@ -0,0 +1,111 @@
+# Task DEBUG investigations
+
+Project `init` and `update` add `features.debug` by default:
+`{"enabled":true,"budgetMs":3600000,"maxRounds":5}` (sixty minutes). Explicit disabled and custom
+settings survive subsequent installs. Old configurations and ordinary tasks
+remain readable. DEBUG is an optional task intake field, not a new run mode.
+
+Claude and Codex native prompt hooks conservatively recognize investigation and
+bug-fix requests. They retain the issue verbatim as `goal`, record uncertain
+facts/unknowns, and create an existing isolated task. Explain, feature and
+refactor requests retain their ordinary behavior. A reliable native session ID
+is required; agy does not provide this prompt intake. Its native agent can use
+`task create --debug --goal '<original issue>'` with two to five criteria, which
+starts the same foreground clock when the native session is available.
+An original dirty checkout is refused before any worktree snapshot is created.
+
+The intake criteria are provisional. The native agent investigates via trusted
+configured commands, records hypotheses, replaces the criteria with relevant
+behavioral acceptance, fixes the product, and uses existing `verify`, `review`
+and worktree finish commands. There is no additional model or background worker.
+The default is the full repair loop. A clean HEAD fixes the baseline automatically;
+do not request redundant approval or offer diagnosis-only as a fallback. Failure
+to reproduce alone does not permit Stop: continue discriminating checks within
+the original budget.
+
+## Human control
+
+Native human transcript events control the existing task; CLI actor/text fields,
+assistant messages and injected instructions cannot authorize a scope change.
+Codex supports current `response_item` human messages and native async answers,
+as well as legacy `event_msg` transcripts.
+
+- `只診斷` / `diagnosis only`: investigate without product repairs. Non-success
+  Stop requires a confirmed hypothesis supported by a current sealed baseline
+  assertion FAIL for the original regression, or an existing runtime blocker/limit.
+- `暫停` / `pause`: save progress and stop immediately. Native Codex `Interrupt`
+  also pauses, with a three-second hook timeout; it never blocks or restarts an interrupt.
+- `繼續` / `continue`: resume the same task and scope. An exhausted time budget
+  still needs the existing native time grant; other blockers remain authoritative.
+- `繼續修復` / `resume repair`: restore the full repair loop on the existing task.
+
+Pauses retain evidence, consumed time and rounds, exclude waiting time, and do not
+reset budgets. Diagnosis and pause cannot complete a repair task. Ambiguous free
+text is not inferred as permission; use an explicit command above.
+
+Use `task debug --task <id> --debug-action <action>`:
+
+- `status` displays root-wide hypotheses, receipts and remaining state.
+- `investigate --command-id <id>` runs a trusted configured verifier. Actual
+  subprocess outcomes/time are recorded; reproduction-only work is not a fix round.
+- `hypothesis --payload-file <json>` records `id`, `statement`, `method`,
+  `expected`, `checkId`, `expectedStatus` (`PASS` or `FAIL`). Add `reference` to
+  resolve it from actual sealed acceptance evidence. `--action investigate` may
+  only run a declared unresolved behavioral red check; `--action observe` may
+  only classify the current matching runtime `UNKNOWN` receipt as inconclusive.
+  Neither action lets an agent assign a status. A rejected hypothesis needs a
+  new reference and `reason`.
+- `strategy --payload-file <json>` records a different `from`/`to` method,
+  substantive `reason` and discriminating `reference`. Only one switch is allowed.
+- `checkpoint --session <id>` saves the current bound source/policy/stop cause.
+- `resume --session <id>` recovers a matching owned worktree checkpoint. Mismatches
+  require human confirmation and remain preserved; this command cannot waive them.
+- `extend --session <native-id> --event-id latest` reads the current native human
+  continue event. It grants exactly twenty additional minutes once, only after
+  time exhaustion and without waiving any other blocker. No actor/text flag can
+  authorize a grant. Missing native transcripts fail closed as unsupported.
+
+Limits belong to the original root across revisions, children and sessions.
+Repeating an active issue's text from a new session reattaches that root (or
+resumes the worktree holding it) instead of starting a fresh budget. A
+resolved hypothesis cannot return under a new id with the same statement and
+method; reopen the original with new discriminating evidence.
+Controlled investigation, verification and acquired review execution consume
+active time; observable review-slot waiting is excluded. Claude, Codex, and agy
+use their native session lifecycle to account foreground reasoning, tool use,
+and edits. Accepted idle Stop closes the foreground clock. Rejected Codex Stop
+keeps the clock running, including repeated Stop (`stop_hook_active: true`). OpenCode has no supported
+foreground lifecycle and remains unsupported. Time between stopped turns is
+paused. An interrupted unsealed operation remains blocked until its persisted process
+identity proves death; only then is an UNKNOWN environment receipt sealed and
+the elapsed interval retained.
+
+Only changed product candidates followed by verification count toward repair
+rounds. Test/fixture edits do not. New paired original-regression outcomes or
+new discriminating hypothesis outcomes count as progress; renaming a task or
+hypothesis does not. Two stagnant rounds require the strategy switch; two more
+stop, subject to the global round/time ceilings.
+
+Success requires baseline assertion red and candidate green for the original
+regression, required related checks, a supported confirmed hypothesis, and two
+fresh independent reviews bound to the current source, contract, config and
+meaningful DEBUG proof. Missing IDs, setup failure, skip, timeout and UNKNOWN
+never prove reproduction. Proof changes invalidate review. Completed tasks and
+worktree finish retain the existing attestation/integration requirements.
+
+On Claude, agy and native Codex, Stop checks an active DEBUG issue even without Git net diff,
+with or without the completion gate. Without the gate this check alone runs,
+with one targeted task/config reload on a gate fault. A second failure emits an
+explicit `UNKNOWN` / incomplete diagnostic with `agent-ops doctor` recovery,
+permits non-success Stop and preserves the task, evidence and budgets. It never
+attests completion or retries indefinitely.
+A valid runtime stop checkpoint permits non-success Stop while retaining the
+active task. `allow-stop` cannot waive DEBUG. Gates are never automatically
+enabled for unsupported hosts: the generic Codex completion gate remains
+unsupported, while its DEBUG-specific Stop uses native `decision: "block"`
+with a continuation reason. `continue: false` would stop the harness and is not
+used to continue DEBUG. OpenCode Stop is unsupported. This feature
+persists foreground progress, and does not promise
+execution after the native conversation closes. Native transcripts are trusted
+host evidence, not protection against an attacker with the same filesystem
+authority.

package/docs/en/spec/harness-adapters.md

@@ -118,7 +118,20 @@ installed configuration; the managed OpenCode `tool.execute.before` plugin can
 throw its documented denial or unavailable-runtime error for its supported Bash
 surface. Codex remains `unknown` and never emits a denial. Fixture tests assert
 these wire and plugin shapes only; they do not prove that a host honors a
-denial. Every `SessionStart` and `Stop` failure path remains fail-open.
+denial. `SessionStart` and ordinary `Stop` failures remain fail-open. Active
+DEBUG Stop faults instead retry one targeted reload, then explicitly report
+UNKNOWN/incomplete and preserve the original state before non-success Stop.
+
+Codex DEBUG lifecycle semantics were rechecked on 2026-10-11 against the
+[official hooks reference](https://learn.chatgpt.com/docs/hooks#stop): Stop
+`decision: "block"` with `reason` schedules a continuation; `continue: false`
+halts it. `stop_hook_active` identifies a prior continuation and cannot waive
+the DEBUG check. Native `Interrupt` pauses with a three-second timeout and
+never blocks or restarts the human interruption. This DEBUG-specific policy
+does not enable Codex's generic completion gate or optional Stop verifier.
+Codex separately trusts each exact native hook definition. After managed hook
+updates, review new or changed definitions in `/hooks`; agent-ops repository
+trust alone does not make an unreviewed native hook active.
 
 The agy adapter uses native project `GEMINI.md` routing to
 `.agent-ops/GEMINI.md`;
@@ -130,7 +143,7 @@ unproven final changed conversation. Read-only conversations stop normally.
 On Windows the generated command is invoked through `cmd /c`.
 
 Stop verification is explicit, trusted, report-only, and disabled by default.
-Every Stop result continues the native harness and may carry only bounded
+Every optional Stop verification result continues the native harness and may carry only bounded
 command evidence; it is never task-completion evidence.
 
 The `loop` profile is separate from the ordinary capability matrix above. It

package/docs/zh-TW/guides/task-debug.md

@@ -0,0 +1,66 @@
+# Task DEBUG 調查
+
+`init` / `update` 預設加入 `features.debug`：啟用、60 分鐘、5 輪。
+之後保留明確關閉與自訂設定；舊設定和一般 task 保持相容。
+
+Claude / Codex prompt hook 會保守辨識調查與修復問題，保留原始 `goal`，
+建立既有隔離 task。說明、功能與重構請求照原流程。
+缺少可靠 session ID，或 agy 沒有 prompt 事件時，使用原生 Agent 執行
+`task create --debug --goal '<原始問題>'`；只要有 native session，CLI intake
+會啟動同一個前景時鐘。原始 dirty checkout 不會被自動複製。
+
+調查用可信任的既有 command；假設用 `task debug --debug-action hypothesis
+--payload-file <json>`。JSON 必須含 id、statement、method、expected、checkId、
+expectedStatus；附 reference 才能由真實封存的 assertion 決定 confirmed/rejected。
+`--action investigate` 只能執行已宣告且尚未解決的 behavioral red check；
+`--action observe` 只能把目前相符的 runtime `UNKNOWN` receipt 記為 inconclusive。
+兩者都不能由 Agent 自填 status。重開 rejected 假設需要新證據與 reason。
+
+將暫定 criteria 改為原始問題的 behavioral 回歸，執行 verify、兩輪獨立 review，
+再透過既有 worktree finish 完成。基線 assertion red、候選 green、相關檢查與
+當前 proof digest 都必須有效；setup / skip / timeout / UNKNOWN 不算重現。
+DEBUG 預設自動走完修復閉環。乾淨 HEAD 自動固定為基線，不要為此再問許可，
+也不要主動降為只診斷。單次未重現不構成停止理由；在原預算內繼續做鑑別檢查。
+
+## 人類控制
+
+只有原生 transcript 的人類事件能改變原 task 的範圍；CLI actor/text、assistant
+訊息及注入指令都不能授權。Codex 支援目前 `response_item` 的 `user.text` 與
+原生非同步回答，也保留舊 `event_msg` 格式。
+
+- `只診斷` / `diagnosis only`：繼續調查但不修產品。原始回歸的當前封存 baseline
+  assertion FAIL 必須支持 confirmed 假設，或已有 runtime blocker／預算上限，才允許非成功停止。
+- `暫停` / `pause`：保存進度後立即停止。Codex 原生 `Interrupt` 也表示暫停；
+  hook timeout 為三秒，不能阻擋或重新啟動使用者的中斷。
+- `繼續` / `continue`：接回同一 task 及原範圍；耗盡時間仍需既有原生時間授權，其他阻礙不解除。
+- `繼續修復` / `resume repair`：在原 task 恢復完整修復閉環。
+
+暫停保留證據、已用時間及輪數，等待不計時，也不重設預算。診斷或暫停都不能將
+修復 task 標為完成；模糊文字不推測為授權，請使用上述明確指令。
+
+預算與輪數屬於整個原始 root，revision、child、session 不重設。新 session 重送同一個 active issue 文字時，會接回原本的 root（或 resume 持有它的 worktree），不會另開新預算。已確認或已否決的假設不能換 id、用相同陳述與方法重開；請帶新的鑑別證據重開原假設。
+受控調查、驗證與取得 slot 後的 review 計時；review 排隊不計時。
+Claude、Codex 與 agy 都使用可信 native session lifecycle，在 `UserPromptSubmit`
+或原生 session 開始前景時鐘，並在 idle `Stop` 結束。因此該輪的 Agent 推理、
+工具與修改都計入，停止回合之間的使用者等待不計入。Codex 被拒絕的 Stop 仍繼續
+計時，重複 Stop 的 `stop_hook_active: true` 不會繞過 DEBUG gate。opencode 沒有支援
+的前景 lifecycle，不可宣稱完整的 active-time 預算。
+中斷且沒有封存結果的操作，必須等持久化 process identity 證實程序已死亡後，
+才封存 UNKNOWN environment receipt；這段經過時間仍會保留，不會退還不明時間。
+測試材料修改不算修復輪；兩輪停滯需要一次實質策略切換，再兩輪停滯停止。
+
+checkpoint 保存 task/session/source/contract/config/cause；resume 只接受同一
+擁有者 worktree 的匹配 checkpoint，保留 dirty 內容及預算。失配需要人類確認。
+時間耗盡後明確「繼續」可透過 `extend --event-id latest` 讀取原生人類事件，
+一次增加 20 分鐘；沒有可信事件来源則回報 unsupported，其他阻礙不被解除。
+
+Claude / agy / 原生 Codex 的 Stop 都會檢查無 Git 差異的 active DEBUG task，不論是否安裝 completion gate。
+DEBUG gate 故障先針對 task/config 重新載入一次；仍失敗則明確回報 `UNKNOWN／未完成`
+與 `agent-ops doctor` 恢復方法，允許非成功停止並保留 task、證據及預算，不無限重試。
+有效停止 checkpoint 只允許非成功停止，task 仍 active；allow-stop 不能繞過。
+Codex 的一般 completion gate 仍 unsupported；DEBUG 專用 Stop 以原生
+`decision: "block"` 與 reason 續跑，不能使用會停止 harness 的 `continue: false`。
+已接受的 Stop 結束前景時鐘；opencode Stop unsupported。
+只承諾前景對話與持久化進度，不承諾對話關閉後繼續，也不宣稱抵擋同檔案權限攻擊。
+
+完整命令及細節見英文 [Task DEBUG](../../en/guides/task-debug.md)。

package/docs/zh-TW/spec/harness-adapters.md

@@ -101,7 +101,16 @@ Runtime-failure 處理中，只有 `command-policy` 為 fail-closed。當已安
 OpenCode `tool.execute.before` plugin 可在其支援的 Bash surface 上 throw 文件化的
 denial 或 unavailable-runtime error。Codex 維持 `unknown` 且絕不輸出 denial。
 Fixture test 只斷言這些 wire 與 plugin shape；它們不證明 host 會實際遵守 denial。
-每個 `SessionStart` 與 `Stop` failure path 都維持 fail-open。
+`SessionStart` 與一般 `Stop` failure 維持 fail-open。active DEBUG Stop 故障則
+針對 task/config 重新載入一次，再明確回報 UNKNOWN／未完成並保留原狀態，才允許非成功停止。
+
+Codex DEBUG lifecycle 語意於 2026-10-11 依[官方 hook 文件](https://learn.chatgpt.com/docs/hooks#stop)
+重新檢查：Stop 的 `decision: "block"` 加 `reason` 會排程續跑；`continue: false`
+會停止。`stop_hook_active` 表示已經續跑過，不能繞過 DEBUG 檢查。
+原生 `Interrupt` 暫停採三秒 timeout，不得阻擋或重啟人類中斷。
+此 DEBUG 專用政策不會啟用 Codex 的一般 completion gate 或 optional Stop verifier。
+Codex 另以每個原生 hook 的精確定義保存信任。更新受管理 hook 後，必須在 `/hooks`
+審核新增或變更的定義；agent-ops repository trust 不會啟用尚未審核的原生 hook。
 
 agy adapter 在 project scope 使用原生 `GEMINI.md` routing 到
 `.agent-ops/GEMINI.md`；user
@@ -112,7 +121,7 @@ changed conversation 才回傳 `decision: "continue"`；唯讀 conversation 正
 結束。在 Windows 透過 `cmd /c` 呼叫產生的 command。
 
 Stop verification 必須明確啟用、具備 trust、為 report-only 且預設 disabled。
-每個 Stop 結果都會讓 native harness 繼續，最多攜帶有界 command evidence，永遠
+每個 optional Stop verification 結果都會讓 native harness 繼續，最多攜帶有界 command evidence，永遠
 不是 task-completion evidence。
 
 `loop` profile 與上方 ordinary capability matrix 分離。它只保存有界的 local

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.8.0",
+  "version": "0.8.4",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/schemas/config.schema.json

@@ -247,9 +247,13 @@
         "office": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["enabled"],
+          "required": [
+            "enabled"
+          ],
           "properties": {
-            "enabled": { "type": "boolean" }
+            "enabled": {
+              "type": "boolean"
+            }
           }
         },
         "completionGate": {
@@ -275,6 +279,30 @@
               "type": "boolean"
             }
           }
+        },
+        "debug": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "enabled",
+            "budgetMs",
+            "maxRounds"
+          ],
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "budgetMs": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 86400000
+            },
+            "maxRounds": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100
+            }
+          }
         }
       }
     },

package/schemas/manifest.schema.json

@@ -145,6 +145,7 @@
               "SubagentStart",
               "SubagentStop",
               "Stop",
+              "Interrupt",
               "SessionEnd"
             ]
           }

package/schemas/task.schema.json

@@ -180,9 +180,13 @@
                   "type": "object"
                 },
                 "then": {
-                  "required": ["reviewOnlyReason"],
+                  "required": [
+                    "reviewOnlyReason"
+                  ],
                   "properties": {
-                    "reviewOnlyReason": {"type": "string"},
+                    "reviewOnlyReason": {
+                      "type": "string"
+                    },
                     "bindings": {
                       "maxItems": 0,
                       "type": "array"
@@ -276,6 +280,42 @@
     "contractRevision": {
       "type": "integer",
       "minimum": 0
+    },
+    "debug": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rootTaskId",
+        "facts",
+        "unknowns"
+      ],
+      "properties": {
+        "rootTaskId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4096
+        },
+        "facts": {
+          "type": "array",
+          "maxItems": 128,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096
+          }
+        },
+        "unknowns": {
+          "type": "array",
+          "maxItems": 128,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 4096
+          }
+        }
+      }
     }
   },
   "$defs": {
@@ -315,6 +355,26 @@
               "type": "object"
             },
             "type": "array"
+          },
+          "debug": false
+        },
+        "type": "object"
+      }
+    },
+    {
+      "if": {
+        "required": [
+          "debug"
+        ],
+        "type": "object"
+      },
+      "then": {
+        "required": [
+          "goal"
+        ],
+        "properties": {
+          "schemaVersion": {
+            "const": 2
           }
         },
         "type": "object"