refactor: replace overloaded surface terminology

packages/tasks/tasks/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/tasks/README.md
-README.md: 053e407d2e28cb175ebe9de15c7e16ef04e95cb8
-README.zh.md: dd39b1098cd01d7db9db6e49210c2b1149b37ecb
+README.md: 18029a2e93396336139612ba72804aeb11e87edf
+README.zh.md: 93efabb212274cdb54114167ff38f0a884b987f5

packages/tasks/tasks/README.md

@@ -6,22 +6,22 @@ The background task registry contract (`ctx.tasks`). The abstract `TaskService`
 
 ## Service contract
 
-- `start(spec): TaskId` validates the control surface, spec, exact live owner, and optional positive `outputLimitBytes` before calling the producer's `run()` once. A starter throw leaves nothing registered; successful return commits without another failable step.
+- `start(spec): TaskId` validates the attached controller, spec, exact live owner, and optional positive `outputLimitBytes` before calling the producer's `run()` once. A starter throw leaves nothing registered; successful return commits without another failable step.
 - `get(id, caller?)` and `list(caller?)` return non-consuming snapshots. Listing includes only caller-owned and unowned tasks.
 - `read(id, caller?)` consumes the single cursor for stream tasks and reads terminal output idempotently for final-output tasks.
 - `kill(id, caller?, reason?)` invokes producer cancellation before changing status. A cancellation throw leaves the task running; success changes it to `stopping` and marks terminal delivery reported.
 - `wait(id, timeoutMs, caller?, signal?)` returns a terminal snapshot or the live snapshot at timeout. Aborting stops only the wait; settlement wins once it has committed terminal delivery to that waiter.
 - `onTaskDone(listener)` observes each terminal record with the exact owner. Listener throws and rejections are contained; listener work is not awaited.
 - `onTasksChanged(listener)` observes visible-set changes — registration, every stopping transition (teardown's included, before it awaits a slow producer), settlement, owner-disposal removal, and the emptying service disposal commits — carrying only the owner whose set moved, or `undefined` when an unowned task changed and every caller's set moved with it. It is owner-granular because removal is a change no per-task record can express, and it is not a superset of `onTaskDone`: it carries no delivery meaning and marks nothing reported. The registration binds to the calling fiber, so an observer mounted outside the registry still sees the disposal emptying.
-- `attachSurface(name)` declares a control surface for its effect lifetime. `start()` fails before producer execution when no attached surface serves the spec's owner.
+- `attachController(name)` declares a task controller for its effect lifetime. `start()` fails before producer execution when no attached controller serves the spec's owner.
 
-All three registrations are owner-relative, because one registry serves every composition in the process. A surface or listener registered from an unscoped context serves every owner; one registered under an agent composition's scope serves exactly the agents composed under it. So a composition that loads no control surface cannot start background work on the strength of another composition's controls, and one settlement notifies only the listeners its owner's composition registered.
+All three registrations are owner-relative, because one registry serves every composition in the process. A controller or listener registered from an unscoped context serves every owner; one registered under an agent composition's scope serves exactly the agents composed under it. So a composition that loads no controller cannot start background work on the strength of another composition's controls, and one settlement notifies only the listeners its owner's composition registered.
 
 Owned access compares the task's `SessionId` with the caller's. Ids such as `bash-1` are predictable, so this fence is the boundary. Unowned tasks are open to callers and last until service disposal.
 
-`outputLimitBytes` is producer-owned model-presentation policy carried unchanged into snapshots. A control surface applies it after adding status or notice metadata; the registry does not rewrite producer output or invent a default for producers that omit it.
+`outputLimitBytes` is producer-owned model-presentation policy carried unchanged into snapshots. A controller applies it after adding status or notice metadata; the registry does not rewrite producer output or invent a default for producers that omit it.
 
-Implementations also owe the lifecycle semantics of the contract: registrations outlive producer and control-surface fibers, owner and service disposal cancel live work and await compliant producers, and settlement is first-wins — one terminal record, one round of contained listener notification, released waiters.
+Implementations also owe the lifecycle semantics of the contract: registrations outlive producer and controller fibers, owner and service disposal cancel live work and await compliant producers, and settlement is first-wins — one terminal record, one round of contained listener notification, released waiters.
 
 See the [task type catalog](../../../docs/subsystems/tasks.md), the [runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md), and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md).
 

