subrouter-cli 0.0.0-stage → 0.1.0

package/test/command-tools.test.ts

@@ -0,0 +1,141 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, test } from 'node:test';
+import { executeTool, prepareCommand, TOOL_DEFINITIONS } from '../src/tools.ts';
+import type { ToolCall } from '../src/types.ts';
+
+let base: string, cwd: string;
+beforeEach(async () => {
+  base = await fs.mkdtemp(path.join(os.tmpdir(), 'sub-command-tools-'));
+  cwd = path.join(base, 'project');
+  await fs.mkdir(cwd);
+  await fs.mkdir(path.join(base, 'outside'));
+});
+afterEach(async () => { await fs.rm(base, { recursive: true, force: true }); });
+function call(args: Record<string, unknown>): ToolCall {
+  return { id: 'command', name: 'run_command', arguments: args, argumentsJson: JSON.stringify(args) };
+}
+
+test('command metadata requires independent approval and cwd preparation is confined', async () => {
+  const tool = TOOL_DEFINITIONS.find((tool) => tool.name === 'run_command');
+  assert.equal(tool?.requiresApproval, true);
+  assert.equal(tool?.approvalScope, 'always');
+  await fs.mkdir(path.join(cwd, 'src'));
+  await fs.writeFile(path.join(cwd, 'file'), 'x');
+  await fs.symlink(path.join(base, 'outside'), path.join(cwd, 'escape'));
+  await fs.symlink('src', path.join(cwd, 'internal'));
+  const prepared = await prepareCommand(cwd, { command: 'pwd', cwd: 'internal' });
+  assert.equal(prepared.cwd, await fs.realpath(path.join(cwd, 'src')));
+  assert.equal(prepared.timeoutMs, 60000);
+  for (const directory of ['../outside', path.join(base, 'outside'), '~', 'escape', 'missing', 'file', '.sub-recovery', null]) {
+    await assert.rejects(() => prepareCommand(cwd, { command: 'pwd', cwd: directory }));
+  }
+  await assert.rejects(() => prepareCommand(cwd, { command: 'echo synthetic-key' }, ['synthetic-key']), /credential|secret|protected/);
+  await assert.rejects(() => prepareCommand(cwd, { command: 'pwd', cwd: 'synthetic-key' }, ['synthetic-key']), /credential/);
+});
+
+test('direct command execution without an explicit approval snapshot never spawns', async () => {
+  const result = await executeTool(call({ command: 'printf nope > marker' }), cwd);
+  assert.equal(result.isError, true);
+  assert.match(result.content, /separate explicit approval/);
+  await assert.rejects(() => fs.stat(path.join(cwd, 'marker')));
+});
+
+test('approved commands use the exact cwd / timeout and report nonzero exit as an error', async () => {
+  await fs.mkdir(path.join(cwd, 'src'));
+  const request = call({ command: 'pwd; printf warning >&2; exit 7', cwd: 'src', timeout_ms: 1000 });
+  const approved = await prepareCommand(cwd, request.arguments);
+  const result = await executeTool(request, cwd, { commandApproval: approved });
+  assert.equal(result.isError, true);
+  const output = JSON.parse(result.content);
+  assert.equal(output.status, 'failed');
+  assert.equal(output.exit_code, 7);
+  assert.equal(output.stdout.trim(), approved.cwd);
+  assert.equal(output.stderr, 'warning');
+});
+
+test('changing command arguments or directory resolution after approval cannot spawn', async () => {
+  const request = call({ command: 'printf ok' });
+  const approved = await prepareCommand(cwd, request.arguments);
+  request.arguments.command = 'printf nope > marker';
+  const result = await executeTool(request, cwd, { commandApproval: approved });
+  assert.equal(result.isError, true);
+  assert.match(result.content, /changed after approval/);
+  await assert.rejects(() => fs.stat(path.join(cwd, 'marker')));
+  await fs.mkdir(path.join(cwd, 'src'));
+  await fs.mkdir(path.join(cwd, 'other'));
+  await fs.symlink('src', path.join(cwd, 'link'));
+  const linked = call({ command: 'printf nope > marker', cwd: 'link' });
+  const linkedApproval = await prepareCommand(cwd, linked.arguments);
+  await fs.unlink(path.join(cwd, 'link'));
+  await fs.symlink('other', path.join(cwd, 'link'));
+  assert.equal((await executeTool(linked, cwd, { commandApproval: linkedApproval })).isError, true);
+  await assert.rejects(() => fs.stat(path.join(cwd, 'other/marker')));
+});
+
+test('a cancelled queued command never spawns and does not poison the mutation queue', async () => {
+  const first = call({ command: 'sleep 0.2; printf done', timeout_ms: 1000 });
+  let started!: () => void;
+  const ready = new Promise<void>((resolve) => { started = resolve; });
+  const firstApproval = await prepareCommand(cwd, first.arguments);
+  const task = executeTool(first, cwd, { commandApproval: firstApproval, onStart: started });
+  await ready;
+  const second = call({ command: 'printf nope > marker' });
+  const secondApproval = await prepareCommand(cwd, second.arguments);
+  const controller = new AbortController();
+  let secondStarted = false;
+  const queued = executeTool(second, cwd, { commandApproval: secondApproval, signal: controller.signal, onStart: () => { secondStarted = true; } });
+  controller.abort();
+  assert.equal((await task).isError, undefined);
+  assert.equal((await queued).isError, true);
+  assert.equal(secondStarted, false);
+  await assert.rejects(() => fs.stat(path.join(cwd, 'marker')));
+  const final = call({ command: 'printf final' });
+  const finalResult = await executeTool(final, cwd, { commandApproval: await prepareCommand(cwd, final.arguments) });
+  assert.equal(JSON.parse(finalResult.content).stdout, 'final');
+});
+
+test('automatic authorization requires live auto mode and rechecks command eligibility', async () => {
+  const request = call({ command: 'pwd' });
+  const approved = { ...await prepareCommand(cwd, request.arguments), kind: 'auto' as const };
+  for (const autoEnabled of [undefined, () => false]) {
+    let started = false;
+    const result = await executeTool(request, cwd, { commandApproval: approved, autoEnabled, onStart: () => { started = true; } });
+    assert.equal(result.isError, true);
+    assert.match(result.content, /revoked/);
+    assert.equal(started, false);
+  }
+  const result = await executeTool(request, cwd, { commandApproval: approved, autoEnabled: () => true });
+  assert.equal(result.isError, undefined);
+  assert.equal(JSON.parse(result.content).stdout.trim(), approved.cwd);
+  const unknown = call({ command: 'printf no > marker' });
+  const rejected = await executeTool(unknown, cwd, { commandApproval: { ...await prepareCommand(cwd, unknown.arguments), kind: 'auto' }, autoEnabled: () => true });
+  assert.equal(rejected.isError, true);
+  await assert.rejects(fs.stat(path.join(cwd, 'marker')));
+});
+
+test('queued automatic commands cannot run after revocation or a package script change', async () => {
+  for (const changeScript of [false, true]) {
+    await fs.writeFile(path.join(cwd, 'package.json'), JSON.stringify({ scripts: { test: 'node --test' } }));
+    const first = call({ command: 'sleep 0.1' });
+    let started!: () => void;
+    const ready = new Promise<void>((resolve) => { started = resolve; });
+    const task = executeTool(first, cwd, { commandApproval: await prepareCommand(cwd, first.arguments), onStart: started });
+    await ready;
+    const second = call({ command: 'npm test' });
+    let enabled = true, didStart = false;
+    const queued = executeTool(second, cwd, {
+      commandApproval: { ...await prepareCommand(cwd, second.arguments), kind: 'auto' },
+      autoEnabled: () => enabled,
+      onStart: () => { didStart = true; },
+    });
+    if (changeScript) await fs.writeFile(path.join(cwd, 'package.json'), JSON.stringify({ scripts: { test: 'printf no > marker' } }));
+    else enabled = false;
+    await task;
+    assert.equal((await queued).isError, true);
+    assert.equal(didStart, false);
+    await assert.rejects(fs.stat(path.join(cwd, 'marker')));
+  }
+});

