super-dsh 0.3.0-a → 0.3.0-d

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

@@ -1,88 +0,0 @@
-# 运行时不变式
-
-[English](invariants.md) | 中文
-
-[dsh-invariants](../../packages/runtime-diagnostics/invariants) 是面向包自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定；注册表设计由[不变式服务 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md)规定。
-
-源码：[`packages/runtime-diagnostics/invariants/src/index.ts`](../../packages/runtime-diagnostics/invariants/src/index.ts)
-
-## 选择
-
-```ts type-equiv
-/** Runtime invariant selection configured on the service plugin. */
-interface Config {
-  /** Global switch; defaults to `true`. */
-  readonly enabled?: boolean
-  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
-  readonly package_allowlist?: string[]
-  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
-  readonly package_blocklist?: string[]
-}
-```
-
-一个包被选中的条件是：服务已启用，允许列表为空或至少一个模式匹配其完整 npm 名称，且没有任何阻止列表模式匹配；阻止列表匹配优先于允许列表匹配。条目用 `new RegExp(source)` 编译：除非模式自带 `^` 和 `$`，匹配不锚定；`/pattern/flags` 语法不被解析。校验在服务启动时明确报错：空白、首尾带空白、重复或无效的条目会抛出异常，而不是被跳过。有效模式可以不匹配任何当前已加载的包，因此后续加载与 HMR（热模块替换）保持确定性；过滤器在服务生命周期内固定不变（[README](../../packages/runtime-diagnostics/invariants/README.zh.md)）。
-
-## 安装器
-
-```ts type-equiv
-/**
- * Throw a package-attributed invariant failure.
- * @param message - violated package contract without the standard prefix.
- * @returns never because reporting a violation throws.
- */
-type InvariantFailure = (message: string) => never
-```
-
-```ts type-equiv
-/** Install one package's checks into the registration's child context. */
-interface InvariantInstaller {
-  /**
-   * Install the package contribution.
-   * @param ctx - child context owned by this invariant registration.
-   * @param fail - reporter bound to the registering package name.
-   * @returns nothing, or a promise settling after asynchronous checks finish.
-   */
-  (ctx: Context, fail: InvariantFailure): void | Promise<void>
-  /** Services the child installer fiber may access. */
-  readonly inject?: Inject
-}
-```
-
-被启用的安装器在专属的子 Cordis fiber 中运行；`installer.inject` 声明该 fiber 可以访问的服务，注册成功之前会先等待安装器同步或异步地执行完毕。`fail(message)` 抛出 `InvariantError`（`extends Error`，带稳定的 `code: 'INVARIANT'`、所属 `packageName`，以及前缀为 `invariant violated by "<package>": …` 的消息），因此违规可归因，而注册表无需导入任何产品包。
-
-## 服务
-
-`ctx.invariants.register(packageName, installer)` 为完整 npm 包名保留唯一一个活跃注册，并返回其绑定到 effect 的 disposer。即使过滤器使安装器保持不活跃，保留依然成立，因此两个插件绝不可能静默地认领同一个包名；重复、空白或含空白字符的名称会抛出异常。安装器失败会原子地 dispose（资源释放）子 fiber 并释放保留。服务拥有每个注册 fiber，而返回的 disposer 同时属于配套插件的 fiber：卸载任一侧都会移除监听器、trace 状态和保留项，因此配套插件可以重载并再次注册同一名称，不留残余状态。
-
-## 配套插件约定
-
-每个工作区包都拥有一个 `./invariant` 配套插件（[包约定](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但刻意不合成断言。只有当包拥有某个可观察事件或某种可变数据关系时，配套插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md)）。可执行配套插件的目录与标准组合方式见[包 README](../../packages/runtime-diagnostics/invariants/README.zh.md)。
-
-<!-- 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="ctxinvariants--invariantregistry"></a>
-
-### `ctx.invariants` — `InvariantRegistry`
-
-Package-owned invariant registry with global and regex-based selection.
-
-```ts cordis-catalog
-/**
- * Register one package's invariant installer. The package name is reserved
- * even when filtering disables its checks. Enabled installers run in a child
- * fiber; failure disposes that fiber and releases the reservation.
- * @param packageName - full npm package name that owns the contribution.
- * @param installer - listener or startup-check installer for the child context.
- * @returns an effect-scoped disposer for the registration.
- */
-register(packageName: string, installer: InvariantInstaller): () => void
-```
-
-Source: [`packages/runtime-diagnostics/invariants/src/index.ts`](../../packages/runtime-diagnostics/invariants/src/index.ts)
-<!-- END GENERATED cordis-surface -->

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

