@zq-silk/yui 2.20.0 → 2.22.0

package/skills/yui-runtime/VERSION

@@ -1 +1 @@
-11
+44

package/skills/yui-runtime/references/archive.md

@@ -0,0 +1,51 @@
+# Archive a Task
+
+Read before an authorized archive or cleanup of retained archive resources.
+This is not required merely to record publication or reopen a result.
+
+## Archive separately
+
+Completion does not authorize archive. A delivery Leader with original user
+authorization may use [ordinary archive](../../yui-leader/references/authorization.md);
+this grants no force or abandonment authority. Otherwise the Operator obtains authorization for
+the exact Task, checks archive eligibility, then uses `--integrated` for verified
+merged delivery or `--abandon` for deliberate non-delivery. General archive
+approval never implies `--force` authority. Preserve the Task record.
+
+Ordinary archive requires settled business, exact delivery (or authorized
+abandonment), and proven stopped execution. It commits logical archive before
+one foreground resource cleanup. Safe physical retention—dirty diagnostics,
+missing-path recovery gaps, or remaining Git registrations—is not a reason to
+force archive or rewrite old Integration outcomes. Terminal failed/superseded
+Integration history stays readable; an active/conflicted attempt or unknown
+execution still requires settlement.
+
+With explicit force authorization for a completed or cancelled (retired) Task, use
+`yui task archive <task> (--integrated|--abandon) --force`. Force commits the
+archive and stops new Task scheduling before attempting safe foreground cleanup.
+Missing/stale delivery evidence, unresolved execution and cleanup errors become
+warnings with retained resource references; they do not block that commit.
+Authority, lifecycle, identity and mandatory audit persistence still fail closed.
+
+Force does not verify a merge, accept work, stop unknown execution, discard dirty
+data or imply abandonment. Keep the requested disposition and original
+Publication/completion evidence. Unverified local commits and resources that
+cannot be safely released stay owned and traceable. Late runtime events remain
+source evidence, not authority to resume or settle unknown input.
+
+Read `task show <task> --json` for `data.archive.warnings`,
+`data.archive.retainedResources` and `data.archive.cleanupEvents`. These bounded
+views include counts and inspection actions; read the existing paginated
+`task event list` and Task context resource inventory for omitted evidence.
+A successful archive
+exit means `archived=true`, not that cleanup fully succeeded. `cleanupFinished`
+means the foreground pass finished, not that every resource was removed.
+`allResourcesReleased` separately requires release evidence and no retained
+resources. Historical warnings do not disappear after a successful later pass.
+If cleanup was interrupted, the Task stays archived. Repeating archive only
+reports current facts. After inspecting the exact retained owner/reason, use
+`task archive-cleanup <task>` for one new bounded pass, or the reported
+WorkItem/Review/Integration cleanup entry. Every pass rechecks current identity,
+runtime and Git registration facts; it is not an atomic batch and does not
+discard unknown material. Registry-only remnants require the existing resource
+inspection route, not a global `worktree prune`. No background retry is implied.

package/skills/yui-runtime/references/command-discovery.md

