@platless/axom-cli 0.1.0 → 0.5.9

package/dist/axom-patch/cli/probes/zcode-subagent-subwork.mjs

@@ -0,0 +1,257 @@
+// Execute the real published adapter modules, without models or credentials.
+// node <probe> <zcode-acp-server-package-directory> [--expect-no-subagents]
+//
+// Pristine zcode-acp-server emits no subagent/async-task variants (the backend's
+// sub-agent lifecycle events carry no taskId, so every listener drops them) and
+// stamps `_meta.subagent` on every Agent dispatch; the patched adapter forwards
+// the backend's own `session.updated` agentId/taskId events as draft ACP
+// subagent variants (RFD #1992) and AIR async-task events, re-scopes the
+// sub-agent's internal `tool_subagent_*` calls onto its `sess_subagent_*` child
+// session, and drops the mark when the client negotiated native subagents.
+// Every emitted frame derives from backend-supplied ids only — no randomness,
+// so the same event replay produces byte-identical output.
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const directory = path.resolve(process.argv[2]);
+const expectNone = process.argv.includes('--expect-no-subagents');
+
+const serverUrl = pathToFileURL(path.join(directory, 'dist/server.js')).href;
+const dispatchUrl = pathToFileURL(path.join(directory, 'dist/handlers/dispatch.js')).href;
+const bgUrl = pathToFileURL(path.join(directory, 'dist/handlers/background-tasks.js')).href;
+const serverMod = await import(serverUrl);
+const dispatchMod = await import(dispatchUrl);
+const bgMod = await import(bgUrl);
+
+if (expectNone) {
+  assert.equal(serverMod.AxomZcodeSubagents, undefined, 'pristine package must not export AxomZcodeSubagents');
+  // Pristine dispatch: no child re-scoping, mark always stamped.
+  const cx = recorder();
+  await dispatchMod.dispatchEvent(fakeServer({ subagents: true }), cx, 'root-1', {
+    kind: 'ToolCallNew', tool: 'Agent', callId: 'tool_subagent_agent_a_call_b', title: 'inner', status: 'pending',
+  });
+  assert.equal(cx.sent.length, 1);
+  assert.equal(cx.sent[0].params.sessionId, 'root-1', 'pristine dispatch addresses sub-agent frames to the root');
+  assert.equal(cx.sent[0].params.update._meta.subagent, true, 'pristine dispatch stamps the subagent mark unconditionally');
+  console.log('PASS zcode-subagent-subwork (pristine: no variants, no re-scoping, mark unconditional)');
+  process.exit(0);
+}
+
+assert.ok(serverMod.AxomZcodeSubagents, 'patched package must export AxomZcodeSubagents');
+
+function recorder() {
+  const sent = [];
+  return { sent, notify: async (method, params) => { sent.push({ method, params }); } };
+}
+
+function fakeServer(caps) {
+  const childCx = recorder();
+  return {
+    clientCapabilities: caps,
+    sessionAliases: (acpSid) => [acpSid],
+    notifyByZcodeSid: async (sid, update) => { void sid; rootCx.sent.push({ method: 'session/update', params: { sessionId: 'root-1', update } }); return true; },
+    clients: { size: 1, broadcast: () => childCx },
+    supportsTerminalOutput: () => false,
+    noteDispatchedToolCall: () => {},
+    dispatchedToolCalls: new Map(),
+    terminalSentData: new Map(),
+    workflowRunNames: new Map(),
+    sessionPlanActive: new Set(),
+    notifyTurnActiveSince: new Map(),
+    lastMode: new Map(),
+    __childCx: childCx,
+  };
+}
+
+const CAPS_NATIVE = { subagents: {}, _meta: { jetbrains: { air: { version: 1, capabilities: ['nativeSubagentSessions', 'asyncTasks'] } } } };
+const CAPS_PLAIN = {};
+
+const rootCx = recorder();
+
+// ---------------------------------------------------------------- scenarios
+const agentSpawn = (over = {}) => ({ type: 'session.updated', payload: {
+  agentId: 'agent_u1', agentType: 'general-purpose', childSessionId: 'sess_subagent_agent_u1',
+  description: 'Count kts files', prompt: 'Count the .kts files.', parentToolCallId: 'call_p1', status: 'running', ...over } });
+const agentTerminal = (over = {}) => agentSpawn({ status: 'completed', totalDurationMs: 4477, totalToolUseCount: 1, totalTokens: 21127, ...over });
+const parentResult = (result) => ({ type: 'tool.updated', payload: { toolCallId: 'call_p1', kind: 'result', result } });
+const taskEvent = (over = {}) => ({ type: 'session.updated', payload: {
+  taskId: 'exec_t1', toolCallId: 'call_b1', toolName: 'Bash', taskKind: 'bash', cancellable: true,
+  command: 'sleep 6', description: 'Sleep 6 seconds', status: 'running', outputPath: '/tmp/out.log', ...over } });
+
+let rootCxReset = () => { rootCx.sent.length = 0; };
+
+// 1. Foreground: spawned at running; state held until the parent tool result,
+//    then child-scoped preview precedes the terminal state.
+{
+  const server = fakeServer(CAPS_NATIVE);
+  const obs = new serverMod.AxomZcodeSubagents(server, 'z-1');
+  obs.handleEvent(agentSpawn());
+  let names = rootCx.sent.map((s) => s.params.update.sessionUpdate);
+  assert.deepEqual(names, ['subagent_spawned']);
+  const spawned = rootCx.sent[0].params.update;
+  assert.equal(spawned.subagentSessionId, 'sess_subagent_agent_u1');
+  assert.equal(spawned.name, 'Count kts files');
+  assert.equal(spawned.task, 'Count the .kts files.');
+  assert.deepEqual(spawned.capabilities, {});
+  obs.handleEvent(agentTerminal()); // terminal arrives first (measured order)
+  assert.equal(rootCx.sent.length, 1, 'foreground completion is held for the parent result');
+  obs.handleEvent(parentResult({ success: true, content: '8\nagentId: agent_u1 (continue)\n<usage>subagent_tokens: 21127\ntool_uses: 1\nduration_ms: 4477</usage>' }));
+  names = rootCx.sent.map((s) => s.params.update.sessionUpdate);
+  assert.deepEqual(names, ['subagent_spawned', 'subagent_state_update']);
+  assert.equal(rootCx.sent[1].params.update.state, 'completed');
+  assert.equal(server.__childCx.sent.length, 1, 'the preview lands on the child session');
+  assert.equal(server.__childCx.sent[0].params.sessionId, 'sess_subagent_agent_u1');
+  assert.equal(server.__childCx.sent[0].params.update.content.text, '8');
+}
+
+// 1b. Foreground with a string-form result payload (both encodings measured).
+rootCxReset();
+{
+  const server = fakeServer(CAPS_NATIVE);
+  const obs = new serverMod.AxomZcodeSubagents(server, 'z-1');
+  obs.handleEvent(agentSpawn());
+  obs.handleEvent(parentResult(JSON.stringify({ success: true, content: 'nine\nagentId: agent_u1 (x)\n<usage>d</usage>' })));
+  obs.handleEvent(agentTerminal());
+  assert.equal(server.__childCx.sent[0].params.update.content.text, 'nine');
+  assert.deepEqual(rootCx.sent.map((s) => s.params.update.sessionUpdate), ['subagent_spawned', 'subagent_state_update']);
+}
+
+// 2. Background agent: state fires at the agent terminal, no preview chunk.
+rootCxReset();
+{
+  const server = fakeServer(CAPS_NATIVE);
+  const obs = new serverMod.AxomZcodeSubagents(server, 'z-1');
+  obs.handleEvent(agentSpawn({ background: true, outputFile: '/tmp/agent/out.txt' }));
+  obs.handleEvent({ type: 'session.updated', payload: { taskId: 'agent_u1', taskKind: 'subagent', status: 'running', toolCallId: 'call_p1' } });
+  assert.deepEqual(rootCx.sent.map((s) => s.params.update.sessionUpdate), ['subagent_spawned'],
+    'taskKind=subagent events belong to the agent path, never async_task');
+  obs.handleEvent(agentTerminal({ background: true, outputFile: '/tmp/agent/out.txt' }));
+  assert.deepEqual(rootCx.sent.map((s) => s.params.update.sessionUpdate), ['subagent_spawned', 'subagent_state_update']);
+  assert.equal(server.__childCx.sent.length, 0, 'background agents stream no child preview');
+}
+
+// 3. Adoption: first sighting already terminal emits spawned(adopted) then state.
+rootCxReset();
+{
+  const server = fakeServer(CAPS_NATIVE);
+  const obs = new serverMod.AxomZcodeSubagents(server, 'z-1');
+  obs.handleEvent(agentTerminal());
+  assert.deepEqual(rootCx.sent.map((s) => s.params.update.sessionUpdate), ['subagent_spawned', 'subagent_state_update']);
+  assert.equal(rootCx.sent[0].params.update._meta.zcode.adopted, true);
+}
+
+// 4. Failed / cancelled mapping; unknown statuses ignored; replay idempotent.
+rootCxReset();
+{
+  const server = fakeServer(CAPS_NATIVE);
+  const obs = new serverMod.AxomZcodeSubagents(server, 'z-1');
+  obs.handleEvent(agentSpawn({ agentId: 'agent_f', childSessionId: 'sess_subagent_agent_f', parentToolCallId: 'call_pf' }));
+  obs.handleEvent(agentSpawn({ agentId: 'agent_f', childSessionId: 'sess_subagent_agent_f', status: 'failed' }));
+  obs.handleEvent(agentSpawn({ agentId: 'agent_c', childSessionId: 'sess_subagent_agent_c', parentToolCallId: 'call_pc', status: 'cancelled' }));
+  obs.handleEvent(agentSpawn({ agentId: 'agent_r', childSessionId: 'sess_subagent_agent_r', status: 'paused' }));
+  const states = rootCx.sent.filter((s) => s.params.update.sessionUpdate === 'subagent_state_update').map((s) => s.params.update.state);
+  assert.deepEqual(states.sort(), ['cancelled', 'failed'], 'paused is not terminal; failed maps directly (foreground, non-completed)');
+  obs.handleEvent(agentSpawn({ agentId: 'agent_f', childSessionId: 'sess_subagent_agent_f', status: 'completed' }));
+  const statesAfter = rootCx.sent.filter((s) => s.params.update.sessionUpdate === 'subagent_state_update').map((s) => s.params.update.state);
+  assert.equal(statesAfter.filter((s) => s === 'completed').length, 0, 'terminal is single-shot');
+}
+
+// 5. Background bash task → AIR async_task pair.
+rootCxReset();
+{
+  const server = fakeServer(CAPS_NATIVE);
+  const obs = new serverMod.AxomZcodeSubagents(server, 'z-1');
+  obs.handleEvent(taskEvent());
+  obs.handleEvent(taskEvent({ status: 'running', pid: 1 })); // duplicate sighting
+  assert.deepEqual(rootCx.sent.map((s) => s.params.update.sessionUpdate), ['async_task_spawned']);
+  const spawned = rootCx.sent[0].params.update;
+  assert.equal(spawned.asyncTaskId, 'exec_t1');
+  assert.equal(spawned.toolCallId, 'call_b1');
+  assert.equal(spawned.outputFilePath, '/tmp/out.log');
+  assert.equal(spawned.canStop, true);
+  assert.equal(spawned.showInTranscript, false);
+  obs.handleEvent(taskEvent({ status: 'failed' }));
+  obs.handleEvent(taskEvent({ status: 'completed' })); // single-shot terminal
+  const states = rootCx.sent.filter((s) => s.params.update.sessionUpdate === 'async_task_state_update').map((s) => s.params.update.state);
+  assert.deepEqual(states, ['failed']);
+}
+
+// 6. Workflow tasks and non-session.updated events are ignored.
+rootCxReset();
+{
+  const server = fakeServer(CAPS_NATIVE);
+  const obs = new serverMod.AxomZcodeSubagents(server, 'z-1');
+  obs.handleEvent(taskEvent({ taskId: 'wf1', taskKind: 'workflow' }));
+  obs.handleEvent({ type: 'turn.started', payload: { inputSource: 'background_task' } });
+  obs.handleEvent({ type: 'model.streaming', payload: { kind: 'text_delta', delta: 'x' } });
+  obs.handleEvent(undefined);
+  assert.equal(rootCx.sent.length, 0);
+}
+
+// 7. Client without the draft capability: nothing is emitted (upstream behavior).
+rootCxReset();
+{
+  const server = fakeServer(CAPS_PLAIN);
+  const obs = new serverMod.AxomZcodeSubagents(server, 'z-1');
+  obs.handleEvent(agentSpawn());
+  obs.handleEvent(agentTerminal());
+  obs.handleEvent(taskEvent({ status: 'completed' }));
+  assert.equal(rootCx.sent.length, 0);
+}
+
+// 8. Dispatch re-scoping + mark gating against the patched dispatch module.
+{
+  const server = fakeServer(CAPS_NATIVE);
+  const cx = recorder();
+  await dispatchMod.dispatchEvent(server, cx, 'root-1', {
+    kind: 'ToolCallNew', tool: 'Bash', callId: 'tool_subagent_agent_u1_call_inner1', title: 'inner bash', status: 'pending',
+    input: { command: 'ls' },
+  });
+  assert.equal(cx.sent.length, 1);
+  assert.equal(cx.sent[0].params.sessionId, 'sess_subagent_agent_u1', 'internal sub-agent frames are re-scoped to the child session');
+  assert.equal(cx.sent[0].params.update.toolCallId, 'tool_subagent_agent_u1_call_inner1');
+  assert.equal(cx.sent[0].params.update._meta.subagent, undefined, 'Bash frames never carry the mark');
+
+  const cxAgent = recorder();
+  await dispatchMod.dispatchEvent(server, cxAgent, 'root-1', {
+    kind: 'ToolCallNew', tool: 'Agent', callId: 'call_p1', title: 'Agent: x', status: 'pending', input: {},
+  });
+  assert.equal(cxAgent.sent[0].params.update._meta.subagent, undefined,
+    'with native subagents negotiated the mark is suppressed (the native events own the projection)');
+
+  const plainServer = fakeServer(CAPS_PLAIN);
+  const cxPlain = recorder();
+  await dispatchMod.dispatchEvent(plainServer, cxPlain, 'root-1', {
+    kind: 'ToolCallNew', tool: 'Agent', callId: 'call_p1', title: 'Agent: x', status: 'pending', input: {},
+  });
+  assert.equal(cxPlain.sent[0].params.update._meta.subagent, true, 'clients without the draft capability still get the mark');
+}
+
+// 9. Background-task card suppression: with the AIR async-task capability declared,
+//    the upstream [background] card must not mint beside the async_task events.
+rootCxReset();
+{
+  const server = fakeServer(CAPS_NATIVE);
+  const listener = new bgMod.BackgroundTaskListener(server, 'z-1');
+  listener.handleEvent(taskEvent());
+  listener.handleEvent(taskEvent({ status: 'completed' }));
+  assert.equal(rootCx.sent.length, 0, 'with asyncTasks declared the bg listener mints no card — AxomZcodeSubagents owns the task');
+  // Sub-agent background tasks are equally owned by the subagent path.
+  listener.handleEvent({ type: 'session.updated', payload: { taskId: 'agent_u1', taskKind: 'subagent', toolCallId: 'call_p1', status: 'running', description: 'd' } });
+  assert.equal(rootCx.sent.length, 0);
+  // Workflow runs keep the upstream fold/poller path — terminal status, so no poller
+  // arms; an unfolded terminal-first sighting still mints the upstream fallback card.
+  listener.handleEvent({ type: 'session.updated', payload: { taskId: 'wf1', taskKind: 'workflow', toolCallId: 'call_w1', status: 'completed', description: 'w' } });
+  assert.equal(rootCx.sent.length, 1, 'workflow tasks keep the upstream background-card path (not suppressed)');
+
+  rootCxReset();
+  const plainServer = fakeServer(CAPS_PLAIN);
+  const plainListener = new bgMod.BackgroundTaskListener(plainServer, 'z-1');
+  plainListener.handleEvent(taskEvent());
+  assert.equal(rootCx.sent.length, 1, 'clients without the AIR capability still get the upstream [background] card');
+  assert.equal(rootCx.sent[0].params.update.sessionUpdate, 'tool_call');
+  assert.ok(rootCx.sent[0].params.update.toolCallId.startsWith('bg_'), 'the upstream card keeps its bg_* id');
+}
+
+console.log('PASS zcode-subagent-subwork (patched: variants, child scoping, mark gating, no double task cards)');

