Merge remote-tracking branch 'origin/master' into xtr/agent-loop-message-machine

# Conflicts:
#	packages/context/workspace-context/README.md
#	packages/llm/llm-retry/README.md
#	packages/session-persistence/session-checkpoint-policy/README.md
#	scripts/type-equiv.manifest.json

packages/tasks/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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
+README.md: f1c224345c94a833c44cbafb635be7617e8c42bf
+README.zh.md: 610a84a1506b4bb780297322f7827e6f04533bc1

packages/tasks/README.md

@@ -1,5 +1,7 @@
 # tasks/ — background task capability family
 
+English | [中文](README.zh.md)
+
 The shared home for background-task ids, owner isolation, reads, cancellation, waiting, and completion notices. Bash, subagents, and future long-running tools use one model-facing protocol. See the [background-task runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md).
 
 | Package | ctx key | Role |

packages/tasks/README.zh.md

@@ -0,0 +1,12 @@
+# tasks/：后台任务能力包族
+
+[English](README.md) | 中文
+
+后台 task id、拥有者隔离、读取、取消、等待和完成通知的共用归属位置。Bash、subagent 及未来的长时间运行工具共用一套面向模型的协议。参见[后台任务运行时 Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)。
+
+| 包（package） | ctx 键 | 角色 |
+|---|---|---|
+| [`tasks`](tasks/README.md)（`@deepseek-ai/dsh-tasks`） | `ctx.tasks` | 注册表服务：品牌化 `<kind>-N` id、按拥有者设防的 read／kill／wait／list、结算记账、等待完成的拥有者清理路径，以及防止 `attachSurface` 配置错误的防线 |
+| [`tool-tasks`](tool-tasks/README.md)（`@deepseek-ai/dsh-tool-tasks`） | 无 | 面向模型的控制接口：`task_output`、`task_list`、`task_kill`、完成通知注入和后台工作习惯提示词段落 |
+
+注册表拥有跨生产方或接口重载的状态；工具包拥有呈现。生产方通过 `ctx.tasks.start` 注册执行钩子，并自行决定其配置是否公开 `run_in_background`。

packages/tasks/tasks/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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
+README.md: 1a073add0fde8f2e519cc83b087af6a531a6cbb8
+README.zh.md: 795602701f072068f05bbf16ee98bdeea57548af

packages/tasks/tasks/README.md

@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-tasks
 
+English | [中文](README.zh.md)
+
 The process-local background task registry (`ctx.tasks`). It gives long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup. Producer plugins extend `TaskKindMap` with their opaque id namespace.
 
 ## Service API

packages/tasks/tasks/README.zh.md

