@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.1

package/test/task-runner.test.ts

@@ -0,0 +1,259 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { PACKAGE_ROOT } from '../src/paths.ts';
+import { childArgs, resolveAttachments, startChild, validateAgentId, withAttachments } from '../src/task/runner.ts';
+
+const FAKE_PI = join(PACKAGE_ROOT, 'test/fixtures/fake-pi.mjs');
+const base = { sessionDir: '/state/subagents', agentId: '11111111-2222-4333-8444-555555555555' };
+
+describe('childArgs (SEC-001, TASK-008)', () => {
+  test('always runs one RPC session per agent ID with this package loaded, so its owner can steer and stop it (C-H4)', () => {
+    expect(childArgs(base)).toEqual(['--mode', 'rpc', '--session-dir', '/state/subagents', '--session-id', base.agentId, '-e', PACKAGE_ROOT]);
+  });
+
+  test('adds trust, model, thinking, and readonly tools in that order', () => {
+    expect(childArgs({ ...base, trusted: true, model: { provider: 'p', id: 'm', thinking: 'high' }, readonly: true })).toEqual([
+      '--mode',
+      'rpc',
+      '--session-dir',
+      '/state/subagents',
+      '--session-id',
+      base.agentId,
+      '-e',
+      PACKAGE_ROOT,
+      '--approve',
+      '--model',
+      'p/m',
+      '--thinking',
+      'high',
+      '--tools',
+      'read,grep,find,ls,bash,TodoWrite',
+      '--no-mcp',
+    ]);
+  });
+});
+
+test('a writable launch adds back the tools a plan-mode launch took; a readonly one never does (C-M1)', () => {
+  expect([childArgs({ ...base, restoreTools: ['edit', 'write'] }).slice(-2), childArgs({ ...base, readonly: true, restoreTools: ['edit'] }).includes('+edit')]).toEqual([['--tools', '+edit,+write'], false]);
+});
+
+describe('attachments (TASK-016)', () => {
+  let dir = '';
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'attach-'));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test('builds the message Pi builds from @file arguments: the prompt, each text file in a <file> block, images as attachments', () => {
+    const png = Buffer.from('89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c489', 'hex');
+    writeFileSync(join(dir, 'note.txt'), '\uFEFFhello\n');
+    writeFileSync(join(dir, 'empty.txt'), '');
+    writeFileSync(join(dir, 'shot.png'), png);
+    const input = withAttachments('  look at these\n', [join(dir, 'note.txt'), join(dir, 'empty.txt'), join(dir, 'shot.png')]);
+    expect(input).toEqual({
+      text: `look at these<file name="${join(dir, 'note.txt')}">\nhello\n\n</file>\n<file name="${join(dir, 'shot.png')}"></file>\n`,
+      images: [{ type: 'image', mimeType: 'image/png', data: png.toString('base64') }],
+    });
+    expect(withAttachments('plain', [])).toEqual({ text: 'plain', images: [] });
+  });
+});
+
+describe('input validation (SEC-001, TASK-016)', () => {
+  let dir = '';
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'attach-'));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  test.for(['../escape', '', 'a/b', '-flag', 'x'.repeat(200)])('rejects the agent ID %j', (id) => {
+    expect(() => validateAgentId(id)).toThrow('is not a valid agent ID');
+  });
+
+  test('accepts a UUID agent ID', () => {
+    expect(validateAgentId(base.agentId)).toBe(base.agentId);
+  });
+
+  test('passes the parent project trust decision on (review r2: security)', () => {
+    expect([childArgs({ ...base, trusted: true }).includes('--approve'), childArgs({ ...base, trusted: false }).includes('--no-approve')]).toEqual([true, true]);
+  });
+
+  test('rejects a directory attachment and expands ~ as Pi read paths do (review r2: security 4)', () => {
+    mkdirSync(join(dir, 'adir'));
+    mkdirSync(join(dir, 'home'));
+    writeFileSync(join(dir, 'home/x.txt'), 'x');
+    expect(() => resolveAttachments(['adir'], dir)).toThrow(`file_attachments: ${join(dir, 'adir')} is not a file`);
+    expect(resolveAttachments(['~/x.txt'], dir, join(dir, 'home'))).toEqual([join(dir, 'home/x.txt')]);
+  });
+
+  test('resolves attachments against the working directory and rejects missing files', () => {
+    writeFileSync(join(dir, 'shot.png'), 'png');
+    expect(resolveAttachments(['shot.png', join(dir, 'shot.png')], dir)).toEqual([join(dir, 'shot.png'), join(dir, 'shot.png')]);
+    expect(() => resolveAttachments(['missing.png'], dir)).toThrow(`file_attachments: ${join(dir, 'missing.png')} does not exist`);
+  });
+});
+
+function run(mode: string, prompt = 'hello', signal?: AbortSignal, onEvent?: (event: { type: string }) => void) {
+  return startChild({ command: [process.execPath, FAKE_PI], args: ['--x', 'y'], prompt, cwd: tmpdir(), env: { ...process.env, FAKE_PI_MODE: mode }, ...(signal ? { signal } : {}), ...(onEvent ? { onEvent } : {}) });
+}
+
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+async function eventually(check: () => boolean, timeoutMs = 8_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (check()) return true;
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  }
+  return check();
+}
+
+describe('startChild', () => {
+  test('sends the prompt as an RPC prompt and returns the final assistant text with summed usage', async () => {
+    const outcome = await run('echo', 'line one\n"quoted" $HOME').done;
+    expect(outcome.finalText).toBe('GOT:line one\n"quoted" $HOME|ARGS:--x y');
+    expect(outcome.usage).toEqual({ input: 20, output: 10, cacheRead: 2, cacheWrite: 4, totalTokens: 36, cost: { input: 0.2, output: 0.4, cacheRead: 0, cacheWrite: 0, total: 0.6 } });
+    expect(outcome.failure).toBeUndefined();
+  });
+
+  test('a command that cannot start has no pid and fails clearly (review recheck: no record for a child that never ran)', async () => {
+    const handle = startChild({ command: [join(tmpdir(), 'no-such-pi-binary')], args: [], prompt: 'x', cwd: tmpdir(), env: process.env });
+    expect(handle.pid).toBeUndefined();
+    expect((await handle.done).failure).toBe(`could not start pi: spawn ${join(tmpdir(), 'no-such-pi-binary')} ENOENT`);
+  });
+
+  test('a child that exits without reading a large prompt fails cleanly instead of crashing Pi (review r2: security 1)', async () => {
+    const handle = startChild({ command: [process.execPath, '-e', 'process.exit(3)'], args: [], prompt: 'x'.repeat(4 * 1024 * 1024), cwd: tmpdir(), env: process.env });
+    expect((await handle.done).failure).toBe('pi exited with code 3:');
+  });
+
+  test('an abort before the child reads its prompt does not crash Pi (review r2: security 1)', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const handle = startChild({ command: [process.execPath, FAKE_PI], args: [], prompt: 'x'.repeat(4 * 1024 * 1024), cwd: tmpdir(), env: { ...process.env, FAKE_PI_MODE: 'hang' }, signal: controller.signal });
+    expect((await handle.done).failure).toBe('Subagent was aborted');
+  });
+
+  test("counts the child's tool-result and compaction usage, as Pi's session totals do (review r2: architecture 2)", async () => {
+    const { usage } = await run('nested').done;
+    expect([usage.input, usage.output, usage.cacheRead, usage.cacheWrite, usage.totalTokens]).toEqual([40, 20, 4, 8, 72]);
+    expect(usage.cost.total).toBeCloseTo(1.2);
+  });
+
+  test('ignores a stdout line that is not JSON instead of crashing the parent (SEC-001)', async () => {
+    const outcome = await run('noise').done;
+    expect([outcome.finalText, outcome.failure]).toEqual(['after noise', undefined]);
+  });
+
+  test('reports an error stop reason as a failure (TASK-015)', async () => {
+    const outcome = await run('error').done;
+    expect(outcome.failure).toBe('provider exploded');
+  });
+
+  test('reports a nonzero exit with stderr as a failure (TASK-015)', async () => {
+    const outcome = await run('crash').done;
+    expect(outcome.failure).toBe('pi exited with code 3: fatal: no model');
+  });
+
+  test('abort kills the child and its descendants (TASK-013)', async () => {
+    const controller = new AbortController();
+    const pids: number[] = [];
+    const handle = startChild({
+      command: [process.execPath, FAKE_PI],
+      args: [],
+      prompt: 'x',
+      cwd: tmpdir(),
+      env: { ...process.env, FAKE_PI_MODE: 'hang' },
+      signal: controller.signal,
+      onEvent: (event) => {
+        if (event.type === 'fake_pids') pids.push(...(event['pids'] as number[]));
+      },
+    });
+    expect(await eventually(() => pids.length === 2)).toBe(true);
+    controller.abort();
+    const outcome = await handle.done;
+    expect(outcome.failure).toBe('Subagent was aborted');
+    expect(await eventually(() => pids.every((pid) => !alive(pid)))).toBe(true);
+  });
+
+  test('kill() stops a running child for session shutdown (TASK-013)', async () => {
+    const pids: number[] = [];
+    const handle = startChild({
+      command: [process.execPath, FAKE_PI],
+      args: [],
+      prompt: 'x',
+      cwd: tmpdir(),
+      env: { ...process.env, FAKE_PI_MODE: 'hang' },
+      onEvent: (event) => {
+        if (event.type === 'fake_pids') pids.push(...(event['pids'] as number[]));
+      },
+    });
+    expect(await eventually(() => pids.length === 2)).toBe(true);
+    handle.kill();
+    expect((await handle.done).failure).toBe('Subagent was aborted');
+    expect(await eventually(() => pids.every((pid) => !alive(pid)))).toBe(true);
+  });
+
+  test('sends attachment images with the prompt', async () => {
+    const outcome = await startChild({ command: [process.execPath, FAKE_PI], args: [], prompt: 'see', images: [{ type: 'image', mimeType: 'image/png', data: 'AA==' }], cwd: tmpdir(), env: { ...process.env, FAKE_PI_MODE: 'echo' } }).done;
+    expect(outcome.finalText).toBe('GOT:see|IMAGES:image/png|ARGS:');
+  });
+
+  test('answers a dialog request as dismissed, since nobody can answer a subagent (HOST-005)', async () => {
+    const outcome = await run('dialog').done;
+    expect(JSON.parse(outcome.finalText.slice('ANSWER:'.length))).toEqual({ type: 'extension_ui_response', id: 'dialog-1', cancelled: true });
+  });
+});
+
+describe('steer and stop (C-H4)', () => {
+  const started = (mode: string) => {
+    let begun: () => void = () => undefined;
+    const running = new Promise<void>((resolve) => {
+      begun = resolve;
+    });
+    const handle = run(mode, 'first', undefined, (event) => {
+      if (event.type === 'agent_start') begun();
+    });
+    return { handle, running };
+  };
+
+  test('steer delivers a message into the running turn, and the agent finishes with it', async () => {
+    const { handle, running } = started('wait');
+    await running;
+    await handle.steer('change course', []);
+    const outcome = await handle.done;
+    expect([outcome.finalText, outcome.failure]).toEqual(['STEERED:change course|steer', undefined]);
+  });
+
+  test('steer refuses once the agent has finished', async () => {
+    const handle = run('echo');
+    await handle.done;
+    await expect(handle.steer('too late', [])).rejects.toThrow('has finished');
+  });
+
+  test('stop aborts the run over RPC and the child exits', async () => {
+    const { handle, running } = started('wait');
+    await running;
+    handle.stop();
+    const outcome = await handle.done;
+    expect(outcome.failure).toBe('Subagent was stopped with stop_agent');
+  });
+
+  test('stop kills a child that ignores the abort after the grace period', async () => {
+    const { handle, running } = started('deaf');
+    await running;
+    const before = Date.now();
+    handle.stop();
+    const outcome = await handle.done;
+    expect([outcome.failure, Date.now() - before >= 2_500]).toEqual(['Subagent was stopped with stop_agent', true]);
+  });
+});

