@zq-silk/yui 0.16.0 → 0.16.2

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

@@ -2,6 +2,15 @@
 
 # Session, AgentRun and notifications
 
+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
+and stopped before settling occupancy. Global stop evidence is retained as a
+record-only system Message, without submitting another native input. Pending
+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.
+
 ## Authority
 
 Task, WorkItem, Message, Decision, Artifact and Project Knowledge preserve
@@ -28,6 +37,7 @@ yui task context <task> --json
 yui task context delta <task> --after <coreCursor>
 yui task context inspect <task> --store <store> --ref <id>
 yui task run context <task/run> --json
+yui task run context expand <task/run> <ref-id> --store <store> --mode full --json
 ```
 
 Task Context is a bounded authorized working set with a current core cursor.
@@ -43,6 +53,22 @@ 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.
 
+Every new Run, including planning, Review and continuation, binds an explicit
+frozen Snapshot before dispatch. Context reads validate its full identity and
+content digest, then read its stored values without rebuilding current Task
+records. Synthesis reads the selected Producer results from that Snapshot.
+Writable Projects come from the Run's captured effective authority; live
+activity is a separate observation, not part of the frozen contract.
+Expansion always requires both `store` and `refId`, even for a unique id.
+
+Historical Run records without a Snapshot remain readable through `run show`
+for audit, but cannot supply execution Context, be submitted or retried.
+Missing/drifted Snapshot evidence fails explicitly; it is never synthesized
+from today's Task. Subsequent observed/steered input records may legitimately
+omit their own Snapshot because they do not establish a new Assignment.
+No stored layout or payload changes: storage remains 37 with the complete
+1→37 migration chain unchanged.
+
 Current Task reads also expose untargeted user/Operator messages to the Task's
 current Worker and Reviewer Sessions, including requirements added after their
 Run snapshot was frozen. Use `task message list/show` or Task Context inspect
@@ -294,6 +320,11 @@ yui task execution start <task>
 yui task execution stop <task> --force --reason <reason>
 ```
 
+`task run retire` accepts only `--expected-progress-at` for its progress fence;
+the former `--progress-at` alias is removed. Retiring an active Run still requires
+its exact progress, Agent/Adapter and, when bound, native Session identity;
+the renamed entry does not relax quiescence or retirement authority.
+
 Task execution start/stop controls Task admission, not Task acceptance.
 Stop first fences new Yui work, then interrupts each exact owned native input
 and confirms its terminal before removing the attachment. This also covers

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

@@ -2,6 +2,12 @@
 
 # Session、AgentRun 与通知
 
+Global Session 停止／替换与 Task Session 共用精确的原生执行静止确认边界。
+Host 消失或 Session 已入历史不代表已接受输入结束：须先检查并停止保留的
+Provider binding，再结算执行占用。Global 停止证据保存为仅记录的 system Message，
+不触发新的原生输入。待投递通知不能重启已明确停止的 Session；普通 Host 脱离仍
+保留 active Session，可正常重连。部分切换失败后，仍须先结算旧输入再选择新会话。
+
 ## 权威
 
 Task、WorkItem、Message、Decision、Artifact 和 Project Knowledge 保存持久工作。
@@ -25,6 +31,7 @@ yui task context <task> --json
 yui task context delta <task> --after <coreCursor>
 yui task context inspect <task> --store <store> --ref <id>
 yui task run context <task/run> --json
+yui task run context expand <task/run> <ref-id> --store <store> --mode full --json
 ```
 
 Task Context 是一个有界的、获授权的工作集，带有当前 core 游标。delta 在一个固定
@@ -37,6 +44,18 @@ Run Context 冻结 Assignment、来源引用、生效配置和工作区边界。
 和消息正文，而不是把加载成功当成交付物。规划 Pack 不暴露 Project 写范围或 Task 完成
 权限。
 
+新 Run（包括规划、Review 和消息续接）必须在派发前绑定明确冻结的 Snapshot。
+Context 读取校验完整身份与内容 digest，然后直接读取已保存的值，不重新收集当前
+Task 记录。聚合执行从该 Snapshot 读取已选择的 Producer 结果；可写 Project 来自
+Run 捕获的生效授权。当前活动状态仍是独立观察，不属于冻结合同。
+展开引用必须同时指定 `store` 与 `refId`，即使 id 唯一也不能省略 store。
+
+缺少 Snapshot 的历史 Run 仍可通过 `run show` 审计，但不能提供执行 Context、
+提交给 Provider 或用于重试。Snapshot 缺失或漂移时明确失败，不用今天的 Task
+事实补造历史。后续观察到的原生输入或 steer 记录可以没有独立 Snapshot，因为
+它们不建立新的 Assignment。本次不改变存储布局或记录载荷：storage 仍为 37，
+完整的 1→37 迁移链保持不变。
+
 当前 Task 读取也会把无定向目标的 user/Operator 消息暴露给该 Task 当前的 Worker 和
 Reviewer Session，包括在它们 Run 快照冻结之后新增的需求。用 `task message list/show`
 或 Task Context inspect 来读取那些原始记录。这不改写冻结的 Assignment，也不授予投递
@@ -239,6 +258,10 @@ yui task execution start <task>
 yui task execution stop <task> --force --reason <reason>
 ```
 
