dsh-agent-board 1.7.4 → 1.7.6

package/test/headless-smoke.test.mjs

@@ -0,0 +1,209 @@
+// dsh-agent-board — 无头冒烟链路 + mock-ctx harness 各面独立用例（task-muxpfon9 无头基建卡1）
+// 本文件同时证明两件事：
+//   ① test/helpers/mock-ctx.mjs 这套无头宿主基建的每一面都可独立工作——
+//      fs 临时目录隔离 / 虚拟时钟推进 / subagents 剧本化（一次性 run + continuable 句柄）/
+//      agentEvents 事件发射 / webServer 路由直调 / agents 剧本 / tools·systemPrompt·llm 记录器；
+//   ② 冒烟链路：真实 import ../index.mjs → apply(env.ctx) → 建一张卡 → 虚拟时钟推进 →
+//      断言派发发生（subagents 剧本收到 continuable spawn）→ emitStatus 事件结算 → 断点续跑 sendMessage。
+// 约束：不改 index.mjs 任何行为；看板文件落在 os.tmpdir 下的独立临时 HOME，cleanup 全清。
+// 注意：node:test 顶层用例默认串行——每个用例自建 env、finally 里 cleanup（HOME env 是进程级，严禁并行env）。
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createMockCtx } from './helpers/mock-ctx.mjs'
+import * as plugin from '../index.mjs'
+
+// ===== harness 面①：fs —— 临时 HOME 接管 / 目录隔离 / cleanup 恢复 =====
+test('harness·fs 面：临时 HOME 接管+隔离，cleanup 恢复 env 并递归删目录', async () => {
+  var hadHome = Object.prototype.hasOwnProperty.call(process.env, 'HOME')
+  var prevHome = process.env.HOME
+  var env1 = createMockCtx()
+  assert.equal(process.env.HOME, env1.home, '创建后 HOME 指向该 env 的临时目录（boardDirName 每次现读 env）')
+  assert.ok(env1.home.indexOf(os.tmpdir()) === 0, '临时目录落在 os.tmpdir 下')
+  assert.ok(fs.existsSync(env1.home), '临时目录真实存在（真写 fs）')
+  var env2 = createMockCtx()
+  assert.notEqual(env1.home, env2.home, '每个 env 各自独立临时目录')
+  fs.writeFileSync(path.join(env1.home, 'marker.txt'), 'x', 'utf8')
+  assert.ok(!fs.existsSync(path.join(env2.home, 'marker.txt')), '目录间互不污染')
+  await env2.cleanup() // LIFO 纪律：后建的先清，HOME 回到 env1
+  assert.equal(process.env.HOME, env1.home, 'cleanup 按 LIFO 恢复上一层 HOME')
+  await env1.cleanup()
+  assert.ok(!fs.existsSync(env1.home), 'cleanup 递归删除临时目录')
+  if (hadHome) assert.equal(process.env.HOME, prevHome, 'HOME env 恢复创建前的原值')
+  else assert.ok(!Object.prototype.hasOwnProperty.call(process.env, 'HOME'), '原本无 HOME 则恢复为未设置')
+})
+
+// ===== harness 面②：虚拟时钟 —— 到期触发 / dispose 取消 / interval 续挂 =====
+test('harness·时钟面：advance 按到期顺序触发，dispose 真取消，interval 自动续挂', async () => {
+  var env = createMockCtx()
+  try {
+    var fired = []
+    var cancel = env.ctx.timer.timeout(function () { fired.push('disposed') }, 10)
+    cancel() // 回调式的 dispose 闭包：真清掉，到期不触发
+    env.ctx.timer.timeout(function () { fired.push('cb50') }, 50)
+    var p100 = env.ctx.timer.timeout(100).then(function () { fired.push('p100') }) // promise 形态（kickCycle/去抖/聚合同款用法）
+    var iv = 0
+    var stopIv = env.ctx.timer.interval(function () { iv++ }, 30)
+    assert.equal(env.clock.now(), 0, '虚拟时钟从 0 起算')
+    await env.clock.advance(40)
+    assert.deepEqual(fired, [], '40ms 内无到期（10 已 dispose，50/100 未到点）')
+    await env.clock.advance(60) // → now=100
+    assert.deepEqual(fired, ['cb50', 'p100'], '按到期顺序触发（回调式 50 先于 promise 式 100）')
+    assert.equal(iv, 3, 'interval 30ms 在 100ms 窗口内触发 3 次（30/60/90）并自动续挂')
+    assert.equal(env.clock.now(), 100)
+    stopIv()
+    await env.clock.advance(1000)
+    assert.equal(iv, 3, 'interval dispose 后不再触发')
+    assert.equal(env.clock.pendingCount(), 0, '全部定时器已结清（一次性触发后即注销）')
+    await p100 // promise 形态确实落定过（then 链已在 advance 内跑完）
+  } finally { await env.cleanup() }
+})
+
+// ===== harness 面③：subagents 剧本 —— 一次性 run 可控结局 + continuable 句柄 + 记录器 =====
+test('harness·subagents 面：一次性 run 由测试驱动结局，continuable/sendMessage/interrupt/listChildren 留痕', async () => {
+  var env = createMockCtx()
+  try {
+    // 一次性 run：result promise 由测试驱动
+    var run = await env.ctx.subagents.start('mock-provider', { label: 'worker:t1', prompt: [{ type: 'text', text: 'p' }] })
+    assert.equal(env.runs.length, 1, 'start 产出登记进 runs 剧本表')
+    assert.equal(run.req.label, 'worker:t1', 'req 原文留痕（label/prompt 可断言）')
+    var settled = null
+    run.result.then(function (r) { settled = r }, function () {})
+    await new Promise(function (r) { setImmediate(r) })
+    assert.equal(settled, null, '未 resolveWith 前 result 不落定（测试掌控节奏）')
+    // localAgent steer/followup 记录器（doIntervene 通道句柄）
+    run.localAgent.steer('高优指令')
+    run.localAgent.followup('补充消息')
+    assert.deepEqual(run.localAgent.steered, ['高优指令'])
+    assert.deepEqual(run.localAgent.followed, ['补充消息'])
+    run.resolveWith('交付文本')
+    var res = await run.result
+    assert.equal(res.output[0].text, '交付文本', 'outputText 可指定（{ output:[{type:text}], stopReason } 形状）')
+    assert.equal(res.stopReason, 'completed')
+    // 失败结局：failWith 拒绝 result
+    var run2 = await env.ctx.subagents.start('mock-provider', { label: 'verifier:t2' })
+    run2.failWith('boom')
+    await assert.rejects(run2.result, /boom/)
+    // continuable 面：{ childId, messageId } 句柄
+    var c = await env.ctx.subagents.startContinuable({ provider: 'mock-provider', label: 'worker:t3', request: { prompt: [] } })
+    assert.ok(c.childId && c.messageId, 'startContinuable 返回 { childId, messageId }')
+    assert.equal(env.continuables[0].label, 'worker:t3', 'continuable 剧本登记 label/request')
+    // sendMessage / interrupt / listChildren 记录器
+    await env.ctx.subagents.sendMessage(env.root, c.childId, [{ type: 'text', text: '续跑指令' }])
+    assert.equal(env.sendMessages[0].childId, c.childId)
+    assert.equal(env.sendMessages[0].content[0].text, '续跑指令')
+    env.ctx.subagents.interrupt(c.childId, { kind: 'ancestor', agent: env.root })
+    assert.equal(env.interrupts[0].childId, c.childId)
+    assert.equal(env.interrupts[0].authority.kind, 'ancestor', 'interrupt authority 形状留痕')
+    env.children.push({ id: 'child-x', label: 'x' })
+    assert.deepEqual(await env.ctx.subagents.listChildren(env.sid), [{ id: 'child-x', label: 'x' }], 'listChildren 剧本可整组替换')
+  } finally { await env.cleanup() }
+})
+
+// ===== harness 面④：agentEvents —— emitStatus 重放 agent/status 事件 =====
+test('harness·agentEvents 面：emitStatus 手动发射事件，payload 形状与退订语义正确', async () => {
+  var env = createMockCtx()
+  try {
+    var got = []
+    var off = env.ctx.on('agent/status', function (p) { got.push(p) })
+    env.emitStatus('child-9', 'running')
+    env.emitStatus('child-9', 'idle')
+    assert.deepEqual(got.map(function (p) { return p.status }), ['running', 'idle'])
+    assert.equal(got[0].agent.session.id, 'child-9', 'payload 形状 { agent: { session: { id } }, status }（与 host 事件契约一致）')
+    off()
+    env.emitStatus('child-9', 'idle')
+    assert.equal(got.length, 2, '退订后不再接收')
+  } finally { await env.cleanup() }
+})
+
+// ===== harness 面⑤：webServer 直调 + agents 剧本 + tools/systemPrompt/llm 记录器（需 apply 接线）=====
+test('harness·webServer/agents 面：apply 后走真 readBody/handler 路径直调 RPC，工具与提示词留痕', async () => {
+  var env = createMockCtx()
+  try {
+    // agents 剧本：currentInitiator/roots 可按测试改写
+    assert.equal(env.ctx.agents.currentInitiator().id, env.sid, '缺省 actor=root sid')
+    env.actor = 'sub-agent-1'
+    assert.equal(env.ctx.agents.currentInitiator().id, 'sub-agent-1', 'actor 可改写模拟子代理身份')
+    env.actor = env.sid
+    assert.equal(env.ctx.agents.roots()[0].session.header.cwd, env.cwd, 'root.session.header.cwd 是 sessionCwd 来源')
+    // 真实 index.mjs 接线（薄壳：session→store→notify→dispatch→rpc）
+    plugin.apply(env.ctx)
+    // webServer register 捕获的路由：env.rpc 以真语义直调（POST body → readBody → handlers[method]）
+    var r = await env.rpc('get-tasks', { sessionId: env.sid })
+    assert.equal(r.sessionId, env.sid)
+    assert.ok(Array.isArray(r.tasks) && r.tasks.length === 0, '新会话空板')
+    assert.equal(r.isRoot, true)
+    // tools.register 记录器：工具表按名可查、execute 可真跑
+    assert.ok(env.tools.get('task_create'), 'task_create 已注册')
+    assert.ok(env.tools.get('board_report'), 'board_report 已注册')
+    var listed = await env.tools.get('task_list').execute({})
+    assert.ok(Array.isArray(listed.tasks) && listed.tasks.length === 0, 'task_list 工具真跑返回空表')
+    // systemPrompt 记录器：Team 引导段在 apply 时注册
+    assert.ok(env.spSections.some(function (s) { return s.name === 'task-board:team-mode' }), 'systemPrompt.section 注册留痕')
+    // llm 记录器：list-models RPC 触发 listProviders
+    var lm = await env.rpc('list-models', {})
+    assert.equal(lm.ok, true)
+    assert.equal(env.llm.listProviders, 1, 'llm.listProviders 调用留痕')
+  } finally { await env.cleanup() }
+})
+
+// ===== ② 冒烟链路：建卡 → 虚拟时钟推进 → 派发发生 → 事件结算 → 断点续跑 =====
+// 这一例证明 harness 可用：真实 index.mjs 全套接线在 mockCtx 上跑通核心派发闭环。
+// 链路：create-task RPC → mutateLocked 写盘 → kickCycle（虚拟 50ms 去抖）→ poolCycle →
+//       pickDispatch → spawnOneShot → subagents.startContinuable（workerContinuable 缺省开）→
+//       agent/status running→idle 事件结算（空文本按失败重排，interrupt 留存）→
+//       再推进去抖 → tryResumeWorker 命中续跑资格 → sendMessage 冷复活（不再 fresh spawn）。
+test('冒烟链路：apply(mockCtx) → 建卡 → 时钟推进 → continuable 派发 → 事件结算 → 断点续跑', async () => {
+  var env = createMockCtx()
+  try {
+    plugin.apply(env.ctx)
+    // 建一张卡（pipeline=work：只做不验，避开 verifier 支线；显式 description 避开软提示）
+    var created = await env.rpc('create-task', { sessionId: env.sid, id: 'task-smoke-1', title: '冒烟任务', description: '无头冒烟链路用例', pipeline: 'work' })
+    assert.equal(created.ok, true)
+    assert.equal(created.task.status, 'pending', '非 Team 模式即建即 pending')
+    assert.ok(fs.existsSync(path.join(env.home, '.dsh', 'tasks-' + env.sid + '.json')), '看板文件落在临时 HOME')
+    // 虚拟时钟推进 50ms（kickCycle 去抖窗口）→ poolCycle 起跑；链尾真实 I/O 由 waitFor 收敛
+    await env.clock.advance(50)
+    // 核心断言：派发发生——subagents 剧本收到 continuable spawn
+    await env.waitFor(function () { return env.continuables.length >= 1 }, 'continuable spawn 发生')
+    var child = env.continuables[0]
+    assert.equal(child.label, 'worker:task-smoke-1', 'spawn label 形如 worker:<taskId>')
+    assert.ok(child.request.prompt[0].text.indexOf('冒烟任务') >= 0, '首条 prompt 携带任务标题')
+    assert.equal(env.runs.length, 0, 'Worker 走 continuable 面，未动用一次性 start')
+    // 卡面：占位 claim（spawn-pending）已换成真实 childId
+    await env.waitFor(function () {
+      var t = env.task('task-smoke-1')
+      return t && t.status === 'in-progress' && t.claimedBy === child.childId ? t : null
+    }, '任务落卡 in-progress 且 claimedBy=childId')
+    // 事件结算：continuable 无 run.result，agent/status 的 running→idle 是唯一结算信号
+    env.emitStatus(child.childId, 'running')
+    env.emitStatus(child.childId, 'idle')
+    // 无 v4 会话日志可读 → 空文本按失败结算：回 pending 重排（settleContinuable 既定语义），interrupt 留存子会话。
+    // waitFor 必须等整条结算链尾（settleWorker 落卡 + closeRunHistory 关账）——否则 cleanup 会
+    // rm 掉在飞写盘的临时目录（链尾不定长是真实 I/O，这正是 harness 提供 waitFor 的原因）。
+    await env.waitFor(function () {
+      var t = env.task('task-smoke-1')
+      return t && t.status === 'pending' && t.retryCount === 1 && t.runs && t.runs.length === 1 && t.runs[0].outcome === 'incomplete' ? t : null
+    }, '空文本失败重排 pending 且 run 关账 incomplete')
+    var t1 = env.task('task-smoke-1')
+    assert.ok(env.interrupts.some(function (i) { return i.childId === child.childId }), '结算收尾 interrupt 留存（不销毁子会话）')
+    assert.equal(t1.runs[0].continuable, true)
+    // 断点续跑：再推进一次去抖窗口 → 命中续跑资格 → sendMessage 冷复活原 child，不再 fresh spawn
+    await env.clock.advance(50)
+    await env.waitFor(function () { return env.sendMessages.length >= 1 }, '断点续跑 sendMessage 发出')
+    assert.equal(env.sendMessages[0].childId, child.childId, '续跑唤醒的是原子会话')
+    assert.ok(env.sendMessages[0].content[0].text.indexOf('断点续跑') >= 0, '续跑指令文案')
+    assert.equal(env.continuables.length, 1, '续跑命中 → 不再 spawn 新子会话')
+    // 续跑轮再次事件结算（仍空文本 → retryCount 2）；runs 留档两条，第二条 resume:true 且关账 incomplete
+    env.emitStatus(child.childId, 'running')
+    env.emitStatus(child.childId, 'idle')
+    await env.waitFor(function () {
+      var t = env.task('task-smoke-1')
+      return t && t.status === 'pending' && t.retryCount === 2 && t.runs && t.runs.length === 2 && t.runs[1].outcome === 'incomplete' ? t : null
+    }, '续跑轮失败重排且关账')
+    var t2 = env.task('task-smoke-1')
+    assert.equal(t2.runs[1].resume, true, '第二条标 resume:true')
+  } finally { await env.cleanup() }
+})

