@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/core/interactiveProfile.js

@@ -0,0 +1,143 @@
+import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileSecretStore } from "../accounts/secrets.js";
+const fail = () => { throw new Error('Invalid interactive profile configuration.'); };
+const object = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return fail();
+    return value;
+};
+const keys = (value, expected) => {
+    if (Object.keys(value).length !== expected.length || expected.some(key => !Object.hasOwn(value, key)))
+        fail();
+};
+const absolute = (value) => {
+    if (typeof value !== 'string' || value.length > 4096 || value.includes('\0') || !isAbsolute(value))
+        return fail();
+    return value;
+};
+const identifier = (value) => {
+    if (typeof value !== 'string' || value.length > 128 || !/^[A-Za-z0-9_-]+$/.test(value))
+        return fail();
+    return value;
+};
+/** Strict, bounded, credential-free configuration. Unknown fields are errors, not ignored secrets. */
+export function validateInteractiveProfile(value) {
+    const record = object(value);
+    keys(record, ['version', 'dataRoot', 'stateDir', 'defaultVariantScope', 'secretBackend']);
+    if (record.version !== 1)
+        return fail();
+    const backend = object(record.secretBackend);
+    let secretBackend;
+    if (backend.kind === 'file') {
+        keys(backend, ['kind', 'path']);
+        secretBackend = { kind: 'file', path: absolute(backend.path) };
+    }
+    else if (backend.kind === 'host') {
+        keys(backend, ['kind', 'id']);
+        secretBackend = { kind: 'host', id: identifier(backend.id) };
+    }
+    else
+        return fail();
+    return {
+        version: 1,
+        dataRoot: absolute(record.dataRoot),
+        stateDir: absolute(record.stateDir),
+        defaultVariantScope: identifier(record.defaultVariantScope),
+        secretBackend
+    };
+}
+export function interactiveProfilePath(home = homedir()) {
+    return join(absolute(home), '.xingular-harness', 'profile.json');
+}
+function selectedConfigPath(location = {}) {
+    return location.configPath === undefined ? interactiveProfilePath(location.home) : absolute(location.configPath);
+}
+/** Read only. Missing is legacy mode; malformed or inaccessible is never silently ignored. */
+export function readInteractiveProfile(location = {}) {
+    const path = selectedConfigPath(location);
+    try {
+        const info = statSync(path);
+        if (!info.isFile() || info.size > 16_384)
+            return fail();
+        return validateInteractiveProfile(JSON.parse(readFileSync(path, 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        // Do not include JSON contents, paths, or backend details in diagnostics.
+        throw new Error('Interactive profile could not be read or validated.');
+    }
+}
+function overrides(value) {
+    if (value === undefined)
+        return {};
+    const record = object(value);
+    if (Object.keys(record).some(key => !['dataRoot', 'stateDir', 'defaultVariantScope', 'secretBackend'].includes(key)))
+        return fail();
+    return record;
+}
+/** Explicit roots > selected profile > caller's legacy defaults. Never creates roots or merges data. */
+export function resolveInteractiveProfile(options = {}) {
+    const home = absolute(options.home ?? homedir());
+    const root = join(home, '.xingular-harness');
+    const selected = readInteractiveProfile(options);
+    const legacy = overrides(options.legacyDefaults);
+    const explicit = overrides(options.overrides);
+    const dataRoot = explicit.dataRoot ?? selected?.dataRoot ?? legacy.dataRoot ?? join(root, 'data');
+    const stateDir = explicit.stateDir ?? selected?.stateDir ?? legacy.stateDir ?? join(root, 'state');
+    const defaultVariantScope = explicit.defaultVariantScope ?? selected?.defaultVariantScope ?? legacy.defaultVariantScope ?? 'default';
+    const secretBackend = explicit.secretBackend ?? selected?.secretBackend ?? legacy.secretBackend ?? {
+        kind: 'file',
+        path: join(stateDir, 'secrets.json')
+    };
+    return validateInteractiveProfile({ version: 1, dataRoot, stateDir, defaultVariantScope, secretBackend });
+}
+/**
+ * Explicit adoption only. Creates the profile file, never roots or credentials; it never replaces
+ * an existing profile or merges data. A pre-profile host must supply its selected backend in
+ * `legacyDefaults` so an absent profile cannot silently downgrade it to the file store.
+ */
+export function adoptInteractiveProfile(profile, location = {}) {
+    const validated = validateInteractiveProfile(profile);
+    const path = selectedConfigPath(location);
+    const folder = dirname(path);
+    mkdirSync(folder, { recursive: true, mode: 0o700 });
+    const temporary = join(folder, `.profile-${randomUUID()}.tmp`);
+    try {
+        const fd = openSync(temporary, 'wx', 0o600);
+        try {
+            writeFileSync(fd, `${JSON.stringify(validated, null, 2)}\n`);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        linkSync(temporary, path);
+    }
+    catch {
+        throw new Error('Interactive profile adoption failed; existing configuration was not replaced.');
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/**
+ * Every participating process must map this host id to the same credential store. The account
+ * lock serializes access but cannot unify distinct native Keychain identities; no file fallback is
+ * allowed when a selected host adapter is unavailable.
+ */
+export async function interactiveProfileSecretStore(profile, host) {
+    const { secretBackend } = validateInteractiveProfile(profile);
+    if (secretBackend.kind === 'file')
+        return fileSecretStore(secretBackend.path);
+    if (!host)
+        throw new Error('The selected credential backend is unavailable; supply its host SecretStore adapter.');
+    const store = await host(secretBackend);
+    if (!store || !['get', 'set', 'delete'].every(key => typeof store[key] === 'function')) {
+        throw new Error('The selected credential backend did not provide a SecretStore.');
+    }
+    return store;
+}

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,4 @@
+/** Quotes command text and escapes terminal control/format characters for approval details. */
+export declare function formatBashCommandForApproval(command: string): string;
+/** Adds the explicit pre-execution escape request to Pi's native Bash tool. */
+export declare function withWorkspaceWriteScope<T>(tool: T): T;

package/dist/sdk/core/workspaceBashTool.js

@@ -0,0 +1,36 @@
+import { Type } from 'typebox';
+import { COMMAND_TIMEOUT_CEILING_SECONDS, COMMAND_TIMEOUT_MAX_SECONDS, DEFAULT_COMMAND_TIMEOUT_SECONDS, resolveCommandTimeout } from "./commandBudget.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')}`);
+}
+/** Adds the explicit pre-execution escape request to Pi's native Bash tool. */
+export function withWorkspaceWriteScope(tool) {
+    const native = tool;
+    const execute = native.execute.bind(tool);
+    return {
+        ...tool,
+        description: `${native.description} 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,31 @@
+import type { BashOperations } from '@earendil-works/pi-coding-agent';
+/** `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;
+}
+export interface WorkspaceSandboxCommand {
+    executable: string;
+    args: string[];
+    marker: string;
+}
+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,320 @@
+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 { 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);
+}
+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 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 = systemExecutable(['/usr/bin/sandbox-exec']);
+        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 = systemExecutable(['/usr/bin/bwrap', '/bin/bwrap']);
+        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 = systemExecutable(['/usr/bin/sandbox-exec']);
+        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 = systemExecutable(['/usr/bin/bwrap', '/bin/bwrap']);
+        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') {
+        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';
+            // Nothing widens a read-only scope: no Full Permission bypass, no outside request.
+            if (scope === 'read-only') {
+                const platform = options.platform ?? process.platform;
+                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({ executable: shellPath(), args: ['-c', command], marker: '' }, canonicalCwd, execOptions, null);
+                return { exitCode: result.exitCode };
+            }
+            if (scope === 'outside') {
+                const reason = 'This command requests filesystem writes outside the active project workspace. It will not run until this one-call request is approved.';
+                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.`);
+                execOptions.onData(Buffer.from('\n[Outside-workspace writes approved for this command; running once.]\n'));
+                const result = await runProcess({ executable: shellPath(), args: ['-c', command], marker: '' }, canonicalCwd, execOptions, null);
+                return { exitCode: result.exitCode };
+            }
+            assertNoExternalHardlinks(root);
+            const platform = options.platform ?? process.platform;
+            const spec = workspaceSandboxCommand(platform, root, canonicalCwd, command);
+            const result = await runProcess(spec, canonicalCwd, execOptions, spec.marker);
+            return { exitCode: result.exitCode };
+        }
+    };
+}

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

@@ -0,0 +1,22 @@
+export interface WorkspaceWriteAuthorization {
+    workspaceRoot: string;
+    cwd: string;
+    path: string;
+    outside: boolean;
+    authorized: boolean;
+    expectedContentHash?: string;
+    signal?: AbortSignal;
+}
+declare function writeWorkspaceFile(path: string, content: string): Promise<void>;
+export declare const workspaceWriteOperations: {
+    mkdir: (_directory: string) => Promise<void>;
+    writeFile: typeof writeWorkspaceFile;
+};
+export declare const workspaceEditOperations: {
+    access: (path: string) => Promise<void>;
+    readFile: (path: string) => Promise<Buffer>;
+    writeFile: typeof writeWorkspaceFile;
+};
+/** Binds one policy-approved path and abort signal to Pi's native write/edit operation. */
+export declare function withWorkspaceWriteAuthorization<T>(tool: T, authorizations: Map<string, WorkspaceWriteAuthorization>): T;
+export {};