package/test/task-schema.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from 'vitest';
+import { effectiveReadonly, TaskParams, taskPreflight } from '../src/task/tool.ts';
+
+describe('Task parameters (TASK-001)', () => {
+  test('requires description and prompt, like Cursor', () => {
+    expect(TaskParams.required).toEqual(['description', 'prompt']);
+  });
+
+  test('accepts Cursor parameters plus the readonly and environment fields pstack passes', () => {
+    const schema = JSON.parse(JSON.stringify(TaskParams)) as { properties: Record<string, { type?: string; enum?: string[] }> };
+    expect(Object.keys(schema.properties).toSorted()).toEqual(['cloud_base_branch', 'description', 'environment', 'file_attachments', 'fork', 'fork_turns', 'model', 'prompt', 'readonly', 'resume', 'run_in_background', 'subagent_type']);
+    expect(schema.properties['environment']?.enum).toEqual(['local', 'cloud']);
+    expect(schema.properties['run_in_background']?.type).toBe('boolean');
+    expect(schema.properties['fork_turns']).toMatchObject({ type: 'integer', minimum: 1 });
+  });
+});
+
+describe('Task preflight', () => {
+  const ok = { description: 'probe', prompt: 'p' };
+
+  test.for([{ cloud_base_branch: 'feature/x' }, { cloud_base_branch: 'feature/x', environment: 'local' as const }])('refuses cloud_base_branch without environment cloud: %j (TASK-010)', (extra) => {
+    expect(() => taskPreflight({ ...ok, ...extra }, 0)).toThrow('cloud_base_branch needs environment "cloud": it names the branch the subagent\'s worktree starts from.');
+  });
+
+  test('allows environment cloud with or without a base branch (TASK-010)', () => {
+    expect([taskPreflight({ ...ok, environment: 'cloud' }, 0), taskPreflight({ ...ok, environment: 'cloud', cloud_base_branch: 'main' }, 1)]).toEqual([undefined, undefined]);
+  });
+
+  test('refuses a grandchild launch (TASK-011)', () => {
+    expect(() => taskPreflight(ok, 2)).toThrow('A subagent launched by another subagent cannot launch further subagents.');
+  });
+
+  test('allows the main agent and direct subagents (TASK-011)', () => {
+    const outcome = (depth: number, environment?: 'local') => {
+      try {
+        taskPreflight(environment === undefined ? ok : { ...ok, environment }, depth);
+        return 'allowed';
+      } catch (error) {
+        return (error as Error).message;
+      }
+    };
+    expect([outcome(0, 'local'), outcome(1), outcome(2)]).toEqual(['allowed', 'allowed', 'A subagent launched by another subagent cannot launch further subagents.']);
+  });
+});
+
+describe('readonly (TASK-008; review: security)', () => {
+  test('a readonly agent type stays readonly whatever the call asks', () => {
+    expect([effectiveReadonly(true, false), effectiveReadonly(true, undefined), effectiveReadonly(false, true), effectiveReadonly(false, undefined)]).toEqual([true, true, true, false]);
+  });
+});

