@zq-silk/yui 0.15.11 → 0.15.12

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

@@ -69,3 +69,50 @@ Telemetry 和缓存是诊断材料，不是 Task 真相，也不是 transcript
 
 从精确的只读记录开始。进程变更、取消、grant 更新和资源清理都需要相应的显式动作
 与范围。一个笼统的诊断请求不授权真实模型、共享或生产环境的测试。
+
+## Task 用量与耗时
+
+Task overview、Web Task/WorkItem 卡片和 `execution audit` 共用授权 Task
+事件的纯读投影。读取不采样 Provider、不打开原始 transcript；没有新增指标存储、
+迁移、价格表或预算策略，既有历史仍可读。
+
+每项指标带 `value`、`status`（`known`、`partial`、`unknown`）和 `reasons`。
+未知为 `null`，不是零；真实零必须有数值证据。部分值是已观测小计，不是完整账单，
+也不保证是单调增长的下界。覆盖说明包括已观测 Session 身份、来源/计数语义和
+证据截止点，不对不可知的 Provider 总量伪造覆盖百分比。口径是 Task 围栏内的
+已观测来源。
+JSON 使用方改读 `cost.tokens.value`、`cost.toolCalls.value` 及其状态/原因，
+不再读取数字占位和 observable 标志。`elapsedSeconds`、`executionSeconds`
+替代含义错误的 Group 求和 `wallClockSeconds`；这是读投影变更，不是持久存储变更。
+
+- 请求用量复用 Session reducer：按稳定请求身份取最后收到的修订，累加输入与
+  输出，缓存/推理子项不重复增加。缺失边界、混合语义、累计回退不猜测；剩余
+  上下文是容量，不是消费。
+- Session 替换不抹去历史。首次非零累计快照可能早于 Task，因此作为排除基线；
+  后续可比增量为部分值，仅一个非零快照时 Task 用量未知。零基线可支持后续
+  累计值。JSON 单独暴露原始 Session 计数，它不是额外的 Task 消费。
+- Leader 直聊不需要伪造 Run/WorkItem。WorkItem 仅接收各次修订均绑定同一
+  精确、匹配 Run 的请求用量；累计值不摊派，整个 Session 的原始计数不冒充
+  WorkItem 用量。Task 总量不必等于 WorkItem 小计之和。
+- 当前合同无法证明子执行计数在父统计之外，因此排除子计数并将覆盖标为部分。
+  多个 Role 对同一原生计数器的归属冲突为未知，不当成两份独立总量。
+- 工具次数按保留的精确原生 Session/Turn/operation 身份去重，失败调用也计一次。
+  工具历史已压缩，有证据时只能是部分次数；无证据为未知，不能推出零调用。
+
+**任务历时**从 Task 创建（含规划和等待）到记录的完成、退役或取消时间；
+活动 Task 截止本次读取时间。归档保留原终点，终态证据缺失则未知，与 Group
+数量无关。
+
+**已观测原生执行累计**合并同一原生资源上起止完整、彼此重叠的 Turn 区间，
+再相加独立并行资源。两个独立执行各十秒，可以在十秒自然时间内累计二十秒。
+它不是 CPU/GPU 时间。由于 Turn 历史已压缩，该指标为部分值；缺少起止证据和
+运行中的 Turn 不计入，不无限延长。保留不足一秒的精度，WorkItem 卡片不再用
+Group 时长替代上述含义。
+
+即使 `--since`、`--until` 过滤其他审计部分，`usage` 部分仍明确为 **Task 全生命周期**。
+首版不提供窗口消费，不能先过滤累计快照，再把历史消费称为窗口用量。
+既有 AgentRun 时长部分保留为单独标明的 Run 指标。
+
+确定性 fixture 验证共享 reducer 和 CLI/Web/audit 语义，不证明真实 Provider 的
+覆盖完整性。内置归一化支持来源所提供的 Codex 累计观察和 Claude 请求观察；
+本次交付不采集真实模型账单证据，也不声称已实测真实 Provider 行为。

package/docs/project-refresh.md