@@ -0,0 +1,41 @@
+# Command discovery
+
+Read before using help/capability discovery or diagnosing a hidden command.
+The shared [yui-runtime](../SKILL.md) remains the loading and authority contract.
+
+Use the narrowest known `yui --json help <command ...>` path through the authorized
+CLI; do not rediscover its ancestors first. A leaf includes its complete usage
+and options; default group help lists immediate children only. When an action
+needs several commands in a known small group, use
+`yui --json help <group ...> --recursive` once instead of serial child lookups.
+Keep root or broad groups non-recursive for discovery; expand only the needed
+group and recover any truncated output. Neither form grants execution authority.
+Help, examples and shell completion
+share the catalog projection; public terminals and unmanaged Agents share one
+public view. This offline view is only guidance, not an authenticated permission
+or a way to switch Roles. An incomplete or stale managed identity must not be
+cleared to obtain public execution authority.
+
+For Codex, the native `CODEX_THREAD_ID` takes precedence over the transport's
+`YUI_NATIVE_SESSION_ID`; a newly created thread can legitimately lack the latter.
+Other adapters do not borrow Codex identity for offline discovery. A missing
+transport variable or hidden help entry alone does not prove Session failure.
+Discovery does not establish that a Session is current: actual execution still
+revalidates Session, Task/Assignment, workspace, resource and Grant boundaries.
+
+When capability discovery appears in that view, use `capability search` for
+templates and `capability describe <name> --task
+<task-id> --input '<json>'` for supported exact authorization assessments.
+No `access` field means no exact authorization conclusion was made: supply the
+required parameters and follow the domain's existing execution checks. Hidden
+operations are omitted; `requestable` includes the exact missing Grant bounds
+and existing request route; `authorized` remains subject to execution-time
+revalidation. Provider outages do not change this authorization observation.
+
+Discovery never sends requests, consumes Grants, starts plugins or approves
+effects. If the Task actually needs a requestable operation, use the existing
+Assignment Message to Leader, Leader InputRequest, or Operator path. Preserve
+the exact action, resource/plugin, digest, environment and phase. A response is
+not a Grant. Existing source-authorized Leader Grant operations and Operator
+Grant authority remain unchanged; never expand an authorization source or
+solicit real-resource validation merely because an operation is requestable.

package/skills/yui-runtime/references/completed-followup.md

@@ -0,0 +1,65 @@
+# Continue a completed result
+
+Read before reopening a completed, unarchived Task for authorized same-result
+follow-up or an explicitly identified unfulfilled commitment. This grants no
+new authority.
+
+## Post-completion routing boundary
+
+An authorized same-result follow-up or explicitly identified unfulfilled
+commitment may require reopening for tracked diagnosis, evidence handoff,
+necessary coordination, implementation or delivery. A simple factual query
+does not. Diagnosis remains read-only unless changes are requested; reopening
+does not turn discussion into implementation. The current matching Leader may call `task reopen <task>` for
+its own Task and continue that request; an Operator handoff is not mandatory,
+and neither Role needs the user to additionally say “reopen.” Read the original
+completion, fixed heads/reports, Publication, new request and current authority
+first. Inspect the reopen result and current Context before executing; delivery
+still requires the current Session's delivery authority, legal workspace and an
+enabled execution gate.
+
+If the Leader already received the request, use its original durable input and
+continue after reopening; do not resend it or create a self-wake. Preserve a
+direct-conversation request and its boundaries in Task records when needed,
+without impersonating user/Operator input. When the Operator or user is routing
+new input, use the existing two operations:
+
+```sh
+yui task reopen <task>
+yui operator submit "<new request, authority, boundaries and prior evidence>" \
+  --task <task> --intent <discuss|develop> --request-id <id>
+```
+
+Unaddressed `task message send` with the same intent/key options is an alternative
+to the second command, not an additional send. Ordinary send/queue/submit still
+refuses completed Tasks before saving new input; no intent implicitly changes
+lifecycle and there is no auto-reopen option. `--to leader` instead requires an existing
+WorkItem/ReviewRound Assignment.
+
+Reopen returns the Task to active and clears its current completion fields;
+original completion events, fixed commits/artifacts and Publication history stay
+intact. The Leader must assess the new request and separately accept any new
+result, not pretend old validation proves changed work. Reopen does not replay
+historical Messages/Runs, change the Role's Agent/model/permissions, or lift an
+independent execution stop. Choose `discuss` for diagnosis/explanation and
+`develop` only with implementation authority. Simple queries, record-only input,
+ordinary notifications, Session recovery or an opportunity for improvement do
+not themselves authorize resumption. New goals need their own Task, not an
+expanded old result.
+Cancelled intent needs explicit
+user/Operator restoration authority and cannot be restored by the Leader;
+archived Tasks cannot reopen. A stopped gate still needs
+the separately authorized start/cleanup path.
+
+These are two atomic operations, not one transaction. Read the reopen result and
+the submission's saved/queued receipt separately. If the second step fails,
+inspect current Task/Message facts and continue only the unapplied step within
+unchanged authority. Keep the same submission key on a matching retry; unknown
+native or external effects are never replay permission. Do not reopen again just
+to retry input after another completion, cancellation or stop. A lifecycle-only
+notification may precede the new Message: the Leader waits for the actual request,
+without rerunning old work or immediately completing the reopened Task.
+
+Publication recording, diff/adopt and verification remain separately authorized
+atomic operations on completed, unarchived results. They need no reopening when
+no further execution is requested, and never grant authority for code changes.

