@qduc/term2 0.7.3 → 0.9.0

package/dist/utils/shell/execute-shell.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-shell.test.d.ts","sourceRoot":"","sources":["../../../source/utils/shell/execute-shell.test.ts"],"names":[],"mappings":""}

package/dist/utils/shell/execute-shell.test.js

@@ -0,0 +1,89 @@
+import { it, expect } from 'vitest';
+import { PassThrough, Writable } from 'stream';
+import { executeShellCommand } from './execute-shell.js';
+it('executeShellCommand returns stdout and exit code for successful command', async () => {
+    const result = await executeShellCommand("printf 'hello'", {
+        execImpl: (_command, _options, callback) => {
+            queueMicrotask(() => callback(null, 'hello', ''));
+            return createFakeChildProcess();
+        },
+    });
+    expect(result.stdout).toBe('hello');
+    expect(result.stderr).toBe('');
+    expect(result.exitCode).toBe(0);
+    expect(result.timedOut).toBe(false);
+});
+it('executeShellCommand captures stderr and exit code for failed command', async () => {
+    const result = await executeShellCommand('fails', {
+        execImpl: (_command, _options, callback) => {
+            const error = new Error('failed');
+            error.code = 2;
+            queueMicrotask(() => callback(error, '', 'oops\n'));
+            return createFakeChildProcess();
+        },
+    });
+    expect(result.stderr.trim()).toBe('oops');
+    expect(result.exitCode).toBe(2);
+    expect(result.timedOut).toBe(false);
+});
+it('executeShellCommand reports timeouts', async () => {
+    const result = await executeShellCommand('long-running', {
+        timeout: 50,
+        execImpl: (_command, _options, callback) => {
+            const error = new Error('timeout');
+            error.signal = 'SIGTERM';
+            queueMicrotask(() => callback(error, '', ''));
+            return createFakeChildProcess();
+        },
+    });
+    expect(result.timedOut).toBe(true);
+});
+it('executeShellCommand closes child stdin immediately', async () => {
+    let stdinEnded = false;
+    const result = await executeShellCommand('waits-for-stdin', {
+        execImpl: (_command, _options, callback) => {
+            const child = createFakeChildProcess();
+            child.stdin = new Writable({
+                write(_chunk, _encoding, next) {
+                    next();
+                },
+                final(next) {
+                    stdinEnded = true;
+                    queueMicrotask(() => callback(null, '', ''));
+                    next();
+                },
+            });
+            return child;
+        },
+    });
+    expect(stdinEnded).toBe(true);
+    expect(result.exitCode).toBe(0);
+});
+it('executeShellCommand stops the child process when execution is aborted', async () => {
+    const abortController = new AbortController();
+    let killCalls = 0;
+    const resultPromise = executeShellCommand('long-running', {
+        signal: abortController.signal,
+        execImpl: (_command, _options, callback) => {
+            const child = createFakeChildProcess();
+            child.kill = () => {
+                killCalls += 1;
+                const error = new Error('aborted');
+                error.signal = 'SIGTERM';
+                queueMicrotask(() => callback(error, '', ''));
+                return true;
+            };
+            return child;
+        },
+    });
+    abortController.abort();
+    const result = await resultPromise;
+    expect(killCalls).toBe(1);
+    expect(result.timedOut).toBe(true);
+});
+function createFakeChildProcess() {
+    return {
+        stdin: new PassThrough(),
+    };
+}
+//# sourceMappingURL=execute-shell.test.js.map

