@zaalipro/dsh-workflows 0.1.0-rc.3

package/docs/architecture.md

@@ -0,0 +1,177 @@
+# Package architecture
+
+English | [中文](architecture.zh.md)
+
+This reference describes the installed architecture of `@zaalipro/dsh-workflows`: one Host/Client bundle for official DeepSeek Harness `0.1.1-rc.2`, with a package-owned MIT compatibility evaluator. The [user guide](user-guide.md) owns operating procedures, the [testing reference](testing.md) owns release evidence, and the [architecture decision](../.agents/notes/implemented/architecture/2026-08-20-installable-workflows-package.md) owns rationale and rejected alternatives.
+
+## Scope and invariants
+
+The package owns definition discovery, logical-run supervision, retained storage, completion delivery, commands, Agent-scoped model-tool replacement, authorized Remote reads, the Web dashboard, and the private JavaScript compatibility evaluator. Official `0.1.1-rc.2` owns the Host, Agent, Session, provider, and Client services. A Headless install evaluates no browser module. A Web install adds the Client aggregate without changing Host execution authority.
+
+Current state: plugin `0.1.0-rc.3` is verified against official `0.1.1-rc.2`. The plugin adapts the public Agent-scoped tool/prompt, filesystem, command, Remote, and provider faces and does not modify the stock `ctx.workflowEngine`.
+
+Four invariants organize every component:
+
+1. A start is durable before it is visible, and a deferred private evaluator attempt has an owner before it can execute.
+2. A same-process resume uses only the quiescent engine checkpoint; observe-only events never become replay authority.
+3. Protected run data moves through Agent-authorized, bounded Remote pages; broadcast events carry invalidation only.
+4. Teardown closes admission and drains owned work to a fixed point before releasing the storage lease.
+
+## Package topology
+
+### Web composition
+
+```mermaid
+flowchart LR
+  subgraph H[Official Harness 0.1.1-rc.2]
+    Loader[Profile loader]
+    Engine[Stock workflow service]
+    Agent[Exact Agent context]
+    Session[Session log]
+    Gateway[Typert Gateway and ApiProxy]
+    Slots[Client slots and shell overlay]
+  end
+  subgraph Package[One installed package]
+    Host[Host aggregate]
+    Registry[Definition registry]
+    Supervisor[Logical-run supervisor]
+    Store[Version-2 store]
+    Recorder[Durable recorder]
+    Remote[Generated Remote services]
+    Client[Client aggregate]
+    Controller[Revisioned controller]
+    Dashboard[Dashboard and inspector]
+    Chat[Durable Chat renderer]
+  end
+  Loader --> Host
+  Host --> Registry
+  Host --> Supervisor
+  Supervisor --> Engine
+  Supervisor --> Store
+  Agent --> Host
+  Supervisor --> Recorder --> Session
+  Registry --> Remote
+  Supervisor --> Remote --> Gateway --> Controller
+  Loader --> Client --> Controller
+  Client --> Dashboard --> Slots
+  Client --> Chat --> Slots
+```
+
+The package's bundle patch mounts exactly one Host aggregate, advertises `lib/client.js`, and disables the stock workflow Chat renderer only where the package renderer consumes the same official durable vocabulary. It does not edit an official profile file.
+
+### Headless composition
+
+```mermaid
+flowchart LR
+  Loader[Official 0.1.1-rc.2 profile loader] --> Host[Package Host aggregate]
+  Host --> Registry[Definition registry]
+  Host --> Supervisor[Logical-run supervisor]
+  Host --> Commands[Commands and tool shadow]
+  Supervisor --> Engine[Package compatibility evaluator]
+  Supervisor --> Store[Version-2 retained store]
+  Supervisor --> Recorder[Durable Session recorder]
+  Host --> Remote[Generated Host Remote services]
+  Browser[Client aggregate]:::absent
+  classDef absent stroke-dasharray: 5 5,opacity:0.45
+```
+
+The headless bundle has no import path to `./client`; commands, saved aliases, the model tool, gates, supervision, persistence, and durable Session recording remain available.
+
+## Component and event ownership
+
+### Host components
+
+- **Aggregate and configuration** validate official `0.1.1-rc.2` faces before filesystem access, resolve every Schemastery default, load assets relative to `import.meta.url`, and mount children under effect ownership.
+- **Definition registry (`ctx.workflows`)** observes bundled, project, and user roots; re-reads authoritative bytes; publishes only coalesced `workflows/change` hints; and owns safe save publication.
+- **Run store and native lease** own manifests, immutable detail sidecars, scripts, scratch files, retention, recovery, and one process-lifetime advisory lock.
+- **Supervisor (`ctx.workflowSupervisor`)** owns exact Agent/Session authorization, logical identities, attempts, status transitions, budgets, checkpoints, gates, controls, and lifecycle events.
+- **Completion notifier** owns the `none -> claimed -> delivered|abandoned` outbox and bounded direct Session-surface append cohorts. It never wakes the Agent or writes either inbox lane.
+- **Run recorder (`ctx.workflowRunRecorder`)** projects explicitly attributed top-level runs into the official Session vocabulary.
+- **Question bridge** maps an exact fenced `workflows/gate-request` to `ctx.userQuestions` and acknowledges only the current Agent/run/execution/gate tuple.
+- **Commands and trusted skill** own `/workflow`, `/create-workflow`, dynamic aliases, and the protected packaged `create-workflow` definition. The Client input-trigger source exclusively owns bare `/workflows` and its overlay.
+- **Tool adapter** temporarily replaces the official `workflow` tool and `tool:workflow` prompt section only in the exact Agent context where both official identities match.
+- **Remote services** expose definition lists and paged run detail, members, logs, result, artifacts, chunks, and revision-checked controls.
+
+The supervisor emits package-local `workflows/run-start`, `workflows/member-start`, `workflows/member-end`, `workflows/run-end`, `workflows/run-change`, and `workflows/gate-request`. These events are process lifecycle and invalidation signals, not durable replay authority. The recorder writes only `tool-workflow/run-start`, `tool-workflow/agent-start`, `tool-workflow/agent-end`, and `tool-workflow/run-end`; the package invents no durable phase or log event.
+
+### Client components
+
+- **Generated Remote mount** installs `lib/typert.remote-client.js` before any Remote consumer and unmounts it after reads and controllers abort.
+- **WorkflowRunsController** keeps one lazy revisioned source per observed Session, handles paging and reconnect generations, and never recreates removed state from a late response.
+- **Dashboard navigator** opens as a client-owned centered overlay modal (conversation remains visible behind dimmed chrome) and owns wide, two-pane, and mobile drill-down navigation.
+- **Member inspector** distinguishes pending, JSON (including `null`), text, primitive, truncated, not-produced, evicted, unavailable-transcript, and request-error states.
+- **Durable Chat renderer** folds only the four official Session events and never observes package-private run heads.
+
+Browser HMR disposes controllers, actions, overlays, generated Remote mounts, and CSS ownership before mounting the new Client generation. A Host HMR cycle follows the full teardown sequence; it never carries a live attempt into a replacement plugin generation.
+
+## Public subpaths and build faces
+
+The public export map is closed: `.`, `./registry`, `./supervisor`, `./run-recorder`, `./user-questions`, `./commands`, `./tool`, `./client`, `./types`, `./invariant`, `./typert`, `./remote`, `./cordis.patch.yml`, `./skills/create-workflow/SKILL.md`, and `./package.json`. No `./src/*` path is public.
+
+The package root owns three compiler faces: solution `tsconfig.json`, Host `tsconfig.host.json`, and Client `tsconfig.client.json`. Build order is **Host TSC -> Typert -> Client TSC -> classic lazy CJS**. A temporary copied mini-workspace provides one staging-root Host aggregate and one copied-package staging `tsconfig.json`; it has no nested Host/Client aggregate files. Focused `WorkspaceTypertGenerator.generate()` returns artifacts, and the build writes exactly `lib/typert.host.js`, `lib/typert.host.d.ts`, `lib/typert.remote-client.js`, and `lib/typert.remote-client.d.ts`, plus a map only when returned.
+
+The final `lib/client.js` must call `window.__ModuleLoader__.load({ id: "@zaalipro/dsh-workflows", factory: (require) => ... })` with a non-empty factory. Optional-chaining `?.load` and `factory: () => ({})` placeholders fail the build and package verifier. The bundle keeps baseline Client dependencies external, inlines package Remote and `clsx` code, and lets Lightning CSS own module names and lifecycle. Skill, patch, and Client asset paths derive from `import.meta.url`, never the process cwd. The private evaluator is emitted from `vendor/workflow-engine` as `lib/compat-engine/index.js` and `worker.cjs`; it is instantiated only for the supervisor and never replaces stock `ctx.workflowEngine`. Published and Git installs ship those prebuilt artifacts; `dsh plugin add` must not run a build.
+
+## Lifecycle authority
+
+### Boot and startup recovery
+
+Activation first verifies the supported official `0.1.1-rc.2` service faces. Storage then validates or creates only the owner-only runs root and permanent lock anchor, opens the anchor without following links, validates its stable identity, and acquires a nonblocking `fs-native-extensions` lifetime lease. Only the lease holder creates or validates the four store directories and performs one complete, bounded recovery before Session admission.
+
+Recovery validates every manifest and referenced sidecar before publishing any row. Persisted active rows become terminal `interrupted`, running member heads become `cancelled`, and orphaned notice claims become `abandoned`. Recovery keeps inspection facts and display ordinals but reconstructs no execution authority.
+
+### Durable-before-visible launch
+
+Start validates ownership, source, args, budget, and capacity before reserving a display ordinal or path. It stages `script.js`, `scratch/`, and `details/`, publishes the single-component run directory, and commits the initial version-2 manifest row. That manifest transaction is durable admission. The supervisor then installs private starting authority, attaches all observers and a deferred evaluator attempt, publishes the in-memory row and package lifecycle, releases execution once, and returns `started` without awaiting settlement.
+
+A caller abort before durable admission rolls back without a run directory or ordinal. After admission, the supervisor owns the detached run. A later attachment or execution failure terminalizes retained history instead of deleting it.
+
+### Pause, resume, and gates
+
+Pause commits `pausing`, closes new engine work, cancels the attempt, awaits its result, awaits idempotent disposal and child/scratch drainage, then reads `checkpoint()` synchronously. The supervisor commits and publishes `paused` only after that quiescent checkpoint exists.
+
+Ordinary Resume starts a new attempt over the immutable admitted script and args plus the retained in-memory checkpoint. An `await_user` acknowledgement continues the exact live attempt and commits the satisfied gate; a `pause` acknowledgement disposes the parked attempt and replays, so an unchanged pause condition emits again. Every answer is fenced by exact Agent identity, Session, logical run, engine execution, gate id, and generation. A budget-limited run accepts only model resume with a strictly higher absolute cap up to 1,024.
+
+### Stop and completion notice
+
+Stop closes admission, commits `stopping`, cancels the attempt and every admitted child/scratch operation, awaits paired member endings and disposal, discards resume authority, then atomically commits terminal `cancelled` and its notice claim. A clean or failed settlement follows the same dispose-before-terminal discipline.
+
+The terminal transaction changes `completionNotice` from `none` to `claimed` before the head becomes visible. One bounded append attempt finalizes that claim as `delivered` or `abandoned`; neither state retries. Cohorts carry at most 20 notices and 262,144 UTF-8 bytes. They append a plugin-sourced `user/message` directly to the owner Session with `surfaceOp: "append"`, making it durable and visible without opening a completion-driven model turn.
+
+### Remote reconnect and HMR
+
+`workflows/run-change` carries only `{ kind: 'invalidate', sessionId, revision }` or `{ kind: 'invalidate-all' }`. ApiProxy keeps keyed-latest hints for at most 256 Session keys and collapses overflow to the global form. On connection loss the Client aborts reads and marks existing sources reconnecting. After `connection/reset`, it fetches a new Agent-authorized epoch baseline before accepting later invalidations. Page, selection, Session, and connection generations suppress late responses.
+
+### Fixed-point teardown
+
+Host teardown closes global start admission, aborts and awaits pre-admission starts, stops and disposes published attempts, drains child/scratch operations, commits terminal rows, completes recorder prefixes, withdraws questions, and delivers or abandons notices. It repeats until completion-driven work cannot add another owner. Only then do the registry and storage close; the native lease unlock and descriptor close are last. This sequence leaves no worker, child, timer, watcher, request, or lock owner behind.
+
+## Manifest version 2 and secure storage
+
+The default root is `$DSH_HOME/workflow-runs` with permanent `.workflow-storage.lock`, Session manifests at `sessions/<sha256(sessionId)>/manifest.json`, and one safe 32-lowercase-hex directory per run under `runs/`. Each run directory owns `script.js`, `scratch/`, and immutable `details/<detail-id>.json` snapshots. `staging/` and `quarantine/` are separate root children.
+
+The at-most-8-MiB manifest is a Session head/index: ownership, display ordinal high-water marks, bounded run heads, revisions, one-component directory ids, sidecar references, and notice state. It never carries absolute paths, full outputs, args, journals, gates, or Agent references. One fully fsynced detail snapshot holds bounded members, logs, result, and artifact indexes; each run has at most 32 MiB of referenced detail. Terminal retention keeps at most 256 rows per Session, and total committed storage is at most 512 MiB. Oldest eligible terminal rows evict deterministically; active and claimed-notice rows never evict, and display ordinal history remains.
+
+Every run-storage directory walk uses the plugin-owned, fail-closed local descriptor implementation; the official filesystem service remains authoritative for definition discovery. A `script_path` read prefers a Host `readBytesNoFollow` capability. Published stock RC2 lacks that method, so only for its verified local filesystem shape the plugin authorizes and normalizes through the public Host `lstat`/`resolve`/`processPath` methods, then performs its own bounded `O_NOFOLLOW` descriptor read; unknown and remote providers fail closed. Root and components must have the current owner, restrictive `0700`/`0600` modes, expected type, one link for regular files, no symlink or junction, and stable device/inode identity. Cleanup never recurses after identity changes. The permanent kernel lock has no PID, heartbeat, stale age, retry, takeover, or deletion protocol. It coordinates cooperating same-user processes, not a malicious same-UID actor that ignores the lease.
+
+## Replay and script containment
+
+The journal addresses committed hooks with positive-safe-integer tuples in numeric lexicographic order and fingerprints each effective operation with lowercase SHA-256. Replay validates id, kind, and fingerprint before any new effect. Cumulative `agentSpend` and member sequence continue across attempts; replay and schema-correction calls cost no additional logical agent. An uncommitted effect may run again, so the system does not claim exactly-once external effects.
+
+Replay-capable runs remove `Date`, `Math.random`, `Atomics`, `SharedArrayBuffer`, `WeakRef`, and `FinalizationRegistry` while preserving deterministic Math functions. `node:vm` shapes that API and keeps synchronous script work off the Host event loop; it is not a security sandbox for hostile code. Scripts retain the same trust premise as existing model shell access.
+
+## Bounded Remote and browser presentation
+
+Every direct Remote method receives an explicit resolved Agent first and a required `AbortSignal` last; none combines that root with `@RemoteScope`. The exact Agent and its Session authorize every run, member, artifact, cursor, and control before protected data is read. List limits default to 50 and cap at 200. Only heads are eager; detail, members, outcomes, logs, result, artifacts, and UTF-8-safe artifact chunks load after selection.
+
+The dashboard has three panes at 1,200 px and wider, two-pane navigation below 1,200 px, and explicit runs-to-execution-to-inspector drill-down below 768 px, including 320 px. It traps and restores focus, uses real selection controls, preserves prior successful pages on errors, exposes labelled Retry actions, supports Escape and guarded P/R/X/S shortcuts, respects reduced motion, and keeps narrow actions at least 44 px.
+
+## Compatibility provenance
+
+Official `0.1.1-rc.2` integration uses Agent-scoped `tools.register` and `systemPrompt.section` only when the stock workflow contribution is identified; custom same-name contributions remain untouched. The package owns deferred execution, replay journal, checkpoints, gates, budget accounting, and scratch in its private compatibility evaluator.
+
+Official `0.1.1-rc.2` is the only verified installed Host for plugin `0.1.0-rc.3`; `0.1.0-rc.8` is unsupported and later Hosts require re-verification. The compatibility evaluator is package-owned MIT source derived narrowly from the maintained workflow behavior, not a replacement for the process-global stock workflow service.
+
+## Capacity bounds
+
+Defaults and hard ceilings keep every path bounded: 128 agents per run by default and 1,024 maximum; deployment live concurrency; 8 MiB Host protocol frames; 64 MiB journals; 1 MiB prompts and definition/projection files; 64 KiB events; 8 MiB manifests; 32 MiB detail per run; 512 MiB committed store; 4,096 startup entries; 64 active runs per Session and 1,024 globally; 200 rows per Remote page; and 256 pending Session invalidation keys. Scratch allows at most 4,096 operations, 64 pending operations, 64 files, 1 MiB per file, and 8 MiB total unless configuration lowers a limit.

