@zq-silk/yui 2.17.0 → 2.19.0

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

@@ -11,6 +11,80 @@ notifications cannot restart an explicitly stopped Session; normal Host detach
 preserves an active Session and remains reconnectable. A switch after a partial
 failure still settles the retained input before selecting a new conversation.
 
+Local stop waits for its durable cleanup obligation, not for the Home-wide
+`scheduler.scan` loop to empty. A signal only requests reconciliation; the
+existing physical-stop proof and cleanup transaction remain the completion
+boundary. A timeout retains the obligation and blocks replacement. Selection
+failure and unconfirmed startup are reported separately; neither permits
+replaying an uncertain native operation.
+
+`operator status` and Session context distinguish desired/effective launch
+revisions and selected-writer state from Host observation health. Old-conversation
+failures remain audit evidence, not the new Session's current failure.
+An exact rejected input can be explicitly retired when obsolete; accepted,
+submitting, unknown and interrupt-owned input still retain their handling path.
+
+`controller status --json` exposes bounded observations under
+`identity.runtime.observations`: authenticated requests, scheduler pending
+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.
+
+`observations.persistence` separates main-thread database lock/body/commit
+costs from persistence-worker round trips, worker execution and worker reads.
+Worker summaries travel on existing replies and retain a worker-instance ID;
+status reads only cached facts, never performs a diagnostic worker RPC.
+Match hashed request targets when comparing round trip and execution. The
+difference includes startup, queueing, transport and main-loop delay, not a
+pure queue-time measurement. Nested database/read durations overlap worker
+execution and must not be added to it. Historical maxima may belong to other
+requests; the latest/slowest samples retain their own timestamps.
+
+With the default persistence worker, periodic Project-sync configuration checks,
+expired Input recommendations and run-progress/stall diagnostic transactions
+execute on that worker as complete read/check/write operations. Their callers
+await completion; lock waiting does not block the socket thread. Existing
+transaction fences and idempotent folds remain unchanged. Explicit worker-off
+mode and injected adapters retain synchronous behavior. This is not blanket
+isolation of all database writes: launch admission, mailbox claims, due Job
+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.
+
+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
+inside the original write transaction. This removes no-op lock waits, not
+contention from actual writes.
+
+Production Controller startup (including handover promotion) retains operational
+diagnostics in `runtime/controller-diagnostics.jsonl`, with two rotated files.
+Each file is bounded to 1 MiB and owner-readable/writable only. An asynchronous
+writer admits at most 32 queued records (16 KiB each); it never writes the
+business database. Scheduler/startup errors retain a classification, fingerprint
+and build-relative source frames, not raw messages, arguments or credentials.
+A 250 ms memory-only sampler records new failed/slow observations (at least
+1 second), active slow work or its own loop delay at most once per second.
+Records carry wall time, monotonic time, PID, process-instance ID and version;
+bounded phase snapshots retain hashed request/target identities. It is sampled
+evidence, not a trace of every request or the exact cause of pre-routing delay.
+`observations.diagnostics` reports written/dropped/pending records and write
+failures. No successful diagnostic write is assumed when storage fails.
+Rotation, queue overflow and abrupt termination can lose evidence; a blocked
+loop cannot emit a snapshot until it resumes. No automatic restart or operation
+replay is introduced. These disposable operational logs are not Task state,
+acceptance, a second recovery authority or a Home schema migration.
+
+Scheduler caches load families lazily and use transaction-maintained Task
+read revisions. Another Task or Global message does not invalidate an unchanged
+Task history; updates, deletions and external writers still do. Compound folds
+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
@@ -569,3 +643,99 @@ Operator storage diagnosis/upgrade also reaches the dedicated migration entry
 without first requiring the Home to already have the target storage version.
 Completion, cancellation and archive have distinct authority and resource
 boundaries. Storage changes use the single [upgrade contract](sqlite-control-plane-design.md).
