@platless/axom-cli 0.3.13 → 0.6.36

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

@@ -0,0 +1,211 @@
+// Execute the real published adapter classes, without models or credentials.
+// node <probe> <pi-acp-package-directory> [--expect-no-subagents]
+//
+// Pristine pi-acp emits no subagent variants and drops custom messages; the patched
+// adapter normalizes pi-subagents children into draft ACP subagent variants with
+// ids derived only from the root session id and toolCallId/runId, so the same input
+// always produces byte-identical frames.
+import assert from 'node:assert/strict';
+import { readFile, writeFile, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+const directory = path.resolve(process.argv[2]);
+const expectNone = process.argv.includes('--expect-no-subagents');
+const require = createRequire(path.join(directory, 'package.json'));
+const scratch = await mkdtemp(path.join(tmpdir(), 'axom-pi-subagents-'));
+try {
+  const original = await readFile(path.join(directory, 'dist/index.js'), 'utf8');
+  let source = original.slice(0, original.lastIndexOf('// src/index.ts')).replace(/^#![^\n]*\n/, '');
+  source = source.replace(/from "([^"\n]+)"/g, (whole, specifier) => specifier.startsWith('@') || specifier === 'cross-spawn'
+    ? `from ${JSON.stringify(pathToFileURL(require.resolve(specifier)).href)}` : whole);
+  source += '\nexport { PiAcpAgent, PiAcpSession };\n';
+  await writeFile(path.join(scratch, 'package.json'), await readFile(path.join(directory, 'package.json')));
+  await writeFile(path.join(scratch, 'runtime.mjs'), source);
+  const { PiAcpSession } = await import(pathToFileURL(path.join(scratch, 'runtime.mjs')));
+
+  const COLLECT = () => {
+    const updates = [];
+    return { updates, conn: { async sessionUpdate(event) { updates.push(event); } } };
+  };
+  const newSession = () => {
+    const collect = COLLECT();
+    let events;
+    const proc = { onEvent(handler) { events = handler; } };
+    const session = new PiAcpSession({ sessionId: 'fixture', cwd: scratch, mcpServers: [], proc, conn: collect.conn });
+    return { session, collect, fire: ev => { events(ev); return session.flushEmits(); } };
+  };
+
+  // One full drive; every awaited fire drains the ordered emit chain first.
+  // verify=false collects the frames without the per-step assertions, for the pristine run.
+  const drive = async (verify = true) => {
+    const { session, collect, fire } = newSession();
+    const updates = collect.updates;
+    const names = () => updates.map(u => `${u.sessionId}:${u.update.sessionUpdate}`);
+
+    // Foreground launch: spawned precedes the adapter's own tool_call frame.
+    await fire({ type: 'tool_execution_start', toolCallId: 't1', toolName: 'subagent',
+      args: { agent: 'scout', task: 'map the repo' } });
+    if (verify) {
+      assert.deepEqual(updates[0].update, { sessionUpdate: 'subagent_spawned', subagentSessionId: 'pi-agent:fixture:t1',
+        name: 'scout', task: 'map the repo', capabilities: {}, _meta: { pi: { toolCallId: 't1' } } });
+      assert.equal(updates[0].sessionId, 'fixture');
+      assert.equal(updates[1].update.sessionUpdate, 'tool_call');
+    }
+
+    // Foreground completion: child preview then terminal state, then the adapter's frame.
+    await fire({ type: 'tool_execution_end', toolCallId: 't1', isError: false,
+      result: { content: [{ type: 'text', text: 'all clear' }], details: { mode: 'single', runId: 'fg1' } } });
+    if (verify) {
+      const afterEnd = names();
+      assert.deepEqual(afterEnd.slice(2, 4), ['pi-agent:fixture:t1:agent_message_chunk', 'fixture:subagent_state_update']);
+      assert.equal(updates[3].update.state, 'completed');
+    }
+
+    // Management and steering calls are not launches.
+    await fire({ type: 'tool_execution_start', toolCallId: 't2', toolName: 'subagent', args: { action: 'list' } });
+    await fire({ type: 'tool_execution_end', toolCallId: 't2', isError: false,
+      result: { content: [{ type: 'text', text: 'agents: ...' }], details: {} } });
+    await fire({ type: 'tool_execution_start', toolCallId: 't3', toolName: 'subagent',
+      args: { id: 'x', message: 'steer' } });
+    await fire({ type: 'tool_execution_end', toolCallId: 't3', isError: false,
+      result: { content: [{ type: 'text', text: 'queued' }], details: {} } });
+    if (verify) assert.ok(!updates.some(u => u.update.sessionUpdate === 'subagent_spawned' && u.update.name !== 'scout'));
+
+    // Async launch: the receipt is not a terminal state.
+    await fire({ type: 'tool_execution_start', toolCallId: 't4', toolName: 'subagent',
+      args: { agent: 'researcher', task: 'study', async: true } });
+    if (verify) assert.equal(updates.find(u => u.update.sessionUpdate === 'subagent_spawned' && u.update._meta?.pi?.toolCallId === 't4')?.update.subagentSessionId, 'pi-agent:fixture:t4');
+    await fire({ type: 'tool_execution_end', toolCallId: 't4', isError: false,
+      result: { content: [{ type: 'text', text: 'Async single: researcher [r9]' }],
+        details: { mode: 'single', runId: 'r9', asyncId: 'r9', asyncDir: '/tmp/async' } } });
+    if (verify) assert.ok(!updates.some(u => u.update.sessionUpdate === 'subagent_state_update' && u.update.subagentSessionId === 'pi-agent:fixture:t4'));
+
+    // The completion notice closes the async child by run id.
+    await fire({ type: 'message_end', message: { role: 'custom', customType: 'subagent-notify',
+      content: 'researcher finished', details: { runs: [{ runId: 'r9', agent: 'researcher', status: 'completed',
+        summary: 'study done', resultPath: '/tmp/async/r9/result.json' }] } } });
+    await fire({ type: 'message_start', message: { role: 'custom', customType: 'subagent-notify',
+      content: 'duplicate pair member', details: { runs: [{ runId: 'r9', agent: 'researcher', status: 'completed' }] } } });
+    if (verify) {
+      const closed = updates.find(u => u.update.sessionUpdate === 'subagent_state_update' && u.update.subagentSessionId === 'pi-agent:fixture:t4');
+      assert.equal(closed.update.state, 'completed');
+      assert.equal(closed.update._meta.pi.runId, 'r9');
+      assert.equal(closed.update._meta.pi.resultPath, '/tmp/async/r9/result.json');
+    }
+
+    // A repeated notice is idempotent.
+    const countBefore = updates.length;
+    if (verify) {
+      const beforePair = updates.length;
+      await fire({ type: 'message_start', message: { role: 'custom', customType: 'subagent-notify',
+        content: 'pair member', details: { runs: [{ runId: 'r9', agent: 'researcher', status: 'completed' }] } } });
+      assert.equal(updates.length, beforePair);
+    }
+    await fire({ type: 'message_end', message: { role: 'custom', customType: 'subagent-notify',
+      content: 'researcher finished', details: { runs: [{ runId: 'r9', agent: 'researcher', status: 'completed' }] } } });
+    if (verify) assert.equal(updates.length, countBefore + 0);
+
+    // Unknown runs (adapter restart) get an adopted spawn plus their state.
+    await fire({ type: 'message_end', message: { role: 'custom', customType: 'subagent-notify',
+      content: 'worker stopped', details: { runs: [{ runId: 'zz', agent: 'worker', status: 'stopped', summary: '' }] } } });
+    if (verify) {
+      const adopted = updates.find(u => u.update.sessionUpdate === 'subagent_spawned' && u.update._meta?.pi?.adopted);
+      assert.equal(adopted.update.subagentSessionId, 'pi-agent:fixture:run:zz');
+      assert.equal(adopted.update.name, 'worker');
+      assert.equal(updates.find(u => u.update.sessionUpdate === 'subagent_state_update' && u.update.subagentSessionId === 'pi-agent:fixture:run:zz').update.state, 'cancelled');
+    }
+
+    // Paused is not terminal; other custom messages are ignored.
+    await fire({ type: 'message_end', message: { role: 'custom', customType: 'subagent-notify',
+      content: 'paused', details: { runs: [{ runId: 'pp', agent: 'worker', status: 'paused' }] } } });
+    if (verify) {
+      assert.ok(updates.some(u => u.update.sessionUpdate === 'subagent_spawned' && u.update.subagentSessionId === 'pi-agent:fixture:run:pp'));
+      assert.ok(!updates.some(u => u.update.sessionUpdate === 'subagent_state_update' && u.update.subagentSessionId === 'pi-agent:fixture:run:pp'));
+    }
+    const beforeOther = updates.length;
+    await fire({ type: 'message_end', message: { role: 'custom', customType: 'something-else',
+      content: 'x', details: {} } });
+    await fire({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }] } });
+    assert.equal(updates.length, beforeOther);
+
+    // Progress dedup: identical-heartbeat tool_execution_update frames are dropped, real
+    // changes pass, other tools are never deduplicated.
+    await fire({ type: 'tool_execution_start', toolCallId: 't5', toolName: 'subagent',
+      args: { agent: 'worker', task: 'long job', async: false } });
+    await fire({ type: 'tool_execution_update', toolCallId: 't5', toolName: 'subagent',
+      partialResult: { content: [{ type: 'text', text: '(running...)' }],
+        details: { progress: [{ agent: 'worker', durationMs: 1000, lastActivityAt: 1791891393036, status: 'running tool bash' }] } } });
+    const afterFirstUpdate = updates.filter(u => u.update.sessionUpdate === 'tool_call_update').length;
+    await fire({ type: 'tool_execution_update', toolCallId: 't5', toolName: 'subagent',
+      partialResult: { content: [{ type: 'text', text: '(running...)' }],
+        details: { progress: [{ agent: 'worker', durationMs: 2000, lastActivityAt: 1791891394047,
+          recentOutput: ['(no output)', '(no output)'], status: 'running tool bash' }] } } });
+    await fire({ type: 'tool_execution_update', toolCallId: 't5', toolName: 'subagent',
+      partialResult: { content: [{ type: 'text', text: '(running...)' }],
+        details: { progress: [{ agent: 'worker', durationMs: 3000, lastActivityAt: 1791891395047,
+          recentOutput: ['(no output)', '(no output)', '(no output)'], status: 'running tool bash' }] } } });
+    await fire({ type: 'tool_execution_update', toolCallId: 't5', toolName: 'subagent',
+      partialResult: { content: [{ type: 'text', text: '(running...)' }],
+        details: { progress: [{ agent: 'worker', durationMs: 3100, lastActivityAt: 1791891396047,
+          recentOutput: ['(no output)', '(no output)', '(no output)'], status: 'running tool bash',
+          inputTokens: 2730, outputTokens: 69, cacheRead: 160, tokens: 2799, window: 2890, windowPeak: 2890 }],
+          results: [{ usage: { input: 2730, output: 69, cost: 0.0009, turns: 1 } }] } } });
+    await fire({ type: 'tool_execution_update', toolCallId: 't5', toolName: 'subagent',
+      partialResult: { content: [{ type: 'text', text: '(running...)' }],
+        details: { progress: [{ agent: 'worker', durationMs: 3200, lastActivityAt: 1791891397047,
+          recentOutput: ['(no output)', '(no output)', '(no output)'], status: 'running tool bash',
+          inputTokens: 5483, outputTokens: 1852, cacheRead: 3049, tokens: 7335, window: 5642, windowPeak: 5642 }],
+          results: [{ usage: { input: 5483, output: 1852, cost: 0.0040, turns: 1 } }] } } });
+    if (verify) {
+      assert.equal(updates.filter(u => u.update.sessionUpdate === 'tool_call_update').length, afterFirstUpdate,
+        'heartbeat frames differing only in timers/recentOutput/token telemetry are dropped');
+    }
+    await fire({ type: 'tool_execution_update', toolCallId: 't5', toolName: 'subagent',
+      partialResult: { content: [{ type: 'text', text: '(running...)' }],
+        details: { progress: [{ agent: 'worker', durationMs: 3500, lastActivityAt: 1791891396047,
+          recentOutput: ['(no output)', '(no output)', '(no output)'], status: 'running tool bash',
+          recentTools: [{ tool: 'bash', args: 'ls', endMs: 1 }] }] } } });
+    if (verify) {
+      assert.equal(updates.filter(u => u.update.sessionUpdate === 'tool_call_update').length, afterFirstUpdate + 1,
+        'a real milestone (recentTools growth / status change) still passes');
+    }
+    const updatesBeforeOther = updates.length;
+    await fire({ type: 'tool_execution_update', toolCallId: 'tx', toolName: 'read',
+      partialResult: { content: [{ type: 'text', text: 'x' }] } });
+    await fire({ type: 'tool_execution_update', toolCallId: 'tx', toolName: 'read',
+      partialResult: { content: [{ type: 'text', text: 'x' }] } });
+    if (verify) assert.equal(updates.length, updatesBeforeOther + 2, 'other tools are never deduplicated');
+    await fire({ type: 'tool_execution_end', toolCallId: 't5', isError: false,
+      result: { content: [{ type: 'text', text: 'long job done' }], details: { mode: 'single', runId: 'fg5' } } });
+    if (verify) {
+      assert.equal(updates.find(u => u.update.sessionUpdate === 'subagent_state_update' && u.update.subagentSessionId === 'pi-agent:fixture:t5')?.update.state, 'completed',
+        'a deduplicated run still closes normally');
+    }
+
+    return updates;
+  };
+
+  if (expectNone) {
+    const first = await drive(false);
+    const spawns = first.filter(u => u.update.sessionUpdate === 'subagent_spawned').length;
+    const states = first.filter(u => u.update.sessionUpdate === 'subagent_state_update').length;
+    assert.equal(spawns, 0);
+    assert.equal(states, 0);
+    assert.ok(first.some(u => u.update.sessionUpdate === 'tool_call'), 'adapter still maps tool calls');
+    console.log('PASS pristine pi-acp emits no subagent variants and ignores custom messages');
+  } else {
+    const first = await drive();
+    const spawns = first.filter(u => u.update.sessionUpdate === 'subagent_spawned').length;
+    const states = first.filter(u => u.update.sessionUpdate === 'subagent_state_update').length;
+    assert.equal(spawns, 5);           // t1, t4, adopted zz, paused pp, t5
+    assert.equal(states, 4);           // t1, r9(t4), zz, t5
+    const second = await drive();
+    assert.deepEqual(second, first);   // deterministic: no ids beyond the inputs
+    console.log('PASS subagent variants, ordering, idempotence and determinism');
+  }
+} finally {
+  await rm(scratch, { recursive: true, force: true });
+}

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)');