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

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;
+}

package/dist/runtime/attempt-process-supervisor-registry.d.ts

@@ -0,0 +1,20 @@
+import type { ProviderProcessHandlers, ProviderProcessRunRequest, ProviderProcessRunner, ProviderProcessRunResult } from "../session/provider-cli/provider-cli.process.js";
+import { AttemptProcessSupervisor, type AttemptProcessSupervisorIdentity, type AttemptProcessSupervisorOptions } from "./attempt-process-supervisor.js";
+/** Runner-local authority for active host attempt process coordinators. */
+export declare class AttemptProcessSupervisorRegistry {
+    private readonly active;
+    register(identity: AttemptProcessSupervisorIdentity, runner: ProviderProcessRunner, options?: AttemptProcessSupervisorOptions): AttemptProcessSupervisor;
+    require(dispatchAttemptId: string, fencingToken: string): AttemptProcessSupervisor;
+    unregister(dispatchAttemptId: string, fencingToken: string): boolean;
+    has(dispatchAttemptId: string): boolean;
+}
+/**
+ * Routes managed-host provider commands through the attempt's named provider
+ * child while retaining the raw runner for Docker and unmanaged execution.
+ */
+export declare class AttemptCoordinatedProviderProcessRunner implements ProviderProcessRunner {
+    private readonly registry;
+    private readonly rawRunner;
+    constructor(registry: AttemptProcessSupervisorRegistry, rawRunner: ProviderProcessRunner);
+    run(request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal): Promise<ProviderProcessRunResult>;
+}

package/dist/runtime/attempt-process-supervisor-registry.js

@@ -0,0 +1,64 @@
+import { AttemptProcessSupervisor, } from "./attempt-process-supervisor.js";
+/** Runner-local authority for active host attempt process coordinators. */
+export class AttemptProcessSupervisorRegistry {
+    active = new Map();
+    register(identity, runner, options = {}) {
+        const existing = this.active.get(identity.dispatchAttemptId);
+        if (existing) {
+            if (existing.fencingToken !== identity.fencingToken) {
+                throw new Error("attempt_process_registry_conflict: dispatch attempt is registered under a different fence.");
+            }
+            return existing.supervisor;
+        }
+        const supervisor = new AttemptProcessSupervisor(identity, runner, options);
+        this.active.set(identity.dispatchAttemptId, { fencingToken: identity.fencingToken, supervisor });
+        return supervisor;
+    }
+    require(dispatchAttemptId, fencingToken) {
+        const registered = this.active.get(dispatchAttemptId);
+        if (!registered) {
+            throw new Error("attempt_process_registry_missing: no process coordinator owns this dispatch attempt.");
+        }
+        if (registered.fencingToken !== fencingToken) {
+            throw new Error("attempt_process_registry_fenced: process coordinator fence does not match the dispatch.");
+        }
+        return registered.supervisor;
+    }
+    unregister(dispatchAttemptId, fencingToken) {
+        const registered = this.active.get(dispatchAttemptId);
+        if (!registered || registered.fencingToken !== fencingToken)
+            return false;
+        return this.active.delete(dispatchAttemptId);
+    }
+    has(dispatchAttemptId) {
+        return this.active.has(dispatchAttemptId);
+    }
+}
+/**
+ * Routes managed-host provider commands through the attempt's named provider
+ * child while retaining the raw runner for Docker and unmanaged execution.
+ */
+export class AttemptCoordinatedProviderProcessRunner {
+    registry;
+    rawRunner;
+    constructor(registry, rawRunner) {
+        this.registry = registry;
+        this.rawRunner = rawRunner;
+    }
+    async run(request, handlers, signal) {
+        if (request.env?.FORGE_RUNTIME_MODE !== "host") {
+            return await this.rawRunner.run(request, handlers, signal);
+        }
+        const dispatchAttemptId = requiredEnvironment(request, "FORGE_DISPATCH_ATTEMPT_ID");
+        const fencingToken = requiredEnvironment(request, "FORGE_FENCING_TOKEN");
+        const supervisor = this.registry.require(dispatchAttemptId, fencingToken);
+        const child = await supervisor.startChildReady("provider", request, handlers, signal, { maxStartAttempts: request.stdin === undefined ? 1 : 3, retryDelayMs: 100 });
+        return await child.result;
+    }
+}
+function requiredEnvironment(request, name) {
+    const value = request.env?.[name]?.trim();
+    if (!value)
+        throw new Error(`attempt_process_registry_invalid: ${name} is required for managed-host execution.`);
+    return value;
+}