@@ -0,0 +1,77 @@
+<p align="right"><strong>English</strong> | <a href="./project-refresh.zh-CN.md">简体中文</a></p>
+
+# Project refresh
+
+`yui project refresh <project>` refreshes the canonical Project checkout from
+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.
+
+## Two separate facts
+
+The checkout HEAD and a local remote-tracking ref are distinct observations.
+Refresh fetches the exact branch into a unique temporary ref, compares its
+commit with the remote's advertised commit, and permits only a clean
+fast-forward from the original HEAD on the stable branch. Configured `HEAD`
+is resolved through the remote's symbolic HEAD, never a guessed default branch.
+
+When exactly one existing Git remote and fetch mapping manages a safe tracking
+destination, refresh also updates that destination to the verified commit.
+This runs even when HEAD is already current, repairing stale tracking refs
+that would otherwise make ordinary Git show a false `ahead` count.
+
+The mapping uses Git's effective fetch URL, including `insteadOf` resolution,
+and full-ref exact or one-star fetch refspecs with negative exclusions. It
+does not assume `origin` or `refs/remotes/<remote>/<branch>`. A configured
+destination under `refs/remotes/` can be created if absent. Multiple matching
+remotes/URLs, multiple destinations, another source managing the same target,
+unsupported refspecs, local-branch/tag destinations and symbolic destinations
+are explicitly unmanaged. Push URLs never establish fetch identity.
+
+Only the unique mapped ref can change. Fetch does not opportunistically update
+other tracking refs, fetch/prune tags, recurse into submodules, or write
+`FETCH_HEAD`. Remote/upstream configuration is never rewritten. Read-only
+tracking observations use the same mapping proof and return no tracking match
+when it is not uniquely established.
+
+## Results and concurrent changes
+
+- `fromCommit`, `toCommit` and `changed` describe HEAD; `changed: false` does
+  not imply that no tracking repair occurred.
+- `tracking.status` is `updated` or `current` for a synchronized target,
+  with its exact ref and old/new object IDs.
+- `tracking.status: unmanaged` includes a reason. HEAD can still refresh
+  successfully, but this is not a claim of tracking consistency.
+- Once work has started, a failed refresh uses the existing nonzero
+  `RUNTIME_ERROR` channel. JSON `details.refresh` retains observed HEAD,
+  the verified commit when available, and the tracking result (`failed` for
+  a managed target). Missing/unreadable observations are nullable. Text
+  errors also state the actual partial result. Preconditions can fail
+  before any mutation without a partial-result record.
+
+Refresh rechecks the mapping, cleanliness, branch and HEAD around the update.
+A Git ref transaction verifies the stable branch and compares the tracking
+target against its captured old value (or absence) before writing it. A local
+ref race, changed mapping, divergent checkout or fetched/advertised mismatch
+fails visibly. After a fast-forward, a failed tracking update leaves HEAD at
+its actual new commit; it never rolls back or overwrites a competing ref.
+There is no automatic retry, replay or background synchronizer.
+
+Temporary-ref cleanup compares the known fetched object before deletion.
+An unsuccessful cleanup reports the retained ref; an interrupted/failed fetch
+can report the exact temporary namespace to inspect. These are Git diagnostics,
+not durable Task progress or a new recovery protocol.
+
+The maintenance fence serializes Yui maintenance, not arbitrary external Git
+commands or user edits. Checks and Git locks bound the observed operation;
+they do not promise that local or remote state cannot change after observation.
+Ordinary `git status` loses the false `ahead` count only when the current
+branch's upstream is the tracking ref refreshed here. A different/missing
+upstream is left untouched and carries no such promise.
+
+## Scope of adoption
+
+This operation adds no persistent Yui schema or migration. Installing code
+that implements it does not itself refresh a real Project. A normal authorized
+refresh applies the behavior; Task completion, integration, publication and
+archive remain separate operations.

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

