dsh-plugin-dev-kb 1.3.0 → 1.5.1

package/kb/site/reference/subsystems/jobs.md

@@ -1,15 +1,16 @@
 ---
 editSource: "docs/subsystems/jobs.zh.md"
+rawMarkdownPath: "reference/subsystems/jobs.md"
 outline: [2,3]
 ---
 
 # 后台任务运行时
 
-长时间运行的生产方、`ctx.jobs` 与任务控制命令共用的类型。[运行时 Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md) 负责设计；本页记录 [`packages/jobs/jobs/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs/src/types.ts) 中的确切字段和变体。
+长时间运行的生产方、`ctx.jobs` 与任务控制命令共用的类型。[seam 收敛 Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md) 负责当前设计，[运行时 reference](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs/README.zh.md) 记录其起源；本页记录 [`packages/jobs/jobs/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs/src/types.ts) 与客户端安全叶子 [`view.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs/src/view.ts) 中的确切字段与变体。
 
 ## ID 与状态
 
-`JobId` 是按 `<kind>-N` 生成的[品牌化 id](./core.md#branded-ids)。访问控制依赖拥有者授权，而非 id 的保密性。`JobKind` 派生自可合并扩展的 map；注册表将各个 kind 视为不透明的 id 命名空间。
+`JobId` 是按 `<kind>-<short-uuid>` 生成的[品牌化 id](./core.md#branded-ids)，kind 后是 UUID 的 16 位小写十六进制字符。访问控制依赖拥有者授权，而非 id 的保密性。`JobKind` 派生自可合并扩展的 map；注册表将各个 kind 视为不透明的 id 命名空间。
 
 ```ts type-equiv
 /**
@@ -18,49 +19,142 @@ outline: [2,3]
  */
 interface JobKindMap {
   bash: 'bash'
-  subagent: 'subagent'
 }
 ```
 
-`JobStatus` 为 `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`；生产方特有的事实归入 `JobSnapshot.detail`。
+`JobStatus` 为 `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`；生产方特有的事实在运行期间归入 `JobView.progress`，结算后归入 `JobView.detail`。
+
+<a id="session-lifecycle-records"></a>
+
+## Session 生命周期记录
+
+有所有者的 job 在原始所有者 Session 中发布 `job/registered` 与 `job/settled`。全局唯一的 `jobId` 同时配对这两条记录并控制运行中的 job。SDK 通过 `session.event` 转发这些仅日志记录，不依赖输出读取。时间戳描述注册表提交时刻，不是 CPU 时间或精确的 OS 进程边界；缺少结算时保持不完整。`producerReported` 表示生产方通过兑现 `done` 报告了终态；强制销毁或 promise 拒绝时为 false，不独立确认资源已释放。
+
+`job/settled` 可能出现在 `turn/end` 之后。SDK run 结果只覆盖自身观测窗口；需要较晚结算的消费方应保留 Session 订阅或读取持久化历史。轮次完成不表示所有有主 job 都已停止。
+
+应用销毁可能在有主 job 的最后一条结算写入存储前停止 Session 事件路由或关闭写句柄。正常的一次性运行结束、信号关停和进程硬退出都可能出现这种情况。即使运行期注册表报告了终止，缺少 `job/settled` 的区间仍不完整；消费方不得虚构结束时间戳。
+
+```ts type-equiv
+/** Durable identity and registration time of one owned job execution. */
+interface JobRegisteredData {
+  /** Unique execution id accepted by job controls and retained in Session history. */
+  readonly jobId: JobId
+  /** Original owner; copied history does not transfer execution ownership. */
+  readonly owner: SessionId
+  /** Producer kind. */
+  readonly kind: string
+  /** Producer-supplied label. */
+  readonly label: string
+  /** Unix epoch milliseconds when registration committed. */
+  readonly startedAt: number
+  /** Creating tool invocation, when the producer was called through a tool. */
+  readonly toolCall?: JobToolCall
+}
+```
+
+```ts type-equiv
+/** Registry settlement, including whether the producer reported a terminal outcome. */
+interface JobSettledData extends JobRegisteredData {
+  /** Unix epoch milliseconds when the registry committed the terminal record. */
+  readonly finishedAt: number
+  /** Recorded terminal outcome. */
+  readonly status: JobOutcome['status']
+  /** Source of the termination request, or producer completion. */
+  readonly cause: JobSettleCause
+  /** True when done fulfilled; false for rejection or forced failure. Does not certify resource release. */
+  readonly producerReported: boolean
+  /** Terminal reason, including a recorded kill reason when applicable. */
+  readonly detail?: string
+}
+```
 
 ## 生产方约定
 
-`JobStart` 声明身份和启动器。运行时会在调用 `run()` 前完成预检，随后提交注册，不再执行可能失败的步骤。生产方拥有执行资源；运行时拥有身份、访问权限和生命周期状态。
+`JobSpec` 声明身份、拥有者会话、可选的拉取式 `output` 源与启动器。运行时会在完成预检后携带该 job 的 `JobHandle` 调用 `run()`，随后提交注册，不再执行可能失败的步骤。生产方拥有执行资源；运行时拥有身份、访问、生命周期状态与输出环。
+
+```ts type-equiv
+/** Tool dispatch that created a job; nested calls retain their root invocation. */
+interface JobToolCall {
+  /** Exact invocation, including a PTC sub-call when applicable. */
+  readonly callId: SessionEventMap['tool/call']['callId']
+  /** Root model-requested invocation owning this execution. */
+  readonly rootCallId: SessionEventMap['tool/call']['callId']
+}
+```
 
 ```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.
+ * execution resources while the runtime owns identity, lifecycle state, and
+ * the output ring.
  */
-interface JobStart {
-  /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
+interface JobSpec {
+  /** Producer kind — also the id prefix (`bash`, …). */
   kind: JobKind
   /** One-line model-facing label (the command; the delegation description). */
   label: string
+  /**
+   * Owning session. Access is fenced by it, and the owner's live Agent must be
+   * the one currently registered under that id: its disposal cancels and
+   * awaits the job. Omitting the owner creates an unowned job, open to any
+   * caller until service disposal.
+   */
+  owner?: SessionId
+  /** Creating tool invocation, retained in the durable lifecycle records. */
+  toolCall?: JobToolCall
   /**
    * Optional UTF-8 byte cap for each complete model-facing completion notice or
-   * output read, including controller status metadata.
+   * output read, including controller status metadata. Independent of ring
+   * retention: it bounds the consuming model surface, never observers.
    */
   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.
+   * Pull sources the registry pumps into the ring at its own cadence.
+   * Producers that narrate their own progress use {@link JobHandle.append}
+   * instead; a job may use both.
    */
-  owner?: Agent
+  output?: readonly JobOutputSource[]
   /**
    * 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.
+   * once with the job's producer face; a throw leaves nothing registered (the
+   * spent ordinal is skipped), and the producer must clean up any partially
+   * started resources.
+   * @param job - the issued id plus the ring append and progress writers.
+   */
+  run(job: JobHandle): JobHooks
+}
+```
+
+```ts type-equiv
+/**
+ * Producer face of one registered job, handed to {@link JobSpec.run} and
+ * valid for the job's whole life. All methods are synchronous. Writes staged
+ * inside the starter call are retained and become visible with the
+ * registration commit; after settlement — the producer's own outcome, a kill,
+ * or a registry-forced teardown end — writes log and drop instead of
+ * throwing, so a producer's trailing flush cannot break its own teardown path.
+ */
+interface JobHandle {
+  /** The registry-issued id (`<kind>-<short-uuid>`). */
+  readonly id: JobId
+  /**
+   * Append one chunk to the output ring. Offsets advance by the chunk's UTF-8
+   * byte length; an empty chunk is dropped without waking observers.
+   * @param text - the chunk text, exactly as produced.
+   * @param options - stream label and gap marker.
+   */
+  append(text: string, options?: JobAppendOptions): void
+  /**
+   * Replace the live progress line (`3/10`, the current phase). Settlement
+   * clears it; the terminal reason travels in {@link JobOutcome.detail}.
+   * @param line - the new progress line.
    */
-  run(): JobHooks
+  updateProgress(line: string): void
 }
 ```
 
-`JobHooks.done` 会在生产方释放其资源后 resolve，而不是仅在工作完成时 resolve。可选的 `readOutput` 用来区分会消费输出的流式任务和仅有最终输出的任务。
+`JobHooks.done` 会在生产方释放其资源后 resolve，而不是仅在工作完成时 resolve。结果是一个值而非流的 job——workflow 渲染出的结果——把它作为 `JobOutcome.result` 返回；模型在结算后的第一次读取携带它一次。
 
 ```ts type-equiv
 /** Hooks through which the runtime controls and observes producer work. */
@@ -77,12 +171,6 @@ interface JobHooks {
    * 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
 }
 ```
 
@@ -91,73 +179,215 @@ interface JobHooks {
 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'). */
+  /**
+   * Terminal reason rendered into status lines (`exit code: 3`, `max-tokens`).
+   * When the job settles `killed` after a {@link JobRegistry.kill} with a
+   * reason, the registry appends that reason.
+   */
   detail?: string
-  /** Final output for jobs without `readOutput`; stream jobs leave it unset. */
-  output?: string
+  /**
+   * Return value for jobs whose result is a value rather than a stream (a
+   * workflow's rendered result, a subagent's report). The output ring carries
+   * the stream; this is handed out once by the model's next {@link JobRegistry.read}.
+   */
+  result?: string
+}
+```
+
+拉取源把一个非消耗的偏移读取器——子进程的 `readFrom` 家族——交给注册表。注册表按自己的节奏（`dsh-jobs-local` 的 `pumpPollMs`）泵送每个源，并在结算封环之前再排干一次，因此生产方不需要把任何东西折进 `done`。
+
+```ts type-equiv
+/**
+ * A pull source the registry pumps into the job's output ring — the subprocess
+ * `readFrom` family. The registry owns the cadence and drains every source one
+ * last time before settlement closes the ring, so a producer folds nothing
+ * into its `done`.
+ */
+interface JobOutputSource {
+  /** Stream label attached to every chunk this source yields. */
+  channel?: JobChannel
+  /**
+   * Read everything captured since `fromByte` without consuming it.
+   * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first).
+   * @returns the delta text, the next offset, the lossy flag, and the spill path the source currently keeps.
+   */
+  read(fromByte: number): JobSourceRead
+}
+```
+
+```ts type-equiv
+/** One incremental read from a {@link JobOutputSource}. */
+interface JobSourceRead {
+  /** Text captured since the requested offset (the whole retained tail when lossy). */
+  text: string
+  /** Whole-stream offset to resume from on the next read. */
+  nextOffset: number
+  /** True when the requested offset slid out of the source's retained window. */
+  lossy: boolean
+  /**
+   * Host path of a file holding the complete stream, when the source
+   * currently keeps an intact one. Reported on every read, so the registry
+   * tracks it as source metadata: a later read without it withdraws the file.
+   */
+  spillPath?: string
+}
+```
+
+## 输出环
+
+每个 job 拥有一个有界的环。拉取源被泵入其中，`JobHandle.append` 的推送整块落地；模型通过注册表保管的游标（`JobRegistry.read`）消耗该环，任意数量的观察者按绝对字节偏移读取它（`JobRegistry.readAt`），二者互不干扰。`JobChannel` 标记 `stdout`、`stderr` 与 `log`；`log` 是只到达观察者、从不进入模型消耗式读取的生产方叙述。结算即封流并把保留量裁剪到结算上限——环没有独立的生命周期。拉取源保留的 spill 文件是 job 元数据（`JobView.output.spillPaths`，每次泵读取都会刷新），不是逐块元数据，所以环淘汰了字节之后、甚至缺口 chunk 本身也被淘汰之后，模型的丢失输出提示仍能点名该文件。浏览器通过 [`dsh-api-job-controller`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/api/job-controller/README.zh.md) 的 Remote 流 `job.list` 与 `job.follow` 触达名册与环，其帧列于下文的 Cordis API 一节。
+
+```ts type-equiv
+/** One chunk of a job's output ring: absolute offset, text, channel, and loss marker. */
+interface JobChunk {
+  /** Absolute offset of the chunk's first byte; offsets never move once assigned. */
+  readonly at: number
+  /** Chunk text exactly as appended (possibly tail-trimmed by retention). */
+  readonly text: string
+  /** Stream label, when the producer supplied one. */
+  readonly channel?: JobChannel
+  /** Bytes immediately before this chunk were lost, at the producer or to retention. */
+  readonly gapBefore?: true
+}
+```
+
+```ts type-equiv
+/** Result of one non-consuming {@link JobRegistry.readAt}. */
+interface JobOutputRead {
+  /** Retained chunks overlapping `[from, total)`, in offset order. */
+  chunks: readonly JobChunk[]
+  /**
+   * Offset to resume from — the ring's current `total`. Always a chunk
+   * boundary: appends land whole and trimming only advances chunk starts, and
+   * consumers concatenate `chunks` under that assumption, so a provider
+   * serving partial chunks would silently duplicate text.
+   */
+  next: number
+  /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */
+  lossy: boolean
 }
 ```
 
 ## 消费方视图
 
-快照是每次新建的只读投影。`ownerSession` 携带用于授权的共享 `SessionId`；完成监听器则会另行收到用于生命周期清理的确切拥有者对象。另一个接口已经交付终止状态或承诺交付时，`reported` 会抑制完成通知；排空 owner 或服务的 teardown 取消同样计入。
+`JobView` 是每个读者都消费的唯一投影：模型工具、浏览器名册与观测流。`owner` 携带划定访问边界的会话 id；注册表为生命周期清理解析其背后的活体 `Agent`，从不把该对象交出去。`progress` 是生产方的实时行，结算时清除；`detail` 是终态原因，合并了记录下来的 kill 原因。
 
 ```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.
+ * Read-only projection of one job — a fresh object per call, never live
+ * registry state. The model tools, the browser roster, and the observation
+ * stream all consume this one shape.
  */
-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
+interface JobView {
+  /** The registry-issued id (`<kind>-<short-uuid>`). */
+  readonly id: JobId
   /**
-   * Owner session id used for authorization and correlation; absent for
-   * unowned jobs. Completion listeners receive the exact {@link Agent}
-   * separately through {@link JobDoneListener}.
+   * The producer kind the job was registered with: a Host-registered
+   * `JobKind`, carried as an open string because a browser bundle or a Remote
+   * codec sees only the `JobKindMap` merges its own program compiles.
    */
-  ownerSession?: SessionId
+  readonly kind: string
+  /** The producer-supplied one-line label. */
+  readonly label: string
+  /** Owning session; absent for an unowned job, which every caller can see. */
+  readonly owner?: SessionId
+  /** Producer-owned cap for complete model-facing notices and reads, in UTF-8 bytes. */
+  readonly outputLimitBytes?: number
   /** Current lifecycle state. */
-  status: JobStatus
-  /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
-  detail?: string
+  readonly status: JobStatus
+  /** The producer's live progress line (`3/10`, the current phase); cleared at settlement. */
+  readonly progress?: string
+  /** Terminal reason (`exit code: 3`); a recorded kill reason is merged in. */
+  readonly detail?: string
   /** Epoch ms when the job was registered. */
-  startedAt: number
-  /** Epoch ms when the job settled; absent while `running`/`stopping`. */
-  finishedAt?: number
+  readonly startedAt: number
+  /** Epoch ms when the job settled; absent while live. */
+  readonly 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.
+   * The output ring's absolute coordinates and the complete-stream files
+   * behind it. `total` is the offset the next chunk starts at (0 while
+   * nothing was written); `earliest` is the oldest retained byte, greater
+   * than zero exactly when retention dropped the head. `spillPaths` lists the
+   * spill files the job's pull sources currently keep, in source order and
+   * deduplicated, and is absent while no source keeps one: it outlives any
+   * chunk, so a reader below `earliest` can still name where the bytes went.
    */
-  reported: boolean
+  readonly output: { readonly total: number; readonly earliest: number; readonly spillPaths?: readonly string[] }
 }
 ```
 
+`JobRegistry` 的 `list`、`get`、`read`、`readAt`、`kill` 和 `wait` 各自接收调用方的 `SessionId`；省略调用方时仅可访问无主 job，传入会话时还可访问该会话拥有的 job。
+
 ```ts type-equiv
-/** Output and post-read state returned by {@link JobRegistry.read}. */
+/** Output and post-read state returned by the consuming {@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
+  /** Ring chunks appended since the model cursor, in offset order; every channel included. */
+  chunks: readonly JobChunk[]
+  /** True when the cursor fell below the oldest retained byte, so bytes are missing before `chunks`. */
+  lossy: boolean
+  /** The producer's {@link JobOutcome.result}, handed out by the first read after settlement only. */
+  result?: string
   /** The job's state at read time. */
-  snapshot: JobSnapshot
+  job: JobView
 }
 ```
 
+## 事件
+
+注册表通过一条带过滤的流宣布每次提交。生命周期事件携带其所宣布的提交之后的投影；`settled` 标出原因，完成播报方据此跳过 teardown；`output` 只携带 id 与新的 total，观察者从自己的游标读取，注册表从不推送负载。
+
+```ts type-equiv
+/**
+ * One lifecycle or output event. Lifecycle events carry the job's projection
+ * after the commit they announce; `output` carries only the id and the new
+ * total, so an observer schedules a {@link JobRegistry.readAt} from its own
+ * cursor and the registry never pushes payloads.
+ */
+type JobEvent =
+  | {
+    /** Registration commit, progress line change, stopping transition, or removal from the visible set. */
+    readonly type: 'registered' | 'progress' | 'stopping' | 'removed'
+    readonly job: JobView
+  }
+  | {
+    readonly type: 'settled'
+    readonly job: JobView
+    readonly cause: JobSettleCause
+    /**
+     * Whether this settlement released a live {@link JobRegistry.wait}. That
+     * waiter's caller receives the terminal projection as its own result, so
+     * a completion reporter treats an awaited settlement as already delivered
+     * and reports only the unawaited ones. A wait that timed out or was
+     * aborted before the settlement does not count.
+     */
+    readonly awaited: boolean
+  }
+  | {
+    readonly type: 'output'
+    readonly id: JobId
+    /** Owning session, absent for an unowned job. */
+    readonly owner?: SessionId
+    /** The ring's total after the append (or at settlement, which ends the stream). */
+    readonly total: number
+  }
+```
+
+```ts type-equiv
+/**
+ * Who a subscription hears about. `{ owner }` delivers that session's jobs
+ * plus every unowned job (the set that session can see). `{ owners: 'scope' }`
+ * delivers the owners composed under the subscribing context — one registry
+ * serves every composition in the process, and a mount under one preset must
+ * not hear another preset's agents. `{ owners: 'all' }` delivers everything.
+ */
+type JobEventFilter =
+  | { readonly owner: SessionId }
+  | { readonly owners: 'all' | 'scope' }
+```
+
 ## 服务行为
 
-抽象的 [`JobRegistry`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs/src/index.ts) Service Definition 规定原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onJobDone` 与 `onJobsChanged` 监听器，以及 `attachController`；[`LocalJobRegistry`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs-local/src/index.ts) 是其进程局部 Service Provider。授权会比较拥有者会话；拥有者清理与准入会使用确切的已注册 `Agent` 实例。本地 Service Provider 的 `maxConcurrentJobsPerOwner` 配置必须是正的安全整数，默认值为 `10`；它按确切 owner 统计 `running` 与 `stopping` 记录，所有无 owner 任务共享一个服务级桶，并在生产方终止结算后释放容量。Service Definition 约定见 [`dsh-jobs`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs/README.zh.md)，注册表生命周期与准入策略见 [`dsh-jobs-local`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs-local/README.zh.md)，面向模型的 Consumer 见 [`dsh-tool-jobs`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/tool-jobs/README.zh.md)。
+抽象的 [`JobRegistry`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs/src/index.ts) Service Definition 规定了原子化的 `start`、各自接收调用方的 `list`、`get`、消耗式 `read`、非消耗的 `readAt`、`kill` 与有界的 `wait`、带过滤的 `events` 流，以及 `attachController`；[`LocalJobRegistry`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs-local/src/index.ts) 是进程本地的 Service Provider。授权比较拥有者会话；拥有者清理与准入使用 job 启动时登记在该拥有者会话下的活体 `Agent`。本地提供方的正安全整数配置 `maxConcurrentJobsPerOwner` 默认为 `10`，按精确拥有者统计 `running` 加 `stopping` 记录，无主任务共享一个桶；生产方的终态结算释放容量；`retainBytes`（默认 262144）与 `settledRetainBytes`（默认 16384）约束每个环的运行期与结算后保留量，`pumpPollMs`（默认 150）是拉取节奏。参见 [`dsh-jobs`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs/README.zh.md) 了解 Service Definition 约定，[`dsh-jobs-local`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs-local/README.zh.md) 了解注册表生命周期与准入策略，[`dsh-tool-jobs`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/tool-jobs/README.zh.md) 了解面向模型的 Consumer。
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -167,18 +397,66 @@ interface JobRead {
 
 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="ctxjobcontroller--jobcontroller"></a>
+
+### `ctx.jobController` — `JobController`
+
+Host service backing the generated `ctx.remote.job` namespace.
+
+```ts cordis-catalog
+/**
+ * Stream the jobs one session can see — its own plus every unowned job —
+ * as whole-set frames: one on open, then one after each coalesced burst of
+ * lifecycle commits. The stream has no natural end; the carrier closes it.
+ * @param request - the session whose visible set to mirror.
+ * @param signal - cancellation owned by the Remote stream carrier.
+ * @returns the roster frames.
+ */
+@Remote({ mode: 'stream' }) list(request: JobListRequest, signal: AbortSignal): AsyncIterable<JobListFrame>
+
+/**
+ * Stream one job's retained output from an absolute byte offset, then its
+ * terminal projection once settled and drained. Non-consuming: the
+ * model-facing cursor and notice state never observe these reads. The
+ * request's session is the fenced read's caller; the registry rejects a
+ * job the session cannot see and an unknown job.
+ * @param request - target job, owning session, and optional resume offset.
+ * @param signal - cancellation owned by the Remote stream carrier.
+ * @returns anchor, coalesced output frames, and the terminal status.
+ */
+@Remote({ mode: 'stream' }) follow(request: JobFollowRequest, signal: AbortSignal): AsyncIterable<JobFollowFrame>
+
+/**
+ * Kill one background job on a human's behalf. The request's session is
+ * the fenced read's caller, so the job must be one that session can see:
+ * the registry's owner fence is the only access rule, and a child session's
+ * own jobs are killable from its list like any other. The kill records
+ * `cancelled by the user` as its reason; it is not one the model requested,
+ * so the owning agent still receives the completion notice, and a shell
+ * tool waiting on that job reads the reason in its own result.
+ * @param request - Session whose job list carries the job, and the job id.
+ * @returns the registry's admission of the kill request.
+ */
+@Remote('kill') kill(request: JobKillRequest): JobKillValue
+```
+
+Source: [`packages/api/job-controller/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/api/job-controller/src/index.ts)
+
 <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).