package/skills/yui-runtime/references/context-ordering.md

@@ -67,37 +67,6 @@ timestamp. On rejection, reread current facts and reconcile only the intended
 fields; do not blindly copy an old summary under a newly read guard.
 An old Session still cannot write through this operation.
 
-## Maintain a baseline and incremental history
-
-For current Task facts, retain `coreCursor` from `task context <task>`.
-`task context delta <task> --after <coreCursor>` returns **event history**, not
-a replacement current view. Retain the same `--after` on every continuation;
-use `--continuation` until `complete: true`, then advance to `throughCursor`.
-The window's upper bound is fixed. Later arrivals belong to the next read.
-
-Deduplicate by source Home + Task + event ID, and process numeric event order
-within that stream. `createdAt` is occurrence/recording metadata, not a global
-causal clock; native acceptance, delivery and acknowledgement are separate
-facts. Never apply a late event's old payload over a newer current record.
-Re-read affected current refs with their digest when making a decision.
-An empty delta preserves the baseline; `stateChanged` can still require a
-current read because not every shared fact is a Task event.
-
-Cursors from another Home/Task, incompatible or invalid continuations, missing
-baselines and source changes require a fresh bounded current read. Do not join
-pages from different windows or versions. A failed original-detail digest
-requires rediscovery; a content page must be reassembled only with its own
-source digest. None of these reads consumes input or permits replay.
-
-Frozen Run context is a different stream. Keep its exact Snapshot and
-Assignment. `deltaRefs` is a launch hint, not a complete patch. The explicit
-Run delta reports complete changed `refs` and `removedRefs` against its named
-parent Snapshot, with large documents paginated. Apply removals only to that
-frozen inventory; an empty delta is a no-op. Mutable Task facts and current
-inbox clarifications must be refreshed separately within read scope; they
-never expand the frozen Assignment or change a Review candidate.
-
-Focused wakes use exact input refs, including delayed and same-timestamp
-inputs. Timestamp-window discovery is under `--history` (or a historical wake
-without refs), not new delivery authority. Original event and Message reads
-remain available without rewriting or replaying them.
+Before consuming Task event or frozen Run deltas, read
+[Incremental context](incremental-context.md). A handoff or conflict handled
+with current facts alone does not require that protocol.

package/skills/yui-runtime/references/context-reads.md