package/dist/axom-patch/cli/qoder-background-terminal.md

@@ -0,0 +1,82 @@
+# qoder-background-terminal
+
+## 为什么需要
+
+测试环境 Qoder CLI 1.1.61 的后台 Agent 调用在 ACP 中只返回 `async_launched`。
+原生根会话 JSONL 随后收到 `origin.kind=task-notification` 的系统完成通知，但 live ACP
+和 `session/load` 均未提供可供平台确认任务终态的更新。因此任务实际完成，Activity 仍显示
+Waiting / Task result unconfirmed。不是根据主 Agent 的自然语言回答判断完成。
+
+## 补丁边界
+
+实现位于 Workstation 的 ACP 会话边界；不修改 Qoder 二进制，不引入 SDK、数据库表或平台委派。
+仅 initialize 身份 `qoder-cli@1.1.61` 的真实托管会话启用，配置探测不启用。
+按进程有效 HOME、cwd、native session ID 定位 `~/.qoder/projects/<encoded-cwd>/<session>.jsonl`。
+只读当前根会话历史，逐行校验精确 session ID / cwd / 非 sidechain；不打开 `tasks/*.output`
+或其他子任务完整日志。路径中的叶子文件不跟随 symlink。
+
+同时满足以下三项，才沿原有 WireEvent / journal / seq / ack 发出同一 Agent 工具的
+`rawOutput.kind=agent-result` 更新：
+
+1. ACP 已观测到该根会话的后台 Agent 调用，且工具调用返回；cached resume 不重放
+   opening 时，从精确匹配的根 JSONL Agent tool_use 与结构化启动回执恢复相同关系。
+2. 原生结构化启动回执的 tool-use-id 对应该调用，并提供 agentId。
+3. 原生系统 task-notification 的 tool-use-id 对应该调用，含明确终态及结果。
+
+原生 ACP 已提供结构化终态时优先使用它。普通用户文字、其他会话、未知版本/格式不能触发补回。
+不根据标题、消息顺序、主 Agent 回答或超时推测完成。成功、失败、取消按明确通知状态处理；
+失败/取消格式当前由确定性用例验证，真机覆盖以验收报告为准。
+
+每次最多增量读取 4 MiB，读取块 64 KiB，单行上限 2 MiB；最多保存 512 个关联，单个结果
+128 KiB，全部结果 4 MiB，超过限制维持原始状态。当前没有待确认调用时不读文件。
+关闭、连接 abort、读取循环终止即停止定时器。没有文件、格式未知或读取失败不阻塞 ACP。
+重复轮询和同一文件重读不重复发布；重建运行时可重新确认同一工具，但不会创建第二个任务。
+历史补回走正常会话恢复路径，不直接修改数据库。
+
+2026-10-03 真机验收补充：默认 Agent 的输入可不带 `subagent_type`。它只是可选的类型
+文案，不能作为识别任务或跟踪完成通知的必填条件。识别仍要求 Qoder 的工具元数据、
+`kind=think`、prompt 和明确后台标记；非字符串类型仍拒绝。服务端的 Qoder 专用摘要
+投影同步允许该字段缺失，不推测子会话身份。升级验收必须覆盖默认 Agent（省略类型）
+和显式类型两种调用，避免测试只覆盖手工指定 `subagent_type` 的请求。
+
+## 上游升级后如何判断是否保留
+
+版本增加不会自动证明修复。新版本默认不启用此补丁，先使用无补丁 CLI 抓取原始 ACP：
+
+- 后台成功、失败、取消均有可对应 toolCallId 的明确终态及结果；启动回执不是任务终态。
+- 两个同时运行的后台任务乱序完成，状态和结果不会串任务。
+- 主轮次结束后迟到的后台完成仍会发送。
+- 重开旧会话的 session/load 能恢复相同终态，断线恢复不创建重复任务。
+
+全部通过后登记修复版本、原始抓包、无补丁回归和删除提交，再删除模块、调用接线及测试。
+只解决 live 而不解决 load 时不能整体退役。需要对新版本继续兼容时，先重新核验目录编码、
+JSONL 字段及通知格式，再显式扩充版本 gate；不对未知版本自动尝试。
+
+## 本地回归
+
+`npx vitest run src/workstation/qoderAdapter/backgroundTerminal.test.ts src/workstation/acp/processor/sideChannel.test.ts src/workstation/acp/processor/equivalence.test.ts`
+（修复折叠逻辑、经 raw 日志的 side note、golden 源 `qoder-background-terminal{,-large}`；旧 live 路径 `acpSession.test.ts` 已随 Task 29 删除）
+以及 CLI 全量测试、typecheck/build/补丁台账校验。此次随 CLI 0.3.2（整合主干 0.3.1）交付，无 npm 发布操作。
+
+## 旧会话详情配套投影
+
+真实 session/load 把同一个 Qoder opening 再次导入为无 turnId 的记录，原调用有唯一 turnId。
+详情原先要求恰好一个 opening，所以即使终态补回也会报 identity ambiguous。
+配套 `qoder-native-replay-detail` 只在 UI 折叠一个有 turn 的原调用及其更晚、无 turn、
+同 owner/call/input/title/locations 和完整 Qoder metadata 的精确副本。数据原样保留，
+多个真实 opening、跨 turn 的重复创建、任何输入或 vendor identity 冲突、其他 provider 的 opening 副本继续拒绝。
+待平台历史导入不再制造重复 opening 且无例外回归通过，再删除这个单独的投影兼容分支。
+此配套修改需要构建并部署 Web / Server，与仅 CLI 的终态修复分开核验。
+
+Cached resume 的补充规则与限制见 [qoder-foreground-output.md](qoder-foreground-output.md)。
+
+
+## 后台结果的到达轮次
+
+2026-10-04 真机复验：session/resume 后按旧 toolCallId 补回两个已完成后台结果，
+不产生重复 opening，但详情控制器曾把更新的到达轮次也当作另一份调用身份，报 ambiguous。
+配套通用详情校验仅允许完整历史中唯一、明确 run_in_background=true 的原调用接收更晚更新；
+更新须同 owner/call/name，kind 不冲突、输入缺省或与原输入完全相等。
+真实重复 opening、前台跨轮复用、修改输入、未知/截断身份与更新早于创建仍拒绝。
+不新增厂商分支，不改任何 provider 的路由或执行控制。新增两个红绿功能测试并真机检查详情。
+这是后台异步结果的正常生命周期校验，独立于 Qoder 补丁，不应随上游补丁退役一并删除。

