@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.4-dev.1ff37038366e

package/dist/runtime/attempt-database-broker.js

@@ -0,0 +1,390 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * The managed host attempt's database capability. The Bridge keeps the test cluster's
+ * administrator credential; an attempt (its agent, its application runtime and its tests)
+ * receives only a login for one database created for it. Forge.Api checks that login before it
+ * migrates (AttemptScopedDatabasePolicy.AssertBrokeredCapabilityAsync), but that check runs in
+ * attempt code: the boundary is what this broker issues and the cluster's pg_hba rules, which
+ * let an attempt role log in only to its own database.
+ */
+export const attemptDatabaseCapabilityEnvironment = "FORGE_ATTEMPT_DATABASE_CAPABILITY";
+export class AttemptDatabaseBrokerError extends Error {
+    code;
+    constructor(code, detail) {
+        super(`${code}: ${detail}`);
+        this.code = code;
+        this.name = "AttemptDatabaseBrokerError";
+    }
+}
+const markerVersion = "broker-v1";
+const attemptNamePattern = /^forge_attempt_[0-9a-f]{32}$/u;
+const template1BusyPattern = /source database "template1" is being accessed by other users/u;
+const hbaRejectPattern = /pg_hba\.conf rejects connection|no pg_hba\.conf entry/u;
+// Three attempts at this limit stay well under the cluster's 200 connections, leaving room for
+// the administrator; the issued pool stays below it.
+const attemptConnectionLimit = 40;
+const attemptPoolSize = 20;
+/**
+ * The ownership marker on the attempt's role. Only a role with CREATEROLE can change a role's
+ * comment, so the attempt cannot forge or erase it (it can rewrite its database's comment, which
+ * is therefore informational). Must match AttemptScopedDatabasePolicy.BrokeredRoleMarkerPrefix.
+ */
+export function brokeredDatabaseMarker(dispatchAttemptId, fencingToken, owner) {
+    return `${brokeredMarkerPrefix(dispatchAttemptId, fencingToken)}owner=${owner}`;
+}
+function brokeredMarkerPrefix(dispatchAttemptId, fencingToken) {
+    const name = attemptDatabaseName(dispatchAttemptId);
+    return `forge_attempt_database:${markerVersion};id=${hex(dispatchAttemptId)};fence=${hex(fencingToken)};database=${name};`;
+}
+export function attemptDatabaseName(dispatchAttemptId) {
+    return `forge_attempt_${hex(dispatchAttemptId)}`;
+}
+/** Identifies one Bridge's broker on a shared cluster, so it reaps only databases it issued. */
+export function attemptDatabaseBrokerOwner(stateRoot) {
+    return createHash("sha256").update(path.resolve(stateRoot).toLowerCase()).digest("hex").slice(0, 16);
+}
+/**
+ * Brokers attempt databases on the dedicated native test cluster that
+ * scripts/setup-native-test-postgres.ps1 provisions. That cluster holds only disposable test
+ * databases, so even a leaked attempt capability cannot reach developer data. Each attempt
+ * gets a login role and a database it owns, cloned from template1 (which carries pgvector,
+ * an extension an unprivileged owner cannot create).
+ */
+export class NativeTestClusterDatabaseBroker {
+    admin;
+    runSql;
+    owner;
+    delay;
+    /** Names being provisioned right now; the reaper leaves them alone. */
+    provisioning = new Set();
+    constructor(admin, runSql, owner, delay = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds))) {
+        this.admin = admin;
+        this.runSql = runSql;
+        this.owner = owner;
+        this.delay = delay;
+        if (!/^[0-9a-f]{16}$/u.test(owner)) {
+            throw new AttemptDatabaseBrokerError("attempt_database_broker_invalid", "the broker owner must be 16 hex characters.");
+        }
+    }
+    async provision(dispatchAttemptId, fencingToken, signal) {
+        const name = attemptDatabaseName(dispatchAttemptId);
+        const marker = brokeredDatabaseMarker(dispatchAttemptId, fencingToken, this.owner);
+        this.provisioning.add(name);
+        const password = randomBytes(24).toString("hex");
+        try {
+            const state = await this.state(name, signal);
+            if (state.roleMarker !== null && state.roleMarker !== marker) {
+                throw new AttemptDatabaseBrokerError("attempt_database_not_owned", `role ${name} exists without this attempt's broker marker and was left untouched.`);
+            }
+            if (state.databaseOwner !== null && (state.roleMarker === null || state.databaseOwner !== name)) {
+                throw new AttemptDatabaseBrokerError("attempt_database_not_owned", `database ${name} is not owned by this attempt's broker role and was left untouched.`);
+            }
+            // One transaction: an interrupted run leaves either no role or a marked one.
+            await this.runSql([
+                "BEGIN;",
+                ...(state.roleMarker === null
+                    ? [
+                        `CREATE ROLE ${ident(name)} LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS NOINHERIT CONNECTION LIMIT ${attemptConnectionLimit} PASSWORD ${literal(password)};`,
+                        `COMMENT ON ROLE ${ident(name)} IS ${literal(marker)};`,
+                        // Lets the administrator create, and later drop, a database the attempt role owns.
+                        `GRANT ${ident(name)} TO CURRENT_USER;`,
+                    ]
+                    : [`ALTER ROLE ${ident(name)} LOGIN PASSWORD ${literal(password)};`]),
+                "COMMIT;",
+            ].join("\n"), signal);
+            if (state.databaseOwner === null)
+                await this.createDatabase(name, signal);
+            // Idempotent, so a retry after an interrupted provision converges.
+            await this.runSql([
+                `COMMENT ON DATABASE ${ident(name)} IS ${literal(marker)};`,
+                `REVOKE ALL ON DATABASE ${ident(name)} FROM PUBLIC;`,
+                `GRANT CONNECT, TEMPORARY ON DATABASE ${ident(name)} TO ${ident(name)};`,
+            ].join("\n"), signal);
+            await this.assertConfinedToOwnDatabase(name, password, signal);
+            return {
+                databaseName: name,
+                connectionString: [
+                    `Host=${this.admin.host}`,
+                    `Port=${this.admin.port}`,
+                    `Database=${name}`,
+                    `Username=${name}`,
+                    `Password=${password}`,
+                    "Timeout=15",
+                    "Command Timeout=60",
+                    `Maximum Pool Size=${attemptPoolSize}`,
+                ].join(";"),
+            };
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                error.message = error.message.replaceAll(password, "[redacted]");
+                if (error.stack)
+                    error.stack = error.stack.replaceAll(password, "[redacted]");
+            }
+            throw error;
+        }
+        finally {
+            this.provisioning.delete(name);
+        }
+    }
+    async release(dispatchAttemptId, fencingToken) {
+        const name = attemptDatabaseName(dispatchAttemptId);
+        const state = await this.state(name);
+        if (state.roleMarker === null && state.databaseOwner === null)
+            return "missing";
+        if (state.roleMarker !== brokeredDatabaseMarker(dispatchAttemptId, fencingToken, this.owner)
+            || (state.databaseOwner !== null && state.databaseOwner !== name)) {
+            throw new AttemptDatabaseBrokerError("attempt_database_not_owned", `${name} is not this attempt's broker database and was left untouched.`);
+        }
+        return await this.drop(name);
+    }
+    async reapOrphans(isLive) {
+        const rows = await this.runSql([
+            "SELECT r.rolname, COALESCE(shobj_description(r.oid, 'pg_authid'), '') FROM pg_roles r",
+            "WHERE r.rolname ~ '^forge_attempt_[0-9a-f]{32}$';",
+        ].join("\n"));
+        const dropped = [];
+        for (const line of rows.split(/\r?\n/u)) {
+            const separator = line.indexOf("|");
+            if (separator < 0)
+                continue;
+            const name = line.slice(0, separator);
+            const marker = line.slice(separator + 1);
+            if (!attemptNamePattern.test(name))
+                continue;
+            // Only this broker's exact-name role marker is ownership evidence; prefix matches are not.
+            const id = name.slice("forge_attempt_".length);
+            if (!new RegExp(`^forge_attempt_database:${markerVersion};id=${id};fence=[0-9a-f]{32};database=${name};owner=${this.owner}$`, "u")
+                .test(marker))
+                continue;
+            try {
+                const state = await this.state(name);
+                if (state.databaseOwner !== null && state.databaseOwner !== name)
+                    continue;
+                // Asked last, so an attempt admitted while the role list was read is still spared.
+                if (this.provisioning.has(name) || isLive(uuidFromHex(id)))
+                    continue;
+                if (await this.drop(name) === "dropped")
+                    dropped.push(name);
+            }
+            catch {
+                // One stuck name must not stop the rest of the reap; it is retried next time.
+            }
+        }
+        return dropped;
+    }
+    async state(name, signal) {
+        const output = await this.runSql([
+            `SELECT 'role', COALESCE(shobj_description(oid, 'pg_authid'), '') FROM pg_roles WHERE rolname = ${literal(name)}`,
+            "UNION ALL",
+            `SELECT 'database', pg_get_userbyid(datdba) FROM pg_database WHERE datname = ${literal(name)};`,
+        ].join("\n"), signal);
+        let roleMarker = null;
+        let databaseOwner = null;
+        for (const line of output.split(/\r?\n/u)) {
+            const separator = line.indexOf("|");
+            if (separator < 0)
+                continue;
+            const kind = line.slice(0, separator);
+            const value = line.slice(separator + 1);
+            if (kind === "role")
+                roleMarker = value;
+            if (kind === "database")
+                databaseOwner = value;
+        }
+        return { roleMarker, databaseOwner };
+    }
+    async createDatabase(name, signal) {
+        // CREATE DATABASE needs template1 to itself for a moment; .NET test fixtures on the same
+        // cluster can hold it briefly.
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await this.runSql(`CREATE DATABASE ${ident(name)} OWNER ${ident(name)} TEMPLATE template1;`, signal);
+                return;
+            }
+            catch (error) {
+                if (attempt >= 10 || !template1BusyPattern.test(String(error.message)))
+                    throw error;
+                signal?.throwIfAborted();
+                await this.delay(500 * attempt);
+            }
+        }
+    }
+    /** Fails closed unless the cluster lets this login reach its own database and nothing else. */
+    async assertConfinedToOwnDatabase(name, password, signal) {
+        const own = await this.runSql("SELECT current_user;", signal, { database: name, username: name, password });
+        if (own.trim() !== name) {
+            throw new AttemptDatabaseBrokerError("attempt_database_broker_failed", `${name} could not log in to its own database.`);
+        }
+        let confined = true;
+        // A database that cannot exist stands for every other name: pg_hba is checked before the
+        // database is looked up, so only a rule that rejects this role everywhere else rejects it.
+        const unmatched = `forge_confinement_probe_${randomBytes(8).toString("hex")}`;
+        for (const other of ["postgres", "template1", unmatched]) {
+            try {
+                await this.runSql("SELECT 1;", signal, { database: other, username: name, password });
+                confined = false;
+            }
+            catch (error) {
+                if (!hbaRejectPattern.test(String(error.message)))
+                    throw error;
+            }
+        }
+        if (confined)
+            return;
+        await this.drop(name).catch(() => "retained");
+        throw new AttemptDatabaseBrokerError("attempt_database_cluster_unrestricted", "the native test cluster lets attempt roles log in to other databases; run scripts/setup-native-test-postgres.ps1 -Action RestrictAttemptRoles.");
+    }
+    async drop(name) {
+        try {
+            await this.runSql([
+                // Refuse new logins first, so nothing reconnects between the terminate and the drop.
+                `ALTER ROLE ${ident(name)} NOLOGIN;`,
+                `SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = ${literal(name)} OR usename = ${literal(name)};`,
+                `DROP DATABASE IF EXISTS ${ident(name)} WITH (FORCE);`,
+                `DROP OWNED BY ${ident(name)};`,
+                `DROP ROLE IF EXISTS ${ident(name)};`,
+            ].join("\n"));
+            return "dropped";
+        }
+        catch {
+            return "retained";
+        }
+    }
+}
+export function nativeTestClusterAdmin(fallback) {
+    const fields = new Map();
+    for (const segment of fallback.connectionString.split(";")) {
+        const separator = segment.indexOf("=");
+        if (separator <= 0)
+            continue;
+        fields.set(segment.slice(0, separator).trim().toLowerCase().replaceAll(" ", ""), segment.slice(separator + 1).trim());
+    }
+    const separator = fallback.endpoint.lastIndexOf(":");
+    const host = fallback.endpoint.slice(0, separator).replace(/^\[(.*)\]$/u, "$1");
+    const port = Number.parseInt(fallback.endpoint.slice(separator + 1), 10);
+    const username = fields.get("username") ?? fields.get("userid") ?? fields.get("user") ?? "";
+    return { host, port, username, password: fields.get("password") ?? "" };
+}
+/** Runs SQL through the psql that ships with the PostgreSQL install hosting the native test cluster. */
+export function psqlSqlRunner(admin, psqlPath, timeoutMs = 120_000) {
+    return (sql, signal, login) => new Promise((resolve, reject) => {
+        const username = login?.username ?? admin.username;
+        const password = login?.password ?? admin.password;
+        const child = spawn(psqlPath, [
+            "-X", "-q", "-A", "-t", "-w",
+            "-v", "ON_ERROR_STOP=1",
+            "-h", admin.host,
+            "-p", String(admin.port),
+            "-U", username,
+            "-d", login?.database ?? "postgres",
+        ], {
+            // Only what psql needs: never the Bridge's own environment.
+            env: {
+                PGPASSWORD: password,
+                PGCONNECT_TIMEOUT: "10",
+                PGAPPNAME: "Forge.Bridge.AttemptDatabaseBroker",
+                ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}),
+                ...(process.env.PATH ? { PATH: process.env.PATH } : {}),
+            },
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+            signal,
+        });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => child.kill(), timeoutMs);
+        child.stdout.setEncoding("utf8").on("data", chunk => { stdout += chunk; });
+        child.stderr.setEncoding("utf8").on("data", chunk => { stderr += chunk; });
+        child.once("error", error => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.once("close", code => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve(stdout);
+            else
+                reject(new AttemptDatabaseBrokerError("attempt_database_broker_failed", stderr.trim().slice(-2_000).replaceAll(password, "[redacted]").replaceAll(admin.password, "[redacted]")
+                    || `psql exited with ${code}`));
+        });
+        child.stdin.end(sql);
+    });
+}
+/** psql beside the cluster's pg_ctl: FORGE_NATIVE_TEST_POSTGRES_PSQL, a Windows install, or PATH. */
+export function resolvePsqlPath() {
+    const configured = process.env.FORGE_NATIVE_TEST_POSTGRES_PSQL?.trim();
+    if (configured)
+        return fs.existsSync(configured) ? configured : null;
+    if (process.platform === "win32") {
+        const root = path.join(process.env.ProgramFiles ?? "C:\\Program Files", "PostgreSQL");
+        let versions;
+        try {
+            versions = fs.readdirSync(root).filter(entry => /^\d+$/u.test(entry));
+        }
+        catch {
+            return null;
+        }
+        for (const version of versions.sort((left, right) => Number(right) - Number(left))) {
+            const candidate = path.join(root, version, "bin", "psql.exe");
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        return null;
+    }
+    for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
+        const candidate = path.join(directory, "psql");
+        if (directory && fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * The broker for this host, or null when no native test cluster is provisioned. Without a
+ * broker, Forge.Api still refuses to start in a managed host attempt; other applications run.
+ */
+export function createNativeTestClusterDatabaseBroker(readFallback, stateRoot) {
+    let fallback;
+    try {
+        fallback = readFallback();
+    }
+    catch {
+        // An unsafe cluster file is reported by pre-publication validation; it is never brokered.
+        return null;
+    }
+    const psqlPath = fallback ? resolvePsqlPath() : null;
+    if (!fallback || !psqlPath)
+        return null;
+    const admin = nativeTestClusterAdmin(fallback);
+    return new NativeTestClusterDatabaseBroker(admin, psqlSqlRunner(admin, psqlPath), attemptDatabaseBrokerOwner(stateRoot));
+}
+/** The exact strings to redact wherever a capability may be printed: the whole value and its password. */
+export function attemptDatabaseCapabilitySecrets(capability) {
+    const value = capability?.trim();
+    if (!value)
+        return [];
+    const password = /(?:^|;)\s*Password\s*=\s*([^;]+)/iu.exec(value)?.[1]?.trim();
+    return password ? [value, password] : [value];
+}
+function uuidFromHex(value) {
+    return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`;
+}
+function hex(uuid) {
+    const value = uuid.trim().toLowerCase().replaceAll("-", "");
+    if (!/^[0-9a-f]{32}$/u.test(value)) {
+        throw new AttemptDatabaseBrokerError("attempt_database_broker_invalid", "attempt identifiers must be UUIDs.");
+    }
+    return value;
+}
+function ident(name) {
+    if (!attemptNamePattern.test(name)) {
+        throw new AttemptDatabaseBrokerError("attempt_database_broker_invalid", `${name} is not an attempt database name.`);
+    }
+    return `"${name}"`;
+}
+function literal(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}

package/dist/runtime/attempt-node-runtime-launcher.d.ts

@@ -0,0 +1,18 @@
+import type { AttemptProcessChildHandle, AttemptProcessSupervisor } from "./attempt-process-supervisor.js";
+import type { HostPortLeaseOwner } from "./host-port-broker.js";
+import { HostListenerInspector } from "./host-listener-inspector.js";
+import type { HostListenerOwnership, NodeRuntimeCommandLauncher, NodeRuntimeLaunchRequest, NodeRuntimeReadinessDiagnostics } from "./node-host-runtime-adapter.js";
+/** Launches one explicitly configured HTTP project beneath the attempt coordinator. */
+export declare class AttemptNodeRuntimeLauncher implements NodeRuntimeCommandLauncher<AttemptProcessChildHandle> {
+    private readonly supervisor;
+    private readonly owner;
+    private readonly logDirectory;
+    private readonly listenerInspector;
+    private readonly exactSecrets;
+    private readonly diagnosticsByChild;
+    constructor(supervisor: AttemptProcessSupervisor, owner: HostPortLeaseOwner, logDirectory: string, listenerInspector?: HostListenerInspector, exactSecrets?: readonly string[]);
+    launch(request: NodeRuntimeLaunchRequest, signal?: AbortSignal): Promise<AttemptProcessChildHandle>;
+    inspectListener(child: AttemptProcessChildHandle, request: NodeRuntimeLaunchRequest): Promise<HostListenerOwnership>;
+    stop(child: AttemptProcessChildHandle): Promise<void>;
+    readinessDiagnostics(child: AttemptProcessChildHandle): Promise<NodeRuntimeReadinessDiagnostics>;
+}

package/dist/runtime/attempt-node-runtime-launcher.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { redactText } from "../shared/redaction/redaction.js";
+import { ForgeFailureError, sanitizeFailureError } from "../session/session.types.js";
+import { HostListenerInspector } from "./host-listener-inspector.js";
+const diagnosticTailLength = 4_000;
+/** Launches one explicitly configured HTTP project beneath the attempt coordinator. */
+export class AttemptNodeRuntimeLauncher {
+    supervisor;
+    owner;
+    logDirectory;
+    listenerInspector;
+    exactSecrets;
+    diagnosticsByChild = new WeakMap();
+    constructor(supervisor, owner, logDirectory, listenerInspector = new HostListenerInspector(), exactSecrets = []) {
+        this.supervisor = supervisor;
+        this.owner = owner;
+        this.logDirectory = logDirectory;
+        this.listenerInspector = listenerInspector;
+        this.exactSecrets = exactSecrets;
+    }
+    async launch(request, signal) {
+        const childName = projectChildName(request.port.name);
+        const stdoutPath = path.join(this.logDirectory, `${childName}.stdout.log`);
+        const stderrPath = path.join(this.logDirectory, `${childName}.stderr.log`);
+        const diagnostics = { exited: false, stdoutTail: "", stderrTail: "", outputRevision: 0 };
+        let child;
+        try {
+            child = await this.supervisor.startChildReady(childName, {
+                command: request.command,
+                args: request.args,
+                cwd: request.cwd,
+                env: request.environment,
+                captureOutput: false,
+                failureRedactionValues: this.exactSecrets,
+            }, {
+                onStdoutLine: async (line) => {
+                    const redacted = redactText(line, this.exactSecrets);
+                    diagnostics.stdoutTail = appendTail(diagnostics.stdoutTail, redacted);
+                    diagnostics.outputRevision += 1;
+                    await appendLine(stdoutPath, redacted);
+                },
+                onStderrLine: async (line) => {
+                    const redacted = redactText(line, this.exactSecrets);
+                    diagnostics.stderrTail = appendTail(diagnostics.stderrTail, redacted);
+                    diagnostics.outputRevision += 1;
+                    await appendLine(stderrPath, redacted);
+                },
+            }, signal, { maxStartAttempts: 3, retryDelayMs: 250 });
+        }
+        catch (error) {
+            throw enrichLaunchFailure(error, diagnostics, this.exactSecrets);
+        }
+        const exposedChild = sanitizedChildHandle(child, this.exactSecrets);
+        this.diagnosticsByChild.set(exposedChild, diagnostics);
+        void exposedChild.result.then(result => {
+            diagnostics.exited = true;
+            diagnostics.exitCode = result.exitCode;
+            diagnostics.stdoutTail = appendTail(diagnostics.stdoutTail, result.stdout);
+            diagnostics.stderrTail = appendTail(diagnostics.stderrTail, result.stderr);
+            diagnostics.outputRevision += 1;
+        }, error => {
+            diagnostics.exited = true;
+            diagnostics.stderrTail = appendTail(diagnostics.stderrTail, redactText(error instanceof Error ? error.message : String(error), this.exactSecrets));
+            diagnostics.outputRevision += 1;
+        });
+        return exposedChild;
+    }
+    async inspectListener(child, request) {
+        return await this.listenerInspector.inspect(child, request.port, this.owner);
+    }
+    async stop(child) {
+        await child.stop(this.owner.fencingToken);
+    }
+    async readinessDiagnostics(child) {
+        // Yield once so an already-settled result can update the diagnostic record.
+        await Promise.resolve();
+        const diagnostics = this.diagnosticsByChild.get(child);
+        return diagnostics ?? { exited: false };
+    }
+}
+function projectChildName(portName) {
+    const candidate = `project-${portName}`;
+    if (/^[a-z][a-z0-9_-]{0,31}$/u.test(candidate))
+        return candidate;
+    const digest = createHash("sha256").update(portName).digest("hex").slice(0, 16);
+    return `project-${digest}`;
+}
+async function appendLine(target, line) {
+    await fs.appendFile(target, `${line}\n`, { encoding: "utf8", mode: 0o600 });
+}
+function appendTail(current, value) {
+    if (!value)
+        return current;
+    const combined = current ? `${current}\n${value}` : value;
+    return combined.slice(-diagnosticTailLength);
+}
+function enrichLaunchFailure(error, diagnostics, exactSecrets) {
+    const sanitized = sanitizeFailureError(error, exactSecrets);
+    const evidence = [
+        diagnostics.stderrTail ? `stderr tail: ${boundedDiagnostic(diagnostics.stderrTail)}` : "",
+        diagnostics.stdoutTail ? `stdout tail: ${boundedDiagnostic(diagnostics.stdoutTail)}` : "",
+    ].filter(Boolean);
+    if (evidence.length === 0)
+        return sanitized;
+    return replaceSanitizedErrorMessage(sanitized, `${sanitized.message} ${evidence.join("; ")}`);
+}
+function sanitizedChildHandle(child, exactSecrets) {
+    const sanitizeResult = (result) => ({
+        ...result,
+        stdout: redactText(result.stdout, exactSecrets),
+        stderr: redactText(result.stderr, exactSecrets),
+    });
+    const ready = child.ready.catch(error => { throw sanitizeFailureError(error, exactSecrets); });
+    const result = child.result.then(sanitizeResult, error => { throw sanitizeFailureError(error, exactSecrets); });
+    const stop = child.stop.bind(child);
+    Object.defineProperties(child, {
+        ready: { configurable: true, enumerable: true, value: ready },
+        result: { configurable: true, enumerable: true, value: result },
+        stop: { configurable: true, enumerable: true, value: async (fencingToken) => {
+                try {
+                    return sanitizeResult(await stop(fencingToken));
+                }
+                catch (error) {
+                    throw sanitizeFailureError(error, exactSecrets);
+                }
+            } },
+    });
+    return child;
+}
+function replaceSanitizedErrorMessage(error, message) {
+    const options = error.cause === undefined ? undefined : { cause: error.cause };
+    return error instanceof ForgeFailureError
+        ? new ForgeFailureError(error.failureCode, message, error.failureSource, options)
+        : new Error(message, options);
+}
+function boundedDiagnostic(value) {
+    return value.replaceAll(/[\r\n\t]+/gu, " ").trim().slice(-1_000);
+}

package/dist/runtime/attempt-path-operation.d.ts

@@ -0,0 +1,21 @@
+import type { BigIntStats } from "node:fs";
+/** A separate process pins cwd without changing the multithreaded Bridge's cwd.
+ * All writes use single relative components, never a re-resolved ancestor path.
+ */
+export declare function runAttemptPathOperation(parent: string, identity: BigIntStats, operation: {
+    kind: "mkdir";
+    segments: string[];
+} | {
+    kind: "private-directory-mode";
+    segments: string[];
+} | {
+    kind: "overlay";
+    name: string;
+    content: string;
+}, timeoutMs?: number, terminationConfirmationMs?: number): Promise<void>;
+/** Archive copies may be large or numerous: never block Bridge heartbeats while a pinned worker writes. */
+export declare function runAttemptArchiveOperation(parent: string, identity: BigIntStats, operation: {
+    name: string;
+    bytes: Buffer;
+    sha256: string;
+}, timeoutMs?: number, terminationConfirmationMs?: number): Promise<void>;

package/dist/runtime/attempt-path-operation.js

@@ -0,0 +1,94 @@
+import { runPinnedDirectoryProcess } from "./pinned-directory-process.js";
+/** A separate process pins cwd without changing the multithreaded Bridge's cwd.
+ * All writes use single relative components, never a re-resolved ancestor path.
+ */
+export async function runAttemptPathOperation(parent, identity, operation, timeoutMs = 30_000, terminationConfirmationMs = 2_000) {
+    try {
+        await runPinnedDirectoryProcess(parent, identity, worker, operation, undefined, 16 * 1024, timeoutMs, terminationConfirmationMs);
+    }
+    catch (error) {
+        throw new Error(`playwright_runtime_adapter_invalid: pinned directory operation failed: ${String(error)}`, { cause: error });
+    }
+}
+/** Archive copies may be large or numerous: never block Bridge heartbeats while a pinned worker writes. */
+export async function runAttemptArchiveOperation(parent, identity, operation, timeoutMs = 30_000, terminationConfirmationMs = 2_000) {
+    try {
+        await runPinnedDirectoryProcess(parent, identity, worker, { kind: "archive", name: operation.name, sha256: operation.sha256 }, operation.bytes, 16 * 1024, timeoutMs, terminationConfirmationMs);
+    }
+    catch (error) {
+        throw new Error(`host_diagnostics_copy_failed: pinned directory operation failed: ${String(error)}`, { cause: error });
+    }
+}
+const worker = String.raw `
+const fs = require('node:fs');
+const path = require('node:path');
+const input = fs.readFileSync(0);
+const boundary = input.indexOf(10);
+const job = JSON.parse(input.subarray(0, boundary).toString('utf8'));
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const samePath = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const component = value => {
+  if (typeof value !== 'string' || !value || value === '.' || value === '..'
+    || ['/', ':', String.fromCharCode(92), String.fromCharCode(0)].some(char => value.includes(char)))
+    throw new Error('invalid relative component');
+};
+const statCwd = () => fs.statSync('.', { bigint: true });
+try {
+  if (!same(statCwd(), { dev: BigInt(job.dev), ino: BigInt(job.ino) })
+    || !samePath(fs.realpathSync('.'), job.parent)) throw new Error('parent identity changed');
+  if (job.kind === 'mkdir' || job.kind === 'private-directory-mode') {
+    let expected = job.parent;
+    for (const name of job.segments) {
+      component(name);
+      let before;
+      try { before = fs.lstatSync(name, { bigint: true }); }
+      catch (error) {
+        if (error.code !== 'ENOENT' || job.kind !== 'mkdir') throw error;
+        try { fs.mkdirSync(name, { mode: 0o700 }); }
+        catch (mkdirError) { if (mkdirError.code !== 'EEXIST') throw mkdirError; }
+        before = fs.lstatSync(name, { bigint: true });
+      }
+      if (!before.isDirectory() || before.isSymbolicLink()) throw new Error('redirected directory');
+      process.chdir(name);
+      expected = path.join(expected, name);
+      if (!same(before, statCwd()) || !samePath(fs.realpathSync('.'), expected)) throw new Error('child identity changed');
+    }
+    if (job.kind === 'private-directory-mode' && process.platform !== 'win32') fs.chmodSync('.', 0o700);
+  } else if (job.kind === 'overlay' || job.kind === 'archive') {
+    component(job.name);
+    let before;
+    try { before = fs.lstatSync(job.name, { bigint: true }); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (before && (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n))
+      throw new Error('overlay must be a regular file');
+    const fd = fs.openSync(job.name, (job.kind === 'archive' ? fs.constants.O_RDWR : fs.constants.O_WRONLY) | (fs.constants.O_NOFOLLOW ?? 0)
+      | (fs.constants.O_NONBLOCK ?? 0) | (before ? 0 : fs.constants.O_CREAT | fs.constants.O_EXCL), 0o600);
+    try {
+      const opened = fs.fstatSync(fd, { bigint: true });
+      if (!opened.isFile() || opened.nlink !== 1n || (before && !same(before, opened)))
+        throw new Error('overlay identity changed');
+      fs.ftruncateSync(fd, 0);
+      if (job.kind === 'overlay') fs.writeFileSync(fd, job.content, 'utf8');
+      else {
+        const bytes = input.subarray(boundary + 1);
+        fs.writeFileSync(fd, bytes);
+        fs.fsyncSync(fd);
+        const hash = require('node:crypto').createHash('sha256');
+        const chunk = Buffer.alloc(64 * 1024);
+        let offset = 0;
+        while (offset < bytes.length) {
+          const count = fs.readSync(fd, chunk, 0, Math.min(chunk.length, bytes.length - offset), offset);
+          if (!count) throw new Error('incomplete archive read');
+          hash.update(chunk.subarray(0, count));
+          offset += count;
+        }
+        const after = fs.fstatSync(fd, { bigint: true });
+        const current = fs.lstatSync(job.name, { bigint: true });
+        if (after.size !== BigInt(bytes.length) || after.nlink !== 1n || current.isSymbolicLink()
+          || !same(opened, after) || !same(after, current) || hash.digest('hex') !== job.sha256)
+          throw new Error('archive verification failed');
+      }
+    } finally { fs.closeSync(fd); }
+  } else throw new Error('invalid operation');
+} catch (error) { process.stderr.write(error.message); process.exitCode = 1; }
+`;

package/dist/runtime/attempt-private-directory.d.ts

@@ -0,0 +1,6 @@
+import type { BigIntStats } from "node:fs";
+/** Validate every existing ancestor before creating anything through a pathname. */
+export declare function assertCanonicalDirectory(target: string, allowMissing?: boolean): Promise<BigIntStats | undefined>;
+export declare function createCanonicalDirectory(target: string): Promise<void>;
+export declare function createPrivateCanonicalDirectory(target: string): Promise<void>;
+export declare function restorePrivateDirectoryMode(target: string): Promise<void>;