@zq-silk/yui 2.8.1 → 2.10.0

package/docs/cli-information-contract.md

@@ -6,8 +6,9 @@ saved/requested/accepted/unknown facts; `ok: true` means the CLI invocation
 succeeded, not that a Task, native Turn or remote delivery completed.
 
 This is the current wire contract, not a compatibility mode. Stored Tasks,
-Messages, results, Snapshots and Session histories are unchanged. No persistent
-schema migration or new snapshot/cache store is introduced.
+Messages, results, Snapshots and Session histories are unchanged. Read projections
+add no snapshot/cache store. New activation-source event attributes use the
+declared storage 1.10 → 1.11 transition; historical sources are never invented.
 
 ## Daily read path
 
@@ -53,10 +54,22 @@ use family discovery when a broader requirement/history audit is needed.
   budget inside a 32 KiB response budget. Single inline values are at most
   2 KiB; large values and Message/Run/WorkItem/Knowledge bodies use references.
   Each collection contributes at most eight sampled records at entry.
-- Global entry samples up to eight unacknowledged inputs, including claimed or
-  uncertain ones. It does not repeat recent history, Profile bodies, frozen Skill
+- Global entry samples up to eight current-turn/available inputs, including
+  uncertain ones. Historical missing receipts are a separate count and explicit
+  `inbox list --view history` read; absence of ACK is not proof of unexecuted work.
+  Continue its pending page with `role message list <role> --current --cursor`.
+  It does not repeat recent history, Profile bodies, frozen Skill
   packages or accumulated retry details. The Manifest is the Profile pointer;
   explicit Message and Session retry reads retain history and original evidence.
+- `inbox list --view current|history|all` uses the current managed identity,
+  prioritizes exact current-turn input and shares originals with automatic
+  delivery. `claim` and `ack` accept 1–16 exact IDs with independent results.
+  ACK records semantic disposition (including legal routing or supersession),
+  not Task completion. Exact terminals emit one bounded handling check without
+  ACK or business replay; reminder-only input cannot self-wake indefinitely.
+  `inbox retire` disposes only obsolete proven-unsubmitted Global input with an
+  explicit reason, preserving its original target. Task retirement remains
+  the Leader's existing `task message retire` operation.
 - Run entry samples up to eight records per live category and 16 frozen refs.
   Pointer continuation uses `--view refs` and `pointerPage.nextCursor`; full pack
   document continuation uses `--view full`. Neither changes the frozen authority.
@@ -91,6 +104,46 @@ concurrent writes. For append-only event traversal use fixed-bound Context delta
 Discovery currently scans the selected authorized family to fingerprint it;
 its output, not total storage-reading cost, is bounded.
 
+## Intent, source and temporal consistency
+
+Current Leader/public Task context projects `phase` (lifecycle, gate, activation
+source and Brief freshness) separately from the managed `caller`'s actual
+execution authority. These are facts, not a semantic permission decision.
+Old Message records carry recording/revision relationships to the adopted
+activation, not an automatic “superseded” verdict.
+
+Activation requests accept either `--source-message <id>` or
+`--source-text <exact-input>`; a Leader must provide one. Develop submissions
+link their saved Message automatically. Exact text is retained in the existing
+immutable event with caller attribution, including native Session identity for
+Leader captures. It is not a Provider-verified user Message and is never queued
+again. Same-request retries cannot change that source. The activation wake
+references the event/original explicitly. Missing or changed sources have a
+diagnostic and original-read route, not a fabricated approval or rejection.
+
+`task brief show` returns `writeGuard`; `task brief update` requires
+`--if-current <writeGuard>`. New semantic input/results, phase changes or edits
+invalidate stale writers transactionally, independently of timestamps and
+runtime heartbeats. On rejection, reread and reconcile intended fields.
+Task Job saves append a semantic event for status, result, cancellation or
+acknowledgement changes, not for heartbeat, checkpoint or notification receipts.
+Core indicates `refresh-needed`; Leader maintains the actual summary at
+meaningful boundaries. No completion gate or automatic prose rewrite is added.
+
+Task event cursors bind the Home and Task. Delta returns `kind: event-history`,
+`fromCursor`, `complete`, `stateChanged` and a fixed `throughCursor`. Keep the
+original `--after` across every `--continuation`; advance only on completion.
+New arrivals remain outside that window. Empty events do not erase a baseline,
+and shared state can change without Task events. Invalid/old cursors require a
+fresh bounded current read. Event numeric IDs order recording within one Task,
+not occurrence, delivery, handling or unrelated Tasks.
+
+Run delta uses its exact frozen parent Snapshot and returns complete changed
+`refs` plus `removedRefs`, with normal document pagination. The clipped launch
+`deltaRefs` remains a hint only. Mutable Task facts never widen that Assignment.
+Focused wakes with exact refs no longer absorb other messages merely because
+timestamps overlap; `--history` retains timestamp-window discovery.
+
 ## Runtime diagnostics
 
 Global failure evidence remains ordinary record-only Messages; no aggregate