packages/tasks/tasks/README.zh.md

@@ -6,22 +6,22 @@
 
 ## 服务约定
 
-- `start(spec): TaskId` 验证控制表层、spec、确切且仍存活的 owner，以及可选的 `outputLimitBytes`（如提供则须为正数），然后只调用生产方的 `run()` 一次。启动方抛出异常时不注册任何内容；成功返回会直接提交，不再执行其他可能失败的步骤。
+- `start(spec): TaskId` 验证已附加的任务控制器、spec、确切且仍存活的 owner，以及可选的 `outputLimitBytes`（如提供则须为正数），然后只调用生产方的 `run()` 一次。启动方抛出异常时不注册任何内容；成功返回会直接提交，不再执行其他可能失败的步骤。
 - `get(id, caller?)` 和 `list(caller?)` 返回非消费式快照。列表只包含调用方拥有及无 owner 的任务。
 - `read(id, caller?)` 消费流任务的唯一游标；对于最终输出任务，则以幂等方式读取终止输出。
 - `kill(id, caller?, reason?)` 在更改状态前调用生产方取消。取消抛出异常时任务保持运行；成功则把状态改为 `stopping`，并将终止交付标记为已报告。
 - `wait(id, timeoutMs, caller?, signal?)` 返回终止快照，或在超时时返回存活快照。中止只会停止等待；一旦终止交付已向该等待方提交，终止结果优先。
 - `onTaskDone(listener)` 观察每条终止记录及其精确 owner。监听器抛出的异常和产生的拒绝都会被隔离；系统不会等待监听器工作。
 - `onTasksChanged(listener)` 观察可见集合的变化——注册、每一次转入 stopping（包括 teardown 在等待缓慢生产者之前的那一次）、结算、owner 销毁时的移除，以及服务销毁提交的清空——只携带集合发生变化的那个 owner，或在无主任务变化、因而每个调用方的集合都随之变化时携带 `undefined`。它按 owner 分粒度，因为移除是任何逐任务记录都无法表达的变化；它也不是 `onTaskDone` 的超集：它不含任何投递含义，也不把任何东西标为已上报。注册绑定的是调用方 fiber，因此挂在注册表之外的观察者仍能收到销毁时的清空。
-- `attachSurface(name)` 在其 effect 生命周期内声明控制表层。当没有任何已附加的表层服务于 spec 的所有者时，`start()` 会在生产方执行前失败。
+- `attachController(name)` 在其 effect 生命周期内声明任务控制器。当没有任何已附加的控制器服务于 spec 的所有者时，`start()` 会在生产方执行前失败。
 
-这三类注册都是相对于所有者的，因为一个注册表要服务进程内的每一套组合。从不带 scope 的上下文注册的表层或监听器服务于每个所有者；在某套 agent 组合的 scope 下注册的，则恰好服务于在该组合下组合出的 agent。因此，未加载任何控制表层的组合无法借另一套组合的控制工具启动后台工作，而一次结算也只会通知其所有者所属组合注册的监听器。
+这三类注册都是相对于所有者的，因为一个注册表要服务进程内的每一套组合。从不带 scope 的上下文注册的控制器或监听器服务于每个所有者；在某套 agent 组合的 scope 下注册的，则恰好服务于在该组合下组合出的 agent。因此，未加载任何控制器的组合无法借另一套组合的控制工具启动后台工作，而一次结算也只会通知其所有者所属组合注册的监听器。
 
 有 owner 的访问会比较任务的 `SessionId` 与调用方。`bash-1` 等 id 可预测，因此这道隔离是安全边界。无 owner 的任务向调用方开放，并持续到服务释放。
 
-`outputLimitBytes` 是生产方拥有的模型呈现策略，会原样携带到快照中。控制表层在添加状态或通知元数据后应用它；注册表不会重写生产方输出，也不会为省略此字段的生产方虚构默认值。
+`outputLimitBytes` 是生产方拥有的模型呈现策略，会原样携带到快照中。控制器在添加状态或通知元数据后应用它；注册表不会重写生产方输出，也不会为省略此字段的生产方虚构默认值。
 