+
+## Message delivery health
+
+The Controller's existing full reconciliation observes Task Role notification
+mailboxes, Assignment continuations, Global Role input and the Operator attention
+mailbox. It reads the real `pending` suffix separately from `processing`, never
+the compatibility `getPendingWakeup` projection. It does not run an Agent polling
+loop, acknowledge input, release a claim, resend an uncertain input or start an
+unavailable Operator.
+
+`yui controller status --verbose --json` exposes a cached, timestamped
+`identity.runtime.observations.messageHealth` view (the Controller RPC exposes
+`runtime.messageHealth`). It includes counts, oldest wait/occupancy, exact
+Session/attempt/wake/message references, answered input references, recorded
+delivery outcome, retry ownership and the existing Host reconciliation evidence.
+`unobserved` is not proof of Host health. Inspect its exact Event/Message read
+commands for durable originals. Status reads perform no database scans or probes.
+The view shows at most 64 owners and reports omissions; records remain readable
+through the existing Task event and Global Role message commands after restart.
+
+An eligible stalled delivery warns after 5 minutes and escalates once at
+30 minutes, or after 15 minutes if the queue at least doubles and reaches eight
+items. A single old input is sufficient. Sampling is on the configured full-pass
+interval (default 120 seconds, permitted 5–300 seconds): with a responsive
+Controller, detection occurs on the first completed pass after the threshold.
+These are not wall-clock delivery guarantees during downtime, blocked I/O or
+unavailable Providers. Accepted long Turns without contrary exact Host evidence
+are busy, not faults; explicit stops, disabled Roles, human ownership, native
+pause and matching open input waits are distinct from blocked delivery. Valid
+bounded retry remains owned by its existing recovery mechanism. Historical
+missing ACKs without a new waiting suffix do not generate backlog alerts.
+
+Each affected delivery owner has one open diagnostic episode: at most a warning,
+one escalation and a backlog-clear observation. Concurrent arrivals coalesce;
+they do not each call a model. Task evidence uses ordinary `message.health.<role>`
+Events; Global evidence uses record-only system Messages. These are append-only
+content in the existing open Event/Message formats, not a new storage envelope,
+schema version or scheduling aggregate. The newest evidence reconstructs
+notification deduplication after restart. Each notice reuses the ordinary
+Operator Global Message queue with a stable request ID, independent of the
+affected Task's occupied mailbox. Only one unsent engineering notice is admitted;
+later evidence stays durable and is reconsidered on subsequent full passes.
+
+If Operator is absent/stopped/uncontrolled, evidence remains generated but no
+new Session is started. If it is busy, the notice stays saved; failures retain
+their exact message and reason and are not replayed. Diagnostics distinguish
+generated evidence, saved notice, transport acceptance, Provider delivery and
+explicit handling. An alert ACK is never recovery. Only an observed empty
+delivery backlog closes an episode; an explicit pause or merely releasing the
+old processing claim while a pending suffix remains does not. Backlog clearance
+itself proves neither business handling nor completion, and grants no recovery
+authority. Moving all pending work to a new processing owner is not clearance:
+retained processing with a deferred delivery remains observable, including its
+exact attempt and rejection detail, even when the current Turn is completed.
+
+### Management recovery guidance
+
+Notices include the current observation time, exact identities, original read
+commands and conditional recovery guidance, also available in the cached
+`recovery` field. A notice delayed by Operator unavailability uses current facts
+when it is finally saved, not the original incident's intervention advice.
+Already-saved notices remain immutable evidence and are not resent merely to
+update advice: always refresh status and exact Session/wake/message evidence
+before acting. A command template is neither authorization nor proof that a
+later invocation still targets the observed Session; current CLI fences apply.
+
+An affected Leader is supervised by Operator; a subordinate Task Role by its
+authorized Leader or Operator. Normal busy work, legitimate pause and owned
+bounded retry receive non-intervention guidance. For an established retained
+Task Host barrier, the supervisor may consider the existing targeted
+`task role session stop` path without waiting for a complete engineering repair
+or perfect historical projections. Inspect exact native/background execution,
+event persistence, authority and cleanup consequences first. Unpersisted Host
+facts must not be destroyed. A saved stop request is not successful physical
+cleanup; retain failure evidence when cleanup cannot be proven. Existing
+authorized lifecycle/delivery may reuse the retained conversation after proven
+stop; verify its identity. Deliberate `task role session new` is a different,
+explicit replacement decision, requiring durable progress and fenced cleanup.
+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
+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.
+
+On refusal or failure, preserve the exact receipt, original inputs and work,
+and escalate only the missing authority, capability or cleanup evidence.
+Verify management request, physical stop, conversation reuse/replacement,
+actual subsequent Provider acceptance and business handling separately.
+Missing evidence remains unverified; no automatic recovery, replay, forced
+ACK, model/account/permission change or Controller-wide restart is introduced.

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