package/docs/cli-information-contract.zh-CN.md

@@ -5,7 +5,8 @@ Yui 将命令的效果、发现和完整证据读取分开。查询不会消费
 CLI 调用成功，不代表 Task、原生 Turn 或远端投递完成。
 
 这是当前通信契约，不是兼容模式。已保存的 Task、Message、结果、Snapshot 和 Session
-历史保持不变；没有持久 schema 迁移，也没有新增快照或缓存存储。
+历史保持不变；读取投影没有新增快照或缓存存储。新激活事件的来源字段使用已声明的
+存储 1.10 → 1.11 迁移，不补造历史来源。
 
 ## 日常读取路径
 
@@ -43,8 +44,16 @@ Run 列表接受 Task 或 `task/work` 目标。
 - 当前 Task Context 至多 64 条，记录与 attention 共 24 KiB，响应预算 32 KiB。
   单个内联值至多 2 KiB；大值及 Message/Run/WorkItem/Knowledge 正文用引用。
   入口每个集合最多抽样八条。
-- Global 入口最多八条未确认处理的输入，保留已领取或效果未知项；不重复 recent、
+- Global 入口最多八条本轮/可用输入，保留效果未知项；历史缺回执单独计数，
+  通过 `inbox list --view history` 显式发现，不把缺 ACK 当作未执行。
+  pending 页用 `role message list <role> --current --cursor` 续读；不重复 recent、
   Profile 正文、历史 Skill 包和累计 retry 详情。Profile 由 Manifest 精确指向。
+- `inbox list --view current|history|all` 优先展示精确本轮输入，与自动投递共用原始记录。
+  `claim`、`ack` 接受 1–16 个精确 ID，分别返回结果。ACK 表示语义处置，
+  包括合法转交或被后续要求替代，不等于 Task 完成。
+  精确终态只生成一次有界检查通知，不自动 ACK 或重放业务；纯提醒不会无限自唤醒。
+  `inbox retire` 仅显式退役已过时且可证明未提交的 Global 输入，保留原始目标和理由；
+  Task 输入继续使用 Leader 的 `task message retire`。
 - Run 入口最多 16 个冻结引用和每类八条活跃观察，附总数。`--view refs` 配合
   `pointerPage.nextCursor` 发现更多引用；`--view full` 显式读取完整冻结包。
   若 `input.directiveOmitted` 为 true，行动前用 `--view input` 全文读取分配指令；
@@ -70,6 +79,36 @@ Run 列表接受 Task 或 `task/work` 目标。
 追加事件遍历使用固定上界 Context delta。目前分类发现扫描选定的授权集合来计算指纹；
 有界的是输出，不是总存储读取成本。
 
+## 意图、来源与时序一致性
+
+Leader/公开 Task 当前视图的 `phase` 投影生命周期、执行开关、激活来源与 Brief
+新鲜度；`caller` 单独展示当前 Session 的实际权限，不代替语义授权判断。
+旧 Message 标明与激活请求的记录/修订先后关系，不自动判为整体失效。
+
+激活请求接受 `--source-message <id>` 或 `--source-text <exact-input>`，Leader
+必须提供其一。develop 提交自动关联已保存的 Message。直接原生输入原文保存在既有
+不可变事件中，带调用者及 Leader Session 归属，不伪装成 Provider 验证过的用户
+Message，也不再次入队。相同 request ID 重试不得更换来源。交接 wake 显式引用
+原始事件/Message；缺失或变更来源有诊断和原文入口，不自动批准或拒绝开发。
+
+`task brief show` 返回 `writeGuard`；更新必须携带 `--if-current <writeGuard>`。
+新语义输入、结果、阶段变化或编辑在事务中使旧写入失效，不依赖墙钟时间。
+Task Job 状态、结果、取消请求和确认处置在保存事务中追加语义事件；
+心跳、checkpoint 和通知回执不使 guard 反复失效。
+拒绝后重读并协调目标字段。Core 只提示 `refresh-needed`，
+Leader 在关键节点维护实际摘要，不新增完成门禁或自动改写原文。
+
+Task 事件游标绑定 Home 与 Task。增量返回 `kind: event-history`、`fromCursor`、
+`complete`、`stateChanged` 和固定 `throughCursor`。续页保留最初的 `--after`，
+用 `--continuation` 读完再推进游标；并发新输入留在下一窗口。空增量不清空基线，
+共享状态也可能在没有 Task 事件时变化。失效游标须重新读取有界当前视图。
+事件序号只表达单 Task 记录顺序，不混同发生、投递、消费或跨 Task 因果关系。
+
+Run 增量基于精确父 Snapshot，返回完整变更 `refs` 与 `removedRefs`，长文档照常
+分页；截断的 `deltaRefs` 仅作启动提示。可变 Task 事实不扩大冻结 Assignment。
+带精确引用的 focused wake 不再仅因时间戳重叠纳入其他 Message；`--history`
+仍可发现时间窗口历史。
+
 ## 重复运行时诊断
 
 `role message list <role> --diagnostics` 从原始 record-only Message 派生故障组，