package/docs/architecture.zh.md

@@ -0,0 +1,177 @@
+# 包架构
+
+[English](architecture.md) | 中文
+
+本参考说明 `@zaalipro/dsh-workflows` 的已安装架构：它是面向官方 DeepSeek Harness `0.1.1-rc.2` 的单一 Host/Client bundle，并包含 private compatibility evaluator（package-owned MIT source）。[用户指南](user-guide.zh.md)负责操作步骤，[测试参考](testing.zh.md)负责发布证据，[架构决策](../.agents/notes/implemented/architecture/2026-08-20-installable-workflows-package.zh.md)负责理由和被拒绝的替代方案。
+
+## 范围与不变量
+
+本包拥有 definition discovery、logical-run supervision、retained storage、completion delivery、命令、Agent-scoped model-tool replacement、授权 Remote read、Web dashboard 与 private JavaScript compatibility evaluator。官方 `0.1.1-rc.2` 拥有 Host、Agent、Session、provider 与 Client service。Headless 安装不求值任何浏览器模块；Web 安装增加 Client aggregate，但不改变 Host execution authority。
+
+当前状态：plugin `0.1.0-rc.3` 已针对官方 `0.1.1-rc.2` 验证。Plugin 适配 public Agent-scoped tool/prompt、filesystem、command、Remote 与 provider face，不修改 stock `ctx.workflowEngine`。
+
+四条不变量组织所有组件：
+
+1. start 在可见前持久化，而且 deferred private evaluator attempt 在执行前已经有 owner。
+2. same-process resume 只使用 quiescent engine checkpoint；observe-only event 绝不成为 replay authority。
+3. 受保护的 run data 通过 Agent-authorized、bounded Remote page 传输；broadcast event 只携带 invalidation。
+4. teardown 先关闭 admission 并把 owned work 排空到 fixed point，最后才释放 storage lease。
+
+## 包拓扑
+
+### Web composition
+
+```mermaid
+flowchart LR
+  subgraph H[Official Harness 0.1.1-rc.2]
+    Loader[Profile loader]
+    Engine[Stock workflow service]
+    Agent[Exact Agent context]
+    Session[Session log]
+    Gateway[Typert Gateway and ApiProxy]
+    Slots[Client slots and shell overlay]
+  end
+  subgraph Package[One installed package]
+    Host[Host aggregate]
+    Registry[Definition registry]
+    Supervisor[Logical-run supervisor]
+    Store[Version-2 store]
+    Recorder[Durable recorder]
+    Remote[Generated Remote services]
+    Client[Client aggregate]
+    Controller[Revisioned controller]
+    Dashboard[Dashboard and inspector]
+    Chat[Durable Chat renderer]
+  end
+  Loader --> Host
+  Host --> Registry
+  Host --> Supervisor
+  Supervisor --> Engine
+  Supervisor --> Store
+  Agent --> Host
+  Supervisor --> Recorder --> Session
+  Registry --> Remote
+  Supervisor --> Remote --> Gateway --> Controller
+  Loader --> Client --> Controller
+  Client --> Dashboard --> Slots
+  Client --> Chat --> Slots
+```
+
+本包的 bundle patch 只挂载一个 Host aggregate，公布 `lib/client.js`，并且只在本包 renderer 消费相同官方 durable vocabulary 的位置禁用 stock workflow Chat renderer。它不会修改官方 profile 文件。
+
+### Headless composition
+
+```mermaid
+flowchart LR
+  Loader[Official 0.1.1-rc.2 profile loader] --> Host[Package Host aggregate]
+  Host --> Registry[Definition registry]
+  Host --> Supervisor[Logical-run supervisor]
+  Host --> Commands[Commands and tool shadow]
+  Supervisor --> Engine[Package compatibility evaluator]
+  Supervisor --> Store[Version-2 retained store]
+  Supervisor --> Recorder[Durable Session recorder]
+  Host --> Remote[Generated Host Remote services]
+  Browser[Client aggregate]:::absent
+  classDef absent stroke-dasharray: 5 5,opacity:0.45
+```
+
+headless bundle 没有通往 `./client` 的 import path；命令、保存的 alias、model tool、gate、supervision、persistence 和 durable Session recording 仍然可用。
+
+## 组件与事件归属
+
+### Host 组件
+
+- **Aggregate 与配置**在访问 filesystem 前验证官方 `0.1.1-rc.2` 的 package version 与 service face，解析每个 Schemastery default，通过 `import.meta.url` 相对路径加载资产，并在 effect ownership 下挂载 child。
+- **Definition registry (`ctx.workflows`)** 观察 bundled、project 和 user root；重新读取 authoritative byte；只发布合并后的 `workflows/change` hint；并拥有 safe save publication。
+- **Run store 与 native lease** 拥有 manifest、immutable detail sidecar、script、scratch file、retention、recovery 和一个 process-lifetime advisory lock。
+- **Supervisor (`ctx.workflowSupervisor`)** 拥有 exact Agent/Session authorization、logical identity、attempt、status transition、budget、checkpoint、gate、control 和 lifecycle event。
+- **Completion notifier** 拥有 `none -> claimed -> delivered|abandoned` outbox 和 bounded direct Session-surface append cohort；它不会唤醒 Agent，也不会写入任何 inbox lane。
+- **Run recorder (`ctx.workflowRunRecorder`)** 把明确归属的 top-level run 投影到官方 Session vocabulary。
+- **Question bridge** 把 exact fenced `workflows/gate-request` 映射到 `ctx.userQuestions`，只确认当前 Agent/run/execution/gate tuple。
+- **命令与 trusted skill** 拥有 `/workflow`、`/create-workflow`、dynamic alias 以及受保护的 packaged `create-workflow` definition。Client input-trigger source 独占裸 `/workflows` 及其 overlay。
+- **Tool adapter** 只在两个官方 identity 都匹配的 exact Agent context 中临时替换官方 `workflow` tool 和 `tool:workflow` prompt section。
+- **Remote service** 提供 definition list 以及分页的 run detail、member、log、result、artifact、chunk 和 revision-checked control。
+
+Supervisor 发出 package-local `workflows/run-start`、`workflows/member-start`、`workflows/member-end`、`workflows/run-end`、`workflows/run-change` 和 `workflows/gate-request`。这些 event 是 process lifecycle 与 invalidation signal，不是 durable replay authority。Recorder 只写入 `tool-workflow/run-start`、`tool-workflow/agent-start`、`tool-workflow/agent-end` 和 `tool-workflow/run-end`；本包不发明 durable phase 或 log event。
+
+### Client 组件
+
+- **Generated Remote mount** 在任何 Remote consumer 前安装 `lib/typert.remote-client.js`，并在 read 和 controller abort 后卸载。
+- **WorkflowRunsController** 为每个 observed Session 保存一个 lazy revisioned source，处理 paging 与 reconnect generation，绝不让 late response 重建已移除状态。
+- **Dashboard navigator** 作为 client-owned 居中 overlay modal 打开（conversation 在 dimmed chrome 后仍可见），拥有宽屏、双 pane 和 mobile drill-down navigation。
+- **Member inspector** 区分 pending、JSON（包括 `null`）、text、primitive、truncated、not-produced、evicted、unavailable-transcript 和 request-error 状态。
+- **Durable Chat renderer** 只 fold 四个官方 Session event，绝不观察 package-private run head。
+
+浏览器 HMR 会依次 dispose controller、action、overlay、generated Remote mount 和 CSS ownership，然后挂载新的 Client generation。Host HMR cycle 遵循完整 teardown sequence；它不会把 live attempt 带入替换后的 plugin generation。
+
+## Public subpath 与 build face
+
+public export map 是闭集：`.`、`./registry`、`./supervisor`、`./run-recorder`、`./user-questions`、`./commands`、`./tool`、`./client`、`./types`、`./invariant`、`./typert`、`./remote`、`./cordis.patch.yml`、`./skills/create-workflow/SKILL.md` 和 `./package.json`。没有公开的 `./src/*` path。
+
+package root 拥有三个 compiler face：solution `tsconfig.json`、Host `tsconfig.host.json` 和 Client `tsconfig.client.json`。Build 顺序为 **Host TSC -> Typert -> Client TSC -> classic lazy CJS**。临时复制的 mini-workspace 提供一个 staging-root Host aggregate 和一个 copied-package staging `tsconfig.json`；其中没有嵌套 Host/Client aggregate file。Focused `WorkspaceTypertGenerator.generate()` 返回 artifact，build 会准确写入 `lib/typert.host.js`、`lib/typert.host.d.ts`、`lib/typert.remote-client.js` 和 `lib/typert.remote-client.d.ts`，并且只在返回值包含 map 时写 map。
+
+最终的 `lib/client.js` 必须调用 `window.__ModuleLoader__.load({ id: "@zaalipro/dsh-workflows", factory: (require) => ... })`，且 factory 非空。Optional-chaining `?.load` 与 `factory: () => ({})` 占位符会使 build 与 package verifier 失败。bundle 保持 baseline Client dependency 为 external，内联 package Remote 与 `clsx` code，并由 Lightning CSS 拥有 module name 和 lifecycle。Skill、patch 与 Client asset path 来自 `import.meta.url`，绝不来自 process cwd。Private evaluator 由 `vendor/workflow-engine` 构建为 tarball 中的 `lib/compat-engine/index.js` 与 `worker.cjs`，只供 supervisor 实例化，绝不替换 stock `ctx.workflowEngine`。发布物与 Git install 带上这些预构建 artifact；`dsh plugin add` 不得在安装时构建。
+
+## Lifecycle authority
+
+### 启动与 startup recovery
+
+Activation 首先验证受支持的官方 `0.1.1-rc.2` service face。Storage 随后只验证或创建 owner-only runs root 和永久 lock anchor，以 no-follow 方式打开 anchor，验证稳定 identity，并取得非阻塞 `fs-native-extensions` lifetime lease。只有 lease holder 能创建或验证四个 store directory，并在 Session admission 前完成一次完整且有界的 recovery。
+
+Recovery 会在发布任何 row 前验证所有 manifest 和引用的 sidecar。持久化的 active row 变成 terminal `interrupted`，running member head 变成 `cancelled`，orphaned notice claim 变成 `abandoned`。Recovery 保留 inspection fact 和 display ordinal，但不重建 execution authority。
+
+### Durable-before-visible launch
+
+Start 在预留 display ordinal 或 path 前验证 ownership、source、args、budget 和 capacity。它 stage `script.js`、`scratch/` 和 `details/`，发布单 component run directory，然后提交 initial version-2 manifest row。该 manifest transaction 是 durable admission。Supervisor 随后安装 private starting authority，附加所有 observer 和一个 deferred evaluator attempt，发布 in-memory row 和 package lifecycle，仅 release execution 一次，并在不等待 settlement 的情况下返回 `started`。
+
+Durable admission 前的 caller abort 会 rollback，不留下 run directory 或 ordinal。Admission 后由 supervisor 拥有 detached run。之后的 attachment 或 execution failure 会 terminalize retained history，而不是删除它。
+
+### Pause、resume 与 gate
+
+Pause 提交 `pausing`，关闭新的 engine work，取消 attempt，等待 result，等待 idempotent disposal 与 child/scratch drainage，然后同步读取 `checkpoint()`。Supervisor 只在该 quiescent checkpoint 存在后提交并发布 `paused`。
+
+普通 Resume 用 immutable admitted script、args 和 retained in-memory checkpoint 启动新 attempt。`await_user` acknowledgement 会继续 exact live attempt 并提交 satisfied gate；`pause` acknowledgement 会 dispose parked attempt 并 replay，因此未改变的 pause condition 会再次 emit。每个 answer 都由 exact Agent identity、Session、logical run、engine execution、gate id 和 generation fence 保护。Budget-limited run 只接受 model resume，且绝对 cap 必须严格提高并不超过 1,024。
+
+### Stop 与 completion notice
+
+Stop 关闭 admission，提交 `stopping`，取消 attempt 和所有 admitted child/scratch operation，等待 paired member ending 与 disposal，丢弃 resume authority，最后原子提交 terminal `cancelled` 及其 notice claim。Clean 或 failed settlement 遵循相同的 dispose-before-terminal discipline。
+
+Terminal transaction 在 head 可见前把 `completionNotice` 从 `none` 变成 `claimed`。一次 bounded append attempt 会把 claim finalize 为 `delivered` 或 `abandoned`；两者都不会重试。每个 cohort 最多携带 20 个 notice 和 262,144 UTF-8 byte。它通过 `surfaceOp: "append"` 把 plugin-sourced `user/message` 直接追加到 owner Session，使 notice durable 且立即可见，同时不会打开 completion-driven model turn。
+
+### Remote reconnect 与 HMR
+
+`workflows/run-change` 只携带 `{ kind: 'invalidate', sessionId, revision }` 或 `{ kind: 'invalidate-all' }`。ApiProxy 为最多 256 个 Session key 保留 keyed-latest hint，并把 overflow 合并成 global form。Connection loss 时 Client abort read，并把已有 source 标记为 reconnecting。`connection/reset` 后，它先获取新的 Agent-authorized epoch baseline，再接受后续 invalidation。Page、selection、Session 和 connection generation 会抑制 late response。
+
+### Fixed-point teardown
+
+Host teardown 关闭 global start admission，abort 并等待 pre-admission start，停止和 dispose 已发布 attempt，排空 child/scratch operation，提交 terminal row，完成 recorder prefix，withdraw question，并 deliver 或 abandon notice。它重复检查，直到 completion-driven work 无法再增加 owner。随后才关闭 registry 和 storage；native lease unlock 与 descriptor close 最后执行。该顺序不会遗留 worker、child、timer、watcher、request 或 lock owner。
+
+## Manifest version 2 与安全存储
+
+默认 root 是 `$DSH_HOME/workflow-runs`，其中包含永久 `.workflow-storage.lock`、位于 `sessions/<sha256(sessionId)>/manifest.json` 的 Session manifest，以及 `runs/` 下每个 run 独有的安全 32 位小写十六进制 directory。每个 run directory 拥有 `script.js`、`scratch/` 和 immutable `details/<detail-id>.json` snapshot。`staging/` 与 `quarantine/` 是独立的 root child。
+
+最大 8 MiB 的 manifest 是 Session head/index：ownership、display ordinal high-water mark、bounded run head、revision、单 component directory id、sidecar reference 和 notice state。它从不携带 absolute path、完整 output、args、journal、gate 或 Agent reference。一个 fully fsynced detail snapshot 保存 bounded member、log、result 和 artifact index；每个 run 最多引用 32 MiB detail。Terminal retention 每个 Session 最多保留 256 row，全部 committed storage 最多 512 MiB。最旧且符合条件的 terminal row 会确定性 evict；active 与 claimed-notice row 绝不 evict，display ordinal history 保留。
+
+每次 run-storage directory walk 都使用 plugin-owned、fail-closed local descriptor implementation；官方 filesystem service 仍负责 definition discovery。`script_path` read 优先使用 Host `readBytesNoFollow` capability。已发布的 stock RC2 没有该方法，因此 plugin 仅在验证为其 local filesystem shape 后，先通过 public Host `lstat`/`resolve`/`processPath` method 完成授权与规范化，再自行执行 bounded `O_NOFOLLOW` descriptor read；unknown 与 remote provider 会 fail closed。Root 与 component 必须属于当前 owner，具有严格 `0700`/`0600` mode、预期 type、regular file 单 link、无 symlink 或 junction，以及稳定 device/inode identity。Identity 改变后 cleanup 不会 recurse。永久 kernel lock 没有 PID、heartbeat、stale age、retry、takeover 或 deletion protocol。它协调同一用户下合作的 process，而不是忽略 lease 的 malicious same-UID actor。
+
+## Replay 与 script containment
+
+Journal 使用按 numeric lexicographic order 排列的 positive-safe-integer tuple 寻址 committed hook，并用小写 SHA-256 fingerprint 标识每个 effective operation。Replay 会在任何新 effect 前验证 id、kind 和 fingerprint。Cumulative `agentSpend` 和 member sequence 跨 attempt 延续；replay 与 schema-correction call 不增加 logical agent 消耗。Uncommitted effect 可能再次执行，因此系统不声称 exactly-once external effect。
+
+Replay-capable run 移除 `Date`、`Math.random`、`Atomics`、`SharedArrayBuffer`、`WeakRef` 和 `FinalizationRegistry`，同时保留 deterministic Math function。`node:vm` 塑造该 API，并使 synchronous script work 不阻塞 Host event loop；它不是 hostile-code security sandbox。Script 与现有 model shell access 保持相同 trust premise。
+
+## Bounded Remote 与浏览器展示
+
+每个 direct Remote method 的首个参数都是显式 resolved Agent，最后一个参数是必需的 `AbortSignal`；没有方法把该 root 与 `@RemoteScope` 组合。Exact Agent 及其 Session 会在读取受保护数据前授权每个 run、member、artifact、cursor 和 control。List limit 默认 50，最大 200。只有 head eager load；detail、member、outcome、log、result、artifact 和 UTF-8-safe artifact chunk 都在 selection 后加载。
+
+Dashboard 在 1,200 px 及以上使用三 pane，低于 1,200 px 使用双 pane，低于 768 px（包括 320 px）使用明确的 runs-to-execution-to-inspector drill-down。它 trap 并恢复 focus，使用真实 selection control，在 error 后保留先前成功 page，提供有 label 的 Retry action，支持 Escape 和受保护的 P/R/X/S shortcut，尊重 reduced motion，并让窄屏 action 至少为 44 px。
+
+## 兼容性来源
+
+官方 `0.1.1-rc.2` integration 只在识别出 stock workflow contribution 时使用 Agent-scoped `tools.register` 与 `systemPrompt.section`；同名 custom contribution 保持不变。Deferred execution、replay journal、checkpoint、gate、budget accounting 与 scratch 由 package private compatibility evaluator 提供。
+
+官方 `0.1.1-rc.2` 是 plugin `0.1.0-rc.3` 唯一已验证的 installed Host；`0.1.0-rc.8` 不受支持，更高 Host 必须重新验证。Compatibility evaluator 是 package-owned MIT source，只窄范围承载 maintained workflow behavior，绝不替换 stock `ctx.workflowEngine` 或 process-global stock workflow service。
+
+## Capacity bound
+
+Default 与 hard ceiling 使所有 path 有界：每个 run 默认 128 个 agent、最多 1,024；deployment live concurrency；8 MiB Host protocol frame；64 MiB journal；1 MiB prompt 与 definition/projection file；64 KiB event；8 MiB manifest；每个 run 32 MiB detail；512 MiB committed store；4,096 个 startup entry；每个 Session 64 个 active run、全局 1,024；每个 Remote page 200 row；以及 256 个 pending Session invalidation key。Scratch 最多允许 4,096 次 operation、64 个 pending operation、64 个 file、每个 file 1 MiB、合计 8 MiB，除非 configuration 下调限制。