@@ -0,0 +1,59 @@
+<p align="right"><a href="./project-refresh.md">English</a> | <strong>简体中文</strong></p>
+
+# Project refresh
+
+`yui project refresh <project>` 按 Project 配置的 remote 和 stable branch 刷新
+规范 checkout。stable 与 development branch 必须一致。操作全程持有 per-Project
+maintenance fence；不会刷新 Task 工作区或改写其记录的基线。
+
+## 两个独立事实
+
+checkout HEAD 与本地 remote-tracking ref 是不同的观察。refresh 将精确分支获取到
+唯一临时 ref，比较获取到的提交与远端 advertised commit，仅允许从原 HEAD 在干净的
+稳定分支上 fast-forward。配置为 `HEAD` 时解析远端 symbolic HEAD，不猜默认分支。
+
+当且仅当一个既有 Git remote 及其 fetch 映射管理安全的 tracking 目标时，refresh
+同时将该目标更新到已验证的提交。HEAD 已最新也执行这一检查，修复会让普通 Git
+错误显示 `ahead` 的陈旧 tracking ref。
+
+映射使用 Git 生效的 fetch URL（包括 `insteadOf` 解析），支持完整 ref 名称的
+精确或单星号 fetch refspec，并处理负向排除。不假定 `origin` 或
+`refs/remotes/<remote>/<branch>`。已配置的 `refs/remotes/` 目标缺失时可以创建。
+多个匹配 remote/URL、多个目标、其他来源也管理同一目标、不支持的 refspec、
+本地分支/标签目标和符号引用目标，均明确标为未管理。push URL 不证明 fetch 身份。
+
+只允许修改唯一映射目标。fetch 不顺带更新其他 tracking refs、不获取/修剪标签、
+不递归获取 submodule、不写入 `FETCH_HEAD`，也不改 remote/upstream 配置。
+只读 tracking 观察复用相同映射证明；无法唯一确证时不返回 tracking 匹配。
+
+## 结果与竞争
+
+- `fromCommit`、`toCommit`、`changed` 描述 HEAD；`changed: false` 不代表没有
+  发生 tracking 修复。
+- `tracking.status` 为 `updated` 或 `current` 时，目标已同步，并包含精确 ref
+  和新旧对象 ID。
+- `tracking.status: unmanaged` 带有原因。HEAD 仍可刷新成功，但不声称 tracking
+  一致。
+- 操作开始后失败，沿用非零的 `RUNTIME_ERROR` 通道。JSON 的 `details.refresh`
+  保留实际观察到的 HEAD、可用时的已验证提交和 tracking 结果（受管目标为
+  `failed`）。缺失或不可读的观察可为 null。文本错误也说明实际部分结果。
+  变更前的前置条件失败可以不带部分结果。
+
+refresh 在更新前后复查映射、干净状态、分支与 HEAD。Git ref 事务同时验证稳定分支，
+并以捕获的旧值（或不存在）比较后写入 tracking 目标。本地 ref 竞争、映射变化、
+checkout 分歧或 fetched/advertised 不一致都会显式失败。ff 之后 tracking 更新失败，
+HEAD 保留实际的新提交；不会回滚或覆盖竞争方的 ref。不自动重试、重放，也没有后台
+同步器。
+
+清理临时 ref 时比较已知 fetched 对象后才删除。清理失败报告保留的 ref；获取中断或
+失败可报告供检查的精确临时命名空间。这些是 Git 诊断，不是持久 Task 进度或新恢复协议。
+
+maintenance fence 串行化 Yui 维护，不锁住任意外部 Git 命令或用户编辑。检查和 Git
+锁约束本次观察，不承诺观察之后本地或远端不再变化。只有当前分支 upstream 指向此次
+刷新的 tracking ref，普通 `git status` 才会消除相应虚假 `ahead`。不同或缺失的
+upstream 保持原样，不作这一承诺。
+
+## 采用边界
+
+本操作不新增 Yui 持久 schema 或迁移。安装实现代码不等于刷新真实 Project；
+正常获授权的 refresh 才应用此行为。Task 完成、集成、发布和归档仍是独立操作。

package/docs/provider-retry.md

