@open-agent-toolkit/cli 0.1.66 → 0.1.72

package/assets/agents/oat-reviewer.md

@@ -400,7 +400,6 @@ Run these to verify the implementation:
 ## Recommended Next Step
 
 Run the `oat-project-review-receive` skill to convert findings into plan tasks.
-
 ````
 
 ```

package/assets/docs/cli-utilities/configuration.md

@@ -87,6 +87,7 @@ Common keys in `.oat/config.json`:
 - `archive.awsRegion` — optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows
 - `tools.<pack>` — whether a bundled tool pack is currently installed in the repo or user scopes after lifecycle reconciliation
 - `workflow.gates.skills` / `workflow.gates.execTargets` — per-skill gates and cross-runtime exec targets; manage with `oat gate`
+- `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` — default review budgets in milliseconds
 
 Tool-pack state example:
 
@@ -101,6 +102,31 @@ Workflow gate objects are structured config and use their own command group
 instead of the scalar `oat config set` surface. See
 [Workflow Gates](workflow-gates.md) for the full command surface and examples.
 
+Gate budgets resolve per run in this order: CLI `--timeout-ms`, selected
+target `timeoutMs`, `workflow.gateTimeouts` by review type,
+`OAT_GATE_EXEC_TIMEOUT_MS`, then the built-in type-and-scope default. Values
+must be integer milliseconds from `1,000` through `14,400,000`.
+
+```json
+{
+  "workflow": {
+    "gateTimeouts": {
+      "code": 2400000,
+      "artifact": 900000
+    },
+    "gates": {
+      "execTargets": {
+        "cursor-large-review": {
+          "runtime": "cursor",
+          "baseCommand": ["cursor-agent", "-p", "--force"],
+          "timeoutMs": 3600000
+        }
+      }
+    }
+  }
+}
+```
+
 Archive example:
 
 ```bash
