@zq-silk/yui 2.21.0 → 2.23.0

package/docs/managed-turn-and-session-runtime.md

@@ -2,6 +2,99 @@
 
 # Session, AgentRun and notifications
 
+## Two lifecycle layers and nonblocking checks
+
+Controller custody of a Host and the Host's native Session lifecycle have
+separate event/guard/transition tables. Neither is an upgrade workflow.
+
+| Layer | Events and transitions | Authority and correlation |
+| --- | --- | --- |
+| Controller → Host | Fresh physical observations recover `unavailable`/`stopped`/`starting`/`running`. Authorized launch enters `starting`; matching launch handshake enters `running`. Stop or graceful-exit request enters `stopping`; sending exit does not prove `stopped`. Physical absence confirms `stopped`; unknown effects enter `unavailable`. | Owner, local operation/revision, returned binding and native Session ID. Durable Role/Task intent, launch reservations and exact process custody remain authoritative. |
+| Host → native Session | Launch, attachment, input acceptance, native activity, terminal, persistence, disconnect and exit drive the native states described below. | Native Session, proxy process, attempt and Turn identity; existing writer/resource fences still authorize effects. |
+
+The Controller wraps the shared Host port for launch/restore, observation and
+stop, including graceful-upgrade exit. A competing physical operation is
+rejected before its side effect, not queued or replayed by this FSM. Late
+reads and old bindings cannot overwrite newer custody; identical observations
+produce no hook feedback loop. A Controller restart reconstructs by observation,
+never by replaying the process-local state. Native completion/attachment exit
+does not prove Host process exit. Legal same-conversation resume correlates the
+layers without sharing their state enums or inventing another durable authority.
+
+Host-side native Session lifecycle state is owned by an explicit transition table, not
+by version detection. Launch/submit enters `starting`; attachment facts select
+`idle`, `busy`, `ready` (owned input), or `delivery-unknown`; acceptance enters
+`ready`; native execution enters `busy`; terminal handling enters `settling`;
+persisted settlement returns to observed `idle`/`busy`. Disconnect enters
+`starting`, classified failures retain their failure outcome, and exit enters
+`exited`. Only an explicit launch can leave `exited`. Native-TUI attachment
+readiness has its own event: `ready` there is not proof of native quiescence.
+Illegal edges do not mutate state; stale process, attempt and terminal-Turn
+facts are ignored. Exact writer/resource guards remain at command admission.
+This process-local reducer reconstructs from existing launch and native facts;
+it adds no persisted Session authority or upgrade workflow state machine.
+
+Optional before/after observations are immutable, deferred and independently
+coalesced (at most one running and one latest pending observation per check).
+“Before” describes the transition's source, not an awaited precondition.
+A slow or failing check cannot veto a transition or hold event folding/input
+delivery; checks must yield for I/O and honour cancellation before effects.
+They may recommend work to the separate fenced upgrade coordinator.
+Controller Host-state hooks suggest version reconciliation. Host Session-state
+hooks asynchronously observe current Skill metadata on attachment/settlement,
+without reading Skill bodies, committing a notice or assuming model memory.
+The exact per-input integrity check remains an ingress safeguard: invalid
+Skills can reject that input, but an optional check cannot stall lifecycle.
+Only accepted input advances the existing notice baseline; unchanged input
+is passed through without any extra content.
+
+Controller startup, Host connection/exit observations, Host state-change
+signals and event persistence trigger version checks without an explicit
+`update` request. Existing periodic reconciliation covers missed hints,
+including providers without reliable background-execution-end events and
+graceful exits that cannot emit a post-exit hint. Checks
+compare actual loaded Host/Endpoint implementations with this Controller's
+loaded target, never npm `latest`. Incomplete readiness on matching versions
+is not an upgrade reason. Checks stop on shutdown; already-admitted work
+retains the existing durable mailbox. A request pinned to a different target
+stays waiting for explicit recovery, not silent retargeting. An explicitly
+stopped Session is never restarted by a check.
+
+## Host upgrade and context checks
+
+`update` reports package installation, verified Controller startup and each
+Host separately. `update --hosts-status` reads current per-Host evidence without
+installing, starting or advancing a switch. Supported controlled Codex Hosts fence new input immediately,
+wait for the current native Turn and event persistence, inspect native background
+execution, and release their owned Endpoint before exiting gracefully. The
+existing role-runtime mailbox retains the exact generation, native Session,
+configuration digest and drain receipt across Controller restarts. A successor
+uses the recorded effective configuration and resumes that same conversation;
+only its loaded Host/Endpoint and control/event handshake confirm success.
+Queued Messages remain original and accepted/unknown inputs are never replayed.
+
+Paused Roles stay paused. Older Hosts, native-TUI-only attachments and Endpoints
+without a quiescence capability are retained with an unsupported diagnosis; no
+unsupported drain command is sent. A busy/unknown native execution has no
+bounded upgrade-completion promise. An uncertain launch is not automatically
+repeated; a later exact successful handshake can settle the retained request.
+This fence covers Host-controlled ingress, not arbitrary external native clients;
+it never terminates a shared daemon or native conversation.
+
+Host Skill checks still run before every input. Unchanged inputs are passed
+through exactly, with no notice, marker, separator or extra native input part.
+The attachment's loading guidance explains this managed-input contract; no
+notice is not a reason to repeat the check. Unmediated clients or uncertain
+current input routing retain the explicit Manifest check fallback; reusing a
+conversation alone does not establish Host mediation. Cold attachment,
+affected Skill changes and observed native compaction supply loading guidance;
+compaction invalidates the next input's metadata baseline. Without a reliable
+native event, the Agent must still recover any missing instructions using the
+Manifest. Neither a version nor an accepted notice proves model memory.
+Routine checks and empty inboxes are not user-facing progress.
+
+## Session stop and runtime observations
+
 Global Session stop/replacement uses the same exact native-execution quiescence
 boundary as Task Sessions. A departed Host or archived Session alone is not
 proof that an accepted input ended: its retained Provider binding is inspected
