@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/core/text.js

@@ -0,0 +1,40 @@
+// Text helpers that count Unicode characters, not UTF-16 units, so budgets and cuts agree across languages.
+export function charCount(text) {
+    let count = 0;
+    for (const _ of text)
+        count += 1;
+    return count;
+}
+export function takeChars(text, count) {
+    if (text.length <= count)
+        return text;
+    let taken = 0;
+    let end = 0;
+    for (const character of text) {
+        if (taken >= count)
+            break;
+        taken += 1;
+        end += character.length;
+    }
+    return text.slice(0, end);
+}
+/** Lines without their terminators; a final newline does not add an empty last line. */
+export function lines(text) {
+    if (!text)
+        return [];
+    const parts = text.split('\n');
+    if (parts[parts.length - 1] === '')
+        parts.pop();
+    return parts.map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line));
+}
+/** Orders file paths segment by segment, so a folder sorts before a sibling whose name extends it. */
+export function comparePaths(left, right) {
+    const a = left.split('/');
+    const b = right.split('/');
+    for (let index = 0; index < Math.min(a.length, b.length); index += 1) {
+        if (a[index] !== b[index])
+            return a[index] < b[index] ? -1 : 1;
+    }
+    return a.length - b.length;
+}
+export const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);

package/dist/sdk/core/workspace.d.ts

@@ -0,0 +1,13 @@
+/** The nearest Git repository containing `cwd`, or its canonical directory when there is none. */
+export declare function resolveWorkspaceRoot(cwd: string): string;
+/**
+ * Resolves a write target relative to `cwd` (the workspace root by default), and returns its
+ * canonical path only when the target stays inside the canonical workspace root.
+ */
+export declare function resolveWorkspaceWritePath(workspaceRoot: string, candidate: string, cwd?: string): string;
+/** Canonicalizes an absolute, relative, or home-relative write target without imposing a root. */
+export declare function resolveWritePath(candidate: string, cwd?: string): string;
+/** Whether a canonical target is within the workspace's canonical filesystem root. */
+export declare function isWithinWorkspace(workspaceRoot: string, canonicalCandidate: string): boolean;
+/** Revalidates a root pinned by an active run; a replaced or redirected root fails closed. */
+export declare function verifyWorkspaceRoot(workspaceRoot: string): string;

package/dist/sdk/core/workspace.js