package/test/task-status.test.ts

@@ -0,0 +1,155 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { subagentDir } from '../src/paths.ts';
+import { writeRecord } from '../src/task/records.ts';
+import { agentStatus, lastAssistantText, listAgentStatuses, registerAgentStatus, statusText } from '../src/task/status.ts';
+
+const idOf = (n: number) => `${String(n).padStart(8, '0')}-2222-4333-8444-555555555555`;
+let dir = '';
+
+function addAgent(n: number, extra: Record<string, unknown> = {}): string {
+  const agentId = idOf(n);
+  writeRecord(dir, { agentId, type: 'generalPurpose', readonly: false, cwd: '/w/app', createdAt: new Date(Date.UTC(2026, 9, 28, 10, n)).toISOString(), depth: 1, ...extra });
+  return agentId;
+}
+
+function addTranscript(agentId: string, texts: string[]): string {
+  const header = { type: 'session', version: 3, id: agentId, timestamp: '2026-10-28T10:00:00.000Z', cwd: '/w/app' };
+  const messages = texts.map((text, index) => ({
+    type: 'message',
+    id: `e${index}`,
+    parentId: index === 0 ? null : `e${index - 1}`,
+    timestamp: '2026-10-28T10:00:01.000Z',
+    message: { role: index % 2 === 0 ? 'user' : 'assistant', content: [{ type: 'text', text }] },
+  }));
+  const path = join(dir, `2026-10-28T10-00-00-000Z_${agentId}.jsonl`);
+  writeFileSync(path, `${[header, ...messages].map((entry) => JSON.stringify(entry)).join('\n')}\n`);
+  return path;
+}
+
+const deadPid = () => spawnSync(process.execPath, ['-e', 'process.stdout.write(String(process.pid))'], { encoding: 'utf8' }).stdout;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'status-'));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('agent_status: one agent', () => {
+  test('running while the run lock names a live pid', () => {
+    const agentId = addAgent(1, { model: { provider: 'p', id: 'm', thinking: 'high' } });
+    addTranscript(agentId, ['task', 'working on it']);
+    writeFileSync(join(dir, `${agentId}.lock`), String(process.pid));
+    expect(agentStatus(dir, agentId)).toMatchObject({ agentId, state: 'running', pid: process.pid, type: 'generalPurpose', model: 'p/m:high', directory: '/w/app', createdAt: '2026-10-28T10:01:00.000Z', lastText: 'working on it' });
+  });
+
+  test('idle with no lock or a lock whose pid is dead', () => {
+    const agentId = addAgent(1);
+    addTranscript(agentId, ['task', 'done']);
+    expect(agentStatus(dir, agentId).state).toBe('idle');
+    writeFileSync(join(dir, `${agentId}.lock`), deadPid());
+    expect(agentStatus(dir, agentId).state).toBe('idle');
+  });
+
+  test('missing without a record or transcript', () => {
+    expect(agentStatus(dir, idOf(7))).toEqual({ agentId: idOf(7), state: 'missing' });
+    expect(statusText(agentStatus(dir, idOf(7)))).toContain('missing');
+  });
+
+  test('names the worktree directory and branch, and the fork source', () => {
+    const worktree = { path: '/wt/a', cwd: '/wt/a/pkg', branch: 'pstack/a', base: 'HEAD', commit: 'abc' };
+    const agentId = addAgent(1, { worktree, forkedFrom: idOf(9) });
+    const status = agentStatus(dir, agentId);
+    expect(status).toMatchObject({ directory: '/wt/a/pkg', branch: 'pstack/a', forkedFrom: idOf(9), model: "Pi's default model" });
+    expect(status.updatedAt).toBeDefined();
+    expect(statusText(status)).toContain('branch: pstack/a');
+  });
+
+  test('the last assistant text is the latest non-empty one, truncated to 500 characters', () => {
+    const agentId = addAgent(1);
+    const path = addTranscript(agentId, ['task', 'x'.repeat(800), 'more', '']);
+    expect(lastAssistantText(path)).toBe(`${'x'.repeat(500)}…`);
+  });
+});
+
+describe('agent_status: bounded transcript read (C-L3)', () => {
+  const line = (entry: unknown) => `${JSON.stringify(entry)}\n`;
+  const message = (role: string, text: string) => ({ type: 'message', message: { role, content: [{ type: 'text', text }] } });
+  const header = { type: 'session', version: 3, id: idOf(1), cwd: '/w/app' };
+
+  test('finds the last response behind a tool result larger than one read', () => {
+    const path = join(dir, 'big.jsonl');
+    writeFileSync(path, [line(header), line(message('assistant', 'early')), line(message('assistant', 'LAST-RESPONSE')), line(message('toolResult', 'x'.repeat(300_000)))].join(''));
+    expect(lastAssistantText(path)).toBe('LAST-RESPONSE');
+  });
+
+  test('reads at most the transcript tail, so a response buried under megabytes of tool output is not shown', () => {
+    const path = join(dir, 'huge.jsonl');
+    writeFileSync(path, [line(header), line(message('assistant', 'BURIED')), line(message('toolResult', 'x'.repeat(5 * 1024 * 1024)))].join(''));
+    expect({ last: lastAssistantText(path) }).toEqual({ last: undefined });
+  });
+});
+
+describe('agent_status: listing', () => {
+  test('lists agents newest first', () => {
+    for (const n of [2, 5, 3]) addAgent(n);
+    expect(listAgentStatuses(dir).agents.map((status) => status.agentId)).toEqual([idOf(5), idOf(3), idOf(2)]);
+  });
+
+  test('is bounded, reporting the total', () => {
+    for (let n = 1; n <= 25; n += 1) addAgent(n);
+    const { agents, total } = listAgentStatuses(dir);
+    expect([agents.length, total, agents[0]?.agentId]).toEqual([20, 25, idOf(25)]);
+    expect(listAgentStatuses(dir, 2).agents.map((status) => status.agentId)).toEqual([idOf(25), idOf(24)]);
+  });
+
+  test('skips a record without a creation time instead of failing the whole list (C-L3)', () => {
+    addAgent(2);
+    writeFileSync(join(dir, `${idOf(3)}.json`), JSON.stringify({ agentId: idOf(3), type: 'generalPurpose', readonly: false, cwd: '/w/app' }));
+    expect(listAgentStatuses(dir)).toMatchObject({ agents: [{ agentId: idOf(2) }], total: 1 });
+  });
+
+  test('an empty or absent directory lists nothing', () => {
+    expect(listAgentStatuses(join(dir, 'none'))).toEqual({ agents: [], total: 0 });
+  });
+});
+
+describe('agent_status tool', () => {
+  type Tool = { name: string; execute: (id: string, params: { agent_id?: string }, signal: undefined, onUpdate: undefined, ctx: { cwd: string }) => Promise<{ content: { text: string }[] }> };
+  const register = () => {
+    const tools: Tool[] = [];
+    registerAgentStatus({ registerTool: (tool: Tool) => tools.push(tool) } as never);
+    return tools[0] as Tool;
+  };
+
+  test('is annotated read-only and closed-world (C-L6)', () => {
+    const tools: { annotations?: unknown }[] = [];
+    registerAgentStatus({ registerTool: (tool: { annotations?: unknown }) => tools.push(tool) } as never);
+    expect(tools[0]?.annotations).toEqual({ readOnlyHint: true, openWorldHint: false });
+  });
+
+  test('reads the workspace subagent directory and never takes a run lock', async () => {
+    const previous = process.env['PI_CODING_AGENT_DIR'];
+    process.env['PI_CODING_AGENT_DIR'] = join(dir, 'agent');
+    try {
+      const tool = register();
+      expect(tool.name).toBe('agent_status');
+      const workspace = join(dir, 'w');
+      expect((await tool.execute('t', {}, undefined, undefined, { cwd: workspace })).content[0]?.text).toBe('No subagents in this workspace yet.');
+      dir = subagentDir(workspace);
+      const agentId = addAgent(1);
+      addTranscript(agentId, ['task', 'all done']);
+      const text = (await tool.execute('t', { agent_id: agentId }, undefined, undefined, { cwd: workspace })).content[0]?.text ?? '';
+      expect(text).toContain('state: idle');
+      expect(text).toContain('all done');
+      expect(listAgentStatuses(dir).agents[0]?.state).toBe('idle');
+      await expect(tool.execute('t', { agent_id: '../x' }, undefined, undefined, { cwd: workspace })).rejects.toThrow('is not a valid agent ID');
+    } finally {
+      if (previous === undefined) delete process.env['PI_CODING_AGENT_DIR'];
+      else process.env['PI_CODING_AGENT_DIR'] = previous;
+    }
+  });
+});