package/test/commandpolicy.test.ts

@@ -0,0 +1,252 @@
+import assert from 'node:assert/strict';
+import { constants } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, test } from 'node:test';
+import { commandPolicy } from '../src/commandpolicy.ts';
+
+let base: string;
+let cwd: string;
+beforeEach(async () => {
+  base = await fs.mkdtemp(path.join(os.tmpdir(), 'sub-command-policy-'));
+  cwd = path.join(base, 'project');
+  await fs.mkdir(cwd);
+  await fs.mkdir(path.join(cwd, 'src'));
+  await fs.mkdir(path.join(cwd, 'test'));
+  await fs.writeFile(path.join(cwd, 'src', 'example.ts'), '');
+  await fs.writeFile(path.join(cwd, 'test', 'example.test.ts'), '');
+  await fs.writeFile(path.join(cwd, 'test', 'with space.test.ts'), '');
+  await fs.writeFile(path.join(cwd, 'tsconfig.json'), '{}');
+  await manifest({ test: 'node --test', typecheck: 'tsc --noEmit', build: 'vite build', lint: 'eslint src', check: 'npm run typecheck && npm run lint' });
+});
+afterEach(async () => { await fs.rm(base, { recursive: true, force: true }); });
+async function manifest(scripts: Record<string, unknown>): Promise<void> {
+  await fs.writeFile(path.join(cwd, 'package.json'), JSON.stringify({ scripts }));
+}
+async function allowed(commands: string[]): Promise<void> {
+  for (const command of commands) {
+    const result = await commandPolicy(command, cwd);
+    assert.equal(result.auto, true, command);
+    assert.equal(typeof result.reason, 'string');
+  }
+}
+async function asked(commands: string[]): Promise<void> {
+  for (const command of commands) {
+    const result = await commandPolicy(command, cwd);
+    assert.equal(result.auto, false, command);
+    assert.equal(result.reason, 'This command requires explicit approval.');
+  }
+}
+
+test('exact literals, whole quoted tokens, and checked && segments', async () => {
+  await allowed(['pwd', ' pwd ', '"pwd"', "'pwd'", 'pwd&&pwd', 'pwd && node --test', 'node --test "test/with space.test.ts"', "node --test 'test/example.test.ts'"]);
+  await asked(['', ' ', '&&pwd', 'pwd&&', 'pwd & pwd', 'pwd&&&pwd', 'p"wd"', '"pwd"x', 'pwd ""', "'pwd", 'pwd\t', 'pwd\n', 'pwd\r', 'pwd\0', 'pwd\x1b', 'ｐｗｄ', `pwd ${'x'.repeat(8192)}`]);
+});
+
+test('shell syntax is rejected even inside quotes, without executing examples', async () => {
+  await asked([
+    'pwd;pwd', 'pwd | pwd', 'pwd || pwd', 'pwd > out', 'pwd 2>&1', 'pwd < in', 'pwd # comment',
+    '$(pwd)', '`pwd`', '$PWD', 'node --test "$PWD"', 'node --test "$(pwd)"',
+    'pwd\\', 'node --test test/*.ts', 'node --test "test/*.ts"', 'node --test test/?.ts',
+    'node --test [abc].ts', 'node --test {a,b}.ts', 'node --test ~/test.ts',
+    '(pwd)', 'pwd &', '! pwd', 'FOO=bar pwd', 'export FOO=bar', 'pwd && FOO=bar node --test',
+    'node --test "test/a;pwd.ts"', 'node --test "test/a#b.ts"', 'node --test "test/a\\b.ts"',
+  ]);
+});
+
+test('unknown executables, wrappers, networking, destructive operations, and interpreters ask', async () => {
+  await asked([
+    'sudo pwd', 'rm file', 'mkdir new', 'touch file', 'mv a b', 'cp a b', 'dd if=a of=b',
+    'git reset --hard', 'git push --force', 'git clean -fd', 'git checkout main',
+    'curl https://example.com', 'wget https://example.com', 'npm install', 'npm ci', 'npx tsc --noEmit',
+    'bash -c pwd', 'sh -c pwd', 'zsh -f -c pwd', 'env pwd', 'command pwd', 'exec pwd',
+    'python -c pass', 'ruby -e exit', 'node src/example.ts', 'node -e code', '/bin/pwd', './pwd', 'pwd --help',
+    'pwd && curl https://example.com', 'NODE_OPTIONS=x node --test',
+  ]);
+});
+
+test('Git uses exact guarded inspection forms and limited flags', async () => {
+  await allowed([
+    'git --no-pager status', 'git --no-pager status --short --branch',
+    'git --no-pager status --porcelain=v2 --untracked-files=no',
+    'git --no-pager diff --no-ext-diff --no-textconv',
+    'git --no-pager diff --no-ext-diff --no-textconv --cached --stat -- src',
+    'git --no-pager diff --no-ext-diff --no-textconv --check',
+    'git --no-pager log --oneline --max-count=5', 'git --no-pager log -n 2 HEAD',
+    'git --no-pager show --no-ext-diff --no-textconv HEAD',
+    'git --no-pager ls-files --cached --stage -- src/example.ts',
+  ]);
+  await asked([
+    'git status', 'git diff', 'git --no-pager diff', 'git --no-pager diff --no-ext-diff',
+    'git --no-pager show HEAD', 'git --no-pager log -p', 'git --no-pager log --patch',
+    'git -c core.pager=x status', 'git --no-pager -C src status', 'git --no-pager --git-dir=src status',
+    'git --no-pager diff --no-ext-diff --no-textconv --output=out',
+    'git --no-pager diff --no-ext-diff --no-textconv --ext-diff',
+    'git --no-pager show --no-ext-diff --no-textconv --textconv HEAD',
+    'git --no-pager log --format=x', 'git --no-pager log --max-count=0', 'git --no-pager log -n 1001',
+    'git --no-pager log --max-count=1 --max-count=2', 'git --no-pager log --oneline --oneline',
+    'git --no-pager log HEAD main', 'git --no-pager log --all',
+    'git --no-pager ls-files --error-unmatch', 'git --no-pager status -- ../outside',
+    'git --no-pager status -- :/src', 'git --no-pager status -- /tmp',
+  ]);
+});
+
+test('Node only permits test mode with built-in reporters and strict test flags', async () => {
+  await allowed([
+    'node --test', 'node --test --test-concurrency=2 --test-reporter=dot',
+    'node --test --test-concurrency 2 --test-reporter spec test/example.test.ts',
+    'node --test --test-only --test-timeout=1000 "--test-name-pattern=simple test"',
+    'node --test --test-skip-pattern=slow -- test/example.test.ts',
+  ]);
+  await asked([
+    'node --test --eval=x', 'node --test -e x', 'node --test --import=src/example.ts',
+    'node --test --require=src/example.ts', 'node --test --loader=src/example.ts', 'node --test --watch',
+    'node --test --test-reporter=src/example.ts', 'node --test --test-reporter-destination=out',
+    'node --test --test-concurrency=0', 'node --test --test-concurrency=257', 'node --test --test-concurrency=2x',
+    'node --test --test-reporter', 'node --test --test-reporter=dot --test-reporter=tap',
+    'node --test --test-only=true', 'node --test --test-timeout=-1', 'node --test --test-timeout=600001',
+    'node --test --test-name-pattern=--import', 'node --test tsconfig.json', 'node --test test',
+    'node --test -- --import=src/example.ts', 'node --test -- src/missing.ts',
+  ]);
+});
+
+test('compiler, Vite build, and lint flags stay narrow and output customization asks', async () => {
+  await allowed([
+    'tsc', 'tsc --noEmit', 'tsc --noEmit --pretty false', 'tsc --strict --skipLibCheck',
+    'tsc --noEmit --project tsconfig.json', 'tsc -p ./tsconfig.json --noEmit true',
+    'tsc --build', 'tsc -b tsconfig.json', 'vite build',
+    'eslint .', 'eslint src test --quiet --max-warnings=0',
+    'eslint --ext .ts,.js --format json src', 'eslint --no-fix -- src/example.ts',
+  ]);
+  await asked([
+    'tsc --watch', 'tsc -w', 'tsc --outDir elsewhere', 'tsc --outFile output.js', 'tsc --noEmit false',
+    'tsc --project ../tsconfig.json', 'tsc --project tsconfig.json --project tsconfig.json',
+    'tsc --build --clean', 'tsc --build --force', 'tsc --unknown', 'tsc --noEmit --noEmit',
+    'vite', 'vite dev', 'vite build --outDir elsewhere', 'vite build --config src/example.ts',
+    'eslint', 'eslint --fix src', 'eslint --cache src', 'eslint --output-file out src',
+    'eslint --config src/example.ts src', 'eslint --format src/example.ts src',
+    'eslint --rule custom src', 'eslint --max-warnings=-1 src', 'eslint --ext .exe src',
+    'eslint --quiet=true src', 'eslint --max-warnings src', 'eslint -- --fix',
+  ]);
+});
+
+test('paths reject traversal, absolutes, missing paths, and external symlinks', async () => {
+  await fs.writeFile(path.join(base, 'outside.ts'), '');
+  await fs.symlink(path.join(base, 'outside.ts'), path.join(cwd, 'escape.ts'));
+  await fs.symlink('test/example.test.ts', path.join(cwd, 'internal.ts'));
+  await allowed(['node --test ./test/example.test.ts', 'node --test internal.ts']);
+  await asked([
+    `node --test ${path.join(base, 'outside.ts')}`, 'node --test ../outside.ts',
+    'node --test test/../../outside.ts', 'node --test test/../test/example.test.ts',
+    'node --test escape.ts', 'eslint escape.ts', 'node --test missing.ts',
+    'eslint /tmp', 'eslint ../', 'eslint src/--option', 'node --test file:src/example.ts',
+  ]);
+});
+
+test('npm exact allowed scripts recursively validate pre/post lifecycle commands', async () => {
+  await allowed(['npm test', 'npm run test', 'npm run build', 'npm run lint', 'npm run typecheck', 'npm run check']);
+  await asked([
+    'npm test -- --test-only', 'npm run typecheck --', 'npm run build --prefix src',
+    'npm --prefix src test', 'npm run test --workspace=x', 'npm -w x test',
+    'npm run test --ignore-scripts', 'npm run start', 'npm start', 'npm run harness',
+    'npm run test extra', 'npm run', 'npm run TEST',
+  ]);
+  await manifest({ test: 'node --test', pretest: 'tsc --noEmit', posttest: 'eslint src' });
+  await allowed(['npm test']);
+  await manifest({ test: 'node --test', pretest: 'rm marker' });
+  await asked(['npm test']);
+  await manifest({ test: 'node --test', posttest: 'curl https://example.com' });
+  await asked(['npm test']);
+  await manifest({ test: 'node --test', posttest: false });
+  await asked(['npm test']);
+  await manifest({ test: 'node --test', pretest: '' });
+  await asked(['npm test']);
+  await manifest({ test: 'node --test', unrelated: 'rm marker', prepare: 'curl https://example.com' });
+  await allowed(['npm test']);
+});
+
+test('npm scripts are not opaque, cached, implicit, or cycle-permissive', async () => {
+  await manifest({ test: 'node src/example.ts', typecheck: 'tsc --noEmit' });
+  await asked(['npm test']);
+  await allowed(['npm run typecheck']);
+  await manifest({ test: 'node --test' });
+  await allowed(['npm test']);
+  await manifest({ test: 'rm marker' });
+  await asked(['npm test']);
+  await manifest({ test: 'npm test' });
+  await asked(['npm test']);
+  await manifest({ test: 'npm run check', check: 'npm run test' });
+  await asked(['npm test']);
+  await manifest({ test: 'node --test', pretest: 'npm test' });
+  await asked(['npm test']);
+  await manifest({ test: 'npm run check && npm run check', check: 'tsc --noEmit' });
+  await allowed(['npm test']);
+  await manifest({ test: true });
+  await asked(['npm test']);
+  await manifest({});
+  await asked(['npm test']);
+});
+
+test('bounded manifest reads reject missing, nonregular, symlinked, malformed, and large files', async (t) => {
+  const file = path.join(cwd, 'package.json');
+  const resolvedFile = await fs.realpath(file);
+  const originalOpen = fs.open;
+  let sawFlags = false;
+  t.mock.method(fs, 'open', async (name: Parameters<typeof fs.open>[0], flags: Parameters<typeof fs.open>[1]) => {
+    assert.equal(name, resolvedFile);
+    assert.equal(typeof flags, 'number');
+    assert.ok((Number(flags) & constants.O_NOFOLLOW) !== 0);
+    assert.ok((Number(flags) & constants.O_NONBLOCK) !== 0);
+    sawFlags = true;
+    return originalOpen(name, flags);
+  });
+  await allowed(['npm test']);
+  assert.equal(sawFlags, true);
+  t.mock.restoreAll();
+  await fs.unlink(file);
+  await asked(['npm test']);
+  await fs.mkdir(file);
+  await asked(['npm test']);
+  await fs.rmdir(file);
+  await fs.writeFile(path.join(base, 'manifest.json'), JSON.stringify({ scripts: { test: 'node --test' } }));
+  await fs.symlink(path.join(base, 'manifest.json'), file);
+  await asked(['npm test']);
+  await fs.unlink(file);
+  for (const text of ['not json', 'null', '[]', '{"scripts":[]}', '{"scripts":"node --test"}', ' '.repeat(65537)]) {
+    await fs.writeFile(file, text);
+    await asked(['npm test']);
+  }
+  await fs.writeFile(file, Buffer.from([0xff, 0xfe]));
+  await asked(['npm test']);
+});
+
+test('recursive validation is bounded by segment count, total work, and script text', async () => {
+  await asked([Array(17).fill('pwd').join(' && ')]);
+  await manifest({ test: Array(16).fill('npm run check').join(' && '), check: Array(16).fill('pwd').join(' && ') });
+  await asked(['npm test']);
+  await manifest({ test: Array(8).fill('npm run check').join(' && '), check: `pwd${' '.repeat(8000)}` });
+  await asked(['npm test']);
+  await manifest({ test: `pwd${' '.repeat(8192)}` });
+  await asked(['npm test']);
+});
+
+test('result reasons are safe fixed text and do not promise a sandbox', async () => {
+  await manifest({ test: 'unknown-sensitive-marker' });
+  const denied = await commandPolicy('npm test', cwd);
+  assert.equal(denied.auto, false);
+  assert.ok(!denied.reason.includes('sensitive-marker'));
+  const result = await commandPolicy('node --test', cwd);
+  assert.match(result.reason, /trusted project code/);
+  assert.match(result.reason, /not sandboxed/);
+  const inspection = await commandPolicy('pwd', cwd);
+  assert.match(inspection.reason, /trusted tool configuration/i);
+  assert.match(inspection.reason, /not a sandbox/);
+  // Callers cannot mutate shared result constants to change future decisions.
+  result.auto = false;
+  denied.auto = true;
+  await allowed(['node --test']);
+  await asked(['unknown-sensitive-marker']);
+  assert.equal((await commandPolicy('pwd', path.join(base, 'missing'))).auto, false);
+  assert.equal((await commandPolicy('pwd', path.join(cwd, 'package.json'))).auto, false);
+});