+`task run retire` 的进度围栏只接受 `--expected-progress-at`，移除旧的
+`--progress-at` 别名。退役活动 Run 仍要求精确进度、Agent/Adapter 及已绑定的
+原生 Session 身份，不放宽静止性检查或退役权限。
+
 Task execution start/stop 控制 Task 准入，而不是 Task 验收。stop 先围住新的 Yui 工作，
 然后中断每一条被拥有的确切原生输入，并在移除 attachment 之前确认其终态。这也覆盖没有
 Run 的普通 Leader 通知。未知的原生状态阻塞清理；仅停止一个代理绝不证明一个共享 Turn

package/docs/observability/README.md

@@ -56,6 +56,53 @@ Claude execution process dying closes its exact input and marks its Session
 failed, even while the supervising Host remains alive. A deliberately stopped
 Session with settled native input is idle rather than a false runtime failure.
 
+## Web attention and progress
+
+Task detail prioritizes **needs your input**, **Session activity**, **Task progress**
+and **key conclusions**. InputRequests retain their original answer controls and
+bounded Context counts; a partial read is not an empty inbox. Technical attention
+names the owner from the existing execution projection. An assigned owner does
+not imply work started, and a diagnostic hint is not new user authorization.
+
+Session observations include direct chat and notifications without an AgentRun.
+The selected native identity is counted once; foreground activity must match its
+exact current input. Earlier Turns and replaced Sessions cannot supply its
+activity. Waiting, quiet, diagnostic-needed, unknown, stopped, ended and unsettled
+background work remain distinct. An operation without a terminal is not an
+everlasting heartbeat. Quiet/diagnostic windows come from the existing runtime
+policy; the read time is not a new activity timestamp. This is a recorded selected
+Session view, not a live process probe or an inventory of historical resources.
+Controller-owned bounded Provider retry waits remain waiting, not stopped or
+waiting for user approval. A successor's activity uses its own exact input.
+
+Progress comes from the original Brief and completion record, with source time;
+activity and tokens do not create a percentage, ETA or semantic checkpoint.
+Current Decisions show their rationale/source; superseded ones remain in history.
+Reports and recommendations are not relabelled as user approval. Core Context
+remains readable when its independent observation fails.
+
+**Results and evidence** reads files only on request. A selected commit-pinned
+text survives refresh and newer file listings; switching versions is explicit.
+A missing revision fails visibly, never substitutes HEAD. HTML/scripts stay
+text, never an executing preview. Copying a source sends nothing; discussion
+uses the original Message form, explicit intent and receipt. Unsent inputs remain
+protected across automatic refresh.
+
+Delivery reuses Publication coverage, including adoption, and keeps
+reported/verified, missing/stale/head-unavailable distinct. On-demand evidence
+shows original Integration checks, fixed Review candidates and original Reviewer
+reports. Review completion is not semantic approval; skipped/missing checks are
+not passes. Workspace ownership does not prove cleanup safety: the existing
+read-only `task archive-preflight` is referenced, not automatically run. There
+are no new accept, publish or archive buttons. Usage retains known/partial/unknown.
+
+All routes use the local Web token and Task boundary.
+`GET /api/tasks/<id>/artifacts` lists a fixed repository revision;
+`?path=<relative-path>&commit=<full-commit>` reads its exact text file.
+`GET /api/tasks/<id>/evidence` reads original check/Review/workspace records.
+These reads do not start a runtime, fetch a remote, write business state, require
+a migration, or introduce a new persistent protocol.
+
 ## Execution audit
 
 `execution audit` aggregates existing Task, Run, wake, Session, Review,

package/docs/observability/README.zh-CN.md

@@ -49,6 +49,43 @@ AgentRun，Role 状态也包含其原生准入/活动；当某个 WorkItem 处
 监督它的 Host 仍存活。一个已被有意停止、且原生输入已结算的 Session 是空闲状态，
 而不是虚假的运行时失败。
 