package/docs/testing.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.
+testing.md: 6c3bb3f89939ed2aae75a6ab812203b841d95bca
+testing.zh.md: 25edde0ab27df71ec0b34b5fe8e91fa6840b7591

package/docs/testing.md

@@ -0,0 +1,125 @@
+# Testing and release acceptance
+
+English | [中文](testing.zh.md)
+
+This reference separates automated proof from the final human release decision. A green unit suite never substitutes for the official-prerequisite, assembled, packed-consumer, browser, race, provider, or manual boundaries below.
+
+## Automated gates
+
+Run package commands from the package checkout with a frozen `pnpm@11.7.0` install. Each command exits nonzero at its first failure; the text after it is the success marker a CI or release log must retain.
+
+### Build, type, lint, coverage, and 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
+```
+
+The documentation command prints exactly `documentation verification passed`. It checks complete English/Chinese pairs and their recorded blob hashes, local files and heading fragments, one trailing LF, current compatibility prose, and the required installation, architecture, testing, user, and Agent Note coverage.
+
+### Keyless assembled snapshots
+
+```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` is a source-resolved fixture: it feeds official `tool-workflow/*` events through `ConversationNodeAssembler`, proves append/prepend/full-replay parity, maps Interrupted Chat nodes to cancelled, and checks the completion-notice footer. It does not boot the official assembled snapshot harness or compare reviewed Session/stdout JSONL files; those `examples/workflows-keyless/` inputs remain a later assembled gate. The dashboard snapshot locks accessible empty, live, terminal, interrupted, disclosure, and member-outcome semantics rather than CSS hashes.
+
+### Package policy and 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'
+```
+
+The standalone packed-consumer test performs one `pnpm pack --json`, records SHA-256, and sends that unchanged absolute tarball to `scripts/verify-package.mjs --tarball`. During a release, `scripts/check-release.mjs` is the sole pack owner and calls `scripts/packed-consumer.mjs` with that same artifact instead; generic unit commands exclude the self-packing spec. Missing skill, client bundle, evaluator, or required peer assets fail before any consumer Session starts. The runner installs the bytes with scripts disabled, installs pinned consumer-only TypeScript/Node types and the exact prebuilt official CLI, imports every JavaScript and strict NodeNext export, and loads `lib/client.js` through the lazy-CJS seam. Every declared Host, Client, Cordis, and React peer remains an exact compatibility declaration but is marked optional: an isolated `autoInstallPeers: true` probe must not materialize one, while the standalone import/type probe supplies peers explicitly. The real Web and headless profile cycles must retain official `autoInstallPeers: false`, contain no profile-local peer package, resolve those peers through the healed official fallback, and resolve `dsh-scope` to one realpath from both agent-loop and agent-presets. Each profile then receives two bounded activation/teardown sentinel boots (the second proves lease release), remove, and manifest restoration. Source-tree runtime fallback, `--help` as activation evidence, a split Host graph, or a second release pack is a failure.
+
+### Automated Chromium
+
+```sh
+pnpm exec vitest run tests/browser-smoke.spec.ts --reporter=dot && printf 'RD10 browser automation PASS\n'
+```
+
+`tests/browser-smoke.spec.ts` currently gates the `scripts/browser-smoke.mjs` helper boundary: absolute arguments, loopback readiness JSON, stdin teardown, and isolation from the caller's workspace. It does not drive Chromium through slash discovery, disclosures, or 1,199/767/320 px layouts. That product journey is the final Ego Lite checklist below, not a substitute this helper already covers.
+
+### Lifecycle, storage, and 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'
+```
+
+These deterministic repeated suites cover aggregate cancellation, pending durable admission, pause/stop/teardown, worker death, completion cohorts, advisory-lease contention, link/inode substitution, interrupted publication, stale gate/control/page responses, reconnect generations, invalidation overflow, and cross-Agent authorization. They assert zero orphan worker, child, scratch operation, timer, watcher, controller, request, cursor, selection, or unhandled rejection. The donor aggregate-cancellation scenario must pass alone and inside the aggregate suite repeatedly; one passing rerun never excuses a failure.
+
+### Opt-in real provider
+
+```sh
+pnpm exec vitest run tests/real-provider.spec.ts --reporter=dot && printf 'RD14 real provider gate PASS\n'
+```
+
+With `DEEPSEEK_API_KEY`, the file starts exactly two logical children labelled `alpha` and `beta`, verifies the independent bytes `alpha` in `alpha.txt` and `beta` in `beta.txt`, verifies final result `{"alpha":"alpha","beta":"beta"}`, and disposes every child, worker, Agent, Host, lease, and temporary directory in `finally`. It reads `DEEPSEEK_BASE_URL` only through official provider configuration. Neither value, any credential, nor a model transcript enters logs or artifacts.
+
+Without the key, this file alone registers exactly one skipped test with reason `DEEPSEEK_API_KEY is not set`. No other package, platform, workflow, or storage lane may self-skip.
+
+### Exact official Host checkout
+
+The packed consumer and CI checkout official DeepSeek Harness `0.1.1-rc.2` at commit `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`. The package build and tests compile against `0.1.1-rc.2` development dependencies; no Harness source patch or fork checkout participates. The package-owned evaluator build, strict NodeNext consumer, add/boot/remove profile cycle, and stock boot after removal are blocking release evidence.
+
+### Final automated aggregate
+
+```sh
+pnpm run check:release
+```
+
+Success ends exactly `release checks passed`. The orchestrator runs clean/frozen-install verification, build, typecheck, lint, owned-source aggregate coverage, snapshots, documentation, package policy, one immutable pack and packed consumer (`official-host-probe` plus real Web/headless add/boot/remove), the browser helper boundary, all three stress suites, and the opt-in provider file in order. It does not publish, launch Ego Lite, or record a GIF. The packed profile cycle is blocking against official `0.1.1-rc.2`; the Chromium product journey remains the final Ego Lite acceptance.
+
+## Coverage policy
+
+`pnpm run test:coverage` enforces truthful aggregate floors of **80% statements, 80% branches, 80% functions, and 80% lines** across owned package integration source. Its explicit instrumentation include is `src/**/*.{ts,tsx}` with type-only declarations excluded, so unimported owned source still counts while generated `lib/` and release helpers under `scripts/` cannot enter the denominator accidentally. Per-file 100% is not claimed: the August 23 baseline was 85.35% statements/lines, 80.69% branches, and 84.98% functions. That command excludes packed-consumer, browser-smoke, snapshot, stress, and real-provider lanes. The stored `coverage-all` report is not 100% of generated `lib/` plus dependencies (~57% last captured); it is not a substitute for the owned-source aggregate gate. Tests exercise deterministic clocks and barriers, every error and cancellation branch, effect disposal, HMR registration, authorization, and external world state rather than self-reported success.
+
+The only non-instrumented artifacts are generated or browser-delivery products rather than an exception for handwritten Host behavior:
+
+| Exclusion | Why it is not instrumented as owned runtime source | Required evidence |
+|---|---|---|
+| `vendor/workflow-engine/*.ts` and emitted `lib/compat-engine/*` | Attributed MIT compatibility evaluator with a separate process/worker protocol gate | `tests/compat-engine.spec.ts`, supervisor replay/gate/budget/scratch suites, packed artifact verification, and live profile smoke |
+| `lib/typert.host.*` and `lib/typert.remote-client.*` | Generated from decorated Host source | `tests/build-artifacts.spec.ts`, Remote API tests, packed imports, and browser mount smoke |
+| `lib/client.js`, emitted Client declarations/maps, and Lightning CSS output | Generated bundle products | Client component/controller specs, dashboard semantic snapshots, packed serving, and `tests/browser-smoke.spec.ts` |
+| `src/client/css-modules.d.ts` | Type-only generated-facing declaration with no executable statements | Client TSC plus source assertion in the build suite |
+| CSS module visual branches | Styles do not enter JavaScript statement coverage | source token assertions, jsdom semantic snapshots, and the final Ego Lite real-flow GIF when GUI behavior changes. Automated Chromium in CI only gates `scripts/browser-smoke.mjs`; layout, light/dark, and reduced-motion remain manual Ego Lite. |
+
+Handwritten Client TypeScript remains covered by its Client test project; generated outputs do not create a parallel coverage denominator. Adding another exclusion requires corresponding real-browser evidence and an explicit testing-policy change.
+
+## CI platform matrix
+
+Blocking Ubuntu 24.04 jobs run Node `22.19.0`, `24`, and `26`; each uses a frozen lockfile and covers build, typecheck, lint, docs, package policy, and its assigned unit/coverage/snapshot gates. Node 24 additionally owns macOS 14, Windows Server 2022, Chromium helper, race-stress, and release-pack/packed-consumer jobs. The packed lane checks out official `0.1.1-rc.2` commit `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`; it applies no Harness patch, packs once, preserves one digest and artifact path, and requires live add/boot/remove for Web and headless.
+
+Windows runs every supported definition, manifest, scratch, retention, recovery, and subprocess case. It explicitly asserts junction/hard-link behavior and either working native advisory locking or the documented `WORKFLOW_STORAGE_UNSUPPORTED` result; it never silently skips the workflow, marks the job `continue-on-error`, or treats a platform limitation as success without asserting its exact branch.
+
+CI may upload reviewed snapshot, browser, stress, and pack diagnostics only after failure. It never uploads a DSH home, credential, secret-lane model transcript, or unrestricted scratch store. Actions are pinned to full commit SHAs, permissions default read-only, jobs have timeouts, and only the real-provider file may skip for an absent key.
+
+## Real-provider secret and cleanup policy
+
+CI passes `DEEPSEEK_API_KEY` only to the isolated provider job when available. The test never prints the key or base URL and never copies them into child prompts, session logs, screenshots, archives, or failure diagnostics. A provider error may name the display handle and provider failure, never the internal run UUID or credential material.
+
+All live resources are created inside an isolated workspace and DSH home. `finally` stops or settles the run, disposes child catalog entries, worker handles, the Agent and Host, releases the permanent-anchor lease, and removes the temporary directories even after provider failure or timeout.
+
+## Final manual Web acceptance
+
+This is a release checklist, not a coding task, CI step, or substitute for automated Chromium. Perform it only after every automated gate passes, using the exact tested tarball installed into a real official `0.1.1-rc.2` Web profile and a real server/model flow.
+
+- [ ] Start the tarball-installed real server and confirm the package activates without a source checkout fallback.
+- [ ] Use **Ego Lite** for the smoke journey. Reuse its task space across the journey; never wipe or reset any user session, cookies, browser storage, or daily-browser state.
+- [ ] Confirm `/create-workflow`, `/workflow`, `/workflows`, and a saved alias appear; launch two runs and observe immediate acknowledgements, display-name numbering, live phase/member/progress updates, and a usable composer.
+- [ ] Open and close the run disclosure and `Inspect · N members`; inspect real text/Markdown and JSON outcomes, logs, result, and a scratch artifact. Verify no internal UUID appears in user-visible or accessible text.
+- [ ] Exercise a resumable gate, Pause, Resume, Stop, and an eligible Save; confirm stale-revision and budget-limited errors remain visible and actionable.
+- [ ] Check focus restoration, keyboard controls, screen-reader labels, light/dark/reduced-motion behavior, and the narrow mobile drill-down without horizontal overflow.
+- [ ] Confirm exactly one completion notice per eligible run and no duplicate `workflows · Completed` row merely from opening the dashboard.
+- [ ] For any product-visible GUI change, record and retain a GIF from this **real PR server/model flow** showing launch, live updates, member outcome inspection, controls, and narrow layout. A mocked or source-only GIF is not release evidence.
+- [ ] When verification is complete, close **only the Ego Lite task space**. Do not wipe sessions, cookies, storage, or unrelated tabs/spaces.
+
+Record the tested tarball SHA-256, official Host build identity, platform, automated aggregate log, manual result, and GIF location in the release evidence. A failed manual item blocks release even when the automated suite is green.