package/dist/axom-patch/cli/qoder-foreground-output.md

@@ -0,0 +1,42 @@
+# qoder-foreground-output / qoder-cached-resume
+
+## 为什么需要
+
+2026-10-03 原生 Qoder CLI 1.1.61 抓包证实：两个前台 Agent 同时运行时，子任务
+文字/思考全部以根 sessionId 发送，没有 messageId 或归属 metadata。字符串在 ACP
+上线已交错，不能按标题、完成顺序或时间可靠拆回。每个 Agent 的工具最终结果却完整。
+另一个独立问题是 session/load 可能迟到重放历史，平台把它写到新轮次，制造重复 opening。
+本补丁不恢复暂存表，也不把未知来源的文字猜成子会话。
+
+## 行为与限制
+
+只启用 initialize 明确报告 qoder-cli@1.1.61 的进程；Claude、Codex、未知版本原样通过。
+实现位于 qoderAdapter/foregroundOutput.ts，ACP 层只接线。
+
+- 根会话明确发出 Agent 前台调用（background=false 或省略）至所有前台调用终止期间，
+  不投递没有 messageId/metadata 的根文字和思考。工具调用、命令、完整工具结果、权限、
+  配置和有身份的子会话事件原样保留。任务完成后的主回答正常展示。
+- 这是结果优先的降级：无法辨别的实时文字（包括此时可能出现的主 Agent 插话）不会展示；
+  **不宣称恢复完整子任务过程，也不宣称能独立操作这些摘要任务的 Stop/Resume**。
+  出错、取消、轮次结束会解除过滤；不会因 unfinished Agent 永久屏蔽下一轮。
+- 已有平台历史的普通 reconnect 使用官方 session/resume，保留同一个 native sessionId，
+  模型/权限配置来自恢复响应。拒绝恢复时直接报错，不偷偷新建另一段会话。
+- 真正历史接管/backfill、显式 settings load、无 resume 能力继续旧路径。本补丁不以模糊
+  文本去重掩盖这些路径的迟到历史；没有证据声称所有 session/load 都已彻底解决。
+- resume 不回放 opening，故后台修复（daemon 的 `BackgroundSideNotes` 读取 + processor 折叠 `qoder_side` note）可从只读根 JSONL 恢复精确后台
+  Agent 输入与启动关系，继续按 tool-use-id 补回明确通知。只发送同一个工具的终态更新，
+  不发送历史 opening、不生成子会话。既有通知可能重新确认相同任务；不是重复执行任务。
+  初次增量扫描完成后，没有待确认任务即停止文件轮询读操作。原有读限制/身份校验仍适用。
+
+## 回归与退役
+
+acp/processor/foreground.test.ts（取代已删除的 qoderForegroundBaseline.test.ts）在 processor 上覆盖原始交错抓包和三前台任务边界、
+省略类型、失败/取消后续轮、完整结果、主回答、已标识文字、background 不过滤，以及 1.1.62/codex/claude 不过滤；
+processor/sideChannel.test.ts 与 golden 等价测试（acp/processor/equivalence.test.ts，含 qoder-parallel-foreground）锁定 processor 输出。
+acpAgents.test.ts 覆盖 cached resume / 真正 backfill / settings load 与其他 provider 边界；
+backgroundTerminal.test.ts 覆盖无 opening 回放的后台精确结果恢复。
+
+上游升级后默认不启用。先裸 ACP 测并行前台长文字：必须提供稳定的来源/session/message
+标识，且终态与实际结果正确；再测 reconnect 不产生旧 opening，backfill 仍能取全历史，
+迟到后台通知仍能补全。通过原始抓包、无补丁回归及平台真机后记录版本再删除补丁。
+仅增加 CLI 版本号或最终任务成功不能证明可以退役。

