@zq-silk/yui 2.20.0 → 2.22.0

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

@@ -0,0 +1,40 @@
+# Incremental context reads
+
+Read before using Task event deltas or frozen Run deltas. This is not required
+for a current read or merely because intent changed. For an apparent conflict,
+read [Current intent](context-ordering.md); the delta itself never grants scope.
+
+## 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.

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

@@ -1,62 +1,9 @@
 # Record external delivery
 
-Use this when routing authorized follow-up delivery or after creating, updating,
-closing, reopening or merging a PR/MR. This procedure does not grant permission
-to push, publish, merge, query an external provider or archive.
-
-## Post-completion routing boundary
-
-An explicit user request to continue implementation or delivery of the same
-completed, unarchived result authorizes its necessary reopening within that
-request's scope. 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 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. Queries, ordinary record/discussion input and Session
-recovery do not authorize resumption. 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.
+Read after an authorized PR/MR operation or before recording, verifying or
+adopting its evidence. This does not authorize push, publish, merge, external
+reads or archive. Reopening and archive have separate action-specific routes
+in [yui-runtime](../SKILL.md).
 
 ## Record and verify the owning Task's publication
 
@@ -135,50 +82,3 @@ decision. Archived history is read-only to these adopt/verify operations.
 
 Use `yui task remote-delivery <task>` to explain external delivery. Publication
 is not Candidate acceptance, Review, Integration or Task completion.
-
-## 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/recovery.md

@@ -1,194 +1,34 @@
 # 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.
-
-### 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, use the deliberate Session
-replacement operation below; 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. Unknown delivery remains fenced for exact
-readback; it is never replayed.
-
-Inspect the current 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. 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.
-
-## 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.
-
-Leader initialization is delivered separately from old inbox handling and
-new queued business. A retained claim cannot block this lifecycle notification.
-The current Leader reads `yui inbox list --view history --json`, then the exact originals and
-prior effects. Claims survive unchanged; use `inbox ack` only after actual
-handling, with the successor's own disposition. Do not claim an already-claimed
-entry again. Repeated reconciliation or Controller restart does not settle
-anything or repeatedly wake an idle handler.
-
-A legally started GlobalRole successor with claims from a previous Session
-receives one Session-pinned recovery Message in its existing inbox. It requests
-the same inspection, not replay of those Messages. A stopped Global Session
-is not started by this notice. Worker/Reviewer Assignment changes still require
-the existing explicit handoff or retirement; no bulk transfer is implied.
-
-Replacement waits for exact native/resource stop and writer release. Missing
-proof requires repairing that observation or a genuinely missing user decision,
-not a timeout, another name, force-ACK or record deletion. Uncertain old
-notification submissions are released from scheduling without replay, retaining
-their fixed wakes and `notification.resolved` evidence. They become explicitly
-inspectable/settleable, not automatically accepted or resubmitted.
-
-## 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.
-
-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.
-
-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.
+Read before retry, Session replacement or intervention in failed/uncertain
+execution. Workers and Reviewers report exact evidence; reading recovery
+instructions grants no supervisor authority.
+
+Preserve pending intent, original input, exact execution identity, workspace
+progress and resource ownership. Never replay unknown native/external effects,
+edit Run status or substitute a Session behind Yui. A timeout, quiet observation
+or failed attempt proves neither stopped execution nor failed business
+acceptance. Recovery grants no new Task, model, account or resource authority.
+
+Read only the complete procedure for the action actually needed:
+
+- **Failed native Turn/launch, configuration/model-name failure, Provider retry
+  or manual successor:** [Failed execution](execution-failure.md). Inspect the
+  exact failure and current retry projection before choosing an attempt; do not
+  duplicate Controller-owned recovery.
+- **Deliberate authorized Session replacement:** [Session replacement](session-replacement.md).
+  Failure alone does not require replacement. Preserve successor context and
+  exact stop/writer proof; replacing yourself ends the native turn.
+- **Unknown delivery, unavailable Controller or failed cleanup:**
+  [Execution uncertainty](uncertain-execution.md). Diagnostic access needs no
+  preliminary successful RPC; restart/cleanup still needs its existing authority.
+- **Host protocol/custody or persistence failure, or Host replacement during
+  an upgrade:** [Host custody](host-custody.md). An ordinary Controller outage
+  alone does not trigger this procedure.
+
+Several actions may apply: read each triggered procedure, not every branch.
+Follow further links only at their stated action. For retained input claims,
+failed ACK or Session-successor handling, also use
+[Inbox recovery](inbox-recovery.md); recovery notices do not settle inputs.
+After recovery inspect prior work and external receipts before continuing;
+preserve unresolved facts rather than broadening cleanup or adding retry loops.