@@ -0,0 +1,61 @@
+# Complete context reads
+
+Read when discovering missing context, following a wake/result pointer, or
+assembling paginated original bodies. Ordinary complete originals need no
+additional discovery. This is an operation manual, not a turn-entry dependency.
+
+Read every relevant original requirement/result/authorization page before its
+decision. CLI JSON is in top-level `data`, not encoded `output`. Lists expose
+`items`, `total`, `complete`, `nextCursor`; summaries/first pages are not full
+bodies. The 32 KiB compact-JSON budget includes nested structure/cursors, with
+summaries limited to 512 UTF-8 bytes. Skill checks are metadata-only but paginate
+when large. Discover only what is needed, not all history.
+
+Long reads replace the value with `contentPage` (Run context/expand:
+`data.context`; delta: `data.contextDelta`). Repeat the same read using
+`--cursor <nextCursor>` until complete, concatenate `text` by offset and parse
+once under the same source/digest. Restart on source change; never mix chunks
+or use read cursors for mutation. Reads neither consume queues nor acknowledge
+implementation or authorize replay.
+
+- Task current Context holds bounded facts/Message refs, not event/terminal Run
+  history. `collections`/`attention` flag incomplete discovery: use
+  `task context list <task> --store <store> [--cursor <cursor>]`, then
+  `task context inspect <task> --store <store> --ref <refId> --digest <digest>`.
+  For 1–8 known independent originals in that Task, `task context inspect <task>
+  --context-ref <store/refId@digest> ...` returns `items` under the same total
+  budget. Repeat the flag for each reference; no JSON quoting is needed.
+  `--refs '<JSON array of exact ref objects>'` is another batch form.
+  Choose one form: single `--store/--ref/--digest`, repeated `--context-ref`,
+  or `--refs`; do not mix them. A stale/unavailable ref rejects the group.
+  Follow `contentPage` with the same ordered selection.
+  Group needed reads, not the whole directory: reuse unchanged complete bodies
+  still available, and fetch missing/changed originals. After loss/compaction,
+  reconstruct the current action's working set, not every historical source.
+  Task Message current view excludes explicit ACK/retirement, not uncertain
+  delivery; default all view is history.
+- For wakes read the complete focused input/result view and relevant originals.
+  `task wake show <task> <wake>` preserves fixed windows/explicit older refs,
+  deduplicates inputs and supplies exact reads. In the focused JSON view, a
+  current Leader's `inbox show <wake>` exposes the same view in `originalContext`
+  (wake metadata stays at the top level); no second wake read is needed when
+  that content is already complete and current. Neither read claims the input.
+  In either carrier, a
+  message's `contentOmitted: false` and `value` provide its complete current
+  original with a versioned `ref`; use that body rather than fetching it again.
+  Long messages and result reports retain their exact read; a completion notice
+  is not a report. Reconcile later revisions against the fixed wake, not by
+  assuming its current value was the originally delivered version. Use `--history`
+  only for needed diagnostics/window history; complete pagination in either view.
+  Ordinary disposition needs no unrelated events or merely started Runs.
+  Event deltas are fixed-upper-bound history, not replacement current state.
+- A result Message's `context inspect` carries the report, when available, in
+  `result.output` beside `value` (per item in a batch). The Message body may be
+  only a completion notice; a `Yui-Summary:` first line does not make the whole
+  report a summary. Finish any `contentPage` before using it.
+  `task message show <task/message>` and `task run show <task>/<run> --view result`
+  are alternative complete-report reads, not follow-up steps after obtaining
+  that same report. Use Run `--view full` when input/launch audit facts are needed.
+  Result is the original, not a summary; finish its pages. Read additional
+  execution facts only when needed: `task run show <task>/<run> --view status --json`
+  omits input/report bodies. Status/report receipt is not semantic acceptance.

package/skills/yui-runtime/references/dispatched-run.md

@@ -0,0 +1,61 @@
+# Dispatched Run context
+
+Required for every explicitly dispatched managed Task AgentRun before planning
+or acting. Follow the shared loading rules in [yui-runtime](../SKILL.md);
+this procedure does not apply to direct conversation or Global Context.
+
+1. Read the exact AgentRun identity from the newest Bootstrap Envelope.
+2. Before acting, load its authorized pack using the current Session Manifest's
+   Context command and the exact Task/Run identity:
+
+   ```sh
+   yui task run context "<task-id>/<run-id>" --json
+   ```
+
+3. Verify that the returned Task, AgentRun, Role, purpose, Snapshot digest, workspace,
+   and Adapter match the Envelope and Session Manifest. Stop and report a
+   context-load failure if the pack is missing, stale, unauthorized, malformed,
+   or mismatched. Never request an inline/full-prompt fallback.
+4. Use the entry's `pointers` (including each pointer's summary) first. They are
+   a bounded window into the frozen readable-ref inventory. `pointerPage`
+   reports total/complete/nextCursor; discover further relevant refs with
+   `task run context <task>/<run> --view refs [--cursor <cursor>]`.
+   `deltaRefs` samples changed identities, with `deltaRefsTotal` reporting coverage.
+   Entry, `--view full` and `--view refs` are alternative discovery views, not a
+   sequence. Once the needed pointers are present, expand their originals directly.
+   A complete pointer page needs no `refs` reread; a full pack already contains
+   those pointers and the input, but not the referenced original bodies.
+   If `input.directiveOmitted` is true, read the complete assigned input with
+   `--view input` before acting; its entry summary is not the instruction body.
+   Otherwise the returned `input.directive` is complete and needs no additional
+   input/full read. Use full only for genuinely missing pack details, not to
+   certify an already complete entry or replace required original expansion.
+   Expand only an authorized ref when
+   its full value is needed, selecting it by the pointer's exact `store` and
+   `refId`:
+
+   ```sh
+   yui task run context expand "<task-id>/<run-id>" <ref-id> --store <store> --mode full --json
+   ```
+
+   `--store` is required, even when the ref id is unique. Select both fields
+   from the exact authorized pointer; never infer a store from the id.
+   For 1–8 known independent originals in this same Run, one expansion can use
+   repeated `--context-ref <store/refId>` from those frozen pointers,
+   instead of positional `<ref-id> --store`. It returns `items` under
+   `data.context`, sharing the ordinary page budget. Repeat the same ordered
+   selection with `--cursor` when paged; do not mix single and batch forms.
+   The Run already pins its Snapshot; optional `@digest` adds an exact match check.
+   Dispatched Runs require an explicit frozen Snapshot. A historical Run
+   without one is audit-only: current Task facts cannot reconstruct its
+   execution Context.
+
+   A pointer or summary is not the request's body. Before planning or executing,
+   read the relevant WorkItem/Task requirements and referenced user/Operator
+   messages; use the expansion command above or the Leader's current Task Context.
+   Reports remain evidence, not authority to enlarge the assignment.
+
+5. On a later wake, refresh current Task facts separately from frozen Run refs.
+   Use a Run delta only against its exact declared Snapshot lineage; `deltaRefs`
+   is a hint, not a complete patch. If no baseline is available, reload the
+   exact pack; do not reconstruct state from transcript memory.