@@ -467,6 +493,7 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.dispatchCeiling.providers.<provider>.<tier>` — one matrix cell for `economy`, `balanced`, `high`, or `frontier`.
 - `workflow.dispatchCeiling.recommendationVersion` — version of the adopted recommended matrix.
 - `workflow.gates.skills` / `workflow.gates.execTargets` — structured per-skill final gate commands and exec-target registry. Use `oat gate set`, `oat gate target set`, `oat gate review`, and `oat gate cross-provider-exec`; do not use `oat config set` for these objects.
+- `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` — validated default gate-review budgets in milliseconds. Both resolve through `local > shared > user`.
 
 ### HiLL plan-field semantics
 

package/assets/docs/cli-utilities/index.md

@@ -16,7 +16,7 @@ Use this section when you want bootstrap guidance, tool-pack lifecycle details,
 - [Configuration](configuration.md) - OAT configuration guidance across shared, local, user, and provider-sync surfaces.
 - [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
 - [Backlog Lifecycle](backlog-lifecycle.md) - Backlog item states, atomic close-out with `oat backlog archive`, and lifecycle drift detection in `oat pjm doctor`.
-- [Workflow Gates](workflow-gates.md) - Per-skill final commands and cross-runtime review dispatch with `oat gate`.
+- [Workflow Gates](workflow-gates.md) - Completion-safe headless reviews, budgets, liveness evidence, and cross-runtime dispatch with `oat gate`.
 
 ## What Lives Here
 

package/assets/docs/cli-utilities/workflow-gates.md

@@ -94,6 +94,51 @@ model that ran, and the reviewer must not replace them with self-identification.
 The CLI compares the copied values with its gate-owned record before it applies
 the severity threshold.
 
+### Headless completion safety
+
+Every `oat gate review` child receives the same headless contract through two
+channels:
+
+- environment: `OAT_GATE_HEADLESS=1`, `OAT_NON_INTERACTIVE=1`,
+  `OAT_GATE_RUN_ID=<runId>`, immutable `OAT_GATE_RUNTIME` and
+  `OAT_INVOCATION_MODEL` values, and checkout-local CLI/receipt paths
+- prompt frontmatter: `oat_gate_headless: true` plus the target runtime and
+  model
+
+In headless mode, `oat-project-review-provide` calls the executable routing
+helper instead of deciding from prose:
+
+```bash
+"$OAT_GATE_CLI_PATH" gate route \
+  --expect-runtime "$OAT_GATE_RUNTIME" \
+  --expect-model "$OAT_INVOCATION_MODEL" \
+  --can-await true \
+  --json
+```
+
+The helper returns `inline`, `delegate-sync`, or `refuse`. Inline review is
+allowed when a provider marker for the expected/current child runtime is
+present and trustworthy model evidence does not contradict the expected model.
+That current-target marker takes precedence over inherited parent-provider
+markers. Generic model variables and model variables belonging to other
+providers are ignored because they may be inherited from the parent;
+current-provider model evidence remains fail-closed. A missing current-target
+marker or trustworthy contradiction delegates only through an awaited child
+route. If no awaited route exists, the reviewer emits
+`OAT_GATE_REFUSAL: <reason>` on its own line and fails closed. Headless review
+never uses fire-and-forget background dispatch.
+
+The route command must use the gate-provided checkout-local CLI; it must not
+retry through bare or installed `oat`. The helper writes
+`OAT_GATE_ROUTE_RECEIPT_PATH`, and the parent accepts it only when the JSON
+decision shape is valid, `cliRoot` equals the checkout that launched the gate,
+and `runtime` equals the selected invocation runtime. Missing, malformed,
+cross-checkout, or runtime-mismatched receipts fail closed.
+
+The gate recognizes refusal lines independently of the child exit code. A
+validated run-correlated artifact still wins; without one, the envelope has
+`status: review_failed`, includes `refusal`, and is not receive-eligible.
+
 ### Gate dispatch report semantics
 
 When gate dispatch is represented in a `DispatchReportV1`, consumers require
@@ -520,11 +565,108 @@ Gate failure behavior is owned by the gate-aware skill:
 available target. Once a target actually runs, its exit code is the gate result;
 OAT does not try another target after a failed review.
 
-Gate target execution has a child-process timeout (default 15 minutes, override
-with `OAT_GATE_EXEC_TIMEOUT_MS`). When a review target times out, JSON output
-reports `status: review_failed`, `outcome: review_did_not_complete`,
-`timedOut: true`, and the timeout value so automation can distinguish a hung
-provider prompt from a completed review with findings.
+Gate target execution has a child-process timeout. Set
+the budget at the narrowest useful level. The first valid value wins:
+
+1. command `--timeout-ms`
+2. selected exec target `timeoutMs`
+3. `workflow.gateTimeouts.code` or `workflow.gateTimeouts.artifact`
+4. `OAT_GATE_EXEC_TIMEOUT_MS`
+5. built-in type-and-scope default
+6. legacy `GATE_EXEC_TIMEOUT_MS` behavior for untyped `gate exec` runs
+
+All configured values must be integer milliseconds from `1,000` through
+`14,400,000`. Invalid persisted values are ignored with a warning and
+resolution continues to the next source. Code reviews at `final`, phase
+(`pNN`), or phase-range (`pNN-pMM`) scope default to 1,800,000 ms (30 minutes).
+Task-scoped code reviews (`pNN-tNN`) and artifact reviews default to 900,000 ms
+(15 minutes). Startup output reports both the resolved value and source.
+
+Example migration from the former single environment override:
+
+```json
+{
+  "workflow": {
+    "gateTimeouts": {
+      "code": 2400000,
+      "artifact": 900000
+    },
+    "gates": {
+      "execTargets": {
+        "cursor-large-review": {
+          "runtime": "cursor",
+          "baseCommand": ["cursor-agent", "-p", "--force"],
+          "timeoutMs": 3600000
+        }
+      }
+    }
+  }
+}
+```
+
+Use a one-off override without changing config:
+
+```bash
+oat gate review --timeout-ms 2700000 \
+  --project "$PROJECT_PATH" \
+  --review-type code \
+  --review-scope final \
+  "Use oat-project-review-provide code final for the declared project"
+```
+
+### Liveness and post-mortem evidence
+
+Each liveness tick keeps stdout-idle time and also reports `processAlive` plus
+the latest metadata-only transcript activity as `lastActivityEvidence` when
+available. The probe performs bounded depth-two traversal and compares newest
+mtime plus total size with its spawn baseline. It never reads transcript
+contents, never extends a budget, and never changes pass/fail or receive
+eligibility.
+
+Claude and Cursor evidence has `scope: project-dir`. Codex's date-sharded
+sessions directory is shared across the runtime, so its evidence has
+`scope: ambient-runtime`; human output labels it “ambient runtime activity (not
+attributable to this gate child).” Probe errors fail soft to process and stdout
+telemetry.
+
+Timeout and child-failure envelopes include the latest `activityEvidence`.
+Before spawn, the gate also writes a transient marker under the system temp
+directory at `oat-gate-runs/<runId>.json`; startup diagnostics print its path.
+The marker records target, runtime, project, review type/scope, start time,
+budget, and budget source. It is deleted at terminal completion. An orphaned
+marker indicates the gate parent itself stopped unexpectedly, but markers are
+diagnostic only and are never used for artifact validation.
+
+After a review target times out, OAT re-scans the project reviews for exactly
+one artifact carrying that invocation's `oat_gate_run_id`. A recovered artifact
+still passes through the normal project, timestamp, invocation, normalization,
+threshold, and handoff checks. If those checks produce `status: ok` or
+`status: blocked`, the envelope also includes `lateCompletion: true`. This is
+additive recovery telemetry, not a new status: route review-receive from
+`status`, `receiveEligible`, and `handoff` as usual.
+
+When timeout recovery finds no matching run-ID path and no changed diagnostic
+artifact, JSON output reports `status: review_failed`, `outcome:
+review_did_not_complete`, `timedOut: true`, the timeout value, and
+`noOutputProduced`. That field is `true` only when the timed-out child emitted
+zero stdout and stderr bytes; it is `false` when the child emitted any captured
+output.
+
+Correlation anomalies keep their more specific failure. Multiple artifacts
+carrying the run ID, or a changed artifact carrying a mismatched run ID, return
+`targeting_correlation_failed` with `receiveEligible: false`. Do not receive
+those artifacts; correct the project/run correlation and start a new gate run.
+
+### Incident-to-regression mapping
+
+| Observed failure                                         | Regression coverage                                                                                                    |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Headless reviewer could not complete an async delegation | route unit matrix plus canonical checkout-local command, strict receipt, headless inline, and structured-refusal cases |
+| Large final review exceeded the old 15-minute budget     | scope-aware resolver tests plus scaled final-scope fake-runtime case                                                   |
+| Silent child looked idle while transcripts grew          | metadata-probe tests plus timeout-with-advancing-transcript fixture                                                    |
+| Timeout or child failure produced no artifact            | fail-closed `noOutputProduced` fixture                                                                                 |
+| Artifact carried the wrong gate run ID                   | provenance-mismatch fixture                                                                                            |
+| Passing artifact lost receive routing                    | handoff and `receiveEligible` fixture                                                                                  |
 
 ## Current limits
 

package/assets/docs/reference/cli-reference.md

@@ -68,8 +68,11 @@ Notable commands introduced in the current CLI surface:
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#plan-declared-parallelism).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
-- `oat gate review <prompt...>` - run a stateful OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. For `artifact_validation_failed`, correct the artifact and rerun the gate for successful revalidation before receive. `targeting_correlation_failed` sets `receiveEligible: false`; do not run review-receive even if it reports an artifact path. Orchestrators should read the structured result rather than poll the filesystem. The command runs standalone (for example, `--review-scope final`), not only inside `oat-project-implement`. See [Workflow Gates → Gate completion signal](../cli-utilities/workflow-gates.md#gate-completion-signal).
+- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. For `targeting_correlation_failed`, do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).
+- `oat gate route --expect-runtime <runtime> --expect-model <model> --can-await <true|false> --json` - return the headless child route (`inline`, `delegate-sync`, or `refuse`) from provider-marker and model evidence. Ambiguous or contradictory evidence never routes inline.
+- `oat gate exec <prompt...>` / `oat gate cross-provider-exec <prompt...>` - run a generic target prompt. `--timeout-ms` uses the same validated CLI override; untyped runs otherwise retain the legacy default path.
 - `oat gate target set <id> --invocation-model <model|provider-default> --invocation-reasoning-effort <effort|provider-default>` - persist optional configured invocation metadata alongside an exec target without inferring it from the target command.
+- `oat gate target set <id> --timeout-ms <milliseconds>` - persist a validated per-target gate budget.
 - `oat gate target list --json` - inspect resolved gate targets without selecting or executing a reviewer. Each entry reports its config origin, whether it is explicitly configured and enabled, current availability, and normalized configured invocation values (`unknown` when omitted).
 - `oat gate cross-provider-exec <prompt...>` - choose an available exec target while avoiding the current runtime by default, then run the prompt with the chosen target's configured base command and exit with the child status.
 
@@ -98,5 +101,6 @@ The `workflow.*` namespace holds user-facing workflow preferences that let you a
 - `workflow.autoNarrowReReviewScope` (`boolean`) — auto-narrow re-review scope to fix-task commits
 - `workflow.autoArtifactReview.plan` (`boolean`, default `true`) — auto-run the bounded `plan.md` artifact-review loop before implementation handoff
 - `workflow.autoArtifactReview.analysis` (`boolean`, default `true`) — auto-run the bounded accuracy-review loop for generated analysis artifacts before apply workflows consume them
+- `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` (integer milliseconds from 1,000–14,400,000) — review-type budget defaults below CLI and target overrides
 
 These workflow keys resolve through config files and defaults (`local > shared > user > default`). Some config keys have explicit environment aliases, but `workflow.autoArtifactReview.plan` and `workflow.autoArtifactReview.analysis` do not. See [Workflow preferences in the Configuration guide](../cli-utilities/configuration.md#workflow-preferences-workflow) for full descriptions, surface guidance, and cross-repo foot-gun examples.

package/assets/docs/workflows/projects/dispatch-ceiling.md

@@ -71,11 +71,20 @@ when the current project has not selected a policy or named ceiling. Adoption
 is offered only when the resolved provider/tier cells are actually missing,
 empty, malformed, or incomplete.
 
-Ladder completeness and project-ceiling selection are separate checks. In
-particular, `oat project dispatch-ceiling resolve` returning `matrix: null` can
-mean that the project policy or ceiling is unresolved; it does not prove that
-the effective reusable ladders are absent. When ladders are complete, planning
-proceeds directly to the project-specific policy choice.
+Ladder completeness and project-policy selection are separate checks.
+`oat project dispatch-ceiling resolve --json` reports both:
+
+- `unresolvedReason: policy | ladder | both` identifies which side is missing;
+- `ladderCompleteness.complete` evaluates every supported provider/tier cell;
+  and
+- `ladderCompleteness.missingCells` identifies the exact cells adoption would
+  fill.
+
+The resolver preserves the merged effective `matrix` when only policy is
+missing, so a missing project policy no longer looks like a missing reusable
+ladder. Planning offers matrix adoption only for `ladder` or `both`, or when
+`ladderCompleteness.complete` is false. With a complete ladder and only policy
+unresolved, it proceeds directly to the project-specific policy choice.
 
 The ownership boundary is deliberate:
 
@@ -253,9 +262,17 @@ ambiguous route, malformed ordering, a reviewer candidate request, or controls
 that cannot compile exactly. The root blocks instead of reusing its own target,
 a base role, or a provider default.
 
-`--preferred` remains available for legacy scalar ceilings and managed
-`Uncapped` compatibility. It is not the exact managed phase-agent selection
-path.
+Implementer and fix resolution has two mutually exclusive selection branches:
+
+- **Preferred selection:** pass `--preferred` for legacy scalar ceilings or
+  managed `Uncapped` compatibility. Do not include `--candidate-model` or
+  `--candidate-effort`.
+- **Exact-candidate selection:** pass `--candidate-model` and, where applicable,
+  `--candidate-effort` for a managed capped phase or fix. Do not include
+  `--preferred`.
+
+Never combine the branches in one resolver invocation. The exact-candidate
+branch replaces, rather than supplements, preferred selection.
 
 ## Provider Enforcement
 

package/assets/docs/workflows/projects/orchestration-model.md

@@ -127,6 +127,27 @@ phase ownership and task commit authority.
 Do not use nested dispatch merely to mirror task granularity. The smoke fixture
 intentionally proves successful execution with no task workers.
 
+## Dispatch Mode and Liveness
+
+Choose foreground or background mode from expected duration and the host
+interaction model. Short checks may run in foreground when interruption risk is
+negligible. Multi-minute implementers, fix loops, and reviewers should use a
+durable background handle when the host supports one, because ordinary session
+interaction can interrupt a foreground child in Cursor.
+
+Background is never fire-and-forget: retain the accepted handle, monitor useful
+progress, and resume that same handle for bounded fixes. For a silent child,
+provider transcript mtime and size can show observable activity without reading
+transcript content; that evidence is liveness telemetry, not a health or
+completion verdict.
+
+Claude print mode (`claude -p`) has a separate hazard: background children are
+terminated at its background-wait ceiling (600 seconds by default). Interactive
+Claude Code is unaffected. Headless gate children therefore do not follow the
+ordinary background preference; they use the gate's inline or synchronously
+awaited route and fail closed when neither is available. See
+[Workflow Gates](../../cli-utilities/workflow-gates.md#headless-completion-safety).
+
 ## Catalogs and Exact Selection
 
 Native model catalogs are per-dispatch-context snapshots. A root catalog does

package/assets/docs/workflows/projects/pr-flow.md

@@ -46,7 +46,18 @@ After `oat-project-pr-final` creates the PR, `state.md` transitions to `oat_phas
 From `pr_open`:
 
 - **Feedback received:** run `oat-project-revise` to create revision tasks and re-enter implementation