package/test/helpers/mock-ctx.mjs

@@ -0,0 +1,327 @@
+// dsh-agent-board — 无头宿主基建（test/helpers/mock-ctx.mjs）
+// 在**无 DSH 环境**下托住真实 index.mjs 的 apply(ctx)：全套假 cordis 服务 + 真 fs 临时 HOME +
+// 虚拟时钟 + 剧本化 subagents + webServer 路由捕获 + systemPrompt/llm 记录器。
+//
+// 设计口径（与宿主真实契约逐一对齐，来源：lib/dispatch.mjs / lib/notify.mjs / lib/store.mjs / lib/rpc.mjs）：
+//   · timer.timeout(ms)          → Promise（kickCycle 50ms / 歧义去抖 25s / 回执聚合 45s / withTimeout 硬超时）
+//   · timer.timeout(cb, ms)      → dispose 函数（软超时臂，armTimeouts 回调式用法）
+//   · timer.interval(fn, ms)     → dispose 函数（15s 心跳）
+//   · subagents.start(provider, req)            → 一次性 run（result promise 由测试驱动落定/拒绝）
+//   · subagents.startContinuable({...})         → { childId, messageId }（持久子会话，turn 结算走 emitStatus）
+//   · subagents.sendMessage / interrupt / listChildren → 记录器 + 可剧本化
+//   · agents.currentInitiator()/roots()/list()/isOwnedBy() → 按测试剧本返回（缺省单 root，actor=root）
+//   · tools.register / webServer.register       → 捕获工具表与 RPC 路由（env.rpc 走真 readBody/handler 路径）
+//   · ctx.get('systemPrompt'|'llm')             → 记录器（注册了什么段/查了什么模型都留痕）
+//   · ctx.effect / ctx.on('agent/status')       → 真实执行 + disposer 收口 / 事件捕获与重放
+//
+// 看板文件走真路径：store 层用 node:fs 直读写 boardHome()=<$HOME>/.dsh——本 harness 把
+// process.env.HOME 指到 os.tmpdir 下的独立临时目录（boardDirName() 每次现读 env，进程内安全），
+// cleanup() 恢复原 env 并递归删除临时目录。每个用例一个独立 mockCtx + 独立临时目录，互不污染。
+// 注意：插件自身从不 mkdir .dsh（生产上宿主保证 ~/.dsh 已存在），故 harness 建目录时预建
+// <home>/.dsh 以镜像这一前置条件——否则 wt() 的 tmp 文件写入会 ENOENT。
+//
+// 虚拟时钟只接管 ctx.timer 注册的所有定时器；Date.now() 仍是真实墙钟（看板时间戳语义不变）。
+// advance(ms) 按到期顺序同步触发回调/落定 promise，每轮之间让出宏任务使异步链（poolCycle→spawn→
+// 落盘）起跑；链尾用 waitFor 轮询收敛（真实 I/O 不定长，这是有意设计而非竞态）。
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { Readable } from 'node:stream'
+
+/**
+ * @typedef {Object} MockEnv
+ * @property {Object} ctx            假 cordis ctx——直接传给插件 apply(ctx)
+ * @property {string} sid            本会话（root agent）id
+ * @property {string} home           临时 HOME 目录（看板文件在 <home>/.dsh/tasks-<sid>.json）
+ * @property {Object} clock          虚拟时钟：advance(ms) 推进并触发到期定时器；tick() 手动触发一次心跳 interval；now() 当前虚拟毫秒
+ * @property {Map}    tools          已注册工具表（task_create/board_report/board_verdict/task_arbitrate/...），调 .execute(args)
+ * @property {(method:string, args?:Object)=>Promise<any>} rpc  以真 RPC 语义（POST body → readBody → handler）调捕获的路由
+ * @property {Array}  runs           start() 产出的一次性 run：{ id, req, result, disposed, localAgent, resolveWith(text,stopReason?), failWith(err) }
+ * @property {Array}  continuables   startContinuable 产出：{ childId, messageId, label, request }
+ * @property {Array}  sendMessages   sendMessage 记录：{ parent, childId, content }
+ * @property {Array}  interrupts     interrupt 记录：{ childId, authority }
+ * @property {Array}  children       listChildren 剧本（可整组替换返回值）
+ * @property {(childId:string, status:'running'|'idle')=>void} emitStatus  重放 agent/status 事件（continuable 结算触发器）
+ * @property {Array}  sent           root.followup 捕获的消息（makeMsg 形态：content[0].text 取文本）
+ * @property {Object} root           假 root agent（followup 记录器；刻意不带 whenIdle → 回执立即投递分支）
+ * @property {Object} spSections     systemPrompt 注册段记录器
+ * @property {Object} llm            llm 记录器（listProviders/listModels 调用留痕）
+ * @property {string} actor          currentInitiator 返回值（缺省=root sid；测试可改写模拟子代理身份）
+ * @property {()=>Object} board      读当前看板文件 JSON（不存在返回 null）
+ * @property {(id:string)=>Object|undefined} task  看板里按 id 取任务
+ * @property {(fn:Function, label?:string, timeoutMs?:number)=>Promise<any>} waitFor  真实时间轮询直到条件为真（默认 5s 上限）
+ * @property {(label:string)=>Object|undefined} lastRun  按 label 前缀找最近一次一次性 run（label 形如 'worker:task-x'）
+ * @property {(fn:(d:Object)=>void)=>void} patchBoard  直接改写看板文件（构造孤儿/脏数据场景用）
+ * @property {()=>Promise<void>} cleanup  收尾：跑全部 disposer、恢复 HOME env、递归删临时目录
+ */
+
+/**
+ * 创建一套无头宿主环境。
+ * @param {Object} [opts]
+ * @param {string} [opts.sid]       会话 id（缺省自动生成，形如 session-mock-xxxx-xx——满足 isFullSessionId 结构）
+ * @param {string} [opts.cwd]       root agent 的工作区路径（缺省=临时 home；sessionCwd/ownerCwd 来源）
+ * @returns {MockEnv}
+ */
+export function createMockCtx(opts) {
+  opts = opts || {}
+  var sid = opts.sid || ('session-mock-' + Math.random().toString(36).slice(2, 10) + '-' + Date.now().toString(36))
+  var home = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-board-test-'))
+  // 镜像宿主前置条件：生产上 ~/.dsh 由宿主保证存在（插件自身从不 mkdir）——临时 HOME 里预建，
+  // 否则 store.wt() 写 <home>/.dsh/tasks-<sid>.json.tmp 会 ENOENT。
+  fs.mkdirSync(path.join(home, '.dsh'), { recursive: true })
+  var cwd = opts.cwd || home
+
+  // ===== 临时 HOME 接管（boardDirName 每次现读 env → 看板文件落在这里，与真实家目录隔离）=====
+  var prevHome = process.env.HOME
+  var hadHome = Object.prototype.hasOwnProperty.call(process.env, 'HOME')
+  process.env.HOME = home
+
+  // ===== 虚拟时钟 =====
+  var now = 0
+  var seq = 0
+  var timers = [] // { id, at, every(0=once), cb, cancelled }
+  function schedule(at, every, cb) { var t = { id: ++seq, at: at, every: every || 0, cb: cb, cancelled: false }; timers.push(t); return t }
+  function flushMacro(turns) { // 让 promise 连续体与 fs 回调起跑（不定长 I/O 的链尾由 waitFor 收敛）
+    var p = Promise.resolve()
+    for (var i = 0; i < (turns || 6); i++) p = p.then(function () { return new Promise(function (r) { setImmediate(r) }) })
+    return p
+  }
+  var clock = {
+    now: function () { return now },
+    pendingCount: function () { return timers.filter(function (t) { return !t.cancelled }).length },
+    // 推进虚拟时间：按到期顺序触发，interval 自动续挂；每触发一个让出一次宏任务
+    advance: async function (ms) {
+      var target = now + ms
+      for (;;) {
+        var next = null
+        for (var i = 0; i < timers.length; i++) {
+          var t = timers[i]
+          if (t.cancelled || t.at > target) continue
+          if (!next || t.at < next.at || (t.at === next.at && t.id < next.id)) next = t
+        }
+        if (!next) break
+        now = next.at
+        if (next.every > 0) next.at = now + next.every
+        else next.cancelled = true
+        try { next.cb() } catch (e) { console.error('[mock-ctx] 定时器回调异常:', String(e)) }
+        await flushMacro(3)
+      }
+      now = target
+      await flushMacro(6)
+    },
+    // 手动触发一次心跳（interval 回调），不动虚拟时间、不改 interval 的既有排程
+    tick: async function () {
+      var cbs = []
+      for (var i = 0; i < timers.length; i++) { var t = timers[i]; if (!t.cancelled && t.every > 0) cbs.push(t.cb) }
+      for (var j = 0; j < cbs.length; j++) { try { cbs[j]() } catch (e) { console.error('[mock-ctx] 心跳回调异常:', String(e)) } }
+      await flushMacro(6)
+    },
+  }
+  var timer = {
+    // 双形态：timeout(ms)→Promise（去抖/聚合/硬超时 race）；timeout(cb, ms)→dispose（软超时臂）
+    timeout: function (a, b) {
+      if (typeof a === 'function') {
+        var t1 = schedule(now + (typeof b === 'number' ? b : 0), 0, a)
+        return function () { t1.cancelled = true }
+      }
+      var ms = typeof a === 'number' ? a : 0
+      return new Promise(function (resolve) { schedule(now + ms, 0, function () { resolve() }) })
+    },
+    interval: function (fn, ms) {
+      var t2 = schedule(now + (typeof ms === 'number' ? ms : 0), typeof ms === 'number' ? ms : 0, fn)
+      return function () { t2.cancelled = true }
+    },
+  }
+
+  // ===== 剧本化 subagents =====
+  var runs = []
+  var continuables = []
+  var sendMessages = []
+  var interrupts = []
+  var children = []
+  var runSeq = 0
+  var childSeq = 0
+  function makeRun(provider, req) {
+    var settle = {}
+    var result = new Promise(function (res, rej) { settle.res = res; settle.rej = rej })
+    var run = {
+      id: 'run-' + (++runSeq),
+      provider: provider,
+      req: req, // { label, prompt, parent, signal, agentOptions? }——label 形如 'worker:task-x' / 'verifier:task-x'
+      result: result,
+      disposed: false,
+      localAgent: { // doIntervene 通道句柄：steer/followup 记录器
+        steered: [],
+        followed: [],
+        steer: function (m) { this.steered.push(m) },
+        followup: function (m) { this.followed.push(m) },
+      },
+      dispose: async function () { run.disposed = true },
+      // 测试驱动结局：resolveWith('文本') = 正常完成（outputText 可指定）；failWith(e) = run 失败
+      resolveWith: function (text, stopReason) { settle.res({ output: [{ type: 'text', text: text || '' }], stopReason: stopReason || 'completed' }) },
+      failWith: function (err) { settle.rej(err instanceof Error ? err : new Error(String(err))) },
+    }
+    runs.push(run)
+    return run
+  }
+  var subagents = {
+    list: function () { return ['mock-provider'] },
+    getProvider: function () { return { inheritsParentContext: false } },
+    start: async function (provider, req) { return makeRun(provider, req) },
+    startContinuable: async function (o) {
+      var c = { childId: 'child-' + (++childSeq), messageId: 'm' + childSeq, label: o && o.label, request: o && o.request }
+      continuables.push(c)
+      return c
+    },
+    sendMessage: async function (parent, childId, content) { sendMessages.push({ parent: parent, childId: childId, content: content }); return { ok: true } },
+    interrupt: function (childId, authority) { interrupts.push({ childId: childId, authority: authority }) },
+    listChildren: async function () { return children },
+  }
+
+  // ===== agents（缺省单 root；actor 可改写模拟子代理/其他会话身份）=====
+  var sent = []
+  var root = {
+    id: sid,
+    session: { id: sid, header: { cwd: cwd } },
+    followup: function (m) { sent.push(m) },
+    // whenIdle 刻意不实现：flushReceipts 走「无空闲门控 → 立即投递」分支（45s 窗口到点即投，可断言）
+  }
+  var env // 前向引用（currentInitiator 读 env.actor）
+  var agents = {
+    currentInitiator: function () { return { id: env.actor } },
+    roots: function () { return [root] },
+    list: function () { return [root] },
+    isOwnedBy: function () { return false },
+  }
+
+  // ===== tools / webServer / systemPrompt / llm / effect / on =====
+  var tools = new Map()
+  var routes = []
+  var spSections = []
+  var llmCalls = { listProviders: 0, listModels: [] }
+  var disposers = []
+  var listeners = {} // event -> Set<fn>
+
+  var ctx = {
+    fs: {}, // store 层走 node:fs 直读写（家目录绝对路径），fs 服务只是占位——保留键位对齐真实契约
+    timer: timer,
+    subagents: subagents,
+    agents: agents,
+    tools: { register: function (t) { tools.set(t.name, t) } },
+    webServer: {
+      register: function (r) {
+        routes.push(r)
+        return function () { var i = routes.indexOf(r); if (i >= 0) routes.splice(i, 1) }
+      },
+    },
+    get: function (name) {
+      if (name === 'systemPrompt') {
+        return {
+          sections: spSections,
+          section: function (spec) { spSections.push(spec); return function () { var i = spSections.indexOf(spec); if (i >= 0) spSections.splice(i, 1) } },
+        }
+      }
+      if (name === 'llm') {
+        return {
+          listProviders: function () { llmCalls.listProviders++; return [] },
+          listModels: async function (p) { llmCalls.listModels.push(p); return [] },
+        }
+      }
+      return undefined
+    },
+    effect: function (fn) {
+      var d
+      if (typeof fn === 'function') d = fn()
+      if (typeof d === 'function') disposers.push(d)
+      return function () {}
+    },
+    on: function (event, fn) {
+      if (!listeners[event]) listeners[event] = new Set()
+      listeners[event].add(fn)
+      return function () { listeners[event].delete(fn) }
+    },
+  }
+
+  env = {
+    ctx: ctx,
+    sid: sid,
+    home: home,
+    cwd: cwd,
+    clock: clock,
+    tools: tools,
+    runs: runs,
+    continuables: continuables,
+    sendMessages: sendMessages,
+    interrupts: interrupts,
+    children: children,
+    sent: sent,
+    root: root,
+    spSections: spSections,
+    llm: llmCalls,
+    actor: sid,
+
+    // 以真 RPC 语义调用捕获的 webServer 路由（POST /dsh-agent-board → readBody → handlers[method]）
+    rpc: async function (method, args) {
+      var route = routes[0]
+      if (!route) throw new Error('webServer 路由未注册（apply 未跑？）')
+      var req = Readable.from([Buffer.from(JSON.stringify({ method: method, args: args || {} }), 'utf8')])
+      req.method = 'POST'
+      var res = {
+        statusCode: 0, body: '',
+        setHeader: function () {},
+        writeHead: function (c) { res.statusCode = c },
+        end: function (s) { res.body = s },
+      }
+      await route.handler(req, res)
+      return JSON.parse(res.body)
+    },
+
+    // 重放 host 事件 agent/status（continuable Worker 的 turn 结算触发器：先 running 后 idle）
+    emitStatus: function (childId, status) {
+      var set = listeners['agent/status']
+      if (!set) return
+      set.forEach(function (fn) { fn({ agent: { session: { id: childId } }, status: status }) })
+    },
+
+    board: function () {
+      try { return JSON.parse(fs.readFileSync(path.join(home, '.dsh', 'tasks-' + sid + '.json'), 'utf8')) } catch (_) { return null }
+    },
+    task: function (id) {
+      var d = env.board()
+      return d && d.tasks.find(function (t) { return t.id === id })
+    },
+    patchBoard: function (fn) {
+      var p = path.join(home, '.dsh', 'tasks-' + sid + '.json')
+      var d = JSON.parse(fs.readFileSync(p, 'utf8'))
+      fn(d)
+      fs.writeFileSync(p, JSON.stringify(d), 'utf8')
+    },
+    lastRun: function (labelPrefix) {
+      for (var i = runs.length - 1; i >= 0; i--) { if (runs[i].req && String(runs[i].req.label).indexOf(labelPrefix) === 0) return runs[i] }
+      return undefined
+    },
+
+    // 真实时间轮询收敛：异步链（读盘→持锁→写盘→spawn→落卡）的终点不定长，按条件等到为止
+    waitFor: async function (fn, label, timeoutMs) {
+      var t0 = Date.now()
+      var cap = timeoutMs || 5000
+      for (;;) {
+        var v
+        try { v = await fn() } catch (_) { v = null }
+        if (v) return v
+        if (Date.now() - t0 > cap) throw new Error('waitFor 超时（' + cap + 'ms）: ' + (label || '(未命名条件)'))
+        await new Promise(function (r) { setTimeout(r, 5) })
+      }
+    },
+
+    cleanup: async function () {
+      for (var i = 0; i < disposers.length; i++) { try { disposers[i]() } catch (_) {} }
+      for (var j = 0; j < timers.length; j++) timers[j].cancelled = true
+      if (hadHome) process.env.HOME = prevHome
+      else delete process.env.HOME
+      try { fs.rmSync(home, { recursive: true, force: true }) } catch (_) {}
+    },
+  }
+  return env
+}