package/test/task-worktree.test.ts

@@ -0,0 +1,106 @@
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { addWorktree, planWorktree } from '../src/task/worktree.ts';
+
+const id = '11111111-2222-4333-8444-555555555555';
+let root = '';
+let repo = '';
+let worktrees = '';
+
+const git = (...args: string[]) => execFileSync('git', ['-C', repo, '-c', 'user.email=t@t', '-c', 'user.name=t', ...args], { encoding: 'utf8' }).trim();
+const commitFile = (name: string, text: string, message: string) => {
+  writeFileSync(join(repo, name), text);
+  git('add', name);
+  git('commit', '-qm', message);
+  return git('rev-parse', 'HEAD');
+};
+
+beforeEach(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), 'worktree-')));
+  repo = join(root, 'repo');
+  worktrees = join(root, 'worktrees');
+  mkdirSync(repo);
+  git('init', '-q', '-b', 'main');
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+describe('planWorktree', () => {
+  test('without a base branch, branches from the parent HEAD commit', () => {
+    const head = commitFile('a.txt', 'A', 'first');
+    expect(planWorktree(repo, worktrees, id)).toEqual({ path: join(worktrees, id), cwd: join(worktrees, id), branch: `pstack/${id}`, base: 'HEAD', commit: head });
+  });
+
+  test('a parent inside a tracked subdirectory runs the child in the same subdirectory of the worktree', () => {
+    mkdirSync(join(repo, 'pkg/inner'), { recursive: true });
+    writeFileSync(join(repo, 'pkg/inner/x.txt'), 'X');
+    git('add', '.');
+    git('commit', '-qm', 'pkg');
+    expect(planWorktree(join(repo, 'pkg/inner'), worktrees, id).cwd).toBe(join(worktrees, id, 'pkg/inner'));
+  });
+
+  test('a subdirectory the base commit lacks runs the child at the worktree root', () => {
+    commitFile('a.txt', 'A', 'first');
+    mkdirSync(join(repo, 'untracked'));
+    expect(planWorktree(join(repo, 'untracked'), worktrees, id).cwd).toBe(join(worktrees, id));
+  });
+
+  test('a cloud_base_branch that names a local branch is the base', () => {
+    commitFile('a.txt', 'A', 'first');
+    git('checkout', '-qb', 'feature');
+    const feature = commitFile('a.txt', 'F', 'feature');
+    git('checkout', '-q', 'main');
+    expect(planWorktree(repo, worktrees, id, 'feature')).toMatchObject({ base: 'feature', commit: feature });
+  });
+
+  test('a cloud_base_branch that only exists on origin falls back to origin/<branch>', () => {
+    const first = commitFile('a.txt', 'A', 'first');
+    git('update-ref', 'refs/remotes/origin/remote-only', first);
+    commitFile('a.txt', 'B', 'second');
+    expect(planWorktree(repo, worktrees, id, 'remote-only')).toMatchObject({ base: 'origin/remote-only', commit: first });
+  });
+
+  test('a cloud_base_branch that resolves nowhere fails, naming both refs it tried', () => {
+    commitFile('a.txt', 'A', 'first');
+    expect(() => planWorktree(repo, worktrees, id, 'nope')).toThrow(`cloud_base_branch "nope" names no commit in ${repo}: neither nope nor origin/nope exists. Pass an existing branch or omit cloud_base_branch to start from HEAD.`);
+  });
+
+  test('a directory outside any git repository fails', () => {
+    const plain = join(root, 'plain');
+    mkdirSync(plain);
+    expect(() => planWorktree(plain, worktrees, id)).toThrow(`environment "cloud" runs the subagent in its own git worktree, but ${plain} is not inside a git repository. Omit environment to run the subagent here.`);
+  });
+
+  test('a repository without commits fails, because HEAD names no commit to branch from', () => {
+    expect(() => planWorktree(repo, worktrees, id)).toThrow(`environment "cloud" branches the subagent's worktree from HEAD, but ${repo} has no commits yet.`);
+  });
+});
+
+describe('addWorktree', () => {
+  test('creates the branch at the base commit with only committed files, leaving the parent checkout alone', async () => {
+    const head = commitFile('a.txt', 'COMMITTED', 'first');
+    writeFileSync(join(repo, 'a.txt'), 'DIRTY');
+    const worktree = planWorktree(repo, worktrees, id);
+    await addWorktree(repo, worktree, undefined);
+    expect([git('rev-parse', `pstack/${id}`), readFileSync(join(worktree.path, 'a.txt'), 'utf8'), readFileSync(join(repo, 'a.txt'), 'utf8'), git('branch', '--show-current')]).toEqual([head, 'COMMITTED', 'DIRTY', 'main']);
+  });
+
+  test('reports git failure, such as a branch that already exists', async () => {
+    commitFile('a.txt', 'A', 'first');
+    git('branch', `pstack/${id}`);
+    await expect(addWorktree(repo, planWorktree(repo, worktrees, id), undefined)).rejects.toThrow(`Could not create the subagent's worktree at ${join(worktrees, id)}: fatal: a branch named 'pstack/${id}' already exists`);
+  });
+
+  test('an abort stops a slow checkout instead of blocking until it ends', async () => {
+    commitFile('a.txt', 'A', 'first');
+    writeFileSync(join(repo, '.git/hooks/post-checkout'), '#!/bin/sh\nsleep 30\n', { mode: 0o755 });
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 200);
+    const started = Date.now();
+    await expect(addWorktree(repo, planWorktree(repo, worktrees, id), controller.signal)).rejects.toThrow(`Stopped creating the subagent's worktree at ${join(worktrees, id)}.`);
+    expect(Date.now() - started).toBeLessThan(5000);
+  });
+});