+## Web 用户关注与进展
+
+Task 详情优先展示「需要你处理」「会话活动」「任务进展」「关键结论」。
+InputRequest 保留原回答入口和有界 Context 计数；部分读取不等于空待办。
+技术关注从既有执行投影取得负责人；有负责人不代表已开始处理，诊断提示
+也不自动成为新的用户授权。
+
+会话观察包含没有 AgentRun 的直聊与通知。选用的原生身份只计一次，前台活动
+必须匹配当前精确输入；旧 Turn、旧 Session 的活动不能借给新输入。
+等待、安静、需诊断、未知、停止、该轮结束和后台未结清保持区分；
+没有终态的操作不是永久心跳。时间窗复用既有 runtime policy，读取时间不冒充
+活动时间。这是已记录选用会话的视图，不是实时进程探测或历史资源盘点。
+Controller 已负责的有界 Provider 重试显示为等待，不误称停止或等待用户审批；
+后继输入的活动仍须匹配它自己的精确身份。
+
+进度来自原 Brief 和完成记录，标注来源时间；活动、token 不产生百分比、
+ETA 或实质检查点。当前 Decision 展示理由与来源，已替代决定留在历史；
+报告与建议不改称用户批准。独立观察失败时，核心 Context 仍可读取。
+
+「成果与证据」仅按需读文件。固定提交的文本阅读在刷新和读取新列表后仍保留，
+切换版本必须显式选择；固定版本缺失就报错，不回退 HEAD。
+HTML／脚本只作为文本，不执行预览。复制来源不发送内容，讨论仍走原 Message
+表单、显式意图及回执；自动刷新保留未提交输入。
+
+交付复用 Publication 覆盖及采用记录，区分 reported/verified 和
+missing/stale/head-unavailable。按需证据展示原 Integration 检查、
+固定 Review 候选及原始 Reviewer 报告；Review completed 不等于语义通过，
+skipped／缺失检查不算通过。工作区所有权不证明可清理；既有只读
+`task archive-preflight` 仅作为操作指引，不自动运行。没有新增验收、发布、
+归档按钮，用量仍保留 known/partial/unknown。
+
+所有入口沿用本地 Web token 与 Task 边界。
+`GET /api/tasks/<id>/artifacts` 列出固定仓库版本；
+`?path=<relative-path>&commit=<full-commit>` 读取该版本文本；
+`GET /api/tasks/<id>/evidence` 读取原检查／Review／工作区记录。
+读取不启动运行时、不访问远端、不写业务状态、不引入迁移或新持久协议。
+
 ## 执行审计
 
 `execution audit` 汇总既有的 Task、Run、wake、Session、Review、Integration、

package/docs/project-refresh.md

@@ -7,6 +7,15 @@ the Project's configured remote and stable branch. Stable and development
 branches must match. The per-Project maintenance fence covers the operation;
 Task workspaces and their recorded bases are not refreshed by this command.
 
+## Project ownership
+
+`yui project clone <name> <remote>` creates a Home-managed checkout by default.
+Add `--external` to clone into `<configured defaultWorkspace>/<name>` and retain
+external ownership. This is a supported public option in help and completion;
+it does not remove the existing confirmation, branch verification or workspace
+isolation boundaries. `project add` can bind an existing external checkout;
+`project migrate` explicitly moves one into Home-managed storage.
+
 ## Two separate facts
 
 The checkout HEAD and a local remote-tracking ref are distinct observations.

package/docs/project-refresh.zh-CN.md

@@ -6,6 +6,14 @@
 规范 checkout。stable 与 development branch 必须一致。操作全程持有 per-Project
 maintenance fence；不会刷新 Task 工作区或改写其记录的基线。
 
+## Project 所有权
+
+`yui project clone <name> <remote>` 默认创建 Home 管理的 checkout。
+添加 `--external` 会克隆到 `<已配置的 defaultWorkspace>/<name>`，保留 external
+所有权。这是帮助和补全中公开支持的选项，不绕过现有确认、分支校验或工作区隔离
+边界。`project add` 可绑定已有 external checkout；`project migrate` 可明确将其
+迁入 Home 管理的存储。
+
 ## 两个独立事实
 
 checkout HEAD 与本地 remote-tracking ref 是不同的观察。refresh 将精确分支获取到

package/docs/provider-retry.md

@@ -48,6 +48,41 @@ panel. `cancel` withdraws this recovery chain; `disable` also disables future
 chains on the current Provider binding. Neither interrupts an admitted Turn.
 `enable` does not replay historical failures. Existing Task/Role authority applies.
 
