@zq-silk/yui 0.15.7 → 0.15.9

package/docs/release-workflow.md

@@ -0,0 +1,305 @@
+<p align="right"><strong>English</strong> | <a href="./release-workflow.zh-CN.md">简体中文</a></p>
+
+# Authorized release operations
+
+A release workflow is an explicitly chosen, authorized sequence of
+external release effects — pull requests, CI confirmation, merges, version
+tags, npm publishes, fresh-install smoke tests, CLI updates, Controller
+replacements, Project migrations, and post-verification. It is a specialized
+external-effect facility, not Yui's Task planning or Agent execution model.
+The Agent selects a predeclared plan, and the facility drives that plan
+from durable state: every transition is persisted before the next external
+call, so a crash, timeout, or revoked grant never leaves the release guessing.
+
+Two task-level record families back it:
+
+- **CapabilityGrant** (`capability-grant-N`) — the authority. A named granter
+  scopes a grant to actions, parameter bounds, an expiry, a use count, and an
+  irreversibility ceiling.
+- **ReleaseWorkflow** (`release-workflow-N`) — the plan and its progress: an
+  exact source (repository + pinned commit, optionally an artifact), an
+  immutable ordered step plan, and one persisted record per step.
+
+The engine (`src/release/releaseWorkflowEngine.ts`) is a pure library; the
+`yui task workflow` and `yui task grant` commands drive it. Every external
+system sits behind `ReleaseWorkflowPorts`
+(`src/release/releaseWorkflowPorts.ts`), so the whole workflow is testable
+with deterministic fakes and no real GitHub, npm, git, Controller, or process
+side effect.
+
+## Authorization model
+
+Every (re)submission of a step passes `checkGrant(grant, request, now)`
+(`src/grant/capabilityGrant.ts`) **before** the external call. The step kind
+is the grant action: a grant lists the step kinds it authorizes, for example
+`--action npm-publish --action version-tag`. The decision is fail-closed —
+every denial carries a machine-readable reason and stops the run:
+
+| Reason | Meaning |
+| --- | --- |
+| `grant-missing` | No grant record is bound to the workflow (engine-level). |
+| `grant-revoked` | The grant was revoked by an operator. |
+| `grant-expired` | The wall clock passed the grant's `expiresAt`. |
+| `grant-uses-exhausted` | The grant's `maxUses` has been consumed. |
+| `grant-action-not-allowed` | The step kind is not in the grant's actions. |
+| `grant-parameter-missing` | A bounded parameter is absent from the step. |
+| `grant-parameter-value-not-allowed` | A bounded parameter has an out-of-bounds value. |
+| `grant-irreversibility-exceeds-ceiling` | The step is more irreversible than the grant's ceiling. |
+
+Additional rules:
+
+- **One use per authorized submission.** The engine records a grant use
+  between the successful decision and the external call, so a `maxUses` grant
+  fails closed on the attempt that would exceed it.
+- **Irreversible steps need a confirmed prefix.** A step marked
+  `irreversible` additionally requires every earlier step to be `succeeded`;
+  otherwise the step fails with `prerequisite-not-confirmed` and the run
+  stops. This is what keeps an `npm-publish` from running behind a failed PR.
+- **Denials are recorded.** When a pending step is denied, the engine starts
+  and fails the step with the denial in its log, so `workflow status` shows
+  exactly where authorization stopped.
+- **Rebinding.** A revoked, expired, or too-narrow grant does not dead-end
+  the workflow. Issue a new grant and resume with
+  `yui task workflow resume <task> <workflow> --grant <new-grant>`; the plan,
+  source, and all confirmed step evidence are immutable across the rebind.
+
+## Stable Task-final Review contract
+
+Compatible CLI package updates and Controller replacements do not change an
+active Task's final-review capability. Managed Sessions use the ordinary
+`yui` command, compatibility is checked by protocol and storage identity, and
+a replacement Leader presents the contract already established by durable Task
+evidence. No version-aware Operator action is required.
+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.
+
+## CLI and Controller release boundary
+
+The global `yui` command is the stable user and managed-Session interface. It
+does not follow `runtime/active-release.json` for ordinary commands: that
+pointer selects the Controller release, not the CLI package. This keeps CLI,
+Operator Session, and Controller replacement compatible without pinning every
+command to one immutable build.
+
+A source-checkout or otherwise unverified local CLI is not this published
+interface. When `YUI_HOME` already names an active release, such a CLI fails
+before opening storage and reports its build/source, the durable Home identity,
+and its invocation class. `make install-local` continues to default to the
+checkout's isolated `output/dev/home`; explicitly pointing that launcher at a
+release-owned Home is rejected.
+
+An explicit `yui release activate <release-id|build-id>` is the one exception.
+The global CLI verifies the installed target release and its matching smoke
+receipt, then delegates the unchanged activation arguments to that target's
+`dist/cli.js`. The target release therefore owns the complete handover protocol
+and timeout hierarchy. A no-target activation, help, `--json`, and every other
+command remain on the global CLI. Activation does not add another ordinary CLI
+routing path.
+
+## Step catalog
+
+The plan is a fixed, predeclared subset of operations. Each plan entry has an
+id (unique within the workflow), a kind, optional params, and an optional
+irreversibility level (`none` | `reversible` | `irreversible`).
+
+| Kind | External effect | Authoritative identity |
+| --- | --- | --- |
+| `pr-create-or-reuse` | Creates the release PR, or reuses an open one for the head. | `pull-request` number |
+| `ci-confirm` | Reads the CI conclusion for the source ref; succeeds only on `success`. | — |
+| `merge` | Merges the named PR (squash by default). | — |
+| `version-tag` | Creates and pushes the annotated version tag. | `git-tag` name |
+| `npm-publish` | Publishes the tarball to the registry. | `npm-package` version |
+| `fresh-install-smoke` | Installs and runs the published package from the registry. | — |
+| `cli-update` | Updates the Yui CLI/Controller home via the existing update orchestrator. | `controller-home` |
+| `controller-replace` | Stops and restarts the file-task Controller. | — |
+| `project-migrate` | Runs the Project migration through the existing project command. | — |
+| `post-verify` | Runs an arbitrary verification command. | — |
+
+Steps may reference earlier evidence: a param value of
+`$externalId:<step-id>` resolves to the referenced step's confirmed external
+id at run time, so a `merge` step can consume the PR number the `pr` step
+produced without the operator knowing it in advance. A reference to an
+unconfirmed step fails the run rather than guessing.
+
+## Recovery and resume semantics
+
+A run always starts from the **resume cursor**: the first plan step whose
+status is not terminal (`succeeded` or `skipped`). There is no "start over" —
+confirmed steps are never re-run.
+
+Because every state transition is persisted before the next external call, a
+process exit at any point is recoverable: re-invoke `run` (or `resume`) and
+the engine continues from the first unconfirmed step. `--max-steps <n>` bounds
+a single run; a run that exhausts its budget mid-workflow returns
+`budget-exhausted` and the next invocation continues.
+
+In-flight steps are resolved by **authoritative identity query**, never by
+blind re-submission:
+
+- A step left `running` or `unknown` is queried first by its recorded
+  `externalIdentity`.
+  - `exists` → the step reaches `succeeded` **without a second submission**
+    (`unknown` is confirmed, `running` is completed).
+  - `unknown` → the run stops with outcome `unknown`; the step is never
+    re-submitted while its fate is unknowable.
+  - `absent` → the effect never landed, so the step is re-attempted (a
+    `running` step records the recovery attempt).
+- A `running` step **without** an external identity crashed before recording a
+  submission result. An irreversible step is queried through the port anyway
+  (the adapter consults its durable idempotency store): `exists` confirms the
+  step without a second submission, `unknown` stops as `unconfirmed`, and only
+  an authoritative `absent` re-attempts the step exactly once. A reversible
+  step always falls through and re-attempts under the same idempotency key.
+- A timeout **without** an external identity marks the step as `unknown`
+  (unconfirmed) so it is never re-submitted blindly; on resume it fails closed
+  as `unconfirmed`.
+- A `failed` step is retried on the next run; its `attempts` counter and logs
+  grow per attempt.
+
+Run outcomes: `succeeded`, `failed`, `unknown`, `unauthorized`,
+`unconfirmed`, `budget-exhausted`. Each carries a machine-readable
+`stopReason` (for example `unknown:publish`, `unauthorized:grant-revoked`,
+`budget-exhausted:verify`) and the list of step ids attempted that run.
+
+## Idempotency key contract
+
+Each step's idempotency key is **predeclared at create time** and never
+changes:
+
+```text
+<taskId>/<workflowId>/<stepId>
+```
+
+The key is passed to every `executeStep` call for that step, including
+retries after a confirmed-absent timeout. The port contract requires
+`executeStep` to be idempotent under the same key: a retried attempt must not
+produce a second side effect. The engine side of the contract is stricter
+still — it never calls `executeStep` for a step it has marked `unknown`; it
+re-queries by the recorded identity instead. The fakes record every key, so
+the test suite proves at-most-once execution directly.
+
+## Operator guide
+
+Session authority is checked against current durable bindings. Telemetry is
+grouped by Role/AgentRun, and process owners use PID/start identity. Storage
+changes follow the [single explicit upgrade boundary](sqlite-control-plane-design.md);
+ordinary commands never rewrite the Home schema.
+
+Grant issue and revoke are irreversible-authority operations. They require
+the current registered global Operator conversation. Its native session ID
+must match the durable live session binding: Codex commands use `CODEX_THREAD_ID`
+when present, otherwise `YUI_NATIVE_SESSION_ID`; Claude uses `YUI_NATIVE_SESSION_ID`.
+Host generation and launch-time Agent labels are not caller identity. Resuming
+the same conversation through another entry point does not revoke its authority.
+An unregistered, replaced, or ended conversation has no such authority.
+A managed Task Agent cannot self-issue or
+self-revoke a grant, and clearing the child-process environment does not
+confer user authority. The recorded granter/revoker is bound to that
+Operator session (`operator:<agent-id>`); there is no `--granter`/`--by`
+label to spoof.
+
+```sh
+# 1. The Operator session issues the authority for the release chain.
+yui task grant issue task-15 \
+  --action pr-create-or-reuse --action npm-publish --action post-verify \
+  --irreversibility-ceiling irreversible
+
+# 2. Create the workflow against an exact source and a predeclared plan.
+#    An npm-publish step requires a content-addressed source artifact: the
+#    immutable workflow source can never gain one later, so a plan without
+#    --source-artifact is rejected at creation.
+yui task workflow create task-15 \
+  --grant capability-grant-1 \
+  --source-repo acme/widget --source-commit abc1234deadbeef0000000000000000000000000 \
+  --source-artifact widget-1.0.0.tgz@sha512-<base64-integrity> \
+  --step pr:pr-create-or-reuse \
+  --step publish:npm-publish --step-irreversibility publish=irreversible \
+  --step-param publish:tarball=./dist/widget-1.0.0.tgz \
+  --step verify:post-verify --step-param verify:command='yui --version'
+
+# 3. Run (or resume) and inspect.
+yui task workflow run    task-15 release-workflow-1
+yui task workflow resume task-15 release-workflow-1 [--grant capability-grant-2] [--max-steps 1]
+yui task workflow status task-15 release-workflow-1
+
+# 4. Revoke authority at any time; the next step stops unauthorized.
+yui task grant revoke task-15 capability-grant-1
+```
+
+`workflow status` renders each step's status, attempt count, and confirmed
+external id, so an operator can see exactly where a release stopped and why.
+
+## Real-resource boundary
+
+Real execution happens only through the `yui` CLI, which wires the real
+adapter (`createReleaseWorkflowPorts`). The adapter is a thin shell over
+existing atomic operations — `gh`, `npm`, `git`, the CLI update orchestrator,
+Controller stop/restart, and `project migrate` — and it runs only when a human
+granter has issued an explicit CapabilityGrant that passes `checkGrant` for
+each step. A local test request never substitutes for that authority.
+
+The tag-triggered `publish.yml` workflow is the only maintained release smoke.
+It reuses the exact commit that passed core CI and adds only artifact assembly,
+fresh installation, and provenance checks required to publish.
+
+That workflow authenticates through npm Trusted Publishing (OIDC), so the
+release identity lives in two places outside the tag: `repository`, `bugs`, and
+`homepage` are copied verbatim from the source `package.json` into the published
+manifest by `assemble-runtime-package.mjs`, and the package's npm Trusted
+Publisher entry names the GitHub owner, repository, workflow file, and
+environment. npm compares `repository.url` against the building repository
+case-sensitively before accepting provenance. Renaming or transferring the
+GitHub repository therefore has to update those URLs and the npm Trusted
+Publisher entry together with the rename; otherwise the next tag reaches
+`npm publish` and fails there, after the tag and the gated build already
+succeeded.
+
+## Adapter security hardening
+
+The real adapter (`createReleaseWorkflowPorts`) applies additional safeguards
+beyond the engine's grant checks:
+
+- **Tarball option injection.** An option-looking tarball path (one starting
+  with `-`) is rejected before any subprocess — both the `tar -xOf` manifest
+  inspection and `npm publish` — sees it, so a crafted path can never be
+  interpreted as a flag.
+- **Tarball TOCTOU.** After the frozen `source.artifact.integrity` is verified,
+  the verified bytes are snapshotted to a workflow-private, read-only temp
+  file. Both the `tar -xOf` manifest inspection and `npm publish` read the
+  snapshot, never the live tarball path, so a replacement of the original file
+  after verification cannot change what is published. The snapshot is removed
+  when the step completes.
+- **Pinned external commands.** The adapter resolves the external commands it
+  shells out to (`gh`, `git`, `npm`, `tar`, `sh`) to absolute paths at
+  construction time via `resolveExecutable`, walking the caller's `PATH`
+  once. Every subprocess invocation uses the resolved path, so a later `PATH`
+  change (or a manipulated working directory) cannot redirect a release effect
+  to a different binary. An unresolvable command returns a synthetic failure
+  (exit 127) without invoking any binary.
+- **Pinned cli-update activation target.** Before the irreversible update
+  effect, the adapter persists the exact activation target — the Home plus the
+  global npm prefix (`bin/yui`) — to a durable file under the Home
+  (`release/cli-update-identity/<idempotency-key>.json`). A hard-exit recovery
+  query (a step with no recorded identity) reads this file and invokes that
+  pinned target; if the file is absent (the process exited before the
+  pre-effect persistence), the query returns `unknown` rather than deriving
+  the target from the resume caller's `npm prefix --global` or `PATH`, so a
+  different installation in the resume environment cannot attest the step.
+- **Controller lifecycle verification.** A `cli-update` recovery query proves
+  the replacement Controller actually owns the target Home: it runs
+  `yui --json controller status` (with `YUI_HOME` pinned to the recorded Home)
+  and requires a `current` controller resource whose `yuiHome` resolves to
+  that Home, then `yui --json controller identity` and requires the
+  authenticated Controller identity to match the activated artifact: the
+  Node.js executable path, the exact Controller entrypoint derived from the
+  pinned global binary, and the package version. Binary health alone (doctor,
+  `--version`) never confirms the handoff, and any unprovable state returns
+  `unknown`. This applies to both the identity-bearing query and the
+  hard-exit query (a step with no recorded identity).
+- **npm integrity comparison.** An `npm-publish` recovery query does not stop
+  at the published version: it fetches `dist.integrity` via
+  `npm view <pkg>@<version> dist.integrity` and compares it byte-for-byte with
+  the frozen `source.artifact.integrity`. A match confirms the step; the same
+  version with different bytes is a conflict and returns `unknown` (never a
+  confirmation, never a re-publish); a missing version is `absent`.

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

