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

package/test/plan.test.ts

@@ -0,0 +1,126 @@
+import type { ExtensionAPI, ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { expect, test } from 'vitest';
+import { PLAN_BASH, PLAN_ENTRY, parsePlanArgs, planBlockReason, planFromBranch, planSection, planTools, registerPlanMode } from '../src/plan.ts';
+
+type Handler = (event: unknown, ctx: unknown) => unknown;
+
+function harness(initialTools = ['read', 'bash', 'edit', 'write', 'Task', 'TodoWrite', 'AskQuestion', 'mcp']) {
+  const tools: ToolDefinition[] = [];
+  const handlers = new Map<string, Handler[]>();
+  const commands = new Map<string, { handler: (args: string, ctx: unknown) => Promise<void> }>();
+  const entries: { type: string; customType: string; data: unknown }[] = [];
+  const sent: { text: string; options: unknown }[] = [];
+  const notes: string[] = [];
+  const status = new Map<string, string | undefined>();
+  let active = [...initialTools];
+  const pi = {
+    registerTool: (tool: ToolDefinition) => tools.push(tool),
+    on: (event: string, handler: Handler) => handlers.set(event, [...(handlers.get(event) ?? []), handler]),
+    registerCommand: (name: string, options: { handler: (args: string, ctx: unknown) => Promise<void> }) => commands.set(name, options),
+    getActiveTools: () => [...active],
+    setActiveTools: (names: string[]) => {
+      active = [...names];
+    },
+    appendEntry: (customType: string, data: unknown) => entries.push({ type: 'custom', customType, data: structuredClone(data) }),
+    sendUserMessage: (text: string, options: unknown) => sent.push({ text, options }),
+  } as unknown as ExtensionAPI;
+  const ctx = {
+    hasUI: true,
+    isIdle: () => true,
+    ui: { notify: (text: string) => notes.push(text), setStatus: (key: string, text: string | undefined) => status.set(key, text), theme: { fg: (_color: string, text: string) => text } },
+    sessionManager: { getBranch: () => entries },
+  };
+  const plan = registerPlanMode(pi);
+  const emit = (event: string, payload: unknown = {}) => (handlers.get(event) ?? []).map((handler) => handler(payload, ctx));
+  const run = (args: string) => (commands.get('plan') as { handler: (args: string, ctx: unknown) => Promise<void> }).handler(args, ctx);
+  return { plan, tools, entries, sent, notes, status, emit, run, active: () => active, setActive: (names: string[]) => (active = names) };
+}
+
+test('parses the command forms', () => {
+  expect(parsePlanArgs('')).toEqual({ kind: 'status' });
+  expect(parsePlanArgs(' off ')).toEqual({ kind: 'off' });
+  expect(parsePlanArgs('on')).toEqual({ kind: 'on', task: '' });
+  expect(parsePlanArgs('add a cache layer')).toEqual({ kind: 'on', task: 'add a cache layer' });
+});
+
+test('registers the sandboxed shell inactive under its own name', () => {
+  const { tools } = harness();
+  expect(tools.map((tool) => [tool.name, tool.defaultActive])).toEqual([[PLAN_BASH, false]]);
+  expect(tools[0]?.description).toContain('denies filesystem writes and network access');
+});
+
+test('/plan restricts the tools and /plan off restores the exact earlier set', async () => {
+  const h = harness();
+  const before = h.active();
+  await h.run('');
+  expect(h.notes.at(-1)).toContain('off');
+  expect(h.plan.section()).toBeUndefined();
+
+  await h.run('on');
+  expect(h.active().toSorted()).toEqual(['AskQuestion', PLAN_BASH, 'Task', 'TodoWrite', 'find', 'grep', 'ls', 'read'].toSorted());
+  expect(h.status.get('pstack-plan')).toBe('plan');
+  expect(h.plan.section()).toBe(planSection());
+  expect(h.sent).toEqual([]);
+
+  await h.run('off');
+  expect(h.active()).toEqual(before);
+  expect(h.status.get('pstack-plan')).toBeUndefined();
+  expect(h.plan.section()).toBeUndefined();
+  expect(h.entries.map((entry) => entry.data)).toEqual([{ enabled: true, toolsBefore: before }, { enabled: false }]);
+});
+
+test('/plan <task> sends the task, and a second /plan keeps the first saved tool set', async () => {
+  const h = harness();
+  const before = h.active();
+  await h.run('investigate the flaky test');
+  expect(h.sent).toEqual([{ text: 'investigate the flaky test', options: { expandPromptTemplates: true } }]);
+  await h.run('another task');
+  await h.run('off');
+  expect(h.active()).toEqual(before);
+});
+
+test('plan mode never activates Task when it was off before', async () => {
+  expect(planTools(['read', 'bash', 'edit'])).toEqual(['read', 'grep', 'find', 'ls', PLAN_BASH]);
+});
+
+test('blocks writers and unknown tools, and lets Task run unchanged for it to restrict (C-M1)', async () => {
+  const h = harness();
+  const call = (toolName: string, input: Record<string, unknown> = {}) => ({ result: h.emit('tool_call', { toolName, input })[0], input });
+  expect(call('write').result).toBeUndefined();
+
+  await h.run('on');
+  expect(call('write').result).toEqual({ block: true, reason: planBlockReason('write') });
+  expect(planBlockReason('edit')).toContain('/plan off');
+  expect((call('bash').result as { reason: string }).reason).toContain(PLAN_BASH);
+  expect((call('mcp').result as { block: boolean }).block).toBe(true);
+  expect(call('read').result).toBeUndefined();
+  const task = call('Task', { prompt: 'look', description: 'x', readonly: false });
+  expect([task.result, task.input]).toEqual([undefined, { prompt: 'look', description: 'x', readonly: false }]);
+  expect(h.plan.enabled()).toBe(true);
+  await h.run('off');
+  expect(h.plan.enabled()).toBe(false);
+});
+
+test('restores plan mode from the session and drops a stray plan shell when off', async () => {
+  const h = harness();
+  await h.run('on');
+  const saved = (h.entries.at(-1) as { data: unknown }).data as { toolsBefore: string[] };
+  h.setActive(['read', 'bash', 'edit']);
+  h.emit('session_start');
+  expect(h.active()).toContain(PLAN_BASH);
+  expect(h.active()).not.toContain('edit');
+  await h.run('off');
+  expect(h.active()).toEqual(saved.toolsBefore);
+
+  h.setActive([...h.active(), PLAN_BASH]);
+  h.emit('session_start');
+  expect(h.active()).not.toContain(PLAN_BASH);
+});
+
+test('reads the last plan entry and treats malformed data as off', () => {
+  const entry = (data: unknown) => ({ type: 'custom', customType: PLAN_ENTRY, data });
+  expect(planFromBranch([])).toEqual({ enabled: false });
+  expect(planFromBranch([entry({ enabled: true, toolsBefore: ['read'] }), entry({ enabled: false })])).toEqual({ enabled: false });
+  expect(planFromBranch([entry({ enabled: true, toolsBefore: ['read', 3] })])).toEqual({ enabled: true });
+  expect(planFromBranch([entry(null)])).toEqual({ enabled: false });
+});

package/test/readonly-shell-security.test.ts

@@ -0,0 +1,84 @@
+import { existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { ExtensionAPI, ExtensionToolContext, ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { afterEach, expect, test, vi } from 'vitest';
+
+// The real sandbox is the subject here (macOS/Linux only); these tests prove the enforcement the tool promises.
+const supported = process.platform === 'darwin' || process.platform === 'linux';
+// An in-process consumer of the same dependency may have initialized a permissive policy first; the shell must not
+// inherit it (reviews/resume-security.md finding 3).
+vi.mock(import('@anthropic-ai/sandbox-runtime'), async (importOriginal) => {
+  const original = await importOriginal();
+  if (supported)
+    await original.SandboxManager.initialize({
+      network: { allowedDomains: ['example.com'], deniedDomains: [] },
+      filesystem: { denyRead: [], allowWrite: [tmpdir()], denyWrite: [] },
+    });
+  return original;
+});
+
+const { registerReadonlyShell } = await import('../src/readonly-shell.ts');
+
+let dir: string;
+afterEach(() => {
+  if (dir !== undefined) rmSync(dir, { recursive: true, force: true });
+});
+
+function bash(): ToolDefinition {
+  const tools: ToolDefinition[] = [];
+  registerReadonlyShell({ registerTool: (tool: ToolDefinition) => tools.push(tool), on: () => undefined } as unknown as ExtensionAPI);
+  const [tool] = tools;
+  if (tool === undefined) throw new Error('no tool registered');
+  return tool;
+}
+
+const run = async (tool: ToolDefinition, command: string, signal?: AbortSignal): Promise<string> => {
+  const result = await tool.execute('call', { command }, signal, undefined, { cwd: dir } as ExtensionToolContext);
+  return result.content.map((part) => (part.type === 'text' ? part.text : '')).join('\n');
+};
+
+test.skipIf(!supported)('a shared pre-initialized sandbox policy does not weaken the shell (TASK-019)', async () => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), 'pi-pstack-ro-shared-')));
+  const text = await run(bash(), `printf shared-escape > ${join(dir, 'shared-escape.txt')} && cat ${join(dir, 'shared-escape.txt')}`).catch((error: Error) => `ERROR: ${error.message}`);
+  expect(text).toMatch(/Operation not permitted|Read-only file system/);
+  expect(existsSync(join(dir, 'shared-escape.txt'))).toBe(false);
+});
+
+test.skipIf(!supported)('the dependency default write paths stay denied (TASK-019)', async () => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), 'pi-pstack-ro-paths-')));
+  const tmpClaude = process.platform === 'darwin' ? '/private/tmp/claude' : '/tmp/claude';
+  const home = homedir();
+  const homeEscape = join(home, '.claude/debug/pstack-escape.txt');
+  rmSync(homeEscape, { force: true });
+  const script = `mkdir -p ${tmpClaude} ~/.claude/debug 2>/dev/null; (printf x > ${tmpClaude}/pstack-escape && echo TMP-CLAUDE-WROTE); (printf x > ${homeEscape} && echo HOME-DEBUG-WROTE); echo done`;
+  const text = await run(bash(), script);
+  expect(text).not.toContain('TMP-CLAUDE-WROTE');
+  expect(text).not.toContain('HOME-DEBUG-WROTE');
+  expect(text).toContain('done');
+  expect(existsSync(homeEscape)).toBe(false);
+  rmSync(join(tmpClaude, 'pstack-escape'), { force: true });
+});
+
+test.skipIf(!supported)('an inherited BASH_ENV startup file never runs outside the sandbox (TASK-019)', async () => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), 'pi-pstack-ro-env-')));
+  const marker = join(dir, 'bashenv-escape.txt');
+  const startup = join(dir, 'startup.sh');
+  writeFileSync(startup, `printf escaped > ${marker}\n`);
+  process.env['BASH_ENV'] = startup;
+  try {
+    const text = await run(bash(), 'echo sandbox-ran');
+    expect(text).toContain('sandbox-ran');
+  } finally {
+    delete process.env['BASH_ENV'];
+  }
+  expect(existsSync(marker)).toBe(false);
+});
+
+test.skipIf(!supported)('an already-aborted call never spawns the command (TASK-019)', async () => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), 'pi-pstack-ro-abort-')));
+  const controller = new AbortController();
+  controller.abort();
+  await expect(run(bash(), 'sleep 1; printf ran-after-abort', controller.signal)).rejects.toThrow(/aborted/i);
+});

