@loucompanion/forge-bridge 0.1.3-dev.d46a8e73d03d → 0.1.3-dev.eeefdb0d19c1

package/README.md

@@ -33,6 +33,16 @@ The bridge can also read connection settings from environment variables:
 - `FORGE_CLI_PROVIDERS`
 - `FORGE_CODEX_MODELS` / `FORGE_CURSOR_MODELS` (optional comma-separated model ids advertised in runner capabilities)
 
+Show or change the saved server without editing `bridge.json`:
+
+```bash
+forge-bridge server show
+forge-bridge server set http://localhost:5208
+forge-bridge server set https://srv1493013.tail66073d.ts.net:8443
+```
+
+`FORGE_URL` overrides the saved server. Changing the saved URL retains runner credentials so aliases for the same deployment keep working; pair again with `--server` when switching to a different Forge deployment.
+
 ## Repo-local development
 
 For active Forge branch development, run the bridge directly from the checkout instead of publishing a package:
@@ -60,9 +70,29 @@ Protocol-v2 bridges preflight Docker before advertising the `docker` sandbox run
 ```bash
 forge sandbox init
 forge sandbox doctor
+forge sandbox smoke
 forge-bridge sandbox reap
 ```
 
+Configure the local bridge's persistent Docker placement policy with:
+
+```bash
+forge-bridge sandbox on
+forge-bridge sandbox on --allow-open-public
+forge-bridge sandbox status
+forge-bridge sandbox off
+```
+
+`sandbox on` keeps unrestricted public networking denied by default. The developer-only
+`--allow-open-public` option stores an explicit local approval in `bridge.json`; it survives
+bridge restarts and is reported by `sandbox status`. Restart a connected bridge after changing
+the policy. `FORGE_DOCKER_SANDBOX` and `FORGE_ALLOW_OPEN_PUBLIC_SANDBOX` remain higher-priority
+operator overrides when present.
+
+`forge sandbox smoke` runs doctor, builds the repository-owned `.forge/Dockerfile`, launches a disposable hardened container on an internal network with a fresh workspace volume, and verifies that its exact attempt-labeled container, network, volume, and image are gone afterward. It writes a redacted JSON report under `FORGE_SANDBOX_STATE_ROOT/smoke-reports`; use `--report <path>` to choose a different destination. Stop the connected bridge before running smoke so the command can exclusively acquire the Docker-context ownership lock.
+
+Use `forge sandbox smoke --probe-loopback-port` only when proving Docker host-port allocation. The normal hardened container remains internal with no publication; a separate exact-labeled fixture requests `127.0.0.1::8080/tcp`, records Docker's assigned loopback port, rejects wildcard or ambiguous mappings, and is removed by the same exact-label cleanup verification.
+
 Production shared runners require a Linux rootless Docker daemon. Docker Desktop is developer-only and must be opted in with `FORGE_ALLOW_DOCKER_DESKTOP_SANDBOX=true`. Useful runner settings are:
 
 - `FORGE_TRUST_DOMAIN_ID` — must match the project trust domain.
