@zaalipro/dsh-workflows 0.1.0-rc.3

package/docs/testing.zh.md

@@ -0,0 +1,125 @@
+# 测试与发布验收
+
+[English](testing.md) | 中文
+
+本参考把自动化证明与最终人工发布决策分开。绿色 unit suite 绝不能替代下列 official-prerequisite、assembled、packed-consumer、browser、race、provider 或 manual boundary。
+
+## 自动化 gate
+
+使用冻结的 `pnpm@11.7.0` install，并从 package checkout 运行命令。每个命令在首次失败时非零退出；其后的文字是 CI 或 release log 必须保留的 success marker。
+
+### Build、type、lint、coverage 与 docs
+
+```sh
+pnpm run build && printf 'package build PASS\n'
+pnpm run typecheck && printf 'package typecheck PASS\n'
+pnpm run lint && printf 'package lint PASS\n'
+pnpm run test:coverage && printf 'package coverage PASS\n'
+node scripts/verify-docs.mjs
+```
+
+Documentation command 准确输出 `documentation verification passed`。它检查完整 English/Chinese pair 及记录的 blob hash、local file 与 heading fragment、单个 trailing LF、当前 compatibility prose，以及必需的 installation、architecture、testing、user 和 Agent Note coverage。
+
+### Keyless assembled snapshot
+
+```sh
+pnpm exec vitest run tests/keyless-snapshot.spec.ts --reporter=dot && printf 'RD5 keyless snapshot PASS\n'
+pnpm exec vitest run tests/dashboard-snapshot.client.spec.tsx --reporter=dot && printf 'RD6 dashboard snapshots PASS\n'
+```
+
+`tests/keyless-snapshot.spec.ts` 是 source-resolved fixture：它把官方 `tool-workflow/*` event 送进 `ConversationNodeAssembler`，证明 append/prepend/full-replay 一致，把 Interrupted Chat node 映射为 cancelled，并检查 completion-notice footer。它不启动官方 assembled snapshot harness，也不比较 reviewed Session/stdout JSONL；`examples/workflows-keyless/` 输入仍是后续 assembled gate。Dashboard snapshot 固定 accessible empty、live、terminal、interrupted、disclosure 和 member-outcome semantic，而不是 CSS hash。
+
+### Package policy 与 exact packed consumer
+
+```sh
+pnpm exec vitest run tests/verify-package.spec.ts --reporter=dot && printf 'RD3 package policy PASS\n'
+pnpm exec vitest run tests/packed-consumer.spec.ts --reporter=dot && printf 'RD8 packed consumer PASS\n'
+```
+
+Standalone packed-consumer test 只执行一次 `pnpm pack --json`，记录 SHA-256，并把完全相同的绝对 tarball 交给 `scripts/verify-package.mjs --tarball`。发布时由 `scripts/check-release.mjs` 独占 pack ownership，并把同一 artifact 交给 `scripts/packed-consumer.mjs`；generic unit command 排除会自行 pack 的 spec。缺少 skill、client bundle、evaluator 或 required peer asset 会在任何 consumer Session 开始前失败。Runner 以 scripts disabled 安装该 artifact，再安装 pinned consumer-only TypeScript/Node type 以及精确的预构建官方 CLI，import 所有 JavaScript 与 strict NodeNext export，并通过 lazy-CJS seam 加载 `lib/client.js`。所有声明的 Host、Client、Cordis 与 React peer 仍保留精确 compatibility declaration，但都标记为 optional：隔离的 `autoInstallPeers: true` probe 不得 materialize 其中任何一个，而 standalone import/type probe 会显式提供 peer。真实 Web 与 headless profile cycle 必须保留官方 `autoInstallPeers: false`，不得包含 profile-local peer package，所有 peer 都必须通过 healed official fallback 解析，并且 agent-loop 与 agent-presets 解析到的 `dsh-scope` realpath 必须完全相同。随后每个 profile 执行两次 bounded activation/teardown sentinel boot（第二次证明 lease 已释放），再 remove 并验证 manifest restoration。Source-tree runtime fallback、用 `--help` 充当 activation evidence、split Host graph，或发布期间第二次 pack 都是失败。
+
+### 自动化 Chromium
+
+```sh
+pnpm exec vitest run tests/browser-smoke.spec.ts --reporter=dot && printf 'RD10 browser automation PASS\n'
+```
+
+`tests/browser-smoke.spec.ts` 当前只覆盖 `scripts/browser-smoke.mjs` helper boundary：absolute argument、loopback readiness JSON、stdin teardown，以及与 caller workspace 隔离。它并不用 Chromium 驱动 slash discovery、disclosure 或 1,199/767/320 px layout。该 product journey 属于下面的最终 Ego Lite checklist，而不是 helper 已经覆盖的替代。
+
+### Lifecycle、storage 与 Client stress
+
+```sh
+pnpm exec vitest run tests/race-stress.spec.ts --reporter=dot && printf 'RD11 host race stress PASS\n'
+pnpm exec vitest run tests/storage-stress.spec.ts --reporter=dot && printf 'RD12 storage stress PASS\n'
+pnpm exec vitest run tests/client-race-stress.client.spec.ts --reporter=dot && printf 'RD13 client race stress PASS\n'
+```
+
+这些 deterministic repeated suite 覆盖 aggregate cancellation、pending durable admission、pause/stop/teardown、worker death、completion cohort、advisory-lease contention、link/inode substitution、interrupted publication、stale gate/control/page response、reconnect generation、invalidation overflow 与 cross-Agent authorization。它们断言不存在 orphan worker、child、scratch operation、timer、watcher、controller、request、cursor、selection 或 unhandled rejection。Donor aggregate-cancellation scenario 必须单独以及在 aggregate suite 中重复通过；一次成功 rerun 绝不能免除失败。
+
+### Opt-in real provider
+
+```sh
+pnpm exec vitest run tests/real-provider.spec.ts --reporter=dot && printf 'RD14 real provider gate PASS\n'
+```
+
+存在 `DEEPSEEK_API_KEY` 时，该文件准确启动两个名为 `alpha` 与 `beta` 的 logical child，分别验证 `alpha.txt` 中独立的 `alpha` byte 和 `beta.txt` 中独立的 `beta` byte，验证最终 result `{"alpha":"alpha","beta":"beta"}`，并在 `finally` 中 dispose 每个 child、worker、Agent、Host、lease 和 temporary directory。它只通过官方 provider configuration 读取 `DEEPSEEK_BASE_URL`。任何 value、credential 或 model transcript 都不会进入 log 或 artifact。
+
+没有 key 时，只有该文件注册一个 skipped test，reason 准确为 `DEEPSEEK_API_KEY is not set`。其他 package、platform、workflow 或 storage lane 都不能 self-skip。
+
+### 精确 official Host checkout
+
+Packed consumer 与 CI checkout 官方 DeepSeek Harness `0.1.1-rc.2` commit `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`。Package build 与 test 针对 `0.1.1-rc.2` development dependency 编译；不使用 Harness source patch 或 fork checkout。Package-owned evaluator build、strict NodeNext consumer、add/boot/remove profile cycle 与 removal 后的 stock boot 都是 blocking release evidence。
+
+### 最终自动化 aggregate
+
+```sh
+pnpm run check:release
+```
+
+成功时准确以 `release checks passed` 结束。Orchestrator 按顺序运行 clean/frozen-install verification、build、typecheck、lint、owned-source aggregate coverage、snapshot、documentation、package policy、一次 immutable pack 与 packed consumer（`official-host-probe` 加真实 Web/headless add/boot/remove）、browser helper boundary、三个 stress suite 和 opt-in provider file。它不会 publish、启动 Ego Lite 或录制 GIF。Packed profile cycle 针对官方 `0.1.1-rc.2` 是 blocking gate；Chromium product journey 仍是最终 Ego Lite acceptance。
+
+## Coverage policy
+
+`pnpm run test:coverage` 对 owned package integration source 强制执行真实的 aggregate floor：**80% statement、80% branch、80% function 与 80% line**。它显式只 instrument `src/**/*.{ts,tsx}` 并排除 type-only declaration，因此未被 import 的 owned source 仍计入，而 generated `lib/` 与 `scripts/` 下的 release helper 不会意外进入 denominator。不再声明逐文件 100%；8 月 23 日 baseline 为 85.35% statement/line、80.69% branch 与 84.98% function。该命令排除 packed-consumer、browser-smoke、snapshot、stress 和 real-provider lane。已保存的 `coverage-all` report 并不是 generated `lib/` 加 dependency 的 100%（最近一次约为 57%）；它不能替代 owned-source aggregate gate。Test 覆盖 deterministic clock 与 barrier、每个 error/cancellation branch、effect disposal、HMR registration、authorization 和 external world state，而不依赖 self-reported success。
+
+唯一不 instrument 的 artifact 是 generated 或 browser-delivery product，而不是 handwritten Host behavior 的例外：
+
+| Exclusion | 为何不作为 owned runtime source instrument | 必需证据 |
+|---|---|---|
+| `vendor/workflow-engine/*.ts` 与 emitted `lib/compat-engine/*` | 带 attribution 的 MIT compatibility evaluator，使用独立 process/worker protocol gate | `tests/compat-engine.spec.ts`、supervisor replay/gate/budget/scratch suite、packed artifact verification 与 live profile smoke |
+| `lib/typert.host.*` 与 `lib/typert.remote-client.*` | 从 decorated Host source 生成 | `tests/build-artifacts.spec.ts`、Remote API test、packed import 与 browser mount smoke |
+| `lib/client.js`、emitted Client declaration/map 与 Lightning CSS output | Generated bundle product | Client component/controller spec、dashboard semantic snapshot、packed serving 与 `tests/browser-smoke.spec.ts` |
+| `src/client/css-modules.d.ts` | 无 executable statement 的 type-only generated-facing declaration | Client TSC 加 build suite source assertion |
+| CSS module visual branch | Style 不进入 JavaScript statement coverage | source token assertion、jsdom semantic snapshot，以及 GUI behavior 改变时最终 Ego Lite real-flow GIF。CI 中的 Automated Chromium 只门禁 `scripts/browser-smoke.mjs`；layout、light/dark 与 reduced-motion 仍是人工 Ego Lite。 |
+
+Handwritten Client TypeScript 仍由其 Client test project 覆盖；generated output 不建立并行 coverage denominator。增加其他 exclusion 必须提供相应 real-browser evidence 和显式 testing-policy change。
+
+## CI platform matrix
+
+Blocking Ubuntu 24.04 job 运行 Node `22.19.0`、`24` 和 `26`；每个 job 使用 frozen lockfile，并覆盖 build、typecheck、lint、docs、package policy 以及分配的 unit/coverage/snapshot gate。Node 24 还拥有 macOS 14、Windows Server 2022、Chromium helper、race-stress 和 release-pack/packed-consumer job。Packed lane checkout 官方 `0.1.1-rc.2` commit `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`；不应用 Harness patch，只 pack 一次并保留一个 digest 和 artifact path，而且要求 Web 与 headless 的 live add/boot/remove。
+
+Windows 运行每个支持的 definition、manifest、scratch、retention、recovery 与 subprocess case。它明确断言 junction/hard-link behavior，以及可工作的 native advisory locking 或已记录的 `WORKFLOW_STORAGE_UNSUPPORTED` result；它绝不静默 skip workflow、把 job 标记为 `continue-on-error`，或在没有断言准确 branch 时把 platform limitation 当作成功。
+
+CI 只能在失败后上传 reviewed snapshot、browser、stress 和 pack diagnostic。它绝不上传 DSH home、credential、secret-lane model transcript 或 unrestricted scratch store。Action 固定到完整 commit SHA，permission 默认 read-only，job 有 timeout，而且只有 real-provider file 可因 key 缺失而 skip。
+
+## Real-provider secret 与 cleanup policy
+
+CI 只在可用时把 `DEEPSEEK_API_KEY` 传给隔离的 provider job。Test 不打印 key 或 base URL，也不把它们复制到 child prompt、session log、screenshot、archive 或 failure diagnostic。Provider error 可以命名 display handle 和 provider failure，绝不能包含 internal run UUID 或 credential material。
+
+所有 live resource 都创建在 isolated workspace 与 DSH home 内。`finally` 会 stop 或 settle run、dispose child catalog entry、worker handle、Agent 和 Host、释放 permanent-anchor lease，并且即使 provider failure 或 timeout 也会移除 temporary directory。
+
+## Final manual Web acceptance
+
+这是 release checklist，不是 coding task、CI step 或 automated Chromium 的替代。只有全部自动化 gate 通过后，才使用安装了完全相同 tested tarball 的真实官方 `0.1.1-rc.2` Web profile 和 real server/model flow 执行。
+
+- [ ] 启动 tarball-installed real server，确认 package activation 没有 source checkout fallback。
+- [ ] 使用 **Ego Lite** 完成 smoke journey。全程复用它的 task space；绝不 wipe 或 reset 任何 user session、cookie、browser storage 或 daily-browser state。
+- [ ] 确认 `/create-workflow`、`/workflow`、`/workflows` 和 saved alias 出现；启动两个 run，观察 immediate acknowledgement、display-name numbering、live phase/member/progress update，以及仍可用的 composer。
+- [ ] 打开并关闭 run disclosure 和 `Inspect · N members`；检查真实 text/Markdown 与 JSON outcome、log、result 和 scratch artifact。验证 user-visible 或 accessible text 中没有 internal UUID。
+- [ ] 运行 resumable gate、Pause、Resume、Stop 和符合条件的 Save；确认 stale-revision 与 budget-limited error 保持可见且 actionable。
+- [ ] 检查 focus restoration、keyboard control、screen-reader label、light/dark/reduced-motion behavior 和没有水平 overflow 的 narrow mobile drill-down。
+- [ ] 确认每个符合条件的 run 只有一个 completion notice，而且仅打开 dashboard 不产生重复 `workflows · Completed` row。
+- [ ] 任何 product-visible GUI change 都要从这个 **real PR server/model flow** 录制并保留 GIF，展示 launch、live update、member outcome inspection、control 和 narrow layout。Mocked 或 source-only GIF 不是 release evidence。
+- [ ] 验证完成后，**只关闭 Ego Lite task space**。不要 wipe session、cookie、storage 或不相关 tab/space。
+
+在 release evidence 中记录 tested tarball SHA-256、official Host build identity、platform、automated aggregate log、manual result 和 GIF location。即使 automated suite 为绿色，任何失败的 manual item 也会阻止 release。