@@ -0,0 +1,237 @@
+<p align="right"><a href="./release-workflow.md">English</a> | <strong>简体中文</strong></p>
+
+# 获授权的发布操作
+
+发布工作流是一段被显式选择、获授权的外部发布效果序列——pull request、CI 确认、
+合并、版本 tag、npm 发布、全新安装冒烟、CLI 更新、Controller 替换、Project 迁移和
+后置验证。它是一个专用的外部效果设施，而不是 Yui 的 Task 规划或 Agent 执行模型。
+Agent 选择一个预先声明的计划，设施从持久状态驱动该计划：每次转换都在下一次外部调用
+之前持久化，因此崩溃、超时或被撤销的 grant 都不会让发布陷入猜测。
+
+两个 Task 级记录族支撑它：
+
+- **CapabilityGrant**（`capability-grant-N`）——权威。一个具名的授权者把 grant
+  限定到若干动作、参数边界、一个过期时间、一个使用次数和一个不可逆上限。
+- **ReleaseWorkflow**（`release-workflow-N`）——计划及其进展：一个确切来源（仓库 +
+  钉住的 commit，可选一个 artifact）、一份不可变的有序步骤计划，以及每步一条持久记录。
+
+引擎（`src/release/releaseWorkflowEngine.ts`）是一个纯库；`yui task workflow` 和
+`yui task grant` 命令驱动它。每个外部系统都位于 `ReleaseWorkflowPorts`
+（`src/release/releaseWorkflowPorts.ts`）之后，因此整个工作流可以用确定性的 fake
+测试，不产生任何真实的 GitHub、npm、git、Controller 或进程副作用。
+
+## 授权模型
+
+每一次（再）提交一个步骤，都在外部调用**之前**通过 `checkGrant(grant, request, now)`
+（`src/grant/capabilityGrant.ts`）。步骤 kind 就是 grant 动作：一个 grant 列出它授权的
+步骤 kind，例如 `--action npm-publish --action version-tag`。该判定是 fail-closed
+的——每个拒绝都带一个机器可读原因并停止这次运行：
+
+| 原因 | 含义 |
+| --- | --- |
+| `grant-missing` | 没有 grant 记录绑定到该工作流（引擎级）。 |
+| `grant-revoked` | 该 grant 已被 operator 撤销。 |
+| `grant-expired` | 墙钟已过该 grant 的 `expiresAt`。 |
+| `grant-uses-exhausted` | 该 grant 的 `maxUses` 已被消耗。 |
+| `grant-action-not-allowed` | 步骤 kind 不在该 grant 的动作中。 |
+| `grant-parameter-missing` | 步骤缺少一个受约束参数。 |
+| `grant-parameter-value-not-allowed` | 一个受约束参数的取值越界。 |
+| `grant-irreversibility-exceeds-ceiling` | 该步骤比 grant 的上限更不可逆。 |
+
+附加规则：
+
+- **每次获授权提交消耗一次。** 引擎在成功判定与外部调用之间记录一次 grant 使用，
+  因此一个 `maxUses` grant 会在那次将要超额的尝试上 fail closed。
+- **不可逆步骤需要一个已确认的前缀。** 一个标记为 `irreversible` 的步骤额外要求此前
+  每个步骤都是 `succeeded`；否则该步骤以 `prerequisite-not-confirmed` 失败并停止运行。
+  这正是让 `npm-publish` 不会跟在一个失败的 PR 之后运行的机制。
+- **拒绝会被记录。** 当一个待处理步骤被拒绝时，引擎会启动并把该步骤失败，日志里带上
+  这次拒绝，因此 `workflow status` 能准确显示授权在哪里停下。
+- **重新绑定。** 一个被撤销、过期或过窄的 grant 不会让工作流走进死胡同。签发一个新
+  grant 并用 `yui task workflow resume <task> <workflow> --grant <new-grant>` 恢复；
+  跨越这次重新绑定，计划、来源和所有已确认的步骤证据都不可变。
+
+## 稳定的 Task-final Review 合同
+
+兼容的 CLI 包更新和 Controller 替换不改变一个活动 Task 的 final-review 能力。受管
+Session 使用普通的 `yui` 命令，兼容性由协议和存储身份检查，一个替换 Leader 呈现由
+持久 Task 证据已确立的合同。不需要任何版本感知的 Operator 动作。Candidate 和
+Task-final 的 ReviewRound 记录必须全部携带那唯一的合同。冲突的记录 fail closed；
+不存在重新绑定事件、恢复命令或第二套合同状态机。
+
+## CLI 与 Controller 发布边界
+
+全局 `yui` 命令是稳定的用户与受管 Session 接口。对普通命令，它不跟随
+`runtime/active-release.json`：那个指针选择的是 Controller 发布，而不是 CLI 包。这让
+CLI、Operator Session 和 Controller 替换保持兼容，而不必把每个命令钉在一个不可变构建上。
+
+一个源码 checkout 或以其他方式未经验证的本地 CLI 不是这个已发布接口。当 `YUI_HOME`
+已经命名了一个活动发布时，这样的 CLI 会在打开存储之前失败，并报告它的构建/来源、
+持久的 Home 身份以及它的调用类别。`make install-local` 仍默认使用 checkout 隔离的
+`output/dev/home`；把那个 launcher 显式指向一个发布拥有的 Home 会被拒绝。
+
+一个显式的 `yui release activate <release-id|build-id>` 是唯一的例外。全局 CLI 校验
+已安装的目标发布及其匹配的冒烟回执，然后把未改动的激活参数委派给那个目标的
+`dist/cli.js`。因此目标发布拥有完整的交接协议和超时层级。一次无目标的激活、help、
+`--json` 以及其他每个命令都留在全局 CLI 上。激活不新增另一条普通 CLI 路由路径。
+
+## 步骤目录
+
+计划是一个固定、预先声明的操作子集。每个计划条目有一个 id（工作流内唯一）、一个
+kind、可选 params，以及一个可选的不可逆级别（`none` | `reversible` | `irreversible`）。
+
+| Kind | 外部效果 | 权威身份 |
+| --- | --- | --- |
+| `pr-create-or-reuse` | 创建发布 PR，或复用一个针对该 head 的开放 PR。 | `pull-request` 号 |
+| `ci-confirm` | 读取该来源 ref 的 CI 结论；仅在 `success` 时成功。 | — |
+| `merge` | 合并具名 PR（默认 squash）。 | — |
+| `version-tag` | 创建并推送带注释的版本 tag。 | `git-tag` 名 |
+| `npm-publish` | 把 tarball 发布到 registry。 | `npm-package` 版本 |
+| `fresh-install-smoke` | 从 registry 安装并运行已发布的包。 | — |
+| `cli-update` | 通过既有更新编排器更新 Yui CLI/Controller home。 | `controller-home` |
+| `controller-replace` | 停止并重启 file-task Controller。 | — |
+| `project-migrate` | 通过既有的 project 命令运行 Project 迁移。 | — |
+| `post-verify` | 运行一个任意的验证命令。 | — |
+
+步骤可以引用更早的证据：一个 param 值为 `$externalId:<step-id>` 时，会在运行时解析为
+被引用步骤已确认的 external id，因此一个 `merge` 步骤可以消费 `pr` 步骤产生的 PR 号，
+而 operator 事先并不需要知道它。对一个未确认步骤的引用会让运行失败，而不是猜测。
+
+## 恢复与 resume 语义
+
+一次运行总是从 **resume 游标**开始：第一个状态非终态（`succeeded` 或 `skipped`）的
+计划步骤。没有“从头再来”——已确认的步骤绝不重跑。
+
+因为每次状态转换都在下一次外部调用之前持久化，所以任意一点的进程退出都是可恢复的：
+重新调用 `run`（或 `resume`），引擎就从第一个未确认步骤继续。`--max-steps <n>` 限定
+单次运行；一次在工作流中途耗尽预算的运行返回 `budget-exhausted`，下一次调用继续。
+
+在途步骤通过**权威身份查询**解决，绝不盲目重新提交：
+
+- 一个留在 `running` 或 `unknown` 的步骤，先按其记录的 `externalIdentity` 查询。
+  - `exists` → 该步骤到达 `succeeded`，且**没有第二次提交**（`unknown` 被确认，
+    `running` 被完成）。
+  - `unknown` → 运行以结果 `unknown` 停止；在其命运不可知期间，该步骤绝不被重新提交。
+  - `absent` → 效果从未落地，因此该步骤被重试（一个 `running` 步骤会记录这次恢复尝试）。
+- 一个**没有** external identity 的 `running` 步骤在记录提交结果之前就崩溃了。一个
+  不可逆步骤无论如何都通过端口查询（适配器咨询其持久幂等存储）:`exists` 不经第二次
+  提交确认该步骤，`unknown` 以 `unconfirmed` 停止，只有权威的 `absent` 才恰好重试该
+  步骤一次。一个可逆步骤总是落到重试，并沿用同一个幂等键。
+- 一次**没有** external identity 的超时把该步骤标记为 `unknown`（unconfirmed），因此
+  它绝不被盲目重新提交；在 resume 时它以 `unconfirmed` fail closed。
+- 一个 `failed` 步骤在下一次运行时被重试；它的 `attempts` 计数和日志按尝试增长。
+
+运行结果：`succeeded`、`failed`、`unknown`、`unauthorized`、`unconfirmed`、
+`budget-exhausted`。每个都带一个机器可读的 `stopReason`（例如 `unknown:publish`、
+`unauthorized:grant-revoked`、`budget-exhausted:verify`）以及该次运行尝试过的步骤 id
+列表。
+
+## 幂等键合同
+
+每个步骤的幂等键在**创建时预先声明**且永不改变：
+
+```text
+<taskId>/<workflowId>/<stepId>
+```
+
+该键被传给该步骤的每一次 `executeStep` 调用，包括在一次确认为 absent 的超时之后的
+重试。端口合同要求 `executeStep` 在同一键下是幂等的：一次重试尝试不得产生第二次
+副作用。引擎侧的合同更严格——它绝不为一个已标记 `unknown` 的步骤调用 `executeStep`,
+而是按记录的身份重新查询。fake 记录每一个键，因此测试套件直接证明至多一次执行。
+
+## Operator 指南
+
+Session 权威依据当前持久绑定检查。Telemetry 按 Role/AgentRun 分组，进程 owner 使用
+PID/start 身份。存储变更遵循[唯一的显式升级边界](sqlite-control-plane-design.zh-CN.md);
+普通命令绝不改写 Home schema。
+
+grant 的签发与撤销是不可逆权威操作。它们需要当前已登记的全局 Operator 对话。它的
+原生 session ID 必须与持久的活动 session 绑定匹配：Codex 命令在存在时使用
+`CODEX_THREAD_ID`，否则使用 `YUI_NATIVE_SESSION_ID`;Claude 使用 `YUI_NATIVE_SESSION_ID`。
+Host generation 和启动时的 Agent 标签不是调用者身份。通过另一个入口恢复同一段对话
+不撤销其权威。一个未登记、被替换或已结束的对话没有这种权威。一个受管的 Task Agent
+不能自签发或自撤销 grant，清空子进程环境也不赋予用户权威。被记录的授权者/撤销者
+绑定到那个 Operator session（`operator:<agent-id>`）；不存在可伪造的 `--granter`/`--by`
+标签。
+
+```sh
+# 1. Operator session 为发布链签发权威。
+yui task grant issue task-15 \
+  --action pr-create-or-reuse --action npm-publish --action post-verify \
+  --irreversibility-ceiling irreversible
+
+# 2. 针对确切来源和预先声明的计划创建工作流。
+#    npm-publish 步骤需要一个内容寻址的来源 artifact：不可变的工作流来源以后
+#    永远无法再获得它，因此没有 --source-artifact 的计划在创建时即被拒绝。
+yui task workflow create task-15 \
+  --grant capability-grant-1 \
+  --source-repo acme/widget --source-commit abc1234deadbeef0000000000000000000000000 \
+  --source-artifact widget-1.0.0.tgz@sha512-<base64-integrity> \
+  --step pr:pr-create-or-reuse \
+  --step publish:npm-publish --step-irreversibility publish=irreversible \
+  --step-param publish:tarball=./dist/widget-1.0.0.tgz \
+  --step verify:post-verify --step-param verify:command='yui --version'
+
+# 3. 运行（或 resume）并检查。
+yui task workflow run    task-15 release-workflow-1
+yui task workflow resume task-15 release-workflow-1 [--grant capability-grant-2] [--max-steps 1]
+yui task workflow status task-15 release-workflow-1
+
+# 4. 随时撤销权威；下一个步骤以 unauthorized 停止。
+yui task grant revoke task-15 capability-grant-1
+```
+
+`workflow status` 渲染每个步骤的状态、尝试次数和已确认的 external id，因此 operator
+能准确看到一次发布在哪里停下以及为什么。
+
+## 真实资源边界
+
+真实执行只通过 `yui` CLI 发生，它接上真实适配器（`createReleaseWorkflowPorts`）。该
+适配器是既有原子操作——`gh`、`npm`、`git`、CLI 更新编排器、Controller stop/restart 和
+`project migrate`——之上的一层薄壳，并且只在一个人类授权者签发了对每个步骤都通过
+`checkGrant` 的显式 CapabilityGrant 时才运行。一个本地测试请求绝不替代那份权威。
+
+由 tag 触发的 `publish.yml` 工作流是唯一维护的发布冒烟。它复用那个通过了 core CI 的
+确切 commit，只增加发布所需的产物装配、全新安装和 provenance 检查。
+
+该工作流通过 npm Trusted Publishing（OIDC）认证，因此发布身份存在于 tag 之外的两处：
+`repository`、`bugs` 和 `homepage` 由 `assemble-runtime-package.mjs` 从源 `package.json`
+逐字复制进已发布 manifest，而该包的 npm Trusted Publisher 条目点明 GitHub owner、
+仓库、工作流文件和环境。npm 在接受 provenance 之前会区分大小写地将 `repository.url`
+与正在构建的仓库比较。因此重命名或转移 GitHub 仓库时，必须连同重命名一起更新这些 URL
+和 npm Trusted Publisher 条目；否则下一个 tag 会走到 `npm publish` 并在那里失败——此时
+tag 和已过门的构建都已成功。
+
+## 适配器安全加固
+
+真实适配器（`createReleaseWorkflowPorts`）在引擎的 grant 检查之外再施加额外防护：
+
+- **Tarball 选项注入。** 一个看起来像选项的 tarball 路径（以 `-` 开头）在任何子进程
+  ——`tar -xOf` manifest 检视和 `npm publish`——看到它之前就被拒绝，因此一个精心构造的
+  路径永远不会被当作 flag 解释。
+- **Tarball TOCTOU。** 在校验冻结的 `source.artifact.integrity` 之后，被校验的字节被
+  快照到一个工作流私有、只读的临时文件。`tar -xOf` manifest 检视和 `npm publish` 都
+  读取该快照，而不是活的 tarball 路径，因此校验之后对原文件的替换不能改变所发布的内容。
+  步骤完成时移除该快照。
+- **钉住的外部命令。** 适配器在构造时通过 `resolveExecutable` 把它 shell 调用的外部
+  命令（`gh`、`git`、`npm`、`tar`、`sh`）解析为绝对路径，只走一次调用者的 `PATH`。每次
+  子进程调用都使用解析后的路径，因此之后的 `PATH` 变化（或被操纵的工作目录）不能把一次
+  发布效果重定向到另一个二进制。一个无法解析的命令返回一个合成失败（exit 127），不调用
+  任何二进制。
+- **钉住的 cli-update 激活目标。** 在不可逆的更新效果之前，适配器把确切的激活目标——
+  Home 加上全局 npm 前缀（`bin/yui`）——持久化到 Home 下的一个持久文件
+  （`release/cli-update-identity/<idempotency-key>.json`）。一次硬退出的恢复查询（一个
+  没有记录身份的步骤）读取这个文件并调用那个钉住的目标；如果该文件不存在（进程在预效果
+  持久化之前退出），查询返回 `unknown`，而不是从 resume 调用者的 `npm prefix --global`
+  或 `PATH` 推导目标，因此 resume 环境中的另一个安装不能替这个步骤背书。
+- **Controller 生命周期校验。** 一次 `cli-update` 恢复查询会证明替换后的 Controller
+  确实拥有目标 Home：它运行 `yui --json controller status`（`YUI_HOME` 钉在记录的 Home
+  上），并要求一个 `current` controller 资源，其 `yuiHome` 解析到那个 Home，然后运行
+  `yui --json controller identity`，并要求已认证的 Controller 身份与已激活的产物匹配：
+  Node.js 可执行路径、由钉住的全局二进制派生的确切 Controller 入口点，以及包版本。仅有
+  二进制健康（doctor、`--version`）绝不确认这次交接，任何不可证明的状态都返回 `unknown`。
+  这适用于带身份的查询和硬退出查询（一个没有记录身份的步骤）两者。
+- **npm integrity 比较。** 一次 `npm-publish` 恢复查询不止步于已发布版本：它通过
+  `npm view <pkg>@<version> dist.integrity` 取 `dist.integrity`，并与冻结的
+  `source.artifact.integrity` 逐字节比较。匹配则确认该步骤；同一版本但字节不同是一个
+  冲突，返回 `unknown`（绝不确认，绝不重新发布）；一个缺失的版本是 `absent`。