+Abstract background job registry. Subclass, implement the abstract members, 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.
+- 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. Such settlements announce `cause: 'teardown'`, because a job whose owner is being destroyed 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.
+- Settlement is first-wins: one terminal record, released waiters, then one round of contained event delivery, even against a late producer outcome. The `settled` event follows every released waiter and reports whether it released one (`awaited`), so a completion reporter can skip settlements a waiting caller already collected.
+- A settled record stays listed until its owner's disposal, service disposal, or an explicit remove by a caller that collected the terminal state itself and never handed the id out.
+- 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 event delivery under `{ owners: 'scope' }` — 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.
+- Every job owns one output ring. Pull sources named by the spec are pumped by the registry and drained once more before settlement; pushed appends land whole. The model's consuming cursor and observers' absolute offsets read the same bytes and never disturb each other.
+- Ring retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap and ends the stream; the ring has no separate lifecycle.
 
 ```ts cordis-catalog
 /**
@@ -186,96 +464,83 @@ Implementations must honor these semantics:
  * 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.
+ * @param spec - job identity, owner, output sources, and synchronous starter.
+ * @returns the registry-issued `<kind>-<short-uuid>` id.
  */
-abstract start(spec: JobStart): JobId
+abstract start(spec: JobSpec): 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.
+ * List caller-owned and unowned jobs in registration order.
+ * @param caller - reading session; omission sees only unowned jobs.
+ * @returns fresh projections.
  */
-abstract list(caller?: Agent): JobSnapshot[]
+abstract list(caller?: SessionId): JobView[]
 
 /**
- * Return a non-consuming snapshot without changing its read cursor or notice
- * state. Throws for an unknown or foreign job.
+ * Project one job without changing its cursor. 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.
+ * @param caller - reading session checked against the owner.
+ * @returns a fresh projection.
  */
-abstract get(id: JobId, caller?: Agent): JobSnapshot
+abstract get(id: JobId, caller?: SessionId): JobView
 
 /**
- * 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.
+ * Consume the ring from the model cursor and advance it to the current
+ * total. After settlement the first read also carries the producer's
+ * result. 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.
+ * @param caller - reading session checked against the owner.
+ * @returns the chunks since the cursor, the lossy flag, the result once, and the post-read projection.
  */
-abstract read(id: JobId, caller?: Agent): JobRead
+abstract read(id: JobId, caller?: SessionId): 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.
+ * Read retained ring output without moving the model cursor. Resume with
+ * a previous read's `next`; an offset inside a retained chunk returns the
+ * whole chunk (its `at` may precede `from`). Throws for a negative or
+ * non-integer offset, or an unknown or foreign job.
+ * @param id - job to read.
+ * @param from - absolute byte offset to read from (0 for the retained head).
+ * @param caller - reading session checked against the owner.
+ * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag.
+ */
+abstract readAt(id: JobId, from: number, caller?: SessionId): JobOutputRead
+
+/**
+ * Request cancellation, then mark the job stopping. A producer throw
+ * propagates without changing job state. A supplied reason is merged into
+ * terminal `detail` when the job settles `killed`. 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.
+ * @param caller - killing session checked against the owner.
+ * @param reason - cancellation reason forwarded verbatim to the producer.
  * @returns `requested` for live work, otherwise `already-finished`.
  */
-abstract kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
+abstract kill(id: JobId, caller?: SessionId, 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.
+ * projection wins. Rejects for an invalid timeout or an unknown or foreign
+ * job.
  * @param id - job to wait for.
  * @param timeoutMs - positive finite wait bound in milliseconds.
- * @param caller - waiting agent checked against the owner.
+ * @param caller - waiting session checked against the owner.
  * @param signal - optional cancellation of the wait itself.
- * @returns snapshot at settlement or timeout.
+ * @returns projection at settlement or timeout.
  */
-abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<JobSnapshot>
+abstract wait(id: JobId, timeoutMs: number, caller?: SessionId, signal?: AbortSignal): Promise<JobView>
 
 /**
- * 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.
+ * Drop one settled job's record from the visible set and announce
+ * `removed`. For a caller that collected the terminal state through its own
+ * {@link wait} and never handed the id to the model, such as a shell tool's
+ * foreground call. Throws for a job that is still live, unknown, or foreign.
+ * @param id - settled job to drop.
+ * @param caller - removing session checked against the owner.
  */
-abstract onJobsChanged(listener: JobsChangedListener): () => void
+abstract remove(id: JobId, caller?: SessionId): void
 
 /**
  * Attach an effect-scoped controller that can read and stop jobs. It serves the
@@ -287,7 +552,7 @@ abstract onJobsChanged(listener: JobsChangedListener): () => void
 abstract attachController(name: string): () => void
 ```
 
-Types: [Agent](./core.md)
+Types: [SessionId](./core.md)
 
 Source: [`packages/jobs/jobs/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/jobs/jobs/src/index.ts)
 <!-- END GENERATED cordis-surface -->