@open-agent-toolkit/cli 0.2.50 → 0.2.52

package/assets/docs/reference/file-locations.md

@@ -92,8 +92,10 @@ Config ownership note:
 - Synced checkout: `.oat/projects/synced/<project>/` (gitignored nested
   worktree)
 - Synced record: `.oat/projects/synced/<project>.json` (tracked on the parent
-  branch)
-- Synced ref: `refs/oat/projects/<project>` on `origin`
+  branch while the project is active; removed after durable archived closeout)
+- Active synced ref: `refs/oat/projects/<project>` on `origin`
+- Completed synced ref: `refs/oat/completed/<project>` on `origin` (the
+  authoritative terminal reachability root after archive)
 - Local: `.oat/projects/local/<project>/`
 - Archived: `.oat/projects/archived/<project>/`
 
@@ -108,6 +110,10 @@ Archive sync surfaces:
 - Remote archive base: `archive.s3Uri` in `.oat/config.json`
 - Archive sync command: `oat repo archive sync` or `oat repo archive sync <project-name>`
 - Remote archive snapshot shape: `<archive.s3Uri>/<repo-slug>/projects/YYYYMMDD-<project-name>/`
+- Terminal archive metadata:
+  `.oat/projects/archived/<project>/.oat-archive-source.json` binds the
+  snapshot to its synced source-ref SHA so a recordless interrupted closeout
+  can retry without recreating the active record or checkout.
 - Summary export target:
   `<repo>/<archive.summaryExportPath>/YYYYMMDD-<project-name>.md` when
   configured. The archive report returns this absolute filesystem path, while

package/assets/docs/reference/oat-directory-structure.md

@@ -58,14 +58,21 @@ Project scope is used for project workflows and repo-local sync state. User scop
 
 ## `.oat/sync/` details
 
-| Path                      | Purpose                                                           |
-| ------------------------- | ----------------------------------------------------------------- |
-| `.oat/sync/manifest.json` | Records sync-managed provider entries and drift contract state    |
-| `.oat/sync/config.json`   | Project sync behavior, provider settings, and known-stray choices |
+| Path                      | Purpose                                                             |
+| ------------------------- | ------------------------------------------------------------------- |
+| `.oat/sync/manifest.json` | Records sync-managed entries, collection ownership, and drift state |
+| `.oat/sync/config.json`   | Project sync behavior, provider settings, and known-stray choices   |
 
 The equivalent user files are `~/.oat/sync/manifest.json` and
 `~/.oat/sync/config.json`.
 
+Manifest version 2 stores `collections` alongside per-entry evidence. Each
+collection record uses scope-relative canonical/provider paths and records
+whether OAT created the exact alias or adopted an existing one. Its inherited
+entries refer back to that collection; the manifest never authorizes deletion
+through the alias target. Writes are atomic, and unchanged manifests from the
+older per-entry schema normalize in memory before the next successful sync.
+
 `config.json` currently includes:
 
 - `version`
@@ -181,7 +188,8 @@ Each OAT project lives under:
 - `.oat/projects/synced/<project>/` for a gitignored nested worktree whose
   history is published to `refs/oat/projects/<project>`
 - `.oat/projects/synced/<project>.json` for the tracked discovery record that
-  identifies the ref, remote, and active or complete status
+  identifies the ref, remote, and active transaction state; archived closeout
+  deletes this record after terminal durability is verified
 - `.oat/projects/local/<project>/`
 - `.oat/projects/archived/<project>/`
 
@@ -189,16 +197,24 @@ Completion and archive sync behavior:
 
 - When archiving is selected, `oat-project-complete` archives locally into
   `.oat/projects/archived/<project>/`. For a synced project, the snapshot omits