@@ -0,0 +1,70 @@
+# Bounded Provider recovery
+
+Yui can continue an owned input after a positively identified transient Provider
+failure without discarding its Session or local work. The Driver supplies failure
+and native-state evidence; the Controller schedules and atomically admits the
+next input. Agents still own semantic recovery and acceptance.
+
+- At most five automatic attempts after the initial failure, within ten minutes.
+- Exponential windows start at five seconds and cap at sixty seconds, with
+  50–100% jitter. A trusted Retry-After is a minimum, with positive jitter.
+  A wait beyond the remaining deadline ends automatic recovery.
+- Busy/admission waiting does not consume a model attempt. Acceptance, heartbeat
+  and partial output do not reset the streak. Only the matching successful
+  native terminal ends the chain; audit history remains.
+- A rejected input retains its original durable reference. An accepted failed
+  Turn gets a new Turn in the same Session with a system recovery instruction:
+  inspect existing work and receipts and continue only unfinished actions.
+- Unknown acceptance is never replayed. Existing exact-identity reconciliation
+  may supply the missing outcome. Restarting the Controller does not reset the
+  counter, deadline, pending input or writer fence.
+- An explicit manual retry of the same Run retains its recovery lineage,
+  automatic count and original deadline. It is not charged as an automatic
+  attempt, but a further failure cannot replenish automatic allowance.
+
+The records live on the existing Provider binding, with indexed pending-record
+reads and the existing Controller deadline timer. There is no retry Task status,
+second queue, automatic Session replacement, account-wide circuit breaker or
+model switch. The original failed AgentRun stays failed; ordinary Run/Review
+retry primitives own its successor and keep the original ReviewRound.
+
+## Inspect and control
+
+Task Sessions:
+
+```sh
+yui task role session retry <task> <role> show
+yui task role session retry <task> <role> cancel
+yui task role session retry <task> <role> disable
+yui task role session retry <task> <role> enable
+```
+
+Global Sessions use `yui session retry <role> show|cancel|disable|enable`.
+This narrow existing Session surface does not register the unrelated
+top-level Global `role` command family.
+
+The same projection appears in Context, Session inspection and the Web role
+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.
+
+## Supported boundary and adoption
+
+Current controlled Codex Hosts advertise exact recovery support. The native
+preflight checks the latest failed Turn identity for accepted-input recovery
+and a complete empty background-terminal page; ordinary `systemError` admission
+remains closed. Missing protocol methods, a changed/active Turn, unresolved
+background execution or a changed Session/configuration require inspection,
+not automatic cleanup. Native chats without an owned input reference, old Hosts,
+and Adapters without this proof capability are not automatically replayed.
+Claude/ACP retain their normal error and explicit recovery behavior.
+
+Storage transition 26→27 adds optional recovery/input facts and indexes without
+scanning or scheduling old failures. Adoption requires the normal explicitly
+authorized release/upgrade and compatible Host lifecycle. Building or completing
+this Task does not enable the change in an already-running shared instance.
+
+Deterministic checks use disposable SQLite Homes, fake native protocol and
+injected time; they do not establish real-provider behavior or idempotency of
+arbitrary external tools. External effects still require their normal authority
+and receipt/idempotency protections.

package/docs/task-delivery.md

@@ -13,6 +13,9 @@ prepares physical workspaces, and adopts status/ownership atomically. Failed
 preparation leaves the Task Draft with a failed request and a diagnosis delivered
 to the Leader. Deferred activation retains the exact intent and waits for native
 quiescence, whether requested in a planning Run or subsequent discussion.
+Project maintenance contention waits asynchronously before resource adoption.
+A lock timeout or cancelled wait preserves the original activation request;
+after acquiring the lock, activation rechecks current intent and authority.
 
 Task type describes the requested outcome, not the mandatory executor.
 Leader owns bounded work directly or assigns substantial independent WorkItems.
@@ -22,7 +25,8 @@ attempts at the same frozen Assignment, followed by Leader-selected synthesis.
 ## Managed workspaces
 
 Stable Project checkouts are read-only references. Task main is a logical
-multi-Project root with per-Project Git worktrees. For one Project, the Agent's
+multi-Project root with independent per-Project Git clones; WorkItem, Review and
+Integration worktrees belong to those Task repositories. For one Project, the Agent's
 normal cwd is its managed Git root; for multiple Projects, the root and native
 additional-directory mechanism expose the explicit Project set.
 
@@ -75,31 +79,147 @@ Leader delivery. The current native turn must end so the pending notification
 can arrive; the Leader then reads the original message and reassesses completion.
 This derives from existing Messages and mailbox delivery, not a second
 acknowledgement or workflow state.
-Terminal workspace cleanup can remain an advisory at completion, but not at
-archive. Artifacts selected as results must be fixed, present and Task-local.
+Terminal workspace cleanup can remain an advisory at completion. Ordinary
+archive requires it to be settled; explicitly authorized force archive may
+retain unresolved resources as described below. Artifacts selected as results
+must be fixed, present and Task-local.
 
 Publication records a remote PR/MR reference. Reported merge, independently
 verified merge and exact Task-head coverage are separate facts. Task completion
 does not prove any of them. Remote delivery is read from exact publication/head
 evidence, not inferred from a title or branch name.
 
