@zq-silk/yui 2.17.0 → 2.18.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

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` 的桌面命令

package/docs/release-workflow.md

@@ -51,6 +51,49 @@ 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.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,35 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 不能将不兼容冒称为兼容，也不为回避版本选择新增历史兼容机制。包版本与协议、
 持久存储契约仍然独立：兼容性检查和必要迁移要求不变，下文存储规则不授予发版权限。
 
+### 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.18.0",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,