package/docs/job-runs.md

@@ -0,0 +1,224 @@
+# Job definitions and exact execution Runs
+
+A Job is a stable, scoped definition. A JobRun is one execution, with its own
+ID, configuration revision, trigger, immutable execution specification,
+process identity, artifacts and terminal result. Changing a definition never
+changes an admitted Run. No Schedule is needed for immediate execution.
+
+## CLI and ownership
+
+Commands operate through the Controller's `job.definition` RPC:
+
+```sh
+yui job define --global --job probe --title "Local probe" \
+  --input '{"kind":"builtin","action":"system.noop","input":{}}'
+yui job run --global --job probe --request-id first
+yui job runs --global --job probe
+yui job run-get --global --job probe --run <exact-run-id>
+yui job logs --global --job probe --run <exact-run-id>
+yui job run-cancel --global --job probe --run <exact-run-id>
+```
+
+Use `--task task-N` instead of `--global` for a Task Job. Its configuration is
+`{kind:"shell",owner,projectId,head,workspace,env,steps}`, with the same managed
+workspace, Project, Assignment and delivery-Session requirements as `job start`.
+The Project target is not the ownership scope. Definitions can be inspected
+with `job show`, listed with `job list`, and revised with `job update --revision
+<observed-revision> --title ... --input ...`. A definition ID is required on
+creation; replaying an identical creation is idempotent. Scope cannot be updated.
+
+Global Job management requires the current authenticated Operator Session.
+Other GlobalRoles cannot inspect or manage Task Job definitions either, matching
+the existing Task Context authorization boundary.
+Users can request it through Operator. Literal `caller.scope=user` is not a
+credential on the existing Controller socket. Task Sessions cannot inspect,
+create, modify or run global Jobs. The initial global action is `system.noop`,
+a fixed local no-op implemented by the same standalone runner. It accepts only
+empty input and no Project; it does not call a model or external service.
+`project.refresh` is the controlled Project maintenance action below. Arbitrary global commands,
+environments, workspaces and Agent calls are not accepted.
+
+`job run --request-id` is a stable trigger identity within the scoped Job.
+Replay returns the original Run; reusing that identity after a configuration
+change or with a different retry target is a conflict. A new key after a
+terminal result admits a new Run. Queued, running or unknown-effect executions
+return `{created:false,reason:"overlap",run:<existing>}` rather than queueing.
+Returning an existing Run (including replay or overlap) requires permission to
+read that exact Run's original Assignment. If a definition was retargeted and
+the caller cannot read the earlier Run, admission fails with `UNAUTHORIZED`
+without exposing its snapshot or creating another Run.
+Unknown outcomes are never automatically replayed, even after acknowledgement.
+Explicit retry uses `--retry-of <exact-failed-cancelled-or-timed-out-run>`.
+Cancellation addresses a Run, not a future Schedule. Log reads return up to
+64 KiB per completed/checkpointed step; a currently uncheckpointed step is not
+included.
+
+The existing `job start` remains the one-shot Task entry point. It creates a
+definition and one Run, and its `job` response is still the **Run**. Existing
+`job get/cancel/acknowledge --task ... --job ...` address exact Runs, not
+definitions or “latest”. `jobs list/retry` is unchanged: it manages Leader
+wake/recovery records and is not this Job module.
+
+## Storage and existing consumers
+
+Storage **1.8 → 1.9** appends two tables without modifying the published
+baseline: `job_definitions` and `global_job_runs`. `durable_jobs` remains the
+authoritative Task Run table, with `definitionId`, `definitionRevision` and
+`trigger` added to each payload. This retains every Task-local Run ID and
+artifact location. Global Runs have `scope:"global"` and no `taskId`, Task or
+Assignment. They use the same execution state machine and supervisor; their
+terminal notices enter the Operator mailbox, never a Task Leader mailbox.
+
+The centralized transactional migration maps each old DurableJob to one
+definition with the same local ID and one preserved Run. Equal commands are
+not grouped. Original payload bytes are retained in `storage_migration_archive`
+under migration 9 / family `durable_jobs`; old results, process evidence and
+Integration references retain their identities. Frozen Context snapshots are
+not rewritten. Ordinary readers accept only current storage; there is no
+dual-format reader. A failed migration rolls back without advancing storage.
+Actual Home upgrades require their own authorization and backup; this change
+does not authorize or perform one.
+
+IntegrationAttempt and verification consumers still use
+`getDurableJob(taskId, exactRunId)`. Existing Task Context `job` entries,
+execution audit, readiness/archive checks and HTTP preview tickets likewise
+refer to exact Runs. Definitions alone never count as active execution or block
+Task completion. Started Runs and retained unknown process evidence keep the
+existing Task lifecycle and physical-cleanup boundaries. The management UI
+retains exact references rather than replacing them with latest.
+
+## Extension seams for Schedule, Project refresh and management UI
+
+- `src/job/jobDefinition.ts`: `JobDefinition`, `JobScope`, `JobConfiguration`
+  and `JobTrigger`. Definition revision is optimistic concurrency, not a Run
+  status. Project targets stay in configuration.
+- `src/controller/jobDefinitionControl.ts`: `admitJobRun(store, home, scope,
+  definitionId, caller, trigger, now, retryOf?)` returns `RunAdmission`.
+  It authenticates current scope, rechecks domain prerequisites, finds exact
+  trigger replay and excludes overlap inside the Store transaction. Schedule
+  can call it inside its own `store.transaction` with advancement in that same
+  transaction; no process starts until commit and supervisor reconciliation.
+  A rollback discards both. `source:"schedule"` is an internal seam, not an
+  accepted manual RPC assertion. Schedule must supply a legitimate current
+  authority; it must not invent a Session or reuse a revoked identity. Any
+  additional durable scheduled-intent authorization belongs to that feature.
+- `src/job/builtinJob.ts`: controlled action compilation. Add a narrowly
+  validated builtin here; snapshot its target/input and compile runner steps
+  from trusted code, never caller-supplied shell. Revalidate before spawn.
+  A non-Git action uses an explicit all-zero `head` sentinel, never a Project
+  commit or Integration proof.
+- `JobRun = DurableJob | GlobalJobRun` shares transitions, heartbeat, timeout,
+  cancel, checkpoints, exact OS identity and unknown-effect recovery. Store
+  methods preserve distinct scope storage; neither table mirrors the other.
+- `createJobDefinitionControl` backs CLI JSON reads/mutations. A future
+  authenticated Web ingress must resolve its own caller and enforce these
+  service boundaries; it must not forward arbitrary browser-supplied identity.
+
+The independent [Schedule module](schedules.md) adds time rules and transactional
+due admission after this 1.9 foundation. It does not introduce an independent
+daemon, cross-Task dependency engine or release behavior.
+
+## Controlled Project refresh
+
+An authenticated Operator can explicitly install one maintenance definition
+per registered managed Project, inspect it, and request independent Runs:
+
+```sh
+yui job define --global --job project-refresh-project-7 --title "Refresh Project 7" \
+  --input '{"kind":"builtin","action":"project.refresh","projectId":"project-7","input":{}}'
+yui job show --global --job project-refresh-project-7
+yui job run --global --job project-refresh-project-7 --request-id refresh-001
+yui job runs --global --job project-refresh-project-7
+yui job run-get --global --job project-refresh-project-7 --run <exact-run-id>
+yui job logs --global --job project-refresh-project-7 --run <exact-run-id>
+```
+
+These examples configure intent; installation, migration and Project registration
+never install or run a default Job or Schedule. Task Sessions cannot use this
+entry point. The Job remains global; `configuration.projectId` identifies its
+target, not an owning Task. Duplicate refresh definitions for the same Project
+are refused with the existing Job ID; `job list --global` also discovers it.
+
+Empty action input explicitly binds the current catalog's Project ID, path,
+ownership, lifecycle, remote URL and stable/development branches into
+`input.targetDigest`. The digest is generated from authoritative configuration,
+not a caller-supplied checkout path. Each Run retains this immutable input.
+Admission, pre-spawn authorization and the domain action after lock acquisition
+recheck the current target. Missing/retired/external Projects and changed targets
+fail closed. After inspecting an intentional configuration change, use
+`job update --revision <observed-revision>` with the same action and empty input
+to bind it explicitly. Run/retry never silently rebinds an old definition.
+
+`project refresh <project>` and the Job call the same Project domain service and
+maintenance lock. The existing manual external-Project behavior is unchanged;
+automatic writes require active **managed** ownership. Both require matching
+stable and development branches. Git checks clean/untracked state, exact branch
+and HEAD; fetch isolates FETCH_HEAD, unrelated tracking refs and maintenance;
+only verified fast-forward and compare-and-swap tracking updates are allowed.
+There is no reset, rebase, guessed checkout, user remote rewrite or semantic
+Knowledge/Skill update. Lock waiting is bounded and never retries the Git action.
+
+The existing detached Job runner invokes a fixed Project-domain executable.
+That action reads current catalog/Run authority through a read-only Store and
+writes Git only through the shared service. The generic runner remains
+artifact-only. Runtime-owned PATH, HOME, SSH agent socket and Git config
+locations are passed for Git discovery/authentication; callers cannot supply
+commands or environment. Interactive Git prompts are disabled, and the action
+has a ten-minute timeout. At most four supervised Project refresh attempts
+are started concurrently; one Project's failure does not stop another.
+Cancellation/timeout uses the existing process-group and unknown-effect contract.
+
+For UI consumers (Task129), the action label is `project.refresh`, target is
+`configuration.projectId`, and `job show/list` adds a **derived** `refresh`
+projection with `lastAttempt` and `lastSuccessfulRefresh` exact Run references,
+revision, trigger, status and timestamps. It is not separately stored.
+A projection includes only refresh Runs for the definition's exact Project and
+target digest; changing action or rebinding a remote/path/branch does not inherit
+another target's successful observation. Full history remains in `job runs`.
+A failed or unknown attempt never advances success. The Run supplies trigger
+source, status, terminal error and artifact identity. `job logs` returns bounded
+step output: successful refresh JSON contains `projectId`, `trigger`, observed
+time, verified remote commit and `refresh.fromCommit/toCommit/tracking`.
+Git-stage failures include `details.refresh` with observed partial HEAD/tracking
+effects and any retained temporary ref. Earlier refusals have no successful
+remote observation. Missing exit evidence, timeout or cancellation must not be
+presented as successful synchronization; inspect retained evidence before retry.
+The Run's all-zero `head` is not a Project revision; use the action's observations.
+
+No persistent envelope/table change is needed: action input and output use the
+existing JobDefinition/JobRun JSON and logs. Schedule should reference this same
+global definition and use its existing admission seam, never a second Project
+automation state. The isolated core scenario covers interval-triggered refresh
+Runs, missed-period coalescing and disable behavior against a local Git remote.
+This does not enable a cadence for any real Project.
+
+## Local Web management
+
+The Task's **Jobs** tab manages only that Task. **Settings → Jobs & schedules**
+manages global definitions. Both use the same component and public services.
+Create/edit a definition, run it immediately, select an exact historical Run
+and read its snapshot/results/logs, or request cancellation of that Run.
+Task shell configuration uses the same explicit managed-workspace specification
+as the CLI; global creation offers only `system.noop` and `project.refresh`.
+Creating or reading a Job never executes it.
+
+The HTTP routes are `/api/tasks/:taskId/jobs|schedules` and
+`/api/settings/jobs|schedules`. GET takes `op`, `id` and optional `runId`; POST
+takes the corresponding public operation fields, with `requestId` for manual
+Run admission. Routes fix scope. Browser-supplied `caller`, `scope` or trigger
+authority is rejected. The loopback token authenticates the local-user ingress,
+and writes additionally require an exact same Origin. The adapter resolves the
+current Operator Session from the server store on every call; if none is
+available, management reports that prerequisite rather than fabricating one.
+Its accepted Jobs/Schedules retain the normal Operator binding/revocation
+semantics. Managed RPC callers retain their existing authentication and cannot
+borrow this local-user adapter.
+
+Schedule forms support once, anchored interval and five-field cron with an
+explicit timezone. Displayed next due and last success come from the service.
+Disable affects future admissions, cancellation affects one exact Run, and a
+manual Run does not move the cadence. Once `completed` means admitted, not
+successful. Errors retain the draft; an unknown write is not automatically
+resent. Refresh only reads facts and keeps the selected Run exact. No new
+tables, scheduling loop, Project switch, implicit refresh or deletion semantics
+are introduced.

