@zq-silk/yui 0.15.7 → 0.15.9

package/skills/yui-operator/SKILL.md

@@ -5,13 +5,15 @@ description: Route user requests into Yui Tasks, explain progress, manage confir
 
 # Yui Operator
 
-Follow `yui-runtime` for every managed Turn. Load the exact authorized Context
-Pack and treat its Task, Role, workspace, and permission view as authoritative.
+Follow [yui-runtime](../yui-runtime/SKILL.md) for the Session's authorized entry. A global Operator reads
+its Global Context without inventing a Task AgentRun. For explicit Task dispatch,
+load the exact Run Context Pack and preserve its scope and permission boundaries.
 
 Be the task-neutral user entry point. Let the user discuss outcomes rather than
 Yui records and commands. The Leader is the default Task coordinator, but the
 Operator may perform any legal Task action when direct intervention is the
-clearest and lowest-complexity path.
+clearest and lowest-complexity path. Global context does not grant a delivery
+workspace. Resolve Skill links relative to this Skill's directory.
 
 ## Communicate at the user's level
 
@@ -51,16 +53,29 @@ determine Task identity. They also do not determine WorkItem count. Let
 isolated workspaces and Integration handle independent Git changes.
 
 Keep the Task title concise and put detailed intent, constraints, and evidence
-in its description or routed Message:
+in its description or routed Message. The examples below are separate
+operations, not an automatic create/submit/activate sequence. For creation-only
+intent, save the Task without starting planning. Discussion does not authorize
+delivery; follow the Leader's [planning and activation boundary](../yui-leader/references/planning.md)
+before activation. Do not reopen terminal Tasks merely because new input arrives.
 
 ```sh
-yui operator submit "<related request and delta>" --task <task-id>
+yui operator submit "<related request and delta>" --task <task-id> --intent discuss
 yui task create "<independent outcome>" \
   --project <project> --base <project>=<ref>
-yui operator submit "<request and routing context>" --task <new-task-id>
+yui operator submit "<request and routing context>" --task <new-task-id> --intent develop
 yui task activate <new-task-id>
 ```
 
+Choose the submission intent explicitly; it is never inferred from the message
+text. `discuss` (the default, and what an old client sends) routes the Draft to
+planning; `record` saves the message without waking the Leader; `develop` asks an
+unplanned Draft to activate now, and reports the exact next step when it cannot
+(already planned → activate manually; execution stopped → start it first). Pass
+`--request-id <key>` to make a submission idempotent: retrying the same key
+returns the original message and routing instead of creating a duplicate, and the
+same key with different text is refused as a conflict.
+
 Resolve all known Projects before repository-backed execution. A stable Project
 checkout is read-only reference state, not the Task base authority. Yui records
 the Task's remote baseline when creating its managed workspace; do not route
@@ -77,26 +92,21 @@ from current ownership and acceptance boundaries. A WorkItem is justified only
 for a substantial independently useful requirement, not for investigation,
 phases, files, tests, reviews, findings, or small repairs.
 
-Keep Review direct by default. Replicated Review is justified only when
-multiple independent inspections materially improve evidence enough to repay
-their coordination cost; it uses at least two Producer Lanes over one frozen
-Assignment and one separate authoritative Reviewer synthesis Turn.
+When directly taking over Task coordination, read
+[yui-leader](../yui-leader/SKILL.md) for execution, review and Integration choices.
+Do not reproduce that scheduling policy in configuration or routing.
 
 ## Prefer the lowest-complexity intervention
 
-When making a Task decision directly, optimize for the lowest total lifecycle
-complexity that satisfies the current contract. Prefer:
-
-- a direct correction over a new workflow layer;
-- reuse of an existing responsibility over another abstraction;
-- a bounded redesign when repeated patches reveal the wrong ownership or
-  boundary; and
-- current demonstrated requirements over speculative future variants.
+Before intervening, read current intent and the existing configuration or
+execution path. An explanation request is not a request to change configuration.
+Distinguish a missing capability from an existing one that was not supplied
+the user's actual environment or context.
 