package/dist/utils/shell/execute-shell.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-shell.test.js","sourceRoot":"","sources":["../../../source/utils/shell/execute-shell.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,EAAE,CAAC,yEAAyE,EAAE,KAAK,IAAI,EAAE;IACvF,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,gBAAgB,EAAE;QACzD,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE;YACzC,cAAc,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;YAClD,OAAO,sBAAsB,EAAE,CAAC;QAClC,CAAC;KACF,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/B,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC,CAAC,CAAC;AAEH,EAAE,CAAC,sEAAsE,EAAE,KAAK,IAAI,EAAE;IACpF,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,OAAO,EAAE;QAChD,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE;YACzC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,QAAQ,CAA6C,CAAC;YAC9E,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;YACf,cAAc,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;YACpD,OAAO,sBAAsB,EAAE,CAAC;QAClC,CAAC;KACF,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtC,CAAC,CAAC,CAAC;AAEH,EAAE,CAAC,sCAAsC,EAAE,KAAK,IAAI,EAAE;IACpD,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,cAAc,EAAE;QACvD,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE;YACzC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,SAAS,CAA+B,CAAC;YACjE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;YACzB,cAAc,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAC9C,OAAO,sBAAsB,EAAE,CAAC;QAClC,CAAC;KACF,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC,CAAC,CAAC;AAEH,EAAE,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;IAClE,IAAI,UAAU,GAAG,KAAK,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,iBAAiB,EAAE;QAC1D,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE;YACzC,MAAM,KAAK,GAAG,sBAAsB,EAAE,CAAC;YACvC,KAAK,CAAC,KAAK,GAAG,IAAI,QAAQ,CAAC;gBACzB,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI;oBAC3B,IAAI,EAAE,CAAC;gBACT,CAAC;gBACD,KAAK,CAAC,IAAI;oBACR,UAAU,GAAG,IAAI,CAAC;oBAClB,cAAc,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;oBAC7C,IAAI,EAAE,CAAC;gBACT,CAAC;aACF,CAAC,CAAC;YAEH,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC,CAAC;IAEH,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC,CAAC,CAAC;AAEH,EAAE,CAAC,uEAAuE,EAAE,KAAK,IAAI,EAAE;IACrF,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;IAC9C,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,MAAM,aAAa,GAAG,mBAAmB,CAAC,cAAc,EAAE;QACxD,MAAM,EAAE,eAAe,CAAC,MAAM;QAC9B,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE;YACzC,MAAM,KAAK,GAAG,sBAAsB,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,GAAG,GAAG,EAAE;gBAChB,SAAS,IAAI,CAAC,CAAC;gBACf,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,SAAS,CAA+B,CAAC;gBACjE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;gBACzB,cAAc,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;gBAC9C,OAAO,IAAI,CAAC;YACd,CAAC,CAAC;YACF,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC,CAAC;IAEH,eAAe,CAAC,KAAK,EAAE,CAAC;IACxB,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC;IAEnC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC,CAAC,CAAC;AAEH,SAAS,sBAAsB;IAC7B,OAAO;QACL,KAAK,EAAE,IAAI,WAAW,EAAE;KACE,CAAC;AAC/B,CAAC"}

package/dist/utils/shell/sandbox/denied-read-detector.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Information extracted from a sandbox denied-read failure.
+ * `path` is the resolved real path of the denied file/dir (for display only).
+ * `suggestedParent` is the smallest stable useful parent to add to `allowRead`
+ *   when the user chooses "allow once" or "allow and remember".
+ * `sensitive` suppresses the "allow and remember" option for credential-shaped paths.
+ */
+export interface DeniedReadInfo {
+    path: string;
+    suggestedParent: string;
+    sensitive: boolean;
+}
+/**
+ * Whether the given denied path is a credential-shaped or broad config root
+ * for which "allow and remember" must be suppressed.
+ */
+export declare function isSensitiveReadPath(p: string): boolean;
+/**
+ * Picks the smallest stable useful parent for a denied path.
+ * For known package-manager stores (pnpm, cargo, rustup, m2, etc.), returns the store root.
+ * For others, falls back to `dirname` of the denied path.
+ * Never collapses to the home root or broad config ancestors.
+ */
+export declare function suggestStableParent(p: string): string;
+/**
+ * Attempt to detect a denied-read failure from sandbox runtime output.
+ * Returns null if no path can be extracted (falls back to the generic escape instruction).
+ *
+ * macOS: parses the `<sandbox_violations>` block emitted by SandboxManager.annotateStderrWithSandboxFailures.
+ * Linux (bwrap): parses common tool error patterns (Permission denied / Operation not permitted),
+ *   since bwrap does not emit structured annotation events.
+ */
+export declare function detectDeniedRead(_command: string, stderr: string): DeniedReadInfo | null;
+/**
+ * Instruction shown to the agent when a sandbox denied-read is detected,
+ * encouraging a same-parameter retry so the user can approve the read.
+ */
+export declare const DETAILED_DENIED_READ_INSTRUCTION = "Sandbox blocked a read access. Retry the same command; the user will be prompted to allow the read for this project.";
+//# sourceMappingURL=denied-read-detector.d.ts.map

