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

package/test/e2e/ask.e2e.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, expect, test } from 'vitest';
+import { makeSandbox, type PiEvent, runJson, type Sandbox, script, startRpc, toolEnds } from './harness.ts';
+
+let sandbox: Sandbox;
+beforeEach(() => {
+  sandbox = makeSandbox();
+});
+afterEach(() => sandbox.dispose());
+
+const budget = {
+  id: 'budget',
+  prompt: 'Pick a reasoning budget',
+  options: [
+    { id: 'unlimited', label: 'unlimited — max reasoning' },
+    { id: 'large', label: 'large — xhigh reasoning' },
+  ],
+};
+const areas = {
+  id: 'areas',
+  prompt: 'Which areas matter most?',
+  allow_multiple: true,
+  options: [
+    { id: 'style', label: 'Response style' },
+    { id: 'subagents', label: 'Subagents' },
+    { id: 'process', label: 'Process' },
+  ],
+};
+
+test('asks each question through UI dialogs and returns option IDs (HOST-005)', async () => {
+  const rpc = startRpc(sandbox, ['--no-session']);
+  try {
+    const answers = ['large — xhigh reasoning', 'Subagents', 'Process', '✓ Done selecting'];
+    const seen: PiEvent[] = [];
+    rpc.child.stdout?.on('data', () => {
+      for (const event of rpc.events.filter((candidate) => candidate.type === 'extension_ui_request' && candidate['method'] === 'select' && !seen.includes(candidate))) {
+        seen.push(event);
+        rpc.send({ type: 'extension_ui_response', id: event['id'], value: answers.shift() });
+      }
+    });
+    rpc.send({ type: 'prompt', message: script([{ tool: 'AskQuestion', args: { questions: [budget, areas] } }]) });
+    const end = await rpc.waitFor((event) => event.type === 'tool_execution_end' && event['toolName'] === 'AskQuestion');
+    expect(seen.map((event) => [event['title'], event['options']])).toEqual([
+      ['Pick a reasoning budget', ['unlimited — max reasoning', 'large — xhigh reasoning', 'Other: (type to answer)']],
+      ['Which areas matter most? (pick one at a time, then ✓ Done selecting)', ['Response style', 'Subagents', 'Process', 'Other: (type to answer)', '✓ Done selecting']],
+      ['Which areas matter most? (picked: Subagents)', ['Response style', 'Process', 'Other: (type to answer)', '✓ Done selecting']],
+      ['Which areas matter most? (picked: Subagents, Process)', ['Response style', 'Other: (type to answer)', '✓ Done selecting']],
+    ]);
+    const result = end['result'] as { content: { text: string }[]; details: unknown };
+    expect(result.content[0]?.text).toBe('budget: large (large — xhigh reasoning)\nareas: subagents (Subagents), process (Process)');
+    expect(result.details).toEqual({ answers: { budget: ['large'], areas: ['subagents', 'process'] } });
+  } finally {
+    await rpc.close();
+  }
+});
+
+test('shows the title and option descriptions of a Cursor-shaped call and still returns IDs (HOST-005)', async () => {
+  // Shape observed in Cursor IDE AskQuestion calls: a top-level title and optional option descriptions.
+  const confirm = {
+    id: 'confirm',
+    prompt: 'Write the rule with this table?',
+    options: [
+      { id: 'accept', label: 'Accept as-is (Recommended)', description: 'Keep all roles on inherit-parent.' },
+      { id: 'change', label: 'Change specific roles' },
+    ],
+  };
+  const rpc = startRpc(sandbox, ['--no-session']);
+  try {
+    const seen: PiEvent[] = [];
+    rpc.child.stdout?.on('data', () => {
+      for (const event of rpc.events.filter((candidate) => candidate.type === 'extension_ui_request' && candidate['method'] === 'select' && !seen.includes(candidate))) {
+        seen.push(event);
+        rpc.send({ type: 'extension_ui_response', id: event['id'], value: (event['options'] as string[])[0] });
+      }
+    });
+    rpc.send({ type: 'prompt', message: script([{ tool: 'AskQuestion', args: { title: 'Confirm pstack rule', questions: [confirm] } }]) });
+    const end = await rpc.waitFor((event) => event.type === 'tool_execution_end' && event['toolName'] === 'AskQuestion');
+    expect(seen.map((event) => [event['title'], event['options']])).toEqual([
+      ['Confirm pstack rule: Write the rule with this table?', ['Accept as-is (Recommended) — Keep all roles on inherit-parent.', 'Change specific roles', 'Other: (type to answer)']],
+    ]);
+    expect((end['result'] as { details: unknown }).details).toEqual({ answers: { confirm: ['accept'] } });
+  } finally {
+    await rpc.close();
+  }
+});
+
+test('a dismissed question is reported, not guessed (HOST-005)', async () => {
+  const rpc = startRpc(sandbox, ['--no-session']);
+  try {
+    let responded = false;
+    rpc.child.stdout?.on('data', () => {
+      const request = rpc.events.find((event) => event.type === 'extension_ui_request' && event['method'] === 'select');
+      if (request === undefined || responded) return;
+      responded = true;
+      rpc.send({ type: 'extension_ui_response', id: request['id'], cancelled: true });
+    });
+    rpc.send({ type: 'prompt', message: script([{ tool: 'AskQuestion', args: { questions: [budget] } }]) });
+    const end = await rpc.waitFor((event) => event.type === 'tool_execution_end' && event['toolName'] === 'AskQuestion');
+    expect((end['result'] as { content: { text: string }[] }).content[0]?.text).toBe('budget: no answer (the user dismissed the question)');
+  } finally {
+    await rpc.close();
+  }
+});
+
+test('without a UI the questions resolve as skipped, as Cursor print mode reports (HOST-005)', async () => {
+  // Observed: cursor-agent -p called AskQuestion and its final reply said the user skipped the question
+  // (parity/pi-pstack-two/evidence/cursor-delegate-v21-resume-run1.json).
+  const run = await runJson(sandbox, script([{ tool: 'AskQuestion', args: { questions: [budget] } }]), ['--no-session']);
+  const [end] = toolEnds(run.events, 'AskQuestion');
+  expect(end?.isError).toBe(false);
+  expect(end?.text).toBe('budget: skipped (no one can answer questions in this session; decide yourself and say what you chose)');
+  expect(end?.details).toEqual({ answers: {}, skipped: ['budget'] });
+});
+
+test('every question offers a typed Other answer, as the Cursor question dialog does (HOST-005)', async () => {
+  const rpc = startRpc(sandbox, ['--no-session']);
+  try {
+    const seen: PiEvent[] = [];
+    rpc.child.stdout?.on('data', () => {
+      for (const event of rpc.events.filter((candidate) => candidate.type === 'extension_ui_request' && !seen.includes(candidate))) {
+        seen.push(event);
+        if (event['method'] === 'select') rpc.send({ type: 'extension_ui_response', id: event['id'], value: 'Other: (type to answer)' });
+        if (event['method'] === 'input') rpc.send({ type: 'extension_ui_response', id: event['id'], value: 'xhigh but cheaper' });
+      }
+    });
+    rpc.send({ type: 'prompt', message: script([{ tool: 'AskQuestion', args: { questions: [budget] } }]) });
+    const end = await rpc.waitFor((event) => event.type === 'tool_execution_end' && event['toolName'] === 'AskQuestion');
+    const select = seen.find((event) => event['method'] === 'select');
+    expect((select?.['options'] as string[] | undefined)?.at(-1)).toBe('Other: (type to answer)');
+    const result = end['result'] as { content: { text: string }[]; details: unknown };
+    expect(result.content[0]?.text).toBe('budget: other ("xhigh but cheaper")');
+    expect(result.details).toEqual({ answers: { budget: ['other'] }, other: { budget: 'xhigh but cheaper' } });
+  } finally {
+    await rpc.close();
+  }
+});