package/skills/yui-runtime/references/execution-failure.md

@@ -0,0 +1,105 @@
+# Failed execution and Provider recovery
+
+Read when a native Turn or launch failed, before retry or a manual successor.
+Apply the common boundaries in [Runtime recovery](recovery.md) first.
+
+## Inspect the failed execution
+
+Read the referenced `runtime.agent-error`, exact AgentRun, Role Session and
+affected WorkItem, ReviewRound or Integration. Use `task next-action` and
+`execution audit` as decision support, not as an automatic plan.
+Active or quiet observations are not a Task-wide lock or proof of failure.
+
+### Configuration and model-name failures
+
+The already-running caller handles a failed launch: Worker/Reviewer failures
+go to their Leader, and an unavailable Leader's failure goes to the existing
+Operator channel. A target that did not start cannot repair itself. Read the
+referenced error once; do not create a recovery Agent, a polling loop or a new
+Task merely to handle it.
+
+Use the error's capability-query pointer to inspect native metadata with the
+recorded failed configuration:
+
+```sh
+yui task event show <task> <error-event>
+yui task role capabilities <task> <role> --error <error-event> --refresh
+```
+
+The query uses the Controller's Provider environment, not your own Agent's
+possibly different account variables, and requires that Controller to be running.
+It preserves the requested model, workspace, profile/settings selection and
+configured Agent identity. Native settings files and credentials are still read
+currently, not copied into error history. A historical error without a recorded
+configuration, or a changed Agent command/bindings, returns a diagnosis instead
+of borrowing today's Role configuration. To inspect the desired next launch
+explicitly, omit `--error`. Distinguish live enumeration, identity-matched cached
+observations, declared static adapter inputs, and unavailable fields. Read field
+reasons, warnings, observation/attempt times and the current query error: a live
+query can contain static or unavailable fields, and a cache hit is not current
+Provider confirmation. Do not treat an alias list as a complete Provider
+whitelist or a static/custom choice as proven native support.
+
+Reconcile the original user requirement with exact native IDs and alias
+mappings. Correcting the name of the same authorized model is routine recovery;
+selecting another model, account, permission or cost boundary is not. If there
+is no proven equivalent, preserve the failure and report the missing choice.
+Do not guess names, select a similarly named variant, or silently fall back.
+
+After correcting only the intended configuration, choose the existing operation
+that matches current facts. A rejected notification retains its input:
+
+```sh
+yui task wake show <task> <wake>
+yui task wake retry <task> <wake> --reason "<correction and evidence>"
+```
+
+Retry does not replace a Session or change its immutable effective configuration.
+If an existing Session must adopt changed settings, read
+[Session replacement](session-replacement.md) before that operation; an assigned
+Run uses its own legal retry operation.
+Accepted or uncertain input cannot be replayed through notification retry.
+Configuration failure is not transient infrastructure recovery, and unchanged
+configuration does not justify another attempt.
+
+### Bounded infrastructure retry
+
+The Controller, not the Agent, counts and schedules qualifying transient
+Provider retries: at most five automatic executions after the initial failure,
+within one ten-minute recovery window. Native acceptance, activity and partial
+output do not reset that count. Only proven native success resets the chain;
+it neither accepts a WorkItem nor completes a Task. Unknown delivery remains
+fenced for exact readback; it is never replayed.
+
+Inspect the current `providerRetry`/`retry` projection in Context, or use
+`task role session retry <task> <role> show`; Global Sessions use
+`session retry <role> show`. While `waiting` or `in-flight`, do not dispatch a
+duplicate or add a private retry loop/resend. After recovery inspect prior work
+and external receipts before continuing; recovery instructions grant no new
+authority. A readable failed Run remains immutable evidence while its recovery
+successor handles the same responsibility and frozen Review boundary.
+
+`cancel` withdraws pending automatic recovery; `disable` additionally disables
+future automatic chains on that Provider binding. Neither stops an admitted
+native Turn. `enable` permits future failures to qualify, without replaying
+old failures. These controls require the existing user/supervisor authority.
+
+`exhausted`, `cancelled` and `needs-attention` preserve the error, input and
+work. Read their exact reason, then choose an authorized next action. Unsupported
+Hosts/Adapters or unprovable Session/background state do not trigger automatic
+replacement, cleanup, model switching or a new grant.
+
+A failed AgentRun is immutable; retry creates a new attempt. Reuse a recoverable
+Session when useful and load the new attempt's current context, not an old
+Assignment from memory. A new Host process need not mean a new native Session.
+Preserve frozen Review candidates and selected synthesis sources on retry.
+An infrastructure failure is not a defect in the business result.
+
+Native internal retries are not failed terminals: observe without submitting
+another input. A missing automatic retry record is not evidence of exhausted
+budget or a damaged Session. An explicit `task run retry <task>/<run>` can
+continue from the current exact failed Turn even without an earlier automatic
+chain. Codex `systemError` alone does not require replacement; the normal
+submission path checks that the latest Turn is that failed Turn and background
+execution is empty. Missing or changed proof is a refusal, not permission to
+replay, change models or silently replace the Session.