+## Failure evidence and Agent handoff
+
+The retry projection includes the original input reference (never copied console
+text), exact Session/attempt identities, the preserved error, the latest Turn
+failure and earlier chain references. A changed error that still satisfies the
+same safe retry rule continues within the original budget. Loss of that rule,
+authority or budget stops automatic submission.
+
+Task errors retain their original `runtime.agent-error` evidence and notify the
+Leader, or the Operator when the affected Role is the Leader. Global failures
+retain record-only Messages in their own Role inbox, including intermediate
+failed attempts; these are evidence, not new input that cancels recovery.
+When Global recovery stops or its effect is unknown, a deduplicated system
+Message carries the facts to the existing Operator. If the Operator itself
+failed, or no Operator is configured, the notice remains visible for the user
+or successor without submitting a self-recovery prompt.
+
+Malformed JSON frames and failing protocol listeners close the affected channel
+with the original cause. Unrelated valid protocol notifications remain ignorable.
+The existing Host Inbox carries the diagnostic to Task/Global consumers without
+inventing a native terminal, clearing a writer fence or replaying input.
+
+Endpoint cleanup preserves stop/close errors, the exact implementation and client
+identities, last observed drain facts and pending effects. A failed inspection is
+not an empty resource list. Later owned cleanup steps, including control-socket
+closure, still run; cleanup failures retain their causes and produce a failing
+Host exit rather than silent success. Timeout reports never claim quiescence.
+
+The optional detached-child metadata reconciler retains its existing bounded
+query, backoff and circuit pause. Unavailable observations preserve writer
+ownership and expose their original error, exact targets and sampling count.
+The first failure and circuit-limit crossing use existing deduplicated error
+events; metadata sampling does not start model work or declare a parent result.
+No new default metadata collector, retry worker or durable state schema is added.
+
 ## Supported boundary and adoption
 
 Current controlled Codex Hosts advertise exact recovery support. The native

package/docs/release-workflow.md

@@ -27,6 +27,121 @@ system sits behind `ReleaseWorkflowPorts`
 external ports exercise recovery without real GitHub, npm, git, Controller,
 or model effects.
 