package/test/todo.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'vitest';
+import { applyTodoWrite, formatTodos, type TodoItem, todosFromBranch } from '../src/todo.ts';
+
+const list: TodoItem[] = [
+  { id: 'frame', content: 'Frame', status: 'completed' },
+  { id: 'fan-out', content: 'Fan out', status: 'in_progress' },
+];
+
+describe('applyTodoWrite (TODO-001)', () => {
+  test('replaces the list when merge is false', () => {
+    expect(applyTodoWrite(list, [{ id: 'x', content: 'Only', status: 'pending' }], false)).toEqual([{ id: 'x', content: 'Only', status: 'pending' }]);
+  });
+
+  test('merges by id, keeps order, fills omitted fields, and appends new ids', () => {
+    expect(
+      applyTodoWrite(
+        list,
+        [
+          { id: 'fan-out', status: 'completed' },
+          { id: 'report', content: 'Report', status: 'pending' },
+        ],
+        true,
+      ),
+    ).toEqual([
+      { id: 'frame', content: 'Frame', status: 'completed' },
+      { id: 'fan-out', content: 'Fan out', status: 'completed' },
+      { id: 'report', content: 'Report', status: 'pending' },
+    ]);
+  });
+
+  test('rejects a new item without content or status', () => {
+    expect(() => applyTodoWrite(list, [{ id: 'new', status: 'pending' }], true)).toThrow('Todo "new" is new, so it needs both content and status.');
+    expect(() => applyTodoWrite([], [{ id: 'a', content: 'A' }], false)).toThrow('Todo "a" is new, so it needs both content and status.');
+  });
+
+  test('rejects duplicate ids in one call', () => {
+    expect(() =>
+      applyTodoWrite(
+        [],
+        [
+          { id: 'a', content: 'A', status: 'pending' },
+          { id: 'a', content: 'B', status: 'pending' },
+        ],
+        false,
+      ),
+    ).toThrow('Todo id "a" appears more than once in this call.');
+  });
+});
+
+describe('formatTodos', () => {
+  test('summarizes counts and marks each status', () => {
+    const text = formatTodos([...list, { id: 'skip', content: 'skip: not needed', status: 'cancelled' }, { id: 'later', content: 'Later', status: 'pending' }]);
+    expect(text).toBe('Todos (1/4 completed, 1 in progress):\n[x] frame: Frame\n[>] fan-out: Fan out\n[-] skip: skip: not needed\n[ ] later: Later');
+  });
+
+  test('reports an empty list', () => {
+    expect(formatTodos([])).toBe('Todos: none.');
+  });
+});
+
+describe('todosFromBranch (TODO-002)', () => {
+  test('takes the last TodoWrite result on the branch and ignores other tools', () => {
+    const entry = (toolName: string, todos: TodoItem[]) => ({ type: 'message', message: { role: 'toolResult', toolName, details: { todos } } });
+    const branch = [entry('TodoWrite', list), entry('read', []), entry('TodoWrite', [list[0] as TodoItem]), { type: 'custom', customType: 'x' }];
+    expect(todosFromBranch(branch)).toEqual([list[0]]);
+    expect(todosFromBranch([])).toEqual([]);
+  });
+
+  test('skips a failed TodoWrite, whose details Pi stores as {} (reviews: parity 2, architecture 1)', () => {
+    const ok = { type: 'message', message: { role: 'toolResult', toolName: 'TodoWrite', details: { todos: list } } };
+    const failed = { type: 'message', message: { role: 'toolResult', toolName: 'TodoWrite', isError: true, details: {} } };
+    expect(todosFromBranch([ok, failed])).toEqual(list);
+  });
+});