package/docs/project-delivery-scope.md

@@ -0,0 +1,59 @@
+# Task Project delivery scope
+
+Project bindings, delivery obligations, observed code changes and remote merge
+facts have different meanings. A Task may retain a temporary implementation in
+one Project while delivering its accepted result from another. Do not delete a
+binding or fabricate a Publication to express that decision.
+
+Read the original scope instruction and `yui task remote-delivery <task>`.
+An authorized user, Operator or current delivery Leader can record one bounded,
+append-only decision:
+
+```sh
+yui task project delivery task-1 project-2 \
+  --requirement excluded \
+  --reason "The accepted standalone implementation replaces the temporary one" \
+  --source-message message-3 \
+  --purpose "Only deliver the standalone implementation" \
+  --if-current none
+```
+
+The Message must be original user/Operator input in this Task and the purpose
+must be an exact quote. The Agent judges whether it authorizes this Project
+change, including an explicit delegation of scope judgment; the CLI verifies
+identity/provenance, not natural-language permission. A Role report, convenient
+reason or invented quote is not authorization to abandon unmet requirements.
+
+Use the latest `scopeDecision.id` from remote-delivery instead of `none` for
+subsequent decisions. To restore delivery, record `--requirement required` with
+its current guard and an appropriate original source. A stale guard fails
+without overwriting the current decision. After an uncertain write, inspect
+the decision before retrying; do not issue a new decision blindly.
+
+Active and completed, unarchived Tasks with enabled execution accept these
+management decisions. Completed Tasks stay completed; frozen heads, acceptance
+and Publication history remain intact. No new execution or cleanup permission
+is created. Archived, cancelled and stopped Tasks cannot use this operation to
+resume or replace lifecycle intent.
+
+The shared projection exposes `deliveryRequirement`, `scopeDecision` and
+`deliveryRequired` alongside unchanged `codeDelivery` and merge/verification
+facts. `codeProjectCount` still counts all changed or unknown Projects;
+`requiredCodeProjectCount` is the obligation denominator, and
+`excludedProjectCount` identifies explicit exclusions. Aggregate merged/verified
+counts and `allMerged`/`allVerified` cover required code Projects only. A zero
+denominator yields `status: none` (no delivery obligation), not evidence that
+excluded code was merged. Missing heads/bases are unknown, never no-change.
+
+CLI, current context, Web and ordinary archive use that projection. An unchanged
+Project needs no exclusion; a required changed Project needs exact verified
+remote coverage. Ordinary archive still requires settled WorkItems, inputs,
+reviews, integrations/jobs and stopped execution. Physical cleanup separately
+protects dirty files and excluded, unverified local commits. Logical archive can
+succeed with retained resources, which remain owned and inspectable through
+archive diagnostics and explicit cleanup. Exclusion never authorizes deletion
+or force archive, nor changes Project-global state.
+
+Storage 1.11 → 1.12 only admits the new event semantics through the centralized
+minor upgrade chain. It does not rewrite old records or invent scope decisions.
+No new table, workflow state, scan or background recovery service is added.