@@ -2,6 +2,57 @@
 
 # Session、AgentRun 与通知
 
+局部停止等待自身的持久清理义务完成，不等待整个 Home 的 `scheduler.scan`
+循环排空。signal 只请求调度；完成仍以现有物理停止证明及清理事务为准。
+超时保留义务并阻止替换；选择失败和新会话启动未确认分别报告，不允许重放未知效果。
+
+`operator status` 与 Session context 区分 desired/effective 配置版本、选定写入者
+状态和 Host 观测健康。旧会话失败保留为审计证据，不是新会话的当前失败。
+明确 rejected 的过时输入可以显式退役；accepted、submitting、unknown 和
+interrupt-owned 输入仍保留原处理路径。
+
+`controller status --json` 的 `identity.runtime.observations` 分别呈现已认证请求、
+调度待处理范围、阶段／读取成本及采样的事件循环延迟。样本使用进程单调时钟，
+目标／请求标签仅保存哈希；每组最多保留 16 个近期样本、16 个活动样本及最慢完成样本。
+in-flight 请求数不是排队数，路由前等待尚未测量。观测不能反推旧事故的唯一根因，
+也不构成静止证明；重启 Controller 不会刷新存活 Host。
+
+`observations.persistence` 将主线程数据库锁等待／事务体／提交成本，与持久化
+worker 的往返耗时、执行和读取成本分开。worker 摘要搭载既有响应，保留 worker
+实例标识；status 只读缓存观测，不另发诊断 RPC。比较往返和执行时间时须匹配
+同一个请求哈希，其差值还包括启动、排队、传输和主线程延迟，不是纯排队时长。
+嵌套的数据库／读取耗时已包含在 worker 执行中，不能重复相加；历史最大值可能
+来自其他请求，latest／slowest 样本保留各自时间戳。
+
+默认启用持久化 worker 时，周期性 Project-sync 配置检查、到期 Input 建议执行、
+运行进展及停滞诊断事务，作为完整的读／检查／写操作在 worker 内执行，调用方等待
+完成；等锁不再阻塞 socket 主线程。既有事务校验和幂等折叠保持不变。
+显式关闭 worker 或注入自定义 adapter 时仍沿用同步行为。这不是全部数据库写入的
+隔离：启动准入、邮箱领取、到期 Job 准入及其他生命周期写入仍需分别分析边界。
+这些维护操作期间状态请求可响应，不代表 Controller 的所有长停顿都已消除。
+
+空闲 Global 收件箱恢复检查、已处分的重试检查使用只读快照，不申请 SQLite
+写锁。真正创建恢复通知或处分未完成重试时，仍在原写事务内复核当前
+Session／claim／输入。这消除的是空操作等锁，不是所有实际写入的竞争。
+
+生产 Controller（含升级接管后的启动）将运行诊断保存至
+`runtime/controller-diagnostics.jsonl`，另保留两个轮转文件，每个最多 1 MiB，
+仅文件所有者可读写。异步写入器最多排队 32 条记录，每条最多 16 KiB，
+不写业务数据库。调度及启动错误只保留分类、指纹和构建内相对源码位置，
+不保留原始错误正文、参数或凭据。每 250 ms 仅检查内存指标；出现新的失败／
+至少 1 秒慢操作、仍在进行的慢操作或自身事件循环延迟时，每秒最多记录一次快照。
+记录包含墙钟、单调时间、PID、进程实例及版本，阶段摘要使用请求／目标哈希。
+这是采样证据，不是逐请求追踪，也不直接证明路由前阻塞原因。
+`observations.diagnostics` 显示写入、丢弃、待写数量和写入失败；磁盘故障不伪装为
+记录成功。轮转、队列溢出、突然终止均可能丢失证据，主线程恢复前也无法输出快照。
+不新增自动重启或操作重放。这些可丢弃运行日志不是 Task 状态、验收依据的替代物、
+第二套恢复权威或 Home 数据格式迁移。
+
+调度缓存按需加载记录族，并使用事务维护的 Task 读取修订号。其他 Task 或 Global
+消息不会使未变化的本 Task 历史失效；更新、删除、其他进程写入仍正确失效。
+组合折叠固定在一个读取快照，未提交写入不产生可复用缓存标识，最多保留最近
+16 个 Task 的投影。缓存不授权派发，也不替代变更时的精确身份检查。
+
 ## 当前身份与持久处理回执
 
 桌面与 TUI 使用相同的当前 Session 授权。只有 `CODEX_THREAD_ID` 的桌面命令