-实现还必须兑现约定的生命周期语义：注册的存续期长于生产方 fiber 与控制表层 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
+实现还必须兑现约定的生命周期语义：注册的存续期长于生产方 fiber 与控制器 fiber，owner 释放和服务释放会取消仍在运行的工作并等待守约的生产方，结算遵循首次结果优先（一条终止记录、一轮异常受到隔离的监听器通知，然后释放等待方）。
 
 参见[任务类型目录](../../../docs/subsystems/tasks.md)、[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)和 [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-task-registry-seam.md)。
 

packages/tasks/tasks/src/index.ts

@@ -39,7 +39,7 @@ declare module '@deepseek-ai/cordis' {
  * standard duplicate-service behavior).
  *
  * Implementations must honor these semantics:
- * - Registrations outlive producer and control-surface fibers. Owner and
+ * - 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.
  * - Owned-task access is fenced by the owner's session id. Ids are
@@ -47,7 +47,7 @@ declare module '@deepseek-ai/cordis' {
  * - Settlement is first-wins: one terminal record, one round of contained
  *   listener notification, and released waiters, even against a late
  *   producer outcome.
- * - {@link start} refuses work while no attached control surface serves the
+ * - {@link start} refuses work while no attached task 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
@@ -152,7 +152,7 @@ export abstract class TaskService extends Service {
    * composition's scope sees exactly the agents composed under it.
    *
    * This is not a superset of {@link onTaskDone}: that one delivers the terminal
-   * record under first-wins semantics a control surface couples to notice
+   * record under first-wins semantics a task 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
@@ -162,13 +162,13 @@ export abstract class TaskService extends Service {
   abstract onTasksChanged(listener: TasksChangedListener): () => void
 
   /**
-   * Attach an effect-scoped surface that can read and stop tasks. It serves the
+   * Attach an effect-scoped controller that can read and stop tasks. It serves the
    * owners its registering context's scope covers, and {@link start} refuses an
-   * owner no attached surface serves.
+   * owner no attached controller serves.
    * @param name - diagnostic label; duplicate names remain independent.
-   * @returns disposer that detaches this surface.
+   * @returns disposer that detaches this controller.
    */
-  abstract attachSurface(name: string): () => void
+  abstract attachController(name: string): () => void
 }
 
 export default TaskService

packages/tasks/tasks/src/types.ts

@@ -1,5 +1,5 @@
 /**
- * Types shared by task producers, the registry, and control surfaces. The
+ * Types shared by task producers, the registry, and controllers. The
  * service implementation lives in `./index.ts`.
  * @module @deepseek-ai/dsh-tasks/types
  */
@@ -50,7 +50,7 @@ export interface TaskStart {
   label: string
   /**
    * Optional UTF-8 byte cap for each complete model-facing completion notice or
-   * output read, including control-surface status metadata.
+   * output read, including controller status metadata.
    */
   outputLimitBytes?: number
   /**
@@ -119,7 +119,7 @@ export interface TaskSnapshot {
   finishedAt?: number
   /**
    * True when a kill, read, or wait has reported or committed to report the
-   * terminal state. Completion surfaces suppress redundant notices when set.
+   * terminal state. Completion reporters suppress redundant notices when set.
    */
   reported: boolean
 }

packages/tasks/tasks/tests/service.spec.ts

@@ -56,7 +56,7 @@ class StubTaskService extends TaskService {
     return () => {}
   }
 
-  attachSurface(_name: string): () => void {
+  attachController(_name: string): () => void {
     return () => {}
   }
 }
@@ -66,7 +66,7 @@ describe('TaskService seam', () => {
     const ctx = new Context()
     await ctx.plugin(StubTaskService)
 
-    const detachSurface = ctx.tasks.attachSurface('seam-test')
+    const detachController = ctx.tasks.attachController('seam-test')
     const id = ctx.tasks.start({ kind: 'bash', label: 'sleep 60', run: () => ({ cancel() {}, done: new Promise(() => {}) }) })
     expect(id).toBe('bash-1')
     expect(ctx.tasks.list()).toHaveLength(1)
@@ -78,7 +78,7 @@ describe('TaskService seam', () => {
     detachListener()
     const detachChanges = ctx.tasks.onTasksChanged(() => {})
     detachChanges()
-    detachSurface()
+    detachController()
   })
 
   it('loading a second implementation throws (one tasks service per context — cordis standard)', async () => {