+## Final historical bridge: 0.16.2
+
+| Release | Home storage | Responsibility |
+| --- | --- | --- |
+| **0.16.2** | Historical v37, supported floor v1 | Last complete historical upgrade chain (v1 through v37). |
+| **1.0.0-alpha.1** (planned) | A distinct new 1.0 baseline | Publish an independent, explicit offline converter from verified historical v37. |
+| **1.0.0** (planned) | The same verified 1.x contract as the final prerelease | Remove converter source after durable publication; never reset storage again. |
+
+0.16.2 supersedes the 0.99.0 release designation without reverting its functional
+changes or Git history. Both use the same v37 endpoint. Publish and verify this
+replacement before withdrawing the 0.99.0 registry version, Release and tag.
+Do not automatically downgrade a local installation or change its Home.
+Stable releases explicitly publish to npm `latest`; prereleases publish to
+`next`, so the new baseline is opt-in.
+
+0.16.2 freezes the historical endpoint at **37**. It does not append a no-op
+migration, rewrite released SQL/data migrations, reset record-local schema or
+protocol versions, or reinterpret historical evidence. Fresh and upgraded Homes
+use the same contract. Ordinary opens still reject historical formats; only
+explicit `upgrade` / `update` may migrate them.
+
+### Select the bridge explicitly
+
+In 0.16.2, `yui update --version 0.16.2` selects an exact published
+package; no argument still selects `latest`. Tags and ranges are not accepted
+as explicit selectors. The actual staged version must equal the requested
+version before preflight or Controller handover. A mismatch cleans only the
+owned staging prefix, leaving the installed binary and database unchanged.
+
+Older CLIs do not acquire this option until updated. Once 0.16.2 is published,
+use a separately staged, exact 0.16.2 CLI to drive the update against an explicit
+`YUI_HOME`. For example, npm can stage it without replacing the global install:
+
+```sh
+YUI_HOME=/absolute/path/to/home npm exec --yes --package=@zq-silk/yui@0.16.2 -- \
+  yui update --version 0.16.2
+```
+
+Do not replace the live global binary first or assume `latest` will continue
+to select the bridge. Preserve target-owned `upgrade --update-preflight` /
+`--update-apply`: refusal happens before activation, and preflight is repeated
+under the handover fence after draining the exact Controller. The older-updater
+recovery guidance below still applies when invoking an older updater.
+
+### Inspect and preserve the old endpoint
+
+With the published 0.16.2 CLI and the intended `YUI_HOME`, use the existing
+`yui --json version`, `yui --json upgrade --dry-run`, `yui --json doctor`,
+`yui --json controller status`, and `yui session reconcile --report` reads.
+After the old-chain upgrade, the upgrade report must be `already-current` at
+storage 37; `upgrade-plan` only describes pending migrations. Neither report
+proves physical quiescence or readiness for the new storage 1.0 cutover.
+Do not add a durable "ready for 1.0" flag or a second version authority.
+
+Before the later offline cutover, settle active work using its original
+contract. `yui session stop --all` explicitly stops idle managed Sessions and
+the Controller; it is not a force stop or proof that detached Jobs and unknown
+resources have exited. Inspect exact ownership and pending effects. Never mark
+Tasks complete, acknowledge uncertain work, or delete resources just to pass an
+upgrade. The future converter must recheck quiescence under its fence.
+
+Retain the **exact published 0.16.2 package**, its existing release manifest,
+registry integrity, tag/source commit, and this guide as the historical bridge.
+The existing package inventory pins compiled migrations and their helpers;
+an expiring CI artifact alone is not a long-term distribution. This release
+introduces no additional Home metadata or migration registry.
+
+The 1.0.0-alpha.1 converter must preserve old ledger/audit bytes, Home identity,
+business IDs, records, Knowledge, workspaces (including dirty files), and
+unconfirmed external effects. A database-only backup cannot fully roll back old
+layout migrations with filesystem/Git effects. Unknown or malformed old formats
+remain blockers. New storage 1.0 must have a distinct baseline identity, never the old
+`v0.15.0-baseline`. Its SQL/fingerprint and final conversion tool belong to
+1.0.0-alpha.1, **not this release**; it accepts verified old v37 rather than carrying
+the complete old chain.
+
+The new storage uses major.minor versions; default upgrades allow only explicit,
+contiguous minor steps within the same major. Any persistent change during
+prereleases must declare a new minor transition, never silently rewrite a
+published baseline. The stable release reuses the final verified contract.
+Publish the converter and checksum as durable prerelease attachments before
+removing their source. Never include conversion code in the runtime tarball or imports, retaining current
+initialization, validation, unknown-format rejection, exact runtime identity and
+normal safety/recovery. Users skipping the bridge must still use the frozen
+tools; 1.0.0 must never guess an old format.
+
+## Controller handover fix in 0.16.1
+
+Controller status and storage preflight are observations, not cleanup. The
+authorized updater explicitly runs its bounded current-Home reconciliation
+under the handover fence before capture/stop. It retains the existing four-pass
+rule and process-start/inode checks, preserving current Controllers and excluding
+Agent/tmux/app/foreign-Home resources.
+
+Update results and release-step logs retain reconciliation targets, completed
+actions, original cleanup errors, the last inventory with its observation time,
+and failed observations or lock release. Captured-identity restoration reports
+success or unknown effects separately. An uncertain cleanup/restore is not a
+stopped Controller or replayable failure; inspect the exact resource before
+choosing recovery. No new recovery worker or persistent protocol is introduced.
+The staged `--update-preflight` / `--update-apply` contract is unchanged.
+
+The updater's stop and exact-identity restoration children now explicitly receive
+the parent updater's handover-lock owner identity. They no longer wait on their
+own parent's lock; unrelated callers remain fenced. Storage remains at version 37.
+
+An already-installed older updater, including 0.15.12 or 0.16.0, cannot gain this
+fix merely by staging the new package. If it reports `CONTROLLER_HANDOVER_TIMEOUT`
+before activation, inspect the original Controller and lock ownership. Once the
+failed updater has released its own lock and the original Controller is confirmed
+healthy, normally stop it with that installed release's `yui controller stop`,
+then retry `yui update`. This preserves managed Agent Sessions and retains the
+normal preflight, backup, migration and verification boundaries. Do not delete
+an active lock or force-kill a Controller to bypass the failure.
+
 ## Pre-1.0 contract cleanup
 
 Version 0.16.0 retires runtime compatibility before the final
@@ -132,7 +247,7 @@ configuration, and explicitly retry the rejected notification.
 Before rollout, replace Sessions whose old Manifest still names `task turn`,
 and explicitly remove/archive old `yui-dev` completion blocks before installing
 current `yui` completion. User shell files are never rewritten by storage migration.
-Host control/event compatibility and updater handover safety remain unchanged.
+Current Host control/event validation and updater handover safety remain enforced.
 
 Storage 33→34 removes Message `wakePolicy` and activation `origin` from current
 records, preserving their original representations in audit Events. Historical
@@ -255,7 +370,7 @@ Candidate and Task-final ReviewRound records must all carry that one contract.
 Conflicting records fail closed; there is no rebind event, recovery command, or
 second contract state machine.
 
-## Persistent Agent Host compatibility
+## Current Agent Host boundary
 
 A running Host keeps its original Endpoint implementation. It records exact
 Session/attempt/native-Turn facts in the existing durable Inbox before contacting
@@ -269,24 +384,28 @@ the long-lived Session environment. This preserves pre-adoption evidence even
 when the frozen Run workspace differs from the Role's default; later activity
 and terminal facts still resolve solely by their own native input identities.
 