package/test/readonly-shell.test.ts

@@ -0,0 +1,44 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { ExtensionAPI, ExtensionToolContext, ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { expect, onTestFinished, test, vi } from 'vitest';
+import { registerReadonlyShell } from '../src/readonly-shell.ts';
+
+function registeredBash(): ToolDefinition {
+  const tools: ToolDefinition[] = [];
+  const pi = { registerTool: (tool: ToolDefinition) => tools.push(tool), on: () => undefined } as unknown as ExtensionAPI;
+  registerReadonlyShell(pi);
+  const [bash] = tools;
+  if (bash === undefined) throw new Error('no tool registered');
+  return bash;
+}
+
+test('describes the subprocess boundary without claiming whole-process isolation', () => {
+  const bash = registeredBash();
+  expect(bash.name).toBe('bash');
+  expect(bash.description).toContain('denies filesystem writes and network access');
+  expect(bash.description).toContain('Pi and trusted extensions are not sandboxed');
+});
+
+test.skipIf(process.platform !== 'darwin' && process.platform !== 'linux')('a process that used the shell exits on its own once its session shuts down', () => {
+  const cwd = mkdtempSync(join(tmpdir(), 'pi-pstack-ro-exit-'));
+  onTestFinished(() => rmSync(cwd, { recursive: true, force: true }));
+  const result = spawnSync(process.execPath, [join(import.meta.dirname, 'fixtures/readonly-shell-exit.ts')], { cwd, encoding: 'utf8', timeout: 20_000 });
+  expect(result.stdout).toContain('SANDBOXED');
+  expect(result.stdout).toContain('SHUTDOWN-DONE');
+  expect([result.error?.message, result.signal, result.status]).toEqual([undefined, null, 0]);
+});
+
+test('unsupported hosts fail closed without running a command', async () => {
+  vi.spyOn(process, 'platform', 'get').mockReturnValue('freebsd');
+  onTestFinished(() => {
+    vi.restoreAllMocks();
+  });
+  const cwd = mkdtempSync(join(tmpdir(), 'pi-pstack-ro-'));
+  onTestFinished(() => rmSync(cwd, { recursive: true, force: true }));
+  await expect(registeredBash().execute('call-1', { command: 'touch escaped.txt' }, undefined, undefined, { cwd } as ExtensionToolContext)).rejects.toThrow('no verified OS sandbox is available');
+  expect(existsSync(join(cwd, 'escaped.txt'))).toBe(false);
+});

package/test/records.test.ts

@@ -0,0 +1,143 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+
+import { SessionManager } from '@earendil-works/pi-coding-agent';
+import { afterEach, beforeEach, describe, expect, onTestFinished, test, vi } from 'vitest';
+import { storeDir, subagentDir, workspaceSlug, workspaceStateDir, worktreesDir } from '../src/paths.ts';
+import { acquireRunLock, readonlyLaunchRestores, readRecord, writeRecord } from '../src/task/records.ts';
+
+const id = '11111111-2222-4333-8444-555555555555';
+let dir = '';
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'locks-'));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+describe('run lock: one writer per agent ID (review: security 3, architecture 2)', () => {
+  test('a second acquire while the holder lives is refused, naming the lock file', () => {
+    const lock = acquireRunLock(dir, id);
+    expect(() => acquireRunLock(dir, id)).toThrow(`Agent ${id} is still running (pid ${process.pid}; lock ${join(dir, `${id}.lock`)}). Wait for its completion before resuming it.`);
+    lock.release();
+    expect(existsSync(join(dir, `${id}.lock`))).toBe(false);
+  });
+
+  test('the lock follows the child that writes the transcript (recheck)', () => {
+    const lock = acquireRunLock(dir, id);
+    const child = spawnSync(process.execPath, ['-e', 'process.stdout.write(String(process.pid))'], { encoding: 'utf8' }).stdout;
+    lock.holdFor(Number(child));
+    expect(readFileSync(join(dir, `${id}.lock`), 'utf8')).toBe(child);
+    lock.release();
+  });
+
+  test('a lock with no readable pid counts as held, naming the file to remove (fail closed)', () => {
+    writeFileSync(join(dir, `${id}.lock`), '');
+    expect(() => acquireRunLock(dir, id)).toThrow(`Agent ${id} is still running (pid unknown; lock ${join(dir, `${id}.lock`)}). Wait for its completion before resuming it.`);
+  });
+
+  test('release leaves a lock that another live holder took over', () => {
+    const lock = acquireRunLock(dir, id);
+    writeFileSync(join(dir, `${id}.lock`), String(process.ppid));
+    lock.release();
+    expect(readFileSync(join(dir, `${id}.lock`), 'utf8')).toBe(String(process.ppid));
+  });
+
+  test('release never throws, because a leftover lock is taken over once its holder is gone (review r2: security)', () => {
+    const lock = acquireRunLock(dir, id);
+    chmodSync(dir, 0o500);
+    try {
+      lock.release();
+    } finally {
+      chmodSync(dir, 0o700);
+    }
+    expect(readFileSync(join(dir, `${id}.lock`), 'utf8')).toBe(String(process.pid));
+  });
+
+  test('a lock left by a dead process is taken over', () => {
+    const dead = spawnSync(process.execPath, ['-e', 'process.stdout.write(String(process.pid))'], { encoding: 'utf8' }).stdout;
+    writeFileSync(join(dir, `${id}.lock`), dead);
+    const lock = acquireRunLock(dir, id);
+    expect(readFileSync(join(dir, `${id}.lock`), 'utf8')).toBe(String(process.pid));
+    expect(() => acquireRunLock(dir, id)).toThrow('is still running');
+    lock.release();
+  });
+});
+
+describe('agent records (review r2: architecture 5)', () => {
+  test.for(['{not json', '{"agentId":"x"}', '[]'])('a corrupt or partial record %j fails with a clear error', (text) => {
+    writeFileSync(join(dir, `${id}.json`), text);
+    expect(() => readRecord(dir, id)).toThrow(`Agent record ${join(dir, `${id}.json`)} is unreadable; delete it and start a new agent.`);
+  });
+
+  test("a cloud agent's worktree survives a write and read (TASK-010)", () => {
+    const worktree = { path: '/s/wt', cwd: '/s/wt/pkg', branch: `pstack/${id}`, base: 'main', commit: 'abc' };
+    writeRecord(dir, { agentId: id, type: 'generalPurpose', readonly: false, cwd: '/w/app', createdAt: 't', worktree });
+    expect(readRecord(dir, id)?.worktree).toEqual(worktree);
+  });
+
+  test.for([
+    { label: 'no createdAt', record: { agentId: id, type: 'generalPurpose', readonly: false, cwd: '/w/app' } },
+    { label: 'a model that is a string', record: { agentId: id, type: 'generalPurpose', readonly: false, cwd: '/w/app', createdAt: 't', model: 'p/m' } },
+    { label: 'a model without an id', record: { agentId: id, type: 'generalPurpose', readonly: false, cwd: '/w/app', createdAt: 't', model: { provider: 'p' } } },
+    { label: 'a thinking level that is not a string', record: { agentId: id, type: 'generalPurpose', readonly: false, cwd: '/w/app', createdAt: 't', model: { provider: 'p', id: 'm', thinking: 3 } } },
+  ])('a record with $label is unreadable (C-L3)', ({ record }) => {
+    writeFileSync(join(dir, `${id}.json`), JSON.stringify(record));
+    expect(() => readRecord(dir, id)).toThrow(`Agent record ${join(dir, `${id}.json`)} is unreadable; delete it and start a new agent.`);
+  });
+
+  test('a record whose worktree lacks a field is unreadable (TASK-010)', () => {
+    writeFileSync(join(dir, `${id}.json`), JSON.stringify({ agentId: id, type: 'generalPurpose', readonly: false, cwd: '/w/app', createdAt: 't', worktree: { path: '/s/wt' } }));
+    expect(() => readRecord(dir, id)).toThrow(`Agent record ${join(dir, `${id}.json`)} is unreadable; delete it and start a new agent.`);
+  });
+});
+
+describe('per-workspace state (review: parity 4)', () => {
+  test('names a workspace the way Pi names a session folder', () => {
+    expect([workspaceSlug('/Users/me/src/app'), workspaceSlug('/w/a:b')]).toEqual(['--Users-me-src-app--', '--w-a-b--']);
+  });
+
+  test('the workspace folder name stays the default session folder Pi gives that directory', () => {
+    vi.stubEnv('PI_CODING_AGENT_DIR', dir);
+    onTestFinished(() => {
+      vi.unstubAllEnvs();
+    });
+    for (const cwd of ['/Users/me/src/app', '/w/a:b']) expect(basename(SessionManager.create(cwd).getSessionDir())).toBe(workspaceSlug(cwd));
+  });
+
+  test("a subagent uses its main chat's workspace state, wherever it runs (C-M2)", () => {
+    expect([workspaceStateDir('/w/worktrees/agent-1', '/state/root-workspace'), workspaceStateDir('/w/app', undefined).endsWith('pstack/workspaces/--w-app--')]).toEqual(['/state/root-workspace', true]);
+  });
+
+  test('keeps subagents and the agent store under the workspace', () => {
+    const base = join(process.env['PI_CODING_AGENT_DIR'] ?? join(process.env['HOME'] ?? '', '.pi/agent'), 'pstack/workspaces/--w-app--');
+    expect([subagentDir('/w/app'), storeDir('/w/app', 'session-1'), worktreesDir('/w/app')]).toEqual([join(base, 'subagents'), join(base, 'store/session-1'), join(base, 'worktrees')]);
+  });
+});
+
+describe('tool loadout after a plan-mode launch (C-M1)', () => {
+  const tool = (name: string) => ({ name, description: name, parameters: { type: 'object' } });
+  const system = (id: string, parentId: string | null, added: string[], removed: string[] = []) => ({
+    type: 'message',
+    id,
+    parentId,
+    timestamp: '2026-10-28T10:00:00.000Z',
+    message: { role: 'system', content: '', toolsAdded: added.map(tool), toolsRemoved: removed.map((name) => ({ name })), timestamp: 0 },
+  });
+  const transcript = (...entries: unknown[]) => {
+    const path = join(dir, `2026-10-28T10-00-00-000Z_${id}.jsonl`);
+    writeFileSync(path, [{ type: 'session', version: 3, id, timestamp: '2026-10-28T10:00:00.000Z', cwd: '/w/app' }, ...entries].map((entry) => `${JSON.stringify(entry)}\n`).join(''));
+    return path;
+  };
+
+  test('gives back the tools a readonly launch took from the last writable loadout', () => {
+    const path = transcript(system('s1', null, ['read', 'bash', 'edit', 'write', 'Task']), system('s2', 's1', ['grep', 'bash'], ['bash', 'edit', 'write', 'Task']));
+    expect(readonlyLaunchRestores(path).toSorted()).toEqual(['Task', 'edit', 'write']);
+  });
+
+  test('gives back nothing when the loadout is writable or was never writable', () => {
+    const writable = readonlyLaunchRestores(transcript(system('s1', null, ['read', 'bash', 'edit', 'write'])));
+    const neverWritable = readonlyLaunchRestores(transcript(system('s1', null, ['read', 'grep'])));
+    expect({ writable, neverWritable }).toEqual({ writable: [], neverWritable: [] });
+  });
+});