package/skills/yui-runtime/references/global-context.md

@@ -0,0 +1,18 @@
+# Global input discovery
+
+Read when the Global Context pending page needs expansion or delivery diagnostics
+are relevant; receiving one exact original uses Runtime’s inbox contract directly.
+
+Global Context `pending` is bounded current/available-input discovery, not
+receipt debt or retry history; the Manifest's profile remains canonical.
+Its separate `currentOriginals` contains complete small Messages correlated to
+this managed Turn. Reuse the matching original; absence means use its exact read,
+not no input. It neither claims nor handles the Message, and future queued or
+historical bodies are not included. Read missing originals with `role message show <role> <message-id>
+--json`; continue incomplete pending pages with `role message list <role>
+--current --cursor <nextCursor>`. Accepted delivery retains its all-list record.
+`historyCount` is missing handling evidence, not new work.
+
+For classified delivery diagnostics, read the diagnostics section of
+[Global input controls](global-input-controls.md) in its full file. That does
+not authorize sending or controlling input.

package/skills/yui-runtime/references/global-input-controls.md

@@ -0,0 +1,44 @@
+# Global input controls
+
+Read before sending, steering or interrupting GlobalRole input, enabling
+controlled Global delivery, or inspecting classified delivery diagnostics.
+This is not required just to receive an input;
+use [yui-runtime](../SKILL.md)'s own-inbox flow for that.
+
+A GlobalRole's durable input uses the same three actions as a Task Role,
+addressed by the Role's own name instead of a Task. The local-user Web surface
+exposes this contract. Use `yui role message queue|steer <role> <text>` or
+`yui role interrupt <role>` through the public CLI. Queue/steer require a stable
+`--request-id`; steer/interrupt require the exact `--expected-target`.
+Configuration remains under `config role` and lifecycle under `session`.
+Do not fabricate Task/Run ownership or borrow the browser's user authority to
+bypass a managed Session boundary.
+
+Queue and steer
+save an owned Message; bare interrupt records a control request, not a new
+Message. Each uses a stable request id and that Role's own Session; none fabricates a Task or
+runId to reuse Task-scoped delivery. `queue` delivers at the Role's next legal
+opportunity and is idempotent by request id. `steer` and `interrupt` affect only
+the exact current native Turn — a stale `--expected-target`, an incapable plan,
+or an unproven delivery leaves the Message saved and reports the reason, and
+`interrupt` stops only through the Provider's native cancel with an optional
+`--then-message` naming one already-saved GlobalRole Message. When the Role holds
+no live managed Turn, a steer or interrupt is `NO_ACTIVE_TURN` and never falls
+back to another action.
+
+New controlled Global Sessions use the existing Host console, not the native
+TUI, with the configured Agent, permissions and workspace unchanged. A live
+unmanaged Session is not silently replaced or adopted; use an explicit Session
+lifecycle action before enabling controlled delivery.
+
+Only an exact terminal and the original Session/writer boundary release a then
+handoff. Never resubmit accepted/unconfirmed steer through changed request IDs
+or composed then; only conclusive rejection permits an explicit new attempt.
+
+## Inspect delivery diagnostics
+
+`role message list <role> --diagnostics` reports classified original failures
+with first/latest occurrence, distinct-observation count and recovery evidence,
+not repeated polls of one observation. `--diagnostic <key>` pages originals.
+Recovery notices neither ACK input nor prove effects undone;
+`interrupt-requested` proves neither Turn nor background stop.