-- **Approved:** run `oat-project-complete` to finalize and archive the project. If `oat_pr_status: open` is already tracked, completion skips asking whether to open a PR again and can show the tracked `oat_pr_url` in its summary.
+- **Ready for completion:** run `oat-project-complete` to finalize and archive the project. If `oat_pr_status: open` is already tracked, completion skips asking whether to open a PR again and can show the tracked `oat_pr_url` in its summary.
+
+Both completion orderings are supported:
+
+- **Complete before merge:** run `oat-project-complete` while the PR is open,
+  then merge.
+- **Merge before completion:** merge the PR first, then run
+  `oat-project-complete`.
+
+An open PR is not a completion blocker. When completion archives project
+artifacts, the archive-aware flow regenerates and synchronizes the open PR body
+so its artifact links remain valid.
 
 ## Reference artifacts
 

package/assets/docs/workflows/projects/review-flavors.md

@@ -76,6 +76,15 @@ external, configured, producer-independent target. Phase implementation may run
 _below_ the review ceiling for cost reasons, but review must never silently
 inherit the below-ceiling phase agent.
 
+Pre-plan inheritance has a narrow executable guard. When dispatch resolution
+reports `unresolvedReason: policy`, an artifact review of `discovery`, `design`,
+or `spec` deliberately inherits the current planning context and records
+`selection_reason: inherit (pre-plan; no project policy)`. An explicit project
+policy is still honored at those scopes. Missing or incomplete ladders
+(`unresolvedReason: ladder | both`) fail closed, as do plan-scope artifact
+reviews and every code review without a resolved policy. Gate exec-target
+selection is separate and unaffected.
+
 ## Independence and fail-closed semantics
 
 The invariant across all four flavors is that the reviewer runs **at or above