package/skills/yui-runtime/references/session-identity.md

@@ -0,0 +1,18 @@
+# Desktop and managed Session identity
+
+Desktop commands may carry only `CODEX_THREAD_ID`. The CLI resolves that native
+identity against the selected Home's current and historical Session records before
+routing operations. An unknown provider thread with no Yui-specific identity hints
+is an ordinary public caller, like a user terminal; it needs no managed Manifest
+to read public information or create a Draft Task. This does not start discussion
+or development or grant internal managed capabilities. Public command availability
+is not user authorization for a new effect.
+Environment and Manifest values are location hints, not continuing grants.
+Conflicting, partially specified, unregistered Yui identities and known historical
+or revoked Sessions do not become public callers. An ID known only in another
+Home cannot be recognized from the selected Home alone: keep the intended
+Home/Manifest context rather than switching Homes or dropping hints.
+`inbox list` reports the resolved managed identity. Do not add or clear
+environment fields to repair a mismatch. Without a Manifest environment pointer,
+`session skills` returns current Skill paths and the Session's captured profile.
+

package/skills/yui-runtime/references/session-replacement.md

@@ -0,0 +1,45 @@
+# Deliberate Session replacement
+
+Read before an authorized Session replacement, not merely because a Turn failed.
+Apply the common boundaries in [Runtime recovery](recovery.md) first.
+
+## 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.
+
+Leader initialization is delivered separately from old inbox handling and
+new queued business. A retained claim cannot block this lifecycle notification.
+The current Leader reads `yui inbox list --view history --json`, then the exact originals and
+prior effects. Claims survive unchanged; use `inbox ack` only after actual
+handling, with the successor's own disposition. Do not claim an already-claimed
+entry again. Repeated reconciliation or Controller restart does not settle
+anything or repeatedly wake an idle handler.
+
+A legally started GlobalRole successor with claims from a previous Session
+receives one Session-pinned recovery Message in its existing inbox. It requests
+the same inspection, not replay of those Messages. A stopped Global Session
+is not started by this notice. Worker/Reviewer Assignment changes still require
+the existing explicit handoff or retirement; no bulk transfer is implied.
+
+Replacement waits for exact native/resource stop and writer release. Missing
+proof requires repairing that observation or a genuinely missing user decision,
+not a timeout, another name, force-ACK or record deletion. Uncertain old
+notification submissions are released from scheduling without replay, retaining
+their fixed wakes and `notification.resolved` evidence. They become explicitly
+inspectable/settleable, not automatically accepted or resubmitted.

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

@@ -0,0 +1,29 @@
+# Unknown execution and unavailable Controller
+
+Read for unknown delivery, an unavailable Controller or failed exact cleanup.
+Apply the common boundaries in [Runtime recovery](recovery.md) first.
+
+## 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.

package/skills/yui-worker/SKILL.md

@@ -8,8 +8,10 @@ description: Complete a bounded Yui WorkItem AgentRun or native child assignment
 Follow [yui-runtime](../yui-runtime/SKILL.md) first, including its per-turn
 version/availability check and conditional full reload. For a managed AgentRun,
 load its exact Context Pack and
-use only the returned WorkItem, refs, workspace, writable Project IDs, and
-completion actions. The launch Envelope is a pointer, not an execution brief.
+use the returned WorkItem, workspace, writable Project IDs, and completion
+actions as execution boundaries. Ordinary relevant evidence reads follow
+Runtime's resource access rules; they never expand the Assignment.
+The launch Envelope is a pointer, not an execution brief.
 
 Complete the assigned WorkItem, or the bounded parent brief for a native child
 without its own WorkItem. Do not create records merely to fit this Skill.
@@ -36,8 +38,9 @@ Report genuine scope conflicts to Leader; older stage-only wording is not a
 new prohibition after a legally authorized handoff.
 
 Leader clarification and continuation arrive as Messages in the exact bounded
-Context Pack. Read those authorized refs; do not request pack-external Leader
-messages or require redispatch/status changes merely to answer a question.
+Context Pack. Read those refs and relevant current originals without requiring
+redispatch/status changes merely to answer a question. Reading another
+Assignment's message does not adopt or acknowledge it.
 Continuation preserves the original Assignment, effective permissions and
 workspace, including unfinished files. If you need clarification, preserve
 those files and report the question; a final question is not WorkItem completion

package/skills/yui-worker/VERSION

@@ -1 +1 @@
-3
+4