-The supported Host boundary is control `yui-agent-host/v5`, event source
-`yui-agent-host-events/v1`, and Controller RPC version 4. Hosts advertising
-`storage=controller-owned` do not open the Home database, including for process
-custody, native account locations, or execution-environment checks. Home 22
-declares the additive Inbox source envelope; valid older Inbox v1 facts and
-domain history remain readable. Future changes must retain this wire boundary
-or reject incompatible live producers before changing storage. CLI wrapper
-refresh and a successful new `doctor` are not Host compatibility proofs.
-
-`upgrade`, the staged target's `update` preflight, and release activation inspect
-live Host capabilities independently. An old Host without this capability,
-including an idle Host or one whose response is unconfirmed, blocks adoption.
-Checks are repeated at the existing fenced/quiesced handover boundary before
-migration or promotion. No Host is killed, replaced, or reloaded by these checks.
-Let existing work settle and preserve original pending input/result evidence;
-then an authorized Operator can select a safe Session replacement/cleanup before
-retrying. Installing this change cannot repair already-loaded legacy Host code
-or collect a terminal that that code never durably emitted.
+The current Host boundary is control `yui-agent-host/v5`, event source
+`yui-agent-host-events/v1`, and Controller RPC version 4. Hosts do not open the
+Home database, including for process custody, native account locations, or
+execution-environment checks. Only the Controller owns storage and resolves
+durable facts; malformed current input fails at its normal protocol boundary.
+
+Breaking upgrades do not inherit historical Hosts or processes. Runtime startup,
+`upgrade`, `update`, and release activation no longer scan old Host sockets or
+processes, infer their capabilities, or negotiate a compatibility handoff. Use a
+clean runtime environment; this is not permission to discard pending work or
+kill resources of uncertain ownership. Current Controller restart, exact
+process-generation checks, handover locks, Session authority and event replay
+protection remain enforced.
+
+Storage migration is separate: the complete 1..37 chain and updater
+`--update-preflight` / `--update-apply` contract remain. Storage preflight is
+rechecked at the fenced/quiesced boundary; no published migration is rewritten.
+Session CLI refresh only retargets the current two-argument quoted wrapper
+named by a valid Manifest. It does not convert retired wrapper forms. Runtime
+diagnostics do not interpret `schema.json`, `state.json`, or a whole-map release
+idempotency file; current SQLite data and per-key release receipts remain the
+authorities, and unrelated files are left untouched.
 
 `task role status`, `task role list`, and `task role session inspect` expose Host
 reporting alongside durable Run state. Pending native results or known reporting

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

@@ -2,6 +2,81 @@
 
 # 获授权的发布操作
 