package/assets/docs/workflows/projects/reviews.md

@@ -26,9 +26,12 @@ Use `oat review latest` when a skill or operator needs to resolve "the most rece
 ```bash
 oat review latest --json
 oat review latest --project .oat/projects/shared/example --json
+oat review latest --project .oat/projects/shared/example --actionable-project --json
 ```
 
-The resolver orders candidates by `oat_generated_at` frontmatter, not filesystem mtime. With an active or explicit project, it scans the project's `reviews/` directory first, then `reviews/archived/`, then ad-hoc review locations (`.oat/repo/reviews/` and `.oat/projects/local/orphan-reviews/`). When candidates share the same generated time, active project reviews outrank archived and ad-hoc reviews, then lifecycle recency breaks remaining ties (`final` > higher phase/task scope > lower phase/task scope). The JSON response contains `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`. Archived project reviews remain discoverable as history but return `actionable: false`; active top-level project reviews return `actionable: true`. If no review exists, those fields are `null`.
+The default resolver is an all-history lookup. It orders candidates by `oat_generated_at` frontmatter, not filesystem mtime. With an active or explicit project, it scans the project's `reviews/` directory first, then `reviews/archived/`, then ad-hoc review locations (`.oat/repo/reviews/` and `.oat/projects/local/orphan-reviews/`). When candidates share the same generated time, active project reviews outrank archived and ad-hoc reviews, then lifecycle recency breaks remaining ties (`final` > higher phase/task scope > lower phase/task scope).
+
+Use `--actionable-project` when project review-receive needs work waiting for disposition. A top-level artifact is actionable only when its scope, type, and artifact path identify a `received` event in the plan's Reviews ledger. Top-level placement alone is insufficient: passed, `fixes_added`, `fixes_completed`, mismatched, and archived events return `actionable: false`. The JSON response contains `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`. If no matching review exists, those fields are `null`.
 
 `oat-project-review-receive` uses this resolver when it is invoked from natural language and needs to offer the latest project review, or route an ad-hoc result to `oat-review-receive`.
 
