@wenrwa/marketplace-cli 0.8.11 → 0.8.13

package/dist/bridge/gitTokenBroker.d.ts

@@ -0,0 +1,28 @@
+export interface GitCredential {
+    token: string;
+    repoFullName: string;
+    expiresAt: string;
+}
+export type GitCredentialFetcher = (workspaceId: string) => Promise<GitCredential>;
+/** Ask again once a cached credential has less than this left. */
+export declare const REFRESH_BEFORE_EXPIRY_MS: number;
+export declare class GitTokenBroker {
+    private fetch;
+    private now;
+    private cache;
+    private inFlight;
+    constructor(fetch: GitCredentialFetcher, now?: () => number);
+    get(workspaceId: string): Promise<GitCredential>;
+}
+export interface GitTokenSocketHandle {
+    path: string;
+    close(): Promise<void>;
+}
+/**
+ * Serve `broker` on a unix socket at `opts.path` (0600). Replaces a stale
+ * socket file left by a previous bridge.
+ */
+export declare function startGitTokenSocket(opts: {
+    path: string;
+    broker: GitTokenBroker;
+}): Promise<GitTokenSocketHandle>;

package/dist/bridge/gitTokenBroker.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitTokenBroker = exports.REFRESH_BEFORE_EXPIRY_MS = void 0;
+exports.startGitTokenSocket = startGitTokenSocket;
+/**
+ * a9be9720 — fresh git credentials for a box's agents, for as long as they run.
+ *
+ * The relay puts a workspace's git token on each PTY's env once, at open
+ * (WENRWA_GIT_TOKEN). It is a GitHub App installation token and lives an
+ * hour; agent sessions live for days. So every session older than that held a
+ * dead credential and could not push — "remote: Invalid username or token",
+ * and no retry helped.
+ *
+ * Now `git-credential-wenrwa get` (infra/terminal-image) asks THIS bridge,
+ * over a unix socket, for a credential for $WENRWA_WORKSPACE_ID:
+ *
+ *   GET /git-credential?workspace=<id>  →  200 "username=…\npassword=…\n"
+ *
+ * The answer is already in git's credential-helper format, so the shell helper
+ * only has to print it. The bridge keeps each workspace's credential in memory
+ * until shortly before it expires, and otherwise asks the relay for a fresh
+ * one (`git-token`, relayClient.requestGitToken).
+ *
+ * Never on disk, never logged. The socket is 0600 and lives in the bridge
+ * user's home: every process that can reach it is the same user whose PTYs
+ * already carry these tokens on their env.
+ *
+ * Any failure answers non-2xx with a one-line reason, and the helper falls back
+ * to the injected token — so a bridge that cannot mint is never worse than
+ * before.
+ */
+const fs_1 = __importDefault(require("fs"));
+const http_1 = __importDefault(require("http"));
+const path_1 = __importDefault(require("path"));
+/** Ask again once a cached credential has less than this left. */
+exports.REFRESH_BEFORE_EXPIRY_MS = 5 * 60_000;
+class GitTokenBroker {
+    fetch;
+    now;
+    cache = new Map();
+    inFlight = new Map();
+    constructor(fetch, now = Date.now) {
+        this.fetch = fetch;
+        this.now = now;
+    }
+    async get(workspaceId) {
+        const cached = this.cache.get(workspaceId);
+        if (cached && Date.parse(cached.expiresAt) - this.now() > exports.REFRESH_BEFORE_EXPIRY_MS)
+            return cached;
+        // A burst of git calls (fetch + push, a submodule walk) makes ONE request.
+        const pending = this.inFlight.get(workspaceId);
+        if (pending)
+            return pending;
+        const request = this.fetch(workspaceId)
+            .then((cred) => {
+            this.cache.set(workspaceId, cred);
+            return cred;
+        })
+            .finally(() => this.inFlight.delete(workspaceId));
+        this.inFlight.set(workspaceId, request);
+        return request;
+    }
+}
+exports.GitTokenBroker = GitTokenBroker;
+/** Workspace ids are UUIDs; anything else is refused before it is used. */
+const WORKSPACE_ID = /^[A-Za-z0-9-]{1,64}$/;
+/**
+ * Serve `broker` on a unix socket at `opts.path` (0600). Replaces a stale
+ * socket file left by a previous bridge.
+ */
+async function startGitTokenSocket(opts) {
+    fs_1.default.mkdirSync(path_1.default.dirname(opts.path), { recursive: true, mode: 0o700 });
+    try {
+        fs_1.default.unlinkSync(opts.path);
+    }
+    catch {
+        /* no previous socket */
+    }
+    const server = http_1.default.createServer((req, res) => {
+        const reply = (status, body) => {
+            res.writeHead(status, { 'content-type': 'text/plain', 'cache-control': 'no-store' });
+            res.end(body);
+        };
+        const url = new URL(req.url ?? '/', 'http://bridge');
+        if (req.method !== 'GET' || url.pathname !== '/git-credential') {
+            reply(404, 'not found\n');
+            return;
+        }
+        const workspaceId = url.searchParams.get('workspace') ?? '';
+        if (!WORKSPACE_ID.test(workspaceId)) {
+            reply(400, 'no workspace: WENRWA_WORKSPACE_ID is not set in this environment\n');
+            return;
+        }
+        opts.broker.get(workspaceId).then((cred) => reply(200, `username=x-access-token\npassword=${cred.token}\n`), (err) => {
+            const e = err;
+            const code = typeof e?.code === 'string' ? e.code : 'GIT_TOKEN_FAILED';
+            const message = typeof e?.message === 'string' ? e.message : 'could not get a git token';
+            reply(502, `${code}: ${message}\n`);
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.path, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    fs_1.default.chmodSync(opts.path, 0o600);
+    return {
+        path: opts.path,
+        close: () => new Promise((resolve) => {
+            server.close(() => resolve());
+            try {
+                fs_1.default.unlinkSync(opts.path);
+            }
+            catch {
+                /* already gone */
+            }
+        }),
+    };
+}

package/dist/bridge/previewCheckout.d.ts

@@ -153,7 +153,18 @@ export declare class PreviewRunner {
     /** One port, so one operation at a time across the whole box. */
     private chain;
     private orphanSwept;
+    /** Queued + running start/update/stop calls (stc-05's cleaner reads it via activity()). */
+    private opsInFlight;
     constructor(opts: PreviewRunnerOpts);
+    /**
+     * stc-05 — what storage cleanup must leave alone right now: any queued or
+     * running start/update/stop (`opInFlight` — it may be writing any slot),
+     * and every workspace with a preview building or serving.
+     */
+    activity(): {
+        opInFlight: boolean;
+        activeWorkspaces: string[];
+    };
     /** Bring the preview up. Already serving this workspace in this mode → answered as-is. */
     start(req: PreviewRequest): Promise<PreviewResult>;
     /** Fetch the default branch again and, when it moved, rebuild and swap. */

package/dist/bridge/previewCheckout.js

@@ -363,6 +363,8 @@ class PreviewRunner {
     /** One port, so one operation at a time across the whole box. */
     chain = Promise.resolve();
     orphanSwept = false;
+    /** Queued + running start/update/stop calls (stc-05's cleaner reads it via activity()). */
+    opsInFlight = 0;
     constructor(opts) {
         this.opts = {
             previewsBaseDir: opts.previewsBaseDir,
@@ -377,6 +379,20 @@ class PreviewRunner {
             toolsDir: opts.toolsDir ?? path.join(opts.previewsBaseDir, '.tools'),
         };
     }
+    /**
+     * stc-05 — what storage cleanup must leave alone right now: any queued or
+     * running start/update/stop (`opInFlight` — it may be writing any slot),
+     * and every workspace with a preview building or serving.
+     */
+    activity() {
+        const activeWorkspaces = [];
+        for (const [ws, st] of this.states) {
+            const alive = !!(st.child && st.child.exitCode === null && st.child.signalCode === null);
+            if (alive || st.status === 'building')
+                activeWorkspaces.push(ws);
+        }
+        return { opInFlight: this.opsInFlight > 0, activeWorkspaces };
+    }
     /** Bring the preview up. Already serving this workspace in this mode → answered as-is. */
     start(req) {
         return this.serialize(async () => {
@@ -458,7 +474,8 @@ class PreviewRunner {
     }
     // ── internals ────────────────────────────────────────────────────────────
     serialize(fn) {
-        const next = this.chain.then(fn, fn);
+        this.opsInFlight += 1;
+        const next = this.chain.then(fn, fn).finally(() => { this.opsInFlight -= 1; });
         this.chain = next.catch(() => undefined);
         return next;
     }

package/dist/bridge/relayClient.d.ts

@@ -10,6 +10,7 @@ import { GitRun } from './changesReporter';
 import { buildChangesReport as buildChangesReportReal } from './changesReport';
 import { CheckoutInventoryDeps } from './checkoutInventory';
 import type { CheckoutResult } from './repoCheckout';
+import { type AutomaticCleanupResult, type StorageCleanerDeps } from './storageCleanup';
 import type { PreviewRunner } from './previewCheckout';
 /**
  * fcct-27 — typed refusal when `resolveLaunch` names a binary this machine does
@@ -76,6 +77,8 @@ export declare function assembleSessionEnv(frame: {
     };
     env?: Record<string, string>;
     sessionId?: string;
+    /** a9be9720 — where git-credential-wenrwa asks this bridge for a fresh token. */
+    gitTokenSocket?: string;
 }): Record<string, string>;
 /** Minimal surface relayClient needs from a socket — lets tests inject fakes if ever needed. */
 export interface WebSocketLike {
@@ -102,6 +105,10 @@ export interface BackoffOpts {
     jitter?: () => number;
 }
 export interface RelayClientOpts {
+    /** a9be9720 — the unix socket this bridge serves fresh git credentials on
+     *  (gitTokenBroker.ts). Put on every workspace PTY's env. Absent → the
+     *  helper uses the token injected at open, as before. */
+    gitTokenSocket?: string;
     relayUrl: string;
     relayToken: string;
     sessions: SessionManager;
@@ -540,6 +547,18 @@ export interface RelayClientOpts {
         exists: (path: string) => boolean;
         run: CheckoutInventoryDeps['run'];
     };
+    /**
+     * stc-05 — opt IN to storage cleanup: report `cleanup-report` (what Clean
+     * up can free) on connect and on every `inventory-scan`, and honor
+     * `cleanup-run`. Absent → no report is ever sent (the backend reads its
+     * absence as "this bridge can't clean" and the arena hides the button) and
+     * `cleanup-run` answers `unsupported`. HOSTED LANE ONLY. Requires
+     * reposBaseDir + storageCleanupDeps.
+     */
+    enableStorageCleanup?: boolean;
+    /** storageCleanup.ts deps minus reposBaseDir/isAttached, which this module
+     *  supplies (isAttached reads the same live `relayOwned` map reclaim uses). */
+    storageCleanupDeps?: Omit<StorageCleanerDeps, 'reposBaseDir' | 'isAttached'>;
     /**
      * Rock-solid sleep/wake — reads the container's memory (/proc/meminfo, see
      * containerMemory.ts) so a PTY spawn that cannot fit is REFUSED with a
@@ -550,6 +569,16 @@ export interface RelayClientOpts {
      * also proceeds — the same discipline the awake-side reconcile uses.
      */
     readMemInfo?: () => MemInfo | null;
+    /**
+     * stc-06 — free/total GB of the volume the checkouts live on, added to
+     * every `sessions` frame as `disk` (the backend's disk-pressure signal and
+     * capability flag). null/throw = unknown → the field is omitted. Absent →
+     * never reported (laptop lane, older embedders). Requires reportSessions.
+     */
+    readDiskSpace?: () => {
+        freeGb: number;
+        totalGb: number;
+    } | null;
     /** Per-agent memory estimate in MB for the check above. Default
      *  DEFAULT_PER_AGENT_MB (measured, see containerMemory.ts). */
     perAgentMemoryMb?: number;
@@ -693,6 +722,24 @@ export interface RelayClientHandle {
     /** Stop reconnecting and close the current socket. Sessions are untouched — they live in SessionManager. */
     close(): void;
     isConnected(): boolean;
+    /**
+     * a9be9720 — ask the relay for a fresh git credential for one workspace.
+     * Rejects at once (code OFFLINE) with no relay connection, and with the
+     * relay's own code/sentence on a refusal; bounded, never hangs.
+     */
+    requestGitToken(workspaceId: string): Promise<{
+        token: string;
+        repoFullName: string;
+        expiresAt: string;
+    }>;
+    /**
+     * stc-05 → stc-06 — free caches + idle preview slots before a disk grows.
+     * Behind a kill switch (storageCleanupDeps.autoCleanupEnabled, default
+     * off): `{ ran: false, reason: 'disabled' }` until it is turned on. A
+     * bridge without cleanup answers the same way. Sends a fresh report after
+     * a run that freed anything.
+     */
+    runAutomaticCleanup(): Promise<AutomaticCleanupResult>;
 }
 /** twr-05 — snapshot handed to `onHealth`: enough for a `fly logs` reader to
  *  tell a wedged bridge (reconnecting, attempt climbing, sessions frozen)

package/dist/bridge/relayClient.js

@@ -112,6 +112,9 @@ const diskPreflight_1 = require("./diskPreflight");
 // hcs-05's checkoutReclaim executor for the actual delete. See
 // checkoutParkAndRemove.ts's doc comment for the full safety design.
 const checkoutParkAndRemove_1 = require("./checkoutParkAndRemove");
+// stc-05 — measure + delete only rebuildable data (caches, idle preview
+// slots, removed-checkout leftovers, build output in clean repos).
+const storageCleanup_1 = require("./storageCleanup");
 const attachmentWriter_1 = require("./attachmentWriter");
 const envSaver_1 = require("./envSaver");
 const envNames_1 = require("./envNames");
@@ -186,6 +189,10 @@ function assembleSessionEnv(frame) {
         env.WENRWA_GIT_TOKEN = frame.gitCredential.token;
         env.WENRWA_GIT_REPO = frame.gitCredential.repoFullName;
     }
+    // a9be9720 — the token above is an hour-lived GitHub token injected once;
+    // the helper asks the bridge here first and keeps it only as a fallback.
+    if (frame.gitTokenSocket)
+        env.WENRWA_GIT_TOKEN_SOCKET = frame.gitTokenSocket;
     // grad-06 — the commit identity. Nothing set one, so `git commit` failed in
     // every hosted terminal with "Author identity unknown": a container has no
     // domain in its hostname, so git refuses to auto-detect an address. Both
@@ -242,6 +249,8 @@ function describeDialError(err) {
     }
     return String(err);
 }
+/** a9be9720 — how long a `git-token` request may go unanswered. `git` waits on it. */
+const GIT_TOKEN_REQUEST_TIMEOUT_MS = 10_000;
 function send(ws, frame) {
     if (ws.readyState === ws_1.WebSocket.OPEN)
         ws.send(JSON.stringify(frame));
@@ -377,6 +386,48 @@ function startRelayClient(opts) {
             reclaimer,
         })
         : null;
+    // stc-05 — storage cleaner. ONE per process (its in-flight lock must span
+    // every `cleanup-run` across reconnects, like `reclaimer` above).
+    const storageCleaner = opts.enableStorageCleanup && opts.reposBaseDir && opts.storageCleanupDeps
+        ? (0, storageCleanup_1.createStorageCleaner)({
+            ...opts.storageCleanupDeps,
+            reposBaseDir: opts.reposBaseDir,
+            isAttached: (workspaceId) => [...relayOwned.values()].some((s) => s.workspaceId === workspaceId),
+        })
+        : null;
+    // Measuring walks node_modules — never block on it, never run two at once,
+    // and run once more if asked mid-measure (same shape as the inventory reporter).
+    let cleanupMeasuring = false;
+    let cleanupMeasureAgain = false;
+    const reportCleanup = () => {
+        if (!storageCleaner)
+            return;
+        if (cleanupMeasuring) {
+            cleanupMeasureAgain = true;
+            return;
+        }
+        cleanupMeasuring = true;
+        storageCleaner
+            .measure()
+            .then((r) => { if (ws && connected)
+            send(ws, { t: 'cleanup-report', cleanupVersion: storageCleanup_1.CLEANUP_VERSION, ...r }); })
+            .catch((err) => console.error('[bridge] cleanup measure failed:', err))
+            .finally(() => {
+            cleanupMeasuring = false;
+            if (cleanupMeasureAgain) {
+                cleanupMeasureAgain = false;
+                reportCleanup();
+            }
+        });
+    };
+    async function runAutomaticCleanup() {
+        if (!storageCleaner)
+            return { ran: false, reason: 'disabled' };
+        const r = await storageCleaner.runAutomaticCleanup();
+        if (r.ran && r.freedBytes > 0)
+            reportCleanup();
+        return r;
+    }
     // tchp-21 — session snapshot anchors (sessionAnchor.ts), keyed by
     // (relay) sessionId. Populated by maybeCreateSessionAnchor below once
     // createSessionAnchor resolves; read by currentChangesSessions() so a
@@ -446,6 +497,32 @@ function startRelayClient(opts) {
     let stopped = false;
     let ws = null;
     let connected = false;
+    // a9be9720 — outstanding git-token requests, by requestId.
+    const pendingGitTokens = new Map();
+    let gitTokenSeq = 0;
+    const gitTokenError = (code, message) => Object.assign(new Error(message), { code });
+    const failPendingGitTokens = (code, message) => {
+        for (const [id, p] of pendingGitTokens) {
+            clearTimeout(p.timer);
+            pendingGitTokens.delete(id);
+            p.reject(gitTokenError(code, message));
+        }
+    };
+    const requestGitToken = (workspaceId) => new Promise((resolve, reject) => {
+        const socket = ws;
+        if (!connected || !socket || socket.readyState !== ws_1.WebSocket.OPEN) {
+            reject(gitTokenError('OFFLINE', 'The bridge is not connected to HiveOp'));
+            return;
+        }
+        const requestId = `gt-${++gitTokenSeq}-${Date.now().toString(36)}`;
+        const timer = setTimeout(() => {
+            pendingGitTokens.delete(requestId);
+            reject(gitTokenError('TIMEOUT', 'HiveOp did not answer the git token request'));
+        }, GIT_TOKEN_REQUEST_TIMEOUT_MS);
+        timer.unref?.();
+        pendingGitTokens.set(requestId, { resolve, reject, timer });
+        send(socket, { t: 'git-token', requestId, workspaceId });
+    });
     let attempt = 0;
     let reconnectHandle = null;
     let healthHandle = null;
@@ -609,7 +686,19 @@ function startRelayClient(opts) {
                 busy = undefined; // a failed sample must never drop the inventory
             }
         }
-        send(ws, busy ? { t: 'sessions', ids, busy } : { t: 'sessions', ids });
+        let disk = null;
+        if (opts.readDiskSpace) {
+            try {
+                const d = opts.readDiskSpace();
+                if (d && Number.isFinite(d.freeGb) && Number.isFinite(d.totalGb) && d.totalGb > 0) {
+                    disk = { freeGb: Math.round(d.freeGb * 100) / 100, totalGb: Math.round(d.totalGb * 100) / 100 };
+                }
+            }
+            catch {
+                disk = null; // unknown never blocks the inventory
+            }
+        }
+        send(ws, { t: 'sessions', ids, ...(busy ? { busy } : {}), ...(disk ? { disk } : {}) });
     }
     /**
      * tchp-02 — the ACTIVE sessions worth polling for working-tree changes:
@@ -944,6 +1033,8 @@ function startRelayClient(opts) {
             // anything below it, and its own in-flight guard means a rapid
             // reconnect never restarts a scan already running.
             checkoutInventoryReporter?.trigger();
+            // stc-05 — and what Clean up could free (absent on a bridge without it).
+            reportCleanup();
         });
         socket.on('message', (raw) => {
             markLinkAlive();
@@ -991,6 +1082,20 @@ function startRelayClient(opts) {
             }
             try {
                 switch (frame.t) {
+                    case 'git-token': {
+                        const p = pendingGitTokens.get(frame.requestId);
+                        if (!p)
+                            break;
+                        pendingGitTokens.delete(frame.requestId);
+                        clearTimeout(p.timer);
+                        if (frame.ok && frame.token && frame.repoFullName && frame.expiresAt) {
+                            p.resolve({ token: frame.token, repoFullName: frame.repoFullName, expiresAt: frame.expiresAt });
+                        }
+                        else {
+                            p.reject(gitTokenError(frame.code ?? 'GIT_TOKEN_FAILED', frame.message ?? 'HiveOp could not mint a git token'));
+                        }
+                        break;
+                    }
                     case 'open': {
                         // Capture into locals so the async .then closures below keep the
                         // discriminated-union narrowing TS would otherwise drop.
@@ -1172,7 +1277,7 @@ function startRelayClient(opts) {
                             // shared container. autolaunch.sh reads HT_AUTONOMOUS from the
                             // PTY's own env (claude vs claude --dangerously-skip-permissions),
                             // NOT a machine-wide var.
-                            const env = assembleSessionEnv({ workspaceId, autonomous, connectToken, gitCredential, gitIdentity, env: injectedEnv, sessionId: relaySessionId });
+                            const env = assembleSessionEnv({ workspaceId, autonomous, connectToken, gitCredential, gitIdentity, env: injectedEnv, sessionId: relaySessionId, gitTokenSocket: opts.gitTokenSocket });
                             if (opts.resolveWorkspaceCwd) {
                                 opts
                                     .resolveWorkspaceCwd({ workspaceId, repoUrl, gitCredential })
@@ -1193,6 +1298,9 @@ function startRelayClient(opts) {
                                             ...(relaySessionId ? { sessionId: relaySessionId } : {}),
                                             code: err.code,
                                             message: err.message,
+                                            // stc-04 — the growth price, untouched; the pane asks
+                                            // Grow / Cancel and the arena makes the grow call.
+                                            ...(err.quote ? { quote: err.quote } : {}),
                                         });
                                         return;
                                     }
@@ -1376,6 +1484,41 @@ function startRelayClient(opts) {
                     }
                     case 'inventory-scan': {
                         checkoutInventoryReporter?.trigger();
+                        reportCleanup();
+                        break;
+                    }
+                    case 'cleanup-run': {
+                        if (!storageCleaner) {
+                            send(socket, { t: 'cleanup-result', outcome: 'unsupported' });
+                            break;
+                        }
+                        storageCleaner
+                            .clean()
+                            .then((r) => {
+                            if (r.busy)
+                                send(socket, { t: 'cleanup-result', outcome: 'busy' });
+                            else
+                                send(socket, { t: 'cleanup-result', outcome: 'done', freedBytes: r.freedBytes, byCategory: r.byCategory, skipped: r.skipped.length });
+                            reportCleanup();
+                            checkoutInventoryReporter?.trigger();
+                        })
+                            .catch((err) => {
+                            console.error('[bridge] cleanup failed:', err);
+                            send(socket, { t: 'cleanup-result', outcome: 'error', reason: err instanceof Error ? err.message : 'cleanup failed' });
+                        });
+                        break;
+                    }
+                    case 'cleanup-auto': {
+                        runAutomaticCleanup()
+                            .then((r) => {
+                            send(socket, r.ran ? { t: 'cleanup-auto-result', ran: true, freedBytes: r.freedBytes } : { t: 'cleanup-auto-result', ran: false, reason: r.reason });
+                            if (r.ran)
+                                checkoutInventoryReporter?.trigger();
+                        })
+                            .catch((err) => {
+                            console.error('[bridge] automatic cleanup failed:', err);
+                            send(socket, { t: 'cleanup-auto-result', ran: false, reason: 'error' });
+                        });
                         break;
                     }
                     case 'park-save':
@@ -1532,6 +1675,7 @@ function startRelayClient(opts) {
                                 // past.
                                 ...(result.code ? { code: result.code } : {}),
                                 ...(result.message ? { message: result.message } : {}),
+                                ...(result.quote ? { quote: result.quote } : {}),
                             });
                         })
                             .catch((err) => {
@@ -1888,6 +2032,7 @@ function startRelayClient(opts) {
         });
         const onDown = (info) => {
             connected = false;
+            failPendingGitTokens('OFFLINE', 'The bridge lost its HiveOp connection');
             stopHeartbeat();
             // Detach (not close) every live handle: the sessions/PTYs survive the
             // drop in the SessionManager, scrollback keeps accumulating, and the
@@ -2086,8 +2231,11 @@ function startRelayClient(opts) {
             if (hookActivityHandle !== null)
                 cancelInterval(hookActivityHandle);
             opts.companionForwarder?.stop(); // bws-08 — close every forwarded listener on bridge shutdown
+            failPendingGitTokens('OFFLINE', 'The bridge is shutting down');
             ws?.close();
         },
         isConnected: () => connected,
+        requestGitToken,
+        runAutomaticCleanup,
     };
 }

package/dist/bridge/repoCheckout.d.ts

@@ -1,4 +1,4 @@
-import { StorageQuotaFact } from './storageQuotaPreflight';
+import { StorageQuotaFact, GrowQuote } from './storageQuotaPreflight';
 export interface RepoCheckoutDeps {
     baseDir: string;
     exists: (path: string) => boolean;
@@ -48,6 +48,8 @@ export interface CheckoutResult {
     code?: string;
     /** Set only when action === 'refused' — one complete, actionable sentence. */
     message?: string;
+    /** stc-04 — a quota refusal the backend priced a disk growth for. */
+    quote?: GrowQuote;
 }
 export declare function parseRepoFullName(repoUrl: string): string | null;
 export declare function ensureRepoCheckout(repoUrl: string, deps: RepoCheckoutDeps): Promise<CheckoutResult>;

package/dist/bridge/repoCheckout.js

@@ -195,7 +195,12 @@ async function ensureWorkspaceRepo(opts, deps) {
             if (verdict && verdict.kind === 'over-quota') {
                 const message = (0, storageQuotaPreflight_1.storageQuotaPreflightMessage)(verdict);
                 console.error(`[repoCheckout] refusing clone for workspace ${workspaceId} (${repoUrl}) — ${message}`);
-                return { action: 'refused', code: storageQuotaPreflight_1.CLONE_QUOTA_PREFLIGHT_REFUSED, message };
+                return {
+                    action: 'refused',
+                    code: storageQuotaPreflight_1.CLONE_QUOTA_PREFLIGHT_REFUSED,
+                    message,
+                    ...(verdict.fact.quote ? { quote: verdict.fact.quote } : {}),
+                };
             }
         }
         try {

package/dist/bridge/storageCleanup.d.ts

@@ -0,0 +1,66 @@
+import { type InventoryRun, type ReadText } from './checkoutInventory';
+export type CleanupCategory = 'caches' | 'previews' | 'removedCheckouts' | 'buildOutput';
+export declare const CLEANUP_CATEGORIES: readonly CleanupCategory[];
+/** Stamped on every report so the backend/arena can tell a bridge that can clean. */
+export declare const CLEANUP_VERSION = 1;
+/** Directory names that are build output by convention — deleted only when the repo ignores them. */
+export declare const BUILD_OUTPUT_DIRS: ReadonlySet<string>;
+/** What the preview runner is doing right now (PreviewRunner#activity). */
+export interface PreviewActivity {
+    /** A start/update/stop is queued or running — which workspace it touches is not known. */
+    opInFlight: boolean;
+    /** Workspaces with a preview building or serving. */
+    activeWorkspaces: string[];
+}
+export interface StorageCleanerDeps {
+    /** e.g. /data/repos — one checkout per workspace id. */
+    reposBaseDir: string;
+    /** e.g. /data/previews. Absent → the previews category is empty. */
+    previewsBaseDir?: string;
+    /** Absolute cache directories (see defaultCacheDirs). Each is removed whole. */
+    cacheDirs: string[];
+    /** Is a session attached to this workspace RIGHT NOW? */
+    isAttached: (workspaceId: string) => boolean;
+    /** Absent → treated as "no preview running". */
+    previewActivity?: () => PreviewActivity;
+    /** git runner, `run('git', ['-C', path, ...])` — the same one the inventory uses. */
+    run: InventoryRun;
+    /** Bytes on disk under a path. Default: a block-based walk (what `du` reports). */
+    sizeBytes?: (p: string) => Promise<number>;
+    /** Recursive, forced removal. Default fs.promises.rm. */
+    rm?: (p: string) => Promise<void>;
+    readText?: ReadText;
+    /** The kill switch for runAutomaticCleanup. Default false. */
+    autoCleanupEnabled?: boolean;
+}
+export type CleanupBytes = Record<CleanupCategory, number>;
+export interface CleanupReport {
+    reclaimableBytes: number;
+    byCategory: CleanupBytes;
+}
+export interface CleanupSkip {
+    category: CleanupCategory;
+    path: string;
+    reason: string;
+}
+export interface CleanupRun {
+    /** Another run was already going; nothing was done. */
+    busy: boolean;
+    freedBytes: number;
+    byCategory: CleanupBytes;
+    skipped: CleanupSkip[];
+}
+export type AutomaticCleanupResult = ({
+    ran: true;
+} & CleanupRun) | {
+    ran: false;
+    reason: 'disabled' | 'busy';
+};
+export interface StorageCleaner {
+    measure(): Promise<CleanupReport>;
+    clean(categories?: readonly CleanupCategory[]): Promise<CleanupRun>;
+    runAutomaticCleanup(): Promise<AutomaticCleanupResult>;
+}
+/** npm / uv / pip caches under each home-like root, de-duplicated. */
+export declare function defaultCacheDirs(roots: Array<string | undefined>): string[];
+export declare function createStorageCleaner(deps: StorageCleanerDeps): StorageCleaner;