@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.bfa11ebe98c6

package/dist/runtime/aspnet-runtime-prebuild.js

@@ -0,0 +1,341 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ForgeFailureError } from "../session/session.types.js";
+const inFlightPrebuilds = new Map();
+export function createAspNetRuntimePrebuildPlan(options) {
+    if (!isDotnetRun(options.command, options.args))
+        return null;
+    const projectArgument = readOptionValue(options.args, "--project");
+    const projectPath = path.resolve(options.cwd, projectArgument ?? ".");
+    const normalizedWorktree = path.resolve(options.worktreePath);
+    const relativeProject = path.relative(normalizedWorktree, projectPath);
+    if (relativeProject.startsWith("..") || path.isAbsolute(relativeProject)) {
+        throw new Error("host_runtime_build_invalid: the ASP.NET project must remain inside the managed worktree.");
+    }
+    const projectDirectory = projectArgument && path.extname(projectPath).toLowerCase() === ".csproj"
+        ? path.dirname(projectPath)
+        : projectPath;
+    const buildArgs = [
+        "build",
+        ...(projectArgument ? [projectArgument] : []),
+        "--nologo",
+        "--no-restore",
+        "--disable-build-servers",
+        "-p:UseSharedCompilation=false",
+        "-p:DefaultItemExcludesInProjectFolder=TestResults/**",
+        ...forwardBuildOptions(options.args),
+    ];
+    const fingerprint = `sha256:${createHash("sha256").update(JSON.stringify({
+        inputCommitSha: options.inputCommitSha,
+        runtimeContractFingerprint: options.runtimeContractFingerprint,
+        project: relativeProject.replaceAll("\\", "/"),
+        args: buildArgs,
+        environment: buildEnvironmentContract(options.environment ?? {}),
+    })).digest("hex")}`;
+    return {
+        fingerprint,
+        receiptPath: path.join(projectDirectory, "obj", ".forge-runtime-build.json"),
+        command: options.command,
+        args: buildArgs,
+        cwd: options.cwd,
+        environment: options.environment ?? {},
+        projectPath,
+        worktreePath: normalizedWorktree,
+        inputCommitSha: options.inputCommitSha,
+    };
+}
+export async function ensureAspNetRuntimePrebuilt(plan, execute, signal) {
+    const pending = inFlightPrebuilds.get(plan.receiptPath);
+    if (pending)
+        return await pending;
+    const started = ensureAspNetRuntimePrebuiltCore(plan, execute, signal);
+    inFlightPrebuilds.set(plan.receiptPath, started);
+    try {
+        return await started;
+    }
+    finally {
+        if (inFlightPrebuilds.get(plan.receiptPath) === started)
+            inFlightPrebuilds.delete(plan.receiptPath);
+    }
+}
+async function ensureAspNetRuntimePrebuiltCore(plan, execute, signal) {
+    const inputs = await aspNetBuildInputs(plan);
+    const fingerprint = `sha256:${createHash("sha256").update(JSON.stringify({
+        planFingerprint: plan.fingerprint,
+        ...inputs,
+    })).digest("hex")}`;
+    const receipt = await readReceipt(plan.receiptPath);
+    if (receipt?.fingerprint === fingerprint
+        && receipt.planFingerprint === plan.fingerprint
+        && receipt.inputCommitSha === plan.inputCommitSha
+        && await aspNetOutputsMatch(plan, receipt.outputs)) {
+        return { cacheHit: true, receiptPath: plan.receiptPath, fingerprint };
+    }
+    const result = await execute(plan, signal);
+    if (result.exitCode !== 0) {
+        const evidence = [
+            diagnostic("stderr", result.stderrTail),
+            diagnostic("stdout", result.stdoutTail),
+            `stdout log: ${result.stdoutLogPath}`,
+            `stderr log: ${result.stderrLogPath}`,
+        ].filter(Boolean).join("; ");
+        throw new ForgeFailureError("host_runtime_project_start_failed", `host_runtime_project_start_failed: dotnet build exited with code ${result.exitCode}.${evidence ? ` ${evidence}` : ""}`, "bridge");
+    }
+    await fs.mkdir(path.dirname(plan.receiptPath), { recursive: true });
+    const outputs = await collectAspNetBuildOutputs(plan);
+    if (outputs.length === 0) {
+        throw new Error("host_runtime_build_output_missing: dotnet build succeeded without producing a verifiable project output.");
+    }
+    const temporaryReceipt = `${plan.receiptPath}.${randomUUID()}.tmp`;
+    const nextReceipt = {
+        schemaVersion: 2,
+        fingerprint,
+        planFingerprint: plan.fingerprint,
+        inputCommitSha: plan.inputCommitSha,
+        projectPath: plan.projectPath,
+        ...inputs,
+        outputs,
+        completedAt: new Date().toISOString(),
+    };
+    await fs.writeFile(temporaryReceipt, `${JSON.stringify(nextReceipt)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        await fs.rename(temporaryReceipt, plan.receiptPath);
+    }
+    finally {
+        await fs.rm(temporaryReceipt, { force: true }).catch(() => undefined);
+    }
+    return { cacheHit: false, receiptPath: plan.receiptPath, fingerprint };
+}
+export function withAspNetPrebuiltRunArguments(command, args) {
+    if (!isDotnetRun(command, args)) {
+        throw new Error("node_runtime_adapter_invalid: aspnetcore adapter requires a dotnet run command.");
+    }
+    const applicationArguments = args.indexOf("--");
+    const insertionIndex = applicationArguments < 0 ? args.length : applicationArguments;
+    const beforeApplication = args.slice(0, insertionIndex);
+    return [
+        ...beforeApplication,
+        ...(!beforeApplication.includes("--no-build") ? ["--no-build"] : []),
+        ...(!beforeApplication.includes("--no-restore") ? ["--no-restore"] : []),
+        ...args.slice(insertionIndex),
+    ];
+}
+export async function resolveWorktreeCommitSha(worktreePath, supplied) {
+    if (supplied && /^[0-9a-f]{40,64}$/iu.test(supplied))
+        return supplied.toLowerCase();
+    return await new Promise((resolve, reject) => {
+        const child = spawn("git", ["rev-parse", "--verify", "HEAD^{commit}"], {
+            cwd: worktreePath,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", chunk => { stdout = `${stdout}${String(chunk)}`.slice(-256); });
+        child.stderr.on("data", chunk => { stderr = `${stderr}${String(chunk)}`.slice(-1_000); });
+        child.once("error", reject);
+        child.once("close", code => {
+            const commit = stdout.trim();
+            if (code === 0 && /^[0-9a-f]{40,64}$/iu.test(commit))
+                resolve(commit.toLowerCase());
+            else
+                reject(new Error(`host_runtime_build_commit_unavailable: git rev-parse failed (${code ?? "unknown"}): ${stderr.trim()}`));
+        });
+    });
+}
+function isDotnetRun(command, args) {
+    const executable = path.basename(command).toLowerCase();
+    return (executable === "dotnet" || executable === "dotnet.exe") && args[0]?.toLowerCase() === "run";
+}
+function readOptionValue(args, option) {
+    const index = args.findIndex(argument => argument === option || argument.startsWith(`${option}=`));
+    if (index < 0)
+        return null;
+    const argument = args[index];
+    return argument.startsWith(`${option}=`) ? argument.slice(option.length + 1) : args[index + 1] ?? null;
+}
+function forwardBuildOptions(args) {
+    const forwarded = [];
+    const optionsWithValues = new Set(["-c", "--configuration", "-f", "--framework", "-r", "--runtime", "--arch", "--os"]);
+    for (let index = 1; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--")
+            break;
+        if (argument === "--project") {
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith("--project="))
+            continue;
+        if (optionsWithValues.has(argument)) {
+            const value = args[index + 1];
+            if (value !== undefined) {
+                forwarded.push(argument, value);
+                index += 1;
+            }
+            continue;
+        }
+        if ([...optionsWithValues].some(option => argument.startsWith(`${option}=`))
+            || argument.startsWith("-p:")
+            || argument.startsWith("/p:")) {
+            forwarded.push(argument);
+        }
+    }
+    return forwarded;
+}
+async function readReceipt(receiptPath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(receiptPath, "utf8"));
+        return parsed.schemaVersion === 2
+            && typeof parsed.fingerprint === "string"
+            && typeof parsed.planFingerprint === "string"
+            && typeof parsed.inputCommitSha === "string"
+            && typeof parsed.sourceDigest === "string"
+            && typeof parsed.dependencyDigest === "string"
+            && typeof parsed.sdkVersion === "string"
+            && Array.isArray(parsed.outputs)
+            ? parsed
+            : null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT" || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+async function aspNetBuildInputs(plan) {
+    const projectDirectory = path.extname(plan.projectPath).toLowerCase() === ".csproj"
+        ? path.dirname(plan.projectPath)
+        : plan.projectPath;
+    const sourceDigest = await directoryContentDigest(projectDirectory);
+    const dependencyReceipt = path.join(projectDirectory, "obj", ".forge-dependency-preparation.json");
+    const dependencyContent = await fs.readFile(dependencyReceipt).catch(() => null);
+    const globalJson = await findAncestorFile(projectDirectory, plan.worktreePath, "global.json");
+    const globalJsonContent = globalJson ? await fs.readFile(globalJson) : null;
+    return {
+        sourceDigest,
+        dependencyDigest: `sha256:${createHash("sha256")
+            .update(dependencyContent ?? Buffer.alloc(0))
+            .update(globalJsonContent ?? Buffer.alloc(0))
+            .digest("hex")}`,
+        sdkVersion: await dotnetSdkVersion(plan.cwd),
+    };
+}
+async function directoryContentDigest(directory) {
+    const files = [];
+    await collectInputFiles(directory, directory, files);
+    const hash = createHash("sha256");
+    for (const file of files.sort((left, right) => left.localeCompare(right))) {
+        hash.update(path.relative(directory, file).replaceAll("\\", "/"));
+        hash.update("\0");
+        hash.update(await fs.readFile(file));
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
+async function collectInputFiles(root, directory, files) {
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const absolute = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!["bin", "obj", "node_modules", ".git", "TestResults"].includes(entry.name)) {
+                await collectInputFiles(root, absolute, files);
+            }
+        }
+        else if (entry.isFile()) {
+            files.push(absolute);
+        }
+    }
+}
+async function collectAspNetBuildOutputs(plan) {
+    const projectDirectory = path.extname(plan.projectPath).toLowerCase() === ".csproj"
+        ? path.dirname(plan.projectPath)
+        : plan.projectPath;
+    const outputRoot = path.join(projectDirectory, "bin");
+    const outputs = [];
+    await collectOutputFiles(outputRoot, projectDirectory, outputs);
+    return outputs.sort((left, right) => left.path.localeCompare(right.path));
+}
+async function collectOutputFiles(directory, projectDirectory, outputs) {
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const absolute = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            await collectOutputFiles(absolute, projectDirectory, outputs);
+        else if (entry.isFile()) {
+            const stat = await fs.stat(absolute);
+            outputs.push({
+                path: path.relative(projectDirectory, absolute).replaceAll("\\", "/"),
+                size: stat.size,
+                digest: createHash("sha256").update(await fs.readFile(absolute)).digest("hex"),
+            });
+        }
+    }
+}
+async function aspNetOutputsMatch(plan, outputs) {
+    if (outputs.length === 0)
+        return false;
+    const projectDirectory = path.extname(plan.projectPath).toLowerCase() === ".csproj"
+        ? path.dirname(plan.projectPath)
+        : plan.projectPath;
+    for (const output of outputs) {
+        const absolute = path.resolve(projectDirectory, output.path);
+        const relative = path.relative(projectDirectory, absolute);
+        if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+            return false;
+        const stat = await fs.stat(absolute).catch(() => null);
+        if (!stat?.isFile() || stat.size !== output.size)
+            return false;
+        const digest = createHash("sha256").update(await fs.readFile(absolute)).digest("hex");
+        if (digest !== output.digest)
+            return false;
+    }
+    return true;
+}
+async function findAncestorFile(directory, root, name) {
+    let current = path.resolve(directory);
+    const resolvedRoot = path.resolve(root);
+    while (true) {
+        const candidate = path.join(current, name);
+        if (await fs.stat(candidate).then(stat => stat.isFile()).catch(() => false))
+            return candidate;
+        if (current === resolvedRoot)
+            return null;
+        const parent = path.dirname(current);
+        if (parent === current || path.relative(resolvedRoot, parent).startsWith(".."))
+            return null;
+        current = parent;
+    }
+}
+async function dotnetSdkVersion(cwd) {
+    return await new Promise(resolve => {
+        const child = spawn("dotnet", ["--version"], { cwd, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+        let output = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", chunk => { output += String(chunk); });
+        child.stderr.on("data", chunk => { output += String(chunk); });
+        child.once("error", () => resolve("unavailable"));
+        child.once("close", code => resolve(code === 0 ? output.trim().slice(0, 256) : `unavailable:${code ?? "unknown"}`));
+    });
+}
+function buildEnvironmentContract(environment) {
+    return {
+        DOTNET_ROOT: environment.DOTNET_ROOT ?? process.env.DOTNET_ROOT ?? null,
+        DOTNET_ROLL_FORWARD: environment.DOTNET_ROLL_FORWARD ?? process.env.DOTNET_ROLL_FORWARD ?? null,
+        DOTNET_MULTILEVEL_LOOKUP: environment.DOTNET_MULTILEVEL_LOOKUP ?? process.env.DOTNET_MULTILEVEL_LOOKUP ?? null,
+        MSBuildSDKsPath: environment.MSBuildSDKsPath ?? process.env.MSBuildSDKsPath ?? null,
+        NUGET_PACKAGES: environment.NUGET_PACKAGES ?? process.env.NUGET_PACKAGES ?? null,
+        FORGE_BUILD_CACHE_EPOCH: createHash("sha256")
+            .update(environment.FORGE_BUILD_CACHE_EPOCH ?? process.env.FORGE_BUILD_CACHE_EPOCH ?? "default")
+            .digest("hex"),
+    };
+}
+function diagnostic(label, value) {
+    const normalized = value.replaceAll(/[\r\n\t]+/gu, " ").trim();
+    return normalized ? `${label} tail: ${normalized.slice(-2_000)}` : "";
+}

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

@@ -8,8 +8,9 @@ export declare class AttemptNodeRuntimeLauncher implements NodeRuntimeCommandLau
     private readonly owner;
     private readonly logDirectory;
     private readonly listenerInspector;
+    private readonly exactSecrets;
     private readonly diagnosticsByChild;
-    constructor(supervisor: AttemptProcessSupervisor, owner: HostPortLeaseOwner, logDirectory: string, listenerInspector?: HostListenerInspector);
+    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>;

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

@@ -1,6 +1,8 @@
 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. */
@@ -9,18 +11,20 @@ export class AttemptNodeRuntimeLauncher {
     owner;
     logDirectory;
     listenerInspector;
+    exactSecrets;
     diagnosticsByChild = new WeakMap();
-    constructor(supervisor, owner, logDirectory, listenerInspector = new HostListenerInspector()) {
+    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: "" };
+        const diagnostics = { exited: false, stdoutTail: "", stderrTail: "", outputRevision: 0 };
         let child;
         try {
             child = await this.supervisor.startChildReady(childName, {
@@ -29,31 +33,39 @@ export class AttemptNodeRuntimeLauncher {
                 cwd: request.cwd,
                 env: request.environment,
                 captureOutput: false,
+                failureRedactionValues: this.exactSecrets,
             }, {
                 onStdoutLine: async (line) => {
-                    diagnostics.stdoutTail = appendTail(diagnostics.stdoutTail, line);
-                    await appendLine(stdoutPath, line);
+                    const redacted = redactText(line, this.exactSecrets);
+                    diagnostics.stdoutTail = appendTail(diagnostics.stdoutTail, redacted);
+                    diagnostics.outputRevision += 1;
+                    await appendLine(stdoutPath, redacted);
                 },
                 onStderrLine: async (line) => {
-                    diagnostics.stderrTail = appendTail(diagnostics.stderrTail, line);
-                    await appendLine(stderrPath, 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);
+            throw enrichLaunchFailure(error, diagnostics, this.exactSecrets);
         }
-        this.diagnosticsByChild.set(child, diagnostics);
-        void child.result.then(result => {
+        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, error instanceof Error ? error.message : String(error));
+            diagnostics.stderrTail = appendTail(diagnostics.stderrTail, redactText(error instanceof Error ? error.message : String(error), this.exactSecrets));
+            diagnostics.outputRevision += 1;
         });
-        return child;
+        return exposedChild;
     }
     async inspectListener(child, request) {
         return await this.listenerInspector.inspect(child, request.port, this.owner);
@@ -84,17 +96,44 @@ function appendTail(current, value) {
     const combined = current ? `${current}\n${value}` : value;
     return combined.slice(-diagnosticTailLength);
 }
-function enrichLaunchFailure(error, diagnostics) {
-    const message = error instanceof Error ? error.message : String(error);
+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);
-    return evidence.length > 0
-        ? new Error(`${message} ${evidence.join("; ")}`, { cause: error })
-        : error instanceof Error
-            ? error
-            : new Error(message);
+    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>;

package/dist/runtime/attempt-private-directory.js

@@ -0,0 +1,54 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runAttemptPathOperation } from "./attempt-path-operation.js";
+/** Validate every existing ancestor before creating anything through a pathname. */
+export async function assertCanonicalDirectory(target, allowMissing = false) {
+    const resolved = path.resolve(target);
+    const parent = path.dirname(resolved);
+    if (parent !== resolved)
+        await assertCanonicalDirectory(parent, allowMissing);
+    try {
+        const stat = await fs.lstat(resolved, { bigint: true });
+        const real = await fs.realpath(resolved);
+        const realStat = await fs.lstat(real, { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isDirectory() || !samePath(real, resolved)
+            || stat.dev !== realStat.dev || stat.ino !== realStat.ino) {
+            throw new Error("playwright_runtime_adapter_invalid: writable paths must be canonical, link-free directories.");
+        }
+        return realStat;
+    }
+    catch (error) {
+        if (allowMissing && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+export async function createCanonicalDirectory(target) {
+    if (await assertCanonicalDirectory(target, true))
+        return;
+    const resolved = path.resolve(target);
+    let parent = path.dirname(resolved);
+    let identity = await assertCanonicalDirectory(parent, true);
+    while (!identity) {
+        parent = path.dirname(parent);
+        identity = await assertCanonicalDirectory(parent, true);
+    }
+    await runAttemptPathOperation(parent, identity, { kind: "mkdir", segments: path.relative(parent, resolved).split(path.sep) });
+    await assertCanonicalDirectory(resolved);
+}
+export async function createPrivateCanonicalDirectory(target) {
+    await createCanonicalDirectory(target);
+    await restorePrivateDirectoryMode(target);
+}
+export async function restorePrivateDirectoryMode(target) {
+    if (process.platform === "win32")
+        return;
+    const resolved = path.resolve(target);
+    const parent = path.dirname(resolved);
+    const identity = await assertCanonicalDirectory(parent);
+    await runAttemptPathOperation(parent, identity, { kind: "private-directory-mode", segments: [path.basename(resolved)] });
+    await assertCanonicalDirectory(resolved);
+}
+function samePath(left, right) {
+    return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}