package/test/e2e/harness.ts

@@ -0,0 +1,179 @@
+// Drives the real Pi CLI against an isolated agent directory that loads this package and the scripted test model.
+import { type ChildProcess, spawn } from 'node:child_process';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { PACKAGE_ROOT } from '../../src/paths.ts';
+
+const PI_CLI = join(PACKAGE_ROOT, 'node_modules/@earendil-works/pi-coding-agent/dist/bundle/cli.js');
+const SCRIPTED_MODEL = join(PACKAGE_ROOT, 'test/fixtures/scripted-model.ts');
+// PSTACK_E2E_PI=<pi executable> runs the suite against an installed Pi, such as the user's launcher, instead of the dev dependency.
+const INSTALLED_PI = process.env['PSTACK_E2E_PI'];
+
+/** The command and argv that run Pi with these arguments. */
+export function piInvocation(args: readonly string[]): [string, string[]] {
+  return INSTALLED_PI === undefined || INSTALLED_PI === '' ? [process.execPath, [PI_CLI, ...args]] : [INSTALLED_PI, [...args]];
+}
+
+export interface Sandbox {
+  root: string;
+  agentDir: string;
+  workDir: string;
+  env: Record<string, string>;
+  dispose: () => void;
+}
+
+export type PiEvent = { type: string } & Record<string, unknown>;
+
+export interface RunResult {
+  events: PiEvent[];
+  exitCode: number | null;
+  stderr: string;
+}
+
+export function makeSandbox(settings: Record<string, unknown> = {}): Sandbox {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'pi-pstack-e2e-')));
+  const agentDir = join(root, 'agent');
+  const workDir = join(root, 'work');
+  mkdirSync(agentDir);
+  mkdirSync(workDir);
+  writeFileSync(join(agentDir, 'settings.json'), JSON.stringify({ packages: [PACKAGE_ROOT], extensions: [SCRIPTED_MODEL], quietStartup: true, ...settings }));
+  // HOME moves too, so user-level resources such as ~/.agents/skills stay out of the run.
+  const env = { ...process.env, HOME: root, PI_CODING_AGENT_DIR: agentDir, PI_OFFLINE: '1', PI_SKIP_VERSION_CHECK: '1' } as Record<string, string>;
+  // Variables that would point a run at the user's real state, or give the parent a subagent identity.
+  for (const name of ['PI_CODING_AGENT_SESSION_DIR', 'PI_PSTACK_DEPTH', 'PI_PSTACK_AGENT', 'PI_PSTACK_PARENT_PID']) delete env[name];
+  return { root, agentDir, workDir, env, dispose: () => rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }) };
+}
+
+/** Splits a byte stream on LF only, as Pi's JSONL framing requires. */
+export function lineSplitter(onLine: (line: string) => void): (chunk: Buffer) => void {
+  let buffer = '';
+  return (chunk) => {
+    buffer += chunk.toString('utf8');
+    let index = buffer.indexOf('\n');
+    while (index !== -1) {
+      const line = buffer.slice(0, index).replace(/\r$/, '');
+      buffer = buffer.slice(index + 1);
+      if (line.trim() !== '') onLine(line);
+      index = buffer.indexOf('\n');
+    }
+  };
+}
+
+export function runJson(sandbox: Sandbox, prompts: string | string[], args: string[] = [], timeoutMs = 45_000): Promise<RunResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(...piInvocation(['--mode', 'json', '--offline', '--model', 'scripted/echo', ...args, ...[prompts].flat()]), { cwd: sandbox.workDir, env: sandbox.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    const events: PiEvent[] = [];
+    let stderr = '';
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`pi --mode json timed out after ${timeoutMs}ms\n${stderr}`));
+    }, timeoutMs);
+    child.stdout.on(
+      'data',
+      lineSplitter((line) => events.push(JSON.parse(line) as PiEvent)),
+    );
+    child.stderr.on('data', (chunk: Buffer) => {
+      stderr += chunk.toString('utf8');
+    });
+    child.on('error', reject);
+    child.on('close', (exitCode) => {
+      clearTimeout(timer);
+      resolve({ events, exitCode, stderr });
+    });
+  });
+}
+
+type Content = string | { type: string; text?: string }[];
+export interface EventMessage {
+  role: string;
+  content: Content;
+  customType?: string;
+  toolName?: string;
+  isError?: boolean;
+  details?: unknown;
+  usage?: { totalTokens: number };
+}
+
+export const contentText = (content: Content): string => (typeof content === 'string' ? content : content.map((part) => part.text ?? '').join(''));
+
+export function messages(events: PiEvent[], role?: string): EventMessage[] {
+  return events
+    .filter((event) => event.type === 'message_end')
+    .map((event) => event['message'] as EventMessage)
+    .filter((message) => role === undefined || message.role === role);
+}
+
+export const assistantTexts = (events: PiEvent[]): string[] => messages(events, 'assistant').map((message) => contentText(message.content));
+
+export interface ToolEnd {
+  toolName: string;
+  isError: boolean;
+  text: string;
+  details: unknown;
+  usage?: { totalTokens: number };
+}
+
+export function toolEnds(events: PiEvent[], toolName: string): ToolEnd[] {
+  return events
+    .filter((event) => event.type === 'tool_execution_end' && event['toolName'] === toolName)
+    .map((event) => {
+      const result = event['result'] as { content: Content; details: unknown; usage?: { totalTokens: number } };
+      return { toolName, isError: event['isError'] === true, text: contentText(result.content), details: result.details, ...(result.usage === undefined ? {} : { usage: result.usage }) };
+    });
+}
+
+/** Pi reads a positional argument that starts with @ as a file, so the directive goes on the second line. */
+export const script = (steps: unknown[]): string => `run the script\n@@script ${JSON.stringify(steps)}`;
+
+export interface RpcSession {
+  child: ChildProcess;
+  events: PiEvent[];
+  send: (command: Record<string, unknown>) => void;
+  waitFor: (predicate: (event: PiEvent) => boolean, timeoutMs?: number) => Promise<PiEvent>;
+  close: () => Promise<void>;
+}
+
+export function startRpc(sandbox: Sandbox, args: string[] = []): RpcSession {
+  const child = spawn(...piInvocation(['--mode', 'rpc', '--offline', '--model', 'scripted/echo', ...args]), { cwd: sandbox.workDir, env: sandbox.env, stdio: ['pipe', 'pipe', 'pipe'] });
+  const events: PiEvent[] = [];
+  const waiters: { predicate: (event: PiEvent) => boolean; resolve: (event: PiEvent) => void }[] = [];
+  child.stdout?.on(
+    'data',
+    lineSplitter((line) => {
+      const event = JSON.parse(line) as PiEvent;
+      events.push(event);
+      for (const waiter of waiters.filter((candidate) => candidate.predicate(event))) {
+        waiters.splice(waiters.indexOf(waiter), 1);
+        waiter.resolve(event);
+      }
+    }),
+  );
+  let stderr = '';
+  child.stderr?.on('data', (chunk: Buffer) => {
+    stderr += chunk.toString('utf8');
+  });
+  const waitFor = (predicate: (event: PiEvent) => boolean, timeoutMs = 30_000) =>
+    new Promise<PiEvent>((resolve, reject) => {
+      const seen = events.find(predicate);
+      if (seen) return resolve(seen);
+      const timer = setTimeout(() => reject(new Error(`timed out waiting for an RPC event\n${stderr}`)), timeoutMs);
+      waiters.push({
+        predicate,
+        resolve: (event) => {
+          clearTimeout(timer);
+          resolve(event);
+        },
+      });
+    });
+  const send = (command: Record<string, unknown>) => child.stdin?.write(`${JSON.stringify(command)}\n`);
+  const close = () =>
+    new Promise<void>((resolve) => {
+      if (child.exitCode !== null) return resolve();
+      child.once('close', () => resolve());
+      child.stdin?.end();
+      setTimeout(() => child.kill('SIGKILL'), 10_000).unref();
+    });
+  return { child, events, send, waitFor, close };
+}

