subrouter-cli 0.0.0-stage → 0.1.0

package/src/usage.ts

@@ -0,0 +1,186 @@
+// usage.ts — GET /usage fetch + render. Strict parsing: missing values are 'unknown',
+// never zero; null limits render as 'unlimited'. Advisory only — a failure must never
+// block chat. 30s cache.
+
+import { errorMessage, type RouterClient } from './client.ts';
+
+const CACHE_MS = 30_000;
+let cache: { data: unknown; at: number } | null = null;
+
+export async function fetchUsage(client: RouterClient, signal?: AbortSignal, refresh = false): Promise<unknown> {
+  signal?.throwIfAborted();
+  if (!refresh && cache && Date.now() - cache.at < CACHE_MS) return cache.data;
+  const data = await client.usage(signal);
+  cache = { data, at: Date.now() };
+  return data;
+}
+
+/** 20-char block bar scaled to a percent; 'unknown' for non-numbers. */
+export function bar(percent: unknown): string {
+  if (typeof percent !== 'number' || !Number.isFinite(percent)) return 'unknown';
+  const filled = Math.round(Math.min(Math.max(percent, 0), 100) / 5);
+  return '█'.repeat(filled) + '░'.repeat(20 - filled);
+}
+
+function num(value: unknown): string {
+  return typeof value === 'number' && Number.isFinite(value) ? value.toLocaleString() : 'unknown';
+}
+
+function isoDate(value: unknown): string {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    const date = new Date(value * 1000);
+    return Number.isFinite(date.getTime()) ? date.toISOString().slice(0, 16) : 'unknown';
+  }
+  if (typeof value === 'string') return value.slice(0, 16);
+  return 'unknown';
+}
+
+/**
+ * Strict render of the live shape (verified): `user` holds quota limits/usage
+ * (daily_token_limit may be null = unlimited), `pools` hold provider/window bars.
+ * Tolerates any other shape by reporting 'unknown' rather than guessing.
+ */
+export function renderUsage(json: unknown): string[] {
+  const lines: string[] = [];
+  if (typeof json !== 'object' || json === null) return ['usage: unrecognized response'];
+  const root = json as Record<string, unknown>;
+
+  const rawUser = root.user ?? root.quotas; // the docs' shape is `quotas`; live is `user`
+  const user = (typeof rawUser === 'object' && rawUser !== null ? rawUser : {}) as Record<string, unknown>;
+
+  const parts: string[] = [`${num(user.rpm_limit)} rpm`];
+  if (typeof user.today_tokens === 'number' || user.daily_token_limit !== undefined) {
+    const limit = user.daily_token_limit === null ? 'unlimited' : num(user.daily_token_limit);
+    parts.push(`${num(user.today_tokens)} tokens today / ${limit}`);
+  }
+  parts.push(`$${num(user.weekly_usd_limit)}/week`);
+  if (typeof user.week_usd === 'number') parts.push(`$${num(user.week_usd)} used`);
+  if (typeof user.resets_at === 'string') parts.push(`resets ${isoDate(user.resets_at)}`);
+  lines.push('quota: ' + parts.join(' · '));
+
+  const pools = root.pools;
+  if (Array.isArray(pools) && pools.length > 0) {
+    lines.push('pools:');
+    for (const p of pools as Record<string, unknown>[]) {
+      if (typeof p !== 'object' || p === null) continue;
+      const name = [p.provider ?? p.name ?? 'pool', p.window].filter((b) => typeof b === 'string').join(' ');
+      const used = p.used_percent;
+      const pct = typeof used === 'number' && Number.isFinite(used) ? `${Math.round(used)}%` : 'unknown';
+      lines.push(`  ${name} ${bar(used)} ${pct} · resets ${isoDate(p.resets_at)}`);
+    }
+  }
+  return lines;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function providerName(value: string): string {
+  const name = value.trim().toLowerCase();
+  return name === 'xai' ? 'grok' : name;
+}
+
+function modelProvider(model: string): string {
+  const id = model.trim().toLowerCase();
+  // The router prefix wins, even for e.g. opencode/deepseek or openai/claude.
+  if (id.includes('/')) return providerName(id.split('/')[0]);
+  if (/^claude[-.]/.test(id)) return 'anthropic';
+  if (/^gpt[-.]/.test(id)) return 'openai';
+  if (/^grok[-.]/.test(id)) return 'grok';
+  if (/^deepseek[-.]/.test(id)) return 'deepseek';
+  return '';
+}
+
+/**
+ * Pure, one-line chat footer for the selected model's provider. All matching
+ * pool percentages are grouped first; reset metadata stays in full /usage.
+ * No other provider's pools or model-name guesses are used for prefixed ids.
+ * xai and grok are aliases. If no pool matches, show the
+ * account's daily token quota / rpm instead. Missing or invalid stats are
+ * unknown (not zero); only an explicit null daily limit means unlimited.
+ */
+export function providerUsage(json: unknown, model: string): string {
+  const root = record(json);
+  if (!root) return 'usage: unknown';
+
+  const provider = modelProvider(model);
+  const pools = Array.isArray(root.pools) ? root.pools : [];
+  const summaries: string[] = [];
+  for (const rawPool of pools) {
+    const pool = record(rawPool);
+    if (!pool || !provider) continue;
+    const name = pool.provider ?? pool.name;
+    if (typeof name !== 'string' || providerName(name) !== provider) continue;
+    const used = pool.used_percent;
+    const available = typeof used === 'number' && Number.isFinite(used) && used >= 0 && used <= 100
+      ? `${Math.round(100 - used)}%`
+      : 'unknown';
+    const window = typeof pool.window === 'string' ? pool.window.trim().replace(/\s+/g, ' ') : '';
+    summaries.push(`${window ? window + ' ' : ''}${available}`);
+  }
+  if (summaries.length) return `${provider}: ${summaries.join(' · ')} available`;
+
+  const user = record(root.user ?? root.quotas);
+  if (!user) return 'usage: unknown';
+  const parts: string[] = [];
+  if (user.today_tokens !== undefined || user.daily_token_limit !== undefined) {
+    const limit = user.daily_token_limit === null ? 'unlimited' : num(user.daily_token_limit);
+    parts.push(`${num(user.today_tokens)} / ${limit} tokens today`);
+  }
+  if (user.rpm_limit !== undefined) parts.push(`${num(user.rpm_limit)} rpm`);
+  return parts.length ? `quota: ${parts.join(' · ')}` : 'usage: unknown';
+}
+
+function compact(value: number): string {
+  if (value >= 1_000_000_000) return `${+(value / 1_000_000_000).toFixed(1)}B`;
+  if (value >= 1_000_000) return `${+(value / 1_000_000).toFixed(1)}M`;
+  if (value >= 1000) return `${+(value / 1000).toFixed(1)}K`;
+  return value.toLocaleString(undefined, { maximumFractionDigits: 2 });
+}
+
+/** These caps are shared account quotas, not invented provider subscription limits. */
+export function usageLimits(json: unknown): string {
+  const root = record(json);
+  const user = record(root?.user ?? root?.quotas);
+  if (!user) return 'account limits: unknown';
+  const amount = (value: unknown): string =>
+    typeof value === 'number' && Number.isFinite(value) && value >= 0 ? compact(value) : '?';
+  const limit = (value: unknown): string => value === null ? 'unlimited' : amount(value);
+  const parts: string[] = [];
+  if (user.rpm_limit !== undefined) parts.push(`${limit(user.rpm_limit)} rpm`);
+  if (user.today_tokens !== undefined || user.daily_token_limit !== undefined)
+    parts.push(`day ${amount(user.today_tokens)}/${limit(user.daily_token_limit)} tokens`);
+  if (user.week_usd !== undefined || user.weekly_usd_limit !== undefined)
+    parts.push(`week $${amount(user.week_usd)}/${user.weekly_usd_limit === null ? 'unlimited' : '$' + amount(user.weekly_usd_limit)}`);
+  return parts.length ? `account: ${parts.join(' · ')}` : 'account limits: unknown';
+}
+
+/** The detailed command panel follows the active provider just like the footer. */
+export function modelUsage(json: unknown, model: string): string[] {
+  const root = record(json);
+  const provider = modelProvider(model);
+  const pools = Array.isArray(root?.pools) ? root.pools.filter((raw) => {
+    const pool = record(raw);
+    const name = pool?.provider ?? pool?.name;
+    return typeof name === 'string' && providerName(name) === provider;
+  }) : [];
+  const lines = ['Usage'];
+  if (pools.length) {
+    for (const raw of pools) {
+      const pool = record(raw)!;
+      const reset = isoDate(pool.resets_at);
+      lines.push(`${providerUsage({ pools: [pool] }, model)} · resets ${reset === 'unknown' ? reset : reset.slice(5).replace('T', ' ')}`);
+    }
+  } else lines.push('No provider pool limits reported by the router.');
+  lines.push('', 'Account limits');
+  const limits = usageLimits(json);
+  lines.push(...(limits.startsWith('account: ') ? limits.slice(9).split(' · ') : ['unknown']));
+  return lines;
+}
+
+export function usageError(err: unknown): string {
+  return errorMessage(err);
+}

package/test/absolute-tools.test.ts

@@ -0,0 +1,296 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import net from 'node:net';
+import { afterEach, beforeEach, test } from 'node:test';
+import { confined, executeTool, prepareCommand, MAX_READ_BYTES, MAX_WRITE_BYTES, MAX_TREE_BYTES, MAX_TREE_ENTRIES, RECOVERY_DIR } from '../src/tools.ts';
+import type { ToolExecutionOptions, ToolResult } from '../src/tools.ts';
+import type { ToolCall } from '../src/types.ts';
+
+let base: string, cwd: string, outside: string, home: string;
+let originalHome: string | undefined;
+const absolute: ToolExecutionOptions = { absoluteAccess: true, absoluteEnabled: () => true };
+beforeEach(async () => {
+  base = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'sub-absolute-tools-')));
+  cwd = path.join(base, 'project');
+  outside = path.join(base, 'outside');
+  home = path.join(base, 'home');
+  await Promise.all([cwd, outside, home].map((dir) => fs.mkdir(dir)));
+  originalHome = process.env.HOME;
+  process.env.HOME = home;
+});
+afterEach(async () => {
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+  await fs.rm(base, { recursive: true, force: true });
+});
+function call(name: string, args: Record<string, unknown>): ToolCall {
+  return { id: name, name, arguments: args, argumentsJson: JSON.stringify(args) };
+}
+async function good(name: string, args: Record<string, unknown>, options = absolute): Promise<ToolResult> {
+  const result = await executeTool(call(name, args), cwd, options);
+  assert.equal(result.isError, undefined, result.content);
+  return result;
+}
+async function bad(name: string, args: Record<string, unknown>, options: ToolExecutionOptions = {}): Promise<ToolResult> {
+  const result = await executeTool(call(name, args), cwd, options);
+  assert.equal(result.isError, true, result.content);
+  return result;
+}
+
+test('drive-wide file results and errors redact the known router credential', async () => {
+  const secret = 'synthetic-router-credential';
+  await fs.writeFile(path.join(outside, 'data'), `data ${secret}`);
+  const options = { ...absolute, redactValues: [secret] };
+  const read = await good('read_file', { path: path.join(outside, 'data') }, options);
+  assert.equal(read.content, 'data [REDACTED]');
+  const batch = await good('read_files', { paths: [path.join(outside, 'data')] }, options);
+  assert.ok(!batch.content.includes(secret));
+  const error = await bad('read_file', { path: path.join(outside, secret) }, options);
+  assert.ok(!error.content.includes(secret));
+});
+
+test('absolute host capability covers external reads, home paths, siblings and symlink reads for every read tool', async () => {
+  await fs.writeFile(path.join(outside, 'note.txt'), 'external needle');
+  await fs.writeFile(path.join(home, 'home.txt'), 'synthetic home');
+  await fs.symlink(outside, path.join(cwd, 'escape'));
+  for (const raw of [path.join(outside, 'note.txt'), '../outside/note.txt', 'escape/note.txt']) {
+    assert.equal((await good('read_file', { path: raw })).content, 'external needle');
+    await bad('read_file', { path: raw });
+    await assert.rejects(() => confined(cwd, raw));
+  }
+  await good('write_file', { path: 'escape/created.txt', content: 'symlink parent write' });
+  await good('edit_file', { path: 'escape/created.txt', old_string: 'write', new_string: 'edit' });
+  assert.equal(await fs.readFile(path.join(outside, 'created.txt'), 'utf8'), 'symlink parent edit');
+  await bad('write_file', { path: 'escape/created.txt', content: 'normal cannot follow' });
+  assert.equal((await good('read_file', { path: '~/home.txt' })).content, 'synthetic home');
+  await bad('read_file', { path: '~/home.txt' });
+  assert.match((await good('list_dir', { path: outside })).content, /note.txt/);
+  assert.match((await good('grep', { path: outside, pattern: 'needle' })).content, /note.txt:1:external needle/);
+  assert.match((await good('find_files', { path: outside })).content, /note.txt/);
+  assert.equal(JSON.parse((await good('file_info', { path: outside })).content).type, 'directory');
+  const batch = JSON.parse((await good('read_files', { paths: [path.join(outside, 'note.txt'), '~/home.txt'] })).content);
+  assert.deepEqual(batch.map((item: { content: string }) => item.content), ['external needle', 'synthetic home']);
+  for (const name of ['list_dir', 'grep', 'find_files', 'file_info']) await bad(name, { path: outside, pattern: 'needle' });
+  assert.match((await good('read_files', { paths: [path.join(outside, 'note.txt')] }, {})).content, /error/);
+});
+
+test('absolute mutations support external paths and retain recovery paths; normal restore cannot escape', async () => {
+  await good('make_dir', { path: '../outside/nested' });
+  const original = path.join(outside, 'nested/original.txt');
+  await good('write_file', { path: original, content: 'old text' });
+  await good('edit_file', { path: original, old_string: 'old', new_string: 'new' });
+  assert.equal(await fs.readFile(original, 'utf8'), 'new text');
+  await good('copy_path', { source: '../outside/nested', destination: '~/copied' });
+  await good('move_path', { source: '~/copied', destination: path.join(outside, 'moved') });
+  const moved = path.join(outside, 'moved');
+  const removed = JSON.parse((await good('remove_path', { path: moved })).content);
+  assert.equal(removed.removed, '../outside/moved');
+  await assert.rejects(fs.stat(moved));
+  const listed = JSON.parse((await good('list_removed', {}, {})).content).items;
+  assert.equal(listed[0].path, '../outside/moved');
+  const record = JSON.parse(await fs.readFile(path.join(cwd, RECOVERY_DIR, removed.recovery_id, 'record.json'), 'utf8'));
+  assert.equal(record.path, '../outside/moved');
+  await bad('restore_file', { recovery_id: removed.recovery_id });
+  await bad('restore_file', { recovery_id: removed.recovery_id, destination: moved });
+  await good('restore_file', { recovery_id: removed.recovery_id });
+  assert.equal(await fs.readFile(path.join(moved, 'original.txt'), 'utf8'), 'new text');
+  await good('write_file', { path: '~/new-home.txt', content: 'home write' });
+  assert.equal(await fs.readFile(path.join(home, 'new-home.txt'), 'utf8'), 'home write');
+  for (const name of ['write_file', 'edit_file', 'make_dir', 'remove_path']) {
+    await bad(name, { path: original, content: 'no', old_string: 'new', new_string: 'no' });
+  }
+  for (const name of ['copy_path', 'move_path']) await bad(name, { source: original, destination: 'inside' });
+});
+
+test('absolute access bypasses project, .git and recovery name guards while normal mutations keep them', async () => {
+  await good('make_dir', { path: '.' });
+  await bad('make_dir', { path: '.' });
+  await good('write_file', { path: '.git/config', content: 'synthetic git' });
+  await good('write_file', { path: `tree/.git/config`, content: 'tree git' });
+  await good('write_file', { path: `tree/${RECOVERY_DIR}/note`, content: 'tree recovery' });
+  await bad('write_file', { path: '.git/config', content: 'no' });
+  await bad('copy_path', { source: 'tree', destination: 'normal-copy' });
+  await good('copy_path', { source: 'tree', destination: path.join(outside, 'tree-copy') });
+  await good('move_path', { source: path.join(outside, 'tree-copy'), destination: path.join(outside, 'tree-moved') });
+  const removed = JSON.parse((await good('remove_path', { path: path.join(outside, 'tree-moved') })).content);
+  await good('restore_file', { recovery_id: removed.recovery_id });
+  assert.equal(await fs.readFile(path.join(outside, 'tree-moved/.git/config'), 'utf8'), 'tree git');
+  assert.equal((await good('read_file', { path: path.join(outside, `tree-moved/${RECOVERY_DIR}/note`) })).content, 'tree recovery');
+  await bad('read_file', { path: `${RECOVERY_DIR}/note` });
+});
+
+test('absolute capability keeps nofollow regular writes, tree symlink guards, collisions and byte caps', async () => {
+  const file = path.join(outside, 'file');
+  await fs.writeFile(file, 'unchanged');
+  const link = path.join(outside, 'link');
+  await fs.symlink(file, link);
+  await bad('write_file', { path: link, content: 'changed' }, absolute);
+  await bad('edit_file', { path: link, old_string: 'unchanged', new_string: 'changed' }, absolute);
+  assert.equal(await fs.readFile(file, 'utf8'), 'unchanged');
+  await bad('write_file', { path: outside, content: 'no' }, absolute);
+  for (const name of ['copy_path', 'move_path', 'remove_path']) {
+    await bad(name, { path: link, source: link, destination: path.join(outside, `${name}-dest`) }, absolute);
+  }
+  await fs.mkdir(path.join(outside, 'linked-tree'));
+  await fs.symlink(file, path.join(outside, 'linked-tree/link'));
+  await bad('copy_path', { source: path.join(outside, 'linked-tree'), destination: 'copied' }, absolute);
+  await bad('copy_path', { source: file, destination: file }, absolute);
+  await bad('copy_path', { source: file, destination: link }, absolute);
+  await bad('write_file', { path: file, content: 'x'.repeat(MAX_WRITE_BYTES + 1) }, absolute);
+  const huge = path.join(outside, 'huge');
+  const handle = await fs.open(huge, 'w');
+  await handle.truncate(MAX_TREE_BYTES + 1);
+  await handle.close();
+  await bad('read_file', { path: huge }, absolute);
+  await bad('copy_path', { source: huge, destination: 'huge-copy' }, absolute);
+  await bad('move_path', { source: huge, destination: 'huge-move' }, absolute);
+  await bad('remove_path', { path: huge }, absolute);
+  await fs.writeFile(path.join(outside, 'large-text'), 'x'.repeat(MAX_READ_BYTES + 1));
+  await bad('read_file', { path: path.join(outside, 'large-text') }, absolute);
+  for (const raw of ['', '\0', null]) await bad('read_file', { path: raw }, absolute);
+});
+
+test('absolute access still rejects special files for text and tree operations', async () => {
+  // A socket is a synthetic special file; never inspect device paths on the drive.
+  const socket = path.join(base, 's');
+  const server = net.createServer();
+  await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(socket, resolve); });
+  try {
+    await bad('read_file', { path: socket }, absolute);
+    await bad('write_file', { path: socket, content: 'no' }, absolute);
+    for (const name of ['copy_path', 'move_path', 'remove_path']) {
+      await bad(name, { path: socket, source: socket, destination: path.join(outside, `${name}-special`) }, absolute);
+    }
+  } finally {
+    await new Promise<void>((resolve, reject) => server.close((err) => err ? reject(err) : resolve()));
+  }
+});
+
+test('absolute directory tree entry cap remains enforced', async () => {
+  const tree = path.join(outside, 'many');
+  await fs.mkdir(tree);
+  for (let i = 0; i < MAX_TREE_ENTRIES; i += 100) {
+    await Promise.all(Array.from({ length: Math.min(100, MAX_TREE_ENTRIES - i) }, (_, j) => fs.writeFile(path.join(tree, String(i + j)), '')));
+  }
+  const result = await bad('copy_path', { source: tree, destination: 'too-many' }, absolute);
+  assert.match(result.content, /entries/);
+  await assert.rejects(fs.stat(path.join(cwd, 'too-many')));
+});
+
+test('only host options grant absolute access and a live callback is mandatory', async () => {
+  const raw = path.join(outside, 'file');
+  await fs.writeFile(raw, 'outside');
+  await bad('read_file', { path: raw, absoluteAccess: true, absoluteEnabled: true });
+  for (const options of [{ absoluteAccess: true }, { absoluteAccess: true, absoluteEnabled: () => false }]) {
+    const result = await bad('read_file', { path: raw }, options);
+    assert.match(result.content, /absolute authorization revoked/);
+    await bad('write_file', { path: path.join(outside, 'marker'), content: 'no' }, options);
+  }
+  await assert.rejects(fs.stat(path.join(outside, 'marker')));
+  const request = call('run_command', { command: 'printf harmless' });
+  const approval = { ...await prepareCommand(cwd, request.arguments), kind: 'absolute' as const };
+  for (const absoluteEnabled of [undefined, () => false]) {
+    let started = false;
+    const result = await executeTool(request, cwd, { commandApproval: approval, absoluteEnabled, onStart: () => { started = true; } });
+    assert.equal(result.isError, true);
+    assert.equal(started, false);
+  }
+});
+
+test('parallel absolute and normal calls remain isolated, including normal execution nested in an absolute context', async () => {
+  await fs.writeFile(path.join(outside, 'file'), 'outside');
+  const results = await Promise.all(Array.from({ length: 30 }, (_, i) => executeTool(call('read_file', { path: '../outside/file' }), cwd, i % 2 ? {} : absolute)));
+  results.forEach((result, i) => assert.equal(result.isError, i % 2 ? true : undefined));
+  let nested!: Promise<ToolResult>, nestedPreparation!: Promise<void>;
+  const request = call('run_command', { command: 'printf isolated', cwd: outside });
+  const approval = { ...await prepareCommand(cwd, request.arguments, [], true), kind: 'absolute' as const };
+  await good('run_command', request.arguments, {
+    ...absolute, commandApproval: approval,
+    onStart: () => {
+      nested = executeTool(call('read_file', { path: '../outside/file' }), cwd);
+      nestedPreparation = assert.rejects(() => prepareCommand(cwd, { command: 'pwd', cwd: outside }));
+    },
+  });
+  assert.equal((await nested).isError, true);
+  await nestedPreparation;
+  await bad('read_file', { path: '../outside/file' });
+});
+
+test('absolute command preparation is opt-in, uses exact external cwd and retains credential validation', async () => {
+  await fs.symlink(outside, path.join(cwd, 'escape'));
+  for (const directory of [outside, '../outside', 'escape', '~']) {
+    await assert.rejects(() => prepareCommand(cwd, { command: 'pwd', cwd: directory }));
+    const prepared = await prepareCommand(cwd, { command: 'pwd', cwd: directory }, [], true);
+    assert.equal(prepared.cwd, await fs.realpath(directory === '~' ? home : outside));
+  }
+  for (const directory of [null, 'missing', '\0']) await assert.rejects(() => prepareCommand(cwd, { command: 'pwd', cwd: directory }, [], true));
+  await fs.writeFile(path.join(outside, 'file'), 'x');
+  await assert.rejects(() => prepareCommand(cwd, { command: 'pwd', cwd: path.join(outside, 'file') }, [], true));
+  await assert.rejects(() => prepareCommand(cwd, { command: 'echo synthetic-secret', cwd: outside }, ['synthetic-secret'], true), /credential|secret|protected/);
+  await assert.rejects(() => prepareCommand(cwd, { command: 'pwd', cwd: path.join(outside, 'synthetic-secret') }, ['synthetic-secret'], true), /credential/);
+  const args = { command: 'pwd', cwd: outside, timeout_ms: 1000 };
+  const approval = { ...await prepareCommand(cwd, args, [], true), kind: 'absolute' as const };
+  const result = await good('run_command', args, { ...absolute, commandApproval: approval });
+  assert.equal(JSON.parse(result.content).stdout.trim(), approval.cwd);
+  await bad('run_command', { command: 'printf harmless', cwd: outside }, absolute);
+});
+
+test('absolute commands recheck live authorization immediately before spawning', async () => {
+  const args = { command: 'printf harmless', cwd: outside };
+  const approval = { ...await prepareCommand(cwd, args, [], true), kind: 'absolute' as const };
+  let checks = 0, started = false;
+  const result = await bad('run_command', args, {
+    absoluteAccess: true, commandApproval: approval,
+    absoluteEnabled: () => ++checks === 1,
+    onStart: () => { started = true; },
+  });
+  assert.match(result.content, /absolute authorization revoked/);
+  assert.equal(checks, 2);
+  assert.equal(started, false);
+});
+
+test('absolute command snapshots reject changed command, cwd, timeout and symlink resolution', async () => {
+  const args = { command: 'printf harmless', cwd: outside, timeout_ms: 1000 };
+  const approval = { ...await prepareCommand(cwd, args, [], true), kind: 'absolute' as const };
+  for (const changed of [{ command: 'printf changed' }, { cwd: home }, { timeout_ms: 1001 }]) {
+    let started = false;
+    const result = await bad('run_command', { ...args, ...changed }, { ...absolute, commandApproval: approval, onStart: () => { started = true; } });
+    assert.match(result.content, /changed after approval/);
+    assert.equal(started, false);
+  }
+  const link = path.join(cwd, 'link');
+  await fs.symlink(outside, link);
+  const linked = { command: 'printf harmless', cwd: 'link' };
+  const linkedApproval = { ...await prepareCommand(cwd, linked, [], true), kind: 'absolute' as const };
+  await fs.unlink(link);
+  await fs.symlink(home, link);
+  const result = await bad('run_command', linked, { ...absolute, commandApproval: linkedApproval });
+  assert.match(result.content, /changed after approval/);
+});
+
+test('revoked queued absolute commands and file mutations never start and do not poison the queue', async () => {
+  const first = call('run_command', { command: 'sleep 0.2; printf done', timeout_ms: 1000 });
+  let started!: () => void;
+  const ready = new Promise<void>((resolve) => { started = resolve; });
+  const blocker = executeTool(first, cwd, { commandApproval: await prepareCommand(cwd, first.arguments), onStart: started });
+  await ready;
+  let enabled = true, commandStarted = false;
+  const args = { command: 'printf harmless', cwd: outside };
+  const approval = { ...await prepareCommand(cwd, args, [], true), kind: 'absolute' as const };
+  const options = { absoluteAccess: true, absoluteEnabled: () => enabled };
+  const queuedCommand = executeTool(call('run_command', args), cwd, { ...options, commandApproval: approval, onStart: () => { commandStarted = true; } });
+  const queuedWrite = executeTool(call('write_file', { path: path.join(outside, 'marker'), content: 'no' }), cwd, options);
+  const queuedDirectory = executeTool(call('make_dir', { path: path.join(outside, 'new-directory') }), cwd, options);
+  enabled = false;
+  assert.equal((await blocker).isError, undefined);
+  for (const result of await Promise.all([queuedCommand, queuedWrite, queuedDirectory])) {
+    assert.equal(result.isError, true);
+    assert.match(result.content, /absolute authorization revoked/);
+  }
+  assert.equal(commandStarted, false);
+  await assert.rejects(fs.stat(path.join(outside, 'marker')));
+  await assert.rejects(fs.stat(path.join(outside, 'new-directory')));
+  await good('write_file', { path: 'after-revoke', content: 'normal queue works' }, {});
+});