package/docs/user-guide.i18n.yaml

@@ -0,0 +1,4 @@
+# Bilingual-pair consistency record: git blob hash of each side at the last
+# confirmed-consistent state. Both languages carry equal authority.
+user-guide.md: b5d6f01071390d0fef3f61aa336db187a2353af4
+user-guide.zh.md: bac2d837c6859f1d0359f73e923f58c9ef28c764

package/docs/user-guide.md

@@ -0,0 +1,351 @@
+# User guide
+
+English | [中文](user-guide.zh.md)
+
+This tutorial takes a Web or headless user from installation to one saved JavaScript definition, one validation smoke, a background run, detailed inspection, controls, and recovery. A **saved definition** is authoring input on disk; a **live or retained run** is an immutable admitted execution record. `/workflows` lists saved definitions (Start) and live or retained runs.
+
+## 1. Install on a compatible Harness
+
+Use official DeepSeek Harness `0.1.1-rc.2` with plugin `0.1.0-rc.3`. Ensure `pnpm` is on the service user's `PATH`; `0.1.0-rc.8` and unverified later Harness releases are unsupported.
+
+Install a pinned release tag, or the exact tested tarball from a durable absolute path:
+
+```sh
+dsh plugin --profile web add github:zaalipro/dsh-workflows#v0.1.0-rc.3
+dsh plugin --profile headless add /absolute/path/zaalipro-dsh-workflows-0.1.0-rc.3.tgz
+```
+
+After npm publication, `dsh plugin --profile <profile> add @zaalipro/dsh-workflows@0.1.0-rc.3` is equivalent.
+
+Restart the profile. Web gains the dashboard and durable Chat renderer in addition to Host behavior; headless gains registry, supervisor, commands, questions, recorder, and model tool without loading browser code. Removal is covered in the [package README](../README.md#installation).
+
+## 2. Create a project definition
+
+In a Session whose cwd belongs to the intended project, enter:
+
+```text
+/create-workflow review workspace changes, verify every finding, and write a report
+```
+
+The command replies exactly:
+
+```text
+Opened the workflow authoring skill.
+```
+
+The command steers that same leading `/create-workflow` user message. The packaged skill is user-invocable, so the compatible Host injects its trusted instructions into that next model step deterministically instead of relying on the model to choose the skill from its catalog.
+
+The packaged skill asks for intent, inputs, fan-out, evidence, failure tolerance, final artifact, maximum agents, a lowercase kebab name, and project or user scope. Choose **project** to save `review-changes.workflow.json` under the nearest Git root's `.dsh/workflows` directory. If no Git root exists, the Session cwd is the project root. Choose **user** to save under `$DSH_HOME/workflows`.
+
+Definitions resolve with first-wins precedence: configured bundled root, project root, then user root. A higher-precedence same-name definition can keep a newly saved lower-precedence file shadowed. Files must be flat, regular, UTF-8, at most the configured 1 MiB default, and named with a valid lowercase kebab stem.
+
+The saved envelope has exactly `meta` and `script`; metadata remains JSON data and the body remains plain JavaScript:
+
+```json
+{
+  "meta": {
+    "name": "review-changes",
+    "description": "Review workspace changes and verify every finding",
+    "whenToUse": "Before requesting merge",
+    "phases": [
+      { "title": "Review", "detail": "Collect bounded evidence" },
+      { "title": "Verify", "detail": "Challenge every retained finding" },
+      { "title": "Report", "detail": "Publish the final artifact" }
+    ]
+  },
+  "script": "phase(\"Review\");\n// JavaScript body omitted here; see the complete pattern below."
+}
+```
+
+Phase titles in `phase(title)` and `agent(..., { phase })` must match metadata titles exactly. Metadata declares presentation; it is never evaluated as host code.
+
+## 3. Understand the validation smoke
+
+The authoring skill asks the model-facing workflow tool to validate and save the proposed inline source with representative args. `save_scope` defaults to `project`; choose `user` for `$DSH_HOME/workflows`. A user-scope save does not require a Session cwd.
+
+```json
+{
+  "script": "<plain JavaScript workflow body>",
+  "meta": {
+    "name": "review-changes",
+    "description": "Review workspace changes and verify every finding"
+  },
+  "args": { "targets": ["src", "tests"] },
+  "validate_only": true,
+  "save_scope": "project"
+}
+```
+
+A successful result has status `validated`, creates no child, run id, directory, display ordinal, dashboard row, completion notice, or durable workflow event, and states:
+
+```text
+Validated one args-selected path with canned agent results; other branches, live tools, and live schema responses were not covered.
+```
+
+The engine parses the **entire** script first, then executes only the path selected by those args with canned schema-shaped agent outputs and an in-memory scratch capability. A gate ends the smoke successfully as `would pause: <message>`. Treat this as syntax, hook-contract, and one-path evidence—not proof of all branches or real provider behavior. Fix any filename/line diagnostic and rerun validation before saving.
+
+## 4. Launch a background run
+
+The canonical command accepts one saved name and an optional JSON object:
+
+```text
+/workflow review-changes {"targets":["src","tests"]}
+```
+
+It returns without waiting for agents:
+
+```text
+Started workflow "review-changes" in the background. Open /workflows to watch it.
+```
+
+When no ordinary slash command collides, the saved definition also has a named alias:
+
+```text
+/review-changes {"targets":["src","tests"]}
+```
+
+If an ordinary command owns `/review-changes`, that command keeps it and the workflow receives the first free repeated-prefix alias, such as `/workflow-review-changes`; canonical `/workflow review-changes` always works. The first run is `review-changes`, then `review-changes-2`, `review-changes-3`, and so on. These display names are the only handles used by human commands and titles.
+
+Bare `/workflow` opens a definition picker in Web and returns this usage in headless:
+
+```text
+Launch or control a workflow.
+
+Usage:
+/workflow <name> [<json-args>]
+/workflow pause <display-name>
+/workflow resume <display-name>
+/workflow stop <display-name>
+/workflow save <display-name>
+
+Examples:
+/workflow review-changes {"target":"origin/main...HEAD"}
+/workflow pause review-changes
+/workflow resume review-changes
+/workflow stop review-changes-2
+/workflow save review-changes
+```
+
+Arguments must be one JSON object. Arrays and scalars fail before launch; malformed trailing text is not repaired or forwarded to the model.
+
+## 5. Open the run dashboard
+
+In Web, submit exact bare:
+
+```text
+/workflows
+```
+
+This browser-only slash action opens the dialog labelled `Workflows`; it invokes neither Host command execution nor the model and creates no command Chat row. `/workflows` with arguments or attachments does not open the overlay; it is refused locally with its draft and attachments intact. Dashboard chrome and Chat labels follow the host locale: the package registers English and Chinese dictionaries, English is the fallback, and the close control uses the same `Close workflows` accessible name as the visible label. Inspector headings (`Pending`, `JSON outcome`, and the rest of criterion 11.4) and the exact criterion 11.4/11.11 error strings stay English.
+
+The dashboard lists saved definitions with a Start control, then the run navigator (display name, status, current phase, agents spent/total, running and settled member counts, a bounded terminal summary, and retained-run loaded/total disclosure). Active runs sort oldest-first and history sorts by newest settlement. `Load more` fetches the next authorized bounded page; only terminal rows are eligible for deterministic oldest-first retention eviction, never active rows or display ordinal history.
+
+At widths of at least 1,200 px, navigator, execution detail, and inspector are independently scrollable panes. Below 1,200 px, navigation and one detail pane remain. Below 768 px, use explicit **Runs -> Execution -> Inspector** drill-down; the same flow works without horizontal page overflow at 320 px.
+
+## 6. Inspect execution and members
+
+Select a run, then open its run disclosure to see declared/current phases, status, progress, controls, logs, terminal result or error, artifacts, and retention disclosure. Open `Inspect · N members` to reveal the member roster. Running and abnormal groups remain open; a completed clean phase can be collapsed without losing detail.
+
+Member lifecycle states are **queued/pending**, **running**, **completed**, **failed**, and **cancelled**. An ordinary child failure is a settled failed member whose script-visible result is JSON `null`; infrastructure failure instead fails the logical run. Select a member to load one distinct outcome presentation:
+
+- `Pending`—the member has no settled outcome yet.
+- `JSON outcome`—the complete retained JSON value, including an actual JSON `null`.
+- `Text outcome`—complete Markdown or plain text.
+- `Value outcome`—a retained JSON primitive other than `null`.
+- `Truncated outcome`—a deterministic preview plus retained and total UTF-8 byte counts.
+- `No outcome produced`—the member settled without an output value.
+- `Outcome evicted`—retention deliberately removed the full detail while preserving that fact.
+
+`Child transcript unavailable` is separate from the retained outcome: the direct one-shot child address may have disappeared while the outcome remains inspectable. `Unable to load member outcome` with `Retry` is a request failure; prior successful pages and detail remain visible. Child navigation refreshes the current direct-child catalog before opening a transcript and refuses stale or foreign addresses.
+
+Logs load in stable index order. Result absence, JSON `null`, truncation, eviction, and request failure render as different facts. Scratch artifacts list safe single-component names and sizes; opening one fetches bounded UTF-8 chunks, and `Load more` continues from a byte cursor adjusted to a complete code-point boundary. A changed, invalid UTF-8, or unsafe artifact fails inline without clearing previously loaded run detail.
+
+## 7. Respond to gates
+
+`await_user(kind, message)` and `pause(kind, message)` both park a run and surface one `Workflow · <display-name>` question with `Resume workflow`, but their replay semantics differ:
+
+- `await_user` acknowledges and resumes the same live engine attempt. The satisfied gate commits, so a later journal replay skips it.
+- `pause` is an uncommitted condition. Acknowledgement starts replay, and the same condition asks again if it remains true.
+
+Dismissing, withdrawing, aborting, or answering an obsolete question leaves the run parked. The package resumes only an exact live Session/Agent/logical-run/execution/gate/generation tuple; a late answer cannot resume a newer attempt or another run.
+
+## 8. Pause, resume, stop, and save
+
+Use dashboard buttons, guarded P/R/X/S shortcuts, or display-name commands:
+
+```text
+/workflow pause review-changes
+/workflow resume review-changes
+/workflow stop review-changes-2
+/workflow save review-changes
+```
+
+Successful command replies are exact:
+
+```text
+Paused workflow "review-changes". Open /workflows to resume or stop it.
+Resumed workflow "review-changes". Open /workflows to watch it.
+Stopped workflow "review-changes-2".
+Saved workflow "review-changes" to <path>.
+```
+
+Pause stops new work, cancels and drains the current attempt, then publishes `paused` only after a quiescent checkpoint is retained. Resume uses the immutable admitted script and args, not later edits to `script.js`; matching committed hooks replay for zero additional spend. Stop cancels admitted children and scratch operations, pairs their endings, discards replay authority, and publishes terminal `cancelled` after cleanup.
+
+Save is available only for a non-built-in, unnumbered, non-Interrupted run with a safe live editable projection. A built-in or numbered handle requires an edited copy with a new unique `meta.name`; a lower-precedence saved file may remain shadowed. Save targets project scope by default or the explicit supported user scope.
+
+Every dashboard control carries the currently visible revision, disables duplicate submission, and merges the authoritative returned row. If another update wins first, no control side effect occurs and the dashboard says:
+
+```text
+workflow run changed; refresh it before applying a control
+```
+
+Every other non-domain control failure shows `Unable to update workflow. Retry.` with a labelled `Retry`, while abort and stale-selection failures remain quiet.
+
+## 9. Handle budgets, completion, and process exit
+
+`budget()` returns `{ total, spent, reserved: 0, remaining }`. The default total is 128 and an admitted run may use an absolute cap from 1 through 1,024. Spend is cumulative across same-process attempts; journal replay and schema-correction retries spend zero. Declarative `parallel()` panels preflight all unreplayed jobs atomically, while arbitrary thunks admit each concrete `agent()` call because their future count is unknowable.
+
+When the cap stops a run, the dashboard shows **Budget limited** and offers Stop but no human Resume. Resume through the model tool only, using this explicitly internal reference shape:
+
+```json
+{
+  "resume_from_run_id": "<internal-run-id>",
+  "agent_budget": 256
+}
+```
+
+The absolute `agent_budget` must be greater than the old total and no greater than 1,024. Human commands, dashboard Resume, or an absent/equal/lower/excessive cap return `workflow "<display-name>" requires a higher agent_budget to resume` without starting another attempt. Internal run ids belong only in this model-tool exchange, never in screenshots, command text, titles, notices, or accessibility labels.
+
+An eligible terminal run attempts one bounded owner completion notice, preferring `scratch/report.md` to the inline result and ending `Open /workflows to inspect the run.` It is at-most-once delivery: a crash can omit a claimed notice, never duplicate it.
+
+After Host process death, startup recovery changes any retained active run to **Interrupted**, changes running members to cancelled, shows `Process exited before workflow settlement.`, and exposes inspection only. No journal, checkpoint, Agent, script/args authority, gate, or child handle crosses processes; an Interrupted run cannot Resume or Save. Launch a new run from the saved definition after checking whether any uncommitted external effect already happened.
+
+## 10. Author replay-safe JavaScript
+
+The worker exposes `args`; `agent`; thunk or declarative `parallel`; `pipeline`; `phase`; `log`; `complete`; `budget`; `pause`; `await_user`; `read_scratch_file`; and `write_scratch_file`. `agent(prompt, opts)` accepts exactly `label`, `phase`, `schema`, `provider`, and `model`. Stock workers have no native `complete`, so this package injects it.
+
+Structured schemas support `type`, `properties`, `required`, `additionalProperties`, `items`, `minItems`, `maxItems`, `enum`, `const`, and `oneOf`. `minItems` and `maxItems` are inclusive array-length bounds. Each bound must be a non-negative safe integer (negative zero, fractions, and non-numbers are invalid), may appear only on a `type: 'array'` node, must satisfy `minItems <= maxItems`, and is forbidden beside `oneOf`. The package validates the authored schema before any child starts, removes only these two forward-compatible keywords from the copy sent to stock RC2, and post-validates the returned structured value against the authored bounds. Unsupported options such as `fork_context`, unsupported schemas, invalid calls, and infrastructure failures are fatal; ordinary child failures or schema-invalid child values return `null`.
+
+This complete body guards nullable outputs, keeps verification fail-closed, sorts and filters deterministically, bounds a log preview explicitly, synchronizes phase titles, and publishes a report:
+
+```js
+const rawTargets = Array.isArray(args.targets) ? args.targets : []
+const targets = [...new Set(rawTargets)]
+  .filter(target => typeof target === 'string' && target.length > 0)
+  .sort((left, right) => left.localeCompare(right))
+
+if (targets.length === 0) {
+  complete({ ok: false, reason: 'no valid targets', findings: [] })
+}
+
+phase('Review')
+const reviews = await parallel(targets.map(target => ({
+  label: `review-${target}`,
+  phase: 'Review',
+  prompt: `Review ${target}. Inspect the workspace; return at most 20 evidence-backed findings.`,
+  schema: {
+    type: 'object',
+    properties: {
+      findings: {
+        type: 'array',
+        maxItems: 20,
+        items: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            summary: { type: 'string' },
+            evidence: { type: 'string' },
+          },
+          required: ['path', 'summary', 'evidence'],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ['findings'],
+    additionalProperties: false,
+  },
+})))
+
+if (reviews.some(review => review === null)) {
+  complete({ ok: false, reason: 'a reviewer failed', findings: [] })
+}
+
+const findings = reviews
+  .flatMap(review => review.findings)
+  .filter(finding => targets.some(target => finding.path === target || finding.path.startsWith(`${target}/`)))
+  .sort((left, right) => left.path.localeCompare(right.path) || left.summary.localeCompare(right.summary))
+
+const preview = JSON.stringify(findings)
+log(preview.length <= 2_000 ? preview : `${preview.slice(0, 2_000)}… [truncated]`)
+
+phase('Verify')
+const verification = await agent(
+  `Challenge every finding against the workspace. Reject unsupported claims.\n${JSON.stringify(findings)}`,
+  {
+    label: 'verifier',
+    phase: 'Verify',
+    schema: {
+      type: 'object',
+      properties: {
+        verified: { type: 'boolean' },
+        reason: { type: 'string' },
+      },
+      required: ['verified', 'reason'],
+      additionalProperties: false,
+    },
+  },
+)
+
+if (verification === null || verification.verified !== true) {
+  complete({ ok: false, reason: verification?.reason ?? 'verification failed', findings: [] })
+}
+
+phase('Report')
+const report = [
+  '# Verified review',
+  '',
+  ...findings.map(finding => `- **${finding.path}** — ${finding.summary}\n  - Evidence: ${finding.evidence}`),
+  '',
+].join('\n')
+await write_scratch_file('report.md', report)
+complete({ ok: true, findings, report: 'report.md' })
+```
+
+`complete(value)` accepts the first lossless JSON value and makes every later hook ineffective even if script code catches its internal sentinel. `return value` also settles the run. Scratch names are one component matching `^[A-Za-z0-9][A-Za-z0-9._-]*$`; defaults allow 4,096 operations, 64 pending, 64 files, 1 MiB per file, and 8 MiB total. `phase`/`log` events are each bounded to 64 KiB UTF-8.
+
+Replay-capable runs remove `Date`, `Math.random`, `Atomics`, `SharedArrayBuffer`, `WeakRef`, and `FinalizationRegistry`. Deterministic Math functions remain. Every effectful agent prompt must be safely repeatable because an effect whose result was not committed can run again. A script has no `workflow()` hook: nested workflows are unsupported; express orchestration with agents, `parallel`, and `pipeline` inside one run.
+
+## 11. Keyboard, mobile, and accessibility
+
+Opening `/workflows` moves focus into a labelled modal card over the conversation (not a full-page takeover). The chrome around the card is dimmed and inert; click that chrome, Close, or Escape to dismiss. Tab and Shift+Tab stay inside the card, escaped focus is recovered, and the invoking composer is restored on close when it still exists. Status always uses text in addition to color, progress and updates use semantic status/live regions, and member rows are real controls with visible `:focus-visible` treatment.
+
+P/R/X/S activate Pause/Resume/Stop/Save only when the dialog owns focus, no modifier or key repeat is present, the target is not editable, and the selected run currently allows that action. Hidden or unavailable actions never fire. Narrow-screen controls are at least 44 px in both dimensions, long labels and results wrap, and reduced-motion preference removes nonessential transitions.
+
+## 12. Troubleshooting
+
+### Incompatible Harness
+
+Symptom: activation reports an unsupported Host face or version. Install official `0.1.1-rc.2` with plugin `0.1.0-rc.3`; do not widen the peer range or assume a later Harness version is compatible.
+
+### Storage is already owned
+
+Symptom: `workflow storage root is already owned by another live process`. Stop the other cooperating Harness process and retry. Never delete or age `.workflow-storage.lock`; the kernel releases its advisory lease when the owner exits. `safe workflow storage is unavailable on <platform>` means the required native lease is unsupported, not that an unlocked fallback is safe.
+
+### Registry is disabled or a definition is missing
+
+`workflow registry is disabled` means listing is inert and Save is intentionally unavailable. `no saved workflow named "<name>"` means no winning definition exists in the current Session cwd's bundled/project/user view. Check the flat filename, root, scope, watcher diagnostic, and precedence; `/workflows` cannot answer definition questions because it lists runs.
+
+### Malformed definition or arguments
+
+A definition must be valid UTF-8 JSON with exactly `{ meta, script }`, known metadata/phase fields, a string script, and a filename stem equal to `meta.name`. Discovery names the offending path and fails the complete observation. Command parse errors are exact:
+
+```text
+trailing args for "review-changes" must be one JSON object — {bad
+trailing args for "review-changes" must be a JSON object (wrap arrays/scalars in a field)
+```
+
+Fix the source; the package never guesses, evaluates metadata, or silently omits the file.
+
+### Run, control, or transcript is unavailable
+
+`workflow "<display-name>" was not found in this Session` deliberately reveals no cross-Session data. `workflow "<display-name>" was interrupted by process exit and cannot resume` requires a new launch. A stale control uses the revision message shown above. `Child transcript unavailable` means the current direct one-shot child catalog no longer authorizes navigation; inspect the retained member outcome instead. A request-level error keeps loaded detail and offers `Retry`.