+## 最后的历史桥接版：0.16.2
+
+| 版本 | Home 存储 | 职责 |
+| --- | --- | --- |
+| **0.16.2** | 旧 v37，最低支持旧 v1 | 最后一次保留完整 v1→v37 历史升级链。 |
+| **1.0.0-alpha.1**（计划） | 身份独立的新 1.0 | 独立发布严格验证后的旧 v37→新 1.0 离线转换器。 |
+| **1.0.0**（计划） | 与最终预发布版相同的已验证 1.x 契约 | 转换器持久发布后删除其源码，不再重置存储。 |
+
+0.16.2 承接 0.99.0 的有效改进，只替代发布编号，不回退功能或改写 Git 历史；
+两者使用同一 v37 终点。先发布并验证替代版本，再撤下 0.99.0 的 npm 版本、
+Release 和 tag。不自动降级本地安装或修改 Home。
+正式版显式发布到 npm `latest`，预发布版发布到 `next`，新基线必须主动选择。
+
+0.16.2 将旧链终点冻结在 **37**，不追加空迁移、不改写已发布 SQL 或
+数据迁移，也不重置记录内的 schemaVersion、运行协议和审计版本。
+新建及升级后的 Home 使用同一当前契约；普通读取不解释历史格式，
+只有显式 `upgrade` / `update` 可以迁移。
+
+### 明确选择桥接版本
+
+在 0.16.2 中，`yui update --version 0.16.2` 选择精确的已发布版本；
+无参数仍选择 `latest`。显式版本不接受标签或范围。暂存包的实际版本必须
+等于指定版本，才可进入预检和 Controller 交接；不匹配时只清理本次暂存目录，
+不改变当前安装和数据库。
+
+旧 CLI 尚不支持此参数。0.16.2 发布后，可先独立暂存精确的 0.16.2 CLI，
+再由它针对明确指定的 `YUI_HOME` 执行升级。例如用 npm 暂存 CLI，
+而不是先覆盖全局安装：
+
+```sh
+YUI_HOME=/absolute/path/to/home npm exec --yes --package=@zq-silk/yui@0.16.2 -- \
+  yui update --version 0.16.2
+```
+
+不要假定未来的 `latest` 仍指向桥接版。保留目标包驱动的
+`upgrade --update-preflight` / `--update-apply` 契约：拒绝发生在激活前，
+并在 handover fence 内、精确 Controller 停止后重新预检。
+若仍使用旧 updater，下文旧版本的交接恢复说明依然适用。
+
+### 检查并保留旧链终点
+
+用已发布的 0.16.2 CLI 和明确的 `YUI_HOME` 读取：
+`yui --json version`、`yui --json upgrade --dry-run`、
+`yui --json doctor`、`yui --json controller status`、
+`yui session reconcile --report`。
+旧链升级完成后，upgrade 报告应为存储 37 的 `already-current`；
+`upgrade-plan` 只表示尚待执行的旧链迁移。两者都不证明运行资源静止，
+更不表示已通过新存储 1.0 的转换预检。不新增“可进入 1.0”持久化标记
+或第二套版本权威。
+
+后续离线切换前，先按原契约结算正在执行的工作。
+`yui session stop --all` 是停止空闲受管 Session 和 Controller 的显式操作，
+不是强制停止，也不证明所有独立 Job 或未知资源已退出。必须检查精确所有权
+和待确认效果，不能为了升级而伪造 Task 完成、确认未知工作或删除资源；
+未来转换器仍须在 fence 内重新检查静止条件。
+
+长期保留**精确的 0.16.2 发布包**、已有 release manifest、registry integrity、
+tag/源码提交及本指南。现有包清单会固定编译后的迁移实现和辅助模块；
+会过期的 CI artifact 不能作为唯一长期分发渠道。本版不新增 Home 元数据
+或迁移注册表。
+
+1.0.0-alpha.1 的一次性转换必须保留旧账本和审计原始内容、Home 身份、业务 ID、
+记录、Knowledge、工作区（含未提交文件）及未确认的外部效果。
+旧布局迁移还涉及文件系统和 Git，单独备份数据库不足以证明完整可回滚。
+未知或损坏格式直接阻塞，不猜测修复。新存储 1.0 必须具有独立身份，
+不能复用旧 `v0.15.0-baseline`。新 SQL/指纹及最终转换工具属于 1.0.0-alpha.1，
+**不在本版提前实现**；它只接受已验证的旧 v37，不再携带整条旧链。
+
+新存储采用主版本.小版本，默认只允许同主版本内显式、连续的小版本升级。
+预发布期间如需改变持久化契约，必须声明新的小版本迁移，不能静默改写已发布基线；
+正式版复用最终已验证契约。转换器及校验和必须作为持久的预发布附件发布后，
+才可删除其源码。正常运行 tarball 和导入链始终不包含转换器，
+保留当前初始化、校验、未知格式拒绝、精确运行身份和正常安全恢复。
+跳过桥接版的用户仍需使用冻结工具，1.0.0 不解释旧格式。
+
 发布工作流是一段被显式选择、获授权的外部发布效果序列——pull request、CI 确认、
 合并、版本 tag、npm 发布、全新安装冒烟、CLI 更新、Controller 替换、Project 迁移和
 后置验证。它是一个专用的外部效果设施，而不是 Yui 的 Task 规划或 Agent 执行模型。
@@ -20,6 +95,29 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 （`src/release/releaseWorkflowPorts.ts`）之后。可用临时 SQLite 和确定性的外部端口测试
 恢复逻辑，无需真实 GitHub、npm、git、Controller 或模型效果。
 
+## 0.16.1 的 Controller 交接修复
+
+Controller 状态与存储预检只负责观测，不暗中清理。已授权的升级流程在交接保护下、
+捕获和停止当前 Controller 之前，显式执行当前 Home 的有界 reconciliation。
+保留最多四轮和进程启动身份/inode 检查；当前 Controller、Agent/tmux/app 和其他
+Home 的资源不在此清理范围。
+
+升级结果与发布步骤日志保留清理目标、已完成动作、原始清理错误、带观测时间的最后
+资源现场，以及观测或锁释放失败。原 Controller 的精确身份恢复单独报告成功或效果
+未知。清理/恢复效果未知不等于 Controller 已停止，也不是可直接重放的失败；先检查
+确切对象再选择恢复。不新增后台恢复或持久协议，暂存二进制的
+`--update-preflight` / `--update-apply` 合同不变。
+
+升级器的停止与精确身份恢复子进程，现在显式接收父升级进程的交接锁归属身份，
+不再等待自己父进程持有的锁；无关调用仍被阻止。存储版本保持 37。
+
+已经安装的旧升级器（包括 0.15.12、0.16.0）不会因为暂存新包而提前获得此修复。
+若其在激活前报告 `CONTROLLER_HANDOVER_TIMEOUT`，先检查原 Controller 和锁的归属。
+确认失败的升级器已释放自己的锁、原 Controller 仍健康后，使用已安装版本的
+`yui controller stop` 正常停止 Controller，再重试 `yui update`。此操作保留受管
+Agent Session，仍完整执行预检、备份、迁移和验证；不要删除活动锁或强杀 Controller
+来绕过失败。
+
 ## 1.0 前的契约清理
 
 版本 `0.16.0` 先清退运行时兼容分支，尚未执行最终 1.0 基线切换，也不重置