package/dist/utils/shell/sandbox/denied-read-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"denied-read-detector.d.ts","sourceRoot":"","sources":["../../../../source/utils/shell/sandbox/denied-read-detector.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;CACpB;AAsDD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAqBtD;AA6BD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CA+BrD;AA+FD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAaxF;AAED;;;GAGG;AACH,eAAO,MAAM,gCAAgC,yHAC2E,CAAC"}

package/dist/utils/shell/sandbox/denied-read-detector.js

@@ -0,0 +1,250 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+const home = os.homedir();
+const SENSITIVE_SUBPATHS = [
+    path.join(home, '.ssh'),
+    path.join(home, '.aws'),
+    path.join(home, '.azure'),
+    path.join(home, '.config', 'gcloud'),
+    path.join(home, '.docker', 'config.json'),
+    path.join(home, '.docker'),
+    path.join(home, '.netrc'),
+    path.join(home, '.git-credentials'),
+    path.join(home, '.bash_history'),
+    path.join(home, '.zsh_history'),
+    path.join(home, '.npmrc'),
+    path.join(home, '.pypirc'),
+    path.join(home, '.kube'),
+    path.join(home, '.gnupg'),
+    path.join(home, '.config', 'gh'),
+    path.join(home, '.config', 'hub'),
+    path.join(home, '.gem'),
+    path.join(home, '.gemrc'),
+    path.join(home, '.config'),
+    path.join(home, '.local'),
+];
+/**
+ * Carve-outs under sensitive broad roots (e.g. ~/.local) that are NOT sensitive.
+ * Checked before the sensitive list so package-manager caches are allowable.
+ */
+const NON_SENSITIVE_SUBPATHS = [
+    path.join(home, '.local', 'share', 'pnpm', 'store'),
+    path.join(home, '.local', 'share', 'pnpm'),
+    path.join(home, '.cargo'),
+    path.join(home, '.rustup'),
+    path.join(home, '.m2', 'repository'),
+    path.join(home, '.m2'),
+    path.join(home, '.gradle'),
+    path.join(home, '.npm', '_cacache'),
+    path.join(home, '.pyenv'),
+    path.join(home, '.rbenv'),
+    path.join(home, '.nvm'),
+];
+const SENSITIVE_REGEX_PREFIXES = [
+    // Browser profile dirs
+    path.join(home, '.mozilla'),
+    path.join(home, '.config', 'google-chrome'),
+    path.join(home, '.config', 'chromium'),
+    path.join(home, 'Library', 'Application Support', 'Google', 'Chrome'),
+    path.join(home, 'Library', 'Application Support', 'Chromium'),
+    path.join(home, 'Library', 'Application Support', 'Firefox'),
+];
+/**
+ * Whether the given denied path is a credential-shaped or broad config root
+ * for which "allow and remember" must be suppressed.
+ */
+export function isSensitiveReadPath(p) {
+    const normalized = path.resolve(p);
+    // Carve-outs (package-manager caches) take precedence over the broad-root rule.
+    for (const sub of NON_SENSITIVE_SUBPATHS) {
+        if (normalized === sub || normalized.startsWith(sub + path.sep)) {
+            return false;
+        }
+    }
+    for (const sub of SENSITIVE_SUBPATHS) {
+        if (normalized === sub || normalized.startsWith(sub + path.sep)) {
+            return true;
+        }
+    }
+    for (const prefix of SENSITIVE_REGEX_PREFIXES) {
+        if (normalized === prefix || normalized.startsWith(prefix + path.sep)) {
+            return true;
+        }
+    }
+    // Allow-listed package-manager caches under ~/.local are not sensitive.
+    // ~/.local/share/pnpm/store is explicitly non-sensitive.
+    return false;
+}
+const STORE_PARENTS = [
+    {
+        prefix: path.join(home, '.local', 'share', 'pnpm', 'store'),
+        parent: path.join(home, '.local', 'share', 'pnpm', 'store'),
+    },
+    { prefix: path.join(home, '.cargo'), parent: path.join(home, '.cargo') },
+    { prefix: path.join(home, '.rustup'), parent: path.join(home, '.rustup') },
+    {
+        prefix: path.join(home, '.m2', 'repository'),
+        parent: path.join(home, '.m2', 'repository'),
+    },
+    { prefix: path.join(home, '.m2'), parent: path.join(home, '.m2') },
+    { prefix: path.join(home, '.config', 'gh'), parent: path.join(home, '.config', 'gh') },
+    { prefix: path.join(home, '.gradle'), parent: path.join(home, '.gradle') },
+    { prefix: path.join(home, '.npm', '_cacache'), parent: path.join(home, '.npm', '_cacache') },
+    { prefix: path.join(home, '.pyenv'), parent: path.join(home, '.pyenv') },
+    { prefix: path.join(home, '.rbenv'), parent: path.join(home, '.rbenv') },
+    { prefix: path.join(home, '.nvm'), parent: path.join(home, '.nvm') },
+    { prefix: path.join(home, '.cargo'), parent: path.join(home, '.cargo') },
+    { prefix: path.join(home, '.rustup'), parent: path.join(home, '.rustup') },
+];
+/**
+ * Picks the smallest stable useful parent for a denied path.
+ * For known package-manager stores (pnpm, cargo, rustup, m2, etc.), returns the store root.
+ * For others, falls back to `dirname` of the denied path.
+ * Never collapses to the home root or broad config ancestors.
+ */
+export function suggestStableParent(p) {
+    const normalized = path.resolve(p);
+    // Known store mappings — prefer the most specific matching prefix.
+    let best;
+    for (const mapping of STORE_PARENTS) {
+        if (normalized === mapping.prefix || normalized.startsWith(mapping.prefix + path.sep)) {
+            if (!best || mapping.prefix.length > best.prefix.length) {
+                best = mapping;
+            }
+        }
+    }
+    if (best) {
+        return best.parent;
+    }
+    // Floor: never suggest the home root or broad config roots.
+    // If dirname would collapse to home, return the path itself (do not broaden).
+    const dir = path.dirname(normalized);
+    if (dir === home || dir === path.join(home) || normalized === home) {
+        return normalized;
+    }
+    // Avoid broad config roots as the suggested parent.
+    if (dir === path.join(home, '.config') ||
+        dir === path.join(home, '.local') ||
+        dir === path.join(home, '.local', 'share')) {
+        return normalized;
+    }
+    return dir;
+}
+/**
+ * macOS sandbox violation line patterns.
+ * Examples handled:
+ *   Sandbox: term2(123) deny(1) file-read* /Users/user/.local/share/pnpm/store
+ *   Sandbox: node(678) deny file-read-data /Users/me/.cargo/registry/cache
+ */
+const MACOS_READ_DENY_REGEXES = [/deny(?:\(\d+\))?\s+file-read\S*\s+(\/\S+)/];
+function extractMacosViolationPath(stderr) {
+    const violationsStart = stderr.indexOf('<sandbox_violations>');
+    const violationsEnd = stderr.indexOf('</sandbox_violations>');
+    if (violationsStart === -1 || violationsEnd === -1)
+        return null;
+    const block = stderr.slice(violationsStart, violationsEnd);
+    const lines = block.split('\n');
+    for (const line of lines) {
+        if (!line.includes('deny'))
+            continue;
+        for (const regex of MACOS_READ_DENY_REGEXES) {
+            const match = regex.exec(line);
+            if (match?.[1]) {
+                return resolvePathSafely(match[1]);
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Linux generic tool error patterns (bwrap does not emit structured annotations;
+ * denials surface as PERMISSION_DENIED / EACCES in the command's own stderr).
+ *   cat: /home/user/.m2/...: Permission denied
+ *   cat: cannot open '/home/...': Permission denied
+ *   grep: /home/user/.cargo/registry: Operation not permitted
+ */
+const LINUX_PERMISSION_REGEXES = [
+    /(?:cannot open '|\s)(\/[^\s']+: Permission denied)/,
+    /cannot open '(\/[^']+)'/,
+    /(?::\s)(\/[^\s:']+)(?:: Permission denied|: Operation not permitted)/,
+    /\s(\/\S+): (?:Permission denied|Operation not permitted)/,
+    /^(\/\S+): (?:Permission denied|Operation not permitted)/m,
+];
+const LINUX_HIDDEN_EXISTING_PATH_REGEXES = [
+    /(?:^|\n)\S*sh: line \d+: (\/[^\n:]+): No such file or directory/,
+];
+function extractLinuxPermissionPath(stderr) {
+    for (const regex of LINUX_PERMISSION_REGEXES) {
+        const match = regex.exec(stderr);
+        if (match?.[1]) {
+            return resolvePathSafely(match[1].replace(/: Permission denied|: Operation not permitted$/, ''));
+        }
+    }
+    return null;
+}
+function extractLinuxHiddenExistingPath(stderr) {
+    for (const regex of LINUX_HIDDEN_EXISTING_PATH_REGEXES) {
+        const match = regex.exec(stderr);
+        if (!match?.[1])
+            continue;
+        const candidate = match[1].trim().replace(/["']/g, '');
+        const normalized = path.resolve(candidate);
+        if ((normalized === home || normalized.startsWith(home + path.sep)) && fs.existsSync(normalized)) {
+            return resolvePathSafely(normalized);
+        }
+    }
+    return null;
+}
+function resolvePathSafely(p) {
+    const trimmed = p.trim().replace(/["']/g, '');
+    try {
+        return fs.realpathSync(trimmed);
+    }
+    catch {
+        return path.resolve(trimmed);
+    }
+}
+function appearsToFileReadDenial(line) {
+    return line.includes('deny') && /file-read/.test(line);
+}
+function hasNetworkOnlyDenial(stderr) {
+    const violationsStart = stderr.indexOf('<sandbox_violations>');
+    const violationsEnd = stderr.indexOf('</sandbox_violations>');
+    if (violationsStart === -1 || violationsEnd === -1)
+        return false;
+    const block = stderr.slice(violationsStart, violationsEnd);
+    const lines = block.split('\n').filter((l) => l.includes('deny'));
+    if (lines.length === 0)
+        return false;
+    // Every violation is network-only (no file-read).
+    return lines.every((l) => !appearsToFileReadDenial(l) && /network/.test(l));
+}
+/**
+ * Attempt to detect a denied-read failure from sandbox runtime output.
+ * Returns null if no path can be extracted (falls back to the generic escape instruction).
+ *
+ * macOS: parses the `<sandbox_violations>` block emitted by SandboxManager.annotateStderrWithSandboxFailures.
+ * Linux (bwrap): parses common tool error patterns (Permission denied / Operation not permitted),
+ *   since bwrap does not emit structured annotation events.
+ */
+export function detectDeniedRead(_command, stderr) {
+    // macOS structured violations block takes precedence.
+    const macosPath = extractMacosViolationPath(stderr);
+    const candidate = macosPath ?? extractLinuxPermissionPath(stderr) ?? extractLinuxHiddenExistingPath(stderr);
+    if (!candidate) {
+        // If the only denials are network, this is not a read denial.
+        if (hasNetworkOnlyDenial(stderr))
+            return null;
+        return null;
+    }
+    const suggestedParent = suggestStableParent(candidate);
+    const sensitive = isSensitiveReadPath(candidate);
+    return { path: candidate, suggestedParent, sensitive };
+}
+/**
+ * Instruction shown to the agent when a sandbox denied-read is detected,
+ * encouraging a same-parameter retry so the user can approve the read.
+ */
+export const DETAILED_DENIED_READ_INSTRUCTION = 'Sandbox blocked a read access. Retry the same command; the user will be prompted to allow the read for this project.';
+//# sourceMappingURL=denied-read-detector.js.map

package/dist/utils/shell/sandbox/denied-read-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"denied-read-detector.js","sourceRoot":"","sources":["../../../../source/utils/shell/sandbox/denied-read-detector.ts"],"names":[],"mappings":"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"}

package/dist/utils/shell/sandbox/denied-read-stores.d.ts

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import type { ILoggingService } from '../../../services/service-interfaces.js';
+import type { DeniedReadInfo } from './denied-read-detector.js';
+/**
+ * Per-command execution override set at approval time and consumed by `execute` on resume.
+ * - `extraAllowRead`: merged into allowRead for this one execution only.
+ * - `forceUnsandboxed`: run this one call without the sandbox (approved escape).
+ */
+export interface ExecutionOverride {
+    extraAllowRead?: string[];
+    forceUnsandboxed?: boolean;
+}
+/**
+ * In-memory, session-scoped store of denied-read info keyed by normalized command string.
+ *
+ * Lifecycle of an entry:
+ * 1. `execute` detects a denied read → `record(command, info)`.
+ * 2. The agent retries the same command; the approval-result builder calls `consume(command)` → returns the info
+ *    (so the approval gate fires), then `stageForDescriptor(command, info)` re-stages it so the
+ *    approval-result builder can attach `deniedRead` metadata to the ApprovalDescriptor.
+ * 3. `consumeStaged(command)` is called by the approval flow to set the retry override and clear.
+ */
+export declare class DeniedReadStore {
+    #private;
+    record(command: string, info: DeniedReadInfo): void;
+    consume(command: string): DeniedReadInfo | null;
+    peek(command: string): DeniedReadInfo | null;
+    has(command: string): boolean;
+    stageForDescriptor(descriptorKey: string, info: DeniedReadInfo): void;
+    consumeStaged(descriptorKey: string): DeniedReadInfo | null;
+    clear(): void;
+}
+/**
+ * In-memory, per-command store of execution overrides. Set at approval-decision time;
+ * consumed and cleared by `execute` when the SDK resumes the approved tool call.
+ */
+export declare class ExecutionOverrideStore {
+    #private;
+    set(command: string, override: ExecutionOverride): void;
+    consume(command: string): ExecutionOverride | null;
+    clear(): void;
+}
+/**
+ * Persistent, project-scoped store of remembered allow-read paths.
+ * Stored at `<workspaceRoot>/.term2/sandbox-allow-paths.json`.
+ *
+ * Paths are realpath-normalized and deduplicated before persistence.
+ * A separate, dedicated store (not the global settings system) so that remembered
+ * paths stay scoped to the workspace where they were approved.
+ */
+export declare class ProjectSandboxAllowReadStore {
+    #private;
+    constructor(workspaceRoot: string, fsImpl?: typeof fs, log?: ILoggingService);
+    load(): string[];
+    append(filePath: string): void;
+}
+/**
+ * Module-level singletons shared between the shell tool and the approval flow.
+ * A conversation is single-threaded in this CLI, so entries are consumed in order.
+ * Each entry is one-shot (consumed on use), so no cross-turn contamination occurs.
+ */
+export declare const deniedReadStore: DeniedReadStore;
+export declare const executionOverrideStore: ExecutionOverrideStore;
+/**
+ * Returns the project-scoped allow-read store for the given workspace root.
+ * The store is lazily created and re-created if the workspace root changes
+ * (unlikely in practice — the launch cwd is stable for the process).
+ */
+export declare function getProjectAllowReadStore(workspaceRoot: string): ProjectSandboxAllowReadStore;
+/**
+ * Test-only: reset all module-level singletons. Not for production use.
+ */
+export declare function resetSandboxDeniedReadStoresForTest(): void;
+//# sourceMappingURL=denied-read-stores.d.ts.map

package/dist/utils/shell/sandbox/denied-read-stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"denied-read-stores.d.ts","sourceRoot":"","sources":["../../../../source/utils/shell/sandbox/denied-read-stores.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;;IAI1B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAInD,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAS/C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAI5C,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI;IAIrE,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAS3D,KAAK,IAAI,IAAI;CAId;AAED;;;GAGG;AACH,qBAAa,sBAAsB;;IAGjC,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAIvD,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IASlD,KAAK,IAAI,IAAI;CAGd;AAUD;;;;;;;GAOG;AACH,qBAAa,4BAA4B;;gBAK3B,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,EAAE,eAAe;IAU5E,IAAI,IAAI,MAAM,EAAE;IAgBhB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CA0B/B;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,iBAAwB,CAAC;AACrD,eAAO,MAAM,sBAAsB,wBAA+B,CAAC;AAKnE;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,4BAA4B,CAM5F;AAED;;GAEG;AACH,wBAAgB,mCAAmC,IAAI,IAAI,CAK1D"}

package/dist/utils/shell/sandbox/denied-read-stores.js

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * In-memory, session-scoped store of denied-read info keyed by normalized command string.
+ *
+ * Lifecycle of an entry:
+ * 1. `execute` detects a denied read → `record(command, info)`.
+ * 2. The agent retries the same command; the approval-result builder calls `consume(command)` → returns the info
+ *    (so the approval gate fires), then `stageForDescriptor(command, info)` re-stages it so the
+ *    approval-result builder can attach `deniedRead` metadata to the ApprovalDescriptor.
+ * 3. `consumeStaged(command)` is called by the approval flow to set the retry override and clear.
+ */
+export class DeniedReadStore {
+    #byCommand = new Map();
+    #stagedByDescriptorKey = new Map();
+    record(command, info) {
+        this.#byCommand.set(command, info);
+    }
+    consume(command) {
+        const info = this.#byCommand.get(command);
+        if (info) {
+            this.#byCommand.delete(command);
+            return info;
+        }
+        return null;
+    }
+    peek(command) {
+        return this.#byCommand.get(command) ?? null;
+    }
+    has(command) {
+        return this.#byCommand.has(command);
+    }
+    stageForDescriptor(descriptorKey, info) {
+        this.#stagedByDescriptorKey.set(descriptorKey, info);
+    }
+    consumeStaged(descriptorKey) {
+        const info = this.#stagedByDescriptorKey.get(descriptorKey);
+        if (info) {
+            this.#stagedByDescriptorKey.delete(descriptorKey);
+            return info;
+        }
+        return null;
+    }
+    clear() {
+        this.#byCommand.clear();
+        this.#stagedByDescriptorKey.clear();
+    }
+}
+/**
+ * In-memory, per-command store of execution overrides. Set at approval-decision time;
+ * consumed and cleared by `execute` when the SDK resumes the approved tool call.
+ */
+export class ExecutionOverrideStore {
+    #byCommand = new Map();
+    set(command, override) {
+        this.#byCommand.set(command, override);
+    }
+    consume(command) {
+        const override = this.#byCommand.get(command);
+        if (override) {
+            this.#byCommand.delete(command);
+            return override;
+        }
+        return null;
+    }
+    clear() {
+        this.#byCommand.clear();
+    }
+}
+const PROJECT_CONFIG_DIR = '.term2';
+const PROJECT_CONFIG_FILE = 'sandbox-allow-paths.json';
+/**
+ * Persistent, project-scoped store of remembered allow-read paths.
+ * Stored at `<workspaceRoot>/.term2/sandbox-allow-paths.json`.
+ *
+ * Paths are realpath-normalized and deduplicated before persistence.
+ * A separate, dedicated store (not the global settings system) so that remembered
+ * paths stay scoped to the workspace where they were approved.
+ */
+export class ProjectSandboxAllowReadStore {
+    #workspaceRoot;
+    #log;
+    #fs;
+    constructor(workspaceRoot, fsImpl, log) {
+        this.#workspaceRoot = workspaceRoot;
+        this.#fs = fsImpl ?? fs;
+        this.#log = log;
+    }
+    get #configPath() {
+        return path.join(this.#workspaceRoot, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILE);
+    }
+    load() {
+        try {
+            if (!this.#fs.existsSync(this.#configPath))
+                return [];
+            const raw = this.#fs.readFileSync(this.#configPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!parsed || !Array.isArray(parsed.allowReadExtra))
+                return [];
+            return this.#normalize(parsed.allowReadExtra);
+        }
+        catch (error) {
+            // Corrupt or unreadable config: fail safe with an empty list.
+            this.#log?.warn('Failed to read project sandbox-allow-paths; returning empty list', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+    append(filePath) {
+        const normalized = this.#normalizeOne(filePath);
+        const current = this.load();
+        if (current.includes(normalized))
+            return;
+        const next = [...current, normalized];
+        this.#write(next);
+    }
+    #write(paths) {
+        const dir = path.dirname(this.#configPath);
+        this.#fs.mkdirSync(dir, { recursive: true });
+        const payload = { version: 1, allowReadExtra: paths };
+        this.#fs.writeFileSync(this.#configPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+    }
+    #normalize(paths) {
+        return Array.from(new Set(paths.map((p) => this.#normalizeOne(p))));
+    }
+    #normalizeOne(filePath) {
+        try {
+            return this.#fs.realpathSync(filePath);
+        }
+        catch {
+            return path.resolve(filePath);
+        }
+    }
+}
+/**
+ * Module-level singletons shared between the shell tool and the approval flow.
+ * A conversation is single-threaded in this CLI, so entries are consumed in order.
+ * Each entry is one-shot (consumed on use), so no cross-turn contamination occurs.
+ */
+export const deniedReadStore = new DeniedReadStore();
+export const executionOverrideStore = new ExecutionOverrideStore();
+let projectAllowReadStore = null;
+let projectAllowReadStoreRoot = null;
+/**
+ * Returns the project-scoped allow-read store for the given workspace root.
+ * The store is lazily created and re-created if the workspace root changes
+ * (unlikely in practice — the launch cwd is stable for the process).
+ */
+export function getProjectAllowReadStore(workspaceRoot) {
+    if (!projectAllowReadStore || projectAllowReadStoreRoot !== workspaceRoot) {
+        projectAllowReadStore = new ProjectSandboxAllowReadStore(workspaceRoot);
+        projectAllowReadStoreRoot = workspaceRoot;
+    }
+    return projectAllowReadStore;
+}
+/**
+ * Test-only: reset all module-level singletons. Not for production use.
+ */
+export function resetSandboxDeniedReadStoresForTest() {
+    deniedReadStore.clear();
+    executionOverrideStore.clear();
+    projectAllowReadStore = null;
+    projectAllowReadStoreRoot = null;
+}
+//# sourceMappingURL=denied-read-stores.js.map