@loucompanion/forge-bridge 0.1.3-dev.f66395c3ac21 → 0.1.3-dev.fbe15023cdfe

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:
@@ -53,6 +63,74 @@ forge-bridge add-repo Forge /path/to/Forge
 forge-bridge remove-repo Forge
 ```
 
+## Docker sandbox runners
+
+Protocol-v2 bridges preflight Docker before advertising the `docker` sandbox runtime. Validate a repository contract and the local runner before enabling a project's `sandbox_required` policy:
+
+```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.
+- `FORGE_MAX_CONCURRENT_SANDBOXES` — hard slot ceiling; start at `1`.
+- `FORGE_MAX_CONCURRENT_SANDBOX_BUILDS` / `FORGE_SANDBOX_PID_CAPACITY` — weighted build and PID admission ceilings (defaults: `1` and `2048`).
+- `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.
+- `FORGE_AGENT_TOOLING_IMAGE` — digest-pinned Node tooling base required by `sandbox_required`.
+- `FORGE_SANDBOX_IMAGE_POLICY_ENFORCED`, `FORGE_SANDBOX_SBOM_EXECUTABLE`, `FORGE_SANDBOX_VULNERABILITY_EXECUTABLE`, and `FORGE_SANDBOX_PROVENANCE_SIGNING_KEY` — required generated-image promotion gates. The SBOM command must accept Syft-compatible `<image> -o spdx-json`; the vulnerability command must accept Trivy-compatible image arguments.
+- `FORGE_SANDBOX_SIGNATURE_EXECUTABLE` / `FORGE_SANDBOX_SIGNATURE_PUBLIC_KEY` — Cosign-compatible verifier and bounded public-key file. `sandbox_required` verifies every digest-pinned external Dockerfile base/`COPY --from` source and Forge tooling base before generated-image promotion, plus every service-catalog and egress-proxy image before runtime use; adoption modes emit a warning when verification is not configured.
+- `FORGE_SANDBOX_BUILD_EGRESS_ENFORCED` — confirms the dedicated BuildKit builder is behind the approved build-egress control; required for `sandbox_required`.
+- `FORGE_SANDBOX_BUILD_NOFILE` — bounded per-build-step file-descriptor cap (default: `4096`). `FORGE_SANDBOX_BUILDER_PIDS_LIMIT` caps and verifies aggregate processes on the dedicated BuildKit container (default `512`). Buildx `--resource` memory/CPU caps are intentionally not emitted because they are not portable across supported Buildx versions; agent runtime containers still receive Docker memory/CPU limits.
+- `FORGE_SANDBOX_BUILDKIT_CACHE_MAX` / `FORGE_SANDBOX_BUILDKIT_CACHE_RESERVED` — pressure-triggered dedicated-builder cache bounds (defaults: 20 GiB maximum and 2 GiB reserved; minimum free space follows `FORGE_MINIMUM_WORKSPACE_BYTES`).
+- `FORGE_SANDBOX_SECCOMP_PROFILE` / `FORGE_SANDBOX_LSM_SECURITY_OPT` — absolute hardened seccomp profile and AppArmor/SELinux Docker security option applied to every agent and service; required for `sandbox_required`.
+- `FORGE_SANDBOX_HARD_WALL_SECONDS` / `FORGE_SANDBOX_IDLE_SECONDS` — monotonic worker deadlines (defaults: 8 hours and 30 minutes; both are capped by the 8-hour hard maximum).
+- `FORGE_SANDBOX_PUBLICATION_MODE=bridge_push` — remote-safe exact-SHA result publication. This is required for `sandbox_required`; the default `shared_filesystem` mode is intended only for deployments where the bridge and API intentionally share the repository filesystem.
+- `FORGE_SERVICE_POSTGRES_IMAGE`, `FORGE_SERVICE_REDIS_IMAGE`, and `FORGE_SERVICE_BROWSER_IMAGE` — digest-pinned service-catalog images when declared by a contract.
+
+`public_allowlist` uses an internal agent network plus a separate external network joined only by a restricted Squid-compatible proxy. Configure a digest-pinned `FORGE_SANDBOX_EGRESS_PROXY_IMAGE` and `FORGE_SANDBOX_EGRESS_ENFORCED=true`; Forge generates the domain allowlist with private, loopback, link-local, metadata, unsafe-port, and default-deny rules and injects proxy variables into the worker. `open_public` is developer-only and additionally requires `FORGE_ALLOW_OPEN_PUBLIC_SANDBOX=true`. Neither setting weakens `sandbox_required`.
+
+Before selecting `sandbox_required`, save the full approved 40- or 64-character Git commit SHA in the project's Sandbox policy dialog. The server persists that SHA on the immutable attempt and the bridge reads `.forge/forge.sandbox.yml`, `.forge/Dockerfile`, and the tracked build context only from that commit. API-key dispatches carry an opaque one-time grant handle; the authenticated current runner instance redeems it after reservation, and plaintext stays out of offers, database payloads, Docker metadata, and host-persisted control files.
+
+Temporary host fallback for `sandbox_preferred` requires both sides to opt in: a project owner must save a reason and future expiry (maximum 30 days), and an operator must enable **Host fallback** for the runner in Profile Settings. Either missing or expired authorization fails closed. `sandbox_required` never falls back.
+
+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 smoke check
 
 From this package directory:

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

@@ -1,4 +1,4 @@
-import type { BridgeCancelHandler, BridgeDispatchHandler, BridgeServiceConfig } 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>;
@@ -9,7 +9,12 @@ export interface BridgeConnection {
     stop(): Promise<void>;
     onClose(handler: (error?: Error) => void): void;
     onDispatch(handler: BridgeDispatchHandler): void;
+    onOffer?(handler: BridgeOfferHandler): void;
+    onStart?(handler: BridgeStartHandler): void;
+    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,29 +1,72 @@
 import type { SessionService } from "../session/session.base.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, BridgeServiceConfig } from "./bridge.types.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;
     private closed;
     private stopped;
     private readonly activeSessions;
-    constructor(config: BridgeServiceConfig, sessions?: SessionService, connections?: BridgeConnectionFactory);
+    private readonly reservations;
+    private readonly activeReadinessProbes;
+    private readonly preflight;
+    private readonly 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>;
     private handleDispatch;
+    private handleOffer;
+    private handleStart;
+    private redeemSecretGrant;
+    private redeemPublishGrant;
+    private handleLeaseUpdate;
+    private sendOfferDecision;
     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;
     private stopHeartbeat;
+    private startSandboxMaintenance;
+    private stopSandboxMaintenance;
+    private runSandboxMaintenance;
+    private readAttemptSnapshot;
+    private flushCleanupReports;
     private sendHeartbeat;
     private capabilities;
+    private usedSandboxResources;
+    private activeSandboxResources;
+    private sandboxResourceCapacity;
     private invokeAck;
     private waitForClose;
     private stopConnection;
@@ -39,8 +82,22 @@ export declare class SignalRBridgeConnection implements BridgeConnection {
     stop(): Promise<void>;
     onClose(handler: (error?: Error) => void): void;
     onDispatch(handler: BridgeDispatchHandler): void;
+    onOffer(handler: BridgeDispatchHandler): void;
+    onStart(handler: BridgeDispatchHandler): void;
+    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;
 export declare function resolveBridgeRunnerHubUrl(serverUrl: string): URL;
+export declare function canReapManagedSandboxes(preflight: {
+    readonly healthy: boolean;
+    readonly unavailableCode?: string | null;
+}): 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>;