@@ -429,3 +480,68 @@ Task。Operator 诊断和 Controller 重启不先要求一个健康的 Controlle
 也能到达专用的迁移入口，而不先要求 Home 已经处于目标存储版本。完成、取消和归档具有
 彼此不同的权限和资源边界。存储变更使用唯一的
 [升级合同](sqlite-control-plane-design.zh-CN.md)。
+
+## 消息投递健康度
+
+Controller 在既有 full reconciliation 中观察 Task Role 通知 mailbox、
+Assignment continuation、Global Role 输入及 Operator attention mailbox。
+分别读取真实 `pending` 后缀与 `processing`，不把 `getPendingWakeup` 的兼容投影
+当作底层队列；不启动 Agent 私有轮询、不自动 ACK、释放占用或重放未知输入。
+
+`yui controller status --verbose --json` 的
+`identity.runtime.observations.messageHealth` 提供带采样时间的缓存诊断；Controller RPC 对应
+`runtime.messageHealth`。可查看数量、最老等待与占用时长、精确 Session/attempt/wake/
+message、已回答输入、投递证据、重试归属与既有 Host 核对结果。`unobserved` 不代表
+Host 健康。按其中的 Event/Message 读取命令核对持久原始证据。状态读取不会扫描数据库
+或发起探测；最多展示 64 个 owner 并显式报告省略数量，重启后原始记录仍可读取。
+
+符合异常条件的投递等待在 5 分钟后预警，30 分钟后最多升级一次；若队列至少翻倍且达到
+8 条，可在 15 分钟后提前升级。仅一条长期不推进的输入也会检测。采样复用 full-pass
+间隔（默认 120 秒，可设 5–300 秒），健康响应的 Controller 在超过阈值后的首次完整
+检查发现；停机、I/O 堵塞和 Provider 不可用期间不保证墙钟时限或即时送达。没有精确
+Host 反证的 accepted 长 Turn 视为忙碌；显式停止、Role 禁用、human 所有权、原生
+暂停、匹配的未回答输入等待单独区分。有效的有界重试仍由既有恢复机制拥有。只有历史
+缺 ACK、没有新待投递后缀，不会生成积压告警。
+
+按受影响的投递 owner 合并一个未关闭异常，最多保存预警、升级和积压消除三个阶段，
+并发到达不会逐条调用模型。Task 使用普通 `message.health.<role>` Event，Global
+使用 record-only system Message，都是既有开放内容格式中的追加证据，不新增存储
+envelope、schema 或调度权威。最新证据用于重启后的去重。告警使用稳定 request ID，
+走独立于受影响 Task 占用的 Operator Global Message 通道；最多保留一条未发送的
+工程通知，其余待告警证据持久保留并在后续 full pass 检查。
+
+Operator 缺席、已停止或没有受控 binding 时，不自动创建 Session；忙碌时保留已保存
+通知，失败时保留原 Message 和原因、不重放。诊断区分已生成证据、已保存通知、传输
+接受、Provider 送达与显式处置。告警 ACK 不关闭异常。只有观察到投递积压消失才记录
+恢复；显式暂停、或仅释放旧 processing 但 pending 仍在，不算恢复。积压消除也不证明
+业务处理完成、Task 验收或获得任何额外恢复权限。
+pending 全部转入新 processing owner 也不算清除：即便当前 Turn 已完成，持续 deferred
+的 processing 仍保留监测及精确 attempt、投递拒绝详情。
+
+### 管理恢复引导
+
+通知直接包含当前观测时间、精确身份、原始读取命令及有前提的恢复引导，缓存诊断的
+`recovery` 字段也提供同一引导。Operator 不可用导致延迟保存的通知使用保存当时的
+当前观测，不复制旧异常的操作建议；已保存通知不重写，也不为更新建议重复发送。
+执行前必须刷新 status 和准确 Session/wake/message 原始证据。命令模板不是授权，
+也不能固定未来调用的目标身份；实际操作仍受现有 CLI 围栏约束。
+
+Leader 自身受阻由 Operator 处理，下属 Task Role 由有权限的 Leader 或 Operator
+处理。正常忙碌、合法暂停、有界重试仍拥有恢复时，不推荐打断。确认 Task Host 遗留
+占用后，可评估已有准确 `task role session stop` 管理路径，不必等待完整工程修复包
+或所有历史投影对齐；先核对准确原生/后台执行、事件持久化、权限和清理影响，不能丢失
+Host 中尚未持久化的事实。stop 请求保存不等于物理清理成功，失败时保留原证据。
+证明停止后，既有授权生命周期/投递可在支持时复用原 conversation，须验证实际身份。
+`task role session new` 则是另行明确选择新 Session，需保存进展并通过清理围栏。
+仅显示 Goal stalled 不能确定根因，也不能据此要求清 Goal。
+
+本候选的 `task wake retry` 仅适用已纠正原因、原准确 claim 仍未消费的明确 rejected，
+且不能存在已接受或不确定原生执行；`task wake resolve` 仅支持准确 unknown claim
+在共享原生静止证明后释放调度，不重放、不 ACK。deferred 不满足二者前提，不能假定
+其他恢复包的扩展行为已经安装。GlobalRole 未确认有专用准确 Host-stop 命令时，读取
+原输入/control 和 `session retry <role> show`，再发现当前权限下的能力；不臆造
+Task 等价命令，也不退化为 stop-all。
+
+动作拒绝或失败后，保留精确回执、原输入和工作区，只升级缺失的权限、能力或清理证据。
+分别验证管理请求、物理停止、原会话复用/显式替换、后续实际 Provider 接受及业务处置；
+缺证据仍标为未验证。不新增自动恢复、重放、强制 ACK、模型/账号/权限变更或全局重启。