-Do not ask the user to select an architecture, Worker count, review route,
-retry, cleanup, or other routine legal alternative. The Operator or Leader
-should choose the option with the least implementation, coordination,
-operation, and maintenance burden that still meets acceptance.
+Choose routine legal alternatives yourself, including architecture, allocation,
+review and recovery. Reuse the current authority and primitives when sufficient;
+choose a bounded redesign when the responsibility is wrong. Preserve user-owned
+configuration and external-effect boundaries.
 
 Escalate only a real product tradeoff, new authority, unavailable external fact,
 credential, irreversible effect, or safety boundary.
@@ -147,11 +157,6 @@ Preserve each Role binding's Agent, model, effort, permission, Profile, and
 Session configuration unless the user requests a change. Apply changes only to
 a dormant Role and verify the complete binding before the next launch.
 
-Configured Agents acting as Leader, Worker, Reviewer, or native children are
-normal execution resources. Follow `yui-runtime` for the separate real-resource
-validation boundary. Do not confuse ordinary review or development with using
-a live provider/model as the subject of an E2E test.
-
 ## Present current progress
 
 Use JSON reads and their top-level `data` field. Report the facts needed to
@@ -159,12 +164,12 @@ understand the outcome:
 
 - Task ID, Projects, recorded bases, and lifecycle;
 - current WorkItems, ownership, dependencies, and acceptance state;
-- active and recent Turns with actual Agent/model when recorded;
+- active and recent AgentRuns with actual Agent/model when recorded;
 - latest Worker or Reviewer result and the Leader's disposition;
 - current ChangeSet and Integration state;
 - Brief focus, blockers, open InputRequests, and bounded next action.
 
-A terminal Worker Turn is not accepted delivery. A terminal Review is not a
+A terminal Worker AgentRun is not accepted delivery. A terminal Review is not a
 Leader decision. Describe these states explicitly as awaiting Leader
 disposition. When a Worker, Reviewer, or Integration result has arrived without
 follow-up, route that exact result to the Leader instead of reporting the Task
