janissary 0.5.0

package/dist/recognizers/analyze.js

@@ -0,0 +1,49 @@
+import { bashRecognizer } from './bash.js';
+import { dbRecognizer as databaseRecognizer } from './db.js';
+import { acpRecognizer } from './acp.js';
+export const recognizers = [bashRecognizer, databaseRecognizer, acpRecognizer];
+// A command is auto-dispatched only when the best match is at least this reliable and clearly
+// ahead of the runner-up; otherwise the user is asked to choose.
+export const HIGH_RELIABILITY = 0.7;
+const DOMINANCE_MARGIN = 0.15;
+// Poll every recognizer and decide how to route the command. The highest-reliability match wins
+// when it is confident enough; otherwise the result is ambiguous and the caller should prompt.
+export function analyzeCommand(command, context) {
+    const matches = recognizers
+        .map((r) => ({ route: r.route, ...r.recognize(command, context) }))
+        .filter((r) => r.match)
+        .map(({ route, reliability }) => ({ route, reliability }))
+        .toSorted((a, b) => b.reliability - a.reliability);
+    const top = matches[0];
+    const runnerUp = matches[1];
+    const isConfident = top !== undefined &&
+        top.reliability >= HIGH_RELIABILITY &&
+        (runnerUp === undefined || top.reliability - runnerUp.reliability >= DOMINANCE_MARGIN);
+    if (isConfident)
+        return { kind: 'route', route: top.route, reliability: top.reliability };
+    return { kind: 'ambiguous', candidates: matches };
+}
+// The routes a user may pick from in the chooser. Always offers shell and acp; offers a db
+// choice per open connection (the query needs a concrete database to target).
+export function routeChoices(openDbs) {
+    const choices = [{ label: 'shell', route: 'shell' }];
+    for (const database of openDbs)
+        choices.push({ label: `db query → ${database}`, route: 'db', dbName: database });
+    choices.push({ label: 'acp (agent prompt)', route: 'acp' });
+    return choices;
+}
+// Rewrite a bare command into the explicit, prefixed form for `choice`'s route, so it can be
+// dispatched through the normal command pipeline.
+export function toPrefixedCommand(command, choice) {
+    switch (choice.route) {
+        case 'shell': {
+            return `shell ${command}`;
+        }
+        case 'acp': {
+            return `acp ${command}`;
+        }
+        case 'db': {
+            return `db sqlite query ${choice.dbName} ${command}`;
+        }
+    }
+}

package/dist/recognizers/bash.js