@@ -0,0 +1,88 @@
+import { lstatSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { invalid } from "./errors.js";
+/** The nearest Git repository containing `cwd`, or its canonical directory when there is none. */
+export function resolveWorkspaceRoot(cwd) {
+    const canonicalCwd = realpathSync(cwd);
+    if (!statSync(canonicalCwd).isDirectory())
+        throw invalid('The working directory must be a directory.');
+    if (dirname(canonicalCwd) === canonicalCwd)
+        throw invalid('The filesystem root cannot be used as an active project workspace.');
+    let directory = canonicalCwd;
+    while (true) {
+        try {
+            const marker = lstatSync(resolve(directory, '.git'));
+            if (marker.isDirectory() || marker.isFile())
+                return directory;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return canonicalCwd;
+        directory = parent;
+    }
+}
+/**
+ * Resolves a write target relative to `cwd` (the workspace root by default), and returns its
+ * canonical path only when the target stays inside the canonical workspace root.
+ */
+export function resolveWorkspaceWritePath(workspaceRoot, candidate, cwd = workspaceRoot) {
+    const canonicalCandidate = resolveWritePath(candidate, cwd);
+    if (!isWithinWorkspace(workspaceRoot, canonicalCandidate))
+        throw invalid('Write target is outside the active project workspace.');
+    return canonicalCandidate;
+}
+/** Canonicalizes an absolute, relative, or home-relative write target without imposing a root. */
+export function resolveWritePath(candidate, cwd = process.cwd()) {
+    const expanded = candidate === '~'
+        ? homedir()
+        : candidate.startsWith('~/') || candidate.startsWith('~\\')
+            ? join(homedir(), candidate.slice(2))
+            : candidate;
+    const absoluteCandidate = isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
+    return canonicalizeTarget(absoluteCandidate);
+}
+/** Whether a canonical target is within the workspace's canonical filesystem root. */
+export function isWithinWorkspace(workspaceRoot, canonicalCandidate) {
+    const canonicalRoot = realpathSync(workspaceRoot);
+    if (!statSync(canonicalRoot).isDirectory())
+        throw invalid('The workspace root must be a directory.');
+    const fromRoot = relative(canonicalRoot, canonicalCandidate);
+    return fromRoot === '' || (fromRoot !== '..' && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot));
+}
+/** Revalidates a root pinned by an active run; a replaced or redirected root fails closed. */
+export function verifyWorkspaceRoot(workspaceRoot) {
+    const canonicalRoot = realpathSync(workspaceRoot);
+    if (dirname(canonicalRoot) === canonicalRoot)
+        throw invalid('The filesystem root cannot be used as an active project workspace.');
+    if (canonicalRoot !== resolve(workspaceRoot) || !statSync(canonicalRoot).isDirectory()) {
+        throw invalid('The active project workspace changed after this run began.');
+    }
+    return canonicalRoot;
+}
+function canonicalizeTarget(path) {
+    const missing = [];
+    let current = path;
+    while (true) {
+        let exists = false;
+        try {
+            lstatSync(current);
+            exists = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (exists)
+            return resolve(realpathSync(current), ...missing.reverse());
+        const parent = dirname(current);
+        if (parent === current)
+            throw invalid('Write target could not be resolved.');
+        missing.push(basename(current));
+        current = parent;
+    }
+}

package/dist/sdk/core/workspaceBashTool.d.ts

@@ -0,0 +1,20 @@
+import type { BashOperations } from '@earendil-works/pi-coding-agent';
+import { type Shell } from "./shell.js";
+/** Quotes command text and escapes terminal control/format characters for approval details. */
+export declare function formatBashCommandForApproval(command: string): string;
+interface ShellToolFactories<T> {
+    createBashTool: (cwd: string, options: {
+        operations: BashOperations;
+    }) => T;
+    createPowerShellTool: (cwd: string, options: {
+        operations: BashOperations;
+    }) => T;
+}
+/**
+ * The `bash` tool for this machine. The capability keeps the name `bash` on every platform; on a
+ * Windows machine without Git Bash it runs PowerShell and carries PowerShell's description.
+ */
+export declare function createWorkspaceShellTool<T>(pi: ShellToolFactories<T>, cwd: string, operations: BashOperations, shell?: Shell | null, platform?: NodeJS.Platform): T;
+/** Adds the explicit pre-execution escape request to Pi's native Bash tool. */
+export declare function withWorkspaceWriteScope<T>(tool: T, note?: string): T;
+export {};

package/dist/sdk/core/workspaceBashTool.js

@@ -0,0 +1,50 @@
+import { Type } from 'typebox';
+import { COMMAND_TIMEOUT_CEILING_SECONDS, COMMAND_TIMEOUT_MAX_SECONDS, DEFAULT_COMMAND_TIMEOUT_SECONDS, resolveCommandTimeout } from "./commandBudget.js";
+import { hostShell, shellLabel } from "./shell.js";
+import { runWithWorkspaceWriteScope } from "./workspaceSandbox.js";
+/** Quotes command text and escapes terminal control/format characters for approval details. */
+export function formatBashCommandForApproval(command) {
+    return JSON.stringify(command).replace(/[\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff]/gu, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+/**
+ * The `bash` tool for this machine. The capability keeps the name `bash` on every platform; on a
+ * Windows machine without Git Bash it runs PowerShell and carries PowerShell's description.
+ */
+export function createWorkspaceShellTool(pi, cwd, operations, shell = hostShell(), platform = process.platform) {
+    const native = shell?.kind === 'powershell'
+        ? { ...pi.createPowerShellTool(cwd, { operations }), name: 'bash' }
+        : pi.createBashTool(cwd, { operations });
+    const note = platform === 'win32' && shell
+        ? ` On this machine commands run in ${shellLabel(shell)}. Windows has no workspace sandbox, so each command asks for approval unless Full Permission is on, and plan mode cannot run commands.`
+        : '';
+    return withWorkspaceWriteScope(native, note);
+}
+/** Adds the explicit pre-execution escape request to Pi's native Bash tool. */
+export function withWorkspaceWriteScope(tool, note = '') {
+    const native = tool;
+    const execute = native.execute.bind(tool);
+    return {
+        ...tool,
+        description: `${native.description}${note} Workspace writes are the default. Set workspaceWriteScope to "outside" to request approval before broader writes. Commands run for ${DEFAULT_COMMAND_TIMEOUT_SECONDS} seconds unless timeout says otherwise; above ${COMMAND_TIMEOUT_CEILING_SECONDS} seconds a reason is required, and ${COMMAND_TIMEOUT_MAX_SECONDS} seconds is the maximum.`,
+        parameters: Type.Object({
+            command: Type.String({ description: 'Shell command to execute' }),
+            timeout: Type.Optional(Type.Number({ description: `Timeout in seconds (default ${DEFAULT_COMMAND_TIMEOUT_SECONDS})` })),
+            reason: Type.Optional(Type.String({ description: `Why a command needs more than ${COMMAND_TIMEOUT_CEILING_SECONDS} seconds` })),
+            workspaceWriteScope: Type.Optional(Type.Union([
+                Type.Literal('workspace'),
+                Type.Literal('outside')
+            ], { description: 'Write scope for this command. Defaults to workspace; outside requests approval before running.' }))
+        }),
+        execute: (...args) => {
+            const input = args[1];
+            const scope = input?.workspaceWriteScope === 'outside' ? 'outside' : 'workspace';
+            const budget = resolveCommandTimeout(input?.timeout, input?.reason);
+            if (!budget.ok)
+                return { content: [{ type: 'text', text: budget.message }], details: { refused: true } };
+            // The native tool reads the timeout from its own arguments; give it the effective one.
+            const callArgs = [...args];
+            callArgs[1] = { ...(input ?? {}), timeout: budget.timeout };
+            return runWithWorkspaceWriteScope(scope, () => execute(...callArgs));
+        }
+    };
+}

package/dist/sdk/core/workspaceSandbox.d.ts

@@ -0,0 +1,41 @@
+import type { BashOperations } from '@earendil-works/pi-coding-agent';
+import { type Shell } from "./shell.js";
+/** `read-only` (plan mode) permits no workspace writes, no network and no outside processes. */
+export type WorkspaceWriteScope = 'workspace' | 'outside' | 'read-only';
+export declare function runWithWorkspaceWriteScope<T>(scope: WorkspaceWriteScope, action: () => T): T;
+export interface WorkspaceWriteScopeRequest {
+    command: string;
+    cwd: string;
+    workspaceRoot: string;
+    reason: string;
+}
+export interface WorkspaceBoundaryBypassRequest {
+    command: string;
+    cwd: string;
+    workspaceRoot: string;
+}
+export interface WorkspaceBashOptions {
+    /** The explicit Full Permission switch can bypass the workspace boundary before the command runs. */
+    bypassWorkspaceBoundary?: (request: WorkspaceBoundaryBypassRequest) => Promise<boolean>;
+    requestWorkspaceWriteScope?: (request: WorkspaceWriteScopeRequest) => Promise<boolean>;
+    /** Overrides the per-call scope; `undefined` falls back to it. */
+    workspaceWriteScope?: () => WorkspaceWriteScope | undefined;
+    /** Exposed for platform-specific tests; production uses the current operating system. */
+    platform?: NodeJS.Platform;
+    /** Exposed for tests; production uses the machine's shell (`hostShell`). */
+    shell?: () => Shell | null;
+}
+/** Why a Windows command asks first: Windows has no write-boundary sandbox the harness can use. */
+export declare const WINDOWS_UNSANDBOXED_REASON = "Windows has no workspace write-boundary sandbox, so this command would run without one. It will not run until this one-call request is approved.";
+export interface WorkspaceSandboxCommand {
+    executable: string;
+    args: string[];
+    marker: string;
+}
+/**
+ * The operating system's write-boundary sandbox for this platform, or null when it is not
+ * installed. Bash cannot run without it, so readiness diagnostics report it before a command runs.
+ */
+export declare function workspaceSandboxBackend(platform?: NodeJS.Platform): string | null;
+export declare function workspaceSandboxCommand(platform: NodeJS.Platform, workspaceRoot: string, cwd: string, command: string, additionalWriteRoots?: readonly string[], readOnlyTempRoot?: string | null): WorkspaceSandboxCommand;
+export declare function createWorkspaceBashOperations(workspaceRoot: string | (() => string | null), options?: WorkspaceBashOptions): BashOperations;

package/dist/sdk/core/workspaceSandbox.js

@@ -0,0 +1,360 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { accessSync, constants, existsSync, lstatSync, mkdtempSync, realpathSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { hostShell, shellArguments } from "./shell.js";
+import { isWithinWorkspace, verifyWorkspaceRoot } from "./workspace.js";
+const MARKER_PREFIX = '__XINGULAR_WORKSPACE_SANDBOX_STARTED_';
+const bashWriteScope = new AsyncLocalStorage();
+export function runWithWorkspaceWriteScope(scope, action) {
+    return bashWriteScope.run(scope, action);
+}
+/** Why a Windows command asks first: Windows has no write-boundary sandbox the harness can use. */
+export const WINDOWS_UNSANDBOXED_REASON = 'Windows has no workspace write-boundary sandbox, so this command would run without one. It will not run until this one-call request is approved.';
+const SANDBOX_BACKENDS = {
+    darwin: ['/usr/bin/sandbox-exec'],
+    linux: ['/usr/bin/bwrap', '/bin/bwrap']
+};
+/**
+ * The operating system's write-boundary sandbox for this platform, or null when it is not
+ * installed. Bash cannot run without it, so readiness diagnostics report it before a command runs.
+ */
+export function workspaceSandboxBackend(platform = process.platform) {
+    const candidates = SANDBOX_BACKENDS[platform];
+    return candidates ? systemExecutable(candidates) : null;
+}
+function systemExecutable(candidates) {
+    for (const candidate of candidates) {
+        try {
+            accessSync(candidate, constants.X_OK);
+            if (statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            // Keep looking only at known system locations.
+        }
+    }
+    return null;
+}
+function shellPath() {
+    const shell = ['/bin/bash', '/usr/bin/bash'].find((candidate) => existsSync(candidate));
+    if (!shell)
+        throw new Error('The workspace write-boundary sandbox requires Bash, but no Bash executable was found.');
+    return shell;
+}
+function requireShell(resolve) {
+    const shell = resolve();
+    if (!shell) {
+        throw new Error(process.platform === 'win32'
+            ? 'No shell was found: neither Git Bash nor PowerShell is available. Bash was not run.'
+            : 'No Bash executable was found. Bash was not run.');
+    }
+    return shell;
+}
+function unconfinedCommand(shell, command) {
+    return { executable: shell.executable, args: shellArguments(shell, command), marker: '' };
+}
+function sbplString(value) {
+    return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n')}"`;
+}
+// Read-only commands need no mach services; denying them all keeps a command from acting through
+// system daemons (preferences, Apple Events, Launch Services), which the file rules do not cover.
+function macReadOnlyProfile(tempRoot) {
+    return [
+        '(version 1)',
+        '(deny default)',
+        '(allow file-read*)',
+        `(allow file-write* (subpath ${sbplString(tempRoot)}))`,
+        '(allow file-write* (literal "/dev/null"))',
+        '(allow file-write* (literal "/dev/tty"))',
+        '(deny file-link)',
+        '(allow process-fork)',
+        '(allow process-exec)',
+        '(allow signal (target same-sandbox))',
+        '(allow sysctl-read)'
+    ].join('');
+}
+function macSandboxProfile(writeRoots) {
+    return [
+        '(version 1)',
+        '(deny default)',
+        '(allow file-read*)',
+        ...writeRoots.map((root) => `(allow file-write* (subpath ${sbplString(root)}))`),
+        '(allow file-write* (literal "/dev/null"))',
+        '(allow file-write* (literal "/dev/tty"))',
+        '(deny file-link)',
+        '(allow process*)',
+        '(allow network*)',
+        '(allow sysctl-read)',
+        '(allow mach-lookup)'
+    ].join('');
+}
+export function workspaceSandboxCommand(platform, workspaceRoot, cwd, command, additionalWriteRoots = [], readOnlyTempRoot = null) {
+    const shell = shellPath();
+    const marker = `${MARKER_PREFIX}${randomUUID()}__`;
+    const wrappedCommand = `printf '%s\\n' '${marker}'\n${command}`;
+    if (readOnlyTempRoot !== null)
+        return readOnlySandboxCommand(platform, realpathSync(readOnlyTempRoot), cwd, shell, wrappedCommand, marker);
+    const writeRoots = [...new Set([workspaceRoot, ...additionalWriteRoots].map((root) => realpathSync(root)))].sort((left, right) => left.length - right.length);
+    if (platform === 'darwin') {
+        const executable = workspaceSandboxBackend(platform);
+        if (!executable)
+            throw new Error('Workspace write-boundary sandbox unavailable: sandbox-exec was not found. Bash was not run.');
+        return { executable, args: ['-p', macSandboxProfile(writeRoots), shell, '-c', wrappedCommand], marker };
+    }
+    if (platform === 'linux') {
+        const executable = workspaceSandboxBackend(platform);
+        if (!executable)
+            throw new Error('Workspace write-boundary sandbox unavailable: install bubblewrap (bwrap). Bash was not run.');
+        return {
+            executable,
+            marker,
+            args: [
+                '--die-with-parent', '--new-session', '--unshare-pid',
+                '--ro-bind', '/', '/',
+                '--dev', '/dev',
+                '--proc', '/proc',
+                ...writeRoots.flatMap((root) => ['--bind', root, root]),
+                '--chdir', cwd,
+                shell, '-c', wrappedCommand
+            ]
+        };
+    }
+    throw new Error(`Workspace write-boundary sandbox unavailable on ${platform}. Bash was not run.`);
+}
+function readOnlySandboxCommand(platform, tempRoot, cwd, shell, wrappedCommand, marker) {
+    if (platform === 'darwin') {
+        const executable = workspaceSandboxBackend(platform);
+        if (!executable)
+            throw new Error('Read-only Bash sandbox unavailable: sandbox-exec was not found. Bash was not run.');
+        return { executable, args: ['-p', macReadOnlyProfile(tempRoot), shell, '-c', wrappedCommand], marker };
+    }
+    if (platform === 'linux') {
+        const executable = workspaceSandboxBackend(platform);
+        if (!executable)
+            throw new Error('Read-only Bash sandbox unavailable: install bubblewrap (bwrap). Bash was not run.');
+        return {
+            executable,
+            marker,
+            args: [
+                '--die-with-parent', '--new-session', '--unshare-pid', '--unshare-net', '--unshare-ipc',
+                '--ro-bind', '/', '/',
+                '--dev', '/dev',
+                '--proc', '/proc',
+                // No session bus or other host sockets under /run.
+                '--tmpfs', '/run',
+                '--bind', tempRoot, tempRoot,
+                '--chdir', cwd,
+                shell, '-c', wrappedCommand
+            ]
+        };
+    }
+    throw new Error(`Read-only Bash sandbox unavailable on ${platform}. Bash was not run.`);
+}
+function killProcess(child) {
+    if (child.pid && process.platform === 'win32') {
+        // Git Bash and PowerShell start their own children; end the whole tree.
+        spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+        return;
+    }
+    if (child.pid) {
+        try {
+            process.kill(-child.pid, 'SIGKILL');
+            return;
+        }
+        catch {
+            // Fall back to the direct child if it has already left its process group.
+        }
+    }
+    child.kill('SIGKILL');
+}
+function runProcess(spec, cwd, options, marker) {
+    if (options.signal?.aborted)
+        return Promise.reject(new Error('aborted'));
+    return new Promise((resolve, reject) => {
+        const child = spawn(spec.executable, spec.args, {
+            cwd,
+            detached: process.platform !== 'win32',
+            env: options.env ?? process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true
+        });
+        let pending = '';
+        let started = marker === null;
+        let timedOut = false;
+        let settled = false;
+        let timeoutHandle;
+        const deliver = (chunk) => {
+            const text = chunk.toString('utf8');
+            if (!started && marker) {
+                pending += text;
+                const markerAt = pending.indexOf(marker);
+                if (markerAt === -1) {
+                    // Preserve only a short prefix in case the shell emitted a startup warning.
+                    if (pending.length > marker.length + 2048) {
+                        options.onData(Buffer.from(pending.slice(0, pending.length - marker.length - 2048)));
+                        pending = pending.slice(-(marker.length + 2048));
+                    }
+                    return;
+                }
+                const before = pending.slice(0, markerAt);
+                const after = pending.slice(markerAt + marker.length).replace(/^\r?\n/u, '');
+                if (before)
+                    options.onData(Buffer.from(before));
+                if (after)
+                    options.onData(Buffer.from(after));
+                pending = '';
+                started = true;
+                return;
+            }
+            options.onData(chunk);
+        };
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            options.signal?.removeEventListener('abort', onAbort);
+            if (!started && pending)
+                options.onData(Buffer.from(pending));
+            if (options.signal?.aborted)
+                reject(new Error('aborted'));
+            else if (timedOut)
+                reject(new Error(`timeout:${options.timeout}`));
+            else
+                resolve({ exitCode: code });
+        };
+        const onAbort = () => killProcess(child);
+        if (options.timeout !== undefined && options.timeout > 0) {
+            timeoutHandle = setTimeout(() => {
+                timedOut = true;
+                killProcess(child);
+            }, options.timeout * 1000);
+        }
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        child.stdout?.on('data', deliver);
+        child.stderr?.on('data', deliver);
+        child.once('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            options.signal?.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+        child.once('close', finish);
+    });
+}
+function assertNoExternalHardlinks(workspaceRoot) {
+    const inodes = new Map();
+    const visit = (directory) => {
+        let entries;
+        try {
+            entries = readdirSync(directory, { withFileTypes: true });
+        }
+        catch (error) {
+            throw new Error(`Workspace hard-link inspection failed at ${directory}; Bash was not run: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        for (const entry of entries) {
+            const path = `${directory}/${entry.name}`;
+            let stats;
+            try {
+                stats = lstatSync(path);
+            }
+            catch (error) {
+                throw new Error(`Workspace hard-link inspection failed at ${path}; Bash was not run: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (stats.isSymbolicLink())
+                continue;
+            if (stats.isDirectory()) {
+                visit(path);
+                continue;
+            }
+            if (!stats.isFile())
+                continue;
+            const key = `${stats.dev}:${stats.ino}`;
+            const inode = inodes.get(key);
+            if (inode)
+                inode.internalLinks += 1;
+            else
+                inodes.set(key, { internalLinks: 1, totalLinks: stats.nlink, samplePath: path });
+        }
+    };
+    visit(workspaceRoot);
+    for (const inode of inodes.values()) {
+        if (inode.totalLinks > inode.internalLinks) {
+            throw new Error(`Workspace write-boundary sandbox cannot safely run Bash because ${inode.samplePath} has a hard-link alias outside the workspace; remove the alias or replace the file with a copy.`);
+        }
+    }
+}
+export function createWorkspaceBashOperations(workspaceRoot, options = {}) {
+    return {
+        async exec(command, cwd, execOptions) {
+            const rootValue = typeof workspaceRoot === 'function' ? workspaceRoot() : workspaceRoot;
+            if (!rootValue)
+                throw new Error('The active project workspace is not available. Bash was not run.');
+            const root = verifyWorkspaceRoot(rootValue);
+            const canonicalCwd = realpathSync(cwd);
+            if (!isWithinWorkspace(root, canonicalCwd))
+                throw new Error('The Bash working directory is outside the active project workspace.');
+            const scope = options.workspaceWriteScope?.() ?? bashWriteScope.getStore() ?? 'workspace';
+            const platform = options.platform ?? process.platform;
+            const shell = options.shell ?? hostShell;
+            // Nothing widens a read-only scope: no Full Permission bypass, no outside request.
+            if (scope === 'read-only') {
+                if (platform === 'win32')
+                    throw new Error('Plan-mode Bash needs a read-only sandbox, which Windows does not have. Bash was not run.');
+                const tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'harness-read-only-bash-')));
+                try {
+                    const spec = workspaceSandboxCommand(platform, root, canonicalCwd, command, [], tempRoot);
+                    const env = { ...(execOptions.env ?? process.env), TMPDIR: tempRoot };
+                    const result = await runProcess(spec, canonicalCwd, { ...execOptions, env }, spec.marker);
+                    return { exitCode: result.exitCode };
+                }
+                finally {
+                    rmSync(tempRoot, { recursive: true, force: true });
+                }
+            }
+            let bypass = false;
+            try {
+                bypass = await options.bypassWorkspaceBoundary?.({ command, cwd: canonicalCwd, workspaceRoot: root }) ?? false;
+            }
+            catch {
+                bypass = false;
+            }
+            if (bypass) {
+                const result = await runProcess(unconfinedCommand(requireShell(shell), command), canonicalCwd, execOptions, null);
+                return { exitCode: result.exitCode };
+            }
+            // Without a sandbox every Windows command is an outside request: a person approves it once.
+            if (scope === 'outside' || platform === 'win32') {
+                const resolved = requireShell(shell);
+                const reason = scope === 'outside'
+                    ? 'This command requests filesystem writes outside the active project workspace. It will not run until this one-call request is approved.'
+                    : WINDOWS_UNSANDBOXED_REASON;
+                let approved = false;
+                try {
+                    approved = await options.requestWorkspaceWriteScope?.({ command, cwd: canonicalCwd, workspaceRoot: root, reason }) ?? false;
+                }
+                catch {
+                    approved = false;
+                }
+                if (!approved)
+                    throw new Error(`${reason} Bash was not run.`);
+                if (scope === 'outside')
+                    execOptions.onData(Buffer.from('\n[Outside-workspace writes approved for this command; running once.]\n'));
+                const result = await runProcess(unconfinedCommand(resolved, command), canonicalCwd, execOptions, null);
+                return { exitCode: result.exitCode };
+            }
+            assertNoExternalHardlinks(root);
+            const spec = workspaceSandboxCommand(platform, root, canonicalCwd, command);
+            const result = await runProcess(spec, canonicalCwd, execOptions, spec.marker);
+            return { exitCode: result.exitCode };
+        }
+    };
+}