package/docs/release-workflow.md

@@ -51,6 +51,92 @@ 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.10.0 compatibility and migration notes
+
+This stable minor includes exact-turn inbox handling and successor recovery
+(Task131 / PR #463 and Task134 / PR #464), plus authenticated trusted-LAN Web
+access and current Operator lifecycle controls (Task135 / PR #465).
+It also includes explicit Task Project delivery scope and safe ordinary archive
+(PR #462), and deployment-specific GitLab publication URLs (PR #461).
+
+Web still defaults to loopback. Explicit private/wildcard binding requires
+`--auth-file <absolute-path>` with an owner-only password file; the browser
+username is `yui`. Authentication precedes workbench content, APIs and Terminal,
+while sandbox previews retain their narrower, listener-scoped read tickets.
+HTTP remains unencrypted: use a trusted network, not a public deployment.
+Current Operator starts, `--detach`, and `--json` return Controller-owned
+receipts; inspect with `yui web --status` and stop with `yui web --stop`.
+Credential rotation requires stop/start, and Controller recovery does not
+automatically reopen Web. See [controlled Web access](web-access.md).
+
+Inbox consumers should use the current/history views and exact returned
+identities. Missing acknowledgement is not proof that work was never executed.
+A successor inspects original input and prior effects before settling a retained
+claim; it does not replay the input or borrow another Session's authority.
+Exact terminal handling checks remain bounded. Project delivery exclusions
+require original scoped authorization and do not erase bindings or prove a merge.
+See [CLI information contracts](cli-information-contract.md) and
+[Project delivery scope](project-delivery-scope.md).
+
+Storage advances from **1.11 to 1.13** through the centralized transitions:
+**1.12** declares Project delivery decisions; **1.13** declares exact inbox
+attempt/target identities, Global input retirement and terminal handling checks.
+Historical messages, claims and acceptance evidence are preserved without
+inventing old Turn ownership or ACKs. Supported **1.0–1.12** Homes use the
+existing same-major update path. With separate update authorization, use
+`yui update --version 2.10.0`; the updater owns preflight, backup, migration and
+Controller handover. Do not open upgraded Homes with an older binary or edit
+storage manually. Package minor numbering is not a blanket compatibility promise.
+
+Release gates reuse exact-commit Core CI and test one runtime tarball on
+Linux x64 and macOS x64/arm64 with Node 20/22/24/26 before npm publication.
+These are deterministic and isolated runtime checks, not real-model validation.
+Publishing does not update any global CLI, migrate a production Home, replace
+an Agent Session or start a production Web listener.
+
+### 2.9.0 compatibility and migration notes
+
+This stable minor includes scoped Job definitions and exact execution Runs,
+persistent Schedules, controlled Project refresh, and their Task/settings
+management UI. It also includes Task124's activation-source and bounded
+temporal-context changes (PR #458) and Task130's tool-neutral publication
+verification (PR #459).
+
+There are deliberate interface changes. Job definitions and Runs have distinct
+identities; existing `job start/get/cancel/acknowledge` continue to address
+one-shot Task executions, while `job define/run/runs/run-get` manage the new
+definition/Run model. Schedules reference scoped Jobs and do not replace Run
+results. `task brief update` now requires the `writeGuard` from `task brief show`
+as `--if-current`; reread and reconcile after a stale-guard rejection. Activation
+requests require explicit source provenance for Leaders. Context consumers must
+respect bounded pages, frozen references and Home/Task-bound event continuations.
+See [Jobs](job-runs.md), [Schedules](schedules.md) and
+[CLI information contracts](cli-information-contract.md).
+
+Leaders may verify a PR/MR through any authorized CLI/API and record exact
+structured evidence with `task publication verify --observation`. Built-in
+gh/glab adapters remain optional. `publication upsert --verified` can no longer
+assert verification without evidence; use the verification entry point instead.
+Existing historical evidence is retained. Candidate/object binding, immutable
+history, observation freshness and ordinary archive safety remain enforced;
+tool output interpretation remains the authorized Leader's responsibility.
+
+Storage advances from **1.8 to 1.11** through the centralized contiguous
+migrations: **1.9** adds Job definitions/global Runs and preserves each old
+Task execution's identity and original payload; **1.10** adds Schedules;
+**1.11** declares activation-source event provenance without inventing historical
+sources or rewriting frozen digests. Supported **1.0–1.10** Homes use the
+existing same-major update path. With update authorization, run
+`yui update --version 2.9.0`; the updater owns preflight, backup, migration and
+Controller handover. Do not open an upgraded Home with an older binary or edit
+storage manually. Missing historical provenance remains an explicit diagnostic.
+
+Release validation uses exact-commit Core CI and the existing fresh-install
+matrix for the same runtime tarball on Linux x64, macOS x64/arm64 and Node
+20/22/24/26, with checksums and npm provenance. This is not real-model or company
+API validation. Package publication does not itself update any global CLI,
+Home or Controller; that is a separately authorized Operator operation.
+
 ### 2.8.1 compatibility and migration notes
 
 This patch fixes maintenance startup for an existing Operator conversation

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

@@ -36,6 +36,74 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 不能将不兼容冒称为兼容，也不为回避版本选择新增历史兼容机制。包版本与协议、
 持久存储契约仍然独立：兼容性检查和必要迁移要求不变，下文存储规则不授予发版权限。
 
+### 2.10.0 兼容性及迁移说明
+
+本稳定 minor 包含精确 Turn 收件箱处理与继任恢复（Task131 / PR #463、
+Task134 / PR #464），以及受认证保护的可信内网 Web 和当前 Operator 生命周期
+控制（Task135 / PR #465）。同时纳入显式 Task Project 交付范围与安全普通归档
+（PR #462），以及部署特定 GitLab 发布 URL 支持（PR #461）。
+
+Web 默认仍为 loopback。显式私网／通配监听要求
+`--auth-file <absolute-path>` 指向仅本用户可访问的密码文件，浏览器用户名为 `yui`。
+工作台页面、API 和 Terminal 之前必须认证；沙箱预览保留仅授权当前监听内特定
+服务读取的窄票据。HTTP 仍不加密，只应在可信网络使用，不用于公网部署。
+当前 Operator、`--detach` 和 `--json` 启动返回 Controller 持有的回执；
+通过 `yui web --status` 查询、`yui web --stop` 停止。轮换密码需停止后重启，
+Controller 恢复不会自动重新开放 Web。详见[受控 Web 访问](web-access.md)。
+
+收件箱调用者应使用 current/history 视图及返回的精确身份；缺少 ACK 不代表
+工作未执行。继任 Session 先检查原始输入和既有效果，再处理保留的 claim，
+不重放输入，也不借用另一 Session 的权限。精确 terminal 的处理检查保持有界。
+Project 交付排除须有原始范围授权，不删除 binding，也不证明代码已合并。
+详见 [CLI 信息契约](cli-information-contract.zh-CN.md)和
+[Project 交付范围](project-delivery-scope.md)。
+
+存储经集中式连续迁移从 **1.11 升至 1.13**：**1.12** 声明 Project 交付决策；
+**1.13** 声明精确 inbox attempt/target 身份、Global 输入退役及 terminal 处理检查。
+历史消息、claim 和验收证据保留，不猜造旧 Turn 归属或 ACK。受支持的
+**1.0–1.12** Home 沿用同 major 更新路径。另获更新授权后使用
+`yui update --version 2.10.0`，由更新器负责预检、备份、迁移与 Controller 交接；
+不要用旧程序打开升级后的 Home，也不要手工编辑存储。包 minor 编号不代表
+对所有接口作向后兼容承诺。
+
+发布门禁复用精确提交的 Core CI，并在 npm 发布前对同一 runtime tarball 执行
+Linux x64、macOS x64/arm64 与 Node 20/22/24/26 的全新安装验证。
+这是确定性和隔离运行时证据，不是真实模型验证。发布不会更新全局 CLI、
+迁移生产 Home、替换 Agent Session 或启动生产 Web。
+
+### 2.9.0 兼容性及迁移说明
+
+本稳定 minor 包含分作用域的 Job 定义与精确执行 Run、持久 Schedule、受控 Project
+刷新，以及 Task／设置页中的管理界面。同时纳入 Task124 的激活来源与有界时序
+上下文改动（PR #458）和 Task130 的工具中立交付验证（PR #459）。
+
+本版包含明确的接口变化：Job 定义与 Run 使用不同身份；原有
+`job start/get/cancel/acknowledge` 仍针对单次 Task 执行，新
+`job define/run/runs/run-get` 管理定义／Run 模型。Schedule 引用同作用域的 Job，
+不替代执行结果。`task brief update` 现在必须把 `task brief show` 返回的
+`writeGuard` 作为 `--if-current` 提交；旧 guard 被拒绝后需重读并协调修改。
+Leader 的激活请求必须提供明确来源。上下文消费者须遵循有界分页、冻结引用、
+Home／Task 绑定的事件续读契约。详见 [Jobs](job-runs.md)、
+[Schedules](schedules.md) 和 [CLI 信息契约](cli-information-contract.zh-CN.md)。
+
+Leader 可通过任意已获授权的 CLI/API 核验 PR/MR，再用
+`task publication verify --observation` 保存精确结构化证据；内置 gh/glab
+适配器仍为可选路径。`publication upsert --verified` 不再允许无证据声明验证，
+应改用正式验证入口。已有历史证据保留；候选／对象绑定、不可变历史、观察时效和
+普通归档安全边界继续执行，工具输出的语义判断仍由获授权 Leader 负责。
+
+存储经集中式连续迁移从 **1.8 升至 1.11**：**1.9** 新增 Job 定义／全局 Run，
+保留每个旧 Task 执行身份及原始 payload；**1.10** 新增 Schedule；**1.11**
+声明激活来源事件属性，不猜造历史来源或改写冻结摘要。受支持的 **1.0–1.10**
+Home 沿用同 major 更新路径。获更新授权后执行 `yui update --version 2.9.0`，
+由更新器负责预检、备份、迁移与 Controller 交接；不要用旧程序打开已升级 Home，
+也不要手工编辑存储。缺失的历史来源仍明确报告为诊断。
+
+发布验证使用精确提交的 Core CI，以及针对同一 runtime tarball 的既有全新安装
+矩阵，覆盖 Linux x64、macOS x64/arm64 和 Node 20/22/24/26，并保留校验和及 npm
+来源证明；不冒称真实模型或公司 API 验证。包发布本身不会更新任何全局 CLI、
+Home 或 Controller，这由另行获授权的 Operator 操作负责。
+
 ### 2.8.1 兼容性及迁移说明
 
 本 patch 修复已有 Operator 会话仅携带 native 身份（包括 Codex Desktop）时的