@@ -0,0 +1,51 @@
+import { FUNCTION_WORDS } from './lexicon.js';
+// Common executables/builtins that strongly signal a shell command when they lead the line.
+const COMMON_COMMANDS = new Set([
+    'ls', 'cd', 'pwd', 'cat', 'echo', 'printf', 'grep', 'egrep', 'fgrep', 'rg', 'find', 'head',
+    'tail', 'less', 'more', 'touch', 'rm', 'rmdir', 'cp', 'mv', 'mkdir', 'chmod', 'chown', 'ln',
+    'ps', 'kill', 'top', 'htop', 'df', 'du', 'tar', 'gzip', 'gunzip', 'zip', 'unzip', 'curl',
+    'wget', 'ssh', 'scp', 'rsync', 'git', 'npm', 'npx', 'node', 'yarn', 'pnpm', 'deno', 'bun',
+    'python', 'python3', 'pip', 'pip3', 'ruby', 'gem', 'go', 'cargo', 'rustc', 'make', 'cmake',
+    'sed', 'awk', 'sort', 'uniq', 'wc', 'cut', 'tr', 'xargs', 'tee', 'date', 'whoami', 'which',
+    'env', 'export', 'unset', 'source', 'sleep', 'history', 'man', 'ping', 'brew', 'apt', 'yum',
+    'docker', 'kubectl', 'code', 'vim', 'nano', 'emacs', 'open', 'say', 'jq', 'sqlite3', 'psql',
+    'mysql', 'test', 'true', 'false', 'set', 'alias', 'jobs', 'bg', 'fg', 'nohup', 'time',
+]);
+// Commands that are also everyday English words, so a sentence can plausibly start with one
+// ("find the largest file", "which file is longest"). For these, a prose-looking line is treated
+// as a natural-language prompt rather than a shell invocation.
+const AMBIGUOUS_COMMANDS = new Set([
+    'which', 'find', 'make', 'test', 'set', 'time', 'date', 'open', 'say', 'help', 'sort', 'do',
+    'who', 'head', 'tail', 'last', 'touch', 'kill', 'cut', 'less', 'more', 'top', 'tee',
+]);
+// Shell metacharacters: pipes, redirects, chaining, command substitution, env refs. A bare `*`
+// is deliberately excluded — it is weak evidence of a shell command and collides with SQL (`SELECT *`).
+const SHELL_OPERATORS = /[|&;<>`]|\$\(|\$\{|\$[A-Za-z_]/;
+const PATH_LIKE = /^(\.{1,2}\/|\/|~\/)/;
+const FLAG = /^-{1,2}[A-Za-z]/;
+// Recognize a shell/bash command. Leading with a known command is the strongest signal; shell
+// operators or an explicit executable path also count. A command word doubling as English
+// ("which", "find", …) at the head of a prose sentence is discounted so it routes to the agent.
+export const bashRecognizer = {
+    route: 'shell',
+    recognize: (command) => {
+        const trimmed = command.trim();
+        const tokens = trimmed.split(/\s+/);
+        const first = (tokens[0] ?? '').toLowerCase();
+        const proseWords = tokens.slice(1).filter((t) => FUNCTION_WORDS.has(t.toLowerCase())).length;
+        const isLooksProse = tokens.length >= 3 && proseWords >= 1;
+        let score = 0;
+        if (COMMON_COMMANDS.has(first)) {
+            score = AMBIGUOUS_COMMANDS.has(first) && isLooksProse ? 0.25 : 0.9;
+        }
+        else if (PATH_LIKE.test(first)) {
+            score = 0.85;
+        }
+        if (SHELL_OPERATORS.test(trimmed))
+            score = Math.max(score, 0.6) + 0.1;
+        if (tokens.length > 1 && FLAG.test(tokens[1]))
+            score += 0.05;
+        score = Math.min(score, 0.98);
+        return { match: score >= 0.5, reliability: score };
+    },
+};

package/dist/recognizers/db.js

@@ -0,0 +1,26 @@
+// Statement keywords that, when they lead the line, mark a SQL query.
+const SQL_START = new Set([
+    'SELECT', 'INSERT', 'UPDATE', 'DELETE', 'CREATE', 'DROP', 'ALTER', 'WITH', 'PRAGMA',
+    'EXPLAIN', 'VACUUM', 'ATTACH', 'DETACH', 'REPLACE', 'BEGIN', 'COMMIT', 'ROLLBACK', 'TRUNCATE',
+]);
+// Secondary keywords that reinforce a SQL match when present anywhere in the statement.
+const SQL_KEYWORDS = ['FROM', 'WHERE', 'JOIN', 'INTO', 'VALUES', 'SET', 'TABLE', 'GROUP BY', 'ORDER BY', 'LIMIT'];
+// Recognize a SQL/db query. Gated on the tab having an open database connection — without one
+// there is nothing to run the query against, so the route is not offered (per design).
+export const dbRecognizer = {
+    route: 'db',
+    recognize: (command, context) => {
+        if (context.openDbs.length === 0)
+            return { match: false, reliability: 0 };
+        const trimmed = command.trim();
+        const first = /^([A-Za-z]+)\b/.exec(trimmed)?.[1]?.toUpperCase();
+        let score = 0;
+        score = first && SQL_START.has(first) ? 0.8 : score;
+        const hits = SQL_KEYWORDS.filter((k) => new RegExp(String.raw `\b${k.replace(' ', String.raw `\s+`)}\b`, 'i').test(trimmed)).length;
+        score += Math.min(0.18, hits * 0.09);
+        if (/;\s*$/.test(trimmed))
+            score += 0.05;
+        score = Math.min(score, 0.98);
+        return { match: score >= 0.5, reliability: score };
+    },
+};

package/dist/recognizers/index.js

@@ -0,0 +1 @@
+export { analyzeCommand, routeChoices, toPrefixedCommand } from './analyze.js';

package/dist/recognizers/lexicon.js

@@ -0,0 +1,11 @@
+// Grammatical "function words" (articles, copulas, auxiliaries, pronouns, prepositions,
+// conjunctions, interrogatives). They pepper natural-language sentences but rarely appear,
+// unquoted, in a shell invocation. Recognizers use their presence to tell a prose request
+// ("find the largest file") apart from a command ("find . -name x").
+export const FUNCTION_WORDS = new Set([
+    'a', 'an', 'the', 'is', 'are', 'was', 'were', 'am', 'be', 'been', 'being', 'of', 'to', 'for',
+    'and', 'or', 'but', 'that', 'this', 'these', 'those', 'with', 'from', 'into', 'my', 'your',
+    'his', 'her', 'their', 'our', 'it', 'its', 'you', 'he', 'she', 'they', 'we', 'do', 'does',
+    'did', 'should', 'would', 'could', 'can', 'will', 'than', 'then', 'what', 'why', 'how', 'who',
+    'whom', 'whose', 'when', 'where', 'which',
+]);

package/dist/recognizers/types.js

@@ -0,0 +1,5 @@
+// A command typed without a prefix may still be a shell command, a SQL/db query, or an agent
+// (acp) prompt. Each route has a "command recognizer" that reads the raw command and reports
+// whether it looks like that route and how reliable the guess is. The analysis module
+// (`analyze.ts`) polls every recognizer and routes by the most reliable match.
+export {};

package/dist/resolve.js

@@ -0,0 +1,39 @@
+import { getOutput } from './commands.js';
+import { commands } from './commands/index.js';
+/**
+ * Classify a prompt input into the action it represents, mirroring the dispatch order
+ * used when a command is typed into a tab. Pure: callers decide the side effects (a
+ * foreground tab can run interactive/app commands; a remote agent refuses them).
+ *
+ * - `shell`: run in a shell. Explicitly requested via a leading `shell ` keyword — there
+ *   is no bare auto-run, so a non-built-in typed without the keyword is unknown.
+ * - `app`: an application built-in that needs live state.
+ * - `output`: a built-in with textual output to display (also the "unknown command" reply).
+ * - `empty`: nothing to do.
+ */
+export function resolveCommand(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return { kind: 'empty' };
+    // Shell commands are launched with the `shell` keyword, which is stripped before the
+    // command reaches the shell.
+    if (/^shell\b/i.test(trimmed)) {
+        return { kind: 'shell', cmd: trimmed.replace(/^shell\b\s*/i, '') };
+    }
+    const command = trimmed.replace(/^\//, '');
+    for (const c of commands) {
+        if (c.match(command)) {
+            return { kind: 'app', name: c.name, cmd: command };
+        }
+    }
+    const output = getOutput(command);
+    if (output !== null) {
+        // `getOutput` returns the "Unknown command: ..." message for anything unrecognized; surface
+        // that as `unknown` so the interactive dispatcher can run command recognition on it.
+        const kind = output.startsWith('Unknown command:') ? 'unknown' : 'output';
+        return { kind, cmd: command, output };
+    }
+    // Shell commands require the `shell` keyword (handled above); a bare non-built-in is
+    // reported as unknown rather than auto-run in the shell.
+    return { kind: 'empty' };
+}

package/dist/route-choice.js

@@ -0,0 +1,11 @@
+import { analyzeCommand } from './recognizers/index.js';
+// Whether `input` resolves to a route (and if so, which one). A bare 'db' target auto-resolves
+// when exactly one db is open — the caller only needs to prompt when there's a real ambiguity.
+export function resolveRouteChoice(input, openDbs) {
+    const decision = analyzeCommand(input, { openDbs });
+    if (decision.kind !== 'route' || (decision.route === 'db' && openDbs.length !== 1))
+        return undefined;
+    return decision.route === 'db'
+        ? { label: '', route: 'db', dbName: openDbs[0] }
+        : { label: '', route: decision.route };
+}

package/dist/sandbox/index.js

@@ -0,0 +1,217 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { SANDBOX_PROFILE, SANDBOX_PROFILE_OFFLINE } from './profile.js';
+import { HOME_WRITE_CARVEOUTS, HOME_READ_CARVEINS, SECRET_DENY_PATHS, HOME_READ_LISTING_DIRS, HOME_WRITE_PREFIX_CARVEOUTS, WRITE_CARVEOUT_PARAMS, READ_CARVEIN_PARAMS, SECRET_DENY_PARAMS, LISTING_DIR_PARAMS, WRITE_PREFIX_PARAMS, ENV_SCRUB_PATTERNS, } from './paths.js';
+import { getConfig } from '../config.js';
+let cachedAvailable;
+// Whether Seatbelt sandboxing can be applied on this machine: darwin, with `sandbox-exec` on
+// `PATH`. Cached after the first check.
+export function sandboxAvailable() {
+    cachedAvailable ??= process.platform === 'darwin' && existsSync('/usr/bin/sandbox-exec');
+    return cachedAvailable;
+}
+// A one-line notice to append to a newly created workspaced tab's transcript when its processes
+// will NOT actually be confined — either the config toggle is off, or `sandbox-exec` isn't
+// available on this machine. Undefined when sandboxing is active, so callers only surface it when
+// there's something to say.
+export function sandboxNotice() {
+    if (!getConfig().sandboxWorkspaces)
+        return 'workspace isolation off: sandboxWorkspaces disabled in config';
+    if (!sandboxAvailable())
+        return 'workspace isolation off: sandbox-exec unavailable';
+    return undefined;
+}
+// Resolve a path through any symlinks (macOS's `/tmp` → `/private/tmp` being the common case) —
+// Seatbelt's `subpath` rules match against the resolved path, so an unresolved path silently
+// fails to carve in. Falls back to the input path if it doesn't exist (yet).
+function resolvePath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+let cachedDarwinUserCacheDir;
+// The real per-user `/var/folders/<xx>/<hash>/C/` cache directory macOS's `confstr(3)` hands out —
+// NOT the same as `$TMPDIR`, which `sandboxSpawn` overrides to a workspace-local path below, and
+// NOT its `.../T/` (temp) sibling, which stays denied (that's where `os.tmpdir()`-based scratch
+// dirs land — carving it in too would let a sandboxed process write anywhere a plain `mktemp`
+// call resolves to, defeating the outside-the-workspace write deny). System frameworks look the
+// cache path up directly via `confstr`, bypassing our `TMPDIR` override entirely, and write
+// lock/cache files into it regardless (e.g. Security.framework's legacy MDS subsystem locks
+// `.../C/mds/mds.lock` on every `SecItemCopyMatching` call — denied, the call silently fails
+// rather than erroring, so a sandboxed harness reads back "not logged in" even with a valid
+// Keychain item). Cached: it's fixed for the life of the host process.
+function darwinUserCacheDir() {
+    if (cachedDarwinUserCacheDir)
+        return cachedDarwinUserCacheDir;
+    try {
+        const cacheDir = execFileSync('getconf', ['DARWIN_USER_CACHE_DIR']).toString().trim();
+        cachedDarwinUserCacheDir = resolvePath(cacheDir);
+    }
+    catch {
+        cachedDarwinUserCacheDir = '/nonexistent-janissary-darwin-user-cache-dir-placeholder';
+    }
+    return cachedDarwinUserCacheDir;
+}
+let cachedClaudeScratchDir;
+// The harness CLI's own per-user scratch tree, `/private/tmp/claude-<uid>/`, under which it creates
+// a per-project/session scratchpad directory before running any tool — including a plain shell
+// command. This is a fixed, UID-keyed path entirely outside `$HOME`, our workspace-local `TMPDIR`
+// override, and the Darwin user cache dir above, so without carving it in, every tool invocation
+// inside a sandboxed harness session fails at that housekeeping step, before the tool's own command
+// ever runs. Cached: the UID is fixed for the life of the host process.
+function claudeScratchDir() {
+    if (cachedClaudeScratchDir)
+        return cachedClaudeScratchDir;
+    const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+    cachedClaudeScratchDir = resolvePath(`/private/tmp/claude-${uid}`);
+    return cachedClaudeScratchDir;
+}
+// Walk up from a resolved executable's path to the nearest ancestor directory literally named
+// `node_modules`, if any. A globally-installed npm package (`npm` itself included) is laid out as
+// `.../node_modules/<pkg>/bin/<script>`, where the script requires sibling files from `<pkg>/lib/`
+// and beyond — carving in only the immediate `bin/` directory (as for a single bundled binary like
+// claude.exe) leaves those sibling requires denied. Carving in the whole `node_modules/` directory
+// instead covers every globally-installed package uniformly (not just the one being run), which is
+// harmless — it's still just $HOME-scoped code, not secrets. Falls back to the script's own
+// directory when there's no `node_modules` ancestor (a single-file bundled binary).
+function packageRootDir(resolvedBin) {
+    let dir = path.dirname(resolvedBin);
+    for (;;) {
+        if (path.basename(dir) === 'node_modules')
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return path.dirname(resolvedBin);
+        dir = parent;
+    }
+}
+// Resolve `command` to an absolute path the way `execvp`/`posix_spawn` would (a `PATH` search for a
+// bare name, or the path itself if it already contains a separator) so its containing directory can
+// be carved into the read allow-list. Without this, a harness binary installed under `$HOME` (e.g.
+// via nvm, or `~/.opencode/bin`) can't read its own executable — which some system frameworks need
+// to do internally (Keychain's `SecItemCopyMatching` calls `CFBundleGetMainBundle`, which reopens the
+// calling process's own binary and its directory to determine code identity for ACL matching; denied,
+// the harness looks logged out even though its Keychain item is intact). Returns both the literal
+// (unresolved — e.g. many npm-global installs are a `bin/foo` symlink into `lib/node_modules/...`)
+// and fully realpath-resolved directory (widened to the enclosing `node_modules/` via
+// `packageRootDir` above, for packages — like npm — that are more than a single bundled file), same
+// dual reasoning as `dualParams` in sandbox-profile.ts: a framework may `opendir`/`lstat` the
+// symlink's own directory as well as the resolved target's. Falls back to a path that matches
+// nothing so the profile's params always have a bound value.
+function resolveExecutableDirs(command) {
+    const fallback = '/nonexistent-janissary-self-bin-placeholder';
+    const literalBin = command.includes('/')
+        ? (existsSync(command) ? command : undefined)
+        : (process.env.PATH ?? '').split(':').filter(Boolean)
+            .map((dir) => path.join(dir, command))
+            .find((candidate) => existsSync(candidate));
+    if (!literalBin)
+        return { literal: fallback, real: fallback };
+    return { literal: path.dirname(literalBin), real: packageRootDir(resolvePath(literalBin)) };
+}
+// The directory of the Node binary currently running the janissary server itself
+// (`process.execPath`), in both literal and realpath-resolved form (same dual reasoning as
+// `resolveExecutableDirs` above — an nvm-managed `node` is commonly a symlink). Carved into the
+// read allow-list so a script running inside the sandbox (e.g. a project's own `.claude/settings.json`
+// hook) can reliably invoke a known-good `node` via the `JANISSARY_NODE` env var below, instead of
+// hoping a bare `node` on the sandboxed process's PATH resolves to a working binary — PATH
+// resolution order inside a spawned/hook context doesn't always match the server's own.
+function serverNodeDirs() {
+    const execPath = process.execPath;
+    return { literal: path.dirname(execPath), real: path.dirname(resolvePath(execPath)) };
+}
+// The workspace clone's own git objects directory. Falls back to a parent repo's real objects
+// directory via a `--shared` alternates file, if one is present (older, locally-shared clones) —
+// today's independent clones of `origin` have no alternates file, so this always hits the fallback.
+function parentGitObjectsDir(workspaceDir) {
+    const fallback = path.join(workspaceDir, '.git', 'objects');
+    try {
+        const alternatesPath = path.join(workspaceDir, '.git', 'objects', 'info', 'alternates');
+        const target = readFileSync(alternatesPath, 'utf8').trim().split('\n', 1)[0];
+        return target ? resolvePath(target) : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+// Drop credential-shaped vars and agent-socket escape vectors (see `sandbox-profile.ts`).
+function scrubEnv(env) {
+    const scrubbed = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (ENV_SCRUB_PATTERNS.some((pattern) => pattern.test(key)))
+            continue;
+        scrubbed[key] = value;
+    }
+    return scrubbed;
+}
+// `-D <param>=<path>` for each home-relative table entry, in both its literal (`~/…`, as named —
+// covers an `lstat`/`readlink` of a symlinked dotfile) and fully realpath-resolved (covers a
+// `read`/`open` that follows the symlink) forms. See the comment on `dualParams` in
+// sandbox-profile.ts for why both are needed.
+function homeDParams(home, relPaths, params) {
+    const args = [];
+    for (const [i, rel] of relPaths.entries()) {
+        const literalPath = path.join(home, rel);
+        args.push('-D', `${params.literal[i]}=${literalPath}`, '-D', `${params.real[i]}=${resolvePath(literalPath)}`);
+    }
+    return args;
+}
+// Wrap a spawn invocation (`command` + `args` — the same shape `child_process.spawn`/node-pty's
+// `spawn` take) for a workspaced tab. Returns the input unchanged when there's nothing to
+// sandbox: no `workspaceDir`, the `sandboxWorkspaces` config toggle is off, or `sandbox-exec`
+// isn't available (e.g. non-darwin). Otherwise returns `sandbox-exec -p <profile> -D … -- <command>
+// <args>` plus a credential-scrubbed environment with `TMPDIR` set to the workspace's private
+// temp dir.
+export function sandboxSpawn(options, command, args, env = process.env) {
+    if (!options.workspaceDir || !getConfig().sandboxWorkspaces || !sandboxAvailable()) {
+        return { command, args, env };
+    }
+    const workspaceDir = resolvePath(options.workspaceDir);
+    const tmpDir = resolvePath(`${options.workspaceDir}.tmp`);
+    const home = resolvePath(homedir());
+    const gitObjects = parentGitObjectsDir(options.workspaceDir);
+    const selfDirs = resolveExecutableDirs(options.selfBinaryHint ?? command);
+    const darwinCacheDir = darwinUserCacheDir();
+    const scratchDir = claudeScratchDir();
+    const serverNodeDir = serverNodeDirs();
+    const scrubbed = scrubEnv(env);
+    scrubbed.TMPDIR = tmpDir;
+    scrubbed.JANISSARY_NODE = process.execPath;
+    if (options.githubToken) {
+        scrubbed.GH_TOKEN = options.githubToken;
+        // `gh` reads `~/.config/gh/hosts.yml` on every invocation regardless of `GH_TOKEN`, and its
+        // config loader treats the sandbox's EPERM deny on that file (see SECRET_DENY_PATHS in
+        // sandbox-profile.ts) as fatal, refusing to run at all. Pointing `GH_CONFIG_DIR` at an empty,
+        // workspace-private directory instead gives `gh` a genuinely absent hosts.yml (real ENOENT),
+        // which it handles by falling through to `GH_TOKEN` normally.
+        scrubbed.GH_CONFIG_DIR = path.join(tmpDir, 'gh-config');
+    }
+    const profile = options.offline ? SANDBOX_PROFILE_OFFLINE : SANDBOX_PROFILE;
+    const dParams = [
+        '-D', `WORKSPACE=${workspaceDir}`,
+        '-D', `TMPDIR=${tmpDir}`,
+        '-D', `HOME=${home}`,
+        '-D', `GIT_OBJECTS=${gitObjects}`,
+        '-D', `SELF_DIR_L=${selfDirs.literal}`,
+        '-D', `SELF_DIR_R=${selfDirs.real}`,
+        '-D', `DARWIN_USER_CACHE_DIR=${darwinCacheDir}`,
+        '-D', `CLAUDE_SCRATCH_DIR=${scratchDir}`,
+        '-D', `SERVER_NODE_DIR_L=${serverNodeDir.literal}`,
+        '-D', `SERVER_NODE_DIR_R=${serverNodeDir.real}`,
+        ...homeDParams(home, HOME_WRITE_CARVEOUTS, WRITE_CARVEOUT_PARAMS),
+        ...homeDParams(home, HOME_READ_CARVEINS, READ_CARVEIN_PARAMS),
+        ...homeDParams(home, SECRET_DENY_PATHS, SECRET_DENY_PARAMS),
+        ...homeDParams(home, HOME_READ_LISTING_DIRS, LISTING_DIR_PARAMS),
+        ...homeDParams(home, HOME_WRITE_PREFIX_CARVEOUTS, WRITE_PREFIX_PARAMS),
+    ];
+    return {
+        command: 'sandbox-exec',
+        args: ['-p', profile, ...dParams, '--', command, ...args],
+        env: scrubbed,
+    };
+}

package/dist/sandbox/paths.js

@@ -0,0 +1,178 @@
+// Table-driven path/env lists the Seatbelt profile in sandbox-profile.ts is built from.
+// Extending any restriction is a one-line table change here.
+// Narrow write carve-outs: harness auth/state directories and package-manager cache subpaths —
+// never the whole `~/.claude`, `~/.cache`, or `~/.npm` (broad cache write access would let a
+// sandboxed agent poison packages/plugins that other, non-sandboxed processes later consume).
+// The `.claude/` entries are the session-state paths a sandboxed `claude` writes while running:
+// transcripts, session env, task/todo/job state, shell snapshots, edit history, debug logs,
+// plans, paste cache, and its stats/statsig telemetry caches. Deliberately absent: `.claude/plugins`
+// (write access would let a sandboxed agent replace plugin code the unsandboxed CLI later runs —
+// reads are carved in below), `daemon`/`ide`/`backups`, and the auto-updater's state files.
+export const HOME_WRITE_CARVEOUTS = [
+    '.claude/projects',
+    '.claude/session-env',
+    '.claude/sessions',
+    '.claude/tasks',
+    '.claude/todos',
+    '.claude/jobs',
+    '.claude/shell-snapshots',
+    '.claude/file-history',
+    '.claude/history.jsonl',
+    '.claude/debug',
+    '.claude/plans',
+    '.claude/paste-cache',
+    '.claude/cache',
+    '.claude/statsig',
+    '.claude/stats-cache.json',
+    '.claude/mcp-needs-auth-cache.json',
+    '.claude.json',
+    '.codex',
+    '.config/opencode',
+    '.local/share/opencode',
+    '.local/state/opencode',
+    '.npm/_cacache',
+    '.npm/_logs',
+    '.npm/_npx',
+    '.cache/pip',
+    '.cache/yarn',
+];
+// Read carve-ins: the write carve-outs (a harness needs to read its own state), plus read-only
+// extras — `.claude/settings.json` and the customization dirs a sandboxed `claude` loads on
+// startup but must not modify (`plugins`, `skills`, `agents`, `commands`, `keybindings.json`),
+// `.gitconfig` and `.gitexcludes` (the latter is whatever `core.excludesfile`
+// in the former points to; every git invocation reads both), `.config/gh/config.yml` (`gh`'s
+// general settings — git_protocol, editor, prompt — as opposed to `hosts.yml`, which can hold a
+// plaintext OAuth token and stays denied via `SECRET_DENY_PATHS`; a workspaced `gh` authenticates
+// via the injected `GH_TOKEN` env var instead, see `github-token.ts`), `Library/Keychains` (see
+// the comment on `SECRET_DENY_PATHS` — read access is needed for any Keychain lookup to work at all
+// on this OS, including harness login), `.nvm` (nvm's own `nvm.sh`/`bash_completion` loader
+// scripts plus every installed Node version's binaries and libs under `versions/` — broader than
+// SERVER_NODE_DIR_L/R in sandbox.ts, which only carves in the one version the janissary server
+// itself runs on; a sandboxed process that sources `nvm.sh` or shells out to a bare `node`/`npm`/
+// `npx`, or to a harness installed under a different nvm-managed version, needs to read the whole
+// tree. Execute access for these binaries doesn't need a separate carve-in — `process-exec` is
+// allowed everywhere except `/tmp`/`/private/tmp`, so this read carve-in is the only gap), `.rvm`
+// (same reasoning as `.nvm`, for Ruby: `rvm`'s own loader script plus every installed Ruby
+// version's binaries and gems under `rubies/`/`gems/`), and `.bash_profile`/`.bashrc` (a
+// login/interactive bash shell sources these on startup; without the carve-in, spawning
+// `bash -lc` inside the sandbox fails that read silently and the shell starts with none of the
+// user's aliases/functions/PATH additions).
+export const HOME_READ_CARVEINS = [
+    ...HOME_WRITE_CARVEOUTS,
+    '.claude/settings.json', '.claude/plugins', '.claude/skills', '.claude/agents', '.claude/commands', '.claude/keybindings.json',
+    '.gitconfig', '.gitexcludes', '.config/gh/config.yml', 'Library/Keychains', '.nvm', '.rvm',
+    '.bash_profile', '.bashrc',
+];
+// Directories where `opendir`/`readdir` must work even though most of their *contents* aren't
+// separately carved in. `.claude` itself: a settings read-modify-write (e.g. `claude --effort`, or
+// any tool following this project's own "read raw settings before writing" convention) opens the
+// directory node itself to enumerate settings files before touching `settings.json` — a plain
+// `subpath` carve-in of the file alone only covers `open()`ing that one path, not the parent
+// directory's `file-read-data` (Seatbelt's listing operation, distinct from the `file-read-metadata`
+// stat access already allowed HOME-wide — see the deny-then-carve-in comment in sandbox-profile.ts).
+// These use `literal`, not `subpath`: the directory node itself becomes listable, but files inside
+// it stay gated by the specific carve-ins in HOME_READ_CARVEINS above (or stay denied).
+export const HOME_READ_LISTING_DIRS = ['.claude'];
+// Write carve-outs matched by Seatbelt `prefix` (string prefix on the full path) rather than
+// `subpath` (path-component match) or `literal` (exact match). `.claude/settings.json` itself is
+// deliberately absent from HOME_WRITE_CARVEOUTS above — but a settings read-modify-write (e.g.
+// `claude --effort`) writes it via an atomic-rename pattern: create a sibling temp file
+// (`settings.json.tmp.<pid>.<random>`, a fresh, unpredictable name every write), fsync it, then
+// rename it over the target. `subpath`/`literal` can't carve in a name that doesn't exist yet and
+// varies per write; `prefix` matches both the base filename and every `<base>.tmp.*` sibling
+// because the base string is a literal character-prefix of each. Narrower than carving in the
+// whole `.claude` directory for writes (still deliberately avoided, per the comment on
+// HOME_WRITE_CARVEOUTS above) — this only ever matches paths starting with the exact
+// `settings.json` string.
+//
+// `Library/Keychains/login.keychain-db` is here for the same atomic-write reason, and is the fix
+// for a specific failure mode: OAuth-based harness auth (e.g. Claude Code) reads its credential
+// from the login Keychain fine — reads are carved in via HOME_READ_CARVEINS — but when the access
+// token expires mid-session, persisting the *refreshed* token back is a Keychain write, which hit
+// the top-level deny-default and silently failed, so the stale expired token kept being sent and
+// the provider returned 401 invalid-credentials. The write lands as an atomic-rename temp sibling
+// `login.keychain-db.sb-<random>` (confirmed in the Sandbox deny log: `file-write-create
+// .../login.keychain-db.sb-151e5e06-tFbiQ8`), so a `subpath`/`literal` carve-in of the base name
+// can't cover it — `prefix` does, and also naturally covers the DB's SQLite sidecars
+// (`login.keychain-db-wal`/`-shm`/`-journal`), all of which share the base as a character-prefix.
+// Deliberately the login keychain DB only, not the whole `~/Library/Keychains` subtree: the DB
+// stays encrypted and per-item ACL-enforced by securityd regardless of raw file writability (same
+// argument the read carve-in rests on — see SECRET_DENY_PATHS), and the narrow prefix keeps a
+// sandboxed process from tampering with unrelated keychain files. If a data-protection keychain
+// (`<UUID>/keychain-2.db`) is ever in play, its own write deny will surface separately in the log.
+export const HOME_WRITE_PREFIX_CARVEOUTS = ['.claude/settings.json', 'Library/Keychains/login.keychain-db'];
+// Secret paths denied last, even inside a carve-in.
+//
+// `Library/Keychains` is deliberately NOT here: reads are carved in (HOME_READ_CARVEINS) and one
+// narrow write is carved in (HOME_WRITE_PREFIX_CARVEOUTS covers `login.keychain-db` and its
+// atomic-write/SQLite siblings, so a harness can persist a refreshed OAuth token — see that
+// comment); every other write under the subtree stays denied by the top-level deny-default. Even
+// "modern" Keychain Services calls (SecItemCopyMatching) fall through to
+// a legacy CDSA/MDS implementation on this OS that reads the keychain DB file directly rather than
+// only talking to securityd over IPC; denying that read blocks every keychain lookup a sandboxed
+// harness makes, including its own OAuth credential, and it shows up as "not logged in" rather
+// than a permission error. The DB stays encrypted and per-item ACL-enforced by securityd regardless
+// of raw file readability, so this doesn't hand out plaintext secrets — it's a materially larger
+// read surface than the other entries here, but the alternative breaks harness login outright.
+//
+// `.config/gh/hosts.yml`'s deny below now reads as ENOENT too (see the errno qualifier on the
+// final deny rule in buildProfile), which is exactly what `gh` needs — but `sandbox.ts` still
+// separately points `GH_CONFIG_DIR` at an empty, workspace-writable directory whenever a scoped
+// token is injected, so `gh` finds a real, uncomplicated absent `hosts.yml` there rather than
+// depending on this deny rule's errno behavior. Kept as defense in depth: `gh`'s Go config loader
+// treats any read error there as fatal, so relying on a single mechanism to keep that read from
+// ever mattering felt worth avoiding.
+export const SECRET_DENY_PATHS = [
+    // On installs without Keychain access (Linux, some containers) this file holds the harness
+    // OAuth token in plaintext. Already outside every carve-in above, but denied explicitly so a
+    // future widening of the `.claude/` entries can't silently expose it.
+    '.claude/.credentials.json',
+    '.ssh', '.aws', '.gnupg', '.kube', '.netrc', '.config/gh/hosts.yml', '.docker',
+    '.config/gcloud', '.azure', '.cargo/credentials', '.cargo/credentials.toml',
+    '.pypirc', '.m2/settings.xml', '.terraform.d',
+    '.bash_history', '.zsh_history', '.python_history', '.node_repl_history',
+    'Library/Application Support/Google/Chrome',
+    'Library/Application Support/Firefox',
+    'Library/Application Support/BraveSoftware',
+    'Library/Safari',
+];
+// Env vars scrubbed from a workspaced process's environment: credential-shaped vars and
+// agent-socket / credential-helper escape vectors that bypass the file-read denies above (e.g.
+// `SSH_AUTH_SOCK` lets a process use the user's SSH keys without ever reading `~/.ssh`). LLM
+// provider keys (`ANTHROPIC_*`, `OPENAI_*`, `GEMINI_*`/`GOOGLE_*`) are deliberately NOT matched —
+// the harnesses and the ACP agent need their own credentials to function.
+export const ENV_SCRUB_PATTERNS = [
+    /^AWS_/, /^GITHUB_TOKEN$/, /^GH_TOKEN$/, /^NPM_TOKEN$/, /^DOCKER_/, /^KUBECONFIG$/,
+    /_SECRET$/, /_PASSWORD$/,
+    /^SSH_AUTH_SOCK$/, /^GPG_AGENT_INFO$/, /^GNUPGHOME$/,
+    /^GIT_ASKPASS$/, /^GIT_CREDENTIAL_HELPER$/, /^KRB5CCNAME$/,
+];
+function paramName(prefix, index) {
+    return `${prefix}${index}`;
+}
+// Two `-D` param names per table entry, in the same order — `sandbox.ts` pairs these with the
+// literal (`~/…`, unresolved beyond `$HOME` itself) and fully realpath-resolved forms of the same
+// path. Both are needed: many dotfiles (`.gitconfig`, `.npmrc`, …) are themselves symlinks (e.g.
+// managed by a dotfile manager), and Seatbelt evaluates an `lstat`/`readlink` of the symlink node
+// against its literal path but a `read`/`open` that follows it against the resolved target —
+// carving in only one leaves the other operation denied.
+export function dualParams(prefix, count) {
+    return {
+        literal: Array.from({ length: count }, (_, i) => paramName(`${prefix}L`, i)),
+        real: Array.from({ length: count }, (_, i) => paramName(`${prefix}R`, i)),
+    };
+}
+export const WRITE_CARVEOUT_PARAMS = dualParams('W', HOME_WRITE_CARVEOUTS.length);
+export const READ_CARVEIN_PARAMS = dualParams('R', HOME_READ_CARVEINS.length);
+export const SECRET_DENY_PARAMS = dualParams('S', SECRET_DENY_PATHS.length);
+export const LISTING_DIR_PARAMS = dualParams('D', HOME_READ_LISTING_DIRS.length);
+export const WRITE_PREFIX_PARAMS = dualParams('P', HOME_WRITE_PREFIX_CARVEOUTS.length);
+export const clausesFor = (params) => [...params.literal, ...params.real].map((p) => `  (subpath (param "${p}"))`).join('\n');
+// Same shape as `clausesFor`, but matches only the exact path (Seatbelt `literal`) — used for
+// HOME_READ_LISTING_DIRS, where a directory node must be listable without granting recursive
+// access to everything under it (that's what `subpath` would do).
+export const literalClausesFor = (params) => [...params.literal, ...params.real].map((p) => `  (literal (param "${p}"))`).join('\n');
+// Same shape again, but Seatbelt `prefix` (string-prefix match) — used for
+// HOME_WRITE_PREFIX_CARVEOUTS, where the writable path's exact name isn't known ahead of time
+// (a randomly-named atomic-write temp sibling of a fixed base filename).
+export const prefixClausesFor = (params) => [...params.literal, ...params.real].map((p) => `  (prefix (param "${p}"))`).join('\n');