package/skills/yui-runtime/references/host-custody.md

@@ -0,0 +1,30 @@
+# Host custody, protocol and upgrades
+
+Read for Host protocol/custody or persistence failures, or when diagnosing or
+changing Host custody during an upgrade. An ordinary Controller outage alone
+does not require it. Apply [Runtime recovery](recovery.md) first.
+
+Compatible upgrades preserve logical Sessions. Build generations and historical
+Skill packages are provenance, not continuation gates. Load current stable
+Skills and current authority; never change a user's model, account, native
+permissions or workspace to make an upgrade work.
+
+Within Host control/event v1, status advertises `controlCapabilities` and the
+loaded `hostImplementation`, independently of `endpointImplementation`. Missing
+capabilities or `eventDelivery` are unreported, not healthy. A Controller must
+not repeatedly send an unsupported `reconcile-turn`; the existing raw Inbox
+still permits exact event consumption without executing the input again.
+Current Hosts retain unpersisted original facts during a filesystem failure;
+keep that process alive until persistence recovers. Those volatile bytes cannot
+be recovered after process loss merely by restarting the Controller.
+
+Program/storage upgrade success does not mean Host replacement succeeded.
+Compatible live Hosts may continue, including busy ones. A new Host may resume
+the same native Session only through the existing authorized lifecycle after
+exact execution, background resources and writer release are proven. An idle
+status, a stopped proxy or a missing control field is insufficient. Unknown
+effects preserve the original Session, input and resources; do not force-kill,
+replay, hot-replace loaded modules or silently create a new Session. Existing
+explicit stop/replacement authority is separate from an ordinary upgrade.
+Unsupported protocols require an explicit bounded recovery plan, not arbitrary
+historical Host adoption. Storage migration remains independently fenced.

package/skills/yui-runtime/references/inbox-recovery.md