package/docs/release-workflow.md

@@ -51,6 +51,69 @@ 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.19.0 compatibility and migration notes
+
+This minor adds message backlog and blocked-delivery monitoring with Operator
+alerts (PR #492). Observations distinguish live work, paused execution and bounded
+retry from stalled delivery, retain original evidence, and deduplicate alerts
+across Controller restarts. Alerts include evidence-matched management guidance:
+inspect the exact input and execution first, distinguish rejected retry from
+unknown-result resolution, and require scoped stop proof or explicit replacement
+authority where applicable. Monitoring never retries, stops or replaces execution
+automatically; an alert is not recovery authority or proof of a unique root cause.
+
+Storage remains **1.24**, and Controller/Host protocols remain v1. Existing
+messages and events are preserved; this release adds no storage migration.
+Older supported Homes still use the centralized contiguous migration chain.
+With separate update authority, the Operator verifies the published artifact
+then runs `yui update --version 2.19.0`. Compatible live Sessions are retained;
+publishing alone does not update the installed program or recover other Tasks.
+Exact-merge Core CI and the same tarball's fresh-install platform/Node matrix
+remain release gates. These checks do not establish real-model behavior.
+
+### 2.18.0 compatibility and migration notes
+
+This minor includes the already-merged independent Jobs workspace and global
+Shell script Jobs (PR #490), plus Controller reliability and diagnostics.
+Exact Session stop/replacement no longer waits for unrelated global scheduling
+to drain. Stop proof, single-writer ownership and unknown-input replay fences
+remain required. Session health distinguishes historical failures from the
+current authority; conclusively rejected obsolete inputs can be retired without
+erasing their original evidence.
+
+Task-scoped lazy read caches, indexed observation queries and persistence
+timings reduce projection work and separate request/worker/database costs.
+With the default persistence worker, periodic maintenance lock waits no longer
+block the socket thread; idle Global recovery and settled retry checks are
+read-only. Actual admission and other business writes may still contend.
+Bounded, redacted asynchronous diagnostics retain incident evidence in
+`runtime/controller-diagnostics.jsonl` and two rotated files. These changes
+address reproduced mechanisms, not a proven unique cause of every historical
+timeout. See [managed runtime](managed-turn-and-session-runtime.md).
+
+Storage advances from **1.22 through 1.23 to 1.24**: 1.23 declares revisioned
+global Shell script definitions and Run snapshots; 1.24 adds Task read-revision
+tokens and triggers without rewriting historical payloads. A production 1.21
+Home first applies the existing 1.22 Role/Profile availability transition.
+Use the centralized contiguous same-major migration, never manual schema edits.
+Controller RPC and Host control/event protocols remain v1. Compatible live
+Hosts/Sessions are retained, not hot-upgraded; unreported Host capabilities and
+unknown results remain explicit.
+
+With separate production authority, the Operator uses
+`yui update --version 2.18.0` after verifying the published artifact. Refresh a
+consistent maintenance backup and capture the current executable/Controller
+identity before migration. An earlier online DB snapshot alone is not a complete
+rollback point and cannot overwrite subsequently accepted input. Do not open a
+1.24 Home with an older binary; rollback requires the matching pre-upgrade
+program and consistent Home backup, with intervening effects reconciled.
+
+Release gates require exact-merge-commit Core CI and the same runtime archive's
+fresh-install platform/Node matrix before npm publication. Local deterministic
+tests and prior smoke evidence do not replace those gates or prove real-model
+behavior. Publication does not itself update a production Home or resolve
+another Task's execution.
+
 ### 2.17.0 compatibility and migration notes
 
 This minor adds persistent Role/Profile enable and disable controls in CLI and

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

@@ -36,6 +36,50 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 不能将不兼容冒称为兼容，也不为回避版本选择新增历史兼容机制。包版本与协议、
 持久存储契约仍然独立：兼容性检查和必要迁移要求不变，下文存储规则不授予发版权限。
 
+### 2.19.0 兼容性及迁移说明
+
+本 minor 新增消息积压、投递阻塞监测及 Operator 告警（PR #492）。观测区分正常执行、
+暂停、有界重试与投递停滞，保留原始证据，并跨 Controller 重启去重告警。
+告警包含按证据匹配的管理恢复引导：先检查精确输入和执行状态，区分明确拒绝后的
+retry 与未知结果的 resolve，并在需要时要求精确停止证明或显式替换授权。
+监测不会自动重试、停止或替换执行；告警本身不是恢复授权，也不证明唯一根因。
+
+存储仍为 **1.24**，Controller/Host 协议仍为 v1。已有消息与事件保留，本版本
+不新增存储迁移；较早受支持 Home 仍通过集中式连续迁移链升级。
+另行获得更新授权后，由 Operator 核验实际发布包，再执行
+`yui update --version 2.19.0`。兼容的存活 Session 保留；发布本身不更新运行安装，
+也不恢复其他 Task。精确 merge commit 的 Core CI 与同一 tarball 的全新安装
+平台／Node 矩阵仍为发布门禁，这些验证不代表真实模型行为验证。
+
+### 2.18.0 兼容性及迁移说明
+
+本 minor 包含已合入的独立 Jobs 工作区和全局 Shell 脚本 Job（PR #490），以及
+Controller 可靠性与诊断改进。精确 Session 停止／替换不再等待无关全局调度排空；
+停止证明、单写者和未知输入防重放仍受保护。Session 健康区分历史故障与当前权限，
+明确拒绝的过期输入可以合法退役，原始证据保留。
+
+Task 局部惰性缓存、索引查询和持久化耗时观测减少投影开销，并区分请求、worker
+和数据库成本。默认持久化 worker 承担周期维护事务的锁等待；空闲 Global 恢复和
+已处分重试检查只读。实际启动准入和其他业务写入仍可能竞争。异步脱敏诊断保存到
+`runtime/controller-diagnostics.jsonl` 及两个有界轮转文件。这些改进解决已复现机制，
+不代表已证明每次历史超时的唯一根因。参见[托管运行时](managed-turn-and-session-runtime.zh-CN.md)。
+
+存储从 **1.22 经 1.23 升至 1.24**：1.23 声明全局 Shell 脚本定义及精确 Run 快照；
+1.24 增加 Task 读取修订号与触发器，不改写历史载荷。生产 1.21 Home 会先执行已有的
+1.22 Role/Profile 启停字段迁移。必须使用集中式同 major 连续迁移，不手工修改数据库。
+Controller RPC、Host control/event 协议仍为 v1；兼容的存活 Host 和 Session 保留，
+而非热更新。Host 未报告能力及未知结果仍明确保留。
+
+另行获得生产授权后，由 Operator 核验实际发布包，再执行
+`yui update --version 2.18.0`。迁移前刷新一致的维护备份，记录当时程序与 Controller
+身份。较早的在线数据库快照不是完整回滚点，不可覆盖后续已接受输入。
+旧二进制不能打开 1.24 Home；回滚需要匹配的旧程序和升级前一致 Home 备份，
+并核对期间发生的效果。
+
+发布门禁要求精确 merge commit 的 Core CI，以及同一运行包的全新安装平台／Node
+矩阵通过后才能发布 npm。本地确定性测试与既有 smoke 不替代这些门禁，也不证明
+真实模型行为。发布本身不更新生产 Home，不代表其他 Task 执行问题已解决。
+
 ### 2.17.0 兼容性及迁移说明
 
 本 minor 在 CLI 和 Web 设置中新增持久化的 Role/Profile 启用、停用控制。

package/docs/storage-baseline.md

@@ -2,7 +2,20 @@
 
 # Storage baseline 1.0
 
-Current storage is 1.22. The 1.21 → 1.22 transition admits an optional boolean
+Current storage is 1.24. The 1.23 → 1.24 transition adds transaction-maintained
+Task read-cache revisions for the scheduler's nine source tables. Inserts,
+updates and deletions invalidate only the affected Task; rollback also rolls
+back the token. These tokens are derived cache identities, never Task authority
+or a replacement for the Home revision CAS. Historical payloads are unchanged,
+and existing Tasks start with an implicit zero token until their first mutation.
+Two partial indexes support exact runtime-observation identity lookup without
+scanning or deserializing the historical observation set.
+
+The 1.22 → 1.23 transition adds global Shell Job
+definitions with revisioned script files and per-Run executable snapshots.
+It preserves existing payloads without rewriting any Job, schedule or history.
+
+The 1.21 → 1.22 transition admits an optional boolean
 `enabled` on Roles and Profiles. Absence means enabled. SQL layout, historical
 payloads, existing Task bindings, Session snapshots and input receipts are
 unchanged; upgrade does not launch or stop execution.

package/docs/storage-baseline.zh-CN.md

@@ -2,7 +2,12 @@
 
 # 存储基线 1.0
 
-当前存储为 1.22。1.21 → 1.22 为 Role/Profile 声明可选布尔字段 `enabled`，
+当前存储为 1.24。1.23 → 1.24 为调度器的九类来源表增加事务维护的 Task 读取缓存修订号。插入、更新和删除只使对应 Task 的缓存失效，回滚同时回滚修订号。该值仅是派生缓存标识，不是 Task 权限或 Home revision CAS 的替代。历史 payload 不变，旧 Task 在首次修改前使用隐含的零修订号。
+同时增加两个局部索引，支持按精确运行观测身份查找，不再扫描或反序列化历史观测集合。
+
+1.22 → 1.23 新增全局 Shell Job、版本化脚本文件及每次运行的配置快照，不改写已有 Job、计划和历史记录。
+
+1.21 → 1.22 为 Role/Profile 声明可选布尔字段 `enabled`，
 缺省表示启用。SQL 布局、历史 payload、已有 Task 绑定、Session 快照和输入回执
 保持不变；升级不启动或停止执行。
 

package/docs/testing/verification-levels.md

@@ -53,12 +53,12 @@ is required.
 Both include `test/core` and `test/platform`. For an already built checkout,
 `npm run test:business` runs only `test/core` and `npm run test:platform` runs
 only `test/platform`; neither rebuilds. CI owns one explicit build per job.
-The stable suite owns current storage 1.22 and its declared 1.0 through 1.21 minor
+The stable suite owns current storage 1.24 and its declared 1.0 through 1.23 minor
 transition. It contains no undeclared historical format compatibility path.
 
 Current coverage includes:
 
-1. Fresh storage 1.22, exact schema/record validation, no initialization over
+1. Fresh storage 1.24, exact schema/record validation, no initialization over
    unknown data, and rejection of old integer formats without mutation.
 2. Exact-version staging, mismatched-target refusal, same-major contiguous
    minor preflight, explicit maintenance-owner identity across handover, and

package/docs/testing/verification-levels.zh-CN.md

@@ -39,12 +39,12 @@ Yui 是一个单用户本地产品。永久验证保护关键的 happy path 和
 两者均包含 `test/core` 和 `test/platform`。已构建的 checkout 可分别运行
 `npm run test:business` 与 `npm run test:platform`，它们不会再次构建。
 CI 每个作业只显式构建一次。
-稳定套件维护当前存储 1.22 和明确声明的 1.0 至 1.21 连续小版本迁移，
+稳定套件维护当前存储 1.24 和明确声明的 1.0 至 1.23 连续小版本迁移，
 不包含未声明的历史格式兼容路径。
 
 当前覆盖包括：
 
-1. 新建存储 1.22、精确结构与记录校验、禁止覆盖未知数据库、无修改拒绝旧整数格式。
+1. 新建存储 1.24、精确结构与记录校验、禁止覆盖未知数据库、无修改拒绝旧整数格式。
 2. 精确版本暂存、目标不匹配拒绝、同主版本连续小版本预检、交接锁显式所有者，
    以及恢复时核对捕获的协议和存储身份，不接受缺失字段。
 3. 持久 Task／Message／Decision 上下文、Draft 激活权威、mailbox 认领、

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "2.17.0",
+  "version": "2.19.0",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,