@@ -29,9 +122,23 @@ submitting, unknown and interrupt-owned input still retain their handling path.
 scopes, phase/read costs and sampled event-loop lag are separate facts.
 Samples use a process-monotonic clock and hashed target/request labels, with
 at most 16 recent and 16 active samples plus the slowest completed sample.
-In-flight request count is not queue depth, and pre-routing wait is not
-measured. These observations neither identify an old incident retroactively
-nor establish quiescence; restarting a Controller does not refresh live Hosts.
+In-flight request count is not queue depth; total client-to-route wait is not
+measured by the server alone. These observations neither identify an old incident
+retroactively nor establish quiescence. A Controller restart does not itself
+prove Host replacement; asynchronous lifecycle checks still require a safe
+drain and the successor's actual handshake.
+
+`observations.commands.routes.transport` correlates socket accept-to-route,
+complete-frame receive-to-route and route-to-local-flush stages by the same
+request hash as route service time. A close before the response finishes is a
+failed transport observation, even if the business handler later succeeds.
+Client socket failures retain local monotonic connect/write/first-response/end
+timestamps in `details.diagnostic.controller.timing`; null means not observed.
+Match the request ID's SHA-256 prefix before comparing these with server stages.
+These are local events, not peer acknowledgement or pure kernel queue time.
+The interval before the server's accept callback includes unobserved socket and
+event-loop delay; sampled lag alone cannot attribute it to a scheduler phase.
+No timeout, coherence check, receipt, retry or stop/start policy is changed.
 
 `observations.persistence` separates main-thread database lock/body/commit
 costs from persistence-worker round trips, worker execution and worker reads.
@@ -54,6 +161,24 @@ admission and other lifecycle writes still require their own boundary analysis.
 Status responsiveness during these maintenance operations is not proof that
 every possible Controller stall has been eliminated.
 
+The worker-backed runtime drain reads its immutable inbox files asynchronously,
+as does native-Session discovery during launch. The 64-event fold limit is not
+a limit on the initial directory scan: a large retained backlog must not be
+read synchronously on the socket thread before that limit takes effect.
+Sorting, per-file validation, event identities, fold order and commit-before-ACK
+remain unchanged. This trades some backlog throughput for control responsiveness;
+it is not a bound on total backlog memory or every CPU operation. Synchronous
+producer deduplication and explicit worker-off drains still need separate
+boundary analysis.
+
+Controller stop retains the captured PID/start-generation fence through both
+graceful drain and physical recovery. If the ownership inventory is unreadable,
+a protected Home-validated discovery can retain that fence, but cannot authorize
+a signal. No physical match is not proof of exit: before allowing successor
+startup, the captured generation must be provably gone. A still-live generation
+times out; unavailable generation evidence refuses recovery. Explicit physical
+stop still revalidates UID, entrypoint, Home, PID and start identity before signalling.
+
 Idle Global inbox recovery and already-settled retry checks use read-only
 snapshots, without reserving SQLite's writer. Creating a recovery notice or
 settling an outstanding retry still rechecks the current Session/claim/input
@@ -85,12 +210,17 @@ pin a read snapshot, uncommitted writes cannot publish a reusable cache token,
 and only 16 recent Task projections are retained. Cache entries never authorize
 dispatch or replace exact mutation-time checks.
 
-A newly created global Operator conversation requests the native title
-`Yui · Operator · MMdd`, using Yui's configured time zone. The request is made
-only after the provider returns the exact new conversation identity; restore
-and reconnect paths never replay it. Providers without a post-create rename
-capability keep the usable Session and expose a diagnostic instead of treating
-metadata failure as Session-creation failure.
+Role instance codes and generated Session/planning titles are Yui presentation
+metadata, using Yui's configured time zone where a date is included.
+Managed Codex retains this launch title but does not submit native title
+synchronization, including on restore and reconnect. This intentional omission
+is logged locally, not emitted as a failed operation or recovery notification.
+An unsubmitted name is never persisted as an applied native title; the native
+conversation and business execution remain usable.
+The native title mutation has been observed to persist without replying and
+block later Goal/Turn requests, even with a separate metadata client. Automatic
+synchronization must not be restored merely by increasing a timeout or retrying
+an unknown write; it requires a verified nonblocking native path.
 
 ## Authority
 
@@ -177,14 +307,27 @@ continuations and the complete-original reading protocol.
 Run Context freezes Assignment, source references, effective configuration and
 workspace boundaries. A Role edit does not rewrite an existing Assignment.
 Reading either Context does not acknowledge input or create execution authority.
-Every managed input points to the exact Session Manifest and CLI entry. The
+Initial or changed managed input points to the exact Session Manifest and CLI entry. The
 Run Pack is a reference directory: read the relevant requirement and message
 bodies before acting, rather than treating a successful load as the deliverable.
 Planning Packs expose no Project write scope or Task-completion permission.
 