package/docs/roles-and-configuration.md

@@ -0,0 +1,115 @@
+<p align="right"><strong>English</strong> | <a href="./roles-and-configuration.zh-CN.md">简体中文</a></p>
+
+# Roles, Profiles and execution configuration
+
+## Responsibilities
+
+Agent selects an execution component, connection plan and launch environment.
+Role selects an active Agent binding and portable behavior. Each binding retains
+independent runtime options. A Role can keep multiple bindings without creating
+parallel writers or sharing one binding's credentials/configuration with another.
+
+Task Roles are Task-local; global Roles provide configured defaults and global
+conversations. Role identity/configuration is not a writable runtime status.
+Session and Provider observations describe actual activity.
+
+An explicit Task-final Review uses an existing Task-local Reviewer Role without
+requiring a same-named global Role. A global Role is a creation template only
+when the requested Task Role does not exist. Availability, producer separation
+and the frozen review candidate still apply.
+
+## Profiles
+
+An Agent Profile combines portable behavior—instructions, Skills and access
+intent—with runtime intent. Runtime either follows the current Global Worker
+binding or explicitly selects an Agent with optional model and effort.
+`config profile reset` supplies `worker`, `explorer`, `implementer` and `reviewer`.
+
+Creating a Task Role from a Profile freezes its resolved behavior and binding.
+Later Profile or Global Worker edits do not rewrite existing Task Roles.
+Reapplying a Profile is an explicit configuration change. The selected Agent
+must match the target binding; explicit Role options override the corresponding
+template fields. A Profile is not a Session, workspace owner or resource grant.
+
+Native children inherit their parent Agent and authority. A Profile can guide
+their behavior; model/effort overrides require actual native tool support.
+They do not acquire Yui Roles, independent Assignments or broader scope.
+
+## Desired, effective and observed
+
+Desired settings are next-launch intent. An AgentRun and Session capture the
+effective launch: Agent/component, protocol, model, effort, permission strategy,
+workspace/environment, Role context and planning/delivery authority.
+
+Live run-configuration inspection separately reports what the Agent actually
+states. Unsupported and unknown are explicit; an accepted setter without a
+reported current value is not an observed match. Configuration reads do not
+modify the Agent to make the observation agree with desired settings.
+
+Worker binding changes preserve an active Assignment's Agent and effective
+snapshot; subsequent explicit dispatch uses the current selection. Leader
+replacement revokes the previous management entry without rewriting Worker
+Assignments. Changing desired configuration does not hot-mutate the native
+Session. An explicit `task role session new` request handles old runtime
+cleanup before selecting a fresh Session; it does not require manually settling
+Run status first. A useful Session may be reused, but it is never the only
+holder of Task context.
+
+## Permissions and Project context
+
+Provider permission strategy, Profile access intent and Project write scope are
+different contracts. Provider bypass does not grant writes to another Project.
+Managed workspace owner, exact Assignment and resource grants enforce Yui
+operations; broad native permissions are not an OS sandbox.
+
+Yui supplies its generic Role Skills and Context pointers. Project Skills remain
+ordinary Project files discovered natively by the Agent. Project Knowledge is
+maintained under `YUI_HOME`; copying repository material into a prompt does not
+make it authoritative Knowledge.
+
+## Native authentication
+
+Account configuration outlives a Session. Yui preserves `HOME` and the selected
+`CLAUDE_CONFIG_DIR`; new/resumed Sessions do not copy, clear, or fabricate native
+login, key-approval, or onboarding records.
+
+For Claude Code, standard API-key, base-URL, bearer/OAuth, model-alias and native
+provider-selection environment variables are forwarded only to Claude. Values
+remain in the Controller's replaceable runtime environment and the child process,
+not in Task/Role records. Unsetting a source and refreshing the Controller
+environment removes it for subsequent launches. Other custom credential variables
+still use explicit Agent environment bindings or native user settings; Yui does
+not inherit the whole shell environment or infer cloud credentials.
+
+Claude itself loads native settings and chooses between API keys, existing
+helpers, login credentials, profiles and cloud authentication according to its
+effective configuration. Yui does not inject `apiKeyHelper`, copy credential
+files, or override the native authentication priority. Explicit `--settings`
+paths and settings-source selections are passed through unchanged.
+
+Fresh native configuration can still require Claude's initialization, key,
+workspace and security confirmations, including access to initialization
+services. Isolating `YUI_HOME` or replacing a Session does not require a fresh
+native account directory. Managed Task execution uses Claude's non-interactive
+stream-json path with the same native configuration ownership.
+
+## Commands
+
+```sh
+yui config agent capabilities <agent-id>
+yui config role show <global-role>
+yui config profile show <profile>
+yui task role add <task> <role> --profile <profile>
+yui task role show <task> <role>
+yui task role update <task> <role> --environment <preparation-id>
+yui task role update <task> <role> --managed-environment
+yui task role session inspect <task> <role>
+yui task role session new <task> <role> --reason "<why a fresh Session is useful>"
+```
+
+On Role creation, explicit Agent settings require `--agent`. On update, omitted
+`--agent` targets the active binding; a named binding is updated without being
+activated. `task role bind` changes selection. A live Session requires the
+command's explicit confirmation before desired settings are changed.
+
+For native configuration and implementation limits, see [Provider runtime](provider-runtime.md).