+Completion heads remain the immutable acceptance baseline. A later, authorized
+integration may produce a different publication candidate (including a rebase
+or merge before a remote squash). Neither ancestry nor a successful Integration
+proves that the accepted behavior survived, or accepts additional changes.
+
+For a completed, unarchived Task, record the exact candidate as the Publication's
+`localCommit`, then read `task publication diff <task>/<publication>`. This reads
+only Task-owned local Git objects and returns the original completion reference,
+both commit/tree endpoints, the full diff (including binary changes), and a
+digest binding those facts. Review removals, additions and conflict resolutions
+against the original requirements. If they preserve the accepted result and all
+relevant increments are accepted, use
+`task publication adopt <task>/<publication> --reviewed-diff <sha256> --acceptance <text>`.
+The acceptance must explain that judgment and its verification/review evidence;
+Core checks fixed identity and facts, not the meaning of the code. If an existing
+Task Integration produced that exact candidate, pass its local ID with
+`--integration <id>` to both commands to bind its committed evidence as well.
+This records one Task event, not a new delivery status, Candidate lifecycle,
+Git operation, or permission to change completed work.
+
+`task publication verify` remains the explicit, authorized provider read. It
+records the remote source head, PR/MR state and merge commit independently of
+Task acceptance. A mismatched head or non-merged state is saved as **reported**,
+superseding earlier verification; provider errors or mismatched external identity
+write nothing. A merged provider observation verifies only that Publication's
+exact local candidate. A squash merge needs no fabricated commit ancestry.
+Metadata/verification successors preserve adoption only through an uninterrupted
+same-candidate Publication lineage. Candidate or referenced Integration changes
+cannot silently reuse the decision.
+
+CLI, current Leader Context and Web derive coverage from these same facts, with
+no provider reads or evidence writes. They distinguish not delivered, merged
+but uncovered, covering merge not verified, partial delivery and verified merge.
+Each Project retains its own accepted head, selected candidate, adoption reference
+and reason. Unknown historical heads remain unknown; old exact-SHA evidence stays
+valid without inventing adoption, and archive never proves remote delivery.
+
 Cancelled intent does not prove the runtime stopped. User/Operator may reopen
 cancelled Tasks; Leader may reopen completed Tasks. Reopening requires fresh
 explicit input/work selection and never replays previous delivery requests.
 
 ## Archive
 
-Archive is a separate authorized action after active work is settled and
-resources are clean and removable. Choose integrated delivery or deliberate
-abandonment explicitly. Integrated archive requires exact merged heads and
-verified publication evidence. An explicitly authorized verification override
-cannot bypass missing or stale heads or an unmerged result.
-
-Managed WorkItem resources must be integrated or deliberately abandoned before
-cleanup. Review, Lane and Integration resources must be settled. Dirty worktrees
-remain for the Agent to resolve; no implicit reset or force deletion occurs.
-Task main branches and durable Task records retain recovery information.
+Archive requires independent user/Operator authorization for an exact completed
+or cancelled (retired) Task. Completion alone grants none, and ordinary archive
+approval does not authorize force. Select one disposition explicitly:
+
+```sh
+yui task archive <task> --integrated
+yui task archive <task> --abandon
+# Only with explicit force authorization, preserving the chosen disposition:
+yui task archive <task> (--integrated|--abandon) --force
+```
+
+### Ordinary archive
+
+Active work and inputs must be settled, and managed resources clean and safely
+removable. WorkItem results must be integrated or deliberately abandoned;
+Review, Lane and Integration resources must be settled. With `--integrated`,
+each Project requiring code delivery needs a merged, verified Publication
+covering its accepted head, either exactly or through valid explicit candidate
+adoption. `--abandon` records deliberate non-delivery,
+not verified merge.
+
+Missing/stale coverage, unresolved execution or dirty worktrees prevent ordinary
+archive. Resolve the reported facts before an explicit retry; no implicit reset
+or force deletion occurs.
+
+### Explicit force archive
+
+`--force` is not merely a merge-verification override. It commits the archive
+and stops new Task scheduling before attempting safe foreground cleanup.
+Missing or stale delivery evidence, an unmerged result, unresolved execution
+and cleanup failures become warnings with retained resource references, rather
+than blocking that archive commit. Authority, eligible lifecycle, exact resource
+identity and mandatory audit persistence still fail closed.
+
+Force neither verifies a merge nor accepts work, proves quiescence, discards
+dirty data or implies `--abandon`. It preserves the selected disposition and
+original Publication/completion evidence. Unverified local commits and resources
+that cannot safely be released stay owned and traceable. A cleanup failure does
+not roll back archive; late runtime events remain source evidence without
+resuming the Task or settling unknown input.
+
+### Read the result before cleanup
+
+`yui task show <task> --json` exposes `data.archive.warnings`,
+`data.archive.retainedResources` and `data.archive.cleanupEvents`.
+`yui task context <task> --json` retains the original records and events;
+`yui task remote-delivery <task> --json` reports delivery separately.
+Warnings include historical cleanup attempts; retained references describe
+current ownership, not a second cleanup queue.
+
+An archive result with `archived=true` proves archival, not that cleanup fully
+succeeded. Even `cleanupFinished` means the foreground pass finished, not that
+every resource was removed. Repeating archive reports current facts and does
+not replay cleanup. After inspection, use explicit exact-owner resource
+operations for safe cleanup; no background retry or broader deletion authority
+is implied. Both archive paths preserve Task history and recovery information.
 Archived Tasks cannot reopen.
 