-The Manifest pointer is a recovery locator, not a read receipt. At the start of
-every turn run `yui session skills --json` through the Session's CLI/Home. It
-checks current paths, internal `VERSION` files and readability, without reading
+The Manifest pointer is a recovery locator, not a read receipt. The managed Host
+checks current paths, internal `VERSION` files and readability before submit/steer,
+including the native Operator TUI relay. Unchanged inputs carry a short check
+notice, not repeated Skill lists or a request for another Agent tool call.
+The ordinary notice is only a check result: it does not repeat compaction or
+loading procedures. Those belong to the launch contract and event-specific
+entry guidance. After lost context, reconstruct the current working set from
+the Runtime/Role entry points and references applicable to the next action;
+do not restore the union of every procedure used earlier in the conversation.
+This is instruction routing, not a claim that the Host detects compaction,
+can evict old text, or knows what the model remembers.
+First input, changed metadata and Host reattachment/recovery supply current pointers.
+Only confirmed Provider acceptance advances the Host-local notice state; failures
+and unknown submissions do not. This state is ephemeral, not a loading receipt.
+Unmediated clients retain `yui session skills --json` through their Session CLI/Home.
+The check operates without reading
 Skill bodies or walking/snapshotting resources. Builtins use the running
 installation's `skills/<id>` entry; configured Skills use `YUI_HOME/skills/<id>`.
 These paths do not contain a Session/content digest. After changing installation
@@ -200,6 +343,8 @@ compacted/uncertain context. Reuse only when versions are unchanged and the full
 instructions remain available now. Yui stores no "already read" state and does
 not claim to inspect the model's context. Historical packages remain audit only;
 missing/corrupt snapshots do not prevent valid Session resume or input delivery.
+Provider compaction is not reliably observable here: missing instructions still
+require Agent-directed reload even when engineering reports unchanged versions.
 Missing current files report their exact path and recovery action. Session
 identity, scope, writer fences and real CLI/Home incompatibility still reject.
 Always refresh dynamic facts. Leader notifications use
@@ -411,7 +556,7 @@ The three failure ingresses retain their native fencing/classification, while
 record creation and deduplication share one writer and supervisor notices use
 the existing event-routing boundary.
 
-Unknown Leader notifications preserve their wake and input window:
+Unknown or rejected Leader notifications preserve their wake and input window:
 
 ```sh
 yui task wake show <task> <wake>
@@ -419,14 +564,20 @@ yui task wake resolve <task> <wake> --reason <quiescence-evidence>
 ```
 
 Resolve releases the claim after native-effect fences are clear. It neither
-replays the notification nor invents acceptance or completion. Independent
+replays the notification nor invents acceptance or completion. A rejection,
+including one recorded after an unknown outcome, is not quiescence evidence.
+If an execution stop removed the operational mailbox, the exact durable
+notification attempt can still be explicitly released for inbox inspection
+and handling; a different current batch is never released. Missing delivery
+evidence is refused, not guessed. Original delivery events and handling claims
+remain unchanged; a repeated resolve adds no second disposition. Independent
 Role work and legal local facts are not a Task-wide recovery lock.
 
 Wake status records notification delivery, not Message implementation. For
 ordinary Leader notifications, `consumed` means native acceptance. Native Turn
 completion and Task delivery need their own runtime evidence and durable results.
-A rejected wake stays `dispatched` with its claim until explicit retry or Session
-replacement; an explicitly released historical wake can remain `dispatched`
+A rejected wake stays `dispatched` with its claim until explicit retry, no-replay
+resolve or Session replacement; an explicitly released historical wake can remain `dispatched`
 without a claim. Unknown acceptance cannot use `wake retry`.
 Session replacement preserves queued input for a new wake and current Context;
 it does not retroactively mark an old wake accepted. Late receipts cannot settle
@@ -725,10 +876,15 @@ Goal `stalled` alone neither establishes the cause nor warrants clearing Goal.
 
 In this candidate, `task wake retry` requires a proven-rejected, unconsumed
 exact claim, a corrected cause and no accepted/uncertain native execution.
-`task wake resolve` supports an unknown exact claim after shared-native
-quiescence; it releases scheduling without replay or semantic acknowledgement.
-Deferred delivery meets neither precondition. Do not assume another recovery
-package's extended behavior is installed. For Global Roles, this candidate
+As an alternative, not a sequence, `task wake resolve` supports an unknown or
+rejected exact notification attempt after shared-native/background/writer
+quiescence and persisted evidence; rejection (including after unknown) is not
+quiescence. It releases scheduling without replay or semantic acknowledgement.
+If the operational mailbox is absent, exact durable wake/attempt evidence is
+still required; another current batch is never released. Original claims,
+delivery events and saved alerts remain unchanged. Deferred delivery meets
+neither precondition. Refresh current installed capabilities before acting.
+For Global Roles, this candidate
 does not establish a dedicated targeted Host-stop command: inspect original
 input/control and `session retry <role> show`, then discover current authorized
 capabilities. There is no guessed Task equivalent or stop-all fallback.

package/docs/managed-turn-and-session-runtime.zh-CN.md

@@ -2,6 +2,74 @@
 
 # Session、AgentRun 与通知
 