@@ -0,0 +1,77 @@
+# Inbox recovery and retained handling
+
+At an exact native terminal, engineering checks for unacknowledged inputs
+correlated to that turn and emits at most one existing notification. This is
+missing-evidence detection, never semantic ACK or proof of absent effects.
+Reminder-only turns do not generate another reminder. The retained originals
+remain inspectable if the bounded reminder is also missed; do not start a
+private polling/retry loop or copy the business input to obtain another turn.
+Task Assignment checks go to Leader for inspection and existing handoff or
+retirement, not automatic Worker/Reviewer replay. Exact terminal can end an
+active-consumption notification reservation without acknowledging its input;
+it does not infer or release an uncertain native writer.
+
+For obsolete Global input that was conclusively not submitted, use
+`yui inbox retire <entry> --request-id <stable-id> --reason "<disposition>"`
+after inspecting the original and current facts. Retirement preserves the
+original target, claim and explicit management evidence; it is not ACK.
+Accepted input uses normal claim/ack reconciliation. Unknown/pending control,
+transport acceptance and interrupt-then ownership cannot be retired through
+this operation. Task Messages retain the existing Leader `task message retire`
+and exact-Assignment handoff paths.
+
+Apply Runtime's claim/ACK contract: interrupted claims remain discoverable,
+non-expiring and unreplayed. A rightful successor must inspect the original
+input and prior effects before completing authorized handling and acknowledging;
+never replay uncertain external actions.
+After legal Session replacement, initialization can arrive before old handling
+is settled. This recovery notification is not the original business input or
+an acknowledgement. Read the current inbox and prior effects first. For
+`claimed-by-previous-session`, retain the original claim: do not claim again.
+Finish only the still-authorized handling and use a new stable ack request ID
+with a concrete disposition; the receipt retains both the old claimant and
+the current acknowledging actor. New queued input remains separate.
+For an exact-Session input already claimed by its selected Session, a rightful
+successor may explicitly settle that handling after inspecting the original
+and prior effects. This preserves the original target and claim; it grants no
+permission to submit or execute the input in a different Session.
+An Assignment change does not inherit handling authority. If the original Run
+stopped before acknowledgement, ask the Leader to inspect its exact native
+terminal and use the existing `task message handoff` to the current authorized
+Assignment. The original claim remains; handoff never resubmits it automatically.
+If that Assignment is obsolete, the Leader may inspect the original and prior
+effects, then explicitly use `task message retire <task/message> --reason "<disposition>"`.
+Retirement preserves the original claim and records the management decision;
+it neither fabricates an acknowledgement nor proves native execution stopped.
+An unfinished claim fences its Assignment, not unrelated work of the same Role.
+
+In-flight, unknown, not-yet-delivered explicit interrupt-then and
+unsettled steer inputs retain their existing owner/receipt and report a bounded
+reason instead of being taken over. Use existing exact-receipt recovery when
+needed; do not change request IDs, clear identity, or copy input to bypass it.
+A steer with no control receipt was not submitted; it may be explicitly handled
+and acknowledged in its authorized inbox, without converting it into a queue.
+Accepted Global inputs, delivered Leader windows and current Assignment
+continuations remain in the inbox until explicitly handled through the normal
+claim/originals/prior-effects/ACK flow above, never another native delivery.
+Claiming never resends input. A current rightful successor may settle accepted
+Global input or a Leader window only after inspecting prior effects, retaining
+the original delivery target. Pending/unknown acceptance remains blocked;
+claiming cannot bypass it or authorize replay.
+An explicitly released Leader notification (`notification.resolved` with
+`released-without-replay`) can be claimed for evidence inspection and settlement
+after verified native stop. Its original delivery status stays unknown or
+unaccepted; handling it cannot retarget Session-specific instructions or
+authorize re-executing unknown effects. If a required fact or user decision is
+unavailable, preserve the claim and report that exact boundary.
+
+An ack belongs to the exact original and revision: fixed windows pin
+`message.updated` event identities, including same-timestamp edits. A later
+revision still needs its own handling. Before Task completion, settle handled
+user-input windows; native acceptance or a terminal does not settle them.
+Original Messages, wake windows and handling receipts remain readable after
+acknowledgement. Lost context, Session continuation and installation upgrades
+do not reset receipts. If ack fails after an external effect, read back the
+original claim and the external receipt before retrying the same ack; do not
+repeat the effect. This is durable handling evidence, not arbitrary external
+exactly-once execution.