package/test/e2e/host.e2e.test.ts

@@ -0,0 +1,193 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { PACKAGE_ROOT } from '../../src/paths.ts';
+import { assistantTexts, contentText, makeSandbox, runJson, type Sandbox, script, startRpc, toolEnds } from './harness.ts';
+
+let sandbox: Sandbox;
+beforeEach(() => {
+  sandbox = makeSandbox();
+});
+afterEach(() => sandbox.dispose());
+
+const section = (prompt: string, name: string) => {
+  const match = new RegExp(`<${name}>\\n([\\s\\S]*?)\\n</${name}>`).exec(prompt);
+  if (!match) throw new Error(`system prompt has no <${name}> section`);
+  return match[1] ?? '';
+};
+
+async function systemPrompt(args: string[] = []): Promise<string> {
+  const run = await runJson(sandbox, 'show me\n@@sys', args);
+  const [text] = assistantTexts(run.events);
+  if (text === undefined) throw new Error(`no reply\n${run.stderr}`);
+  return text;
+}
+
+/** The system prompt of a long-lived RPC session, where loops can run. */
+async function rpcSystemPrompt(): Promise<string> {
+  const rpc = startRpc(sandbox, ['--no-session']);
+  try {
+    rpc.send({ type: 'prompt', message: 'show me\n@@sys' });
+    const reply = await rpc.waitFor((event) => event.type === 'message_end' && (event['message'] as { role: string }).role === 'assistant');
+    return contentText((reply['message'] as { content: { type: string; text?: string }[] }).content);
+  } finally {
+    await rpc.close();
+  }
+}
+
+describe('host map (HOST-001)', () => {
+  test('names the skills, rule, transcript, store, project, and subagent locations in Pi terms', async () => {
+    const host = section(await systemPrompt(), 'pstack_host');
+    const skills = join(PACKAGE_ROOT, 'skills');
+    const workspace = join(sandbox.agentDir, 'pstack/workspaces', `--${sandbox.workDir.replace(/^\//, '').replaceAll('/', '-')}--`);
+    expect(host).toContain(`pstack runs here through the pi-pstack package at ${PACKAGE_ROOT}.`);
+    expect(host).toContain(`<SKILLS> = ${skills}`);
+    expect(host).toContain('"the X skill", "/X", and "principle-X" mean <SKILLS>/X/SKILL.md');
+    expect(host).toContain('a delegate that needs poteto-mode reads <SKILLS>/poteto-mode/SKILL.md');
+    expect(host).toContain(`- The model rule is ${join(sandbox.agentDir, 'pstack/pstack-models.md')}. Its current content is in <pstack_models>.`);
+    expect(host).toContain(`- Skill folders: project \`.pi/skills/\`, personal \`${join(sandbox.agentDir, 'skills')}/\`.`);
+    expect(host).toContain(`Subagent transcripts for this workspace: ${join(workspace, 'subagents')}/*_<agent id>.jsonl. A subagent is still running while ${join(workspace, 'subagents')}/<agent id>.lock exists and names a live pid.`);
+    expect(host).toMatch(new RegExp(`"The current agent's store" is ${join(workspace, 'store')}/[0-9a-f-]+\\. Create it when a playbook needs it\\.`));
+    expect(host).toContain(`- Projects: a program's Project is ${join(workspace, 'projects')}/<project-slug>/, with notes.md as its Project tracker and store/ as its Project store.`);
+    expect(host).toMatch(new RegExp(`- Files a tool makes for the user, such as visualize charts, go in ${join(workspace, 'artifacts')}/[0-9a-f-]+\\.`));
+    expect(host).toContain(`- Transcripts: this workspace's Pi session files are in ${join(sandbox.agentDir, 'sessions')}/--${sandbox.workDir.replace(/^\//, '').replaceAll('/', '-')}--.`);
+    expect(host).toContain('Installed skills (62): architect, arena, automate-me,');
+    expect(host).toContain("agent_status reads a subagent's state without waking it.");
+    expect(host).toContain('- The user keeps a skill on every turn with `/mode <skill>` (exit `/mode off`) and plans without edits with `/plan` (exit `/plan off`).');
+    expect(host).toContain('- MCP tools are named mcp__<server>__<tool>; `pi mcp list` shows the servers.');
+    expect(host).toContain('- Isolated workers (Task environment "cloud") run on this machine in their own git worktree on branch pstack/<agent id>');
+  });
+
+  test('names no Cursor host feature (HOST-008)', async () => {
+    const prompt = await systemPrompt(['--no-session']);
+    const names = ['pstack_host', 'pstack_subagents', 'pstack_models', 'pstack_mode', 'pstack_plan', 'pstack_loop'];
+    const pstack = names.map((name) => new RegExp(`<${name}>\\n([\\s\\S]*?)\\n</${name}>`).exec(prompt)?.[1] ?? '').join('\n');
+    expect(pstack).not.toMatch(/cursor/i);
+  });
+
+  test('tells a one-shot run it cannot subscribe, and a long-lived session how subscriptions wake it (HOST-010)', async () => {
+    const [rpc, oneShot] = [section(await rpcSystemPrompt(), 'pstack_host'), section(await systemPrompt(['--no-session']), 'pstack_host')];
+    expect([rpc.includes('- Subscriptions (subscribe_github_pr, subscribe_timer, subscribe_webhook) wake this chat'), oneShot.includes('- Subscriptions: this run ends when it settles, so nothing can wake it')]).toEqual([true, true]);
+  });
+
+  test("names the main chat's own store as the root agent's store", async () => {
+    const host = section(await systemPrompt(['--no-session']), 'pstack_host');
+    const current = /"The current agent's store" is (\S+)\. /.exec(host)?.[1];
+    expect(host).toContain(`"The root agent's store" is ${current}, the store of the main chat that started this subagent tree; in the main chat it is the current agent's store.`);
+  });
+
+  test('names AskQuestion only where a user can answer (HOST-005; review r2: parity 4)', async () => {
+    const [rpc, oneShot] = [section(await rpcSystemPrompt(), 'pstack_host'), section(await systemPrompt(['--no-session']), 'pstack_host')];
+    expect([
+      rpc.includes('- Todo lists: the TodoWrite tool. Structured questions: the AskQuestion tool.'),
+      oneShot.includes('- Todo lists: the TodoWrite tool. Structured questions: the AskQuestion tool, but nobody can answer in this run, so every question comes back skipped; decide yourself and say what you chose.'),
+    ]).toEqual([true, true]);
+  });
+
+  test('tells a long-lived session how to arm /loop (HOST-004)', async () => {
+    const host = section(await rpcSystemPrompt(), 'pstack_host');
+    expect(host).toContain(
+      '- /loop: the user starts `/loop [interval] <prompt>`. When a playbook says to arm /loop, call the Loop tool with prompt plus interval (fixed cadence) or wake_in (agent-paced). Inside a loop, Loop with wake_in schedules the next run and stop: true ends it.',
+    );
+  });
+
+  test('tells a one-shot run, such as a subagent, that it cannot arm /loop (HOST-004, recheck 2)', async () => {
+    const host = section(await systemPrompt(['--no-session']), 'pstack_host');
+    expect(host).toContain(
+      '- /loop: this run ends when it settles (a subagent, or a print or JSON run), so it has no Loop tool and cannot arm a loop. Keep working until the goal is met, and name in the final reply anything the parent chat should loop on.',
+    );
+  });
+
+  test('frames an attached skill as the workflow to follow', async () => {
+    const host = section(await systemPrompt(), 'pstack_host');
+    expect(host).toContain(
+      '- A <skill> block in a user message means the user attached that skill to this request. Follow its workflow from its first step, including the steps it says to take before answering, instead of answering directly.',
+    );
+  });
+
+  test('names the persisted transcript of this chat', async () => {
+    const host = section(await systemPrompt(['--session-dir', join(sandbox.root, 'sessions')]), 'pstack_host');
+    expect(host).toMatch(new RegExp(`This chat's transcript is ${join(sandbox.root, 'sessions')}/[^ ]+\\.jsonl\\.`));
+  });
+
+  test('says when the chat is not persisted', async () => {
+    const host = section(await systemPrompt(['--no-session']), 'pstack_host');
+    expect(host).toContain('This chat is not persisted (--no-session), so it has no transcript file.');
+  });
+});
+
+describe('subagent catalog (HOST-002)', () => {
+  test('lists the subagent types and the models Task accepts', async () => {
+    const catalog = section(await systemPrompt(['--no-session']), 'pstack_subagents');
+    expect(catalog).toContain('- generalPurpose (default): ');
+    expect(catalog).toContain('- poteto-agent (runs in the background unless run_in_background is false): Delegate subagent for code-writing and helper tasks spawned during a `/poteto-mode` run.');
+    expect(catalog).toContain('- comment-sicko: A deranged comment-hater that savors deletion and condemns workaround code.');
+    expect(catalog).toContain('- inherit (default): the parent model and thinking level. auto and inherit-parent mean the same.');
+    expect(catalog).toMatch(/^- This chat runs scripted\/echo(:\w+)?\. pstack's model families \(claude-\*, grok-\*\) go by the model id after its provider\.$/m);
+    expect(catalog).toContain('Available models: scripted/echo (thinking: off, minimal, low, medium, high), scripted/plain');
+    expect(catalog).toContain('- A Pi model <provider>/<model-id> or <model-id>, optionally with :<level> from the thinking levels the model lists below. A level the model does not list is rejected.');
+  });
+});
+
+describe('capability-aware sections (C-M4)', () => {
+  test('a readonly subagent gets no subagent catalog and no Task or stop_agent lines; its parent gets both', async () => {
+    const run = await runJson(sandbox, script([{ tool: 'Task', args: { description: 'probe', prompt: 'go\n@@sys', readonly: true } }]), ['--no-session']);
+    const child = toolEnds(run.events, 'Task')[0]?.text ?? '';
+    const parentHost = section(await systemPrompt(['--no-session']), 'pstack_host');
+    expect([child.includes('<pstack_host>'), child.includes('<pstack_subagents>'), section(child, 'pstack_host').includes('Task'), section(child, 'pstack_host').includes('stop_agent')]).toEqual([true, false, false, false]);
+    expect([parentHost.includes('- Subagents: call the Task tool'), parentHost.includes('stop_agent stops a running agent.')]).toEqual([true, true]);
+  });
+});
+
+describe('model rule (RULE-001)', () => {
+  test('reports the default when no rule exists', async () => {
+    const models = section(await systemPrompt(['--no-session']), 'pstack_models');
+    expect(models).toBe(`No pstack model rule exists at ${join(sandbox.agentDir, 'pstack/pstack-models.md')}. Every role uses its skill default until /setup-pstack writes one.`);
+  });
+
+  test('applies the rule on every request when it exists', async () => {
+    mkdirSync(join(sandbox.agentDir, 'pstack'), { recursive: true });
+    writeFileSync(join(sandbox.agentDir, 'pstack/pstack-models.md'), '# budget: small (medium)\nswarm workers: scripted/plain\n');
+    const run = await runJson(sandbox, ['first\n@@sys', 'second\n@@sys'], ['--no-session']);
+    const prompts = assistantTexts(run.events);
+    expect(prompts).toHaveLength(2);
+    for (const prompt of prompts) expect(section(prompt, 'pstack_models')).toBe(`Path: ${join(sandbox.agentDir, 'pstack/pstack-models.md')}\n# budget: small (medium)\nswarm workers: scripted/plain`);
+  });
+});
+
+describe('tool listing', () => {
+  test('lists the pstack tools a one-shot run can use, and the todolist guideline (HOST-001, TODO-001, recheck 2)', async () => {
+    const prompt = await systemPrompt(['--no-session']);
+    const tools = /<tools>\n([\s\S]*?)\n<\/tools>/.exec(prompt)?.[1] ?? '';
+    expect(
+      tools
+        .split('\n')
+        .filter((line) => /^- (Task|TodoWrite|AskQuestion|Loop):/.test(line))
+        .toSorted(),
+    ).toEqual([
+      '- AskQuestion: Structured multiple-choice questions for the user',
+      '- Task: Launch subagents (foreground, background with completion notifications, resume by agent ID)',
+      '- TodoWrite: Create and update the todo list for this session',
+    ]);
+    expect(prompt).toContain('- When a skill or playbook says to open a todolist or todo list, call TodoWrite before other work, with the steps it names as the first items.');
+  });
+});
+
+describe('image generation (HOST-006)', () => {
+  test('the path the host section names generates an image when an image model is configured', async () => {
+    const images = makeSandbox({ extensions: [join(PACKAGE_ROOT, 'test/fixtures/scripted-model.ts'), join(PACKAGE_ROOT, 'test/fixtures/image-model.ts')] });
+    try {
+      // The script follows the host section line: codemode's models.generateImages(), shown with image().
+      const code =
+        'const [painter] = await models.getAvailableOfType("image");\nconst result = await models.generateImages(painter, { input: [{ type: "text", text: "a fox" }] });\nfor (const block of result.output) if (block.type === "image") image(block);\nreturn painter.provider + "/" + painter.id + " " + result.stopReason;';
+      const run = await runJson(images, script([{ tool: 'codemode', args: { code } }]), ['--no-session', '--tools', '+codemode']);
+      const [end] = toolEnds(run.events, 'codemode');
+      expect(end?.isError).toBe(false);
+      expect(end?.text).toContain('testimg/painter stop');
+      expect(JSON.stringify(run.events.find((event) => event.type === 'tool_execution_end' && event['toolName'] === 'codemode'))).toContain('"type":"image"');
+    } finally {
+      images.dispose();
+    }
+  });
+});

package/test/e2e/lifecycle.e2e.test.ts

@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, expect, test } from 'vitest';
+import { contentText, makeSandbox, type PiEvent, type RpcSession, type Sandbox, script, startRpc } from './harness.ts';
+
+let sandbox: Sandbox;
+let rpc: RpcSession;
+beforeEach(() => {
+  sandbox = makeSandbox();
+  rpc = startRpc(sandbox, ['--no-session']);
+});
+afterEach(async () => {
+  await rpc.close();
+  sandbox.dispose();
+});
+
+// Pi sets process.title to "pi", so ps cannot find a child by its arguments; the Task details carry its pid.
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+async function gone(pids: readonly number[], timeoutMs = 12_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (pids.every((pid) => !alive(pid))) return true;
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  }
+  return pids.every((pid) => !alive(pid));
+}
+
+async function reply(message: string): Promise<string> {
+  const mark = rpc.events.length;
+  rpc.send({ type: 'prompt', message });
+  await rpc.waitFor((event) => event.type === 'agent_settled' && rpc.events.indexOf(event) >= mark);
+  const last = rpc.events
+    .slice(mark)
+    .filter((event) => event.type === 'message_end' && (event['message'] as { role: string }).role === 'assistant')
+    .at(-1);
+  if (last === undefined) throw new Error('the run produced no assistant message');
+  return contentText((last['message'] as { content: { type: string; text?: string }[] }).content);
+}
+
+async function backgroundAgent(): Promise<number> {
+  const mark = rpc.events.length;
+  rpc.send({ type: 'prompt', message: script([{ tool: 'Task', args: { description: 'slow', prompt: 'go\n@@sleep 60000 SLOW', run_in_background: true } }]) });
+  const end = await rpc.waitFor((event: PiEvent) => event.type === 'tool_execution_end' && event['toolName'] === 'Task' && rpc.events.indexOf(event) >= mark);
+  await rpc.waitFor((event) => event.type === 'agent_settled' && rpc.events.indexOf(event) >= mark);
+  return (end['result'] as { details: { pid: number } }).details.pid;
+}
+
+// Interactive Pi redraws the chat between the old session's shutdown and the new session's start, so a warning sent
+// at shutdown never reaches the screen. The new session's mode status marks that start.
+test.for([
+  { replace: 'new session', command: { type: 'new_session' }, reason: 'new' },
+  { replace: 'reload', command: { type: 'prompt', message: '/test-reload' }, reason: 'reload' },
+])('a $replace shows the stopped-subagent warning after the next session starts', async ({ command, reason }) => {
+  await backgroundAgent();
+  const mark = rpc.events.length;
+  rpc.send({ id: 'replace', ...command });
+  await rpc.waitFor((event) => event['id'] === 'replace');
+  const after = rpc.events.slice(mark);
+  const isUi = (event: PiEvent, method: string) => event.type === 'extension_ui_request' && event['method'] === method;
+  const started = after.findIndex((event) => isUi(event, 'setStatus') && event['statusKey'] === 'pstack-mode');
+  const warned = await rpc.waitFor((event) => isUi(event, 'notify') && String(event['message']).startsWith('Stopped 1 background') && rpc.events.indexOf(event) >= mark);
+  expect([warned['message'], rpc.events.indexOf(warned) - mark > started, started >= 0]).toEqual([`Stopped 1 background subagent (session ${reason}). Resume one with its agent ID.`, true, true]);
+});
+
+test('/reload keeps aliases and tools, and stops the old runtime children (PKG-002)', async () => {
+  const pid = await backgroundAgent();
+  expect(alive(pid)).toBe(true);
+  rpc.send({ id: 'reload', type: 'prompt', message: '/test-reload' });
+  await rpc.waitFor((event) => event['id'] === 'reload');
+  expect(await gone([pid])).toBe(true);
+  expect(await reply('/how @@say STILL-ALIASED')).toBe('STILL-ALIASED');
+  expect(
+    (await reply('tools\n@@tools-list'))
+      .split(',')
+      .filter((name) => name === 'Task' || name === 'TodoWrite')
+      .toSorted(),
+  ).toEqual(['Task', 'TodoWrite']);
+});
+
+test('a new session resets mode and todos and stops the old children (PKG-002)', async () => {
+  rpc.send({ id: 'mode', type: 'prompt', message: '/mode tdd' });
+  await rpc.waitFor((event) => event['id'] === 'mode');
+  await reply(script([{ tool: 'TodoWrite', args: { merge: false, todos: [{ id: 'a', content: 'Alpha', status: 'pending' }] } }]));
+  const pid = await backgroundAgent();
+  expect(alive(pid)).toBe(true);
+  rpc.send({ id: 'new', type: 'new_session' });
+  await rpc.waitFor((event) => event['id'] === 'new');
+  expect(await gone([pid])).toBe(true);
+  const notice = rpc.events.find((event) => event.type === 'extension_ui_request' && event['method'] === 'notify' && String(event['message']).startsWith('Stopped 1 background'));
+  expect(notice?.['message']).toBe('Stopped 1 background subagent (session new). Resume one with its agent ID.');
+  expect(await reply('fresh\n@@sys')).not.toContain('<pstack_mode>');
+  expect(await reply(script([{ tool: 'TodoWrite', args: { merge: true, todos: [{ id: 'b', content: 'Beta', status: 'pending' }] } }]))).toBe('RESULTS:\n[TodoWrite] Todos (0/1 completed):\n[ ] b: Beta');
+});