package/dist/axom-patch/cli/qoder-steering.json

@@ -0,0 +1,52 @@
+{
+  "id": "qoder-steering",
+  "package": "@qoder-ai/qodercli",
+  "versions": [
+    "1.1.71"
+  ],
+  "bin": "qodercli",
+  "edits": [
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "a7ff3d5883231c1add98d266d5f860813c6fa7e498ae075384b7c558e8531c88",
+      "after_sha256": "b43037a4df32734a47bd5eb0f937583252bbbe637c36514cc8aba7fced3acfe9",
+      "before": "protocolVersion:_vs,authMethods:e,agentInfo:{name:d0,title:Nn,version:t},agentCapabilities:",
+      "after": "protocolVersion:xbs,authMethods:e,agentInfo:{name:HQ,title:Hn,version:t},_meta:{steering:{supported:true,timings:[\"now\"]}},agentCapabilities:"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "b43037a4df32734a47bd5eb0f937583252bbbe637c36514cc8aba7fced3acfe9",
+      "after_sha256": "f1ec60df59dce8dc241fa504d947e5eb5aad7c098dbaa5e89a28d3fd8bb9000c",
+      "before": "async prompt(A){await this.ensureAuthenticated();let e=this.sessions.get(A.sessionId);",
+      "after": "async extMethod(method,params){\n  if(method !== \"_session/steering\") throw as.methodNotFound(method);\n  await this.ensureAuthenticated();\n  if(!params || typeof params.sessionId !== \"string\" || !params.sessionId) throw as.invalidParams(undefined,\"Missing sessionId\");\n  const session=this.sessions.get(params.sessionId);\n  if(!session) throw as.invalidParams(undefined,\"Unknown sessionId\");\n  return session.axomQoderSteer(params);\n}\nasync prompt(A){await this.ensureAuthenticated();let e=this.sessions.get(A.sessionId);"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "f1ec60df59dce8dc241fa504d947e5eb5aad7c098dbaa5e89a28d3fd8bb9000c",
+      "after_sha256": "ea26b18b8e10d410c6eaf03d9df720d6b061979dd9cbc62ff4a1a98682b2f3e4",
+      "before": "promptRunning=!1;pendingMessages=[];",
+      "after": "promptRunning=!1;pendingMessages=[];axomQoderSteeringMessages=[];"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "ea26b18b8e10d410c6eaf03d9df720d6b061979dd9cbc62ff4a1a98682b2f3e4",
+      "after_sha256": "3660901654aecf58b04ac669f2dc945c8ba16376e204ccef53f499a13d1d69e9",
+      "before": "async promptViaQueryEngine(A,e,t,i,n){",
+      "after": "axomQoderSteer(A){\n  const steering=A._meta?.steering;\n  if(steering?.priority !== undefined && steering.priority !== \"now\") throw as.invalidParams(undefined,\"Qoder supports only now steering\");\n  if(steering?.idleBehavior !== undefined && steering.idleBehavior !== \"promptRequired\") throw as.invalidParams(undefined,\"Unsupported steering idleBehavior\");\n  if(!Array.isArray(A.prompt) || !A.prompt.length || A.prompt.some(block=>!block || block.type !== \"text\" || typeof block.text !== \"string\")) throw as.invalidParams(undefined,\"Qoder steering requires text blocks\");\n  const text=A.prompt.map(block=>block.text).join(\"\\n\");\n  if(!text.trim() || text.length > 131072) throw as.invalidParams(undefined,\"Invalid steering text length\");\n  if(this.disposed || !this.active || !this.promptRunning || !this.queryEngine?.activeAbortController || !this.pendingPrompt || this.pendingPrompt.signal.aborted) return {outcome:\"promptRequired\",reason:\"noRunningTurn\"};\n  if(this.axomQoderSteeringMessages.length >= 32) throw as.invalidParams(undefined,\"Too many pending steering messages\");\n  const message={prompt:A.prompt.map(block=>({type:\"text\",text:block.text})),id:mte()};\n  this.axomQoderSteeringMessages.push(message);\n  try{this.queryEngine.abort({source:\"sdk_interrupt\",origin:\"user\"});}\n  catch(error){this.axomQoderSteeringMessages.pop();throw error;}\n  return {outcome:\"injected\"};\n}\nasync promptViaQueryEngine(A,e,t,i,n){\n  let result;\n  try{\n    result=await this.axomQoderPromptOnce(A,e,t,i,n);\n    const originalId=result.userMessageId;\n    while(!e.aborted && !this.disposed && this.active && this.axomQoderSteeringMessages.length){\n      const message=this.axomQoderSteeringMessages.shift();\n      const next=await this.axomQoderPromptOnce(message.prompt,e,mte(),message.id);\n      if(result.usage && next.usage){\n        const inputTokens=result.usage.inputTokens+next.usage.inputTokens;\n        const outputTokens=result.usage.outputTokens+next.usage.outputTokens;\n        next.usage={inputTokens,outputTokens,totalTokens:inputTokens+outputTokens};\n        const models=new Map;\n        for(const item of [...result._meta?.quota?.model_usage??[],...next._meta?.quota?.model_usage??[]]){\n          const prior=models.get(item.model)??{input_tokens:0,output_tokens:0};\n          models.set(item.model,{input_tokens:prior.input_tokens+item.token_count.input_tokens,output_tokens:prior.output_tokens+item.token_count.output_tokens});\n        }\n        next._meta={...next._meta,quota:{token_count:{input_tokens:inputTokens,output_tokens:outputTokens},model_usage:Array.from(models,([model,token_count])=>({model,token_count}))}};\n      }\n      result=next;\n    }\n    return {...result,...(originalId?{userMessageId:originalId}:{})};\n  }finally{this.axomQoderSteeringMessages.length=0;}\n}\nasync axomQoderPromptOnce(A,e,t,i,n){"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "3660901654aecf58b04ac669f2dc945c8ba16376e204ccef53f499a13d1d69e9",
+      "after_sha256": "7b031034151e76daccbf26c7dbf08779b3e75a281da97b8a56673efdf8433956",
+      "before": "if(!A.includes(\"Operation aborted\"))throw new cs(500,A);",
+      "after": "if(!A.includes(\"Operation aborted\")&&!(this.axomQoderSteeringMessages.length&&[\"aborted_tools\",\"aborted_streaming\"].includes(c.terminal_reason)))throw new as(500,A);"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "7b031034151e76daccbf26c7dbf08779b3e75a281da97b8a56673efdf8433956",
+      "after_sha256": "a2949de7f397a904753d5d1d838d637cc93b3cf43e8b51af8e58a188d6c2e282",
+      "before": "else if(\"error_during_execution\"===A.subtype&&\"refusal\"!==A.stop_reason){let e=A.errors??[];",
+      "after": "else if(\"error_during_execution\"===A.subtype&&\"refusal\"!==A.stop_reason&&!(this.axomQoderSteeringMessages.length&&[\"aborted_tools\",\"aborted_streaming\"].includes(A.terminal_reason))){let e=A.errors??[];"
+    }
+  ]
+}