-  the nested checkout's `.git` pointer and `reviews/`, then completion marks
-  the tracked record complete, removes the nested worktree, and retains the
-  project ref so pinned links keep resolving.
+  the nested checkout's `.git` pointer and `reviews/`. After required local and
+  configured S3 durability succeeds, completion makes
+  `refs/oat/completed/<project>` authoritative, removes the nested worktree,
+  and deletes the tracked JSON record. Full-SHA links remain reachable through
+  the completed ref.
+- Both a completed-only ref and completed plus same-SHA active alias are valid
+  terminal shapes. The alias is inert and ignored by list, pull, and open;
+  differing SHAs are a hard mismatch with explicit recovery guidance.
 - When archiving is disabled or declined, completion leaves the synced
   checkout and ref in place, pushes the finalized artifacts, and exact-path
   commits the tracked record as complete.
-- If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, completion also uploads a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
+- If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, completion must successfully upload a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/` before it retires the active record and checkout.
 - `oat repo archive sync` syncs all repo archived projects down from S3 into `.oat/projects/archived/`.
 - `oat repo archive sync <project-name>` syncs the latest dated remote snapshot for a single project into `.oat/projects/archived/<project-name>/`.
 - Default archive sync is non-destructive toward unrelated local-only archive data, but it does replace a local project archive when a newer dated remote snapshot is selected for that same project.
+- `oat project prune` is separate and destructive: for a terminal project it
+  removes the completed ref and any matching active alias, while leaving local
+  and S3 archive snapshots intact. A ref mismatch blocks deletion.
 
 Typical contents:
 

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

@@ -28,10 +28,15 @@ rebases it on the fetched project ref, and pushes only that ref. Arrival skills
 run `oat project pull` before reading artifacts so a record or remote ref can
 materialize the checkout first.
 
-The tracked JSON record is routing metadata, not a copy of the project. It
-identifies the slug, `origin`, ref, status, and archive snapshot when present.
-The project ref remains the source of truth for active artifact content and
-history.
+The tracked JSON record is active routing metadata, not a copy of the project.
+It identifies the slug, `origin`, active ref, and status. The active project ref
+remains the source of truth for active artifact content and history.
+
+Archived closeout transitions terminal identity to
+`refs/oat/completed/<project>`, deletes the active record and checkout, and
+persists source-ref identity in local archive metadata. Arrival and pull flows
+never rematerialize a completed project as active state: the completed ref and
+archive metadata own terminal reachability and retry identity.
 
 ## Core artifacts
 

package/assets/docs/workflows/projects/evidence-layers.md

@@ -63,7 +63,7 @@ launched**, and it records:
   `gate-target` (adapters may add a more specific diagnostic but never replace
   or rename these);
 - the ordered `candidates_considered` before launch (never sorted);
-- launch acceptance status (`accepted` or `pre-start-rejected`) and mechanism.
+- launch acceptance status (`accepted` or `blocked-before-start`) and mechanism.
 
 Because the launcher constructs the invocation payload itself, this layer does
 not depend on any child cooperation. A launch is judged consistent only when its
@@ -75,6 +75,20 @@ This layer maps to Dispatch Report V1 and its provenance record; see the
 [Dispatch Report V1 / producer provenance](dispatch-ceiling.md#dispatch-report-v1-and-producer-provenance)
 section.
 
+For project-aware work, OAT persists this native dispatch lineage as one
+generic record per request under the project's `dispatch/` directory. The
+generic snake-case fields remain authoritative. A namespaced `oat` block adds
+only canonical-role identity, proven pre-start rejection, fallback linkage,
+and optional runtime observation. `DispatchReportV1` and the parseable
+`Dispatch:` compatibility stamp keep their existing byte shape.
+
+The launcher constructs and redacts the complete payload before calling the
+native host, then records the host's accepted or `blocked-before-start` result
+immediately. Only a provider-wrapper attestation proving that no child started
+can authorize one fresh, exact-target fallback record. Timeout, `BLOCKED`,
+refusal after acceptance, runtime mismatch, missing telemetry, and malformed
+output cannot authorize replacement.
+
 ## Layer 3 — Runtime-observed identity (optional corroboration)
 
 Layer 3 is the only layer that reflects what a runtime said about itself, and it
@@ -90,6 +104,95 @@ missing or `not-reported` runtime identity **never invalidates** the
 launcher-owned configured-invocation evidence in Layer 2. Selected model and
 effort axes stay exact even when runtime producer identity is not reported.
 
+### Provider metadata observation
+
+`oat project dispatch record` accepts an optional post-launch observation event
+whose `metadata` is a provider envelope — `provider`, `observedAt`, and
+`entries` — and normalizes it against the record's own immutable configured
+invocation. `entries` may be raw, unmodified provider output. The result is stored under the record's `oat.runtimeObservation`.
+
+The channel is metadata-only and capability-gated:
+
+| Provider | Observed axes                                               | Notes                                                                                                                                               |
+| -------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Codex    | child lineage, role, model, effort                          | Read from `session_meta` and `turn_context` metadata entries. No captured Codex rollout reports a service tier, so that axis never populates today. |
+| Claude   | role, model, effort, service tier; lineage is root-or-child | Read from on-disk `assistant` entry metadata (`attributionAgent`, `effort`, `isSidechain`) plus `message.model` and `message.usage.service_tier`.   |
+| Cursor   | none                                                        | Explicitly `not-reported`; requested values are never copied into it.                                                                               |
+
+Parsers classify entries by their `type` discriminator alone, so a conversation
+entry's body is never read, and only bounded provider identifiers are extracted.
+The Claude parser reads `assistant` entry metadata, which is not the same as
+reading a conversation: it reaches inside `message` by exactly two explicit key
+paths and never spreads, enumerates, or filters that object, so
+`message.content` is never touched rather than being dropped afterwards.
+
+Claude reports lineage only as a binary: `root` for a main session and
+`depth-unknown` for a subagent turn. No depth, nesting, or ancestry field exists
+on any captured assistant entry and `parentUuid` links messages within one agent
+rather than agents to each other, so a depth number is reported unknown rather
+than derived.
+
+The guarantee is the projection, not caller discipline. Provider parsing happens
+entirely inside the provider module, and what comes back is a flat, closed set
+of neutral facts — lineage, role, model, effort, service tier, correlation —
+whose key names are owned by OAT rather than by the provider. That projection,
+never the raw input, is what the sensitive-content boundary inspects and what is
+compared against the configured invocation. `entries` are never persisted in any
+form.
+
+Emitting neutral keys rather than mirroring the provider's own entry shape is
+deliberate. Mirroring a source shape means inheriting its field names, and a
+provider is free to name a field anything: an earlier revision passed the
+provider's shape through and carried `sessionId` and `message` into the output,
+both of which classify as sensitive, which made every real Claude transcript
+unrecordable.
+
+A caller may therefore hand over an unmodified rollout or session log: every
+field outside the fact set, including instruction text, conversation bodies,
+working directories, and repository identity, is dropped before the record
+boundary and is never read in the first place. Requiring pre-sanitized input
+instead would push the stripper into every caller, which is a larger leak
+surface than the one it removes.
+
+Comparison covers only the axes both sides report, and `comparedAxes` records
+exactly which ones. This qualifier is load-bearing: `matching` means "every axis
+in `comparedAxes` agreed", never "the configured invocation was confirmed". An
+observation reporting only a service tier can be `matching` while model, role,
+and effort are all unknown, so read `comparedAxes` — or the `on role+model`
+qualifier in human output — before treating a match as corroboration. With no
+comparable axis the match is `not-comparable`, because silence is not agreement.
+
+An axis a provider genuinely does not expose (`not-exposed`) is excluded rather
+than compared as a literal. That value is reserved for a truly absent axis: an
+axis a provider does report is recorded with its observed value, and an axis it
+simply did not mention on a given run is left unreported. An axis the configured invocation names under two equally
+authoritative spellings — a canonical role name and its materialized native
+selector — matches either.
+
+`match` and `comparedAxes` are always derived at the durable-write boundary from
+the record's own configured invocation. A caller that submits a finished
+observation cannot assert its own verdict, and an observation naming a provider
+the record does not use is refused.
+
+Request correlation is verified only when the provider declares one: a session
+that names a different request is declined, and a session that declares none is
+attributed to the request the caller paired it with. In practice neither
+provider declares an OAT request id today — no captured Codex rollout carries
+`session_meta.request_id`, and Claude's own `requestId` is a per-turn API
+identifier rather than a dispatch request — so correlation is caller-asserted
+for both, and the declared-correlation check is a forward-compatible guard.
+
+A parse failure, a declined request correlation, an unsupported provider, or an
+envelope too large to project all produce `not-reported`. A `runtime-observation`
+event carrying neither `metadata` nor `observation` is a malformed event and is
+rejected by the schema rather than degraded. None of them copies a requested
+argument or a materialized pin into observed state, and `mismatching` is
+evidence only: it authorizes no replacement, retry, or fallback, and leaves
+`launch_status`, `child_outcome`, and every configured control untouched. The
+`--json` result reports `runtimeIdentity.configured` and
+`runtimeIdentity.observed` as separate objects that are never merged into one
+"effective" identity.
+
 ## How the smoke runner consumes these layers
 
 The smoke runner's evidence pipeline reads all three layers and asserts only on
@@ -108,6 +211,12 @@ collection. The collector then flows the evidence through three stages:
    artifacts, carrying `reported` / `not-reported` runtime status without
    letting a missing Layer 3 fail a Layer 2 assertion.
 
+The collector projects `runtimeObservation` the same way: it reads committed
+records and never launches a provider, so an observation appears in a bundle
+only because a launcher-owned record already carried one. A partially filled
+observation normalizes to `not-reported` rather than being completed from any
+other layer.
+
 For how to run this end to end and when to refresh the fixture, see
 [Smoke testing](../../contributing/smoke-testing.md).
 

package/assets/docs/workflows/projects/implementation-execution.md

@@ -32,6 +32,9 @@ and updates project state.
   third tier.
 - **Parallelism:** plan-declared phases may run concurrently in separate
   worktrees. Tasks inside one phase remain serial.
+- **Dispatch evidence:** project-aware launches persist one generic request
+  record plus namespaced OAT native dispatch lineage without changing native
+  model or provider selection.
 
 Tasks execute serially in one worktree for the phase.
 
@@ -69,6 +72,16 @@ The root:
 The root does not implement phase tasks while an accepted phase launch owns
 that scope.
 
+Before a native launch, the root constructs and redacts the complete generic
+dispatch record and OAT role event. Immediately after the host returns, it runs
+`oat project dispatch record --project <project-path> --event-file - --json`
+with the accepted or `blocked-before-start` result. An accepted launch closes
+replacement. Only an explicit rejection proving no child started permits one
+fresh request that preserves the exact target and controls and is labeled as
+an approximation. Timeout, `BLOCKED`, refusal after acceptance, runtime
+mismatch, missing telemetry, and malformed output are terminal evidence, not
+fallback triggers.
+
 ### Phase implementer
 
 The phase implementer receives one `Phase Scope`, reads the relevant artifacts

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

@@ -84,14 +84,26 @@ On completion, OAT treats archive handling as an explicit closeout choice:
 - For a synced project, closeout first finalizes the project artifacts and
   pushes them to `refs/oat/projects/<project>`. Archive then requires a clean,
   fully pushed checkout; copies it without the `.git` pointer or `reviews/`;
-  marks the tracked record complete; commits the record and configured durable
-  exports on the parent branch; removes the nested checkout; and retains the
-  ref. This order keeps SHA-pinned PR links valid after completion.
-- If `.oat/config.json` enables `archive.s3SyncOnComplete` and sets `archive.s3Uri`, completion also attempts an S3 upload for a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
+  seals configured durable exports; transitions terminal reachability to
+  `refs/oat/completed/<project>`; removes the nested checkout; and deletes the
+  tracked JSON record in the parent lifecycle commit. This order keeps
+  SHA-pinned PR links valid without leaving active discovery state behind.
+- A completed-only ref and a completed ref plus same-SHA active alias are both
+  valid terminal shapes. The active alias is inert: list omits it and pull/open
+  reject it. Differing SHAs are a hard mismatch with recovery guidance.
+- If `.oat/config.json` enables `archive.s3SyncOnComplete` and sets `archive.s3Uri`, completion requires the S3 upload of a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/` to succeed before terminal record/ref cleanup. A failed configured upload leaves retry identity intact and does not claim closeout.
 - If `.oat/config.json` sets `archive.awsProfile` and/or `archive.awsRegion`, those values are forwarded to every `aws` invocation triggered by completion (preflight checks + `aws s3 sync`) and override any ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` / `AWS_REGION` / `AWS_DEFAULT_REGION` values. The repo's archive-scoped credentials are treated as deliberate intent so users don't have to unset shell env vars before running completion. See [`config-and-local-state.md`](../../cli-utilities/config-and-local-state.md) for the full precedence chain.
 - If `.oat/config.json` sets `archive.summaryExportPath`, completion copies `summary.md` to `<archive.summaryExportPath>/20260401-<project>.md`.
-- Missing or unusable AWS CLI configuration produces warnings during completion instead of blocking closeout.
+- Missing or unusable AWS CLI configuration blocks synced terminal cleanup when S3 durability is configured; when S3 sync is not configured, it is not part of the durability requirement.
 - `oat repo archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.