@@ -0,0 +1,43 @@
+# @deepseek-ai/dsh-tasks
+
+[English](README.md) | 中文
+
+进程局部的后台任务注册表（`ctx.tasks`）。它为长时间运行的生产方提供共享 id、owner 隔离、读取、取消、等待、通知和清理。生产方插件使用其不透明 id namespace 扩展 `TaskKindMap`。
+
+## 服务 API
+
+- `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。监听器抛出异常或拒绝会被封装；系统不会等待监听器工作。
+- `attachSurface(name)` 在其 effect 生命周期内声明控制表层。如果没有附加任何表层，`start()` 会在生产方执行前失败。
+
+有 owner 的访问会比较任务的 `SessionId` 与调用方。`bash-1` 等 id 可预测，因此这道隔离是安全边界。无 owner 的任务向调用方开放，并持续到服务释放。
+
+`outputLimitBytes` 是生产方拥有的模型呈现策略，会原样携带到快照中。控制表层在添加状态或通知元数据后应用它；注册表不会重写生产方输出，也不会为省略此字段的生产方虚构默认值。
+
+## 生命周期
+
+任务属于其 owner 和后端，而不是生产方工具 fiber，因此重载生产方或表层不会停止任务。某个 owner 的第一个任务会把一个受等待的 effect 附加到精确的 `Agent` scope。owner 释放会取消该对象的任务，等待生产方完全停稳，并移除其快照；复用 agent 或 Session id 无法重定向旧清理。
+
+服务释放会关闭监听器、取消所有存活任务、等待其记录，并从仍存活的 owner scope 分离 effect。如果拆卸取消抛出异常，服务会强制把记录标为失败，并警告工作可能遗留，而不会死锁。取消已返回但始终不终止 `done` 时，系统无法将其与缓慢停止区分开，拆卸可能因此停滞。
+
+参见[任务类型目录](../../../docs/core-data-structures/tasks.md)和[运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)。
+
+## 模型体验
+
+通过生产方插件和 [`dsh-tool-tasks`](../tool-tasks/README.md) 间接影响；它们会渲染 task id、输出、状态、取消和完成通知。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由命名消费方负责。
+
+## 已知限制与暂缓事项
+
+- **任务只存在于进程本地**：持久或跨重启执行需要独立生命周期。
+- **服务与实现没有拆分**：第二个后端必须先定义塑造该边界的生命周期。
+- **流输出只有一个消费游标**：独立观察者需要游标或快照 API。
+- **前台工作无法提升**：生产方在启动前选择前台或后台。
+- **静默无效的取消可能使拆卸停滞**：只有显式抛出异常才能安全地强制标为失败。

packages/tasks/tool-tasks/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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
+README.md: 70c0c7da6ef17129241902d37359dd58b6d56605
+README.zh.md: 3ad8d8897ab348832b0d357436a0e78bf98c429b

packages/tasks/tool-tasks/README.md

@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-tool-tasks
 
+English | [中文](README.zh.md)
+
 The model-facing control surface for `ctx.tasks`: three kind-independent tools, completion notices, and one background-work prompt section. Loading the plugin attaches the surface required by `ctx.tasks.start()`.
 
 ## Tools

packages/tasks/tool-tasks/README.zh.md

@@ -0,0 +1,86 @@
+# @deepseek-ai/dsh-tool-tasks
+
+[English](README.md) | 中文
+
+`ctx.tasks` 的面向模型控制表层：三个与 kind 无关的工具、完成通知和一个后台工作提示词区段。加载该插件会附加 `ctx.tasks.start()` 所要求的表层。
+
+## 工具
+
+- `task_output(task_id, wait?, timeout_ms?)` 默认以非阻塞方式读取。流任务只返回下一个增量；最终输出任务在终止后返回结果。每个响应都以 `[status: ...]` 结尾。`wait: true` 最多等待到配置上限，超时时仍让运行中的任务保持存活。
+- `task_list()` 以 `<id> [<kind>] <status> — <label>` 返回调用方可见的任务。
+- `task_kill(task_id, reason?)` 立即请求取消并转发已记录的原因。终止任务返回非消费式快照。
+
+三个工具都使用通用 UI 卡片：output 和 list 使用 `read`，kill 使用 `execute`。
+
+它们的规范值依次为 `{ text, task }`、`PublicTaskSnapshot[]` 和 `{ outcome: 'cancellation-requested' | 'already-finished', task }`。公共快照携带 id、kind、label、status/detail 及开始／结束时间；它有意省略 `ownerSession` 和内部 `reported` 通知位。原生 renderer 保留上述状态与确认文本。
+
+当生产方提供 `outputLimitBytes` 时，`task_output`、终止 `task_kill` 和完成通知会在添加状态或通知文本后，对完整的原生 UTF-8 结果施加上限。只要能够容纳，读取就会保留输出尾部与控制后缀；有界完成通知则先为 `background task <id>` 和 `task_output` 收集指令预留空间，再把剩余字节用于可变的 kind、label、status、detail 与截断标记。一个前置 pre-execute 监听器会在策略运行前捕获调用方可见任务；每个任务控制定义的 final-content 回调会把其生产方上限应用到单文本拒绝、短路、规范化工具或流水线失败、替换和阻止；结构化多块策略结果保持自身形状。已有的生产方截断标记会复用，不会重复添加。省略该字段的生产方保留现有的无界控制表层行为。
+
+## 完成通知
+
+一项尚未报告的完成会向精确 owner 的会话注入 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.`。应用上限时，在 PTY 支持的 64 字节下限内，稳定 id 前缀和收集命令的优先级高于可变 label/detail，因此通知仍可操作。注入是下一次请求使用的持久上下文，并非唤醒。kill 或终止性 read/wait 会把交付标为已报告，并抑制重复通知；owner 释放竞态会被封装。
+
+## 配置
+
+| key | 默认值 | 含义 |
+|---|---|---|
+| `waitTimeoutMs` | `30000` | `wait: true` 省略 `timeout_ms` 时使用的等待时间 |
+| `maxWaitTimeoutMs` | `600000` | 模型所给等待时间的上限 |
+
+默认值高于上限时，插件会在加载时失败。
+
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到的内容
+
+该插件注册 scope 中的每次请求都包含以下指引。按 agent scope 过滤工具时，可能会隐藏工具，却不会移除独立注册的提示词区段。
+
+##### 后台任务指引
+
+```markdown
+Track every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.
+```
+
+#### Token 影响
+
+激活期间，每次请求承担少量固定输入成本。
+
+#### KV Cache 影响
+
+只要插件 scope 与指引文本不变，前缀就保持稳定。激活或释放可能使从该提示词区段起的复用失效。
+
+### 工具 schema
+
+#### 模型看到的内容
+
+该表层可见时，会看到生成的 [`task_output`、`task_list` 和 `task_kill` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-tasks)。
+
+#### Token 影响
+
+工具可见的每次请求承担固定 schema 成本。
+
+#### KV Cache 影响
+
+只要工具定义与可见性不变，前缀就保持稳定。注册生命周期或 scope 限制可能使从第一个发生变化的 schema token 起的复用失效。
+
+### 结果与通知
+
+#### 模型看到的内容
+
+读取会返回输出或 `(no new output)`，随后是 `[status: <status>]` 和可选 detail。空列表返回 `(no background tasks)`。kill 返回 `requested cancellation of task <id>` 或现有终止状态。尚未报告且有 owner 的完成使用上述通知。
+
+#### Token 影响
+
+结果与通知在压缩前保留于父级历史。流读取不会重复已消费的输出；生产方提供的 `outputLimitBytes` 会限制每次完整读取或通知。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 配置项失效。
+
+## 已知限制与暂缓事项
+
+- **完成通知不会唤醒空闲 agent**：需要立即获得结果的调用方必须使用 `task_output`。
+- **流读取只有单一消费方**：独立观察者需要另一套运行时 API。
+- **无 owner 的任务没有会话隔离**：外部表层必须提供调用方策略或避开这些任务。