+## 两层生命周期与非阻塞检查
+
+Controller 对 Host 的管理状态、Host 对原生 Session 的生命周期分别拥有自己的
+事件、guard 和转换表，都不是升级流程状态机。
+
+| 层级 | 事件与转换 | 权限及关联 |
+| --- | --- | --- |
+| Controller → Host | 新鲜物理观测恢复 `unavailable`／`stopped`／`starting`／`running`；合法 launch 进入 `starting`，匹配启动握手进入 `running`。停止或优雅退出请求进入 `stopping`，发送退出不证明 `stopped`；物理不存在才确认 `stopped`，未知效果进入 `unavailable`。 | owner、本地操作／观测 revision、返回 binding 和原生 Session ID；持久 Role／Task 意图、启动 reservation 和精确进程权属仍是权威。 |
+| Host → 原生 Session | launch、附件、输入接受、原生活动、终态、持久化、断连和退出驱动下述原生状态。 | 原生 Session、proxy 进程、attempt 和 Turn 身份；原有 writer／资源栅栏继续授权副作用。 |
+
+Controller 在共享 Host port 处统一管理启动／恢复、观测与停止（含安全升级的优雅退出）。
+冲突物理操作在副作用前拒绝，不由状态机另建队列或重放。迟到读取和旧 binding 不能覆盖
+新管理状态；相同观测不重复触发检查反馈循环。Controller 重启后从观测重建，
+不重放进程内状态。原生轮次完成或附件退出不能证明 Host 进程已退出；
+合法恢复通过同一原生对话关联两层，不共用状态枚举或新增持久权威。
+
+Host 内的原生 Session 生命周期由明确的转换表管理，不由版本检查管理。
+launch／submit 进入 `starting`；附件事实选择 `idle`、`busy`、
+`ready`（持有输入）或 `delivery-unknown`；接受输入进入 `ready`；
+原生执行进入 `busy`；终态处理进入 `settling`；持久化结清后回到观测到的
+`idle`／`busy`。断连进入 `starting`，分类失败保留对应失败状态，退出进入
+`exited`，只有显式 launch 可离开它。原生 TUI 附件就绪有独立事件，
+其 `ready` 不证明原生执行静止。非法边不改变状态；过期的进程、attempt、
+终态 Turn 事实被忽略。精确 writer／资源 guard 仍在命令准入处执行。
+状态机仅在进程内从现有 launch 和原生事实恢复，不新增持久 Session 权威或升级流程状态机。
+
+可组合的前／后检查接收不可变观测，各自异步执行并合并重复提示
+（每项最多一个执行中和一个最新待处理观测）。“前”表示转换来源，不是等待完成的前置条件。
+慢检查或失败不能否决转换、阻塞事件折叠或输入投递；检查回调必须异步等待 I/O，
+并在请求副作用前响应取消。它们只能向独立的、受精确栅栏保护的升级协调器提出请求。
+Controller 的 Host 状态 hook 提议版本对账；Host 的 Session 状态 hook 在附件和结清时
+异步观测当前 Skill 元数据，不读正文、不提交通知基线、不假定模型记忆。
+逐输入完整性核验仍是投递安全门：无效 Skill 可以拒绝该次输入，但可选检查不能卡住生命周期。
+仍只有被接受的输入推进通知基线，未变化输入原样通过，不额外注入内容。
+
+Controller 启动、Host 连接／退出观测、Host 状态变化 signal 和事件持久化均可触发版本检查，
+不依赖显式 `update`。现有周期对账覆盖丢失提示、无法可靠提供后台执行结束事件的提供方，
+以及无法在退出后发出提示的优雅退出。
+比较对象是实际加载的 Host／Endpoint 实现与当前 Controller 已加载的目标，不查询 npm `latest`。
+版本匹配但就绪证据未齐不是升级理由。关闭时停止检查，已准入工作仍保留现有持久 mailbox；
+请求固定的目标与当前 Controller 不同时保持等待，交由显式恢复，不静默改目标。
+检查不会复活明确停止的 Session。
+
+## Host 升级与上下文检查
+
+`update` 分别报告程序安装、Controller 启动核验及逐 Host 的状态。
+`update --hosts-status` 只读查询逐 Host 证据，不安装、启动或推进切换。支持此能力的
+受控 Codex Host 先关闭新输入准入，等待当前原生轮次和事件持久化、核验后台执行，
+释放自己持有的 Endpoint 后优雅退出。现有 role-runtime mailbox 保存精确实现代际、
+native Session、配置摘要和排空回执，Controller 重启后仍可继续。
+后继使用原 effective 配置接回同一对话；实际加载的 Host/Endpoint、控制与事件能力
+握手通过后才确认成功。队列中的 Message 原文不变，不重放 accepted 或 unknown 输入。
+
+暂停角色保持暂停。旧 Host、仅有原生 TUI 的附件及不能证明静止的 Endpoint
+保留并报告不支持，不反复发送不支持的排空命令。忙碌或未知执行不承诺限时升级。
+启动结果未知不自动重放；后续精确成功握手可结清原请求。
+准入栅栏覆盖 Host 控制的入口，不控制任意外部原生客户端，也不会终止共享 daemon 或原生对话。
+
+Host 仍逐输入机械检查 Skills。未变化时原文原样通过，不添加检查通知、隐藏标记、
+分隔换行或原生输入片段。附件加载指引说明这一托管输入约定，不因没有通知而重复检查。
+绕过 Host 的客户端或当前输入路由不明时仍通过 Manifest 显式检查；复用同一对话
+本身不证明当前输入受 Host 托管。首次附件、局部 Skill 变化、已观测到的原生压缩
+提供相应加载指引；压缩使下一次输入的元数据基线失效。
+提供方无法可靠暴露事件时，Agent 仍须通过 Manifest 恢复缺失指令。
+版本和已接受的通知都不能证明模型记忆；例行检查、角色版本和空 inbox 不作为用户进度播报。
+
+## 会话停止与运行时观测
+
 局部停止等待自身的持久清理义务完成，不等待整个 Home 的 `scheduler.scan`
 循环排空。signal 只请求调度；完成仍以现有物理停止证明及清理事务为准。
 超时保留义务并阻止替换；选择失败和新会话启动未确认分别报告，不允许重放未知效果。
