super-dsh 0.3.0-c → 0.3.0-e

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/workflow.zh.md

@@ -1,278 +0,0 @@
-# 工作流
-
-[English](workflow.md) | 中文
-
-工作流 seam 允许 agent（智能体）运行由模型编写、会启动 subagent 的编排脚本。与 [subagent](subagent.zh.md) 一样，它是**一项可选能力**，不属于 agent loop，因此其类型和操作记录在此处，而非 [core.md](core.zh.md)。与 bash 一样，每个上下文只允许一个引擎实现提供 `ctx.workflowEngine`；没有命名提供方注册表（第二个引擎通过插件配置替换第一个，而不与它同时运行）。
-
-Service Definition：[dsh-workflow](../../packages/workflow/workflow)（`ctx.workflowEngine` + 下文词汇）。Service Provider 是 [dsh-workflow-worker-thread](../../packages/workflow/workflow-worker-thread)（一个 `node:worker_threads` 引擎——每个 run 一个 worker，脚本的 vm 上下文位于其中）；面向模型的 Consumer 是 [dsh-tool-workflow](../../packages/workflow/tool-workflow)。提案与设计理由见 [dynamic-workflows Agent Note](../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md)。
-
-源码：浏览器安全词汇位于 [`packages/workflow/workflow/src/types.ts`](../../packages/workflow/workflow/src/types.ts)，Host 请求与活跃运行句柄位于 [`runtime-types.ts`](../../packages/workflow/workflow/src/runtime-types.ts)。
-
-## 启动请求
-
-本节定义调用方启动一次运行时提交的请求。普通工作流工具会根据模型的 `{ script, meta, args }` 调用和发起调用的 agent 构建该请求；专用消费方还可以为本次运行选择引擎级 `subagentProvider`，并将 `maxTotalAgents` 调低，但脚本无法观察或替换这两项策略。`meta` 与 `args` 是普通 JSON 数据；引擎会用 schema 校验 `meta`，并在任何工作开始前明确报错并拒绝无效数据。引擎绝不会通过对脚本文本求值来获取它们。`parent` 是必填字段——脚本启动的每个子 agent 都归属于它，cwd、谱系与深度通过 [subagent seam](subagent.zh.md) 传递。
-
-```ts type-equiv
-/**
- * What a caller asks for when starting a workflow run. `meta` and `args` are
- * plain JSON data by the seam contract. `parent` is required because every
- * `agent()` spawned by the script is attributed to that live Agent.
- */
-interface WorkflowStartRequest {
-  /** The plain-JS script body (top-level await allowed; ends with `return <json-value>`). */
-  script: string
-  /** The workflow's identity block, as plain JSON data (shape-validated by the engine). */
-  meta: WorkflowMeta
-  /** Optional input exposed verbatim to the script as the `args` global. */
-  args?: unknown
-  /** Optional engine-wide child-provider override for this run. */
-  subagentProvider?: string
-  /** Optional per-run total-child ceiling. */
-  maxTotalAgents?: number
-  /** The agent on whose behalf the run executes (parent of every child). */
-  parent: Agent
-  /** Cancels the run when aborted. */
-  signal?: AbortSignal
-}
-```
-
-## 工作流的身份标识：`WorkflowMeta`
-
-作为数据附在启动请求上的身份块（工具的 `meta` 参数；字段词汇与 Claude Code 动态工作流的 meta 块一致）。`phases` 仅用于进度展示：`phase()` 调用与标题匹配，供观察者使用；不暗示任何执行结构。
-
-```ts type-equiv
-/**
- * The script's identity block, provided as plain JSON data alongside the
- * script body (the model-facing tool carries it as its `meta` parameter) and
- * validated by the engine before the body runs. `name`/`description` are
- * required; the rest is optional annotation. The field vocabulary matches the
- * Claude Code dynamic-workflows meta block.
- */
-interface WorkflowMeta {
-  /** Short kebab-case workflow name (display + persistence key). */
-  name: string
-  /** One-line description of what the workflow does. */
-  description: string
-  /** Optional guidance on when this workflow applies (shown in listings). */
-  whenToUse?: string
-  /** Optional phase declarations matched by `phase()` calls. */
-  phases?: WorkflowPhase[]
-}
-```
-
-## 终态结果：`WorkflowResult`
-
-`WorkflowRun.result` 会兑现为一次运行的结果。`value` 是脚本的物化返回值——纯宿主域 JSON 数据（脚本无返回值时为 `null`）——仅在 `completed` 时有意义。`stopReason` 是封闭联合类型（由引擎定义；消费方可穷举）：`completed` | `cancelled` | `error`。非 `completed` 的原因在 `error` 中携带失败信息，消费方将其映射为 `isError` 工具结果，而非把部分输出当作成功上报。
-
-```ts type-equiv
-/**
- * The outcome resolved by a live workflow run. `value` is
- * the script's materialized return value (plain host-realm JSON data; `null`
- * when the script returned `undefined`) — meaningful only for `completed`.
- * A non-`completed` reason carries the failure in `error`; the consumer maps
- * it to an `isError` tool result rather than reporting partial output.
- */
-interface WorkflowResult {
-  /** The script's return value (host JSON data; `null` for no return). */
-  value: unknown
-  /** Why the run settled. */
-  stopReason: WorkflowStopReason
-  /** The failure message (present iff `stopReason` is not `completed`). */
-  error?: string
-  /**
-   * How many `agent()` calls the run accepted over its whole lifetime. On a
-   * graceful settlement this is the script-side count (calls still queued for
-   * a concurrency slot included); on a termination path (grace force-settle,
-   * worker death) it degrades to the host-observed count — calls queued
-   * inside a terminated script are unknowable then.
-   */
-  agentsStarted: number
-}
-```
-
-## 活跃运行：`WorkflowRun`
-
-脚本执行期间消费方持有的句柄。消费方会等待 `result`，可以在运行期间调用 `cancel`，并且必须在每条路径上调用 `dispose`（资源释放）。`result` 不会被拒绝：脚本失败会兑现为 `stopReason: 'error'`。运行被取消后，即使脚本本身永不结算，结果也会在引擎规定的有界宽限期内结算；引擎会强制将其结算为 `cancelled`，随后 worker-thread 引擎会终止脚本所在的 worker。因此，等待 `result` 的消费方不会在取消后无限期挂起。`dispose()` 会执行取消、等待有界结算并等待子 agent 完全停稳，不会因脚本卡死而挂起。
-
-```ts type-equiv
-/**
- * Holder-owned live workflow. `result` never rejects; consumers may cancel
- * and must call idempotent `dispose()` to await script and child quiescence.
- */
-interface WorkflowRun {
-  readonly id: WorkflowRunId
-  /** The validated meta block available before the script body runs. */
-  readonly meta: WorkflowMeta
-  readonly result: Promise<WorkflowResult>
-  /** Cancel the run and its children. */
-  cancel(reason?: string): void
-  /** Cancel if needed and await bounded settlement and cleanup. */
-  dispose(): Promise<void>
-}
-```
-
-## 失败纪律：`WorkflowError.fatal`
-
-脚本内部的钩子误用：错误参数、未知或延迟的 `agent()` 选项、超出[结构化输出子集](../../packages/core/tools/README.zh.md)的 schema、超出上限、seam 启动失败、取消，都会抛出 `fatal: true` 的 `WorkflowError`。`parallel()`/`pipeline()` 组合器对 fatal 错误直接重新抛出，而非将该项映射为 `null`：一个拼写错误的选项必须明确报错并终止脚本，绝不能消融为看似普通子 agent 失败的结果。逐项的 `null` 保留给子运行失败（非 `completed` 的 stop reason）和阶段内的普通脚本错误。
-
-## 事件
-
-`workflow/*` 事件（`workflow/start`、`workflow/phase`、`workflow/log`、`workflow/agent-start`、`workflow/agent-end`、`workflow/end`，见[事件目录](#cordis-surface)）是**仅供观察**的 emit，携带数据快照：每个 payload 以 `WorkflowRunInfo`（id + meta）开头，而非活跃的 `WorkflowRun`，因此订阅者无法获得 `cancel`/`dispose`；`workflow/end` 刻意省略 result value（观察结果的监听器不得收到调用方 result 的可变别名）。每次 emit 对每个监听器隔离：订阅者抛出的异常会被记录到日志中而不会传播，也不会阻止后续注册的监听器收到事件；每个监听器收到自己的 payload 克隆，因此修改它既不会损坏引擎也不会影响其他监听器。这种隔离方式与 `subagent/start`/`subagent/end` 一致。
-
-## 持久 Chat 记录
-
-顶层 `dsh-tool-workflow` 消费方把展示事实投影到调用它的父 Session，同时不改变执行所有权。运行接受后写 `tool-workflow/run-start`，以 `runId + seq` 配对成员开始与结束，并且只在结果已取得且 dispose 完全停稳后写 `tool-workflow/run-end`。嵌套 transport 调用不写记录。第一次 append 失败会禁用本运行后续写入，因此日志保持为空或合法连续前缀，工具结果不变。
-
-`dsh-tool-workflow/invariant` 会在实时提交前和 Session 加载时校验同一协议：每个运行只有一个 start，成员序号为正且唯一，成员 end 必须配对，仍有开放成员时不能结束运行，运行结束后不能继续更新。日志尾部缺少成员 end 或 run end 是有效的中断证据，不是损坏。
-
-`dsh-client-ui-workflow-run` 通过 Conversation Node 引擎把四类事件折叠为一个 `workflow-run` Chat 节点，以 run-start 序号锚定在原工作流工具节点之后。阶段组只来自真正开始过的成员，并保留精确字符串，包括字段缺省与 `''` 的区别。Location 关闭时，缺失终点会显示为已中断。[界面包 README](../../packages/client/ui-workflow-run/README.zh.md)负责定义 disclosure、状态与同父本地导航行为。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxworkflowengine--workflowengine-abstract-seam"></a>
-
-### `ctx.workflowEngine` — `WorkflowEngine` (abstract seam)
-
-Workflow Service Definition contract. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.
-
-```ts cordis-catalog
-/**
- * Parse and execute a workflow script.
- * @param request - the script, its `args`, the parent agent, and an
- *   optional cancel signal.
- * @returns the live run; its `result` resolves when the script settles.
- */
-abstract start(request: WorkflowStartRequest): WorkflowRun
-```
-
-Source: [`packages/workflow/workflow/src/index.ts`](../../packages/workflow/workflow/src/index.ts)
-
-<a id="workflow-events"></a>
-
-### `workflow/*` events
-
-<a id="workflowagent-end--emit"></a>
-
-#### `workflow/agent-end` — emit
-
-One `agent()` call settled (clean result, child failure, or run cancellation). Paired with Events['workflow/agent-start'] by `agent.seq`, exactly once per started call on every stop path — on an engine termination path (a worker killed past its grace) the end is engine-synthesized with outcome `'cancelled'`.
-
-```ts cordis-catalog
-/**
- * One `agent()` call settled (clean result, child failure, or run
- * cancellation). Paired with {@link Events['workflow/agent-start']} by
- * `agent.seq`, exactly once per started call on every stop path — on an
- * engine termination path (a worker killed past its grace) the end is
- * engine-synthesized with outcome `'cancelled'`.
- * @param info - the run's identity snapshot.
- * @param agent - the call identity plus its outcome.
- * @mode emit
- */
-'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
-```
-
-Source: [`packages/workflow/workflow/src/index.ts`](../../packages/workflow/workflow/src/index.ts)
-
-<a id="workflowagent-start--emit"></a>
-
-#### `workflow/agent-start` — emit
-
-One `agent()` call established a published child run. Paired with Events['workflow/agent-end'] by `agent.seq`. A call that never receives a published run from the provider emits neither event in this pair.
-
-```ts cordis-catalog
-/**
- * One `agent()` call established a published child run. Paired with
- * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
- * receives a published run from the provider emits neither
- * event in this pair.
- * @param info - the run's identity snapshot.
- * @param agent - the call's sequence number, label, phase, and child id.
- * @mode emit
- */
-'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
-```
-
-Source: [`packages/workflow/workflow/src/index.ts`](../../packages/workflow/workflow/src/index.ts)
-
-<a id="workflowend--emit"></a>
-
-#### `workflow/end` — emit
-
-A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves. Paired with Events['workflow/start'].
-
-```ts cordis-catalog
-/**
- * A workflow run settled (any stop reason). Fired when
- * {@link WorkflowRun.result} resolves. Paired with
- * {@link Events['workflow/start']}.
- * @param info - the run's identity snapshot.
- * @param result - the outcome data (stop reason, error, agent count) —
- *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
- * @mode emit
- */
-'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
-```
-
-Source: [`packages/workflow/workflow/src/index.ts`](../../packages/workflow/workflow/src/index.ts)
-
-<a id="workflowlog--emit"></a>
-
-#### `workflow/log` — emit
-
-The script emitted a narration line (a `log(message)` call).
-
-```ts cordis-catalog
-/**
- * The script emitted a narration line (a `log(message)` call).
- * @param info - the run's identity snapshot.
- * @param message - the logged message, verbatim.
- * @mode emit
- */
-'workflow/log'(info: WorkflowRunInfo, message: string): void
-```
-
-Source: [`packages/workflow/workflow/src/index.ts`](../../packages/workflow/workflow/src/index.ts)
-
-<a id="workflowphase--emit"></a>
-
-#### `workflow/phase` — emit
-
-The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics.
-
-```ts cordis-catalog
-/**
- * The script entered a phase (a `phase(title)` call) — progress grouping
- * for observers; no execution semantics.
- * @param info - the run's identity snapshot.
- * @param title - the phase title, verbatim.
- * @mode emit
- */
-'workflow/phase'(info: WorkflowRunInfo, title: string): void
-```
-
-Source: [`packages/workflow/workflow/src/index.ts`](../../packages/workflow/workflow/src/index.ts)
-
-<a id="workflowstart--emit"></a>
-
-#### `workflow/start` — emit
-
-A workflow run started — the script's meta block validated, the body about to execute. Paired with Events['workflow/end'].
-
-```ts cordis-catalog
-/**
- * A workflow run started — the script's meta block validated, the body
- * about to execute. Paired with {@link Events['workflow/end']}.
- * @param info - the run's identity snapshot (id + meta).
- * @mode emit
- */
-'workflow/start'(info: WorkflowRunInfo): void
-```
-
-Source: [`packages/workflow/workflow/src/index.ts`](../../packages/workflow/workflow/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/workspace.md

@@ -1,321 +0,0 @@
-# Workspaces
-
-English | [中文](workspace.zh.md)
-
-A workspace is the persistent record of a directory the user works in: a stable id over a canonical path, a display title, and the ordered account of sessions that belong to it. The subsystem is one package ([dsh-workspace](../../packages/workspace/workspace), `ctx.workspaceRegistry`) — an optional host-side capability, not part of the agent-loop spine, and invisible to models (no tools, no prompt text, no session events). It stores its records through the [storage domain form](storage.md) and validates session membership against [`SessionHeader.cwd`](persistence.md#sessionheader--metadata-beside-the-log), so `storageDomain` and `sessionPersistence` are mandatory startup dependencies: an unavailable persistence peer leaves the plugin pending rather than being mistaken for an empty history. Design record: [domain KV storage Agent Note](../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md); bootstrap and GUI ordering: [Workspace UI product-flow Agent Note](../../.agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.md).
-
-Source: [`packages/workspace/workspace/src/types.ts`](../../packages/workspace/workspace/src/types.ts)
-
-## Identity
-
-```ts type-equiv
-/**
- * Identifies one workspace record. A generated uuid, never the path: path
- * normalization rewrites paths, and a reference anchor must stay stable.
- */
-type WorkspaceId = Branded<'WorkspaceId'>
-```
-
-`WorkspaceId` is a [branded id](core.md#branded-ids). Path identity is separate: `realpathNormalize` (`fs.realpath`; trailing slashes, `..`, and symlinks resolved) is the one uniqueness canon — workspace paths are stored canonicalized, uniqueness is string equality of canonical paths (a symlink to an owned directory collides), and attach-time session cwd checks go through the same canon.
-
-## The workspace entity
-
-Consumers see only the `Workspace` interface; the implementation stays package-private.
-
-```ts type-equiv
-/**
- * One workspace: a stable id over an existing directory, a display title, and
- * an ordered candidate account of sessions. Membership requires both an id in
- * that account and a session header whose canonical cwd equals the workspace
- * path. Consumers only see this interface; the implementation stays private.
- */
-interface Workspace {
-  /** Stable record id (generated uuid). */
-  readonly id: WorkspaceId
-
-  /**
-   * Canonical directory path: the `fs.realpath` of the path given at create
-   * time (trailing slashes, `..`, and symlinks all resolved). Never rewritten
-   * afterwards, even when the directory disappears (see {@link status}).
-   */
-  readonly path: string
-
-  /** Display title. Defaults to the final path segment, or a filesystem root's own spelling; duplicates are allowed. */
-  readonly title: string
-
-  /** ISO-8601 creation instant, stamped at create and never rewritten. */
-  readonly createdAt: string
-
-  /** ISO-8601 instant of the last durable mutation (create counts as one). */
-  readonly updatedAt: string
-
-  /**
-   * Header-validated sessions in manually owned order: a new session is
-   * prepended at attach, explicit reordering goes through
-   * `insertSessionBefore`, and activity never reorders. The durable candidate
-   * account is filtered synchronously: missing headers, invalid cwd values,
-   * and canonical cwd mismatches are never returned. A subsequent workspace
-   * mutation prunes those filtered candidates durably.
-   */
-  readonly sessionIds: readonly SessionId[]
-
-  /**
-   * Replace the display title durably.
-   * @param title - New title; any string, duplicates across workspaces allowed.
-   * @returns resolution after durability.
-   */
-  setTitle(title: string): Promise<void>
-
-  /**
-   * Prepend a session to this workspace's candidate account. An already
-   * accounted id resolves without writing, aside from the durable
-   * filtered-candidate prune every accepted mutation performs. A new id's
-   * live or persisted
-   * header cwd must resolve to an existing directory equal to {@link path};
-   * unknown ids, missing or invalid cwd values, and mismatches reject without
-   * writing.
-   * @param sessionId - The session to record.
-   * @returns resolution after durability.
-   */
-  attachSession(sessionId: SessionId): Promise<void>
-
-  /**
-   * Move an accounted session within the manual order, DOM-insertBefore-like:
-   * with an anchor the session lands before it, without one it appends to the
-   * end. Only the moved id changes position. A session or anchor absent from
-   * the account rejects without writing; a move to the current position
-   * resolves without writing, aside from the durable filtered-candidate
-   * prune every accepted mutation performs; decided on the domain write
-   * chain.
-   * @param sessionId - The accounted session to move.
-   * @param beforeSessionId - Accounted anchor to insert before; omitted appends.
-   * @returns resolution after durability.
-   */
-  insertSessionBefore(sessionId: SessionId, beforeSessionId?: SessionId): Promise<void>
-
-  /**
-   * Remove a session from this workspace's account. Idempotent: an id not on
-   * the account resolves without writing, aside from the durable
-   * filtered-candidate prune every accepted mutation performs; decided on
-   * the domain write chain like attach. Never touches the session's own stored log.
-   * @param sessionId - The session to remove.
-   * @returns resolution after durability.
-   */
-  detachSession(sessionId: SessionId): Promise<void>
-
-  /**
-   * Live directory check, uncached: whether {@link path} currently exists and
-   * is a directory. A missing directory never mutates the record — the
-   * directory may only be temporarily moved.
-   * @returns `'ok'` when the directory exists, `'missing-dir'` otherwise.
-   */
-  status(): Promise<'ok' | 'missing-dir'>
-}
-```
-
-Ownership truth is the record's ordered `sessionIds`, never derived from session cwd — but membership requires both: an id on the account and a header whose canonical cwd equals the workspace path, so one session structurally belongs to at most one workspace. Failed writes reject (`insertSessionBefore` account errors as `WorkspaceMoveInvalidError`, storage failures as plain errors); every accepted mutation stamps `updatedAt` and durably prunes candidates that no longer pass the membership check.
-
-## The registry: `ctx.workspaceRegistry`
-
-`WorkspaceRegistry` ([signatures](#ctxworkspaceregistry--workspaceregistry)) owns registration and resolution. `create(path, title?)` requires a fully qualified path, canonicalizes it, rejects a nonexistent path (the original `ENOENT`) or a non-directory, returns the existing entity unchanged when the canonical path is already owned, and otherwise creates a record with `title ?? defaultWorkspaceTitle(path)` prepended to the durable registry order (different canonical paths may share a display title, and a path with no final segment uses its root spelling). `get(id)` and the ordered `list()` are synchronous cache reads; `resolveByPath(path)` applies the same fully qualified realpath canon without creating. `delete(id)` removes only the registration, order entry, and session account — the directory, user files, live sessions, and persisted logs are never touched, so those sessions become Ungrouped ([decision](../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)); unknown ids return `false`. Create and delete persist a pending-mutation marker before their two writes (record + order) can diverge; startup resolves exactly the marked mutation — by deleting the marked table row, which completes an interrupted delete and rolls back an interrupted create (the registration is re-creatable, so rollback is the safe direction) — and an unmarked order/table mismatch fails loud as corruption.
-
-Sessions get their cwd at create time from whoever creates them, not from this registry — the API gateway resolves a new session's cwd from the chosen workspace's `path` (falling back to an explicit or default cwd), creates the session so the cwd lands in its immutable [`SessionHeader`](persistence.md#sessionheader--metadata-beside-the-log), then calls `attachSession`, which re-validates that stored header cwd against the workspace path. On the first successful start, the registry bootstraps history from persisted headers alone (`id`, `cwd`, `createdAt` — never event bodies), grouping sessions with a valid canonical cwd into per-directory workspaces, newest first; the initialized marker is written last so an interrupted bootstrap resumes safely. The bootstrap is one-time: cwd-less legacy sessions stay Ungrouped, and sessions created afterwards join a workspace only through `attachSession`.
-
-## Consumers
-
-[`dsh-workspace-controller`](../../packages/api/workspace-controller) serves workspace CRUD to GUI clients over `ctx.workspaceRegistry`, and [`dsh-session-controller`](../../packages/api/session-controller) performs the create-session-then-attach flow above. [dsh-agent-instructions](../../packages/context/agent-instructions) is **not** a consumer despite the name: it discovers AGENTS.md-style instruction files under an agent's own cwd and never touches `ctx.workspaceRegistry` — the shared word refers to the user's working directory, not to this registry's entities.
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxdirectorypicker--directorypicker-abstract-seam"></a>
-
-### `ctx.directoryPicker` — `DirectoryPicker` (abstract seam)
-
-Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.
-
-```ts cordis-catalog
-/**
- * The backend's interaction capability.
- * @returns the discriminated capability consumers switch on.
- */
-abstract capability(): DirectoryPickerCapability
-```
-
-Source: [`packages/host/directory-picker/src/index.ts`](../../packages/host/directory-picker/src/index.ts)
-
-<a id="ctxdirectorypickercontroller--directorypickercontroller"></a>
-
-### `ctx.directoryPickerController` — `DirectoryPickerController`
-
-Host service backing the generated `ctx.remote.directoryPicker` namespace. The seam it exports is abstract and therefore never a Loader entry of its own, so this controller carries the wire verbs: one composed backend serves either the native chooser or the browse primitives, and a verb the composition cannot serve is refused rather than approximated.
-
-```ts cordis-catalog
-/**
- * Open the host's OS chooser for a Remote caller.
- * @param signal - caller lifetime; abort terminates the chooser.
- * @returns the chosen absolute path, or null when the operator cancels.
- */
-@Remote('pick') async pick(signal: AbortSignal): Promise<string | null>
-
-/**
- * List one directory level for a Remote caller's in-app browser.
- * @param path - absolute directory to list; absent lists the home directory.
- * @param signal - caller lifetime; abort stops the backend's scan instead of
- *   letting it outlive a disconnected caller.
- * @returns the level's listing with its ancestry.
- */
-@Remote('list') async list(path: string | undefined, signal: AbortSignal): Promise<DirectoryListing>
-
-/**
- * Create one child directory for a Remote caller's in-app browser.
- * @param path - absolute existing parent directory.
- * @param name - single non-blank path segment.
- * @returns the created directory's absolute path.
- */
-@Remote('createDirectory') async createDirectory(path: string, name: string): Promise<string>
-```
-
-Source: [`packages/api/workspace-controller/src/directory-picker.ts`](../../packages/api/workspace-controller/src/directory-picker.ts)
-
-<a id="ctxworkspacecontroller--workspacecontroller"></a>
-
-### `ctx.workspaceController` — `WorkspaceController`
-
-Host service backing the generated `ctx.remote.workspace` namespace.
-
-```ts cordis-catalog
-/**
- * Create or idempotently resolve one Workspace over an existing directory.
- * @param request - directory path to register.
- * @returns the Workspace and whether this call created it.
- */
-@Remote('create') create(request: WorkspaceCreateRequest): Promise<WorkspaceCreateValue>
-
-/**
- * Rename one Workspace to a unique non-blank title.
- * @param request - Workspace identity and proposed title.
- * @returns the updated Workspace projection.
- */
-@Remote('rename') rename(request: WorkspaceRenameRequest): Promise<WorkspaceValue>
-
-/**
- * Remove one Workspace registration while retaining files and Sessions.
- * @param request - Workspace identity to remove.
- * @returns deletion confirmation.
- */
-@Remote('delete') delete(request: WorkspaceDeleteRequest): Promise<WorkspaceDeleteValue>
-
-/**
- * Move one Workspace within the registry display order.
- * @param request - moved Workspace and optional anchor.
- * @returns the complete resulting Workspace order.
- */
-@Remote('insertBefore') insertBefore(request: WorkspaceInsertBeforeRequest): Promise<WorkspaceOrderValue>
-
-/**
- * Move one accounted Session within a Workspace.
- * @param request - Workspace, Session, and optional anchor identities.
- * @returns the updated Workspace projection.
- */
-@Remote('insertSessionBefore') insertSessionBefore(request: WorkspaceInsertSessionBeforeRequest): Promise<WorkspaceValue>
-
-/**
- * Hide one known Session from Workspace grouping surfaces.
- * @param request - Session identity to archive.
- * @returns the complete resulting archive set.
- */
-@Remote('archiveSession') archiveSession(request: WorkspaceArchiveSessionRequest): Promise<WorkspaceArchiveValue>
-
-/**
- * Stream a complete Workspace baseline followed by ordered increments.
- * @param signal - generation cancellation.
- * @returns baseline followed by ordered Workspace increments.
- */
-@Remote({ mode: 'stream' }) follow(signal: AbortSignal): AsyncIterable<WorkspaceFollowFrame>
-```
-
-Source: [`packages/api/workspace-controller/src/index.ts`](../../packages/api/workspace-controller/src/index.ts)
-
-<a id="ctxworkspaceregistry--workspaceregistry"></a>
-
-### `ctx.workspaceRegistry` — `WorkspaceRegistry`
-
-Durable workspace registry. Startup waits for `sessionPersistence`, builds one canonical-cwd header index, and completes the one-time history bootstrap before the service becomes active. The persistence dependency is mandatory so an unavailable peer can never be mistaken for an empty history and commit the initialized marker.
-
-```ts cordis-catalog
-/**
- * Create or reuse a workspace for an existing directory. The fully qualified
- * path is canonicalized through `fs.realpath`; a relative, nonexistent, or
- * non-directory path rejects. Repeated calls for the same canonical path
- * return the existing entity without changing its title.
- * A newly created workspace is prepended to the durable registry order.
- * Different canonical paths may share a display title.
- * @param path - Existing directory to own, in a fully qualified path spelling.
- * @param title - Display title used only when a new record is created.
- * @returns the existing or newly durable workspace.
- */
-async create(path: string, title?: string): Promise<Workspace>
-
-/**
- * Look up a workspace by id.
- * @param id - Workspace id.
- * @returns the workspace, or `undefined` when unknown.
- */
-get(id: WorkspaceId): Workspace | undefined
-
-/**
- * Synchronous workspace projection in durable registry order. Every
- * entity's `sessionIds` getter is already filtered by the startup/live
- * canonical-cwd header index; this method performs no persistence reads.
- * @returns a fresh ordered array of workspace entities.
- */
-list(): Workspace[]
-
-/**
- * Delete one workspace registration while retaining its directory and every
- * session log. The durable order is updated before the table deletion; a
- * failed table write restores the prior order and keeps the entity
- * published. Unknown ids are an idempotent no-op for domain callers.
- * @param id - Workspace registration to remove.
- * @returns `true` when a record was deleted, `false` when it was unknown.
- */
-delete(id: WorkspaceId): Promise<boolean>
-
-/**
- * Move one workspace within the durable display order, DOM-insertBefore-like.
- * With an anchor it lands before that workspace; without one it appends.
- * @param id - Workspace to move.
- * @param beforeId - Workspace anchor; omitted appends.
- * @returns the complete committed workspace order.
- */
-insertBefore(id: WorkspaceId, beforeId?: WorkspaceId): Promise<readonly WorkspaceId[]>
-
-/**
- * Archive one session durably. The session must exist (live or in session
- * persistence); its workspace accounting — or lack of one — is irrelevant.
- * An already archived id resolves without writing.
- * @param sessionId - The session to archive.
- * @returns resolution after durability.
- */
-archiveSession(sessionId: SessionId): Promise<void>
-
-/**
- * Resolve by canonical directory path without creating or mutating a
- * workspace. A missing path rejects during `realpath`; an existing unowned
- * directory returns `undefined`.
- * @param path - Existing directory path in a fully qualified spelling.
- * @returns the workspace owning the canonical path, when one exists.
- */
-async resolveByPath(path: string): Promise<Workspace | undefined>
-```
-
-Types: [SessionId](core.md)
-
-Source: [`packages/workspace/workspace/src/index.ts`](../../packages/workspace/workspace/src/index.ts)
-<!-- END GENERATED cordis-surface -->