package/test/registry.test.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { expect, test } from 'vitest';
+import { createSubagentRegistry } from '../src/task/registry.ts';
+import type { ChildOutcome } from '../src/task/runner.ts';
+
+const notice = { title: 't', toolCallId: 'c1', mode: 'json' as const, detailFor: () => ({ status: 'success' as const, detail: 'x' }) };
+const json = { mode: 'json' } as ExtensionContext;
+
+test('a one-shot run holds its exit for a running background subagent, unless the run was aborted (TASK-003; review r2: architecture)', async () => {
+  const registry = createSubagentRegistry({ sendMessage: () => undefined } as unknown as ExtensionAPI);
+  registry.track('11111111-2222-4333-8444-555555555555', { done: new Promise<ChildOutcome>(() => undefined), kill: () => undefined, stop: () => undefined, steer: async () => undefined, pid: 1 }, () => undefined, false, notice);
+  let completedSettled = false;
+  void registry.beforeSettle(json, 'completed').then(() => {
+    completedSettled = true;
+  });
+  const aborted = await registry.beforeSettle(json, 'aborted');
+  expect([aborted, completedSettled]).toEqual([undefined, false]);
+});

package/test/resources.test.ts

@@ -0,0 +1,162 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadSkills, parseFrontmatter } from '@earendil-works/pi-coding-agent';
+import { describe, expect, test } from 'vitest';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const PSTACK_HIDDEN = 57;
+const TEAM_KIT = ['control-cli', 'control-ui', 'deslop'];
+const STANDARD_FIELDS = new Set(['name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools', 'disable-model-invocation']);
+const SHIPPED_ROOTS = ['skills', 'agents', 'docs', 'automations', 'README.md'];
+
+function loadPackageSkills() {
+  return loadSkills({ cwd: tmpdir(), agentDir: join(tmpdir(), 'pi-pstack-no-agent-dir'), skillPaths: [join(root, 'skills')], includeDefaults: false });
+}
+
+function shippedFiles(predicate: (path: string) => boolean): string[] {
+  const files: string[] = [];
+  const walk = (directory: string) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name);
+      if (entry.name === 'node_modules' || entry.name === '.DS_Store') continue;
+      if (entry.isDirectory()) walk(path);
+      else if (predicate(path)) files.push(relative(root, path));
+    }
+  };
+  for (const shipped of SHIPPED_ROOTS) {
+    const path = join(root, shipped);
+    if (statSync(path).isDirectory()) walk(path);
+    else if (predicate(path)) files.push(shipped);
+  }
+  return files.sort();
+}
+
+/**
+ * Words that name Cursor's host rather than something a Pi user has. Nothing shipped may name Cursor (lowercase
+ * "cursor" is a text or loop cursor) except the spans listed in OUTSIDE_DATA, each on its own file with the reason.
+ */
+const CURSOR_HOST_TERMS =
+  /~\/\.cursor|\.cursor\/|\.cursor-plugin|\.mdc\b|Option\+Enter|Alt\+Enter|agent-transcripts|cursor\.com|github\.com\/cursor\/|api2\.cursor|update_state|SendToUser|add-plugin|Custom Mode|cloud agent|cloud VM|cursor-team-kit|Grok Bot/i;
+const OUTSIDE_DATA: { file: string; span: RegExp; reason: string }[] = [
+  { file: 'README.md', span: /A `pstack-models\.mdc` from an earlier version is moved there once, without its frontmatter, and kept as `pstack-models\.mdc\.migrated`\./, reason: 'names the legacy rule file pi-pstack migrates' },
+  { file: 'README.md', span: /`licenses\/cursor-team-kit\.LICENSE`/, reason: 'names the shipped MIT notice of deslop, control-cli, and control-ui' },
+];
+
+function hostTermLines(file: string, text: string): string[] {
+  const exempt = OUTSIDE_DATA.filter((entry) => entry.file === file);
+  return text.split('\n').flatMap((line, index) => {
+    const rest = exempt.reduce((remaining, entry) => remaining.replace(entry.span, ''), line);
+    return CURSOR_HOST_TERMS.test(rest) || /\bCursor\b/.test(rest) ? [`${file}:${index + 1}: ${line.trim().slice(0, 120)}`] : [];
+  });
+}
+
+describe('shipped resources', () => {
+  test('loads 62 skills with no diagnostics and names equal to directories (RES-001)', () => {
+    const { skills, diagnostics } = loadPackageSkills();
+    expect(diagnostics).toEqual([]);
+    expect(skills).toHaveLength(62);
+    const renamed = skills.filter((skill) => skill.name !== skill.filePath.split('/').at(-2));
+    expect(renamed.map((skill) => skill.name)).toEqual([]);
+    expect(skills.map((skill) => skill.name)).toEqual(expect.arrayContaining(['poteto-mode', 'make-bot-ui', 'how', 'setup-pstack', 'create-skill', 'ketchup-video', 'statechart', ...TEAM_KIT]));
+  });
+
+  test('keeps only Agent Skills fields at the top level of skill frontmatter (RES-004)', () => {
+    const extra = shippedFiles((path) => path.startsWith(join(root, 'skills')) && path.endsWith('/SKILL.md')).flatMap((path) => {
+      const { frontmatter } = parseFrontmatter(readFileSync(join(root, path), 'utf8'));
+      return Object.keys(frontmatter)
+        .filter((key) => !STANDARD_FIELDS.has(key))
+        .map((key) => `${path}: ${key}`);
+    });
+    expect(extra).toEqual([]);
+    const poteto = parseFrontmatter(readFileSync(join(root, 'skills/poteto-mode/SKILL.md'), 'utf8')).frontmatter;
+    expect(poteto['metadata']).toEqual({ icon: 'crown', color: 'yellow' });
+    const typescript = parseFrontmatter(readFileSync(join(root, 'skills/typescript-best-practices/SKILL.md'), 'utf8')).frontmatter;
+    expect(typescript['metadata']).toEqual({ paths: ['**/*.ts', '**/*.tsx'] });
+  });
+
+  test('hides 57 pstack skills from model invocation and keeps the rest invocable (RES-003, RES-005)', () => {
+    const { skills } = loadPackageSkills();
+    const invocable = skills.filter((skill) => !skill.disableModelInvocation).map((skill) => skill.name);
+    expect(invocable.toSorted()).toEqual(['control-cli', 'control-ui', 'create-skill', 'deslop', 'setup-pstack']);
+    expect(skills.filter((skill) => skill.disableModelInvocation)).toHaveLength(PSTACK_HIDDEN);
+  });
+
+  test('ships the two subagent definitions (RES-006)', () => {
+    expect(readdirSync(join(root, 'agents')).toSorted()).toEqual(['comment-sicko.md', 'poteto-agent.md']);
+  });
+
+  test('poteto-mode tells delegates where bundled skills live, and every principle it names is at ../<name>/SKILL.md (RES-010)', () => {
+    const potetoMode = join(root, 'skills/poteto-mode/SKILL.md');
+    const text = readFileSync(potetoMode, 'utf8');
+    expect(text).toContain('Bundled skills live at `../<name>/SKILL.md` from this file');
+    // Each Principles index entry names its leaf: an explicit (**principle-x**), else principle-<kebab title>.
+    const index = text.slice(text.indexOf('Each leaf is the **principle-<title>** skill'), text.indexOf('\n## ', text.indexOf('Each leaf is the')));
+    const leaves = [...index.matchAll(/^- \*\*([^*]+?)\.?\*\*(?: \(\*\*(principle-[a-z-]+)\*\*\))?/gm)].map(
+      ([, title = '', explicit]) =>
+        explicit ??
+        `principle-${title
+          .toLowerCase()
+          .replace(/[^a-z0-9 -]/g, '')
+          .replace(/ +/g, '-')}`,
+    );
+    expect(leaves.length).toBeGreaterThan(20);
+    expect(leaves.filter((name) => !existsSync(resolve(dirname(potetoMode), '..', name, 'SKILL.md')))).toEqual([]);
+  });
+
+  test('resolves every relative Markdown link in shipped text (RES-007)', () => {
+    const broken: string[] = [];
+    for (const file of shippedFiles((path) => path.endsWith('.md'))) {
+      const text = readFileSync(join(root, file), 'utf8');
+      // Every relative target that names a file or folder (an extension or a trailing /); placeholders such as (url) are not links.
+      for (const match of text.matchAll(/\]\((?![a-z]+:|#|\/)([^)#\s]+(?:\.[a-z0-9]+|\/))\)/gi)) {
+        const target = resolve(dirname(join(root, file)), match[1] ?? '');
+        if (!existsSync(target)) broken.push(`${file} -> ${match[1]}`);
+      }
+    }
+    expect(broken).toEqual([]);
+    expect(existsSync(join(root, 'docs/guide/01-setup.md'))).toBe(true);
+  });
+
+  test('ships Benny as files that never load as skills (RES-008)', () => {
+    expect(shippedFiles((path) => path.includes('/automations/benny/') && path.endsWith('SKILL.md'))).toHaveLength(3);
+    const { skills } = loadPackageSkills();
+    expect(skills.filter((skill) => skill.filePath.includes('/automations/'))).toEqual([]);
+  });
+
+  test('ships both MIT license texts (RES-009)', () => {
+    expect(readFileSync(join(root, 'licenses/pstack.LICENSE'), 'utf8')).toContain('Copyright (c) 2026 Lauren Tan');
+    expect(readFileSync(join(root, 'licenses/cursor-team-kit.LICENSE'), 'utf8')).toContain('MIT License');
+    const readme = readFileSync(join(root, 'README.md'), 'utf8');
+    expect(readme).toContain('licenses/pstack.LICENSE');
+    expect(readme).toContain('licenses/cursor-team-kit.LICENSE');
+  });
+
+  test('nothing depends on a Cursor plugin checkout: no sync script, lock, or host adapter (RES-011)', () => {
+    for (const path of ['upstream.lock.json', 'scripts/sync-upstream.mjs', 'scripts/patches.json', 'docs/harness']) expect(existsSync(join(root, path)), path).toBe(false);
+    const scripts = (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts: Record<string, string> }).scripts;
+    expect(Object.keys(scripts).filter((name) => name.includes('upstream'))).toEqual([]);
+  });
+
+  test('shipped text names Pi, not Cursor host features (RES-012)', () => {
+    const offending = shippedFiles(() => true).flatMap((file) => hostTermLines(file, readFileSync(join(root, file), 'utf8')));
+    const stale = OUTSIDE_DATA.filter(
+      (entry) =>
+        !readFileSync(join(root, entry.file), 'utf8')
+          .split('\n')
+          .some((line) => entry.span.test(line)),
+    );
+    expect({ offending, stale: stale.map((entry) => `${entry.file}: ${entry.reason}`) }).toEqual({ offending: [], stale: [] });
+  });
+
+  test('RES-012 catches host paths in any case, in README.md, and beside an exempt span', () => {
+    expect(hostTermLines('skills/x/SKILL.md', 'See https://GitHub.com/Cursor/plugins/blob/main/pstack/README.md.')).toHaveLength(1);
+    expect(hostTermLines('skills/x/SKILL.md', 'See https://cursor.com/changelog.')).toHaveLength(1);
+    expect(hostTermLines('README.md', 'Install with /add-plugin pstack.')).toHaveLength(1);
+    expect(hostTermLines('README.md', 'Theirs are in `licenses/cursor-team-kit.LICENSE`.')).toEqual([]);
+    expect(hostTermLines('README.md', 'Theirs are in `licenses/cursor-team-kit.LICENSE`, and Cursor reads them.')).toHaveLength(1);
+    expect(shippedFiles(() => true)).toContain('README.md');
+  });
+});