@@ -14,8 +82,20 @@ interrupt-owned 输入仍保留原处理路径。
 `controller status --json` 的 `identity.runtime.observations` 分别呈现已认证请求、
 调度待处理范围、阶段／读取成本及采样的事件循环延迟。样本使用进程单调时钟，
 目标／请求标签仅保存哈希；每组最多保留 16 个近期样本、16 个活动样本及最慢完成样本。
-in-flight 请求数不是排队数，路由前等待尚未测量。观测不能反推旧事故的唯一根因，
-也不构成静止证明；重启 Controller 不会刷新存活 Host。
+in-flight 请求数不是排队数，服务端不能独自测量客户端到路由的完整等待。
+观测不能反推旧事故的唯一根因，
+也不构成静止证明；Controller 重启本身不证明 Host 已替换，
+异步生命周期检查仍须经过安全排空和后继实际握手。
+
+`observations.commands.routes.transport` 使用与 route service time 相同的请求哈希，
+分别关联 socket accept→route、完整帧 receive→route、route→本地 flush。
+响应完成前连接关闭会记录 transport 失败，即使业务 handler 随后成功。
+客户端 socket 失败在 `details.diagnostic.controller.timing` 保留单调时钟的
+connect／write／首个 response／end 时间戳；null 表示未观测到。
+比较服务端阶段前须匹配 request ID 的 SHA-256 前缀。这些是本地事件，
+不是对端确认或纯内核排队时间。服务端 accept callback 之前仍有未观测到的
+socket／事件循环延迟，不能仅凭采样 lag 归因到某个调度阶段。
+timeout、coherence、receipt、重试及 stop/start 策略均未改变。
 
 `observations.persistence` 将主线程数据库锁等待／事务体／提交成本，与持久化
 worker 的往返耗时、执行和读取成本分开。worker 摘要搭载既有响应，保留 worker
@@ -31,6 +111,18 @@ worker 的往返耗时、执行和读取成本分开。worker 摘要搭载既有
 隔离：启动准入、邮箱领取、到期 Job 准入及其他生命周期写入仍需分别分析边界。
 这些维护操作期间状态请求可响应，不代表 Controller 的所有长停顿都已消除。
 
+worker 模式的 runtime drain 改用异步读取不可变 inbox 文件，启动时的原生 Session
+发现也使用同一路径。64 条折叠上限不限制前置目录扫描，不能在该上限生效前，
+先在 socket 主线程同步读取整个积压。排序、逐文件校验、事件身份、折叠顺序及
+先提交后 ACK 保持不变。这以部分积压吞吐换取控制面响应，不构成总积压内存或
+全部 CPU 操作的上限；同步生产者去重及显式关闭 worker 的 drain 仍需分别分析。
+
+Controller stop 在优雅停止和物理恢复两条分支都保留所捕获的 PID／启动代次。
+所有权扫描不可读时，经权限及 Home 校验的 discovery 可以保留该代次约束，但
+不能据此发信号。未找到物理匹配不等于已退出：允许启动后继前，必须证明原代次
+已消失；仍活着则超时，代次证据不可读则拒绝恢复。显式物理停止在发信号前，
+仍复核 UID、入口、Home、PID 及启动代次。
+
 空闲 Global 收件箱恢复检查、已处分的重试检查使用只读快照，不申请 SQLite
 写锁。真正创建恢复通知或处分未完成重试时，仍在原写事务内复核当前
 Session／claim／输入。这消除的是空操作等锁，不是所有实际写入的竞争。
@@ -90,10 +182,13 @@ Provider binding，再结算执行占用。Global 停止证据保存为仅记录
 不触发新的原生输入。待投递通知不能重启已明确停止的 Session；普通 Host 脱离仍
 保留 active Session，可正常重连。部分切换失败后，仍须先结算旧输入再选择新会话。
 
-新建 global Operator 对话会按 Yui 当前配置时区请求原生标题
-`Yui · Operator · MMdd`。只有 Provider 返回新对话的确切身份后才执行该请求；
-恢复与重连路径不会重放。若 Provider 不支持创建后改名，已创建的 Session 仍保持
-可用，并留下诊断，而不会把元数据失败冒充为 Session 创建失败。
+Role 实例码及生成的 Session／规划标题属于 Yui 展示元数据；包含日期时采用当前
+配置时区。托管 Codex 保留 launch 标题，但不提交原生标题同步，恢复与重连也不提交。
+这一有意省略只写本地日志，不作为失败操作或恢复通知；未提交的标题不能记作已应用的
+原生标题，原生对话与业务执行保持可用。
+原生命名曾出现写入已生效却无回执、随后 Goal/Turn 请求阻塞的情况，独立元数据
+连接也未解决。恢复自动同步需要验证不会阻塞执行的原生路径，不能仅增加超时或重试
+结果未知的写入。
 
 ## 权威
 