@@ -1,290 +0,0 @@
-# Background Task Runtime
-
-English | [中文](jobs.zh.md)
-
-Types shared by long-running producers, `ctx.jobs`, and job controls. The [runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) owns the design; this page records the exact fields and variants from [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts).
-
-## Ids and status
-
-`JobId` is a [branded id](core.md#branded-ids) generated as `<kind>-N`. Access control relies on owner authorization, not id secrecy. `JobKind` derives from a merge-extensible map; the registry treats kinds as opaque id namespaces.
-
-```ts type-equiv
-/**
- * Producer-defined job kinds. Plugins extend this map by declaration merging;
- * the registry treats every value as an opaque id namespace.
- */
-interface JobKindMap {
-  bash: 'bash'
-  subagent: 'subagent'
-}
-```
-
-`JobStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `JobSnapshot.detail`.
-
-## Producer contract
-
-`JobStart` declares identity and a starter. The runtime finishes preflight before calling `run()` and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state.
-
-```ts type-equiv
-/**
- * Producer declaration passed to {@link JobRegistry.start}. The runtime
- * preflights access and cleanup before invoking {@link run}; the producer owns
- * execution resources while the runtime owns identity and lifecycle state.
- */
-interface JobStart {
-  /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
-  kind: JobKind
-  /** One-line model-facing label (the command; the delegation description). */
-  label: string
-  /**
-   * Optional UTF-8 byte cap for each complete model-facing completion notice or
-   * output read, including controller status metadata.
-   */
-  outputLimitBytes?: number
-  /**
-   * Owning live agent. Access is fenced by its session id, and agent disposal
-   * cancels and awaits the job. The instance must be the one currently
-   * registered under its agent id. Omitting the owner creates an unowned job,
-   * open to any caller until service disposal.
-   */
-  owner?: Agent
-  /**
-   * Start the work after preflight and synchronously return its hooks. Called
-   * once; a throw leaves nothing registered, and the producer must clean up any
-   * partially started resources.
-   */
-  run(): JobHooks
-}
-```
-
-`JobHooks.done` resolves after the producer releases its resources, not merely when work finishes. Optional `readOutput` distinguishes consuming stream jobs from final-output-only jobs.
-
-```ts type-equiv
-/** Hooks through which the runtime controls and observes producer work. */
-interface JobHooks {
-  /**
-   * Request termination. Must be synchronous, idempotent, and eventually settle
-   * {@link done}; throws propagate. The optional reason is forwarded verbatim.
-   */
-  cancel(reason?: string): void
-  /**
-   * Resolves after the producer releases its resources, not merely when work
-   * finishes. Must not reject; the runtime converts a rejection to `failed`.
-   * If teardown cancellation throws, the runtime may force-fail only the
-   * registry record without claiming that the work stopped.
-   */
-  done: Promise<JobOutcome>
-  /**
-   * Consume output produced since the previous call. The producer formats
-   * truncation and spill notices. Absence marks a final-output-only job; each
-   * job has one consuming cursor.
-   */
-  readOutput?(): string
-}
-```
-
-```ts type-equiv
-/** Terminal result supplied by a producer through {@link JobHooks.done}. */
-interface JobOutcome {
-  /** How the job ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
-  status: 'completed' | 'killed' | 'failed'
-  /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
-  detail?: string
-  /** Final output for jobs without `readOutput`; stream jobs leave it unset. */
-  output?: string
-}
-```
-
-## Consumer views
-
-Snapshots are fresh read-only projections. `ownerSession` carries the shared `SessionId` used for authorization; completion listeners separately receive the exact owner object used for lifecycle cleanup. `reported` suppresses a completion notice after another reporter has delivered or committed to deliver the terminal state, including the teardown cancel that drains an owner or the service.
-
-```ts type-equiv
-/**
- * A read-only projection of one job, safe to hand to listeners and tools —
- * a fresh object per call, never live registry state.
- */
-interface JobSnapshot {
-  /** The registry-issued id (`<kind>-N`). */
-  id: JobId
-  /** The producer kind the job was registered with. */
-  kind: JobKind
-  /** The producer-supplied one-line label. */
-  label: string
-  /** Producer-owned cap for complete model-facing notices and output reads. */
-  outputLimitBytes?: number
-  /**
-   * Owner session id used for authorization and correlation; absent for
-   * unowned jobs. Completion listeners receive the exact {@link Agent}
-   * separately through {@link JobDoneListener}.
-   */
-  ownerSession?: SessionId
-  /** Current lifecycle state. */
-  status: JobStatus
-  /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
-  detail?: string
-  /** Epoch ms when the job was registered. */
-  startedAt: number
-  /** Epoch ms when the job settled; absent while `running`/`stopping`. */
-  finishedAt?: number
-  /**
-   * True when a kill, read, wait, or teardown cancel has reported or committed
-   * to report the terminal state. Completion reporters suppress redundant
-   * notices when set. Teardown claims it because the owner or service being
-   * destroyed leaves no reader: a reporter that opens a turn on notice would
-   * otherwise spend a model request per teardown layer.
-   */
-  reported: boolean
-}
-```
-
-```ts type-equiv
-/** Output and post-read state returned by {@link JobRegistry.read}. */
-interface JobRead {
-  /**
-   * Stream kinds: the consuming delta since the previous read. Final-output
-   * kinds: empty while live, the terminal {@link JobOutcome.output} (or
-   * empty) once settled — idempotent, never consumed.
-   */
-  text: string
-  /** The job's state at read time. */
-  snapshot: JobSnapshot
-}
-```
-
-## Service behavior
-
-The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, failure-isolated `onJobDone` and `onJobsChanged` listeners, and `attachController`; [`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) is the process-local Service Provider. Authorization compares owner sessions; owner cleanup and admission use the exact registered `Agent` instance. The local provider's positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10` and counts `running` plus `stopping` records per exact owner, with one shared bucket for unowned jobs; terminal producer settlement releases capacity. See [`dsh-jobs`](../../packages/jobs/jobs/README.md) for the Service Definition contract, [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md) for the registry lifecycle and admission policy, and [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md) for the model-facing Consumer.
-
-<!-- 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="ctxjobs--jobregistry-abstract-seam"></a>
-
-### `ctx.jobs` — `JobRegistry` (abstract seam)
-
-Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Implementations must honor these semantics:
-
-- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Teardown cancellation also marks the record reported, because a record its owner is being destroyed for has no reader left.
-- Owned-job access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
-- Settlement is first-wins: one terminal record, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously.
-- start refuses work while no attached job controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it.
-
-```ts cordis-catalog
-/**
- * Preflight access, validation, owner cleanup, and implementation-owned
- * admission before starting and atomically registering work. Any preflight
- * rejection leaves no job id or execution resource. A throwing starter
- * leaves nothing registered; after it returns, registration cannot fail.
- * Settlement records the outcome, notifies listeners, and releases waiters.
- * @param spec - job identity, owner, and synchronous starter.
- * @returns the registry-issued `<kind>-N` id.
- */
-abstract start(spec: JobStart): JobId
-
-/**
- * List caller-owned and unowned jobs in registration order without exposing
- * another session's labels.
- * @param caller - reading agent; a non-agent caller sees only unowned jobs.
- * @returns fresh snapshots.
- */
-abstract list(caller?: Agent): JobSnapshot[]
-
-/**
- * Return a non-consuming snapshot without changing its read cursor or notice
- * state. Throws for an unknown or foreign job.
- * @param id - job to look up.
- * @param caller - reading agent checked against the owner.
- * @returns a fresh snapshot.
- */
-abstract get(id: JobId, caller?: Agent): JobSnapshot
-
-/**
- * Read the next stream delta, or the idempotent final output after settlement.
- * A terminal read marks the job reported. Throws for an unknown or foreign
- * job.
- * @param id - job to read.
- * @param caller - reading agent checked against the owner.
- * @returns output text and the post-read snapshot.
- */
-abstract read(id: JobId, caller?: Agent): JobRead
-
-/**
- * Request cancellation, then mark the job stopping and reported. A producer
- * throw propagates without changing job state. Throws for an unknown or
- * foreign job.
- * @param id - job to cancel.
- * @param caller - killing agent checked against the owner.
- * @param reason - logged reason forwarded to the producer.
- * @returns `requested` for live work, otherwise `already-finished`.
- */
-abstract kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
-
-/**
- * Wait for settlement or timeout without cancelling the job. Caller abort
- * rejects only while the job is live; after settlement the terminal
- * snapshot wins so a notice suppressed for this waiter is still delivered.
- * Throws for invalid, unknown, or foreign input.
- * @param id - job to wait for.
- * @param timeoutMs - positive finite wait bound in milliseconds.
- * @param caller - waiting agent checked against the owner.
- * @param signal - optional cancellation of the wait itself.
- * @returns snapshot at settlement or timeout.
- */
-abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<JobSnapshot>
-
-/**
- * Register an effect-scoped completion listener. It receives the settlements
- * of the owners its registering context's scope covers; each listener is
- * contained; returned promises are observed but not awaited. No listener runs
- * after service disposal.
- * @param listener - receives each terminal snapshot and its exact owner.
- * @returns disposer that unregisters the listener.
- */
-abstract onJobDone(listener: JobDoneListener): () => void
-
-/**
-/**
- * Register an effect-scoped observer of visible-set changes. It fires after
- * every commit that changes what {@link list} returns for that owner —
- * registration, every stopping transition (including the one teardown
- * performs before it awaits a slow producer), settlement, owner-disposal
- * removal, and the emptying that service disposal commits — so an observer
- * re-reads rather than accumulating deltas.
- *
- * Delivery is owner-relative on the same terms as {@link onJobDone}: an
- * observer registered from an unscoped context — a host composition's own
- * carrier — sees every owner, while one registered under an agent
- * composition's scope sees exactly the agents composed under it.
- *
- * This is not a superset of {@link onJobDone}: that one delivers the terminal
- * record under first-wins semantics a job controller couples to notice
- * delivery, while this one carries no delivery meaning and marks nothing
- * reported. Listeners are contained and never awaited.
- * @param listener - receives the owner whose visible set changed, or
- *   `undefined` when an unowned job changed and every caller's set did.
- * @returns disposer that unregisters the listener.
- */
-abstract onJobsChanged(listener: JobsChangedListener): () => void
-
-/**
- * Attach an effect-scoped controller that can read and stop jobs. It serves the
- * owners its registering context's scope covers, and {@link start} refuses an
- * owner no attached controller serves.
- * @param name - diagnostic label; duplicate names remain independent.
- * @returns disposer that detaches this controller.
- */
-abstract attachController(name: string): () => void
-```
-
-Types: [Agent](core.md)
-
-Source: [`packages/jobs/jobs/src/index.ts`](../../packages/jobs/jobs/src/index.ts)
-<!-- END GENERATED cordis-surface -->

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