+- Persisted archive metadata binds the snapshot to the source-ref SHA, allowing
+  an interrupted closeout or legacy complete record to resume without
+  rematerializing an active project. Dashboard and list surfaces omit fully
+  retired projects and report precise cleanup or ref-mismatch diagnoses for
+  remaining legacy state.
+- `oat project links` continues to render full-SHA links through the completed
+  ref. `oat project prune` is a separate destructive choice that removes
+  terminal ref reachability but preserves local and S3 archive snapshots.
 
 ### Phase status: `pr_open`
 

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

@@ -76,12 +76,14 @@ sequenceDiagram
   participant Root as Project root
   participant Adapter as Project adapter
   participant Engine as Dispatch engine
+  participant Journal as Project dispatch journal
   participant Phase as Phase implementer
 
   Root->>Adapter: Phase + lifecycle authority
   Adapter->>Engine: Provider-neutral dispatch request
   Engine-->>Root: Exact route + request ID
   Root->>Phase: Phase Scope
+  Root->>Journal: Accepted or blocked-before-start record
   Phase-->>Root: Phase report + commits
 ```
 
@@ -118,6 +120,22 @@ original `request_id`.
 This preserves continuity without allowing replacement after an accepted failed
 launch.
 
+## Native Dispatch Lineage
+
+The launcher constructs and redacts the complete generic record plus the
+namespaced OAT role event before it calls the native host. Immediately after
+the host returns, the project adapter validates and persists the accepted or
+`blocked-before-start` state with `oat project dispatch record`. The command is
+a recorder only; it never launches a provider or changes selection authority.
+
+An accepted handle owns the scope and closes replacement. One fresh fallback
+record is legal only when the native wrapper proves no child started, links the
+trigger and fallback request IDs, preserves the exact provider/model/effort/
+route/authority controls, resolves canonical role identity, and labels the
+fresh child as an approximation. Timeout, `BLOCKED`, refusal after acceptance,
+runtime mismatch, missing telemetry, interruption, and malformed output never
+authorize a fallback.
+
 ## Optional Third Tier
 
 Nested work is appropriate when the work itself benefits:

package/assets/docs/workflows/projects/picking-up-projects.md

@@ -25,6 +25,14 @@ the nested checkout. When the selected project is a coordination parent, pull
 also discovers and pulls its child projects by default. Pass `--no-children`
 only when you intentionally want the selected project alone.
 
+Completed projects are not adoption candidates. Their authoritative ref is
+`refs/oat/completed/<project>`; both `pull` and `open` return a terminal
+diagnosis instead of recreating an archived checkout or record. A same-SHA
+active ref may remain as an inert alias and is ignored. Differing active and
+completed SHAs require repair before lifecycle work continues. The same guard
+applies to coordination children: a terminal child discovered while pulling
+its parent is reported and skipped rather than adopted.
+
 After adoption, set or open the project through the normal lifecycle command
 you are using. Arrival-aware project skills pull before reading its artifacts.
 
@@ -47,17 +55,19 @@ you are using. Arrival-aware project skills pull before reading its artifacts.
   project ref during sync operations such as `pull`; do not expect a generic
   clone or `git fetch` to materialize the checkout.
 
-## Why retained refs remain durable
+## Why completed refs remain durable
 
-`refs/oat/projects/<project>` is a real Git ref locally and on `origin`. The
+`refs/oat/completed/<project>` is a real Git ref locally and on `origin`. The
 objects reachable from it remain garbage-collection roots even when no nested
 checkout exists. Branch pruning, remote-tracking-ref pruning, and
-`git worktree prune` do not delete the project ref. Completion deliberately
-retains it so pinned PR links remain valid.
+`git worktree prune` do not delete the completed ref. Completion deliberately
+retains this terminal reachability root so pinned PR links remain valid.
 
-Only the explicit destructive operation `oat project prune` removes the local
-and remote project refs. Treat it as permanent project-history deletion and
-review its warnings before using `--force`.
+Only the explicit destructive operation `oat project prune` removes the
+completed ref and any matching active alias. Treat that as permanent Git
+project-history reachability deletion and review its warnings before using
+`--force`. Prune does not remove durable local or S3 archive snapshots, and it
+refuses to delete either ref when their SHAs differ.
 
 ## Archive contents
 
@@ -65,8 +75,15 @@ When archive is selected, completion copies a synced project into
 `.oat/projects/archived/<project>/` without the nested checkout's `.git`
 pointer or `reviews/`. S3 snapshots also omit `pr/`, following the existing
 archive policy. When archive is disabled or declined, the active synced
-checkout remains in place. Both paths retain the project ref and commit the
-tracked record as `complete`; only the archive path records an archive snapshot.
+checkout remains in place. Successful archived closeout instead uploads the S3
+snapshot first when configured, makes the completed ref authoritative, removes
+the checkout, and deletes the tracked JSON record. The local archive metadata
+retains the source-ref identity needed for recordless retries and later S3
+restore without recreating active state.
+
+If closeout is interrupted after terminal archive identity exists, rerun
+completion so it can resume from the completed ref and archive metadata. Do not
+use `pull` or `open` to recreate an active record or checkout.
 
 ## Related
 

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

@@ -76,9 +76,11 @@ Both completion orderings are supported:
 
 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. Synced completion retains the project ref,
-which keeps its SHA-pinned links resolvable after the nested checkout is
-removed.
+so its artifact links remain valid. Synced completion makes
+`refs/oat/completed/<project>` authoritative at the verified source SHA. A
+same-SHA `refs/oat/projects/<project>` ref may remain only as an inert alias;
+the completed ref keeps the SHA-pinned links resolvable after the nested
+checkout and tracked record are removed.
 
 ## Reference artifacts
 

package/assets/docs/workflows/projects/reviewing-oat-prs.md

@@ -6,17 +6,21 @@ description: Understand synced-project records, SHA-pinned artifact links, and t
 # Reviewing OAT PRs
 
 A PR for a synced OAT project contains the implementation diff without placing
-the agent-facing project tree on the feature branch. Reviewers get durable
-project context through a small tracked record and a generated links block in
-the PR body.
+the agent-facing project tree on the feature branch. While the project is
+active, reviewers discover its context through a small tracked record and a
+generated links block in the PR body.
 
 ## The synced record
 
-`.oat/projects/synced/<project>.json` is tracked on the feature branch. It
-names the project slug, `origin`, `refs/oat/projects/<project>`, whether the
-project is active or complete, and the archive snapshot when completion has
-created one. It is discovery and lifecycle metadata; the project artifacts
-themselves live on the project ref.
+`.oat/projects/synced/<project>.json` is tracked on the feature branch while
+the project is active. It names the project slug, `origin`, and
+`refs/oat/projects/<project>`. The record and active ref are discovery and
+lifecycle metadata; the project artifacts themselves live on the project ref.
+
+Successful archived closeout deletes the tracked record and makes
+`refs/oat/completed/<project>` the authoritative terminal reachability root.
+The PR's existing SHA-pinned artifact links remain valid through that completed
+ref even after the active checkout and record are gone.
 
 ## The artifact links block
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.50",
-  "docs-config": "0.2.50",
-  "docs-theme": "0.2.50",
-  "docs-transforms": "0.2.50"
+  "cli": "0.2.52",
+  "docs-config": "0.2.52",
+  "docs-theme": "0.2.52",
+  "docs-transforms": "0.2.52"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: oat-dispatch-subagents
-version: 1.2.3
+version: 1.2.4
 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
@@ -129,6 +129,62 @@ decomposition.
 The optional policy and ceiling are already-resolved inputs. Do not infer where
 they came from or resolve project state to obtain them.
 
+## Native Dispatch Lineage
+
+For a project-aware dispatch, the calling workflow records native dispatch
+lineage through the project adapter; this provider-neutral engine never writes
+project state itself.
+
+1. Construct the complete generic record and namespaced OAT event, redact it,
+   and validate sensitive-content exclusion before the native host call or
+   launch. Construction is in memory; do not claim a launch result yet.
+2. Invoke the exact native target once. Immediately after the host returns,
+   record either `launch_status: accepted` or
+   `launch_status: blocked-before-start` in the generic dispatch record. A
+   blocked result also requires the provider-wrapper attestation
+   `provesNoChildStarted: true`.
+3. Preserve the exact target and controls: provider, model, effort, reasoning
+   mode, service tier, route, authority, sandbox/tool payload, deadline, and
+   retry limit. Namespaced evidence cannot redefine any generic field.
+4. Only a proven pre-start rejection permits one fresh fallback record; that
+   one fallback requires `provesNoChildStarted: true`. It preserves the exact
+   target and controls, links both request IDs,
+   includes resolved canonical role identity, and says `approximation: true`.
+5. Timeout, `BLOCKED`, refusal after acceptance, runtime mismatch, missing
+   telemetry, malformed output, and interruption never authorize fallback or
+   replacement. Continue only through the accepted handle or stop.
+
+Pre-start native-selection rejection is a closed event set, disjoint from
+terminal child-outcome codes. Use exactly one of `native-role-unavailable`,
+`native-target-unavailable`, `native-selector-unsupported`,
+`native-catalog-unsatisfying`, `capability-unresolved-or-unsupported`,
+`wrapper-payload-rejected`, or `wrapper-launch-refused`. The recorder rejects
+every other code, and it names the prohibited outcome family when a terminal
+code such as `timeout` is submitted. A fallback additionally requires the
+trigger record to carry resolved canonical role evidence, and the fallback's
+role evidence must equal it exactly.
+
+`wrapper-launch-refused` covers only conditions in which the launch surface
+declined the request and no child process was ever created: a rejected or
+unsupported payload, a refused authorization scope, an unavailable or
+unregistered target, or a wrapper precondition failure raised before spawn. Any
+condition in which a child process was created — including spawn success
+followed by immediate exit, a crash, a broken handle, or a lost transport — is a
+terminal outcome, not a pre-start rejection, and must be recorded through
+`child_outcome`. If you cannot prove the child never existed, you cannot set
+`provesNoChildStarted: true`, and no fallback is authorized.
+
+Project-aware callers pass the validated record and event on standard input:
+
+```bash
+oat project dispatch record \
+  --project "$PROJECT_PATH" \
+  --event-file - \
+  --json
+```
+
+The command validates and persists evidence only. It never launches a provider.
+
 ## Capability and Authorization
 
 Classify delegation before launch:

package/assets/skills/oat-dispatch-subagents/references/record-schema.md

@@ -191,7 +191,9 @@ current nested dispatcher. It does not imply a stable enum or authorize
 reconstruction of a materialized lifecycle variant.
 
 `role_selector` is the exact provider or harness agent-type selector, when that
-surface exists. Preserve opaque selectors byte-for-byte.
+surface exists. Preserve opaque selectors byte-for-byte, within the
+256-character identifier bound described under
+[Size and Content Bounds](#size-and-content-bounds).
 
 Use the stable selection reasons `native-catalog`,
 `native-catalog-unsatisfying`, `pre-start-rejection`, `inherit`, and
@@ -257,3 +259,77 @@ the interpreted service tier when known.
 A service tier never changes `model_class_floor` or `floor_satisfaction`.
 Unknown tier semantics must be recorded as a diagnostic and may block a
 consequential route.
+
+## Size and Content Bounds
+
+A dispatch record is evidence, not a document. Validation enforces these bounds
+and fails closed; know them before authoring a record rather than discovering
+them at a durable write.
+
+Caller-authored text, by kind:
+
+- 256 characters — identifiers, names, selectors, routes, and statuses.
+- 512 characters — a single explanatory field such as `classification_reason`
+  or one `escalate_when` entry.
+- 1024 characters — the longest free-form fields: `objective`,
+  `expected_output`, and `verification_evidence`.
+
+Six container fields carry short references and identifiers, never narrative
+text: `payload`, `candidates_considered`, `configured_invocation_evidence`,
+`continuation_events`, `diagnostics`, and `escalate_when`. Each is validated as
+a closed JSON projection bounded on four independent axes, so no one axis can
+be traded against another:
+
+- nesting depth at most 4 levels;
+- each string at most 512 characters;
+- at most 512 values per field, which closes chunking one body into many short
+  strings; and
+- at most 16 KiB serialized per field.
+
+The whole record is additionally capped at 64 KiB, measured as the **published**
+bytes — the pretty-printed JSON plus trailing newline that is actually written
+to the journal, not compact `JSON.stringify` output. The two differ by roughly a
+tenth on a nested record, so size against the published form. Per-field
+projection limits above remain compact measurements, because they bound the
+shape of a field rather than the size of a file. A realistically rich record
+measures a few kilobytes, so these limits bind prompt bodies, transcripts, and
+chunked logs rather than legitimate evidence.
+
+Keys are classified against credential, token, prompt/message, transcript, and
+role-content families after Unicode folding, and a spelling the normalizer
+cannot fully account for is treated as sensitive rather than classified on a
+partial token. Store references, identifiers, and digests; never role content, message bodies,
+or credentials.
+
+Absolute filesystem paths are handled by field class, because the journal is
+committed and a home path in it is permanent:
+
+- **Identity and control fields reject them.** `caller`, `scope`, every
+  selector, `selected_route`, the `guidance_*` fields, `authority`,
+  `authorization_scope`, `catalog_snapshot`, `candidates_considered` and
+  `fallback` refuse a record containing an absolute path, including
+  colon-prefixed forms such as `cwd:/Users/alice`. A path is never a legitimate
+  identifier there, so ambiguity resolves to rejection. Pass a repository-relative
+  path or a redacted form like `<user>/agents/<role>.md`.
+- **Prose and nested evidence redact them best-effort.** `objective`,
+  `expected_output`, `verification_evidence`, `classification_reason`,
+  `escalate_when`, and the bounded container fields replace a detected path with
+  `<redacted-path>`. This is deliberately conservative rather than complete: it
+  skips candidates inside an `http`/`https` URL and candidates ending in `/`, so
+  a URL route (`?next=/dashboard`) and a regex literal (`/foo/bar/`) survive
+  intact. Colon-prefixed forms also survive. Corrupting a legitimate value is
+  worse than leaving a path in prose, so do not rely on this to sanitize
+  caller-authored text — redact before submitting.
+
+Optional runtime observation is metadata-only and subject to the same
+identifier bound, which admits letters, digits, `.`, `_`, and `-` only, so no
+observation value can carry a path or a URL. Its `match` and `comparedAxes` are
+always derived from the record's configured invocation rather than supplied by
+the caller, and `matching` covers only the axes listed in `comparedAxes`.
+It records what a provider reported about its own child and never restates the
+request. An axis the provider did not report is simply absent from the
+observation; an absent or unparseable observation is `not-reported` as a whole;
+and `not-exposed` is reserved vocabulary for an axis a provider genuinely has
+no selectable control for, with no producer today. None of the three is ever
+filled in from `model_selector`, `effort_selector`, `service_tier_selector`, or
+`role_selector`.