package/test/absolute-ui.test.ts

@@ -0,0 +1,153 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { test, type TestContext } from 'node:test';
+
+function exercise(t: TestContext, script: string, cli = false): void {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'sub-absolute-ui-'));
+  t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+  fs.mkdirSync(path.join(home, 'project'));
+  fs.mkdirSync(path.join(home, 'outside'));
+  fs.writeFileSync(path.join(home, 'outside/data'), 'external data');
+  fs.mkdirSync(path.join(home, '.config/subrouter-cli'), { recursive: true });
+  fs.writeFileSync(path.join(home, '.config/subrouter-cli/config.json'), '{"auto_approve":true}');
+  const child = spawnSync(process.execPath, ['--input-type=module', '-e', String.raw`
+    import assert from 'node:assert/strict';
+    import fs from 'node:fs';
+    import path from 'node:path';
+    Object.defineProperty(process.stdin, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'rows', { value: 24 });
+    Object.defineProperty(process.stdout, 'columns', { value: 100 });
+    process.stdin.setRawMode = () => {};
+    process.chdir(path.join(process.env.HOME, 'project'));
+    const { ui } = await import(${JSON.stringify(new URL('../src/ui.ts', import.meta.url).href)});
+    const { LineInput } = await import(${JSON.stringify(new URL('../src/lineinput.ts', import.meta.url).href)});
+    const prompts = [], modes = [], requests = [], chat = [], cards = [], submitted = [];
+    let status = '';
+    const setStatus = ui.setStatus.bind(ui), setMode = ui.setMode.bind(ui), say = ui.say.bind(ui), startTool = ui.startTool.bind(ui), submitInput = ui.submitInput.bind(ui);
+    ui.setStatus = (value) => { status = value; setStatus(value); };
+    ui.setMode = (value) => { modes.push(value); setMode(value); };
+    ui.say = (line) => { chat.push(line); say(line); };
+    ui.startTool = (name, preview) => { cards.push(preview); startTool(name, preview); };
+    ui.submitInput = (prompt, text) => { submitted.push(text); submitInput(prompt, text); };
+    const question = LineInput.prototype.question;
+    LineInput.prototype.question = function(prompt, echoAnswer) { prompts.push(prompt); return question.call(this, prompt, echoAnswer); };
+    let releasePending;
+    const pending = new Promise((resolve) => { releasePending = resolve; });
+    const client = {
+      listModels: async () => [{ id: 'openai/test' }], usage: async () => ({}),
+      chat: async (req) => {
+        requests.push(structuredClone(req));
+        if (req.messages.at(-1).role === 'tool') return { message: { role: 'assistant', content: 'Done.' }, stopReason: 'stop' };
+        const user = req.messages.at(-1).content;
+        if (user === 'pending') await pending;
+        const name = user === 'outside' ? 'read_file' : user === 'file' ? 'write_file' : 'run_command';
+        const args = user === 'outside' ? { path: path.join(process.env.HOME, 'outside/data') }
+          : user === 'file' ? { path: path.join(process.env.HOME, 'outside/new-file'), content: 'hello' }
+          : user === 'pending' ? { command: 'printf noop' }
+          : { command: 'printf harmless > marker', cwd: path.join(process.env.HOME, 'outside') };
+        return { message: { role: 'assistant', content: '', toolCalls: [{ id: 'c' + requests.length, name, arguments: args, argumentsJson: JSON.stringify(args) }] }, stopReason: 'tool_calls' };
+      },
+    };
+    if (${cli}) {
+      const { RouterClient } = await import(${JSON.stringify(new URL('../src/client.ts', import.meta.url).href)});
+      RouterClient.prototype.listModels = client.listModels;
+      RouterClient.prototype.usage = client.usage;
+      RouterClient.prototype.chat = client.chat;
+      process.argv = [process.execPath, 'sub', '--model', 'openai/test', '--absolute'];
+      await import(${JSON.stringify(new URL('../src/index.ts', import.meta.url).href)});
+    } else {
+      const { startRepl } = await import(${JSON.stringify(new URL('../src/repl.ts', import.meta.url).href)});
+      startRepl({ client, model: 'openai/test', config: { apiKey: 'synthetic-key', maxToolRounds: 25, maxOutputTokens: 8192, autoApprove: true } });
+    }
+    const key = (text) => process.stdin.emit('data', Buffer.from(text));
+    const until = async (predicate) => {
+      const deadline = Date.now() + 5000;
+      while (!predicate() && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 5));
+      assert.ok(predicate()); await new Promise(setImmediate);
+    };
+    ${script}
+  `], { cwd: new URL('..', import.meta.url), encoding: 'utf8', timeout: 15000, env: { ...process.env, HOME: home, SUBROUTER_API_KEY: 'synthetic-key', NO_COLOR: '1' } });
+  assert.equal(child.status, 0, child.stderr || String(child.error));
+  assert.ok(!child.stdout.includes('synthetic-key'));
+  assert.equal(fs.readFileSync(path.join(home, '.config/subrouter-cli/config.json'), 'utf8'), '{"auto_approve":true}');
+}
+
+test('absolute warning rejects blank/all/cancellation; picker acknowledgement enables drive access without prompts', (t) => {
+  exercise(t, String.raw`
+    for (const answer of ['\r', 'a\r', '\x03', '\x1b']) {
+      const count = prompts.length;
+      key('/mode absolute\r'); await until(() => prompts.length === count + 1);
+      key(answer); await until(() => status === 'ready');
+      assert.equal(modes.at(-1), 'files allowed · commands ask');
+    }
+    key('/mode\r'); await until(() => status === 'choose permission mode');
+    key('\x1b[B\x1b[B\r'); await until(() => prompts.length === 5);
+    assert.equal(modes.at(-1), 'files allowed · commands ask');
+    assert.ok(chat.some((line) => line.includes('ENTIRE DRIVE, NO APPROVALS')));
+    assert.ok(chat.some((line) => line.includes('permanently delete')));
+    key('ABSOLUTE\r'); await until(() => status === 'ready');
+    assert.equal(modes.at(-1), 'ABSOLUTE — NO APPROVALS');
+    key('outside\r'); await until(() => requests.length === 2 && status === 'ready');
+    assert.match(requests[1].messages.at(-1).content, /external data/);
+    key('file\r'); await until(() => requests.length === 4 && status === 'ready');
+    assert.equal(fs.readFileSync(path.join(process.env.HOME, 'outside/new-file'), 'utf8'), 'hello');
+    key('command\r'); await until(() => requests.length === 6 && status === 'ready');
+    assert.equal(prompts.length, 5);
+    assert.equal(fs.readFileSync(path.join(process.env.HOME, 'outside/marker'), 'utf8'), 'harmless');
+    assert.ok(cards.some((card) => card?.title === 'Terminal command · ABSOLUTE'));
+    assert.ok(!requests.some((request) => request.messages.some((message) => message.role === 'user' && message.content === 'ABSOLUTE')));
+    assert.ok(!submitted.includes('ABSOLUTE'));
+    key('/mode ask\r'); await until(() => status === 'ready');
+    key('outside\r'); await until(() => requests.length === 8 && status === 'ready');
+    assert.equal(requests[7].messages.at(-1).isError, true);
+    key('/exit\r');
+  `);
+});
+
+test('CLI absolute starts in ask mode until typed acknowledgement, never from file config', (t) => {
+  exercise(t, String.raw`
+    await until(() => prompts.length === 1);
+    assert.equal(modes.at(-1), 'ask before writes');
+    key('ABSOLUTE\r'); await until(() => status === 'ready');
+    assert.equal(modes.at(-1), 'ABSOLUTE — NO APPROVALS');
+    key('command\r'); await until(() => requests.length === 2 && status === 'ready');
+    assert.equal(prompts.length, 1);
+    assert.equal(JSON.parse(requests[1].messages.at(-1).content).status, 'completed');
+    key('/exit\r');
+  `, true);
+});
+
+test('agent approvals preempt an absolute warning without enabling it or mixing answers', (t) => {
+  exercise(t, String.raw`
+    key('pending\r'); await until(() => requests.length === 1);
+    key('/mode absolute\r'); await until(() => prompts.length === 1);
+    releasePending(); await until(() => prompts.length === 2);
+    assert.equal(modes.at(-1), 'files allowed · commands ask');
+    assert.ok(prompts[1].includes('Allow command [y/n]'));
+    key('n\r'); await until(() => requests.length === 2 && status === 'ready');
+    assert.match(requests[1].messages.at(-1).content, /denied/);
+    assert.ok(!modes.includes('ABSOLUTE — NO APPROVALS'));
+    key('/exit\r');
+  `);
+});
+
+test('EOF cannot enable startup absolute mode', (t) => {
+  exercise(t, String.raw`
+    await until(() => prompts.length === 1);
+    key('\x04');
+    await new Promise(setImmediate);
+    assert.ok(!modes.includes('ABSOLUTE — NO APPROVALS'));
+  `, true);
+});
+
+test('absolute CLI rejects conflicting flags and noninteractive/one-shot activation', () => {
+  for (const flags of [['--absolute', '--auto'], ['--auto-approve', '--absolute'], ['--absolute'], ['--absolute', '-p', 'test'], ['--absolute', '--check']]) {
+    const child = spawnSync(process.execPath, ['src/index.ts', ...flags], { cwd: new URL('..', import.meta.url), encoding: 'utf8', timeout: 5000 });
+    assert.equal(child.status, 2);
+    assert.match(child.stderr, /Choose --absolute|requires an interactive REPL/);
+  }
+});