@@ -95,7 +193,7 @@ Session 归属统一使用 SQLite。旧 `launch-env` owner 行或 `runtime/sessi
 
 不再支持 `task turn` 和 `yui-dev` 补全身份。上线前应替换仍依赖 `task turn`
 Manifest 的 Session；明确卸载／归档旧 `yui-dev` 补全块后，再安装现行 `yui` 补全。
-存储迁移不会修改用户 shell 文件。Host 控制／事件兼容与 updater 交接安全检查保持不变。
+存储迁移不会修改用户 shell 文件。当前 Host 控制／事件校验与 updater 交接安全检查继续生效。
 
 存储 `33→34` 从当前记录移除 Message `wakePolicy` 与激活 `origin`，原始表达
 保存在审计事件。旧的仅记录消息转换为 `intent: record`，其他缺少意图的
@@ -192,7 +290,7 @@ Session 使用普通的 `yui` 命令，兼容性由协议和存储身份检查
 Task-final 的 ReviewRound 记录必须全部携带那唯一的合同。冲突的记录 fail closed；
 不存在重新绑定事件、恢复命令或第二套合同状态机。
 
-## 常驻 Agent Host 升级兼容
+## 当前 Agent Host 边界
 
 存活 Host 保持原 Endpoint 实现，先把准确的 Session/attempt/nativeTurn 事实写入现有
 持久 Inbox，再联系 Controller。只有当前 Controller 解析 Run 归属、校验权限、工作区、
@@ -203,18 +301,21 @@ ACK 不会重放用户输入或模型工作。
 环境。即使冻结的 Run 工作区不同于 Role 默认值，登记前的证据也能保留；后续活动和
 终态仍只按各自的原生输入身份解析归属。
 
-支持边界为控制协议 `yui-agent-host/v5`、事件来源协议 `yui-agent-host-events/v1`、
-Controller RPC 版本 4。声明 `storage=controller-owned` 的 Host 不打开 Home 数据库，
-包括进程归属、原生账号位置和执行环境校验。Home 22 声明 Inbox 的新增来源字段，
-不改写有效历史事实与业务记录。后续版本要么保留该线协议，要么在修改存储前拒绝不兼容
-的存活生产者。刷新 Session CLI wrapper 或新 `doctor` 成功都不能证明旧 Host 兼容。
-
-`upgrade`、`update` 的目标版本预检及 release activation 独立检查存活 Host。
-没有此能力的 legacy Host（包括 idle）以及兼容响应不确定的 Host 都阻止采用；
-在既有隔离/静默交接边界再次检查，先于迁移或发布切换。检查不会 kill、替换或 reload
-Host。先让原有工作结束并保留原始未决输入/结果证据，再由获授权的 Operator 在安全
-边界选择 Session 替换或清理，之后重试。安装新代码不能修改已加载的 legacy Host 内存，
-也不能回收它从未持久投递过的终态。
+当前边界为控制协议 `yui-agent-host/v5`、事件来源协议 `yui-agent-host-events/v1`、
+Controller RPC 版本 4。Host 不打开 Home 数据库，包括进程归属、原生账号位置和
+执行环境校验。只有 Controller 拥有存储并解析持久事实；非法当前输入在正常协议
+边界得到明确错误。
+
+破坏性升级不承接历史 Host 或进程。启动、`upgrade`、`update` 和 release activation
+不再扫描旧 Host socket／进程、推断旧能力或协商兼容交接。使用干净的运行时环境；
+这不授权丢弃未决工作或终止归属不确定的资源。当前 Controller 正常重启、准确进程
+代际校验、交接锁、Session 权限与事件防重放继续生效。
+
+存储迁移是独立边界：保留完整 1..37 迁移链和 updater 的 `--update-preflight`／
+`--update-apply` 合同，在隔离／静默边界重查存储预检，不改写已发布迁移。
+Session CLI 刷新只重定位有效 Manifest 指向的当前双参数引号 wrapper，不转换
+退役形态。运行时诊断不解释 `schema.json`、`state.json` 或整表 release 幂等文件；
+当前 SQLite 与逐 key release 回执仍是权威，无关文件保持原样。
 
 `task role status`、`task role list` 和 `task role session inspect` 在持久 Run 状态旁
 显示 Host 上报观测。原生结果待落库或已知上报故障需要关注，但不代表 Provider 失败、