@@ -137,8 +232,16 @@ Run Context 冻结 Assignment、来源引用、生效配置和工作区边界。
 和消息正文，而不是把加载成功当成交付物。规划 Pack 不暴露 Project 写范围或 Task 完成
 权限。
 
-Manifest 指针是恢复定位入口，不是已读凭据。每轮开始通过本 Session 的 CLI/Home 执行
-`yui session skills --json`，轻量检查当前路径、内部 `VERSION` 和文件可读性，不读取
+Manifest 指针是恢复定位入口，不是已读凭据。managed Host 在 submit/steer 前检查，
+原生 Operator TUI 代理也使用同一逻辑。普通未变化输入仅附短检查提示，不重复清单、
+不要求 Agent 再发工具调用；首次、元数据变化和 Host 重连／恢复才给当前入口。
+普通提示仅是工程检查结果，不逐轮重发压缩或加载操作说明；这些说明属于启动契约和
+事件触发的入口引导。丢失上下文后，从 Runtime／Role 入口和当前动作适用引用重建工作集，
+不恢复历史上用过的全部流程。这是指令路由，不声称 Host 能识别所有压缩、移除历史文本
+或判断模型记忆。任务原文和必要新鲜状态仍按业务需要读取。
+只有 Provider 明确接受才推进 Host 进程内的通知状态，失败与未知提交不推进；
+它不是持久化加载收据。不经过该 Host 的客户端仍通过本 Session CLI/Home 执行
+`yui session skills --json`。检查当前路径、内部 `VERSION` 和文件可读性，不读取
 正文或遍历/冻结资源。内置入口是当前安装目录的 `skills/<id>`，自定义入口是
 `YUI_HOME/skills/<id>`，不包含 Session/内容摘要；安装位置变化后由检查重新解析当前入口。
 Global Manifest 的 `skillCheckCommand` 使用自包含的 `session context <role>`，