@@ -1,290 +0,0 @@
-# 后台任务运行时
-
-[English](jobs.md) | 中文
-
-长时间运行的生产方、`ctx.jobs` 与任务控制命令共用的类型。[运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md) 负责设计；本页记录 [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts) 中的确切字段和变体。
-
-## ID 与状态
-
-`JobId` 是按 `<kind>-N` 生成的[品牌化 id](core.zh.md#branded-ids)。访问控制依赖拥有者授权，而非 id 的保密性。`JobKind` 派生自可合并扩展的 map；注册表将各个 kind 视为不透明的 id 命名空间。
-
-```ts type-equiv
-/**
- * Producer-defined job kinds. Plugins extend this map by declaration merging;
- * the registry treats every value as an opaque id namespace.
- */
-interface JobKindMap {
-  bash: 'bash'
-  subagent: 'subagent'
-}
-```
-
-`JobStatus` 为 `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`；生产方特有的事实归入 `JobSnapshot.detail`。
-
-## 生产方约定
-
-`JobStart` 声明身份和启动器。运行时会在调用 `run()` 前完成预检，随后提交注册，不再执行可能失败的步骤。生产方拥有执行资源；运行时拥有身份、访问权限和生命周期状态。
-
-```ts type-equiv
-/**
- * Producer declaration passed to {@link JobRegistry.start}. The runtime
- * preflights access and cleanup before invoking {@link run}; the producer owns
- * execution resources while the runtime owns identity and lifecycle state.
- */
-interface JobStart {
-  /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
-  kind: JobKind
-  /** One-line model-facing label (the command; the delegation description). */
-  label: string
-  /**
-   * Optional UTF-8 byte cap for each complete model-facing completion notice or
-   * output read, including controller status metadata.
-   */
-  outputLimitBytes?: number
-  /**
-   * Owning live agent. Access is fenced by its session id, and agent disposal
-   * cancels and awaits the job. The instance must be the one currently
-   * registered under its agent id. Omitting the owner creates an unowned job,
-   * open to any caller until service disposal.
-   */
-  owner?: Agent
-  /**
-   * Start the work after preflight and synchronously return its hooks. Called
-   * once; a throw leaves nothing registered, and the producer must clean up any
-   * partially started resources.
-   */
-  run(): JobHooks
-}
-```
-
-`JobHooks.done` 会在生产方释放其资源后 resolve，而不是仅在工作完成时 resolve。可选的 `readOutput` 用来区分会消费输出的流式任务和仅有最终输出的任务。
-
-```ts type-equiv
-/** Hooks through which the runtime controls and observes producer work. */
-interface JobHooks {
-  /**
-   * Request termination. Must be synchronous, idempotent, and eventually settle
-   * {@link done}; throws propagate. The optional reason is forwarded verbatim.
-   */
-  cancel(reason?: string): void
-  /**
-   * Resolves after the producer releases its resources, not merely when work
-   * finishes. Must not reject; the runtime converts a rejection to `failed`.
-   * If teardown cancellation throws, the runtime may force-fail only the
-   * registry record without claiming that the work stopped.
-   */
-  done: Promise<JobOutcome>
-  /**
-   * Consume output produced since the previous call. The producer formats
-   * truncation and spill notices. Absence marks a final-output-only job; each
-   * job has one consuming cursor.
-   */
-  readOutput?(): string
-}
-```
-
-```ts type-equiv
-/** Terminal result supplied by a producer through {@link JobHooks.done}. */
-interface JobOutcome {
-  /** How the job ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
-  status: 'completed' | 'killed' | 'failed'
-  /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
-  detail?: string
-  /** Final output for jobs without `readOutput`; stream jobs leave it unset. */
-  output?: string
-}
-```
-
-## 消费方视图
-
-快照是每次新建的只读投影。`ownerSession` 携带用于授权的共享 `SessionId`；完成监听器则会另行收到用于生命周期清理的确切拥有者对象。另一个接口已经交付终止状态或承诺交付时，`reported` 会抑制完成通知；排空 owner 或服务的 teardown 取消同样计入。
-
-```ts type-equiv
-/**
- * A read-only projection of one job, safe to hand to listeners and tools —
- * a fresh object per call, never live registry state.
- */
-interface JobSnapshot {
-  /** The registry-issued id (`<kind>-N`). */
-  id: JobId
-  /** The producer kind the job was registered with. */
-  kind: JobKind
-  /** The producer-supplied one-line label. */
-  label: string
-  /** Producer-owned cap for complete model-facing notices and output reads. */
-  outputLimitBytes?: number
-  /**
-   * Owner session id used for authorization and correlation; absent for
-   * unowned jobs. Completion listeners receive the exact {@link Agent}
-   * separately through {@link JobDoneListener}.
-   */
-  ownerSession?: SessionId
-  /** Current lifecycle state. */
-  status: JobStatus
-  /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
-  detail?: string
-  /** Epoch ms when the job was registered. */
-  startedAt: number
-  /** Epoch ms when the job settled; absent while `running`/`stopping`. */
-  finishedAt?: number
-  /**
-   * True when a kill, read, wait, or teardown cancel has reported or committed
-   * to report the terminal state. Completion reporters suppress redundant
-   * notices when set. Teardown claims it because the owner or service being
-   * destroyed leaves no reader: a reporter that opens a turn on notice would
-   * otherwise spend a model request per teardown layer.
-   */
-  reported: boolean
-}
-```
-
-```ts type-equiv
-/** Output and post-read state returned by {@link JobRegistry.read}. */
-interface JobRead {
-  /**
-   * Stream kinds: the consuming delta since the previous read. Final-output
-   * kinds: empty while live, the terminal {@link JobOutcome.output} (or
-   * empty) once settled — idempotent, never consumed.
-   */
-  text: string
-  /** The job's state at read time. */
-  snapshot: JobSnapshot
-}
-```
-
-## 服务行为
-
-抽象的 [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition 规定原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onJobDone` 与 `onJobsChanged` 监听器，以及 `attachController`；[`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) 是其进程局部 Service Provider。授权会比较拥有者会话；拥有者清理与准入会使用确切的已注册 `Agent` 实例。本地 Service Provider 的 `maxConcurrentJobsPerOwner` 配置必须是正的安全整数，默认值为 `10`；它按确切 owner 统计 `running` 与 `stopping` 记录，所有无 owner 任务共享一个服务级桶，并在生产方终止结算后释放容量。Service Definition 约定见 [`dsh-jobs`](../../packages/jobs/jobs/README.zh.md)，注册表生命周期与准入策略见 [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.zh.md)，面向模型的 Consumer 见 [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.zh.md)。
-
-<!-- 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="ctxjobs--jobregistry-abstract-seam"></a>
-
-### `ctx.jobs` — `JobRegistry` (abstract seam)
-
-Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
-
-Implementations must honor these semantics:
-
-- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Teardown cancellation also marks the record reported, because a record its owner is being destroyed for has no reader left.
-- Owned-job access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
-- Settlement is first-wins: one terminal record, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously.
-- start refuses work while no attached job controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it.
-
-```ts cordis-catalog
-/**
- * Preflight access, validation, owner cleanup, and implementation-owned
- * admission before starting and atomically registering work. Any preflight
- * rejection leaves no job id or execution resource. A throwing starter
- * leaves nothing registered; after it returns, registration cannot fail.
- * Settlement records the outcome, notifies listeners, and releases waiters.
- * @param spec - job identity, owner, and synchronous starter.
- * @returns the registry-issued `<kind>-N` id.
- */
-abstract start(spec: JobStart): JobId
-
-/**
- * List caller-owned and unowned jobs in registration order without exposing
- * another session's labels.
- * @param caller - reading agent; a non-agent caller sees only unowned jobs.
- * @returns fresh snapshots.
- */
-abstract list(caller?: Agent): JobSnapshot[]
-
-/**
- * Return a non-consuming snapshot without changing its read cursor or notice
- * state. Throws for an unknown or foreign job.
- * @param id - job to look up.
- * @param caller - reading agent checked against the owner.
- * @returns a fresh snapshot.
- */
-abstract get(id: JobId, caller?: Agent): JobSnapshot
-
-/**
- * Read the next stream delta, or the idempotent final output after settlement.
- * A terminal read marks the job reported. Throws for an unknown or foreign
- * job.
- * @param id - job to read.
- * @param caller - reading agent checked against the owner.
- * @returns output text and the post-read snapshot.
- */
-abstract read(id: JobId, caller?: Agent): JobRead
-
-/**
- * Request cancellation, then mark the job stopping and reported. A producer
- * throw propagates without changing job state. Throws for an unknown or
- * foreign job.
- * @param id - job to cancel.
- * @param caller - killing agent checked against the owner.
- * @param reason - logged reason forwarded to the producer.
- * @returns `requested` for live work, otherwise `already-finished`.
- */
-abstract kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
-
-/**
- * Wait for settlement or timeout without cancelling the job. Caller abort
- * rejects only while the job is live; after settlement the terminal
- * snapshot wins so a notice suppressed for this waiter is still delivered.
- * Throws for invalid, unknown, or foreign input.
- * @param id - job to wait for.
- * @param timeoutMs - positive finite wait bound in milliseconds.
- * @param caller - waiting agent checked against the owner.
- * @param signal - optional cancellation of the wait itself.
- * @returns snapshot at settlement or timeout.
- */
-abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<JobSnapshot>
-
-/**
- * Register an effect-scoped completion listener. It receives the settlements
- * of the owners its registering context's scope covers; each listener is
- * contained; returned promises are observed but not awaited. No listener runs
- * after service disposal.
- * @param listener - receives each terminal snapshot and its exact owner.
- * @returns disposer that unregisters the listener.
- */
-abstract onJobDone(listener: JobDoneListener): () => void
-
-/**
-/**
- * Register an effect-scoped observer of visible-set changes. It fires after
- * every commit that changes what {@link list} returns for that owner —
- * registration, every stopping transition (including the one teardown
- * performs before it awaits a slow producer), settlement, owner-disposal
- * removal, and the emptying that service disposal commits — so an observer
- * re-reads rather than accumulating deltas.
- *
- * Delivery is owner-relative on the same terms as {@link onJobDone}: an
- * observer registered from an unscoped context — a host composition's own
- * carrier — sees every owner, while one registered under an agent
- * composition's scope sees exactly the agents composed under it.
- *
- * This is not a superset of {@link onJobDone}: that one delivers the terminal
- * record under first-wins semantics a job controller couples to notice
- * delivery, while this one carries no delivery meaning and marks nothing
- * reported. Listeners are contained and never awaited.
- * @param listener - receives the owner whose visible set changed, or
- *   `undefined` when an unowned job changed and every caller's set did.
- * @returns disposer that unregisters the listener.
- */
-abstract onJobsChanged(listener: JobsChangedListener): () => void
-
-/**
- * Attach an effect-scoped controller that can read and stop jobs. It serves the
- * owners its registering context's scope covers, and {@link start} refuses an
- * owner no attached controller serves.
- * @param name - diagnostic label; duplicate names remain independent.
- * @returns disposer that detaches this controller.
- */
-abstract attachController(name: string): () => void
-```
-
-Types: [Agent](core.zh.md)
-
-Source: [`packages/jobs/jobs/src/index.ts`](../../packages/jobs/jobs/src/index.ts)
-<!-- END GENERATED cordis-surface -->