@loucompanion/forge-bridge 0.1.3-dev.8687c5099dce → 0.1.3-dev.88e93f53db5b

package/README.md

@@ -101,7 +101,9 @@ Production shared runners require a Linux rootless Docker daemon. Docker Desktop
 - `FORGE_DOCKER_CONTEXT` / `FORGE_DOCKER_EXECUTABLE` — dedicated daemon selection.
 - `FORGE_SANDBOX_STATE_ROOT` — fsync'd attempt ledgers, restricted diagnostics, and build state.
 - `FORGE_DISK_HIGH_WATERMARK_PERCENT` / `FORGE_DISK_LOW_WATERMARK_PERCENT` / `FORGE_MINIMUM_WORKSPACE_BYTES` — admission watermarks with high/low hysteresis.
-- `FORGE_SANDBOX_HOST_MEMORY_RESERVE_BYTES` — host memory withheld from sandbox admission. The default is 2 GiB, or 1 GiB when Docker Desktop developer mode is explicitly enabled; production Linux/rootless runners retain 2 GiB unless an operator supplies a measured override.
+- Per-attempt workspace reservations are calculated from the repository source footprint, detected Node/.NET/browser toolchains, the execution role, and immutable sandbox app services. The API uses that request for local and Bridge placement; a Bridge rechecks its authoritative checkout and Docker contract before acceptance. Shared Docker images and package caches remain runner-level capacity, while `FORGE_MINIMUM_WORKSPACE_BYTES` remains a separate host safety reserve rather than a per-lane charge.
+- `FORGE_SANDBOX_HOST_MEMORY_RESERVE_BYTES` — explicit host-memory safety-reserve override for sandbox admission. Without an override, Forge derives a bounded reserve from the sampled capacity domain (Linux: 12.5%, 1–4 GiB; Docker Desktop development: 6.25%, 1–2 GiB). The floor, ceiling, and percentage are configurable with `FORGE_SANDBOX_HOST_MEMORY_RESERVE_FLOOR_BYTES`, `FORGE_SANDBOX_HOST_MEMORY_RESERVE_CEILING_BYTES`, and `FORGE_SANDBOX_HOST_MEMORY_RESERVE_PERCENT`.
+- Managed-host admission uses the same bounded 12.5% physical-memory policy through `FORGE_HOST_MEMORY_RESERVE_BYTES` or its `_FLOOR_BYTES`, `_CEILING_BYTES`, and `_PERCENT` controls. Pressure is applied immediately; recovery requires two samples one second apart by default (`FORGE_HOST_MEMORY_RECOVERY_SAMPLES` and `FORGE_HOST_MEMORY_RECOVERY_SAMPLE_INTERVAL_MS`). `FORGE_HOST_DEFAULT_WORKER_MEMORY_LIMIT_BYTES` configures only the conservative cold-start fallback for legacy packets that omit an exact worker request; current packets remain governed by their explicit role request.
 - `FORGE_SANDBOX_MEMORY_SAMPLE_INTERVAL_MS` — interval for sampled Docker peak-memory telemetry (default `1000` ms, clamped to `250`–`30000` ms). Sampling is diagnostic and never changes an attempt outcome.
 - `FORGE_SANDBOX_DEDICATED_DISK=true` — operator assertion that sandbox storage is on a dedicated, conservatively watermarked disk when the Docker storage driver cannot enforce per-volume quotas. `sandbox_required` fails placement unless either quota support or this assertion is advertised.
 - `FORGE_SANDBOX_IMAGE_RETENTION_COUNT` / `FORGE_SANDBOX_IMAGE_RETENTION_TTL_MS` — per-project image-cache retention (defaults: 3 images and 7 days).
@@ -131,6 +133,21 @@ In `bridge_push` mode, the start packet carries only an attempt/fence/branch-bou
 
 Failed project, tooling, and agent image stages preserve only a redacted, capped, mode-0600 diagnostic at `FORGE_SANDBOX_STATE_ROOT/build-logs/<image-key>/<stage>.log`. The event stream carries its digest, byte count, and truncation flag, never the log contents. Treat this directory as restricted source-bearing audit data and apply local retention controls.
 
+## Owned test evidence
+
+`npm test` closes a manifest over the complete Bridge source, test, runtime, configuration, workflow,
+and imported fixture set before compilation. It records the Git commit and exact Node, npm, Git, .NET,
+TypeScript, Vitest, OS, and temporary-root identities, compiles into an owned temporary root, runs
+Vitest through the Windows process-tree supervisor, revalidates the source and toolchain, independently
+rehashes the compiled output, and removes the exact owner root before reporting success.
+
+Set `FORGE_BRIDGE_SUITE_RECEIPT_PATH` to an absolute path for a nonexistent output file to retain the
+verified execution receipt. On Windows evidence runs, `TEMP`, `TMP`, `TMPDIR`, and `FORGE_TMPDIR` may
+point to the same short, empty, high-capacity root. This changes only owned temporary-file placement; it
+does not weaken disk, memory, cleanup, or Docker preflight policy. A Bridge receipt remains
+`fullGateAttested=false` until the suite is registered with the live residue auditor and the required
+source/toolchain-identical repeat evidence is complete.
+
 ## Package smoke check
 
 From this package directory:

package/dist/bridge/bridge.base.d.ts

