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

package/dist/bridge/bridge.types.d.ts

@@ -1,6 +1,9 @@
 import type { ApiKeySecretGrant, DispatchSandboxResourceRequest, RunOnceResultPacket, RunnerDispatchEvent } from "../session/session.types.js";
 import type { SandboxFeatureMatrix } from "../sandbox/sandbox.types.js";
 import type { HostRuntimeCapacitySnapshot } from "../runtime/host-runtime-lease.js";
+import type { MemoryAdmissionDiagnostics } from "../runtime/memory-capacity.js";
+import type { DockerEngineCapabilitySnapshot } from "../runtime/docker-engine-probe.js";
+import type { BridgeChatCapability, ChatTurnCancelPacket } from "./bridge-chat.types.js";
 export interface BridgeServiceConfig {
     readonly serverUrl: string;
     readonly runnerId: string;
@@ -14,7 +17,12 @@ export interface BridgeServiceConfig {
     readonly sandboxPublicationMode?: "bridge_push" | "shared_filesystem";
     readonly dockerExecutable: string;
     readonly dockerContext: string;
+    readonly dockerDesktopRecoveryEnabled: boolean;
+    readonly dockerRecoveryFailureThreshold: number;
+    readonly dockerRecoveryCooldownMs: number;
+    readonly dockerRecoveryStartupTimeoutMs: number;
     readonly sandboxStateRoot: string;
+    readonly sandboxExecutionRoot: string;
     readonly requireRootlessDocker: boolean;
     readonly diskHighWatermarkPercent: number;
     readonly diskLowWatermarkPercent: number;
@@ -45,10 +53,13 @@ export interface BridgeServiceConfig {
     readonly supportsDraftRunOnce: boolean;
     readonly supportsDraftAttachments: boolean;
     readonly supportsDraftImageAttachments: boolean;
+    readonly bridgeChat: BridgeChatCapability;
     readonly version: string;
     readonly protocolVersion: number;
     readonly minServerVersion?: string | null;
     readonly heartbeatIntervalMs: number;
+    readonly callbackAckTimeoutMs?: number;
+    readonly heartbeatDockerProbeWaitMs?: number;
     readonly reconnectBackoffMs: readonly number[];
 }
 export interface BridgeRepoMapping {
@@ -72,6 +83,20 @@ export interface BridgeProviderStatus {
     readonly version?: string | null;
     readonly models?: readonly string[] | null;
 }
+export interface BridgeToolCapability {
+    readonly available: boolean;
+    readonly executable: string;
+    readonly version?: string | null;
+}
+export interface BridgeToolchainCapabilities {
+    readonly node: BridgeToolCapability;
+    readonly pnpm: BridgeToolCapability;
+    readonly dotnet: BridgeToolCapability;
+    readonly git: BridgeToolCapability;
+    readonly bash: BridgeToolCapability;
+    readonly powershell: BridgeToolCapability;
+    readonly docker?: BridgeToolCapability | null;
+}
 export interface BridgeCapabilities {
     readonly schemaVersion?: number | null;
     readonly activeSessionCount?: number | null;
@@ -83,6 +108,8 @@ export interface BridgeCapabilities {
     readonly sandboxProfiles?: readonly string[] | null;
     readonly runnerInstanceId?: string | null;
     readonly trustDomainId?: string | null;
+    readonly executionFacilities?: readonly string[] | null;
+    readonly dockerEngine?: DockerEngineCapabilitySnapshot | null;
     readonly sandboxRuntimes?: readonly string[] | null;
     readonly sandboxRuntimeVersion?: string | null;
     readonly sandboxFeatures?: SandboxFeatureMatrix | null;
@@ -110,6 +137,11 @@ export interface BridgeCapabilities {
     readonly supportsDraftRunOnce?: boolean | null;
     readonly supportsDraftAttachments?: boolean | null;
     readonly supportsDraftImageAttachments?: boolean | null;
+    readonly bridgeChat?: BridgeChatCapability | null;
+    readonly toolchains?: BridgeToolchainCapabilities | null;
+    readonly playwrightProjects?: readonly string[] | null;
+    readonly browserLaunch?: boolean | null;
+    readonly providerConnectivity?: Readonly<Record<string, boolean>> | null;
 }
 export interface SandboxMemoryCapacityDiagnostics {
     readonly defaultWorkerMemoryLimitBytes: number;
@@ -119,7 +151,10 @@ export interface SandboxMemoryCapacityDiagnostics {
     readonly activeReservationBytes: number;
     readonly daemonTotalBytes: number;
     readonly daemonAvailableBytes: number;
+    readonly hostAvailableBytes: number;
+    readonly conservativeAvailableBytes: number;
     readonly availableForAdmissionBytes: number;
+    readonly memoryAdmission: MemoryAdmissionDiagnostics;
 }
 export interface BridgeHelloRequest {
     readonly version: string;
@@ -200,7 +235,9 @@ export interface BridgeLeaseUpdateRequest {
     readonly runnerInstanceId: string;
     readonly expiresAt: string;
 }
-export interface BridgeCancelRequest {
+export interface BridgeCancelRequest extends ChatTurnCancelPacket {
+    /** When present, cancels only this pre-start reservation, never an active session. */
+    readonly dispatchAttemptId?: string | null;
     readonly leaseId: string;
     readonly fencingToken: string;
     readonly reason?: string | null;
@@ -223,6 +260,7 @@ export interface BridgeAttemptSnapshotResponse extends BridgeCallbackAck {
     readonly generatedAt?: string | null;
 }
 export type BridgeDispatchHandler = (dispatch: unknown) => Promise<void>;
+export type BridgeChatTurnHandler = (dispatch: unknown) => Promise<void>;
 export type BridgeOfferHandler = (dispatch: unknown) => Promise<void>;
 export type BridgeStartHandler = (dispatch: unknown) => Promise<void>;
 export type BridgeLeaseUpdateHandler = (request: BridgeLeaseUpdateRequest) => Promise<void>;
@@ -259,6 +297,13 @@ export interface BridgeRuntimeReadinessResult {
     readonly qaAppLaunchTarget?: BridgeRuntimeReadinessQaLaunchTarget | null;
     readonly checkedAt: string;
 }
+export interface BridgeRuntimeReadinessAccepted {
+    readonly schemaVersion: 1;
+    readonly requestId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly acceptedAt: string;
+}
 export interface BridgeRuntimeReadinessQaLaunchTarget {
     readonly managedRuntimePort: string;
     readonly routes: readonly string[];

package/dist/bridge/dispatch-result-outbox.d.ts

@@ -0,0 +1,25 @@
+import type { BridgeDispatchResultCallback } from "./bridge.types.js";
+export interface DurableDispatchResult {
+    readonly schemaVersion: 1;
+    readonly persistedAt: string;
+    readonly payload: BridgeDispatchResultCallback;
+}
+export interface DispatchResultOutbox {
+    persist(payload: BridgeDispatchResultCallback): Promise<void>;
+    pending(): Promise<readonly DurableDispatchResult[]>;
+    acknowledge(leaseId: string): Promise<void>;
+}
+/**
+ * Persists the already-redacted terminal result before the Bridge attempts its
+ * SignalR callback. A transport or API restart can therefore delay delivery,
+ * but cannot turn successful provider work into a fabricated failed result.
+ */
+export declare class FileDispatchResultOutbox implements DispatchResultOutbox {
+    private readonly stateRoot;
+    private readonly writes;
+    constructor(stateRoot: string);
+    persist(payload: BridgeDispatchResultCallback): Promise<void>;
+    pending(): Promise<readonly DurableDispatchResult[]>;
+    acknowledge(leaseId: string): Promise<void>;
+    private operate;
+}

package/dist/bridge/dispatch-result-outbox.js

@@ -0,0 +1,62 @@
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { assertCanonicalDirectory, createCanonicalDirectory } from "../runtime/attempt-private-directory.js";
+import { runPinnedDirectoryProcess } from "../runtime/pinned-directory-process.js";
+import { dispatchResultReceiptWorker } from "./dispatch-result-worker.js";
+/**
+ * Persists the already-redacted terminal result before the Bridge attempts its
+ * SignalR callback. A transport or API restart can therefore delay delivery,
+ * but cannot turn successful provider work into a fabricated failed result.
+ */
+export class FileDispatchResultOutbox {
+    stateRoot;
+    writes = new Map();
+    constructor(stateRoot) {
+        this.stateRoot = stateRoot;
+    }
+    async persist(payload) {
+        const name = recordName(payload.leaseId);
+        const value = JSON.parse(JSON.stringify({ payload }));
+        const pending = this.writes.get(name);
+        if (pending) {
+            if (!isDeepStrictEqual(pending.value, value)) {
+                throw new Error("dispatch_result_conflict: lease identity reused with a different result.");
+            }
+            return await pending.write;
+        }
+        const write = this.operate({
+            kind: "persist",
+            name,
+            record: { schemaVersion: 1, persistedAt: new Date().toISOString(), ...value },
+        }).then(() => undefined);
+        this.writes.set(name, { value, write });
+        try {
+            await write;
+        }
+        finally {
+            if (this.writes.get(name)?.write === write)
+                this.writes.delete(name);
+        }
+    }
+    async pending() {
+        return JSON.parse(await this.operate({ kind: "pending" }));
+    }
+    async acknowledge(leaseId) {
+        await this.operate({ kind: "acknowledge", name: recordName(leaseId) });
+    }
+    async operate(operation) {
+        const root = path.resolve(this.stateRoot, "dispatch-results");
+        await createCanonicalDirectory(root);
+        const identity = await assertCanonicalDirectory(root);
+        if (!identity)
+            throw new Error("dispatch_result_invalid: outbox directory is missing.");
+        return await runPinnedDirectoryProcess(root, identity, dispatchResultReceiptWorker, operation, undefined, 256 * 1024 * 1024);
+    }
+}
+function recordName(leaseId) {
+    const value = leaseId.replaceAll("-", "").toLowerCase();
+    if (!/^[0-9a-f]{32}$/u.test(value)) {
+        throw new Error("dispatch_result_invalid: lease id must be a UUID.");
+    }
+    return `${value}.json`;
+}

package/dist/bridge/dispatch-result-worker.d.ts

@@ -0,0 +1,2 @@
+/** Runs in a bounded async child. Receipt IO stays relative to verified, pinned cwd. */
+export declare const dispatchResultReceiptWorker: string;

package/dist/bridge/dispatch-result-worker.js

@@ -0,0 +1,122 @@
+/** Runs in a bounded async child. Receipt IO stays relative to verified, pinned cwd. */
+export const dispatchResultReceiptWorker = String.raw `
+const fs = require('node:fs');
+const { randomUUID } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+const job = JSON.parse(fs.readFileSync(0, 'utf8'));
+const maximumBytes = 64 * 1024 * 1024;
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const sameReadMetadata = (a, b) => a.size === b.size && a.mtimeNs === b.mtimeNs
+  && a.mode === b.mode && a.uid === b.uid && a.gid === b.gid && a.birthtimeNs === b.birthtimeNs;
+const samePublicationMetadata = (a, b) => a.ctimeNs === b.ctimeNs && a.nlink === b.nlink;
+const validDate = value => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const uuid = value => typeof value === 'string' && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(value);
+const validName = name => typeof name === 'string' && /^[0-9a-f]{32}\.json$/.test(name);
+const validRecord = (record, name) => record && record.schemaVersion === 1
+  && validDate(record.persistedAt) && record.payload
+  && uuid(record.payload.leaseId) && uuid(record.payload.fencingToken)
+  && (record.payload.dispatchAttemptId == null || uuid(record.payload.dispatchAttemptId))
+  && (record.payload.runnerInstanceId == null || uuid(record.payload.runnerInstanceId))
+  && record.payload.result && Number.isInteger(record.payload.result.exitCode)
+  && typeof record.payload.result.summary === 'string'
+  && Array.isArray(record.payload.result.events)
+  && record.payload.leaseId.replaceAll('-', '').toLowerCase() + '.json' === name;
+const read = name => {
+  if (!validName(name)) throw new Error('dispatch_result_invalid: invalid name');
+  let before;
+  try { before = fs.lstatSync(name, { bigint: true }); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  if (!before.isFile() || before.isSymbolicLink() || before.size > BigInt(maximumBytes))
+    throw new Error('dispatch_result_invalid: not a bounded regular file');
+  const fd = fs.openSync(name, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+  try {
+    const opened = fs.fstatSync(fd, { bigint: true });
+    if (!same(before, opened) || !opened.isFile() || opened.size !== before.size)
+      throw new Error('dispatch_result_invalid: receipt identity changed');
+    let baseline = opened;
+    let firstRead;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const bytes = Buffer.alloc(Number(opened.size));
+      let offset = 0;
+      while (offset < bytes.length) {
+        const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+        if (!count) throw new Error('dispatch_result_invalid: incomplete receipt');
+        offset += count;
+      }
+      const after = fs.fstatSync(fd, { bigint: true });
+      const current = fs.lstatSync(name, { bigint: true });
+      if (!same(opened, after) || !same(after, current) || !current.isFile() || current.isSymbolicLink()
+        || !sameReadMetadata(baseline, after) || !sameReadMetadata(after, current))
+        throw new Error('dispatch_result_invalid: receipt changed during read');
+      if (!samePublicationMetadata(baseline, after) || !samePublicationMetadata(after, current)) {
+        // A publisher may unlink its temporary hard link between either stat.
+        // This is only a retry fence, never permission to trust unstable bytes.
+        if (attempt !== 0 || job.kind !== 'persist' || baseline.nlink !== 2n || current.nlink !== 1n
+          || baseline.ctimeNs === current.ctimeNs
+          || (!samePublicationMetadata(baseline, after) && !samePublicationMetadata(after, current)))
+          throw new Error('dispatch_result_invalid: receipt changed during read');
+        firstRead = bytes;
+        baseline = current;
+        continue;
+      }
+      if (firstRead && !bytes.equals(firstRead))
+        throw new Error('dispatch_result_invalid: receipt changed during read');
+      const record = JSON.parse(bytes.toString('utf8'));
+      if (!validRecord(record, name)) throw new Error('dispatch_result_invalid: malformed or wrong identity');
+      return record;
+    }
+    throw new Error('dispatch_result_invalid: receipt changed during read');
+  } finally { fs.closeSync(fd); }
+};
+const identical = (existing, candidate) => {
+  if (!isDeepStrictEqual(existing.payload, candidate.payload))
+    throw new Error('dispatch_result_conflict: lease identity reused with a different result');
+};
+try {
+  const cwd = fs.statSync('.', { bigint: true });
+  const real = fs.realpathSync('.');
+  if (!same(cwd, { dev: BigInt(job.dev), ino: BigInt(job.ino) })
+    || (process.platform === 'win32' ? real.toLowerCase() !== job.parent.toLowerCase() : real !== job.parent))
+    throw new Error('dispatch_result_invalid: parent identity changed');
+  if (job.kind === 'persist') {
+    if (!validName(job.name) || !validRecord(job.record, job.name)) throw new Error('dispatch_result_invalid: invalid candidate');
+    const content = JSON.stringify(job.record) + '\n';
+    if (Buffer.byteLength(content) > maximumBytes) throw new Error('dispatch_result_invalid: receipt too large');
+    const existing = read(job.name);
+    if (existing) identical(existing, job.record);
+    else {
+      const temporary = job.name + '.' + randomUUID() + '.tmp';
+      let owned = false;
+      try {
+        const fd = fs.openSync(temporary, 'wx', 0o600);
+        owned = true;
+        try { fs.writeFileSync(fd, content, 'utf8'); fs.fsyncSync(fd); }
+        finally { fs.closeSync(fd); }
+        try { fs.linkSync(temporary, job.name); }
+        catch (error) {
+          if (error.code !== 'EEXIST') throw error;
+          const winner = read(job.name);
+          if (!winner) throw error;
+          identical(winner, job.record);
+        }
+      } finally { if (owned) fs.unlinkSync(temporary); }
+    }
+  } else if (job.kind === 'pending') {
+    const records = [];
+    const directory = fs.opendirSync('.');
+    try {
+      let entry;
+      while (records.length < 3 && (entry = directory.readSync()) !== null) {
+        if (!entry.isFile() || !validName(entry.name)) continue;
+        try { const record = read(entry.name); if (record) records.push(record); }
+        catch { /* Retain malformed evidence; never send it as a trusted callback. */ }
+      }
+    } finally { directory.closeSync(); }
+    records.sort((a, b) => a.persistedAt.localeCompare(b.persistedAt));
+    process.stdout.write(JSON.stringify(records));
+  } else if (job.kind === 'acknowledge') {
+    if (!validName(job.name)) throw new Error('dispatch_result_invalid: invalid name');
+    try { fs.unlinkSync(job.name); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  } else throw new Error('dispatch_result_invalid: invalid operation');
+} catch (error) { process.stderr.write(error.message); process.exitCode = 1; }
+`;

package/dist/bridge/internals.d.ts

@@ -1,3 +1,5 @@
 export { SignalRBridgeConnection, SignalRBridgeConnectionFactory, defaultBridgeServiceConfig } from "./bridge.service.js";
+export { bridgeChatProtocolVersion, bridgeChatUpdateRequiredCode, normalizeBridgeChatCapability, parseChatTurnDispatchPacket, unavailableBridgeChatCapability } from "./bridge-chat.types.js";
 export type { BridgeConnection, BridgeConnectionFactory } from "./bridge.base.js";
+export type { BridgeChatCapability, ChatTurnDispatchPacket } from "./bridge-chat.types.js";
 export type { BridgeCallbackAck, BridgeCancelHandler, BridgeCancelRequest, BridgeCapabilities, BridgeDispatchEventCallback, BridgeDispatchHandler, BridgeDispatchResultCallback, BridgeHeartbeatRequest, BridgeHelloRequest, BridgeRepoMapping, BridgeServiceConfig } from "./bridge.types.js";

package/dist/bridge/internals.js

@@ -1 +1,2 @@
 export { SignalRBridgeConnection, SignalRBridgeConnectionFactory, defaultBridgeServiceConfig } from "./bridge.service.js";
+export { bridgeChatProtocolVersion, bridgeChatUpdateRequiredCode, normalizeBridgeChatCapability, parseChatTurnDispatchPacket, unavailableBridgeChatCapability } from "./bridge-chat.types.js";

package/dist/bridge/readiness-result-outbox.d.ts

@@ -0,0 +1,21 @@
+import type { BridgeRuntimeReadinessResult } from "./bridge.types.js";
+export interface DurableReadinessResult {
+    readonly schemaVersion: 1;
+    readonly expiresAt: string;
+    readonly persistedAt: string;
+    readonly result: BridgeRuntimeReadinessResult;
+}
+export interface ReadinessResultOutbox {
+    persist(result: BridgeRuntimeReadinessResult, expiresAt: string): Promise<void>;
+    pending(): Promise<readonly DurableReadinessResult[]>;
+    acknowledge(requestId: string): Promise<void>;
+}
+export declare class FileReadinessResultOutbox implements ReadinessResultOutbox {
+    private readonly stateRoot;
+    private readonly writes;
+    constructor(stateRoot: string);
+    persist(result: BridgeRuntimeReadinessResult, expiresAt: string): Promise<void>;
+    pending(): Promise<readonly DurableReadinessResult[]>;
+    acknowledge(requestId: string): Promise<void>;
+    private operate;
+}

package/dist/bridge/readiness-result-outbox.js

@@ -0,0 +1,54 @@
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { assertCanonicalDirectory, createCanonicalDirectory } from "../runtime/attempt-private-directory.js";
+import { runPinnedDirectoryProcess } from "../runtime/pinned-directory-process.js";
+import { readinessReceiptWorker } from "./readiness-result-worker.js";
+export class FileReadinessResultOutbox {
+    stateRoot;
+    writes = new Map();
+    constructor(stateRoot) {
+        this.stateRoot = stateRoot;
+    }
+    async persist(result, expiresAt) {
+        const name = recordName(result.requestId);
+        // Capture caller-owned data before yielding. Compare semantic JSON, not key order.
+        const value = JSON.parse(JSON.stringify({ result, expiresAt }));
+        const pending = this.writes.get(name);
+        if (pending) {
+            if (!isDeepStrictEqual(pending.value, value))
+                throw new Error("runtime_readiness_result_conflict: request identity reused.");
+            return await pending.write;
+        }
+        const write = this.operate({ kind: "persist", name, record: {
+                schemaVersion: 1, persistedAt: new Date().toISOString(), ...value,
+            } }).then(() => undefined);
+        this.writes.set(name, { value, write });
+        try {
+            await write;
+        }
+        finally {
+            if (this.writes.get(name)?.write === write)
+                this.writes.delete(name);
+        }
+    }
+    async pending() {
+        return JSON.parse(await this.operate({ kind: "pending" }));
+    }
+    async acknowledge(requestId) {
+        await this.operate({ kind: "acknowledge", name: recordName(requestId) });
+    }
+    async operate(operation) {
+        const root = path.resolve(this.stateRoot, "readiness-results");
+        await createCanonicalDirectory(root);
+        const identity = await assertCanonicalDirectory(root);
+        if (!identity)
+            throw new Error("runtime_readiness_result_invalid: outbox directory is missing.");
+        return await runPinnedDirectoryProcess(root, identity, readinessReceiptWorker, operation, undefined, 256 * 256 * 1024 + 1024);
+    }
+}
+function recordName(requestId) {
+    const value = requestId.replaceAll("-", "").toLowerCase();
+    if (!/^[0-9a-f]{32}$/u.test(value))
+        throw new Error("runtime_readiness_result_invalid: request id must be a UUID.");
+    return `${value}.json`;
+}

package/dist/bridge/readiness-result-worker.d.ts

@@ -0,0 +1,2 @@
+/** Runs in a bounded async child. Receipt IO stays relative to verified, pinned cwd. */
+export declare const readinessReceiptWorker: string;

package/dist/bridge/readiness-result-worker.js

@@ -0,0 +1,121 @@
+/** Runs in a bounded async child. Receipt IO stays relative to verified, pinned cwd. */
+export const readinessReceiptWorker = String.raw `
+const fs = require('node:fs');
+const { randomUUID } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+const job = JSON.parse(fs.readFileSync(0, 'utf8'));
+const maximumBytes = 256 * 1024;
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const sameReadMetadata = (a, b) => a.size === b.size && a.mtimeNs === b.mtimeNs
+  && a.mode === b.mode && a.uid === b.uid && a.gid === b.gid && a.birthtimeNs === b.birthtimeNs;
+const samePublicationMetadata = (a, b) => a.ctimeNs === b.ctimeNs && a.nlink === b.nlink;
+const validDate = value => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const uuid = value => typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+const validName = name => typeof name === 'string' && /^[0-9a-f]{32}\.json$/.test(name);
+const validRecord = (record, name) => record && record.schemaVersion === 1
+  && validDate(record.expiresAt) && validDate(record.persistedAt) && record.result
+  && record.result.schemaVersion === 1 && uuid(record.result.requestId) && uuid(record.result.fencingToken)
+  && uuid(record.result.runnerInstanceId) && validDate(record.result.checkedAt)
+  && ['parallel_ready', 'serialized', 'failed'].includes(record.result.status)
+  && record.result.requestId.replaceAll('-', '').toLowerCase() + '.json' === name;
+const read = name => {
+  if (!validName(name)) throw new Error('runtime_readiness_result_invalid: invalid name');
+  let before;
+  try { before = fs.lstatSync(name, { bigint: true }); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  // Atomic publishers may briefly hold their own second hard link until cleanup.
+  if (!before.isFile() || before.isSymbolicLink() || before.size > BigInt(maximumBytes))
+    throw new Error('runtime_readiness_result_invalid: not a bounded regular file');
+  const fd = fs.openSync(name, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+  try {
+    const opened = fs.fstatSync(fd, { bigint: true });
+    if (!same(before, opened) || !opened.isFile() || opened.size !== before.size)
+      throw new Error('runtime_readiness_result_invalid: receipt identity changed');
+    let baseline = opened;
+    let firstRead;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const bytes = Buffer.alloc(Number(opened.size));
+      let offset = 0;
+      while (offset < bytes.length) {
+        const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+        if (!count) throw new Error('runtime_readiness_result_invalid: incomplete receipt');
+        offset += count;
+      }
+      const after = fs.fstatSync(fd, { bigint: true });
+      const current = fs.lstatSync(name, { bigint: true });
+      if (!same(opened, after) || !same(after, current) || !current.isFile() || current.isSymbolicLink()
+        || !sameReadMetadata(baseline, after) || !sameReadMetadata(after, current))
+        throw new Error('runtime_readiness_result_invalid: receipt changed during read');
+      if (!samePublicationMetadata(baseline, after) || !samePublicationMetadata(after, current)) {
+        // A publisher may unlink its temporary hard link between either stat.
+        // This is only a retry fence, never permission to trust unstable bytes.
+        if (attempt !== 0 || job.kind !== 'persist' || baseline.nlink !== 2n || current.nlink !== 1n
+          || baseline.ctimeNs === current.ctimeNs
+          || (!samePublicationMetadata(baseline, after) && !samePublicationMetadata(after, current)))
+          throw new Error('runtime_readiness_result_invalid: receipt changed during read');
+        firstRead = bytes;
+        baseline = current;
+        continue;
+      }
+      if (firstRead && !bytes.equals(firstRead))
+        throw new Error('runtime_readiness_result_invalid: receipt changed during read');
+      const record = JSON.parse(bytes.toString('utf8'));
+      if (!validRecord(record, name)) throw new Error('runtime_readiness_result_invalid: malformed or wrong identity');
+      return record;
+    }
+    throw new Error('runtime_readiness_result_invalid: receipt changed during read');
+  } finally { fs.closeSync(fd); }
+};
+const identical = (existing, candidate) => {
+  if (!isDeepStrictEqual(existing.result, candidate.result) || existing.expiresAt !== candidate.expiresAt)
+    throw new Error('runtime_readiness_result_conflict: request identity reused');
+};
+try {
+  const cwd = fs.statSync('.', { bigint: true });
+  const real = fs.realpathSync('.');
+  if (!same(cwd, { dev: BigInt(job.dev), ino: BigInt(job.ino) })
+    || (process.platform === 'win32' ? real.toLowerCase() !== job.parent.toLowerCase() : real !== job.parent))
+    throw new Error('runtime_readiness_result_invalid: parent identity changed');
+  if (job.kind === 'persist') {
+    if (!validName(job.name) || !validRecord(job.record, job.name)) throw new Error('runtime_readiness_result_invalid: invalid candidate');
+    const content = JSON.stringify(job.record) + '\n';
+    if (Buffer.byteLength(content) > maximumBytes) throw new Error('runtime_readiness_result_invalid: receipt too large');
+    const existing = read(job.name);
+    if (existing) identical(existing, job.record);
+    else {
+      const temporary = job.name + '.' + randomUUID() + '.tmp';
+      let owned = false;
+      try {
+        const fd = fs.openSync(temporary, 'wx', 0o600);
+        owned = true;
+        try { fs.writeFileSync(fd, content, 'utf8'); fs.fsyncSync(fd); }
+        finally { fs.closeSync(fd); }
+        try { fs.linkSync(temporary, job.name); }
+        catch (error) {
+          if (error.code !== 'EEXIST') throw error;
+          const winner = read(job.name);
+          if (!winner) throw error;
+          identical(winner, job.record);
+        }
+      } finally { if (owned) fs.unlinkSync(temporary); }
+    }
+  } else if (job.kind === 'pending') {
+    const records = [];
+    const directory = fs.opendirSync('.');
+    try {
+      let entry;
+      while (records.length < 256 && (entry = directory.readSync()) !== null) {
+        if (!entry.isFile() || !validName(entry.name)) continue;
+        try { const record = read(entry.name); if (record) records.push(record); }
+        catch { /* Retain malformed evidence; never send it as a trusted callback. */ }
+      }
+    } finally { directory.closeSync(); }
+    records.sort((a, b) => a.persistedAt.localeCompare(b.persistedAt));
+    process.stdout.write(JSON.stringify(records));
+  } else if (job.kind === 'acknowledge') {
+    if (!validName(job.name)) throw new Error('runtime_readiness_result_invalid: invalid name');
+    // unlink is relative to pinned cwd and never follows a replaced leaf link.
+    try { fs.unlinkSync(job.name); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  } else throw new Error('runtime_readiness_result_invalid: invalid operation');
+} catch (error) { process.stderr.write(error.message); process.exitCode = 1; }
+`;

package/dist/bridge/runner-host-capabilities.d.ts

@@ -0,0 +1,15 @@
+import type { BridgeServiceConfig, BridgeToolchainCapabilities } from "./bridge.types.js";
+export interface RunnerHostCapabilitySnapshot {
+    readonly toolchains: BridgeToolchainCapabilities;
+    readonly playwrightProjects: readonly string[];
+    readonly browserLaunch: boolean;
+    readonly providerConnectivity: Readonly<Record<string, boolean>>;
+}
+export interface RunnerHostCapabilityProbe {
+    detect(config: BridgeServiceConfig): Promise<RunnerHostCapabilitySnapshot>;
+}
+export declare class ProcessRunnerHostCapabilityProbe implements RunnerHostCapabilityProbe {
+    detect(config: BridgeServiceConfig): Promise<RunnerHostCapabilitySnapshot>;
+}
+export declare function isUnavailablePlaywrightConfigError(error: unknown): boolean;
+export declare function emptyRunnerHostCapabilitySnapshot(): RunnerHostCapabilitySnapshot;

package/dist/bridge/runner-host-capabilities.js

@@ -0,0 +1,93 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export class ProcessRunnerHostCapabilityProbe {
+    async detect(config) {
+        const [pnpm, dotnet, git, bash, pwsh, windowsPowerShell] = await Promise.all([
+            probe("pnpm", ["--version"]),
+            probe("dotnet", ["--version"]),
+            probe("git", ["--version"]),
+            probe("bash", ["--version"]),
+            probe("pwsh", ["-NoProfile", "-Command", "$PSVersionTable.PSVersion.ToString()"]),
+            process.platform === "win32"
+                ? probe("powershell.exe", ["-NoProfile", "-Command", "$PSVersionTable.PSVersion.ToString()"])
+                : Promise.resolve(unavailable("powershell.exe")),
+        ]);
+        const playwrightProjects = await detectPlaywrightProjects(config.repoMappings);
+        const browserLaunch = playwrightProjects.length > 0
+            || config.repoMappings.some(mapping => Boolean(mapping.qaAppLaunchTarget?.url
+                || mapping.qaAppLaunchTarget?.command
+                || mapping.qaAppLaunchTarget?.managed_runtime_port));
+        return {
+            toolchains: {
+                node: { available: true, executable: process.execPath, version: process.version },
+                pnpm,
+                dotnet,
+                git,
+                bash,
+                powershell: pwsh.available ? pwsh : windowsPowerShell,
+            },
+            playwrightProjects,
+            browserLaunch,
+            providerConnectivity: Object.fromEntries(Object.entries(config.providerStatuses)
+                .map(([provider, status]) => [provider, status.signedIn === true])),
+        };
+    }
+}
+async function probe(executable, args) {
+    try {
+        const result = await execFileAsync(executable, [...args], { encoding: "utf8", timeout: 5_000 });
+        const version = `${result.stdout || result.stderr}`.trim().split(/\r?\n/u)[0] ?? "";
+        return { available: true, executable, version };
+    }
+    catch {
+        return unavailable(executable);
+    }
+}
+function unavailable(executable) {
+    return { available: false, executable, version: null };
+}
+async function detectPlaywrightProjects(repoMappings) {
+    const projects = new Set();
+    for (const mapping of repoMappings) {
+        if (!mapping.localPath)
+            continue;
+        const candidates = [
+            "playwright.config.ts", "playwright.config.js", "playwright.config.mjs",
+            "tests/e2e/playwright.config.ts", "tests/e2e/playwright.config.js", "tests/e2e/playwright.config.mjs",
+        ];
+        for (const relative of candidates) {
+            try {
+                const source = await fs.readFile(path.join(mapping.localPath, relative), "utf8");
+                for (const match of source.matchAll(/\bname\s*:\s*["']([^"']+)["']/gu))
+                    projects.add(match[1]);
+            }
+            catch (error) {
+                if (!isUnavailablePlaywrightConfigError(error))
+                    throw error;
+            }
+        }
+    }
+    return [...projects].sort((left, right) => left.localeCompare(right));
+}
+export function isUnavailablePlaywrightConfigError(error) {
+    const code = error?.code;
+    return code === "ENOENT" || code === "EACCES" || code === "EPERM" || code === "ENOTDIR";
+}
+export function emptyRunnerHostCapabilitySnapshot() {
+    return {
+        toolchains: {
+            node: { available: true, executable: process.execPath, version: process.version },
+            pnpm: unavailable("pnpm"),
+            dotnet: unavailable("dotnet"),
+            git: unavailable("git"),
+            bash: unavailable("bash"),
+            powershell: unavailable(process.platform === "win32" ? "powershell.exe" : "pwsh"),
+        },
+        playwrightProjects: [],
+        browserLaunch: false,
+        providerConnectivity: {},
+    };
+}