@@ -147,6 +250,8 @@ Global Manifest 的 `skillCheckCommand` 使用自包含的 `session context <rol
 首次进入、版本变化、恢复，以及压缩后全文缺失或可用性不确定时，读取当前 Runtime、
 Role/custom Skills 全文及必要引用、Manifest 的 profile。只有版本未变且全文仍在当前
 上下文时才复用。系统不保存“已经读过”状态，也不声称检查了模型上下文。
+当前接口不能可靠观察 Provider 压缩；即使工程报告版本未变，Agent 发现指令缺失时
+仍须补读，不能将未发变化提示当作全文仍在的证明。
 历史冻结包仅作审计：缺失或损坏不阻止合法 Session 恢复与消息投递；当前文件缺失则
 报告具体路径和修复动作。身份、作用域、writer fence 与实际 CLI/Home 不兼容仍会拒绝。
 动态事实仍须刷新：
@@ -302,19 +407,23 @@ retry 把被拒绝批次及后续排队输入交回现有 mailbox，不把旧 wa
 工作区条目或当前 Session 引导协议。三类错误入口保留各自的原生身份检查与分类，
 错误创建、去重统一一个写入入口，上级通知统一使用事件路由边界。
 
-未知的 Leader 通知保留其唤醒和输入窗口：
+未知或被拒绝的 Leader 通知保留其唤醒和输入窗口：
 
 ```sh
 yui task wake show <task> <wake>
 yui task wake resolve <task> <wake> --reason <quiescence-evidence>
 ```
 
-resolve 在原生效果围栏清除后释放该认领。它既不重放通知，也不编造接受或完成。独立的
+resolve 在原生效果围栏清除后释放该认领。它既不重放通知，也不编造接受或完成。
+被拒绝（包括先 unknown 后 rejected）不等于已经静止。执行停止移除临时 mailbox 后，
+仍可依据该 wake 的精确持久投递 attempt 显式释放，以便在 inbox 检查和结清；
+不得释放另一当前批次。缺失投递证据时拒绝猜测。原始投递事件与处理认领保持不变，
+重复 resolve 不增加第二次处分。独立的
 Role 工作和合法的本地事实不是一把 Task 范围的恢复锁。
 
 wake 状态记录通知投递，不记录 Message 的实施结果。普通 Leader 通知的 `consumed`
 表示原生接受；原生 Turn 完成与 Task 交付应分别依据运行证据和持久结果判断。
-被拒绝的 wake 保持 `dispatched` 并保留 claim，直到显式重试或 Session 替换；
+被拒绝的 wake 保持 `dispatched` 并保留 claim，直到显式重试、无重放 resolve 或 Session 替换；
 已显式释放的历史 wake 可以保持 `dispatched` 而不占用 claim。
 接受状态未知的通知不能用 `wake retry` 重放。Session 替换把待投递输入
 保留给新 wake 与当前 Context，不会追溯把旧 wake 标成已接受；旧回执也不能结算
@@ -536,9 +645,12 @@ Host 中尚未持久化的事实。stop 请求保存不等于物理清理成功
 仅显示 Goal stalled 不能确定根因，也不能据此要求清 Goal。
 
 本候选的 `task wake retry` 仅适用已纠正原因、原准确 claim 仍未消费的明确 rejected，
-且不能存在已接受或不确定原生执行；`task wake resolve` 仅支持准确 unknown claim
-在共享原生静止证明后释放调度，不重放、不 ACK。deferred 不满足二者前提，不能假定
-其他恢复包的扩展行为已经安装。GlobalRole 未确认有专用准确 Host-stop 命令时，读取
+且不能存在已接受或不确定原生执行。另一可选动作是 `task wake resolve`：准确 unknown
+或 rejected 通知 attempt 在共享原生／后台／writer 静止及持久证据确认后释放调度，
+不重放、不 ACK。两者不是自动依次执行的步骤；rejected（包括 unknown 后的拒绝）
+不等于静止。operational mailbox 缺失时仍须精确持久 wake/attempt 证据，不能释放
+另一当前批次。原始处理认领、投递事件与已保存告警不改写。deferred 不满足二者前提，
+执行前刷新实际安装能力。GlobalRole 未确认有专用准确 Host-stop 命令时，读取
 原输入/control 和 `session retry <role> show`，再发现当前权限下的能力；不臆造
 Task 等价命令，也不退化为 stop-all。
 

package/docs/provider-retry.md

@@ -25,6 +25,17 @@ next input. Agents still own semantic recovery and acceptance.
   accepted failed Turn and original input. The error need not have qualified
   for automation; manual intent does not waive Session, authority, latest-Turn
   or background-quiescence checks.
+- A current-owner manual execution retry can recover that same failed Turn
+  across a message continuation and subsequent retries only when the durable
+  chain proves every intervening attempt was rejected before a Provider write.
+  Session, authority, Assignment, launch configuration and workspace must match.
+  It carries the current continuation input, not the earlier business directive,
+  and preserves the original automatic budget. Missing proof or any intervening
+  accepted/unknown input leaves ordinary admission fenced.
+- Once that exact recovery is accepted, its Agent can claim and acknowledge
+  the original continuation Message through the same verified lineage. This
+  is handling authority, not another delivery: recipient, continuation target,
+  prior claims and failure records stay unchanged; no Message is requeued.
 
 The records live on the existing Provider binding, with indexed pending-record
 reads and the existing Controller deadline timer. There is no retry Task status,

package/docs/release-workflow.md

@@ -51,6 +51,65 @@ merely to avoid a version decision. Package versions remain distinct from protoc
 and persistent-storage contracts: their compatibility checks and required migrations
 are unchanged, and the storage rules below do not authorize a package release.
 
+### 2.23.0 compatibility and migration notes
+
+Host upgrades use explicit lifecycle signals and safe drain/reattachment
+boundaries without replaying business input or replacing native identity.
+Routine Skill checks remain inside the Host; unchanged Turns carry no Skill
+notice. Cold attachment, explicit context loss/compaction and changed Skills
+provide only the current loading pointers.
+
+Codex keeps original user input separate from application context on start and
+steer. Failed-Turn recovery does not duplicate the original input or imply lost
+Skill context. This requires the native `additionalContext` contract verified
+against Codex CLI 0.159.2; older native implementations are not covered and there
+is no fallback that reinserts metadata into user input.
+
+Native titles reuse the Role/Task/Draft/instance format through an independent,
+bounded metadata process, never blocking Startup, Goal or Turn. Exact identity,
+persisted intent and native readback distinguish confirmed naming from unknown
+effects. Observed manual names are preserved; unknown writes are not replayed.
+Historical polluted names without ownership evidence are diagnosed, not renamed.
+The native naming API has no compare-and-swap, so a final concurrent external
+rename cannot be protected atomically.
+
+Storage advances to **1.28**, preserving **1.26 → 1.27** Host-upgrade signals and
+adding **1.27 → 1.28** native-title receipts without rewriting history. Back up
+the Home and use the normal upgrade/migration path; do not open a migrated Home
+with an older binary. Controller/Host protocols remain v1. Publishing does not
+update the global CLI, migrate production data or restart shared services.
+
+### 2.22.0 compatibility and migration notes
+
+Context reads now support bounded discovery, precise batched original retrieval,
+body transport receipts and focused notifications. Runtime/Role Skills organize
+required material around actions and recovery after compaction; pointers and
+transport receipts never prove semantic reading or acknowledge an input.
+Full originals remain available. Automated consumers must follow explicit
+pagination and retrieval references rather than assuming every default response
+contains every body. Help is focused by default; consumers needing the complete
+recursive command tree must explicitly request recursive help, including JSON
+consumers affected by the changed child projection.
+
+Host restoration and Controller scheduling/SQLite transaction boundaries are
+bounded without replaying unknown effects. Codex Host native title mutation is
+omitted where it could stall execution; Yui presentation retains Role instance
+codes and planning markers, but an unapplied native title is not recorded as
+success. Codex temporary-directory exclusion options are preserved end to end.
+
+Storage advances to **1.26** through the centralized **1.25 → 1.26** migration;
+the already-published 1.24 → 1.25 migration is unchanged. Back up the Home and
+use the normal upgrade/migration path; do not open a migrated Home with an older
+binary. Controller/Host protocols remain v1. Publishing this version does not
+update the global CLI, migrate a production Home or restart its services.
+
+The maintained evaluation entry is `scripts/eval/`, with shared infrastructure
+separate from context-specific logic. Context guidance and historical analyses
+live under `docs/evaluations/context/`; the old `scripts/collaboration-eval/`
+entry is retired. Engineering gathers measurements; Agents interpret actual
+experimental and production traces, including compaction boundaries and missing
+evidence. Local output reductions are not a claim of universal token savings.
+
 ### 2.21.0 compatibility and migration notes
 
 Ordinary Task, Assignment and frozen-context evidence reads now use the local
@@ -870,6 +929,12 @@ and timeout hierarchy. A no-target activation, help, `--json`, and every other
 command remain on the global CLI. Activation does not add another ordinary CLI
 routing path.
 
+Activation's two storage preflights use the verified target's existing read-only
+upgrade primitive in an isolated process, not its ordinary inactive CLI entry.
+The target must be installed in this Home with matching integrity and smoke
+evidence before each preflight. This neither migrates storage nor permits an
+inactive release or checkout CLI to read/write the Home through ordinary commands.
+
 ## Step catalog
 
 The plan is a fixed, predeclared subset of operations. Each plan entry has an

package/docs/release-workflow.zh-CN.md

@@ -36,6 +36,50 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 不能将不兼容冒称为兼容，也不为回避版本选择新增历史兼容机制。包版本与协议、
 持久存储契约仍然独立：兼容性检查和必要迁移要求不变，下文存储规则不授予发版权限。
 
+### 2.23.0 兼容性及迁移说明
+
+Host 升级使用明确的生命周期信号及安全排空／重新挂接边界，不重放业务输入、
+不替换原生会话身份。常规 Skill 检查保留在 Host 内，未变化的 Turn 不携带
+Skill 提示；仅首次挂接、明确上下文丢失／压缩及 Skill 变化提供当前加载指针。
+
+Codex 的 start／steer 将用户原文与应用上下文分离。失败 Turn 恢复不复制原文，
+也不视为 Skill 上下文丢失。此路径要求原生 `additionalContext` 契约，已核对
+Codex CLI 0.159.2；旧原生实现不在验证范围内，不提供把元信息塞回用户输入的回退。
+
+原生标题复用 Role／Task／Draft／实例格式，通过独立、有界的元数据进程同步，
+不阻塞 Startup、Goal 或 Turn。精确身份、持久化意图和原生读回区分成功与未知效果。
+保留已观测到的手动命名，未知写入不重放；缺乏归属证据的历史污染标题只诊断、不改名。
+原生命名 API 没有 compare-and-swap，无法原子保护最后读写窗口内的外部并发改名。
+
+存储升级至 **1.28**：保留 **1.26 → 1.27** Host 升级信号迁移，追加
+**1.27 → 1.28** 原生标题回执，不改写历史。升级前备份 Home，使用正常升级／迁移
+路径，不要用旧二进制打开已迁移的 Home。Controller/Host 协议仍为 v1。
+发布本身不更新全局 CLI、不迁移生产数据，也不重启共享服务。
+
+### 2.22.0 兼容性及迁移说明
+
+上下文读取增加有界发现、精确批量原文读取、正文传输回执及聚焦通知。
+Runtime／Role Skill 按动作组织必需材料，并明确上下文压缩后的恢复路径；
+指针和传输回执不证明语义阅读，也不自动 ACK。完整原文仍可获取。
+自动化调用方应遵循明确的分页和原文入口，不再假定默认返回包含全部正文。
+help 默认聚焦当前命令；需要完整递归命令树时须明确请求递归 help，
+使用 JSON 的调用方也应适配子命令投影变化。
+
+Host 恢复、Controller 调度及 SQLite 事务边界改为有界处理，不重放未知效果。
+Codex Host 在可能阻塞执行的路径省略原生标题变更；Yui 展示保留 Role 实例码及
+planning 标记，但不会将未应用的原生标题记为成功。Codex 临时目录排除选项
+贯穿配置及启动链路保留。
+
+存储通过集中式 **1.25 → 1.26** 迁移升级至 **1.26**；已发布的 1.24 → 1.25
+迁移不变。升级前备份 Home，并使用正常升级／迁移路径；不要用旧二进制打开
+已迁移的 Home。Controller/Host 协议仍为 v1。发布本版本本身不更新全局 CLI、
+不迁移生产 Home，也不重启服务。
+
+受维护的评测入口为 `scripts/eval/`，公共基础设施与上下文专属逻辑分离；
+上下文指导及历史分析位于 `docs/evaluations/context/`，旧
+`scripts/collaboration-eval/` 入口退役。工程负责数据统计，Agent 根据实验和
+线上实际轨迹分析，包括压缩边界及证据缺失；局部输出减量不代表普遍 token 收益。
+
 ### 2.21.0 兼容性及迁移说明
 
 普通 Task、Assignment 和冻结上下文证据读取改按本地资源边界处理，不再将 Task
@@ -647,6 +691,10 @@ CLI、Operator Session 和 Controller 替换保持兼容，而不必把每个命
 `dist/cli.js`。因此目标发布拥有完整的交接协议和超时层级。一次无目标的激活、help、
 `--json` 以及其他每个命令都留在全局 CLI 上。激活不新增另一条普通 CLI 路由路径。
 
+激活的两次存储预检在隔离子进程中调用已验证目标包现有的只读升级原语，不经过目标包
+尚未激活的普通 CLI 入口。每次预检前都要求目标已安装于此 Home，且完整性及冒烟回执
+匹配。这既不迁移存储，也不允许 inactive release 或源码 checkout 的普通命令读写 Home。
+
 ## 步骤目录
 
 计划是一个固定、预先声明的操作子集。每个计划条目有一个 id（工作流内唯一）、一个