@@ -8,6 +8,8 @@ export interface BridgeConnection {
     start(): Promise<void>;
     stop(): Promise<void>;
     onClose(handler: (error?: Error) => void): void;
+    onReconnecting?(handler: (error?: Error) => void): void;
+    onReconnected?(handler: (connectionId?: string) => void | Promise<void>): void;
     onDispatch(handler: BridgeDispatchHandler): void;
     onOffer?(handler: BridgeOfferHandler): void;
     onStart?(handler: BridgeStartHandler): void;

package/dist/bridge/bridge.service.d.ts

@@ -1,5 +1,5 @@
 import type { SessionService } from "../session/session.base.js";
-import { type DispatchSandboxResourceRequest, type RunOnceDispatchPacket } from "../session/session.types.js";
+import { type DispatchSandboxResourceRequest, type RunOnceDispatchPacket, type RunOnceResultPacket } from "../session/session.types.js";
 import { DockerPreflight } from "../sandbox/preflight.js";
 import type { SandboxPreflightResult } from "../sandbox/sandbox.types.js";
 import { type SandboxRuntime } from "../sandbox/runtime.js";
@@ -10,6 +10,15 @@ export interface ResolvedSandboxResourceProfile {
     readonly resources: DispatchSandboxResourceRequest;
     readonly sandboxConfigCommitSha: string;
 }
+/**
+ * Protocol-v2 events are acknowledged one at a time before runOnce returns.
+ * Sending the complete transcript again in DispatchResult made long QA and CI
+ * sessions exceed SignalR's receive limit, disconnecting the bridge after the
+ * provider had already completed. The API combines its acknowledged streamed
+ * events with the terminal result, so the callback only needs the outcome and
+ * artifacts. Protocol v1 retains the transcript for legacy servers.
+ */
+export declare function compactTerminalResult(dispatch: RunOnceDispatchPacket, result: RunOnceResultPacket): RunOnceResultPacket;
 export declare class ForgeBridgeService implements BridgeService {
     private readonly config;
     private readonly connections;
@@ -22,6 +31,8 @@ export declare class ForgeBridgeService implements BridgeService {
     private sandboxMaintenanceTimer;
     private sandboxMaintenanceRunning;
     private closed;
+    private transportRecovery;
+    private transportRecoveryGeneration;
     private stopped;
     private readonly activeSessions;
     private readonly reservations;
@@ -30,12 +41,15 @@ export declare class ForgeBridgeService implements BridgeService {
     private readonly sandboxRuntime;
     private readonly sandboxResourceResolver;
     private readonly sessions;
+    private sandboxAmbientMemoryCommitmentBytes;
     constructor(config: BridgeServiceConfig, sessions?: SessionService | undefined, connections?: BridgeConnectionFactory, preflight?: DockerPreflight, sandboxRuntime?: SandboxRuntime, sandboxResourceResolver?: SandboxResourceResolver);
     connectOnce(): Promise<void>;
+    private registerConnection;
     run(signal?: AbortSignal): Promise<void>;
     stop(): Promise<void>;
     private handleDispatch;
     private handleOffer;
+    private commitOfferReservation;
     private handleStart;
     private redeemSecretGrant;
     private redeemPublishGrant;
@@ -56,6 +70,7 @@ export declare class ForgeBridgeService implements BridgeService {
     private startLeaseWatchdog;
     private stopLeaseWatchdog;
     private expireLeases;
+    private expireReservations;
     private stopHeartbeat;
     private startSandboxMaintenance;
     private stopSandboxMaintenance;
@@ -68,6 +83,9 @@ export declare class ForgeBridgeService implements BridgeService {
     private activeSandboxResources;
     private sandboxResourceCapacity;
     private invokeAck;
+    private beginTransportRecovery;
+    private completeTransportRecovery;
+    private waitForTransportRecovery;
     private waitForClose;
     private stopConnection;
 }
@@ -81,6 +99,8 @@ export declare class SignalRBridgeConnection implements BridgeConnection {
     start(): Promise<void>;
     stop(): Promise<void>;
     onClose(handler: (error?: Error) => void): void;
+    onReconnecting(handler: (error?: Error) => void): void;
+    onReconnected(handler: (connectionId?: string) => void | Promise<void>): void;
     onDispatch(handler: BridgeDispatchHandler): void;
     onOffer(handler: BridgeDispatchHandler): void;
     onStart(handler: BridgeDispatchHandler): void;
@@ -92,12 +112,16 @@ export declare class SignalRBridgeConnection implements BridgeConnection {
 }
 export declare function defaultBridgeServiceConfig(overrides?: Partial<BridgeServiceConfig>): BridgeServiceConfig;
 export declare function resolveBridgeRunnerHubUrl(serverUrl: string): URL;
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function waitForPromiseOrAbort(promise: Promise<unknown>, signal?: AbortSignal): Promise<void>;
 export declare function canReapManagedSandboxes(preflight: {
     readonly healthy: boolean;
     readonly unavailableCode?: string | null;
 }): boolean;
+export declare function infrastructureFailureEventType(summary: string): string | null;
 export type SandboxResourceVector = DispatchSandboxResourceRequest;
 export declare function canReserveSandboxResources(used: SandboxResourceVector, requested: SandboxResourceVector, capacity: SandboxResourceVector): boolean;
+export declare function sandboxMemoryCommitmentCapacity(preflight: Pick<SandboxPreflightResult, "totalMemoryBytes" | "availableMemoryBytes" | "hostReserveBytes">, activeMemoryBytes: number, ambientMemoryCommitmentBytes?: number): number;
 export declare function sandboxCapacityFailureMessage(used: SandboxResourceVector, requested: SandboxResourceVector, capacity: SandboxResourceVector, preflight: SandboxPreflightResult | null, config: BridgeServiceConfig): string;
 export declare function resolveDynamicSandboxResources(requested: DispatchSandboxResourceRequest, serviceCount: number, networkMode: "offline" | "public_allowlist" | "open_public", baseRuntimeOverheadBytes?: number): DispatchSandboxResourceRequest;
 export declare function resolveSandboxResourcesFromRepo(dispatch: RunOnceDispatchPacket, baseRuntimeOverheadBytes?: number): Promise<ResolvedSandboxResourceProfile>;