@@ -89,6 +92,23 @@ Status progression in `plan.md` Reviews table:
 - `fixes_completed`
 - `passed`
 
+Each row is an append-ordered review event. Duplicate scope and type rows are
+valid because separate reviews can cover the same subject. Scope, type, and the
+artifact filename identify an event:
+
+- The first event for a scope and type may claim an unbound `pending` row whose
+  artifact is `-`.
+- A review with a distinct artifact filename appends a new row instead of
+  overwriting an earlier bound event.
+- Later bookkeeping updates match the event by scope, type, and artifact
+  filename. Moving an artifact into `reviews/archived/` preserves that identity.
+- An event advances through the status progression monotonically and never
+  moves backward. A later event can begin at `received` without changing an
+  earlier event that already reached `passed`.
+
+Readers that need current lifecycle state use the latest appended event matching
+the relevant scope and type.
+
 ## Current policy
 
 - Critical/Important: address before pass.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.66",
-  "docs-config": "0.1.66",
-  "docs-theme": "0.1.66",
-  "docs-transforms": "0.1.66"
+  "cli": "0.1.72",
+  "docs-config": "0.1.72",
+  "docs-theme": "0.1.72",
+  "docs-transforms": "0.1.72"
 }

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-dispatch-subagents
-version: 1.1.2
+version: 1.1.3
 description: Use when an OAT skill or workflow needs provider-neutral selection, launch, recovery, or evidence for bounded subagent work without project lifecycle policy.
 disable-model-invocation: true
 user-invocable: false