@@ -184,40 +189,19 @@ with a reason and return the decision to the Leader:
 yui task input cancel <task> <input> --reason "<Leader-owned decision>"
 ```
 
-Never use an InputRequest to solicit permission for unrequested real-resource
-validation. Complete ordinary delivery with deterministic or isolated
-evidence, report the gap, and offer the validation as a separate follow-up.
-
-Immediately after creating, updating, closing, reopening, or merging a PR/MR,
-record the confirmed fact with `yui task publication upsert`; do not defer it
-to another Role or require provider-specific discovery logic. Supply only
-information already known from the operation itself. Use
-`yui task publication verify` after the merge only when current authorization
-covers the external provider read. Track PR/MR identity, state, commits, URL,
-merge time, and evidence—not CI or deployment state. Publication never
-substitutes for Candidate, Review, Integration, acceptance, or Task completion.
-
-Completion does not authorize archive. Report whether the exact Task is
-archive-eligible and obtain user authorization before archiving it. Then use
-`--integrated` for verified merged delivery or `--abandon` for deliberate
-non-delivery. Never infer `--force` authority from general archive approval.
+After an authorized PR/MR operation or before archive, read
+[publication and archive boundaries](../yui-runtime/references/publication.md).
+Record confirmed delivery facts promptly. Completion does not authorize
+archive, and archive approval does not authorize forced cleanup.
 
 ## Recover from evidence, not from imagined states
 
-Read the exact `runtime.agent-error`, Turn, Role Session, ReviewRound, or
-Integration record before intervening. Retry a failed Turn on its existing
-recoverable Session when useful. Replace only the exact Session that the Driver
-proves cannot continue. Preserve failed records as evidence.
-
-Use `yui task next-action <task>` and `yui execution audit` as decision support,
-not autopilot. Advisories about repeated Reviews, WorkItems, checks, quiet
-Sessions, or retained workspaces are cost evidence; they do not authorize
-acceptance, deletion, a new protocol, or automatic recovery.
-
-After repeated failure of the same bounded recovery, summarize the observed
-cause, impact, and smallest remaining options to the user. Do not add a retry
-state machine, create replacement Roles, or broaden cleanup merely to cover a
-hypothetical next failure.
+Read [runtime recovery](../yui-runtime/references/recovery.md) before retrying,
+replacing a Session, resolving unknown input or restarting an unavailable
+Controller. Yui's exact execution cleanup, not manual state editing, enables
+recovery. Retain original intent and evidence.
 
-Never edit Yui's authoritative files, managed refs, tmux Sessions, or worktree
-directories directly.
+For terminal ReviewRound resources, take ownership of the explicit Yui cleanup
+operation or let the Leader do so. A Reviewer must not be expected to clean
+its own runtime after returning its final result. Preserve dirty diagnostics
+and report a real resource boundary rather than broadening cleanup.

package/skills/yui-reviewer/SKILL.md

@@ -5,7 +5,8 @@ description: Review the exact frozen WorkItem Candidate or unified Task-final sc
 
 # Yui Reviewer
 
-Follow `yui-runtime` first and load the exact current Turn Context Pack. The
+Follow [yui-runtime](../yui-runtime/SKILL.md) first and load the exact current
+AgentRun Context Pack. The
 ReviewRound, Candidate, workspace, and Snapshot digest returned there are the
 only review scope; fail closed on any mismatch.
 
@@ -18,50 +19,48 @@ reinterpret its scope:
   anchor.
 
 A Role is an executor, not a workspace owner: each ReviewRound owns an exact
-workspace record. Consecutive Task-final Rounds for the same Reviewer reuse one
-clean physical workspace and native Session while Yui updates the checkout and
-records the new Round snapshot. Treat the new Turn Context Pack and frozen head
+workspace record. Consecutive Task-final Rounds may reuse a clean physical
+workspace and native Session while Yui records each Round's exact snapshot.
+Treat the new AgentRun Context Pack and frozen head
 as the authority even when the conversation continues; never reuse an earlier
 verdict. Review edits are confined to that workspace, never modify the
 WorkItem Develop workspace, and never become a ChangeSet source.
 
-For a dispatched Review, the Turn Context Pack identifies the ReviewRound,
+For a dispatched Review, the AgentRun Context Pack identifies the ReviewRound,
 frozen Project commits, and assigned workspace. Inspect those exact commits.
 The current mutable Task-main checkout is context only and must never replace,
 widen, or silently update the assigned Review scope.
 
-The Turn also identifies the execution shape. A direct Review Turn is the main
-Reviewer and produces the authoritative Review result. In replicated Review,
-a Producer Lane independently inspects the same frozen Assignment in its own
-Lane workspace and returns one complete original result. A Producer result is
-non-authoritative: do not create a Candidate, ChangeSet, integration, or
-completion decision.
-
-Only the main Reviewer synthesis Turn may interpret all stable successful
-Producer results and complete the ReviewRound. Read every exact source Turn's
-original result, inspect every supplied result,
-resolve disagreement through judgment against the frozen sources, and return
-one complete authoritative report. Do not select a winning Lane, mutate
-Producer results, rerun successful Producers, or omit a successful result from
-the synthesis.
+The AgentRun identifies the execution shape. A direct main Reviewer returns
+the authoritative Review report. For a Producer Lane or main synthesis
+assignment, read [replicated execution](../yui-leader/references/replicated-execution.md)
+before acting. Producer evidence is not an authoritative Review result or an
+acceptance decision. Resolve links relative to this Skill's directory.
+
+Clarification for the same ReviewRound may arrive through a Message continuation
+in its exact Context Pack. Preserve the frozen candidate and original results;
+the new execution does not authorize reviewing a newer Task head. Messages for
+an obsolete candidate remain visible but cannot restart the old Review. During
+execution a scoped question may be sent with `task message send <task> "<question>"
+--to leader --review-round <round-id>` (include `--work-item` for WorkItem Review).
 
 ## Separate infrastructure failure from review judgment
 
-Verify the exact Turn identity, Context Pack, frozen head, and ReviewRound-owned
+Verify the exact AgentRun identity, Context Pack, frozen head, and ReviewRound-owned
 workspace before inspecting candidate sources. If context loading or workspace
 binding fails before review begins:
 
 - do not inspect the candidate, run candidate checks, invent findings, accept
   risk, or claim the frozen result was reviewed;
-- return the exact infrastructure diagnosis through the assigned Review Turn;
+- return the exact infrastructure diagnosis through the assigned Review AgentRun;
 - do not recommend a Repair WorkItem—the Leader must recover the same frozen
   review boundary with Yui's projected same-Round `task review retry` or exact
-  `task turn retry`;
+  `task run retry`;
 - if any candidate inspection or Reviewer output did occur, report it
   explicitly so the Leader can judge what remains useful. Core records only
   the execution boundary and never classifies the meaning of this prose.
 
-The Review scope remains the current Turn's frozen candidate even if the Leader
+The Review scope remains the current AgentRun's frozen candidate even if the Leader
 handles new user input or advances Task main while this Review is running. Do
 not switch to the newer head, cancel the current inspection, or claim the
 result covers anything beyond the frozen candidate.
@@ -72,11 +71,8 @@ material defect, or needs a full Review, and explain why. These are recommended
 conclusions for the Leader, not machine-readable dispositions. Never create or
 request a follow-up Round yourself.
 
-Keep the context layers distinct. Yui Core owns ReviewRound identity,
-lifecycle, access, workspace, and exact Turn-result correlation; this generic Skill owns
-portable review behavior; Agent-native Project Skills and Project Policy and
-Knowledge own project-specific checks and review expectations; and the Task
-Contract owns the current outcome, scope, acceptance, and required evidence.
+Use Project Skills, Policy and Knowledge for project-specific checks. The
+Task Contract and frozen scope determine acceptance and required evidence.
 
 Review design complexity against the current Task Contract and reachable
 operating paths. Report abstractions, state, indirection, fallback, or module
@@ -86,17 +82,19 @@ future-proofing merely because they are possible. A focused redesign is
 appropriate when repeated patches expose a wrong responsibility or duplicated
 authority.
 
-Follow `yui-runtime`'s distinction between normal Agent execution and
-real-resource validation. This Reviewer Turn is normal execution; additional
-live-provider, paid, shared, or production validation is not implied.
+Tie each finding to a reachable scenario, violated contract and direct
+evidence. Separate confirmed defects, verification gaps and optional
+improvements. A clean review is valid; do not invent findings to justify the
+Round or change delivery sources to demonstrate a preferred design.
 
 Complete the assigned frozen-scope review before ending the Provider Turn. Accumulate all
 reachable findings, verification gaps, checks actually run, and bounded next
-actions, then return them together in one Review Turn result; do not stop as
+actions, then return them together in one Review AgentRun result; do not stop as
 soon as the first finding is discovered. A review result is evidence for Leader
 judgment; it does not accept the WorkItem or complete the Task. Preserve the
-ReviewRound record and explicitly clean its workspace after the round is
-terminal.
+ReviewRound record and workspace, and report any diagnostic changes. After
+the Round is terminal, an authorized Leader or Operator owns cleanup through
+Yui; do not attempt to terminate or delete your own managed runtime/workspace.
 
 A helpful default result layout is Conclusion, Material findings, Verification,
 Uncertainty, and Recommended next action. Markdown or JSON are both acceptable.
@@ -113,8 +111,9 @@ specific gap; do not rerun an unchanged complete suite for ceremony.
 
 Return each reachable finding to the Leader with direct evidence and a bounded
 route to the original execution unit: Leader-owned work returns to the Leader,
-native work to the same child, and managed work to the same Role and native
-Session. Keep the existing WorkItem when its scope remains open. For a small
+native work to its parent for disposition, and managed work to the owning Role.
+Session reuse is optional; preserve the assignment rather than requiring an
+old conversation to survive. Keep the WorkItem when its scope remains open. For a small
 Task-main fix, return it to the Leader without recommending another WorkItem;
 recommend a Repair WorkItem only when the repair is itself a substantial,
 independently owned requirement. Never capture or integrate the ReviewRound's

package/skills/yui-runtime/SKILL.md

@@ -1,25 +1,43 @@
 ---
 name: yui-runtime
-description: Load and use the authorized context for every Yui-managed Leader, Worker, Reviewer, Operator, or custom Role Turn, and complete that Turn through its bounded control-plane protocol.
+description: Use authorized context, durable results, and recovery boundaries in a Yui-managed Session, including global conversation, direct Leader work, and dispatched AgentRuns.
 ---
 
 # Yui Runtime
 
-Treat the Session Manifest and Turn Bootstrap Envelope as pointers, never as the
+Use this Skill for the shared Yui execution contract. The Role Skill owns
+coordination or delivery judgment; Project Skills, Policy and Knowledge own
+project-specific methods. These instructions grant no additional authority.
+Resolve links relative to this Skill's directory, not the execution workspace.
+
+Treat the Session Manifest and AgentRun Bootstrap Envelope as pointers, never as the
 Task brief. Do not infer Task facts from the launch command, process list,
-workspace layout, native transcript, or an earlier Turn.
+workspace layout, native transcript, or an earlier AgentRun.
+
+## Enter through the current context
+
+There are two normal Task entry points. A user may continue directly with the
+current, unrevoked Leader Session: read current context using the Session CLI
+with `task context <task-id> --json`. Do not request a self-wake, reopen a Task,
+or reuse an old completed AgentRun snapshot merely to obtain authority. Pending
+delivery, unknown execution evidence and missing reports do not themselves
+revoke Session authority. Task lifecycle, scope, Assignment, workspace and
+resource boundaries still apply; a planning Session does not gain delivery
+authority merely because the Task becomes active.
+Use the runtime-provided `TMPDIR` for temporary context or diagnostic files,
+not fixed shared `/tmp` names or the logical multi-Project workspace container.
 
-For every managed Task Turn:
+For every explicitly dispatched managed Task AgentRun:
 
-1. Read the exact Turn identity from the newest Bootstrap Envelope.
+1. Read the exact AgentRun identity from the newest Bootstrap Envelope.
 2. Before acting, load its authorized pack with the Session CLI named by the
    current Session Manifest:
 
    ```sh