package/dist/axom-patch/cli/qoder-steering.md

@@ -0,0 +1,30 @@
+# Qoder 原生 ACP 插话
+
+Qoder 1.1.61 的原生 ACP 将运行中的 `session/prompt` 排队，没有声明或实现
+`_session/steering`。只在实验 SDK adapter 中支持插话，不能让普通 `qoder` 入口出现按钮。
+
+`qoder-steering.json` 在 `qoder-subagent-origin.json` 之后应用，逐步核验官方 npm
+包的 SHA-256。只修改 Axom 拥有的不可变副本，不改用户安装的 CLI 或 npm 缓存。
+原生 ACP 的 new/load/resume、模型、权限、MCP、工具和子任务归属继续由 Qoder 处理。
+
+补丁在 initialize 顶层声明 `_meta.steering={supported:true,timings:["now"]}`，
+并实现 `_session/steering`。文本通过校验后加入当前会话的专用插话队列，调用原生
+QueryEngine.abort 中断当前执行；原有平台 prompt 保持待完成。原生执行收束后，在
+同一个 QueryEngine、历史、配置与平台回合内处理插话，新的回复完成才返回 prompt。
+这会中断尚未完成的工具；不承诺撤销已经完成的文件或命令副作用。
+
+没有运行回合时返回 `promptRequired`，不自行启动无人跟踪的回合。当前仅支持文本和
+`now`；无效输入不打断执行。Stop 与关闭会话优先于插话，真实执行错误继续上报。
+消息队列限 32 条、每条文本限 128 KiB；每次 prompt 收束清理专用队列。它不增加
+数据库字段或第二份 transcript。通用 ACP、服务端和 UI 不增加 Qoder 判断。
+
+目前只认证 npm 1.1.61 这份原文件。新包必须重新核验源文件和运行时语义，不按版本号
+猜兼容。显式 command 覆盖继续尊重用户设置，不偷偷把本地 CLI 换成 managed 包。
+
+当无补丁的原生 Qoder ACP 自己声明并实现相同插话协议，且普通入口的运行中工具、
+消息落点、Stop、load/resume、模型/权限、子任务与完整基线验收通过时，可移除这份
+配方、runtime 引用和台账项；单独 SDK 探针或版本升级不构成移除依据。
+
+验证包括 CLI 的 `nativeSteeringPatch.test.ts`、对官方补丁包执行
+`node axom-patch/cli/probes/qoder-steering.mjs <package>`，以及测试环境普通 `qoder`
+入口的真实模型、REST 和 canvas 界面验收。测试入口名称及具体会话必须写入验收记录。