@@ -145,6 +145,26 @@ Keep these controls independent in selection and evidence:
 A materialized role may package defaults, but its record must preserve each
 configured axis separately.
 
+## Deliberate Dispatch Mode
+
+Choose foreground or background deliberately from expected duration and the
+host interaction model. Multi-minute implementers, fix loops, and reviewers
+must survive ordinary session interaction and therefore run in background when
+the host supports a durable awaited handle. Reserve foreground dispatch for
+short checks whose interruption risk is negligible. Record the selected mode
+and reason with the launch payload.
+
+Background does not mean fire-and-forget. Retain and await the accepted handle,
+apply the Acceptance and Recovery contract below, and surface useful progress.
+In headless gate contexts, fire-and-forget background dispatch is forbidden:
+use the gate's inline or synchronously awaited route contract instead.
+
+For a silent background child, provider transcript filesystem metadata at the
+documented runtime path can provide observable liveness evidence. Check only
+metadata such as mtime and size. This evidence shows observable activity; it
+is never a health verdict and never authorizes replacement, timeout extension,
+or a second launch.
+
 ## Baseline Role Classes
 
 Specific role names are extensible, but map every dispatch to one class:

package/assets/skills/oat-dispatch-subagents/references/provider-claude.md

@@ -42,3 +42,24 @@ satisfy a universal catalog rule.
 
 Verify current `claude --help` before using a CLI route. Preserve the caller's
 authority and construct a self-contained bounded prompt.
