@kylecheng3146/agent-ops 0.10.0 → 0.11.0

package/dist/runtime/src/verify/source-fingerprint.js

@@ -3,17 +3,30 @@ import { join } from "node:path";
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { resolveGitCommit } from "./change-surface.js";
+/**
+ * Escape-ledger records are committed after the fix; a commit touching only them leaves the base-mode fingerprint alone.
+ * Only top-level task records qualify: rules/ steer the surface gate and stay fingerprinted.
+ */
+const ledgerRecord = (path) => /^\.agent-ops-escapes\/task-[A-Za-z0-9-]+\.json$/u.test(path);
+/** HEAD's tree without the ledger, so a ledger-only commit yields the same digest. */
+async function ledgerFreeTree(runner) {
+    const result = await runner.run(["ls-tree", "-r", "--full-tree", "-z", "HEAD"]);
+    if (result.exitCode !== 0)
+        throw new AgentOpsError("CHANGE_SURFACE_GIT_FAILED", "Git could not list the HEAD tree.");
+    const entries = Buffer.from(result.stdout).toString("utf8").split("\0").filter(entry => entry !== "" && !ledgerRecord(entry.split("\t", 2)[1]));
+    return sha256(entries.join("\0"));
+}
 export async function calculateSourceFingerprint(root, scope, runner) {
-    const head = await resolveGitCommit(runner, "HEAD");
     if (scope.mode === "base") {
         return sha256(JSON.stringify({
-            domain: "agent-ops-source-v1",
+            domain: "agent-ops-source-v2",
             mode: scope.noChange === true ? "goal-no-change" : "base",
-            head,
+            tree: await ledgerFreeTree(runner),
             base: scope.resolvedBase,
-            paths: [...scope.changedFiles]
+            paths: scope.changedFiles.filter(path => !ledgerRecord(path))
         }));
     }
+    const head = await resolveGitCommit(runner, "HEAD");
     const paths = [];
     for (const path of scope.changedFiles) {
         const absolute = join(root, ...path.split("/"));

package/docs/en/guides/configuration.md

@@ -275,7 +275,7 @@ evidence. Give each editing conversation its own worktree instead:
   (Claude Code refuses it inside an isolated worktree session). `agent-ops
   worktree finish <name>` completes every non-archived task in the worktree,
   subtasks before their parents, each against the base its PASS review
-  recorded (the worktree's base when none was recorded), before any rebase.
+  recorded (the worktree's base when none was recorded), before merging.
   If one cannot complete, nothing merges and the error names the task.
   Creating a subtask keeps the session attached to the top of its tree, and
   each task keeps its own review record, so a parent and a subtask reviewed
@@ -295,9 +295,13 @@ evidence. Give each editing conversation its own worktree instead:
   its files, so uncommitted changes there block it. When the main checkout is
   on another branch or detached, only the target's ref moves: the checkout, its
   files and its uncommitted changes are left alone. A target checked out in
-  another worktree is refused, naming that path. If the target moved, it rebases; a clean rebase whose own patch
-  is unchanged is re-verified before merging, and a conflict is reported with
-  the `refs/notes/agent-ops` intent of the work that landed first. The note
+  another worktree is refused, naming that path. If the target moved, it rebases the worktree and
+  stops with `WORKTREE_REBASED` before completing any task: earlier evidence
+  covered the old base, not the combination that would merge. Verify and
+  review again with the printed `--base`, then finish again; a task that was
+  already complete cannot take new evidence, so cover the rebased change with
+  a follow-up task. A conflict is reset and reported with the
+  `refs/notes/agent-ops` intent of the work that landed first. The note
   records every task of the worktree, subtasks indented under their parent,
   and a `session: <id>` line naming the session that finished it. Finish
   also resets that session's gate baseline to the merged source, so the

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

@@ -1,123 +1,41 @@
 # 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.
-- `origin --payload-file <json>` declares where the bug came from once a
-  hypothesis is confirmed: `{"kind": "escape-of", "commit": "<commit>", "label":
-  "<earliest gate>"}` (optional `"receipt"`) or `{"kind": "pre-existing" |
-  "external", "reason": "..."}`. It revises the contract, so re-verify and
-  re-record the confirmed hypothesis before review; finish refuses
-  `ESCAPE_ORIGIN_MISSING` without it. `escape-of` prints the link state and
-  `git blame` hints and writes `.agent-ops-escapes/<task-id>.json`, which is
-  committed with the fix (see `EVIDENCE-ESCAPE-001`). A surface label also
-  needs a tracked `.agent-ops-escapes/rules/<rule-id>.json` rule that replays
-  at the escaped commit, and a criteria/verify label needs `"promote":
-  "<runnerId:checkId>"`; finish refuses `ESCAPE_RULE_UNPROVEN` otherwise (see
-  `EVIDENCE-ESCAPE-002`).
-- `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.
+A DEBUG task is an ordinary task whose acceptance proves the original
+regression: a behavioral criterion whose `redCheckIds` fail with an assertion at
+the baseline commit and pass on the candidate. Nothing else is special about it.
+
+```sh
+agent-ops task create --debug --title "Fix cart scroll" \
+  --goal '<the issue, verbatim>' \
+  --surface-file surface.json \
+  --criterion-file regression.json --criterion-file related.json
+```
+
+- `--debug` needs `--goal` and at least one behavioral criterion with
+  `redCheckIds`; otherwise creation fails with `TASK_DEBUG_RED_CHECK_REQUIRED`.
+  The surface audit is required as for any task.
+- The baseline is the commit the task was created on; `task revise --baseline
+  <ref>` moves it (for example off the wrong branch) and voids earlier evidence.
+- Then fix, commit, `verify`, two-round `review` and `worktree finish` exactly
+  as for any task. Setup failure, skip, timeout and UNKNOWN never prove
+  reproduction; the red check must fail on an assertion at the baseline.
+
+## Escape origin (advisory)
+
+If you know where the bug came from, record it like any task:
+`task revise --escape-of <commit> --escape-label <label>`. It writes `.agent-ops-escapes/<task-id>.json` and
+prints the link state, `git blame` hints and any rule proof
+(`ESCAPE_RULE_UNPROVEN` and friends). None of it blocks finish; see
+`EVIDENCE-ESCAPE-001` and `EVIDENCE-ESCAPE-002`.
+
+## Removed in 0.11.0
+
+`task debug` (hypotheses, strategy switches, investigate, checkpoint, resume,
+extend, origin), the 60-minute budget and five-round limit, native control
+words (只診斷, 暫停, 繼續, 繼續修復, 取消時間限制), automatic DEBUG intake from
+prompt hooks, the DEBUG-specific Stop block and the Codex `Interrupt` hook are
+gone. `task debug` now fails with `TASK_DEBUG_REMOVED`.
+
+Older state still loads: tasks keep their `debug` tag, stored budget and
+hypothesis state is ignored, `originRequired` no longer blocks finish, and a
+config's `features.debug` is accepted and dropped by the next `update`.

package/docs/en/spec/acceptance-and-evidence.md

@@ -18,6 +18,11 @@ Executable acceptance MUST bind the current contract to immutable replay evidenc
   build and test build. Tasks provide stable check IDs and explicit committed
   test/fixture/helper materials. Each checkout installs and builds its own version
   before candidate materials are overlaid. Tasks cannot override runner commands.
+- A generic runner must emit every `checkId` requested by criteria sharing its
+  runner, baseline and materials, each exactly once; missing or duplicate rows are
+  UNKNOWN. Other rows are ignored, so a binding may list only its red checks. A
+  failing unrequested row still disagrees with a PASS aggregate through the
+  runner's exit code, which makes the candidate UNKNOWN, never green.
 - Fixture, collection, build, timeout, cancellation, truncated output, missing or
   duplicate IDs, retries and skips MUST NOT establish red or green. Complete raw
   execution artifacts are digest-bound to the contract, materials and commits.
@@ -30,9 +35,15 @@ Executable acceptance MUST bind the current contract to immutable replay evidenc
   counters and cannot supply mechanical proof by itself. Pytest requires one
   ordered setup/call/teardown lifecycle per nodeid; the Rust protocol requires
   explicit attempts. Missing metadata MUST NOT default to a successful attempt.
-- Baselines are immutable creation commits, or failed candidates for finding pins.
-  Revise/replan preserve the original goal, every mapped requirement and previous
-  contracts/evidence. New contracts require new proof and both fresh reviews.
+- Baselines are creation commits, or failed candidates for finding pins.
+  `task revise --baseline <ref>` moves every typed criterion's baseline (and the
+  task's creation commit) at once to a commit that is an ancestor of HEAD, for example after a task was opened on the
+  wrong branch, and voids its verification. Revise/replan preserve the original
+  goal, every mapped requirement and previous contracts/evidence.
+- Verification evidence binds an execution hash of the criteria only. A revise
+  that changes the surface or origin keeps it; a criteria or configuration change
+  voids it. Evidence from before 0.11 bound the full contract hash and still
+  matches an unchanged contract. Every new contract needs both fresh reviews.
 - `task pin-finding` validates saved report digest/index provenance. Recurrence
   explicitly names an existing pin. A sixth criterion returns a replan obligation
   without changing state; the mapped replan must retain the pin and all requirements.
@@ -72,7 +83,7 @@ Each child worktree MUST record its modification intent before editing.
 
 Every new task MUST record a surface audit of where else its change lands before writing criteria, and review MUST NOT run while discovery finds an unclassified place.
 
-- Trigger: Creating a task (`task create`, a run plan, or before a DEBUG task's first repair), revising its surface, or reviewing it.
+- Trigger: Creating a task (`task create`, including `--debug`, or a run plan), revising its surface, or reviewing it.
 - Action: Search four axes with recorded fixed-string queries or `n/a: reason`, classify every hit as included, excluded (glob + reason) or UNKNOWN, give every surface row an observable `behavior`, and declare each shared contract compatible or breaking. Pass it with `task create|revise --surface-file <json>`.
 - Evidence: The surface is stored on the task, bound into its contract hash with revision history, replayed by `git grep -F` before review, and handed to both reviewers under the `surface-coverage` criterion.
 - Positive: `A diff token hits three copy-pasted sibling pages; the audit includes them with their behavior before review runs.`
@@ -114,8 +125,11 @@ Every new task MUST record a surface audit of where else its change lands before
   dismissals. Reviewers see each dismissal with its hit count, flagged when it
   hid a file an earlier `SURFACE_UNCLASSIFIED` block named.
   Results are cached by HEAD, base, diff, query set and config hash.
+- `verify` runs the same gate after verification and prints its result as
+  advisory lines (`Surface: PASS`, or the code and unclassified paths), so the
+  surface is fixed before review; only review enforces it.
 - Review returns NOT_RUN with: `SURFACE_MISSING` (no or unparseable surface;
-  also refused at create for non-DEBUG tasks), `SURFACE_UNCLASSIFIED`,
+  also refused at create), `SURFACE_UNCLASSIFIED`,
   `SURFACE_QUERY_TOO_BROAD` (one recorded query over 200 files),
   `SURFACE_EXCLUSION_TOO_BROAD` (one glob over 10 files, or any file in the
   diff), `SURFACE_DISMISSAL_TOO_BROAD` (over 128 dismissals),
@@ -133,17 +147,15 @@ Every new task MUST record a surface audit of where else its change lands before
 
 ## EVIDENCE-ESCAPE-001
 
-Every DEBUG fix MUST declare where its bug came from before review, and a declared escape MUST be linked, labelled and recorded mechanically.
+A bug fix SHOULD declare where its bug came from when known, and a declared escape MUST be linked, labelled and recorded mechanically. The declaration is advisory: it never blocks finish.
 
-- Trigger: A DEBUG hypothesis is confirmed, or a normal task fixes a bug that passed earlier gates.
-- Action: Declare `origin` with `task debug --debug-action origin --payload-file <json>`: `{"kind": "escape-of", "commit": "<commit>", "label": "<label>"}` (optional `"receipt"`), or `{"kind": "pre-existing" | "external", "reason": "..."}`. A normal task may opt in with `task create|revise --escape-of <commit> --escape-label <label> [--escape-receipt <id>]`. Commit the `.agent-ops-escapes/<task-id>.json` record with the fix.
-- Evidence: `origin` is bound into the task contract hash; finish, `task complete` and the completion gate refuse a DEBUG task created after this rule without it as `ESCAPE_ORIGIN_MISSING`; both reviewers receive the link state, labels, facts and residual risks under the `escape-label` criterion.
-- Positive: `Hypothesis confirmed; origin escape-of 864dbbe2 label surface; replay marks the missed page surface-unseen; the record is committed with the fix.`
-- Negative: `Finish a DEBUG fix without an origin, or relabel a surface-excluded miss as review because the reviewer "should have noticed".`
+- Trigger: A DEBUG task (`task create --debug`) or any task fixes a bug that passed earlier gates and its origin is known.
+- Action: Declare `origin` with `task create|revise --escape-of <commit> --escape-label <label> [--escape-receipt <id>]`, the same for DEBUG and normal tasks. `pre-existing` and `external` origins (with a `reason`) recorded by 0.10 `task debug` still load; an undeclared origin is counted as such. Commit the `.agent-ops-escapes/<task-id>.json` record with the fix.
+- Evidence: `origin` is bound into the task contract hash; both reviewers receive the link state, labels, facts and residual risks under the `escape-label` criterion. A task without an origin still finishes; 0.10 tasks marked `originRequired` are no longer refused (`ESCAPE_ORIGIN_MISSING` was removed in 0.11.0).
+- Positive: `Regression red at the baseline, green on the fix; origin escape-of 864dbbe2 label surface; replay marks the missed page surface-unseen; the record is committed with the fix.`
+- Negative: `Relabel a surface-excluded miss as review because the reviewer "should have noticed".`
 
-- The declaration comes after a confirmed hypothesis (`ESCAPE_ORIGIN_EARLY`
-  otherwise), inside the DEBUG budget. It is a contract revision: re-verify,
-  re-record the confirmed hypothesis with the new evidence, then review.
+- The declaration is a contract revision: re-verify, then review.
   Re-declaring replaces the record. The output lists `git blame` hint commits
   for lines the fix changed or removed; blame is a hint only, because an
   omission bug lives in lines nobody wrote.
@@ -177,13 +189,13 @@ Every DEBUG fix MUST declare where its bug came from before review, and a declar
 
 ## EVIDENCE-ESCAPE-002
 
-A surface escape MUST become a proven, tracked rule before its fix finishes, and learned rules MUST only tighten the surface gate.
+A surface escape SHOULD become a proven, tracked rule, and learned rules MUST only tighten the surface gate. The proof is advisory: it never blocks finish.
 
 - Trigger: A declared escape-of origin (EVIDENCE-ESCAPE-001), or a past escape backfilled with `task create --escape-of <commit> --escape-label <label> --escape-fix <fix-commit>`.
-- Action: For a `surface`, `surface-unseen` or `surface-excluded` label, commit a rule `.agent-ops-escapes/rules/<rule-id>.json` shaped `{"id", "escape", "label", "trigger": {"paths", "tokens"}, "expand": {"paths", "queries"}, "noExclude"}` and re-declare the origin. For `criteria` or `verify`, name the fixing task's red-to-green check with `--escape-promote <runnerId:checkId>` (DEBUG payload `"promote"`). Other labels record a lesson.
-- Evidence: Finish, `task complete` and the completion gate re-run the proof and refuse `ESCAPE_RULE_UNPROVEN`, `ESCAPE_RULE_TOO_BROAD` or `SURFACE_BUDGET_EXCEEDED`; the ledger record stores the proving rule, its content hash and its backtest fires, commits and rate.
+- Action: For a `surface`, `surface-unseen` or `surface-excluded` label, commit a rule `.agent-ops-escapes/rules/<rule-id>.json` shaped `{"id", "escape", "label", "trigger": {"paths", "tokens"}, "expand": {"paths", "queries"}, "noExclude"}` and re-declare the origin. For `criteria` or `verify`, name the fixing task's red-to-green check with `--escape-promote <runnerId:checkId>` (origin field `"promote"`). Other labels record a lesson.
+- Evidence: Declaring the origin runs the proof and prints `ESCAPE_RULE_UNPROVEN`, `ESCAPE_RULE_TOO_BROAD` or `SURFACE_BUDGET_EXCEEDED` when it fails; since 0.11.0 finish no longer refuses them. The ledger record stores the proving rule, its content hash and its backtest fires, commits and rate.
 - Positive: `Escape surface-unseen; rule image-size-siblings fires on the escaped commit, its query hits both missed sibling pages there, and fires on 2 of the last 200 commits.`
-- Negative: `Finish a surface escape whose rule never fires on the escaped commit, or add a rule field that excludes paths.`
+- Negative: `Report a surface escape as proven when its rule never fires on the escaped commit, or add a rule field that excludes paths.`
 
 - Rules are data only and need no trust: triggers and expands become argv
   `git grep -F` queries and path globs, never shell or regex. The strict schema
@@ -253,7 +265,7 @@ New verification evidence uses schema 3. Schema 2 remains readable and its exit-
 
 Existing task files remain readable without migration. Legacy tasks without a config baseline, arbitrary evidence references, or unfinished archived children must be recreated and verified/reviewed before completion. Repeating completion also revalidates the evidence; an old completed status alone is insufficient. Runtime callers must supply `TaskServiceOptions.completion`; omitting this repository context fails closed for completion while leaving read-only task operations available.
 
-Before committing, use the default worktree scope for verify, review and completion. After committing, use the same `--base <git-ref>` on all three commands to produce fresh proof for that committed range; `TaskServiceOptions.completion.base` selects it for runtime callers. Base mode requires a clean worktree. Without a worktree change surface or an explicit base, completion returns `TASK_COMPLETION_SCOPE_REQUIRED`. The agy Stop gate still checks worktree-scoped proof: complete and stop before committing, or use its user-approved one-time permit after inspecting a completed base-scoped task.
+Before committing, use the default worktree scope for verify, review and completion. After committing, use the same `--base <git-ref>` on all three commands to produce fresh proof for that committed range. When `--base` is absent and the tree is clean, verify and review choose it: a session worktree uses its merge-base with the target branch (which follows a finish rebase), elsewhere the task's creation commit when it is an ancestor of HEAD. Base-mode source fingerprints ignore escape-ledger task records (`.agent-ops-escapes/task-*.json`; rules stay fingerprinted), so committing the ledger keeps verification and review current; fingerprints from 0.10 differ, so re-verify once after upgrading; `TaskServiceOptions.completion.base` selects it for runtime callers. Base mode requires a clean worktree. Without a worktree change surface or an explicit base, completion returns `TASK_COMPLETION_SCOPE_REQUIRED`. The agy Stop gate still checks worktree-scoped proof: complete and stop before committing, or use its user-approved one-time permit after inspecting a completed base-scoped task.
 
 This enforces the toolkit's completion command, not a host's natural-language completion claim. It does not prevent a process with the same filesystem authority from editing task/evidence files directly, and it does not lock Git or external source writers.
 

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

@@ -109,7 +109,7 @@ The current registration matrix is intentionally asymmetric:
 | office-presence (Preview) | degraded | degraded | supported | degraded |
 | lifecycle-summary | degraded | supported | supported | degraded |
 | command-policy | supported | unknown | supported | supported |
-| completion-gate | supported | unsupported | unsupported | unsupported |
+| completion-gate | supported | unsupported | supported | unsupported |
 | optional-stop-verify | degraded | unsupported | supported | degraded |
 
 For runtime-failure handling, only `command-policy` is fail-closed. Claude
@@ -118,17 +118,12 @@ 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. `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.
+denial. `SessionStart` and `Stop` failures remain fail-open.
+
+Since 0.11.0 no hook is DEBUG-specific: prompts never open DEBUG tasks, Stop
+never holds a session for one, and Codex `Interrupt` is no longer registered
+(a stale registration from an older install is a no-op until `update`). Codex
+still has no 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.
@@ -191,6 +186,34 @@ removes only `run` and keeps `loop`.
 - Positive: `A Claude Code session with the run profile writes .agent-ops/state/run-goal.md in the main checkout and starts agent-ops run --host claude --wait in the background.`
 - Negative: `Split an eight-criteria change into subtasks while the run profile is active, add auto-run text to GEMINI.md, or resume a blocked run without the user.`
 
+`run status` includes `recovery` in JSON and the same guidance in text: phase
+(unknown for legacy records), original bounded redacted diagnostic, sealed proof
+(`recorded-unchecked` is an observation, not validation), cleanup state,
+resumability and concrete remediation. An unchanged cleanup failure retains its
+original cause. Trust, native identity, generation and denial failures remain
+fail-closed; a sealed proof never erases a native or organization denial.
+The JSON `state` of `run status` and `run logs` omits the event history and goal
+text, keeping `eventCount` and `goalHash`, so repeated polling stays small;
+`run logs` returns the events themselves.
+
+Manual resume of a receipt-bound integration validates the exact sealed proof,
+receipt digest and transaction, owner/generation, candidate/target ancestry and
+Git note before cleanup. It executes only missing note, gate, trust and checkout
+cleanup steps; it preserves existing receipt bytes and completed task/proof work.
+A missing unrecorded note may be bound to the sealed receipt; a missing or changed
+recorded note blocks. Completed cleanup requires the owned checkouts to be gone.
+The target is never moved again. A changed target is accepted only as a descendant
+of the receipt-bound candidate with recorded integration history.
+
+Cleanup records a bounded redacted original failure and a retry-input digest of
+the transaction boundary, checkout status, untracked file metadata and heartbeat
+liveness. Identical inputs return `RUN_CLEANUP_UNCHANGED` before repeating cleanup;
+a remediation delta permits a fresh attempt after all safety checks. This digest
+is a retry guard, not verification reuse or new authority. Finalization failure
+does not immediately replay the failed integration: it preserves the original
+cause for manual recovery. Live/unknown/forged/symlink heartbeats and unrelated
+user files retain the existing non-force removal protections.
+
 ## HARNESS-ADAPTER-008
 
 `agent-ops office` (Preview) MUST show progress read-only from agent-ops state alone. The

package/docs/en/spec/loop-engineering.md

@@ -14,8 +14,12 @@
   goals. Same-host writers use isolated worktrees and current generation leases;
   the coordinator counts toward the maximum two writers. Dependencies become
   available only through frozen deliveries; child baselines follow those commits.
-- The default 60-minute budget counts the union of active intervals, including
-  setup, proof, review and integration. Resume keeps elapsed time and usage epochs.
+- New runs have no total time cap (`budget.limitMs: null`). Active interval unions
+  still measure setup, proof, review and integration. Legacy finite runs upgrade
+  only on manual resume, retaining the old limit, intervals, elapsed time, usage
+  epochs and blocker history. Reads and installation never upgrade or awaken runs.
+  Command/review timeouts, provider quotas and no-progress/stop
+  controls remain independent and effective. Explicit --time-budget is rejected.
   Missing counters remain UNKNOWN; partial usage is not a complete cost estimate.
 - Questions pause work and require an explicit answer. Repair preserves the goal
   and records failures; two identical rounds without progress stop that worker
@@ -38,17 +42,47 @@
   setup requires explicit resume and retains its checkout and failure artifact.
 - A coordinator may assess additional fixed non-dangerous capabilities only under
   a run-scoped policy bound to the original repository trust, executable runtime
-  and remaining budget. Explicit native or organization denial cannot be bypassed.
+  and a finite one-hour authorization window. Explicit native or organization denial cannot be bypassed.
   Policy changes fence all writers, preserve frozen deliveries and journal contract
   synchronization before new generations acquire leases. This never grants global
   repository trust. Native decisions retain redacted command scope and rationale;
   absent provider evidence remains UNKNOWN.
-  Explicit resume renews expired authorization from the remaining budget and
-  reconciles immutable renewal lineage before policy synchronization. An answer
-  uses the same recovery checks; neither action can revive an explicit denial.
+  Active execution automatically renews an expired grant only when the original
+  repository trust, config, executable runtime and operation scope still match.
+  Renewal is digest-bound to its predecessor, preserves assessments, rejects
+  invalid/backward clocks, and loses to concurrent stop, denial or scope changes.
+  Changed/revoked authority requires genuine authorization through the existing
+  trust/resume process; renewal never grants permanent trust or clears denial.
+  Explicit resume reconciles immutable renewal lineage before policy synchronization.
+  An answer uses the same recovery checks; neither action can revive an explicit denial.
+  `run resume <id> --retry-approval <auth-event-id>` MAY explicitly retry a
+  Codex automatic approval review that failed with its usage-limit wrapper.
+  Each selected failure MUST retain its original private artifact, digest,
+  worker identity and policy lineage; unrelated or genuine denials still block.
+  Repeat the flag for multiple failures. Successful acknowledgements are audited
+  and revalidated on later resumes. This grants no command permission: native
+  approval runs again. Existing writer-death, checkout, trust and budget checks apply.
+  Initial recovery after a current manual resume MAY ignore an owned Codex limit
+  snapshot received before activation whose native update second strictly predates
+  that resume. Automatic restarts, unknown/equal/future timestamps, clock rollback,
+  and every limit received after activation starts remain authoritative. Native
+  activation MUST acknowledge an active goal before starting or steering a turn.
+  Manual resume releases derivative `RUN_POLICY_DISABLED` task blocks while
+  preserving IDs, accounting, history and unrelated product failures.
 - Convergence compares actual per-check statuses and outstanding finding pins.
   Source fingerprints, timing and diagnostics alone cannot establish progress.
 
+For any `jobs` value, the coordinator MUST yield only through an explicit
+`action=wait` request sent after it has planned its children; the supervisor
+never stops a coordinator that is still planning. A wait confirms coordinator
+process death, frees its slot and drops its native thread, so the coordinator does
+not poll `run status` while children work. Recovery leaves a waiting coordinator
+stopped; once every child is delivered, complete or blocked, it restarts under a
+new generation in a fresh native session whose instructions list each child's
+status and delivered commit. With `jobs=1`, child execution MUST wait for that
+confirmed death. Native registration, recovery and start MUST enforce at most
+`jobs` active agents; changing task slot accounting alone is insufficient.
+
 This module defines the bounded loop used to plan, implement, verify, and hand off work.
 
 ## LOOP-START-001

package/docs/en/spec/review.md

@@ -10,6 +10,8 @@ An independent reviewer MUST receive a minimal packet containing the request, cr
 - Positive: `Packet contains recorded task intent, criteria, files, and evidence requirements.`
 - Negative: `Forward the complete session transcript and environment.`
 
+Large surface audits, including complete revision history, discovery and post-block exclusions, may use a digest-bound reference to an exact normalized match in the validated snapshot contract manifest. Both review rounds must read the complete manifest surface. The 64 KiB inline packet and 512 KiB manifest bounds remain enforced; small and legacy packets retain inline data.
+
 ## REVIEW-RESULT-001
 
 A review result MUST preserve PASS, FAIL, or NOT_RUN and MUST NOT convert NOT_RUN into PASS.
@@ -57,6 +59,10 @@ Raw reviewer output remains bounded and unstreamed. SIGINT or SIGTERM aborts
 the active process tree without fallback or attestation; timeout remains a
 distinct NOT_RUN reason rather than being flattened to `missing-cli`.
 
+agy may remain silent throughout a generation. Its review and resumed answer
+MUST NOT be cancelled solely for missing output; the configured round timeout
+and caller cancellation remain effective.
+
 ## REVIEW-CHAIN-001
 
 The two planned sessions MUST be ordered as a necessary review followed by an

package/docs/zh-TW/guides/configuration.md

@@ -236,7 +236,7 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   詢問一次。
 - 在 worktree 裡對每個 task 執行 verify 與 review，但不要執行 `task complete`
   （Claude Code 在隔離的 worktree session 中會拒絕它）。`agent-ops worktree finish
-  <name>` 會在任何 rebase 之前 complete worktree 內每個未封存的 task，先 subtask
+  <name>` 會在合併之前 complete worktree 內每個未封存的 task，先 subtask
   後 parent，各自使用其 PASS review 記錄的 base（沒有記錄時使用 worktree 的 base）。
   任一 task 無法完成時不會合併，錯誤訊息會指出是哪個 task。建立 subtask 時 session
   維持附著在 task 樹最上層，且每個 task 各自保留 review 紀錄，所以在同一份原始碼上
@@ -254,8 +254,11 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
   finish。主 checkout 就在 target branch 上時，合併會更新它的檔案，所以那裡有未
   commit 的變更會擋住合併；主 checkout 在其他 branch 或 detached 時，只移動
   target 的 ref，checkout、檔案與未 commit 的變更都不會被動到。Target 若被其他
-  worktree checkout 則拒絕，並指出該路徑。Target 若已前進會先 rebase；沒有衝突且自身 patch 不變的 rebase 會先
-  重新驗證再合併；衝突則連同先合併那份工作在 `refs/notes/agent-ops` 的意圖一起
+  worktree checkout 則拒絕，並指出該路徑。Target 若已前進，會 rebase worktree 後以
+  `WORKTREE_REBASED` 停下，不 complete 任何 task：先前的證據涵蓋的是舊 base，
+  不是即將合併的組合。以印出的 `--base` 重新 verify 與 review，再執行一次 finish；
+  已 complete 的 task 不能再記錄證據，需以 follow-up task 涵蓋 rebase 後的變更。
+  衝突則重設並連同先合併那份工作在 `refs/notes/agent-ops` 的意圖一起
   回報。Note 會記錄 worktree 的每個 task，subtask 縮排在其 parent 之下，並附上
   一行 `session: <id>`，標明完成這次 finish 的 session。Finish 也會把該 session
   的 gate baseline 重設為合併後的原始碼，所以即使 task 現在只存在於 note 裡，