package/dist/runtime/attempt-process-supervisor.d.ts

@@ -0,0 +1,97 @@
+import type { ProviderProcessHandlers, ProviderProcessRunRequest, ProviderProcessRunner, ProviderProcessRunResult } from "../session/provider-cli/provider-cli.process.js";
+export type AttemptProcessChildStatus = "starting" | "running" | "stopping" | "exited" | "failed";
+export type AttemptProcessSupervisorStatus = "active" | "stopping" | "stopped" | "degraded";
+export interface AttemptProcessSupervisorIdentity {
+    readonly processSupervisorId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly fencingToken: string;
+    readonly logDirectory: string;
+}
+export interface AttemptProcessChildLedgerEntry {
+    readonly name: string;
+    readonly generation: number;
+    readonly childId: string;
+    readonly processSupervisorId: string;
+    readonly metadataPath: string;
+    readonly status: AttemptProcessChildStatus;
+    readonly startedAt: string;
+    readonly settledAt?: string;
+    readonly exitCode?: number;
+    readonly failure?: string;
+    readonly peakMemoryBytes?: number;
+    readonly memorySampleCount?: number;
+    readonly memorySource?: string;
+    readonly memoryObservedAt?: string;
+}
+export interface AttemptProcessSupervisorLedger {
+    readonly schemaVersion: 1;
+    readonly attemptSupervisorId: string;
+    readonly dispatchAttemptId: string;
+    readonly executionLeaseId: string;
+    readonly status: AttemptProcessSupervisorStatus;
+    readonly updatedAt: string;
+    readonly children: readonly AttemptProcessChildLedgerEntry[];
+}
+export interface AttemptProcessChildHandle {
+    readonly name: string;
+    readonly generation: number;
+    readonly childId: string;
+    readonly processSupervisorId: string;
+    readonly metadataPath: string;
+    readonly ready: Promise<void>;
+    readonly result: Promise<ProviderProcessRunResult>;
+    stop(fencingToken: string): Promise<ProviderProcessRunResult>;
+}
+export interface AttemptProcessSupervisorOptions {
+    readonly metadataReadyTimeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface AttemptProcessChildReadyOptions {
+    readonly maxStartAttempts?: number;
+    readonly retryDelayMs?: number;
+}
+/**
+ * Owns the independently supervised process trees that belong to one host
+ * dispatch attempt. Each named child gets a distinct Windows Job Object or
+ * Unix process group through the existing process runner, while this
+ * coordinator supplies shared fencing, cancellation, and a durable ledger.
+ */
+export declare class AttemptProcessSupervisor {
+    private readonly runner;
+    readonly ledgerPath: string;
+    private readonly identity;
+    private readonly metadataReadyTimeoutMs;
+    private readonly records;
+    private readonly currentByName;
+    private readonly attemptController;
+    private status;
+    private persistTail;
+    private persistenceFailure;
+    private stopOperation;
+    constructor(identity: AttemptProcessSupervisorIdentity, runner: ProviderProcessRunner, options?: AttemptProcessSupervisorOptions);
+    startChild(name: string, request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal): Promise<AttemptProcessChildHandle>;
+    /**
+     * Starts a child and proves that the OS process tree is supervised before
+     * returning it to the caller. A launch that settles before producing its
+     * provider-ready supervision record is safe to retry: the raw runner only
+     * persists that record after the actual provider child has started, before
+     * Forge announces the provider as active.
+     */
+    startChildReady(name: string, request: ProviderProcessRunRequest, handlers?: ProviderProcessHandlers, signal?: AbortSignal, options?: AttemptProcessChildReadyOptions): Promise<AttemptProcessChildHandle>;
+    stopChild(name: string, generation: number, fencingToken: string, reason?: unknown): Promise<ProviderProcessRunResult>;
+    stopAll(fencingToken: string, reason?: unknown): Promise<void>;
+    private performStopAll;
+    snapshot(): AttemptProcessSupervisorLedger;
+    providerMemoryTelemetry(): AttemptProcessTreeMemoryTelemetry | null;
+    private observeChildReady;
+    private settleChild;
+    private assertFence;
+    private persist;
+}
+export interface AttemptProcessTreeMemoryTelemetry {
+    readonly peakMemoryBytes: number;
+    readonly sampleCount: number;
+    readonly source: string;
+    readonly observedAt: string;
+}

package/dist/runtime/attempt-process-supervisor.js

@@ -0,0 +1,397 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ForgeFailureError, sanitizeFailureError } from "../session/session.types.js";
+const terminalChildStatuses = new Set(["exited", "failed"]);
+const defaultMetadataReadyTimeoutMs = process.platform === "win32" ? 60_000 : 10_000;
+/**
+ * Owns the independently supervised process trees that belong to one host
+ * dispatch attempt. Each named child gets a distinct Windows Job Object or
+ * Unix process group through the existing process runner, while this
+ * coordinator supplies shared fencing, cancellation, and a durable ledger.
+ */
+export class AttemptProcessSupervisor {
+    runner;
+    ledgerPath;
+    identity;
+    metadataReadyTimeoutMs;
+    records = [];
+    currentByName = new Map();
+    attemptController = new AbortController();
+    status = "active";
+    persistTail = Promise.resolve();
+    persistenceFailure;
+    stopOperation = null;
+    constructor(identity, runner, options = {}) {
+        this.runner = runner;
+        this.identity = validateIdentity(identity);
+        this.metadataReadyTimeoutMs = boundedInteger(options.metadataReadyTimeoutMs ?? defaultMetadataReadyTimeoutMs, 100, 120_000, "metadataReadyTimeoutMs");
+        this.ledgerPath = path.join(this.identity.logDirectory, "attempt-process-supervisor.json");
+        if (options.signal?.aborted) {
+            this.status = "stopping";
+            this.attemptController.abort(options.signal.reason);
+        }
+        else {
+            options.signal?.addEventListener("abort", () => {
+                // stopAll already persists a degraded terminal snapshot when a child
+                // rejects during cancellation. Do not relabel that process failure as
+                // a persistence failure: doing so poisons every later cleanup retry,
+                // even after all supervised processes have exited.
+                void this.stopAll(this.identity.fencingToken, options.signal?.reason).catch(() => undefined);
+            }, { once: true });
+        }
+    }
+    async startChild(name, request, handlers = {}, signal) {
+        assertChildName(name);
+        if (this.status !== "active" || this.attemptController.signal.aborted) {
+            throw new Error("attempt_process_supervisor_closed: the attempt no longer accepts child processes.");
+        }
+        if (signal?.aborted)
+            throw cancellationError(signal);
+        const existing = this.currentByName.get(name);
+        if (existing && !terminalChildStatuses.has(existing.status)) {
+            throw new Error(`attempt_process_supervisor_conflict: child '${name}' is already active.`);
+        }
+        const generation = (existing?.generation ?? 0) + 1;
+        const childId = `${name}:${generation}`;
+        const processSupervisorId = childProcessSupervisorId(this.identity.processSupervisorId, childId);
+        const metadataPath = path.join(this.identity.logDirectory, `process-supervisor.${name}.${generation}.json`);
+        const controller = new AbortController();
+        const combinedSignal = signal
+            ? AbortSignal.any([this.attemptController.signal, controller.signal, signal])
+            : AbortSignal.any([this.attemptController.signal, controller.signal]);
+        const failureRedactionValues = [...new Set((request.failureRedactionValues ?? []).filter(value => value.length > 0))];
+        const { failureRedactionValues: _failureRedactionValues, ...executableRequest } = request;
+        const childRequest = {
+            ...executableRequest,
+            env: {
+                ...request.env,
+                FORGE_RUNTIME_MODE: "host",
+                FORGE_RESOURCE_LEASE_ID: this.identity.executionLeaseId,
+                FORGE_EXECUTION_LEASE_ID: this.identity.executionLeaseId,
+                FORGE_DISPATCH_ATTEMPT_ID: this.identity.dispatchAttemptId,
+                FORGE_FENCING_TOKEN: this.identity.fencingToken,
+                FORGE_LOG_DIR: this.identity.logDirectory,
+                FORGE_PROCESS_SUPERVISOR_ID: processSupervisorId,
+                FORGE_PROCESS_SUPERVISOR_METADATA_PATH: metadataPath,
+                FORGE_PROCESS_CHILD_ID: childId,
+                FORGE_PROCESS_CHILD_NAME: name,
+                FORGE_PROCESS_CHILD_GENERATION: String(generation),
+            },
+        };
+        const startedAt = new Date().toISOString();
+        const record = {
+            name,
+            generation,
+            childId,
+            processSupervisorId,
+            metadataPath,
+            controller,
+            failureRedactionValues,
+            startedAt,
+            status: "starting",
+            result: Promise.resolve({ exitCode: 1, stdout: "", stderr: "not started" }),
+        };
+        this.records.push(record);
+        this.currentByName.set(name, record);
+        const result = this.runner.run(childRequest, handlers, combinedSignal);
+        record.result = result;
+        void result.then(value => this.settleChild(record, "exited", value.exitCode, undefined, value), error => this.settleChild(record, "failed", undefined, error));
+        try {
+            await this.persist();
+        }
+        catch (error) {
+            controller.abort("Attempt process ledger could not be persisted.");
+            await result.catch(() => undefined);
+            throw error;
+        }
+        const ready = this.observeChildReady(record);
+        void ready.catch(() => undefined);
+        return {
+            name,
+            generation,
+            childId,
+            processSupervisorId,
+            metadataPath,
+            ready,
+            result,
+            stop: async (fencingToken) => await this.stopChild(name, generation, fencingToken),
+        };
+    }
+    /**
+     * Starts a child and proves that the OS process tree is supervised before
+     * returning it to the caller. A launch that settles before producing its
+     * provider-ready supervision record is safe to retry: the raw runner only
+     * persists that record after the actual provider child has started, before
+     * Forge announces the provider as active.
+     */
+    async startChildReady(name, request, handlers = {}, signal, options = {}) {
+        const maxStartAttempts = boundedInteger(options.maxStartAttempts ?? 1, 1, 5, "maxStartAttempts");
+        const retryDelayMs = boundedInteger(options.retryDelayMs ?? 100, 0, 5_000, "retryDelayMs");
+        let lastError;
+        for (let attempt = 1; attempt <= maxStartAttempts; attempt += 1) {
+            const child = await this.startChild(name, request, handlers, signal);
+            try {
+                await child.ready;
+                return child;
+            }
+            catch (error) {
+                lastError = error;
+                await child.result.catch(() => undefined);
+                if (!isRetryableStartFailure(error) || attempt === maxStartAttempts)
+                    throw error;
+                if (signal?.aborted)
+                    throw cancellationError(signal);
+                if (retryDelayMs > 0)
+                    await wait(retryDelayMs * attempt);
+            }
+        }
+        throw lastError;
+    }
+    async stopChild(name, generation, fencingToken, reason = "Forge stopped the supervised child.") {
+        this.assertFence(fencingToken);
+        const record = this.currentByName.get(name);
+        if (!record || record.generation !== generation) {
+            throw new Error(`attempt_process_supervisor_stale: child '${name}' generation ${generation} is no longer current.`);
+        }
+        if (!terminalChildStatuses.has(record.status)) {
+            record.status = "stopping";
+            record.controller.abort(reason);
+            await this.persist();
+        }
+        return await record.result;
+    }
+    async stopAll(fencingToken, reason = "Forge stopped the supervised attempt.") {
+        this.assertFence(fencingToken);
+        // The durable terminal ledger is part of the stop operation's contract.
+        // Join an in-flight stop before inspecting terminal state so lease cleanup
+        // cannot remove the log directory underneath its final persistence.
+        if (this.stopOperation)
+            return await this.stopOperation;
+        if (this.status === "stopped")
+            return;
+        const operation = this.performStopAll(reason);
+        this.stopOperation = operation;
+        void operation.catch(() => undefined).finally(() => {
+            if (this.stopOperation === operation && this.status !== "stopped")
+                this.stopOperation = null;
+        });
+        return await this.stopOperation;
+    }
+    async performStopAll(reason) {
+        this.status = "stopping";
+        this.attemptController.abort(reason);
+        const active = [...this.currentByName.values()].filter(record => !terminalChildStatuses.has(record.status));
+        for (const record of active)
+            record.status = "stopping";
+        await this.persist();
+        const results = await Promise.allSettled(active.map(record => record.result));
+        const rejected = results.flatMap((result, index) => result.status === "rejected"
+            ? [sanitizeFailureError(result.reason, active[index].failureRedactionValues)]
+            : []);
+        const terminalStatus = rejected.length > 0 || this.persistenceFailure !== undefined ? "degraded" : "stopped";
+        await this.persist({
+            ...this.snapshot(),
+            status: terminalStatus,
+            updatedAt: new Date().toISOString(),
+        });
+        this.status = terminalStatus;
+        if (rejected.length > 0) {
+            throw new AggregateError(rejected, "attempt_process_supervisor_cleanup_degraded");
+        }
+        if (this.persistenceFailure !== undefined)
+            throw this.persistenceFailure;
+    }
+    snapshot() {
+        return {
+            schemaVersion: 1,
+            attemptSupervisorId: this.identity.processSupervisorId,
+            dispatchAttemptId: this.identity.dispatchAttemptId,
+            executionLeaseId: this.identity.executionLeaseId,
+            status: this.status,
+            updatedAt: new Date().toISOString(),
+            children: this.records.map(record => ({
+                name: record.name,
+                generation: record.generation,
+                childId: record.childId,
+                processSupervisorId: record.processSupervisorId,
+                metadataPath: record.metadataPath,
+                status: record.status,
+                startedAt: record.startedAt,
+                ...(record.settledAt ? { settledAt: record.settledAt } : {}),
+                ...(record.exitCode === undefined ? {} : { exitCode: record.exitCode }),
+                ...(record.failure ? { failure: record.failure } : {}),
+                ...(record.peakMemoryBytes === undefined ? {} : { peakMemoryBytes: record.peakMemoryBytes }),
+                ...(record.memorySampleCount === undefined ? {} : { memorySampleCount: record.memorySampleCount }),
+                ...(record.memorySource ? { memorySource: record.memorySource } : {}),
+                ...(record.memoryObservedAt ? { memoryObservedAt: record.memoryObservedAt } : {}),
+            })),
+        };
+    }
+    providerMemoryTelemetry() {
+        const observations = this.records
+            .filter(record => record.name === "provider"
+            && record.peakMemoryBytes !== undefined
+            && record.peakMemoryBytes > 0
+            && record.memorySampleCount !== undefined
+            && record.memorySampleCount > 0
+            && record.memorySource
+            && record.memoryObservedAt);
+        if (observations.length === 0)
+            return null;
+        const peak = observations.reduce((current, candidate) => (candidate.peakMemoryBytes ?? 0) > (current.peakMemoryBytes ?? 0) ? candidate : current);
+        return {
+            peakMemoryBytes: peak.peakMemoryBytes,
+            sampleCount: observations.reduce((total, candidate) => total + (candidate.memorySampleCount ?? 0), 0),
+            source: peak.memorySource,
+            observedAt: peak.memoryObservedAt,
+        };
+    }
+    async observeChildReady(record) {
+        const deadline = Date.now() + this.metadataReadyTimeoutMs;
+        while (Date.now() <= deadline) {
+            if (await fileExists(record.metadataPath)) {
+                if (record.status === "starting") {
+                    record.status = "running";
+                    await this.persist();
+                }
+                return;
+            }
+            if (terminalChildStatuses.has(record.status)) {
+                const detail = await childStartFailureDetail(record);
+                throw new ForgeFailureError("attempt_process_supervisor_start_failed", `attempt_process_supervisor_start_failed: child '${record.childId}' exited before supervision metadata was produced${detail ? `: ${detail}` : "."}`, "bridge");
+            }
+            await wait(25);
+        }
+        record.controller.abort("Supervised child metadata was not produced before the readiness deadline.");
+        const detail = await childStartFailureDetail(record);
+        throw new ForgeFailureError("attempt_process_supervisor_start_timeout", `attempt_process_supervisor_start_timeout: child '${record.childId}' did not become supervised${detail ? `: ${detail}` : "."}`, "bridge");
+    }
+    async settleChild(record, status, exitCode, failure, result) {
+        record.status = status;
+        record.settledAt = new Date().toISOString();
+        record.exitCode = exitCode;
+        record.failure = failure === undefined
+            ? undefined
+            : boundedFailure(failure, record.failureRedactionValues);
+        if (result?.peakMemoryBytes !== undefined
+            && result.peakMemoryBytes > 0
+            && result.memorySampleCount !== undefined
+            && result.memorySampleCount > 0
+            && result.memorySource
+            && result.memoryObservedAt) {
+            record.peakMemoryBytes = result.peakMemoryBytes;
+            record.memorySampleCount = result.memorySampleCount;
+            record.memorySource = result.memorySource;
+            record.memoryObservedAt = result.memoryObservedAt;
+        }
+        await this.persist().catch(error => {
+            this.persistenceFailure ??= error;
+            this.status = "degraded";
+        });
+    }
+    assertFence(fencingToken) {
+        if (fencingToken !== this.identity.fencingToken) {
+            throw new Error("attempt_process_supervisor_fenced: fencing token does not own this attempt.");
+        }
+    }
+    persist(snapshot = this.snapshot()) {
+        const operation = this.persistTail.then(async () => {
+            await ensurePrivateDirectory(this.identity.logDirectory);
+            const temporary = `${this.ledgerPath}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+            try {
+                const handle = await fs.open(temporary, "wx", 0o600);
+                try {
+                    await handle.writeFile(`${JSON.stringify(snapshot)}\n`);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                await fs.rename(temporary, this.ledgerPath);
+            }
+            catch (error) {
+                await fs.rm(temporary, { force: true }).catch(() => undefined);
+                throw error;
+            }
+        });
+        this.persistTail = operation.catch(() => undefined);
+        return operation;
+    }
+}
+function validateIdentity(identity) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u.test(identity.processSupervisorId)) {
+        throw new Error("attempt_process_supervisor_invalid: process supervisor id is invalid.");
+    }
+    assertUuid(identity.dispatchAttemptId, "dispatch attempt");
+    assertUuid(identity.executionLeaseId, "execution lease");
+    assertUuid(identity.fencingToken, "fencing token");
+    if (!path.isAbsolute(identity.logDirectory)) {
+        throw new Error("attempt_process_supervisor_invalid: log directory must be absolute.");
+    }
+    return { ...identity, logDirectory: path.resolve(identity.logDirectory) };
+}
+function assertChildName(name) {
+    if (!/^[a-z][a-z0-9_-]{0,31}$/u.test(name)) {
+        throw new Error("attempt_process_supervisor_invalid: child name must be a safe lowercase identifier.");
+    }
+}
+function childProcessSupervisorId(attemptSupervisorId, childId) {
+    const digest = createHash("sha256")
+        .update(JSON.stringify([attemptSupervisorId, childId]))
+        .digest("hex")
+        .slice(0, 32);
+    return `host-${digest}`;
+}
+function assertUuid(value, label) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(value)) {
+        throw new Error(`attempt_process_supervisor_invalid: ${label} id must be a UUID.`);
+    }
+}
+function boundedInteger(value, minimum, maximum, name) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`attempt_process_supervisor_invalid: ${name} must be between ${minimum} and ${maximum}.`);
+    }
+    return value;
+}
+function boundedFailure(error, exactSecrets = []) {
+    const message = sanitizeFailureError(error, exactSecrets).message;
+    return message.replaceAll(/[\r\n\t]+/gu, " ").slice(0, 512);
+}
+async function childStartFailureDetail(record) {
+    try {
+        const result = await record.result;
+        const stderr = boundedDiagnostic(result.stderr, record.failureRedactionValues);
+        return stderr
+            ? `exit ${result.exitCode}; stderr: ${stderr}`
+            : `exit ${result.exitCode}`;
+    }
+    catch (error) {
+        return boundedFailure(error, record.failureRedactionValues);
+    }
+}
+function boundedDiagnostic(value, exactSecrets = []) {
+    return sanitizeFailureError(value, exactSecrets).message
+        .replaceAll(/[\r\n\t]+/gu, " ")
+        .trim()
+        .slice(0, 512);
+}
+function isRetryableStartFailure(error) {
+    return error instanceof ForgeFailureError
+        && (error.failureCode === "attempt_process_supervisor_start_failed"
+            || error.failureCode === "attempt_process_supervisor_start_timeout");
+}
+function cancellationError(signal) {
+    return new Error(String(signal.reason ?? "Supervised child launch was cancelled."));
+}
+async function ensurePrivateDirectory(directory) {
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32")
+        await fs.chmod(directory, 0o700);
+}
+async function fileExists(target) {
+    return await fs.stat(target).then(() => true, () => false);
+}
+function wait(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}

package/dist/runtime/canonical-source-file.d.ts

@@ -0,0 +1,3 @@
+import type { PinnedDirectoryIdentity } from "./pinned-directory-process.js";
+/** Keep the validated source inode open: reopening a checked pathname can follow a replacement. */
+export declare function readCanonicalSourceFile(target: string, maximumBytes: number, expectedIdentity?: PinnedDirectoryIdentity): Promise<Buffer>;