package/test/disk-tools.test.ts

@@ -0,0 +1,220 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { executeTool, MAX_READ_BYTES, MAX_TREE_BYTES, MAX_TREE_ENTRIES, RECOVERY_DIR } from '../src/tools.ts';
+
+let base: string, cwd: string, outside: string;
+beforeEach(async () => {
+  base = await fs.mkdtemp(path.join(os.tmpdir(), 'sub-disk-'));
+  cwd = path.join(base, 'project');
+  outside = path.join(base, 'outside');
+  await fs.mkdir(cwd);
+  await fs.mkdir(outside);
+  await fs.writeFile(path.join(cwd, 'hello.txt'), 'hello');
+  await fs.writeFile(path.join(outside, 'secret'), 'outside');
+});
+afterEach(async () => { await fs.rm(base, { recursive: true, force: true }); });
+
+function run(name: string, args: Record<string, unknown> = {}) {
+  return executeTool({ id: 'test', name, arguments: args, argumentsJson: JSON.stringify(args) }, cwd);
+}
+async function good(name: string, args: Record<string, unknown> = {}) {
+  const result = await run(name, args);
+  assert.equal(result.isError, undefined, result.content);
+  assert.equal(result.toolCallId, 'test');
+  return result.content;
+}
+async function bad(name: string, args: Record<string, unknown>, pattern?: RegExp) {
+  const result = await run(name, args);
+  assert.equal(result.isError, true, result.content);
+  if (pattern) assert.match(result.content, pattern);
+}
+async function exists(relative: string) { return !!await fs.lstat(path.join(cwd, relative)).catch(() => null); }
+
+it('creates nested directories without changing existing content', async () => {
+  await good('make_dir', { path: 'new/project/src' });
+  await good('make_dir', { path: 'new/project/src' });
+  assert.ok((await fs.stat(path.join(cwd, 'new/project/src'))).isDirectory());
+  await bad('make_dir', { path: 'hello.txt' });
+});
+
+it('batch reads retain per-path errors and enforce count / total byte bounds', async () => {
+  await fs.writeFile(path.join(cwd, 'large.txt'), 'x'.repeat(MAX_READ_BYTES));
+  const results = JSON.parse(await good('read_files', { paths: ['hello.txt', 'missing', '../outside/secret', 'large.txt'] }));
+  assert.equal(results[0].content, 'hello');
+  assert.ok(results.slice(1).every((r: { error?: string }) => r.error));
+  const exact = JSON.parse(await good('read_files', { paths: ['large.txt', 'hello.txt'] }));
+  assert.equal(exact[0].content.length, MAX_READ_BYTES);
+  assert.match(exact[1].error, /limit 0/);
+  for (const paths of [[], ['hello.txt', 42], Array(21).fill('hello.txt'), 'hello.txt']) await bad('read_files', { paths });
+});
+
+it('reports metadata without binary content and rejects binary text reads', async () => {
+  await fs.writeFile(path.join(cwd, 'image.bin'), Buffer.from([0, 1, 255]));
+  const info = JSON.parse(await good('file_info', { path: 'image.bin' }));
+  assert.equal(info.type, 'file');
+  assert.equal(info.size_bytes, 3);
+  assert.match(info.permissions, /^[0-7]{3}$/);
+  assert.ok(Number.isFinite(Date.parse(info.modified_at)));
+  await fs.symlink('hello.txt', path.join(cwd, 'local-link'));
+  assert.equal(JSON.parse(await good('file_info', { path: 'local-link' })).type, 'symlink');
+  await bad('read_file', { path: 'image.bin' }, /binary/);
+  await fs.writeFile(path.join(cwd, 'binary-match'), Buffer.from('needle\0secret'));
+  assert.equal(await good('grep', { pattern: 'needle' }), '(no matches)');
+});
+
+it('finds nested paths with literal filters, skips links and generated directories', async () => {
+  for (const dir of ['src/nested', 'node_modules/pkg', '.git', RECOVERY_DIR]) await fs.mkdir(path.join(cwd, dir), { recursive: true });
+  for (const file of ['src/nested/main.ts', 'node_modules/pkg/no.ts', '.git/no.ts', `${RECOVERY_DIR}/no.ts`]) await fs.writeFile(path.join(cwd, file), 'x');
+  await fs.symlink(outside, path.join(cwd, 'outside-link'));
+  assert.equal(await good('find_files', { pattern: '.ts', type: 'file' }), 'src/nested/main.ts');
+  assert.equal(await good('find_files', { path: 'src', type: 'directory' }), 'nested/');
+  assert.equal(await good('find_files', { pattern: '*.ts' }), '(no matches)');
+  await bad('find_files', { type: 'invalid' });
+  await bad('find_files', { path: 'hello.txt' });
+  for (let i = 0; i < 510; i++) await fs.writeFile(path.join(cwd, `file-${i}`), '');
+  assert.match(await good('find_files'), /capped/);
+});
+
+it('copies text, binary assets and trees without overwriting', async () => {
+  await fs.mkdir(path.join(cwd, 'assets/empty'), { recursive: true });
+  const bytes = Buffer.from([0, 2, 3, 255]);
+  await fs.writeFile(path.join(cwd, 'assets/photo.bin'), bytes);
+  await fs.writeFile(path.join(cwd, 'assets/tool'), 'script', { mode: 0o755 });
+  await good('copy_path', { source: 'assets', destination: 'new/assets' });
+  assert.deepEqual(await fs.readFile(path.join(cwd, 'new/assets/photo.bin')), bytes);
+  assert.equal((await fs.stat(path.join(cwd, 'new/assets/tool'))).mode & 0o777, 0o755);
+  assert.ok(await exists('new/assets/empty'));
+  await good('copy_path', { source: 'hello.txt', destination: 'copied.txt' });
+  await bad('copy_path', { source: 'hello.txt', destination: 'copied.txt' }, /exists/);
+  await bad('copy_path', { source: 'assets', destination: 'assets/child' }, /source tree/);
+  assert.equal(await fs.readFile(path.join(cwd, 'copied.txt'), 'utf8'), 'hello');
+});
+
+it('moves and renames files / directories, including empty directories', async () => {
+  await good('move_path', { source: 'hello.txt', destination: 'new/renamed.txt' });
+  assert.ok(!await exists('hello.txt'));
+  await fs.mkdir(path.join(cwd, 'empty'));
+  await bad('move_path', { source: 'new', destination: 'empty' }, /exists/);
+  await good('move_path', { source: 'new', destination: 'renamed' });
+  assert.equal(await fs.readFile(path.join(cwd, 'renamed/renamed.txt'), 'utf8'), 'hello');
+  await good('move_path', { source: 'empty', destination: 'empty2' });
+});
+
+it('preflights size / entry caps before copying, moving or removing', async () => {
+  const file = await fs.open(path.join(cwd, 'too-large'), 'w');
+  await file.truncate(MAX_TREE_BYTES + 1); await file.close();
+  for (const name of ['copy_path', 'move_path']) await bad(name, { source: 'too-large', destination: 'not-created/deep/file' }, /100 MiB/);
+  await bad('remove_path', { path: 'too-large' }, /100 MiB/);
+  assert.ok(!await exists('not-created'));
+  assert.ok(!await exists(RECOVERY_DIR));
+  await fs.mkdir(path.join(cwd, 'many'));
+  for (let i = 0; i < MAX_TREE_ENTRIES; i++) await fs.writeFile(path.join(cwd, 'many', String(i)), '');
+  await bad('copy_path', { source: 'many', destination: 'many-copy' }, /entries/);
+  assert.ok(!await exists('many-copy'));
+});
+
+it('serializes conflicting mutations so only one destination is created', async () => {
+  const results = await Promise.all([
+    run('move_path', { source: 'hello.txt', destination: 'first' }),
+    run('move_path', { source: 'hello.txt', destination: 'second' }),
+  ]);
+  assert.equal(results.filter((r) => !r.isError).length, 1);
+  assert.notEqual(await exists('first'), await exists('second'));
+  await good('write_file', { path: 'after-failure.txt', content: 'queue still works' });
+});
+
+it('removes recoverably, lists IDs, refuses occupied restore paths, and restores trees', async () => {
+  await fs.mkdir(path.join(cwd, 'work/empty'), { recursive: true });
+  await fs.writeFile(path.join(cwd, 'work/data'), 'keep');
+  assert.deepEqual(JSON.parse(await good('list_removed')).items, []);
+  const removed = JSON.parse(await good('remove_path', { path: 'work' }));
+  assert.equal(await fs.readFile(path.join(cwd, RECOVERY_DIR, '.gitignore'), 'utf8'), '*\n');
+  assert.ok(!await exists('work'));
+  const listing = JSON.parse(await good('list_removed'));
+  assert.equal(listing.items[0].recovery_id, removed.recovery_id);
+  assert.equal(listing.items[0].path, 'work');
+  assert.equal((await fs.stat(path.join(cwd, RECOVERY_DIR))).mode & 0o777, 0o700);
+  await fs.mkdir(path.join(cwd, 'work'));
+  await bad('restore_file', { recovery_id: removed.recovery_id }, /exists/);
+  await good('restore_file', { recovery_id: removed.recovery_id, destination: 'restored/work' });
+  assert.equal(await fs.readFile(path.join(cwd, 'restored/work/data'), 'utf8'), 'keep');
+  assert.ok(await exists('restored/work/empty'));
+  assert.deepEqual(JSON.parse(await good('list_removed')).items, []);
+  await bad('restore_file', { recovery_id: removed.recovery_id });
+  const file = JSON.parse(await good('remove_path', { path: 'hello.txt' }));
+  await good('restore_file', { recovery_id: file.recovery_id });
+  assert.equal(await fs.readFile(path.join(cwd, 'hello.txt'), 'utf8'), 'hello');
+});
+
+it('confines all new paths and protects project root, git internals and symlink trees', async () => {
+  await fs.symlink(outside, path.join(cwd, 'escape'));
+  await fs.symlink(path.join(outside, 'new'), path.join(cwd, 'dangling'));
+  await fs.mkdir(path.join(cwd, 'tree'));
+  await fs.symlink('hello.txt', path.join(cwd, 'local-link'));
+  await fs.symlink(outside, path.join(cwd, 'tree/nested-link'));
+  for (const raw of ['../outside', outside, '~/.ssh', 'escape', 'dangling']) {
+    for (const name of ['make_dir', 'remove_path', 'file_info']) await bad(name, { path: raw });
+    for (const name of ['copy_path', 'move_path']) {
+      await bad(name, { source: raw, destination: 'new' });
+      await bad(name, { source: 'hello.txt', destination: raw });
+    }
+  }
+  for (const raw of ['.', '.git/config', 'local-link']) {
+    for (const name of ['remove_path', 'write_file', 'edit_file', 'make_dir']) await bad(name, { path: raw, content: 'no', old_string: 'hello', new_string: 'no' });
+  }
+  for (const name of ['copy_path', 'move_path']) await bad(name, { source: 'tree', destination: 'new' }, /symlink/);
+  await bad('remove_path', { path: 'tree' }, /symlink/);
+  assert.equal(await fs.readFile(path.join(outside, 'secret'), 'utf8'), 'outside');
+  assert.ok(!await fs.lstat(path.join(outside, 'new')).catch(() => null));
+});
+
+describe('recovery confinement', () => {
+  it('refuses direct and aliased access to recovery storage', async () => {
+    const removed = JSON.parse(await good('remove_path', { path: 'hello.txt' }));
+    await fs.symlink(RECOVERY_DIR, path.join(cwd, 'recovery-alias'));
+    for (const raw of [RECOVERY_DIR, `x/../${RECOVERY_DIR}`, 'recovery-alias']) {
+      for (const name of ['read_file', 'list_dir', 'find_files', 'write_file', 'remove_path']) await bad(name, { path: raw, content: 'no' }, /recovery/);
+    }
+    await good('restore_file', { recovery_id: removed.recovery_id });
+  });
+  it('rejects non-private recovery storage without moving the source', async () => {
+    await fs.mkdir(path.join(cwd, RECOVERY_DIR), { mode: 0o755 });
+    await bad('remove_path', { path: 'hello.txt' }, /private/);
+    assert.ok(await exists('hello.txt'));
+  });
+  it('rejects a symlink recovery root without moving the source', async () => {
+    await fs.symlink(outside, path.join(cwd, RECOVERY_DIR));
+    await bad('remove_path', { path: 'hello.txt' }, /real directory/);
+    await bad('list_removed', {}, /real directory/);
+    assert.ok(await exists('hello.txt'));
+  });
+  it('rejects malicious IDs, records, payload links and entry links', async () => {
+    const removed = JSON.parse(await good('remove_path', { path: 'hello.txt' }));
+    const entry = path.join(cwd, RECOVERY_DIR, removed.recovery_id);
+    for (const id of ['../outside', 'no', null]) await bad('restore_file', { recovery_id: id });
+    await fs.writeFile(path.join(entry, 'record.json'), JSON.stringify({ path: '../outside/secret', removed_at: 'now' }));
+    await bad('restore_file', { recovery_id: removed.recovery_id }, /escapes/);
+    await fs.writeFile(path.join(entry, 'record.json'), JSON.stringify({ path: 'hello.txt', removed_at: 'now' }));
+    await fs.unlink(path.join(entry, 'item'));
+    await fs.symlink(path.join(outside, 'secret'), path.join(entry, 'item'));
+    await bad('restore_file', { recovery_id: removed.recovery_id }, /symlink/);
+    await fs.unlink(path.join(entry, 'record.json'));
+    await fs.symlink(path.join(outside, 'secret'), path.join(entry, 'record.json'));
+    await bad('restore_file', { recovery_id: removed.recovery_id });
+    await fs.rm(entry, { recursive: true });
+    await fs.symlink(outside, entry);
+    await bad('restore_file', { recovery_id: removed.recovery_id }, /invalid recovery entry/);
+    assert.equal(await fs.readFile(path.join(outside, 'secret'), 'utf8'), 'outside');
+  });
+});
+
+it('rejects missing write/edit content, empty edit matches, and oversized edits without data loss', async () => {
+  await bad('write_file', { path: 'hello.txt' }, /content/);
+  await bad('edit_file', { path: 'hello.txt', old_string: 'hello' }, /new_string/);
+  await bad('edit_file', { path: 'hello.txt', old_string: '', new_string: 'bad' }, /old_string/);
+  await bad('edit_file', { path: 'hello.txt', old_string: 'hello', new_string: 'x'.repeat(1024 * 1024 + 1) }, /exceeds/);
+  assert.equal(await fs.readFile(path.join(cwd, 'hello.txt'), 'utf8'), 'hello');
+});