@@ -71,6 +101,8 @@ 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.
+- `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).
 - `FORGE_SANDBOX_AUDIT_RETENTION_COUNT` / `FORGE_SANDBOX_AUDIT_RETENTION_TTL_MS` — restricted failed-build/attestation retention (defaults: 200 keys and 30 days); evidence for active image digests is protected.
@@ -93,6 +125,8 @@ Temporary host fallback for `sandbox_preferred` requires both sides to opt in: a
 
 The bridge reaps exact-labeled orphan resources before connecting and every minute afterward. Connected passes reconcile current-instance ledgers against an authoritative, instance-scoped server attempt snapshot; startup does not adopt old-instance resources and terminates them before advertising capacity. Per-resource removal outcomes are written mode-0600 under `FORGE_SANDBOX_STATE_ROOT/cleanup-reports` before transmission, replayed after reconnect, acknowledged by report ID, and persisted by the API only when attempt, fence, resource runner instance, and current reporting runner match. Fenced dispatch events also persist image/cache status, build/agent-start/import/teardown timestamps, and a validated inventory of created agent/sidecar containers, networks, volumes, and published ports. Selected-session diagnostics expose that lifecycle data and recent cleanup actions while retaining cleanup-pending state after the agent outcome is terminal. Install `forge-bridge sandbox reap` as an independently supervised OS timer with the same `FORGE_RUNNER_ID`, Docker context, and state root so resources are reconciled while the bridge is down; the Docker-context ownership lock makes an overlapping pass fail safely. A non-zero `degradedReservationCount` means teardown has not completed; the affected capacity remains unavailable until a successful reaper pass. Drain a runner from Profile Settings before upgrades or Docker maintenance, wait for active/starting counts to reach zero, then restart the bridge. Profile Settings also exposes a scoped **Reap** action; the API delivers it only to the currently established protocol-v2 runner instance. Image GC runs only while disk pressure is latched, shares the build lock, preserves active image digests, and prunes only expired images beyond the per-project retention count. Lease renewals are HMAC-bound to the attempt and fence and advance an in-container monotonic deadline; lease, hard-wall, and idle expiry produce distinct failure codes.
 
+Every attempt-owned container (including short-lived initialization helpers), network, and volume carries `dev.forge.resource-lease-id` equal to the dispatch execution lease. Ledger schema v2 persists the same `resourceLeaseId`; teardown compares the complete expected label set, and orphan reaping fails closed unless the managed, resource-lease, execution-lease, attempt, runner, runner-instance, and fencing identities are all present and consistent.
+
 In `bridge_push` mode, the start packet carries only an attempt/fence/branch-bound publication handle. After validating and importing the output bundle, the authenticated current bridge redeems that handle for an in-memory, exact-repository credential; the API rechecks the live lease/fence/grant/branch/result SHA and records redemption before returning it. Git receives the credential through a process environment configuration, never command arguments, files, Git config, or the container. The bridge compares the remote branch with the immutable input commit and pushes only the exact result commit using `--force-with-lease`; cancellation aborts Git, an already-published matching result is an idempotent success, and any other remote value is rejected as stale. The API records the fenced publication acknowledgment before sign-off and does not push the branch a second time while opening the pull request.
 
 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.

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

@@ -1,4 +1,4 @@
-import type { BridgeCancelHandler, BridgeDispatchHandler, BridgeLeaseUpdateHandler, BridgeOfferHandler, BridgeReapHandler, BridgeServiceConfig, BridgeStartHandler } from "./bridge.types.js";
+import type { BridgeCancelHandler, BridgeDispatchHandler, BridgeLeaseUpdateHandler, BridgeOfferHandler, BridgeReadinessProbeHandler, BridgeReapHandler, BridgeServiceConfig, BridgeStartHandler } from "./bridge.types.js";
 export interface BridgeService {
     connectOnce(): Promise<void>;
     run(signal?: AbortSignal): Promise<void>;
@@ -14,6 +14,7 @@ export interface BridgeConnection {
     onLeaseUpdate?(handler: BridgeLeaseUpdateHandler): void;
     onCancel(handler: BridgeCancelHandler): void;
     onReap?(handler: BridgeReapHandler): void;
+    onReadinessProbe?(handler: BridgeReadinessProbeHandler): void;
     invoke<TResponse>(methodName: string, payload: unknown): Promise<TResponse>;
 }
 export interface BridgeConnectionFactory {

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

@@ -1,15 +1,23 @@
 import type { SessionService } from "../session/session.base.js";
-import { type DispatchSandboxResourceRequest } from "../session/session.types.js";
+import { type DispatchSandboxResourceRequest, type RunOnceDispatchPacket } 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";
 import type { BridgeConnection, BridgeConnectionFactory, BridgeService } from "./bridge.base.js";
 import type { BridgeCancelHandler, BridgeDispatchHandler, BridgeLeaseUpdateRequest, BridgeReapRequest, BridgeServiceConfig } from "./bridge.types.js";
+export type SandboxResourceResolver = (dispatch: RunOnceDispatchPacket) => Promise<ResolvedSandboxResourceProfile>;
+export interface ResolvedSandboxResourceProfile {
+    readonly resources: DispatchSandboxResourceRequest;
+    readonly sandboxConfigCommitSha: string;
+}
 export declare class ForgeBridgeService implements BridgeService {
     private readonly config;
-    private readonly sessions;
     private readonly connections;
     private connection;
     private heartbeatTimer;
+    private heartbeatInFlight;
+    private consecutiveHeartbeatFailures;
+    private reconnectingFromHeartbeatFailure;
     private leaseWatchdogTimer;
     private sandboxMaintenanceTimer;
     private sandboxMaintenanceRunning;
@@ -17,9 +25,12 @@ export declare class ForgeBridgeService implements BridgeService {
     private stopped;
     private readonly activeSessions;
     private readonly reservations;
+    private readonly activeReadinessProbes;
     private readonly preflight;
     private readonly sandboxRuntime;
-    constructor(config: BridgeServiceConfig, sessions?: SessionService, connections?: BridgeConnectionFactory, preflight?: DockerPreflight, sandboxRuntime?: SandboxRuntime);
+    private readonly sandboxResourceResolver;
+    private readonly sessions;
+    constructor(config: BridgeServiceConfig, sessions?: SessionService | undefined, connections?: BridgeConnectionFactory, preflight?: DockerPreflight, sandboxRuntime?: SandboxRuntime, sandboxResourceResolver?: SandboxResourceResolver);
     connectOnce(): Promise<void>;
     run(signal?: AbortSignal): Promise<void>;
     stop(): Promise<void>;
@@ -33,12 +44,15 @@ export declare class ForgeBridgeService implements BridgeService {
     private parseDispatchOrReport;
     private handleCancel;
     private handleReap;
+    private handleReadinessProbe;
     private abortActiveSessions;
+    private abortActiveReadinessProbes;
     private normalizeDispatch;
     private sendResult;
     private sendLegacyResult;
     private sendResultPayload;
     private startHeartbeat;
+    private heartbeatTick;
     private startLeaseWatchdog;
     private stopLeaseWatchdog;
     private expireLeases;
@@ -51,6 +65,7 @@ export declare class ForgeBridgeService implements BridgeService {
     private sendHeartbeat;
     private capabilities;
     private usedSandboxResources;
+    private activeSandboxResources;
     private sandboxResourceCapacity;
     private invokeAck;
     private waitForClose;
@@ -72,6 +87,7 @@ export declare class SignalRBridgeConnection implements BridgeConnection {
     onLeaseUpdate(handler: (request: BridgeLeaseUpdateRequest) => Promise<void>): void;
     onCancel(handler: BridgeCancelHandler): void;
     onReap(handler: (request: BridgeReapRequest) => Promise<void>): void;
+    onReadinessProbe(handler: (request: unknown) => Promise<void>): void;
     invoke<TResponse>(methodName: string, payload: unknown): Promise<TResponse>;
 }
 export declare function defaultBridgeServiceConfig(overrides?: Partial<BridgeServiceConfig>): BridgeServiceConfig;
@@ -82,3 +98,6 @@ export declare function canReapManagedSandboxes(preflight: {
 }): boolean;
 export type SandboxResourceVector = DispatchSandboxResourceRequest;
 export declare function canReserveSandboxResources(used: SandboxResourceVector, requested: SandboxResourceVector, capacity: SandboxResourceVector): boolean;
+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>;