-   "$YUI_SESSION_CLI" task turn context "$YUI_TASK_ID/<turn-id>" --json
+   "$YUI_SESSION_CLI" task run context "$YUI_TASK_ID/<run-id>" --json
    ```
 
-3. Verify that the returned Task, Turn, Role, purpose, Snapshot digest, workspace,
+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.
@@ -28,25 +46,35 @@ For every managed Task Turn:
    `refId`:
 
    ```sh
-   "$YUI_SESSION_CLI" task turn context expand "$YUI_TASK_ID/<turn-id>" <ref-id> --store <store> --mode full --json
+   "$YUI_SESSION_CLI" task run context expand "$YUI_TASK_ID/<run-id>" <ref-id> --store <store> --mode full --json
    ```
 
    A bare `<ref-id>` remains supported only when it identifies exactly one
    authorized pointer. If multiple stores use that id, bare expansion fails
    closed; never guess which store was intended.
 
+   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, request only the declared delta after the last pack cursor.
    If no cursor is available, reload the exact pack; do not reconstruct state
    from transcript memory.
 
-`liveTaskState.activeTurns` and `liveTaskState.activeTaskReviews` are
+Loading and verifying Context is the start of the work, not its result. Continue
+with the authorized assignment. In Draft, persist the discussed plan and wait
+when the user asks for alignment; do not end with only a context-loaded receipt.
+
+`liveTaskState.activeRuns` and `liveTaskState.activeTaskReviews` are
 observational views of work currently in flight. They grant no authority and
-create no Task-wide lock or gate; use each exact Turn or Review binding when a
+create no Task-wide lock or gate; use each exact AgentRun or Review binding when a
 decision depends on it.
 
 The pack's authority view and writable Project IDs are hard boundaries. A
-native subagent inherits the parent Turn's refs and authority; it does not gain a
-new Yui actor, Turn, Session, or cross-Task read permission.
+native subagent inherits only its parent's current refs and authority, including
+any Assignment restrictions. It gains no new Yui actor, AgentRun, Session or
+cross-Task read permission.
 
 For a global Operator or custom GlobalRole Session, execute the exact
 `contextProtocol.loadCommand` carried by the current Session Manifest before
@@ -54,9 +82,33 @@ routing or acting. That command is self-contained because a Global Codex Thread
 may move between Yui's remote TUI and Desktop; never reconstruct it from
 `YUI_SESSION_*` process variables.
 
+If that read fails because the Controller is unavailable, use only authorized
+offline diagnostics and [Controller recovery](references/recovery.md) to restore
+access, then reload context. Failure does not grant Task execution authority,
+but a successful preliminary RPC is not a prerequisite for that recovery.
+
 Global context grants no Task implementation workspace. Read a Task only after
 the Operator has routed to its public/task-authorized context command; never
-invent a Task Turn identity for a GlobalRole.
+invent a Task AgentRun identity for a GlobalRole.
+
+## Preserve intent and authority
+
+An analysis, diagnosis, or review request is read-only unless the user also
+requests changes. A request to fix or implement authorizes the bounded work,
+not unrelated configuration, new external effects, or broader cleanup.
+Choose routine legal implementation and recovery actions without asking the
+user to operate Yui mechanically.
+
+Tasks, WorkItems, Messages, Decisions, results and managed workspaces hold
+durable intent and progress. Sessions, AgentRuns and runtime observations
+describe execution; their failure is not failed acceptance or permission to
+discard the assignment. Save context that a successor needs in durable records,
+not only in the native conversation.
+
+The Leader normally owns Task coordination and acceptance. An authorized
+Operator may perform the same legal Task-management actions; responsibility
+is not an extra permission gate. Worker and Reviewer results remain evidence
+until an authorized acceptance decision.
 
 ## Separate execution from real-resource validation
 
@@ -75,15 +127,27 @@ When such validation was not requested, use deterministic or isolated evidence,
 state the material gap, and optionally recommend a separate follow-up. Do not
 create an InputRequest merely to solicit permission for it.
 
-Provider acceptance, Context load, Turn completion, and Task completion are
-separate facts. For a managed Task Turn, end the Provider Turn with one truthful
+## Return evidence and recover within scope
+
+Provider acceptance, Context load, AgentRun completion, and Task completion are
+separate facts. For an explicitly dispatched managed Task AgentRun, end with one truthful
 final report. Yui automatically correlates that native terminal with the exact
-current Turn and persists the report; no completion command is required. The
-Leader alone decides whether the WorkItem or Task is complete.
-
-After a failed Provider Turn, read the referenced `runtime.agent-error` fact.
-The failed Turn is immutable; a recovery is always a new Turn. Continue on the
-same native Session when it remains recoverable, and load only the current Turn
-delta instead of replaying its original Assignment. A new Host process does not
-imply a new Session, and a new Session must never be substituted silently for
-the persisted native Session id.
+current AgentRun and persists the report; no completion command is required. The
+report itself does not accept the WorkItem or complete the Task.
+
+Ordinary native conversation is not an implicit managed assignment and does
+not require a separate execution report. Result Messages reference the
+execution's original report; read them with `task message show <task/message>`
+instead of asking the producer to copy or resend the report.
+
+Session reuse is a preference, not a prerequisite for progress. Before retry,
+replacement, or intervention in uncertain execution, read
+[runtime recovery](references/recovery.md). Preserve pending intent, exact
+runtime identity and workspace progress; never edit Run status or substitute
+a native Session behind Yui's back. A timeout is not proof of quiescence and
+does not authorize replay of unknown input.
+
+After an authorized external PR/MR operation, use the shared
+[publication recording contract](references/publication.md). Recording delivery
+facts does not authorize the external operation, imply acceptance, or grant
+permission to archive.

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

@@ -0,0 +1,22 @@
+# Record external delivery
+
+Use this after creating, updating, closing, reopening or merging a PR/MR
+within existing user authorization. This procedure does not grant permission
+to push, publish, merge, query an external provider or archive.
+
+Immediately record the confirmed operation with `yui task publication upsert`.
+Supply only facts already known from the operation; do not defer recording to
+another Role or depend on provider-specific discovery.
+
+Track PR/MR identity, state, commits, URL, merge time and evidence, not CI or
+deployment status. After merge, use `yui task publication verify` only when
+current authorization covers that external provider read. Otherwise retain
+reported evidence and state the verification gap.
+
+Use `yui task remote-delivery <task>` to explain external delivery. Publication
+is not Candidate acceptance, Review, Integration or Task completion.
+
+Completion does not authorize archive. 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.

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

@@ -0,0 +1,64 @@
+# Runtime recovery
+
+Read this when a native Turn fails, delivery acceptance is unknown, the
+Controller is unavailable, or an authorized supervisor chooses Session
+replacement. Workers and Reviewers report exact evidence; they do not acquire
+supervisor authority by reading this procedure.
+
+## 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.
+
+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.
+
+## Replace a Session deliberately
+
+An authorized Leader or Operator may request:
+
+```sh
+yui task role session new <task> <role> --reason "<reason>"
+```
+
+The old Run may still be active, the Session may already be released, or fresh
+context may simply be preferable. Save necessary requirements, decisions,
+progress and results first. Yui persists replacement intent, stops the exact
+execution and retires its engineering attempts while retaining Task history and
+workspaces. Do not manipulate Run status, delete context or change models to
+make replacement legal.
+
+When replacing yourself, end the native turn. The successor reads durable Task
+context and fixed notification references, then chooses which still-valid
+assignment to continue. Released Leaders retain scoped diagnostic reads but
+cannot regain write authority.
+
+## Handle uncertainty and failed cleanup
+
+Never replay a notification whose acceptance is unknown. After evidence
+establishes shared-native quiescence, an authorized supervisor can use:
+
+```sh
+yui task wake resolve <task> <wake> --reason "<quiescence evidence>"
+```
+
+This releases only the claim, preserves the original unknown record, and lets
+independent later inputs proceed. It neither asserts acceptance nor implements
+the Message. Uncertain native activity still blocks conflicting execution;
+unrelated authorized local work can continue.
+
+If the Controller is unresponsive, an authorized Operator can use
+`controller status` and explicit `controller restart` without a successful
+preliminary RPC. Preserve the resource and restart authorization boundary.
+If exact native stop or inspection fails, read the persisted diagnostic and
+resolve that resource boundary; do not kill arbitrary processes, clear unknown
+execution records, or modify managed refs, tmux Sessions or state files.
+
+After repeated failure of the same bounded recovery, report the observed
+cause, impact and smallest remaining options. Do not broaden cleanup or add
+a private retry loop. A failed recovery does not erase the pending requirement.