+
+## Dispatch Mode and Liveness
+
+The background-wait ceiling hazard applies only to Claude print mode
+(`claude -p`). Print-mode background children are terminated after
+`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` (600 seconds by default). Interactive
+Claude Code sessions are unaffected. Print mode is reachable in autonomous
+and headless invocations outside gates as well as through gate exec targets, so
+do not choose an unawaitable background route there. In gate contexts, defer to
+the headless inline/synchronously-awaited route contract rather than
+duplicating its decision.
+
+Nested Claude subagent transcripts live below the parent session:
+
+```text
+~/.claude/projects/<encoded-cwd>/<parent-session-id>/subagents/agent-<id>.jsonl
+```
+
+For a silent awaited child, use that specific file's mtime and size as
+observable activity evidence only. Metadata change is not a health verdict and
+does not alter acceptance or recovery policy.

package/assets/skills/oat-dispatch-subagents/references/provider-codex.md

@@ -49,6 +49,22 @@ Only an actual role-selection rejection before child start permits another
 recorded route. Timeout, interruption, `BLOCKED`, or task failure after
 acceptance does not.
 
+## Child Transcript Liveness
+
+Each native Codex subagent gets a separate rollout:
+
+```text
+~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<start-timestamp>-<child-thread-id>.jsonl
+```
+
+The child's `session_meta` carries `parent_thread_id`; the root rollout carries
+the corresponding dispatch, steering, and result records. Because the
+dispatcher knows the child thread ID at launch, resolve the child's own rollout
+and inspect only its filesystem mtime and size for observable liveness
+evidence. Rollouts shard by session start date: a fresh child of a long-lived
+root can be in a different date directory, so resolve from the child's spawn
+date, never the parent's. Metadata change is not a health verdict.
+
 ## CLI Route
 
 When native dispatch cannot express the complete target and the route is

package/assets/skills/oat-dispatch-subagents/references/provider-cursor.md

@@ -29,6 +29,27 @@ Do not infer Cursor IDE behavior from a headless CLI surface. Keep bounded
 recon on economical explicit targets and reserve stronger targets for
 context-heavy or consequential work.
 
+## Dispatch Mode and Liveness
+
+In an interactive Cursor session, a user message can interrupt a foreground
+subagent turn. Run multi-minute implementers, fix loops, and reviewers in
+background when the host provides a durable awaited handle; reserve foreground
+for short checks. This background preference does not apply to headless gate
+children, which must follow the inline/synchronously-awaited gate route
+contract and never fire-and-forget.
+
+The dispatch-returned agent ID directly addresses that background child's
+transcript:
+
+```text
+~/.cursor/projects/<encoded-cwd>/agent-transcripts/<agentId>/<agentId>.jsonl
+```
+
+This is a sibling of the main thread's transcript directory. For silent-child
+liveness, stat that specific file's mtime and size rather than inferring from a
+directory. Metadata change is observable activity evidence, not a health
+verdict.
+
 ## Pre-Start CLI Routes
 
 When the current native intersection is absent or unsatisfactory, a caller may

package/assets/skills/oat-project-autonomous/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-autonomous
-version: 1.0.1
+version: 1.0.3
 description: Use when a user explicitly asks to run an OAT project autonomously end-to-end. Activates session-only autonomy, resumes the correct lifecycle phase, and drives the existing OAT skills through final PR or a reported boundary.
 argument-hint: '<goal | project-slug | ticket-ref>'
 disable-model-invocation: true