package/dist/axom-patch/cli/qoder-subagent-origin.json

@@ -0,0 +1,73 @@
+{
+  "id": "qoder-subagent-origin",
+  "package": "@qoder-ai/qodercli",
+  "versions": [
+    "1.1.71"
+  ],
+  "edits": [
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "bbac475858838d609241881d1ee89b26c32a2eae8697672522778b18ed78a94a",
+      "after_sha256": "4807a4c1cfdb57a6bd9102ec3924185e3e2649935164fed3e98ca353063ff5f0",
+      "before": "toolCallNames=new Map;",
+      "after": "toolCallNames=new Map;axomQoderToolOrigins=new Map;"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "4807a4c1cfdb57a6bd9102ec3924185e3e2649935164fed3e98ca353063ff5f0",
+      "after_sha256": "6485062df36f164432cfe8d8a7adbf32f0bf85053500c11b61b8fce15bcdcbed",
+      "before": "async sendUpdate(A){let e={sessionId:this.id,update:A};await this.connection.sessionUpdate(e)}",
+      "after": "axomQoderId(value){return typeof value === \"string\" && value.length > 0 && value.length <= 256 && !/[\\x00-\\x1f\\x7f]/.test(value)}\naxomQoderObserveSdk(message){\n  if(message.type !== \"assistant\" || !Array.isArray(message.message?.content)) return;\n  const parent=message.parent_tool_use_id;\n  if(parent !== null && !this.axomQoderId(parent)) return;\n  for(const block of message.message.content){\n    if(block?.type !== \"tool_use\" || !this.axomQoderId(block.id) || !this.axomQoderId(block.name)) continue;\n    const prior=this.axomQoderToolOrigins.get(block.id);\n    if(this.axomQoderToolOrigins.has(block.id)){\n      if(prior && (prior.parent !== parent || prior.name !== block.name)) this.axomQoderToolOrigins.set(block.id,null);\n      continue;\n    }\n    if(this.axomQoderToolOrigins.size >= 4096) continue;\n    this.axomQoderToolOrigins.set(block.id,{parent,name:block.name});\n  }\n}\naxomQoderSdkUpdate(message,update){\n  if(this.axomQoderId(message.parent_tool_use_id)) update={...update,_meta:{...update._meta,qoder:{...update._meta?.qoder,version:1,source:\"native-acp-patch\",parentToolUseId:message.parent_tool_use_id,route:\"child\"}}};\n  return this.sendUpdate(update);\n}\nasync sendUpdate(A){\n  if(A.sessionUpdate === \"tool_call\" || A.sessionUpdate === \"tool_call_update\"){\n    const origin=this.axomQoderToolOrigins.get(A.toolCallId);\n    if(origin) A={...A,_meta:{...A._meta,qoder:{...A._meta?.qoder,version:1,source:\"native-acp-patch\",toolName:origin.name,...(origin.parent ? {parentToolUseId:origin.parent,route:\"child\"} : {})}}};\n  }\n  let e={sessionId:this.id,update:A};await this.connection.sessionUpdate(e)\n}"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "6485062df36f164432cfe8d8a7adbf32f0bf85053500c11b61b8fce15bcdcbed",
+      "after_sha256": "2acc4d22cf66ca8c2c73543ba6bd1023d64c7730204521444ce2386c724bb0fd",
+      "before": "async dispatchSDKMessage(A){switch(A.type){",
+      "after": "async dispatchSDKMessage(A){this.axomQoderObserveSdk(A);switch(A.type){"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "2acc4d22cf66ca8c2c73543ba6bd1023d64c7730204521444ce2386c724bb0fd",
+      "after_sha256": "7908a80dee46d50fcf8d57ba94c45f52ac3261b358a105719e07c9d4db0b0538",
+      "before": "await this.sendUpdate({sessionUpdate:\"agent_message_chunk\",content:{type:\"text\",text:e.delta.text}})",
+      "after": "await this.axomQoderSdkUpdate(A,{sessionUpdate:\"agent_message_chunk\",content:{type:\"text\",text:e.delta.text}})"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "7908a80dee46d50fcf8d57ba94c45f52ac3261b358a105719e07c9d4db0b0538",
+      "after_sha256": "d01e482a334b7973c40bc61f99482da0ccfda08984c289148cc1ca30866f7286",
+      "before": "await this.sendUpdate({sessionUpdate:\"agent_thought_chunk\",content:{type:\"text\",text:e.delta.thinking}})",
+      "after": "await this.axomQoderSdkUpdate(A,{sessionUpdate:\"agent_thought_chunk\",content:{type:\"text\",text:e.delta.thinking}})"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "d01e482a334b7973c40bc61f99482da0ccfda08984c289148cc1ca30866f7286",
+      "after_sha256": "24113eca8518c82ed990ba68e1728cac9bd55f57fb2026030cfa5be430b85e85",
+      "before": "async streamHistory(A){let e=Ocd(A);for(let t of A){",
+      "after": "async streamHistory(A){let e=Ocd(A);for(let t of A){this.axomQoderObserveSdk(t);"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "24113eca8518c82ed990ba68e1728cac9bd55f57fb2026030cfa5be430b85e85",
+      "after_sha256": "2337caf11a15d6f5f08dd0fade9968d3caaf2c4f4d370df4b86b28d7e8838bd2",
+      "before": "await this.sendUpdate({sessionUpdate:\"user_message_chunk\",content:{type:\"text\",text:A},messageId:t.uuid})",
+      "after": "await this.axomQoderSdkUpdate(t,{sessionUpdate:\"user_message_chunk\",content:{type:\"text\",text:A},messageId:t.uuid})"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "2337caf11a15d6f5f08dd0fade9968d3caaf2c4f4d370df4b86b28d7e8838bd2",
+      "after_sha256": "628db161081afd5a44573e916de1afc096c0f2451c0f62f774f5116ecbfd414a",
+      "before": "await this.sendUpdate({sessionUpdate:\"agent_message_chunk\",content:{type:\"text\",text:A},messageId:t.uuid})",
+      "after": "await this.axomQoderSdkUpdate(t,{sessionUpdate:\"agent_message_chunk\",content:{type:\"text\",text:A},messageId:t.uuid})"
+    },
+    {
+      "file": "bundle/qodercli.js",
+      "before_sha256": "628db161081afd5a44573e916de1afc096c0f2451c0f62f774f5116ecbfd414a",
+      "after_sha256": "a7ff3d5883231c1add98d266d5f860813c6fa7e498ae075384b7c558e8531c88",
+      "before": "await this.sendUpdate({sessionUpdate:\"agent_thought_chunk\",content:{type:\"text\",text:A.thinking},messageId:t.uuid})",
+      "after": "await this.axomQoderSdkUpdate(t,{sessionUpdate:\"agent_thought_chunk\",content:{type:\"text\",text:A.thinking},messageId:t.uuid})"
+    }
+  ],
+  "bin": "qodercli"
+}