+`yui task archive-preflight <task> (--integrated|--abandon) [--force] [--json]`
+reads current admission, delivery and exact-owner cleanup checks in one report.
+It is available before and after archive, including to the Task's authorized
+Leader reader. `--force` here only selects the behavior to inspect. It never
+archives, prepares workspaces, refreshes Git indexes, stops Sessions, acquires
+maintenance locks, fetches remote data, or writes a cleanup plan.
+
+Each blocking/unknown check has a resource, reason code, expected and observed
+values, source references and existing inspection/disposition commands. Git
+paths outside the authorized Task are redacted. The report distinguishes
+missing Candidate workspace, changed workspace identity/metadata/path, missing
+frozen commit, moved HEAD, dirty worktree, missing/locked Git registration,
+unintegrated result, uncovered delivery, unsettled owner and unknown execution.
+Status inspection disables optional index writes and filesystem-monitor hooks.
+If a tracked file selects a configured clean/process filter (including an
+initialized submodule's), it reports `git-status-requires-filter` as unknown instead of
+executing the program or bypassing normalization and guessing clean/dirty.
+Historical Candidate paths remain immutable. A path difference, including one
+consistent with an earlier layout migration, does not itself prove a safe
+relocation: without an exact mapping the check reports the difference and
+retains the resource; it does not repair history or weaken commit/owner checks.
+
+Preflight is an observation, not a removal permit. Cleanup reloads the same
+checks and Git verifies ownership/dirt again at removal. A Task-main clone's
+dependent registrations are expected before child cleanup and must be absent
+before clone removal. Archive preserves new dirt even in a failed Integration
+workspace; the separate explicit Integration cleanup command keeps its existing
+disposable-conflict behavior. A finished force cleanup means the foreground
+attempt ended, not that every resource was released. Current retained references
+and exact physical runtime evidence remain separate from historical diagnostics.
+
 Use each command's `--help` to inspect its exact authority and options before
 cleanup; reading a lifecycle document does not authorize an external write.

package/docs/task-delivery.zh-CN.md

@@ -11,6 +11,8 @@ Task 生命周期是 `draft / active / completed / cancelled / archived`。Draft
 状态/所有权。准备失败会让 Task 停在 Draft，附带一个失败请求和投递给 Leader 的
 诊断。延迟激活保留确切意图并等待原生静止，无论它是在规划 Run 中还是在后续讨论中
 被请求的。
+Project 维护争用会在采用资源前异步等待。锁超时或等待被取消时保留原激活请求；
+获得锁后重新检查当前意图与权限。
 
 Task type 描述被请求的结果，而不是强制的执行者。Leader 直接负责有界工作，或分派
 有独立价值的 WorkItem。直接执行没有 Group。复制是为了在同一个冻结 Assignment 上
@@ -19,7 +21,8 @@ Task type 描述被请求的结果，而不是强制的执行者。Leader 直接
 ## 受管工作区
 
 稳定的 Project checkout 是只读参考。Task main 是一个逻辑上的多 Project 根，带有
-按 Project 划分的 Git worktree。对单个 Project，Agent 的正常 cwd 是其受管 Git 根；
+按 Project 划分的独立 Git clone；WorkItem、Review 和 Integration worktree 归这些
+Task 仓库所有。对单个 Project，Agent 的正常 cwd 是其受管 Git 根；
 对多个 Project，根加上原生的附加目录机制暴露明确的 Project 集合。
 
 一个隔离的 WorkItem 为可写 Project 拥有独立 worktree，为其余 Project 提供 Task-main
@@ -58,25 +61,111 @@ Reviewer Run 持有报告；执行成功不等于语义通过。验收归 Leader
 干净且已提交的 Task-main 快照。当有一条新的 user/Operator 消息仍在等待 Leader
 投递时，它也会拒绝完成。当前原生轮次必须结束，待处理的通知才能到达；随后 Leader
 读取原始消息并重新评估完成。这派生自既有的 Message 和 mailbox 投递，而不是第二套
-确认或工作流状态。终态工作区清理在完成时可以只是建议，但在归档时不行。被选作
-结果的 Artifact 必须是固定的、存在的且 Task 局部的。
+确认或工作流状态。终态工作区清理在完成时可以只是建议。普通归档要求清理已结算；
+明确授权的 force 归档可以保留下文所述的未解决资源。被选作结果的 Artifact 必须是
+固定的、存在的且 Task 局部的。
 
 发布记录一个远程 PR/MR 引用。被报告的合并、独立验证的合并以及确切的 Task-head
 覆盖是彼此独立的事实。Task 完成不证明其中任何一项。远程交付从确切的发布/head
 证据读取，而不从标题或分支名推断。
 
+完成 head 始终是不可变的验收基线。之后获授权的集成可能产生不同的发布候选
+（例如远端 squash 前的 rebase 或 merge）。祖先关系和 Integration 成功都不能
+证明验收行为未被撤销，也不验收额外增量。
+
+对于已完成但未归档的 Task，先把精确候选记为 Publication 的 `localCommit`，
+再读 `task publication diff <task>/<publication>`。此命令只读取 Task 自有的
+本地 Git 对象，返回原完成记录引用、两端 commit/tree、完整差异（含二进制变更），
+以及绑定这些事实的摘要。逐项核对删除、增加和冲突处理是否仍满足原需求；仅在原成果
+保留、相关增量也已验收时，执行
+`task publication adopt <task>/<publication> --reviewed-diff <sha256> --acceptance <text>`。
+验收依据应解释上述判断及其验证/审阅证据；Core 核验固定身份和事实，不裁定代码语义。
+如果已有本 Task 的 Integration 产出了该精确候选，在两个命令中都传入
+`--integration <id>`，一并绑定其已提交证据。这只新增一个 Task 事件，不新增交付
+状态表、Candidate 生命周期或 Git 操作，也不授权修改已完成成果。
+
+`task publication verify` 仍是显式且须获授权的 provider 读取。它独立于 Task
+验收，记录远端 source head、PR/MR 状态和 merge commit。head 不匹配或尚未合并时，
+保存为 **reported** 并取代旧验证；provider 错误或外部身份不匹配则不写任何证据。
+已合并的 provider 观察仅验证该 Publication 的精确本地候选；squash 不需要伪造
+提交祖先关系。元数据/验证更新只有沿连续同候选的 Publication 血缘才能继承采用；
+候选或所引用的 Integration 变化，不能悄悄复用旧决定。
+
+CLI、当前 Leader Context 和 Web 从同一组事实推导覆盖，不联网、不写证据。展示
+区分尚未交付、PR/MR 已合并但未覆盖、已覆盖合并但未验证、部分交付、已验证合并。
+每个 Project 保留自己的验收 head、候选、采用引用和原因。缺失的历史 head 仍然
+未知；旧精确 SHA 证据无需补造采用记录，归档也不能反推已交付。
+
 取消意图不证明运行时已停止。user/Operator 可以重开已取消的 Task；Leader 可以重开
 已完成的 Task。重开需要全新的显式输入/工作选择，绝不重放先前的交付请求。
 
 ## 归档
 
-归档是一次单独的授权动作，发生在活动工作已了结、资源干净可移除之后。显式选择
-集成交付或有意放弃。集成归档要求确切的已合并 head 和已验证的发布证据。一次显式
-授权的验证覆盖不能绕过缺失或陈旧的 head，也不能绕过一个未合并的结果。
-
-受管的 WorkItem 资源必须在清理前被集成或有意放弃。Review、Lane 和 Integration
-资源必须已结算。脏 worktree 留给 Agent 解决；不发生隐式 reset 或强制删除。Task
-main 分支和持久 Task 记录保留恢复信息。已归档的 Task 不能重开。
+归档需要针对确切的 completed 或 cancelled（retired）Task 获得独立的 user/Operator
+授权。完成本身不授予归档权限，普通归档批准也不授权 force。显式选择一种处置：
+
+```sh
+yui task archive <task> --integrated
+yui task archive <task> --abandon
+# 仅在明确授权 force 后使用，并保留所选处置：
+yui task archive <task> (--integrated|--abandon) --force
+```
+
+### 普通归档
+
+活动工作与输入必须已了结，受管资源干净且可安全移除。WorkItem 结果必须已集成或
+有意放弃；Review、Lane 和 Integration 资源必须已结算。使用 `--integrated` 时，
+每个需要代码交付的 Project 都要求已合并且已验证的 Publication，通过精确匹配
+或有效显式采用候选覆盖其验收 head。`--abandon` 记录有意不交付，而不是已验证合并。
+
+缺失或陈旧的覆盖、未解决的执行或脏 worktree 会阻止普通归档。先解决报告的事实，
+再显式重试；不会隐式 reset 或强制删除。
+
+### 明确授权的 force 归档
+
+`--force` 不只是覆盖合并验证要求。它先提交归档并停止新的 Task 调度，再尝试安全的
+前台清理。缺失或陈旧的交付证据、未合并结果、未解决的执行和清理失败会成为警告及
+保留资源引用，而不阻止这次归档提交。权限、合法生命周期、精确资源身份和强制审计
+持久化仍严格检查，失败时拒绝相应操作。
+
+Force 不验证合并、不验收工作、不证明物理静止、不丢弃脏数据，也不隐含 `--abandon`。
+它保留所选处置及原始 Publication/完成证据。未验证的本地提交和无法安全释放的资源
+仍有明确 owner 且可追溯。清理失败不回滚归档；迟到的运行时事件仍作为来源证据，
+不恢复 Task 或结算未知输入。
+
+### 清理前先读结果
+
+`yui task show <task> --json` 暴露 `data.archive.warnings`、
+`data.archive.retainedResources` 和 `data.archive.cleanupEvents`。
+`yui task context <task> --json` 保留原始记录与事件；
+`yui task remote-delivery <task> --json` 单独报告交付。警告包含历史清理尝试；
+保留引用描述当前所有权，不是第二套清理队列。
+
+归档结果中的 `archived=true` 证明已归档，不证明清理全部成功。即使 `cleanupFinished`
+也只代表前台清理已走完，不代表资源全部移除。重复归档只报告当前事实，不重放清理。
+检查后通过显式的精确 owner 资源操作进行安全清理；不隐含后台重试或更广泛的删除
+权限。两条归档路径都保留 Task 历史与恢复信息。已归档的 Task 不能重开。
+
+`yui task archive-preflight <task> (--integrated|--abandon) [--force] [--json]`
+一次读取归档条件、交付覆盖与各精确 owner 的清理检查。归档前后都可用，获授权的
+Task Leader reader 也可读取。这里的 `--force` 仅选择要检查的行为，不会归档、
+准备工作区、刷新 Git index、停止 Session、获取维护锁、抓取远端或保存清理计划。
+
+每项阻断/未知检查都有资源、原因码、预期/观察值、来源引用及既有检查/处置命令。
+无权访问的 Task 外路径会脱敏。报告区分 Candidate 工作区缺失、工作区身份/元数据/
+路径变化、冻结 commit 缺失、HEAD 变化、脏 worktree、Git 注册缺失或锁定、结果未集成、
+交付未覆盖、owner 未结算和执行未知。状态检查禁用可选 index 写入及 filesystem-monitor
+钩子；若已跟踪文件的属性选择了配置中的 clean/process filter（包括已初始化的 submodule），则返回
+`git-status-requires-filter` 未知诊断，不执行程序，也不绕过规范化猜测干净/脏状态。
+历史 Candidate 路径保持不可变。路径差异即使
+符合早期布局迁移的形状，也不单独证明安全迁址；没有确切映射时只报告差异并保留资源，
+不会改写历史或放宽 commit/owner 保护。
+
+预检是观察，不是删除凭据。清理会重新读取同一组检查，Git 删除时再验证身份和脏状态。
+Task-main clone 在子工作区清理前存在关联 Git 注册是正常现象，但移除 clone 前它们必须
+已释放。归档会保留失败 Integration 工作区中新出现的脏文件；独立的显式 Integration
+清理命令保留既有的可丢弃冲突现场合同。force 清理完成只表示这次前台尝试结束，不表示
+全部资源已释放；当前保留引用、精确物理运行时证据与历史诊断仍是不同事实。
 
 清理前用每个命令的 `--help` 查看它确切的权限和选项；阅读一份生命周期文档不授权
 一次外部写入。