@hunterzhu/pulse-adapters 0.1.11 → 0.2.1

package/dist/tools/filesystem.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
-import { lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { link, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 function filesystemError(code, retryable = false, cause) {
@@ -56,13 +56,67 @@ export class FilesystemTool {
     async read(path, signal) { if (signal?.aborted)
         throw filesystemError('ABORTED'); return readFile(await this.existing(path), 'utf8'); }
     async readLimited(path, maxBytes, signal) {
+        const { content, truncated } = await this.readRange(path, maxBytes, 0, signal);
+        return { content, truncated };
+    }
+    /** Resolve a one-based source line without confusing line numbers with byte offsets. */
+    async offsetForLine(path, startLine, signal) {
+        if (!Number.isSafeInteger(startLine) || startLine < 1)
+            throw filesystemError('INVALID_START_LINE');
+        if (signal?.aborted)
+            throw filesystemError('ABORTED');
+        if (startLine === 1)
+            return 0;
+        const handle = await open(await this.existing(path), 'r');
+        try {
+            const buffer = Buffer.alloc(64 * 1024);
+            let offset = 0;
+            let line = 1;
+            const scanLimit = 16 * 1024 * 1024;
+            while (offset < scanLimit) {
+                if (signal?.aborted)
+                    throw filesystemError('ABORTED');
+                const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, scanLimit - offset), offset);
+                if (signal?.aborted)
+                    throw filesystemError('ABORTED');
+                if (!bytesRead)
+                    return offset;
+                for (let index = 0; index < bytesRead; index++) {
+                    if (buffer[index] === 10 && ++line === startLine)
+                        return offset + index + 1;
+                }
+                offset += bytesRead;
+            }
+            throw filesystemError('READ_LINE_SCAN_LIMIT');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async readRange(path, maxBytes, offset = 0, signal) {
         if (signal?.aborted)
             throw filesystemError('ABORTED');
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 1_000_000 || !Number.isSafeInteger(offset) || offset < 0)
+            throw filesystemError('INVALID_READ_RANGE');
         const handle = await open(await this.existing(path), 'r');
         try {
             const buffer = Buffer.alloc(maxBytes + 1);
-            const { bytesRead } = await handle.read(buffer, 0, maxBytes + 1, 0);
-            return { content: buffer.subarray(0, Math.min(bytesRead, maxBytes)).toString('utf8'), truncated: bytesRead > maxBytes };
+            const { bytesRead } = await handle.read(buffer, 0, maxBytes + 1, offset);
+            if (signal?.aborted)
+                throw filesystemError('ABORTED');
+            if (bytesRead && (buffer[0] & 0xc0) === 0x80)
+                throw filesystemError('INVALID_UTF8_OFFSET');
+            let end = Math.min(bytesRead, maxBytes);
+            if (bytesRead > maxBytes) {
+                // The byte after the window is a continuation: drop the partial codepoint.
+                while (end > 0 && (buffer[end] & 0xc0) === 0x80)
+                    end--;
+            }
+            if (end === 0 && bytesRead > 0)
+                throw filesystemError('READ_WINDOW_TOO_SMALL');
+            const content = buffer.subarray(0, end).toString('utf8');
+            const truncated = bytesRead > end;
+            return { content, truncated, offset, nextOffset: truncated ? offset + end : null };
         }
         finally {
             await handle.close();
@@ -102,7 +156,7 @@ export class FilesystemTool {
     async writeIfUnchanged(path, content, expectedHash, signal) {
         if (signal?.aborted)
             throw filesystemError('ABORTED');
-        if (!/^[a-f0-9]{64}$/.test(expectedHash))
+        if (expectedHash !== null && !/^[a-f0-9]{64}$/.test(expectedHash))
             throw filesystemError('INVALID_FILE_BASELINE_HASH');
         const target = await this.writable(path);
         return this.withLock(target, async () => {
@@ -113,11 +167,12 @@ export class FilesystemTool {
                 current = await readFile(target);
             }
             catch (cause) {
-                if (cause.code === 'ENOENT')
-                    throw filesystemError('FILE_BASELINE_MISSING');
-                throw filesystemCause(cause);
+                if (cause.code !== 'ENOENT')
+                    throw filesystemCause(cause);
             }
-            const currentHash = createHash('sha256').update(current).digest('hex');
+            if (current === undefined && expectedHash !== null)
+                throw filesystemError('FILE_BASELINE_MISSING');
+            const currentHash = current === undefined ? null : createHash('sha256').update(current).digest('hex');
             if (currentHash !== expectedHash)
                 throw filesystemError('FILE_BASELINE_CONFLICT');
             const bytes = Buffer.byteLength(content, 'utf8');
@@ -126,10 +181,17 @@ export class FilesystemTool {
             try {
                 handle = await open(temporary, 'wx', 0o600);
                 await handle.writeFile(content, 'utf8');
+                if (current !== undefined)
+                    await handle.chmod((await lstat(target)).mode & 0o777);
                 await handle.sync();
                 await handle.close();
                 handle = undefined;
-                await rename(temporary, target);
+                if (signal?.aborted)
+                    throw filesystemError('ABORTED');
+                if (expectedHash === null)
+                    await link(temporary, target);
+                else
+                    await rename(temporary, target);
             }
             finally {
                 if (handle)

package/dist/tools/sandbox-initialization.d.ts

@@ -0,0 +1,2 @@
+import { type SandboxRuntimeConfig } from '@anthropic-ai/sandbox-runtime';
+export declare function initializeShellSandbox(policy: SandboxRuntimeConfig, platform?: NodeJS.Platform): Promise<void>;

package/dist/tools/sandbox-initialization.js

@@ -0,0 +1,17 @@
+import { SandboxManager } from '@anthropic-ai/sandbox-runtime';
+export async function initializeShellSandbox(policy, platform = process.platform) {
+    try {
+        await SandboxManager.initialize(policy, undefined, false);
+    }
+    catch (error) {
+        // A cold Windows sandbox account can time out during the WFP readiness
+        // probe. Retry that probe once after cleanup, before any command is run.
+        // A failed isolation check, ACL error, or second timeout still fails closed.
+        if (platform !== 'win32' || !error || typeof error !== 'object'
+            || !('code' in error) || error.code !== 'srt_win_timeout'
+            || !('subcommand' in error) || error.subcommand !== 'wfp')
+            throw error;
+        await SandboxManager.reset();
+        await SandboxManager.initialize(policy, undefined, false);
+    }
+}

package/dist/tools/shell.d.ts

@@ -6,10 +6,20 @@ export interface ShellResult {
     timedOut: boolean;
     aborted: boolean;
 }
+/** Read-only prerequisite probe; never provisions accounts or changes permissions. */
+export declare function checkShellSandbox(): Promise<{
+    errors: string[];
+    warnings: string[];
+}>;
+export declare function quoteWindowsArgument(value: string): string;
+/** Build the command text expected by srt without interpreting model argv as shell syntax. */
+export declare function encodeSandboxCommand(command: string, args: string[], platform?: NodeJS.Platform): string;
+export declare function decodeUtf8WithinByteLimit(value: Buffer, maxBytes: number): string;
 export declare function runShell(command: string, args?: string[], options?: {
     cwd?: string;
     signal?: AbortSignal;
     timeoutMs?: number;
     maxOutputBytes?: number;
     env?: NodeJS.ProcessEnv;
+    allowedDomains?: string[];
 }): Promise<ShellResult>;

package/dist/tools/shell.js

@@ -1,81 +1,370 @@
-import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { homedir, tmpdir } from 'node:os';
+import { basename, delimiter, dirname, join, parse, resolve, sep } from 'node:path';
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { SandboxManager, VENDORED_SRT_WIN_EXE, checkWindowsDependenciesAsync, resolveSrtWin } from '@anthropic-ai/sandbox-runtime';
+import { resolveWindowsPackageManager } from './windows-package-manager.js';
+import { carveWindowsReadDenies } from './windows-read-policy.js';
+import { initializeShellSandbox } from './sandbox-initialization.js';
 function shellError(code, retryable = false, cause) {
     return Object.assign(new Error(code), { code, retryable, ...(cause === undefined ? {} : { cause }) });
 }
+// SandboxManager owns process-global proxy and policy state. A per-invocation
+// policy is installed for exactly one child at a time to avoid one concurrent
+// call widening another call's filesystem grants.
+let sandboxTail = Promise.resolve();
+function withSandboxLease(work) {
+    const result = sandboxTail.then(work, work);
+    sandboxTail = result.then(() => undefined, () => undefined);
+    return result;
+}
+/** Read-only prerequisite probe; never provisions accounts or changes permissions. */
+export async function checkShellSandbox() {
+    // doctor runs before initialize(), so the manager has no Windows config yet.
+    // Probe the same packaged helper used for execution without provisioning it.
+    return withSandboxLease(() => process.platform === 'win32'
+        ? checkWindowsDependenciesAsync({ srtWin: resolveSrtWin({ path: VENDORED_SRT_WIN_EXE }) })
+        : SandboxManager.checkDependenciesAsync());
+}
+function quotePosix(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export function quoteWindowsArgument(value) {
+    if (value.length > 0 && !/[\s"]/u.test(value))
+        return value;
+    let output = '"';
+    let slashes = 0;
+    for (const character of value) {
+        if (character === '\\') {
+            slashes++;
+            continue;
+        }
+        if (character === '"')
+            output += '\\'.repeat(slashes * 2 + 1) + '"';
+        else
+            output += '\\'.repeat(slashes) + character;
+        slashes = 0;
+    }
+    return output + '\\'.repeat(slashes * 2) + '"';
+}
+const powershellArgvRunner = String.raw `
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$payload = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('__PULSE_ARGV_JSON__'))
+$spec = ConvertFrom-Json -InputObject $payload
+$psi = [System.Diagnostics.ProcessStartInfo]::new()
+$psi.FileName = [string]$spec.command
+$psi.Arguments = [string]$spec.arguments
+$psi.UseShellExecute = $false
+$psi.CreateNoWindow = $true
+$psi.RedirectStandardOutput = $true
+$psi.RedirectStandardError = $true
+$psi.RedirectStandardInput = $true
+$psi.StandardOutputEncoding = [System.Text.Encoding]::UTF8
+$psi.StandardErrorEncoding = [System.Text.Encoding]::UTF8
+$child = [System.Diagnostics.Process]::new()
+$child.StartInfo = $psi
+try { if (-not $child.Start()) { exit 127 } }
+catch {
+  $cause = $_.Exception
+  while ($cause.InnerException) { $cause = $cause.InnerException }
+  [Console]::Error.WriteLine($cause.Message)
+  if ($cause -is [System.ComponentModel.Win32Exception] -and $cause.NativeErrorCode -in 2,3) { exit 127 }
+  exit 126
+}
+$outTask = $child.StandardOutput.ReadToEndAsync()
+$errTask = $child.StandardError.ReadToEndAsync()
+$inTask = [Console]::OpenStandardInput().CopyToAsync($child.StandardInput.BaseStream)
+[void]$inTask.GetAwaiter().GetResult()
+$child.StandardInput.Close()
+$child.WaitForExit()
+try { [Console]::Out.Write([string]$outTask.GetAwaiter().GetResult()) } catch {}
+try { [Console]::Error.Write([string]$errTask.GetAwaiter().GetResult()) } catch {}
+exit $child.ExitCode
+`.trim();
+/** Build the command text expected by srt without interpreting model argv as shell syntax. */
+export function encodeSandboxCommand(command, args, platform = process.platform) {
+    if ([command, ...args].some((value) => value.includes('\0')))
+        throw shellError('INVALID_SHELL_ARGUMENT');
+    if (platform === 'win32') {
+        // The only bytes placed in cmd.exe's command string are fixed tokens and
+        // base64. PowerShell decodes JSON and ProcessStartInfo.Arguments uses a
+        // Windows CRT-compatible encoder, preserving argv without a shell parse.
+        const payload = Buffer.from(JSON.stringify({ command, arguments: args.map(quoteWindowsArgument).join(' ') }), 'utf8').toString('base64');
+        const encoded = Buffer.from(powershellArgvRunner.replace('__PULSE_ARGV_JSON__', payload), 'utf16le').toString('base64');
+        const commandText = `powershell.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand ${encoded}`;
+        if (commandText.length > 24_000)
+            throw shellError('INVALID_SHELL_ARGUMENTS_TOO_LARGE');
+        return commandText;
+    }
+    return `exec ${[command, ...args].map(quotePosix).join(' ')}`;
+}
+async function sandboxConfig(cwd, allowedDomains = [], toolchainRoots = [], scratch) {
+    // Linux invokes this trusted helper *inside* the read-restricted namespace.
+    // A user-local npm install otherwise hides it together with the home directory.
+    const seccompPath = process.platform === 'linux'
+        ? await realpath(resolve(dirname(createRequire(import.meta.url).resolve('@anthropic-ai/sandbox-runtime')), '..', 'vendor', 'seccomp', process.arch, 'apply-seccomp'))
+        : undefined;
+    const home = homedir();
+    const parent = dirname(cwd);
+    const root = parse(cwd).root;
+    if (cwd === root || cwd === home || home.startsWith(cwd + sep) || parent === root) {
+        throw shellError('SANDBOX_WORKSPACE_TOO_BROAD');
+    }
+    // Windows runs as a separate srt-sandbox account, which has no access to
+    // private host-profile files without explicit grants. Stamping the entire
+    // profile recursively is both redundant and very expensive (registry/cache
+    // trees); only carve the workspace's sibling boundary on that platform.
+    const denyRead = new Set(process.platform === 'win32' ? [] : [home]);
+    // Close the common sibling-workspace and temporary-directory escape: deny
+    // the workspace's immediate container, then re-open only this invocation's
+    // cwd. Root workspaces cannot be carved this way and are rejected upstream.
+    if (parent !== parse(cwd).root && parent !== cwd)
+        denyRead.add(parent);
+    const allowRead = [cwd, ...toolchainRoots, ...(scratch ? [scratch] : []), ...(seccompPath ? [seccompPath] : [])];
+    // Reads default to the system toolchain plus this workspace. Writes are
+    // limited to the workspace; srt adds only its required stdio/temp paths.
+    return {
+        network: { allowedDomains, deniedDomains: [], strictAllowlist: true },
+        filesystem: {
+            denyRead: process.platform === 'win32' ? await carveWindowsReadDenies([...denyRead], allowRead) : [...denyRead],
+            allowRead,
+            allowWrite: [cwd, ...(scratch ? [scratch] : [])],
+            denyWrite: [],
+        },
+        ...(seccompPath ? { seccomp: { applyPath: seccompPath } } : {}),
+        ...(process.platform === 'win32' ? { windows: { srtWin: { path: VENDORED_SRT_WIN_EXE } } } : {}),
+    };
+}
+function cleanPath(value) {
+    return resolve(value);
+}
+export function decodeUtf8WithinByteLimit(value, maxBytes) {
+    if (!Number.isFinite(maxBytes) || maxBytes < 0)
+        throw shellError('INVALID_SHELL_OUTPUT_LIMIT');
+    const decoded = value.subarray(0, maxBytes).toString('utf8');
+    let used = 0;
+    const output = [];
+    for (const character of decoded) {
+        const bytes = Buffer.byteLength(character, 'utf8');
+        if (used + bytes > maxBytes)
+            break;
+        output.push(character);
+        used += bytes;
+    }
+    return output.join('');
+}
+function shellEnvironment(env) {
+    const source = env ?? process.env;
+    return Object.fromEntries(Object.entries(source).filter(([key]) => !/(API_KEY|TOKEN|SECRET|PASSWORD|PRIVATE_KEY|AUTHORIZATION|BEARER|CREDENTIAL|COOKIE)/i.test(key) && key !== 'NODE_OPTIONS'));
+}
 export function runShell(command, args = [], options = {}) {
     const max = options.maxOutputBytes ?? 256 * 1024;
     if (!Number.isFinite(max) || max < 0)
         return Promise.reject(shellError('INVALID_SHELL_OUTPUT_LIMIT'));
     if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0))
         return Promise.reject(shellError('INVALID_SHELL_TIMEOUT'));
-    return new Promise((resolve, reject) => {
-        const child = spawn(command, args, { cwd: options.cwd, env: options.env, shell: false, detached: process.platform !== 'win32', windowsHide: true });
-        let stdout = '';
-        let stderr = '';
-        let truncated = false;
-        const append = (target, chunk) => { const value = chunk.toString(); const current = target === 'stdout' ? stdout : stderr; const next = current + value; if (Buffer.byteLength(next) > max) {
-            truncated = true;
-            const limited = next.slice(0, max);
-            if (target === 'stdout')
-                stdout = limited;
-            else
-                stderr = limited;
+    if (!command || typeof command !== 'string' || !Array.isArray(args) || args.some((arg) => typeof arg !== 'string'))
+        return Promise.reject(shellError('INVALID_SHELL_ARGUMENT'));
+    try {
+        encodeSandboxCommand(command, args);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    return withSandboxLease(async () => {
+        if (options.signal?.aborted)
+            return { code: null, stdout: '', stderr: '', truncated: false, timedOut: false, aborted: true };
+        let cwd;
+        try {
+            cwd = await realpath(cleanPath(options.cwd ?? process.cwd()));
         }
-        else if (target === 'stdout')
-            stdout = next;
-        else
-            stderr = next; };
-        let closed = false;
-        const signalProcessGroup = (signal) => {
-            if (process.platform !== 'win32' && child.pid) {
-                try {
-                    process.kill(-child.pid, signal);
+        catch (cause) {
+            throw shellError('INVALID_SHELL_CWD', false, cause);
+        }
+        // Trust only the installation hosting Pulse, never arbitrary PATH directories.
+        const nodeExecutable = await realpath(process.execPath);
+        const nodeBin = dirname(nodeExecutable);
+        const installation = basename(nodeBin) === 'bin' ? dirname(nodeBin) : nodeBin;
+        const toolchainRoots = installation !== homedir() && installation !== parse(installation).root ? [installation] : [nodeExecutable];
+        // PNPM_HOME is a host installation setting, never supplied by model argv.
+        let pnpmHome;
+        if (process.env.PNPM_HOME) {
+            try {
+                const candidate = await realpath(process.env.PNPM_HOME);
+                if (candidate !== homedir() && candidate !== parse(candidate).root && !homedir().startsWith(candidate + sep)) {
+                    pnpmHome = candidate;
+                    toolchainRoots.push(candidate);
+                    // pnpm/action-setup exposes its executable shims from node_modules/.bin;
+                    // their targets live in the adjacent node_modules tree.
+                    if (basename(candidate) === '.bin')
+                        toolchainRoots.push(dirname(candidate));
+                }
+            }
+            catch { /* stale installation settings do not grant access */ }
+        }
+        const scratch = await realpath(await mkdtemp(join(tmpdir(), 'pulse-shell-')));
+        try {
+            const baseEnv = shellEnvironment(options.env);
+            const pathKey = Object.keys(baseEnv).find((key) => key.toUpperCase() === 'PATH') ?? 'PATH';
+            const executionEnv = { [pathKey]: [...(pnpmHome ? [pnpmHome] : []), nodeBin, join(cwd, 'node_modules', '.bin'), baseEnv[pathKey] ?? ''].join(delimiter),
+                ...(process.platform === 'win32' ? {} : { HOME: scratch, TMPDIR: scratch, TMP: scratch, TEMP: scratch, XDG_CONFIG_HOME: scratch, XDG_CACHE_HOME: scratch, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1' }) };
+            let executable = command;
+            let executableArgs = args;
+            if (command === 'node')
+                executable = nodeExecutable;
+            if (process.platform === 'darwin' && command === 'git') {
+                // /usr/bin/git is an xcrun shim that writes outside TMPDIR. Resolve the
+                // installed tool through Apple's fixed locator before entering isolation.
+                const located = await promisify(execFile)('/usr/bin/xcrun', ['--find', 'git'], { timeout: 5000, env: baseEnv });
+                executable = located.stdout.trim();
+                if (!executable.startsWith('/'))
+                    throw shellError('GIT_TOOLCHAIN_NOT_FOUND');
+            }
+            if (process.platform === 'win32') {
+                const resolved = await resolveWindowsPackageManager(command, nodeExecutable, pnpmHome);
+                if (resolved) {
+                    executable = resolved.executable;
+                    executableArgs = [...resolved.prefixArgs, ...args];
+                }
+            }
+            const invocationId = randomUUID();
+            const policy = await sandboxConfig(cwd, options.allowedDomains ?? [], toolchainRoots, scratch);
+            let child;
+            const outputChunks = { stdout: [], stderr: [] };
+            const outputBytes = { stdout: 0, stderr: 0 };
+            let truncated = false;
+            let closed = false;
+            let termination;
+            let timer;
+            let killTimer;
+            const signalProcessGroup = (signal) => {
+                if (!child?.pid)
+                    return;
+                if (process.platform !== 'win32') {
+                    try {
+                        process.kill(-child.pid, signal);
+                        return;
+                    }
+                    catch { /* process group may already be gone */ }
+                }
+                if (process.platform === 'win32') {
+                    const tree = spawn('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true, env: shellEnvironment(options.env) });
+                    tree.once('error', () => child?.kill(signal));
+                    tree.unref();
                     return;
                 }
-                catch { /* process group may already be gone */ }
+                child.kill(signal);
+            };
+            const terminate = (reason) => {
+                if (closed)
+                    return;
+                termination ??= reason;
+                signalProcessGroup('SIGTERM');
+                if (!killTimer)
+                    killTimer = setTimeout(() => { if (!closed)
+                        signalProcessGroup('SIGKILL'); }, 250);
+            };
+            const append = (target, chunk) => {
+                const remaining = Math.max(0, max - outputBytes[target]);
+                const kept = Math.min(chunk.byteLength, remaining);
+                if (kept > 0)
+                    outputChunks[target].push(chunk.subarray(0, kept));
+                outputBytes[target] += kept;
+                if (kept < chunk.byteLength)
+                    truncated = true;
+            };
+            const outputText = (target) => {
+                return decodeUtf8WithinByteLimit(Buffer.concat(outputChunks[target]), max);
+            };
+            let setupStage = 'reset';
+            try {
+                // reset first in case an earlier initialize failed part-way through.
+                await SandboxManager.reset();
+                setupStage = 'initialize';
+                await initializeShellSandbox(policy);
+                const commandText = encodeSandboxCommand(executable, executableArgs);
+                setupStage = 'wrap';
+                const descriptor = await SandboxManager.wrapWithSandboxArgv(commandText, undefined, undefined, options.signal, cwd, { commandId: invocationId, commandText: 'shell.exec' });
+                if (options.signal?.aborted) {
+                    SandboxManager.cleanupAfterCommand();
+                    await SandboxManager.reset();
+                    return { code: null, stdout: '', stderr: '', truncated: false, timedOut: false, aborted: true };
+                }
+                child = spawn(descriptor.argv[0], descriptor.argv.slice(1), {
+                    cwd,
+                    env: { ...baseEnv, ...shellEnvironment(descriptor.env), ...executionEnv },
+                    shell: false,
+                    detached: process.platform !== 'win32',
+                    windowsHide: true,
+                });
             }
-            if (process.platform === 'win32' && child.pid) {
-                // child.kill() only terminates the direct process on Windows; kill the
-                // owned process tree so cancelled shell tools cannot leave descendants.
-                const tree = spawn('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
-                tree.once('error', () => child.kill(signal));
-                tree.unref();
-                return;
+            catch (cause) {
+                try {
+                    await SandboxManager.reset();
+                }
+                catch { /* preserve the setup failure */ }
+                // Persist only classified diagnostics, never raw subprocess output or credentials.
+                const message = cause instanceof Error ? cause.message : '';
+                const nativeCode = cause && typeof cause === 'object' && 'code' in cause ? String(cause.code) : '';
+                const reason = /windows-install|not provisioned/i.test(message) ? 'WINDOWS_SANDBOX_NOT_PROVISIONED'
+                    : ['ENOENT', 'EACCES', 'EPERM'].includes(nativeCode) ? nativeCode : 'SANDBOX_INITIALIZATION_ERROR';
+                throw Object.assign(shellError('SANDBOX_SETUP_FAILED', false, cause), {
+                    message: `SANDBOX_SETUP_FAILED (${setupStage}: ${reason})`,
+                    details: { platform: process.platform, stage: setupStage, reason },
+                });
             }
-            child.kill(signal);
-        };
-        let termination;
-        let killTimer;
-        const terminate = (reason) => {
-            if (closed)
-                return;
-            termination ??= reason;
-            signalProcessGroup('SIGTERM');
-            if (!killTimer)
-                killTimer = setTimeout(() => { if (!closed)
-                    signalProcessGroup('SIGKILL'); }, 250);
-        };
-        const timer = options.timeoutMs && options.timeoutMs > 0 ? setTimeout(() => terminate('timeout'), options.timeoutMs) : undefined;
-        const abort = () => terminate('aborted');
-        if (options.signal) {
-            if (options.signal.aborted)
-                abort();
-            else
-                options.signal.addEventListener('abort', abort, { once: true });
+            // This API has no stdin payload; deliver EOF to readers inside the sandbox.
+            child.stdin?.end();
+            return await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    if (timer)
+                        clearTimeout(timer);
+                    if (killTimer)
+                        clearTimeout(killTimer);
+                    options.signal?.removeEventListener('abort', abort);
+                };
+                const abort = () => terminate('aborted');
+                timer = options.timeoutMs && options.timeoutMs > 0 ? setTimeout(() => terminate('timeout'), options.timeoutMs) : undefined;
+                if (options.signal)
+                    options.signal.addEventListener('abort', abort, { once: true });
+                if (options.signal?.aborted)
+                    abort();
+                child.stdout?.on('data', (chunk) => append('stdout', chunk));
+                child.stderr?.on('data', (chunk) => append('stderr', chunk));
+                child.once('error', (cause) => {
+                    closed = true;
+                    cleanup();
+                    const errorCode = cause && typeof cause === 'object' ? cause.code : undefined;
+                    const code = typeof errorCode === 'string' ? errorCode : 'SHELL_EXECUTION_ERROR';
+                    reject(shellError(code === 'ENOENT' || code === 'EACCES' ? code : 'SHELL_EXECUTION_ERROR', false, cause));
+                });
+                child.once('close', (code) => {
+                    closed = true;
+                    cleanup();
+                    const stdout = outputText('stdout');
+                    const stderr = outputText('stderr');
+                    const annotated = SandboxManager.annotateStderrWithSandboxFailures(invocationId, stderr);
+                    const boundedStderr = decodeUtf8WithinByteLimit(Buffer.from(annotated, 'utf8'), max);
+                    const outputWasTruncated = truncated || Buffer.byteLength(annotated, 'utf8') > max;
+                    resolve({ code, stdout, stderr: boundedStderr, truncated: outputWasTruncated, timedOut: termination === 'timeout', aborted: termination === 'aborted' });
+                });
+            }).finally(async () => {
+                try {
+                    SandboxManager.cleanupAfterCommand();
+                    await SandboxManager.reset();
+                }
+                catch (cause) {
+                    // A teardown failure must be visible and fail closed for the next call.
+                    throw shellError('SANDBOX_CLEANUP_FAILED', false, cause);
+                }
+            });
+        }
+        finally {
+            await rm(scratch, { recursive: true, force: true });
         }
-        child.stdout.on('data', (chunk) => append('stdout', chunk));
-        child.stderr.on('data', (chunk) => append('stderr', chunk));
-        child.on('error', (cause) => {
-            closed = true;
-            if (timer)
-                clearTimeout(timer);
-            if (killTimer)
-                clearTimeout(killTimer);
-            const code = cause && typeof cause === 'object' && typeof cause.code === 'string' ? String(cause.code) : 'SHELL_EXECUTION_ERROR';
-            reject(shellError(code === 'ENOENT' || code === 'EACCES' ? code : 'SHELL_EXECUTION_ERROR', false, cause));
-        });
-        child.on('close', (code) => { closed = true; if (timer)
-            clearTimeout(timer); if (killTimer)
-            clearTimeout(killTimer); resolve({ code, stdout, stderr, truncated, timedOut: termination === 'timeout', aborted: termination === 'aborted' }); });
     });
 }

package/dist/tools/windows-package-manager.d.ts

@@ -0,0 +1,5 @@
+/** Resolve trusted installations without executing .cmd shims or fetching via Corepack first. */
+export declare function resolveWindowsPackageManager(command: string, nodeExecutable: string, pnpmHome?: string): Promise<{
+    executable: string;
+    prefixArgs: string[];
+} | undefined>;

package/dist/tools/windows-package-manager.js

@@ -0,0 +1,31 @@
+import { realpath, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** Resolve trusted installations without executing .cmd shims or fetching via Corepack first. */
+export async function resolveWindowsPackageManager(command, nodeExecutable, pnpmHome) {
+    if (!['npm', 'npx', 'pnpm', 'pnpx', 'corepack'].includes(command))
+        return undefined;
+    const nodeBin = dirname(nodeExecutable);
+    const candidates = [];
+    if (command === 'pnpm' || command === 'pnpx') {
+        // pnpm 11+ ships a native executable and an .mjs wrapper; older versions use .cjs.
+        // action-setup installs its package next to PNPM_HOME (.bin).
+        const roots = [...(pnpmHome ? [pnpmHome, join(dirname(pnpmHome), 'pnpm')] : []), join(nodeBin, 'node_modules', 'pnpm')];
+        for (const root of roots) {
+            candidates.push({ path: join(root, 'pnpm.exe'), native: true, dlx: command === 'pnpx' }, { path: join(root, 'bin', `${command}.mjs`) }, { path: join(root, 'bin', 'pnpm.cjs'), dlx: command === 'pnpx' });
+        }
+    }
+    else {
+        candidates.push({ path: join(nodeBin, 'node_modules', command === 'corepack' ? 'corepack/dist/corepack.js' : `npm/bin/${command}-cli.js`) });
+    }
+    candidates.push({ path: join(nodeBin, 'node_modules', 'corepack', 'dist', `${command}.js`) });
+    for (const candidate of candidates) {
+        try {
+            const path = await realpath(candidate.path);
+            if (!(await stat(path)).isFile())
+                continue;
+            return { executable: candidate.native ? path : nodeExecutable, prefixArgs: [...(candidate.native ? [] : [path]), ...(candidate.dlx ? ['dlx'] : [])] };
+        }
+        catch { /* Missing installations fall through to the next trusted candidate. */ }
+    }
+    return undefined;
+}

package/dist/tools/windows-read-policy.d.ts

@@ -0,0 +1,2 @@
+/** Keep denied subtrees off the ancestors Git must stat to reach an allowed workspace. */
+export declare function carveWindowsReadDenies(denied: string[], allowed: string[]): Promise<string[]>;