package/dist/axom-patch/cli/qoder-subagent-subwork.md

@@ -0,0 +1,73 @@
+# qoder-subagent-origin / qoder-subagent-subwork
+
+## 为什么需要
+
+Qoder CLI 1.1.61 的内部运行流已经带 `parent_tool_use_id`，但它自己的 ACP
+`dispatchSDKMessage` / `streamHistory` 在生成文字、思考和工具事件时丢掉了这个字段。
+因此原生 `qodercli --acp` 的子任务 Read / Bash 出现在主会话。ACP 上层无法从时间、
+标题或返回顺序补出可靠关系，尤其不能拆解并发任务。
+
+此前只在 Axom 的 SDK adapter 里加 `_meta.qoder`，没有覆盖用户正在用的原生入口。
+那个实验能证明 SDK 归属信息存在，但不能证明原生入口已经修好。
+
+## 补丁的位置与行为
+
+1. `qoder-subagent-origin.json` 对官方 npm `@qoder-ai/qodercli@1.1.61` 的
+   `bundle/qodercli.js` 做精确版本、原文件及每一步产物 SHA-256 校验。
+   在 Qoder 原生 ACP 转换层保留每个工具的父 ID，在文字/思考及历史事件上写
+   `_meta.qoder={version:1,source:"native-acp-patch",parentToolUseId,route:"child"}`。
+   根工具保留工具名和补丁版本，但不伪造父 ID。冲突和容量不足不猜归属。
+2. `qoderAdapter/subwork.ts` 消费该元数据，生成已有的 ACP
+   `subagent_spawned` / `subagent_state_update`，并给 child item 填确定性地址：
+   `qoder-agent:<root native sessionId>:<Agent toolCallId>`。
+   解析器仍在根进程；任务正文、执行工具、结果和带身份的文字/思考落在 subwork。
+3. Agent 工具调用被归一为同一个 subwork 派发与结果，不再额外产生委派摘要卡。
+   后台 `async_launched` 只是启动回执，不能据此结束子工作；已存在的后台真实终态修补
+   走同一归一入口。权限回调保持原生根会话的请求/回答路径，不启用独立子任务控制。
+
+服务端、数据库、公共工作模型及 App 不新增 Qoder 判断；此次新增的核心 Qoder
+元数据分支已经撤回。通用 ACP 会话只接线到 Qoder 自己的边界。
+
+## 分发和版本门槛
+
+`runtime.json` 引用补丁配方。`managedPatches.ts` 在 Install/Update/首次 managed
+launch 时复制完整 npm 包及依赖，校验并写收据，启动不可变副本。npm 原缓存和用户
+原有 Qoder 二进制保持原样。Qoder 包同时发布 `qodercli` 和 dispatcher 两个 bin，
+配方显式选择 `bin:"qodercli"`；通用补丁加载器只增加可信配方的 bin 选择能力。
+没有显式 bin 的其他补丁仍执行原来的单入口检查。
+
+- 只认证原生 Qoder CLI 1.1.61 的这份发布包，不把 1.1.64 当作兼容版本。
+- CLI 版本 bump 到 0.3.7，补丁跟随正常 Client release 分发。
+- 显式自定义 command 按用户配置运行，不会偷偷替换用户二进制。要启用原生补丁，
+  工作站 Qoder 项使用 catalog 管理的原生 npm ACP 入口（清除旧二进制 command/args）。
+- 继续走 Qoder 原生 ACP 的 new/load/resume、模型和权限模式；不把原生会话切换到
+  不支持恢复的 SDK adapter。已有历史不追溯猜分或改写；修复后的新事件才按证据分流。
+- SDK adapter 的既有实验同样可经过本边界，但不是原生入口验收的替代品。
+
+## 什么时候可以移除
+
+当无补丁的 Qoder ACP 能发送稳定的派生关系、每帧子任务归属、真实终态以及可回放
+的同一关系，并通过并发乱序、失败/取消、后台迟到、load/resume/重连验收后：删除
+配方、runtime 引用、Qoder subwork 归一器和接线，台账标 retired。继续保留通用
+ACP/Claude/Codex 基线。不以升级版本号或主 Agent 返回成功作为移除依据。
+
+## 验证
+
+```bash
+cd axom-cli
+npm test
+cd ..
+node axom-patch/cli/probes/qoder-subagent-origin.mjs /path/to/patched/qoder-package
+AXOM_BASELINE_SQLITE_BIN=/path/to/new-sqlite/bin \
+AXOM_BASELINE_PYTHON_BIN=/path/to/new-python/bin scripts/test-acp-baseline.sh
+```
+
+运行时探针执行官方 bundle 里实际的 ACP dispatch 方法，验证并发 child 的工具与
+结果、文字、根输出和冲突边界；不启动模型、不读取凭据。真实功能验收必须另经
+测试工作站、服务端、数据库、REST 和页面，记录具体会话。fixture 通过不等于上线验收。
+
+## 原生后台过程补齐
+
+Qoder 1.1.61 不向主 ACP 流转发后台子任务的 SDK 消息。`backgroundProcess.ts` 只读轮询经过原生启动回执确认的 `agent-<agentId>.jsonl`；每行必须同时匹配 native session、cwd、agentId、parent_tool_use_id、isSidechain 与版本。只发出实际记录的工具调用、结果、思考和回复，经 `_meta.qoder` 进入同一 subwork 边界。父会话空闲后仍可接收这些项；完成状态继续采用原生 task-notification，不从最后一条文本推断完成。
+
+解析有单行、单轮字节与行数上限，拒绝符号链接、未知工具结果与不完整行，并按原生 uuid 去重。这一补齐针对本次已观察的后台调用；历史未观察任务不会被猜测迁移。上游转发后台消息后应移除 transcript 轮询，并保留并行归属和晚到事件验收。