@loucompanion/forge-bridge 0.1.3-dev.62c25087ca89 → 0.1.3-dev.6bad40c431d6

package/README.md

@@ -53,6 +53,50 @@ 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-bridge sandbox reap
+```
+
+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_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_MEMORY` / `FORGE_SANDBOX_BUILD_CPU_QUOTA` / `FORGE_SANDBOX_BUILD_NOFILE` — bounded per-build-step memory/swap, CPU CFS quota, and file-descriptor caps (defaults: `4g`, `200000` per `100000` period, and `4096`). `FORGE_SANDBOX_BUILDER_PIDS_LIMIT` caps and verifies aggregate processes on the dedicated BuildKit container (default `512`).
+- `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.
+
+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, BridgeReapHandler, BridgeServiceConfig, BridgeStartHandler } from "./bridge.types.js";
 export interface BridgeService {
     connectOnce(): Promise<void>;
     run(signal?: AbortSignal): Promise<void>;
@@ -9,7 +9,11 @@ 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;
     invoke<TResponse>(methodName: string, payload: unknown): Promise<TResponse>;
 }
 export interface BridgeConnectionFactory {

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

@@ -1,29 +1,57 @@
 import type { SessionService } from "../session/session.base.js";
+import { type DispatchSandboxResourceRequest } from "../session/session.types.js";
+import { DockerPreflight } from "../sandbox/preflight.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 declare class ForgeBridgeService implements BridgeService {
     private readonly config;
     private readonly sessions;
     private readonly connections;
     private connection;
     private heartbeatTimer;
+    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 preflight;
+    private readonly sandboxRuntime;
+    constructor(config: BridgeServiceConfig, sessions?: SessionService, connections?: BridgeConnectionFactory, preflight?: DockerPreflight, sandboxRuntime?: SandboxRuntime);
     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 abortActiveSessions;
     private normalizeDispatch;
     private sendResult;
+    private sendLegacyResult;
+    private sendResultPayload;
     private startHeartbeat;
+    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 sandboxResourceCapacity;
     private invokeAck;
     private waitForClose;
     private stopConnection;
@@ -39,8 +67,14 @@ 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;
     invoke<TResponse>(methodName: string, payload: unknown): Promise<TResponse>;
 }
 export declare function defaultBridgeServiceConfig(overrides?: Partial<BridgeServiceConfig>): BridgeServiceConfig;
 export declare function resolveBridgeRunnerHubUrl(serverUrl: string): URL;
+export type SandboxResourceVector = DispatchSandboxResourceRequest;
+export declare function canReserveSandboxResources(used: SandboxResourceVector, requested: SandboxResourceVector, capacity: SandboxResourceVector): boolean;