@loucompanion/forge-bridge 0.1.3-dev.d1ca67076aa9 → 0.1.3-dev.e7b62d8fdd33

package/dist/cleanup/cleanup.service.js

@@ -1,5 +1,498 @@
-export class NoopCleanupService {
-    async run(_request) {
-        return { removedWorktrees: 0 };
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RepositoryCoordinatorLock } from "../sandbox/repository-lock.js";
+import { GitClient } from "../shared/git/git.js";
+import { isSubPath, resolveExistingDirectoryPath, resolvePathIdentity } from "../shared/path/path.js";
+import { validRuntimeIsolationLease } from "../runtime/runtime-isolation-lease.js";
+import { defaultWorktreeCoordinatorStateRoot, resolveManagedWorktreeRootForRepo, } from "../worktree/worktree-paths.js";
+const staleRuntimeReadinessAgeMs = 30 * 60 * 1000;
+export class ManagedWorktreeCleanupService {
+    stateRoot;
+    git;
+    coordinator;
+    constructor(stateRoot = defaultWorktreeCoordinatorStateRoot(), git = new GitClient(), coordinator = new RepositoryCoordinatorLock(stateRoot)) {
+        this.stateRoot = stateRoot;
+        this.git = git;
+        this.coordinator = coordinator;
     }
+    async run(request) {
+        const [repoPath, allowedRepoRoot] = await Promise.all([
+            resolveExistingDirectoryPath(request.repoRoot),
+            request.allowedRepoRoot
+                ? resolvePathIdentity(request.allowedRepoRoot)
+                : Promise.resolve(undefined),
+        ]);
+        const worktreeRoot = resolveManagedWorktreeRootForRepo(repoPath, allowedRepoRoot);
+        return await this.coordinator.withLock(repoPath, async () => {
+            return await this.runLocked(repoPath, worktreeRoot, request);
+        });
+    }
+    async runLocked(repoPath, worktreeRoot, request) {
+        if (request.mode === "merged") {
+            if (request.force)
+                await this.git.run(repoPath, ["worktree", "prune"]);
+            return emptyResult(worktreeRoot, request.force);
+        }
+        const safeRoot = await resolveSafeManagedRoot(worktreeRoot);
+        if (!safeRoot) {
+            if (request.force)
+                await this.git.run(repoPath, ["worktree", "prune"]);
+            return emptyResult(worktreeRoot, request.force);
+        }
+        const [listedWorktrees, runtimeLeases] = await Promise.all([
+            this.listWorktrees(repoPath),
+            this.readRuntimeLeases(),
+        ]);
+        const activeRuntimePaths = await Promise.all(runtimeLeases
+            .filter(lease => lease.state !== "released")
+            .map(lease => resolveRuntimeLeasePath(lease.worktreePath)));
+        const metadataRoot = await this.worktreeMetadataRoot(repoPath);
+        const staleReadinessPaths = await this.staleRuntimeReadinessPaths(listedWorktrees, activeRuntimePaths);
+        const activeWorktrees = activePaths(listedWorktrees)
+            .filter(activePath => !staleReadinessPaths.some(stalePath => samePath(stalePath, activePath)));
+        if (request.mode === "all") {
+            const protectedPaths = uniquePaths([
+                ...activeWorktrees.filter(activePath => isSubPath(safeRoot, activePath)),
+                ...activeRuntimePaths.filter(activePath => isSubPath(safeRoot, activePath)),
+            ]);
+            if (protectedPaths.length > 0) {
+                throw new Error(`Refusing to remove managed worktree root ${safeRoot}; ${protectedPaths.length} active worktree or runtime lease(s) remain.`);
+            }
+            const scan = await this.scanManagedCandidates(metadataRoot, safeRoot, activeWorktrees, activeRuntimePaths);
+            if (request.force && !scan.rootRemovalSafe) {
+                throw new Error(`Refusing to remove managed worktree root ${safeRoot}; unowned content remains (${scan.skippedUnownedDirectories} skipped director${scan.skippedUnownedDirectories === 1 ? "y" : "ies"}).`);
+            }
+            if (request.force) {
+                await quarantineAndRemoveRoot(safeRoot);
+                await this.git.run(repoPath, ["worktree", "prune"]);
+            }
+            return {
+                worktreeRoot: safeRoot,
+                removedWorktrees: request.force ? scan.candidates.length : 0,
+                candidateWorktrees: scan.candidates.length,
+                protectedWorktrees: scan.protectedWorktrees,
+                skippedUnownedDirectories: scan.skippedUnownedDirectories,
+                removedRoot: request.force,
+                dryRun: !request.force,
+            };
+        }
+        const scan = await this.scanManagedCandidates(metadataRoot, safeRoot, activeWorktrees, activeRuntimePaths);
+        if (!request.force) {
+            return {
+                worktreeRoot: safeRoot,
+                removedWorktrees: 0,
+                candidateWorktrees: scan.candidates.length,
+                protectedWorktrees: scan.protectedWorktrees,
+                skippedUnownedDirectories: scan.skippedUnownedDirectories,
+                removedRoot: false,
+                dryRun: true,
+            };
+        }
+        let removedWorktrees = 0;
+        for (const candidate of scan.candidates) {
+            const [currentWorktrees, currentLeases] = await Promise.all([
+                this.listWorktrees(repoPath),
+                this.readRuntimeLeases(),
+            ]);
+            const currentRuntimePaths = await Promise.all(currentLeases
+                .filter(lease => lease.state !== "released")
+                .map(lease => resolveRuntimeLeasePath(lease.worktreePath)));
+            const currentStaleReadinessPaths = await this.staleRuntimeReadinessPaths(currentWorktrees, currentRuntimePaths);
+            const currentlyProtected = [
+                ...activePaths(currentWorktrees)
+                    .filter(activePath => !currentStaleReadinessPaths.some(stalePath => samePath(stalePath, activePath))),
+                ...currentRuntimePaths,
+            ];
+            if (worktreePathState(candidate, currentlyProtected) !== "none") {
+                continue;
+            }
+            const candidateIdentity = await forgeManagedCandidateIdentity(metadataRoot, candidate);
+            if (!candidateIdentity) {
+                continue;
+            }
+            if (await quarantineAndRemoveCandidate(safeRoot, candidate, candidateIdentity)) {
+                removedWorktrees += 1;
+            }
+        }
+        await this.git.run(repoPath, ["worktree", "prune"]);
+        return {
+            worktreeRoot: safeRoot,
+            removedWorktrees,
+            candidateWorktrees: scan.candidates.length,
+            protectedWorktrees: scan.protectedWorktrees,
+            skippedUnownedDirectories: scan.skippedUnownedDirectories,
+            removedRoot: false,
+            dryRun: false,
+        };
+    }
+    async listWorktrees(repoPath) {
+        const output = await this.git.run(repoPath, ["worktree", "list", "--porcelain", "-z"]);
+        return parseWorktreeListing(repoPath, output);
+    }
+    async staleRuntimeReadinessPaths(worktrees, runtimePaths) {
+        const stale = [];
+        for (const worktree of worktrees) {
+            if (worktree.prunable || !isRuntimeReadinessWorktree(worktree))
+                continue;
+            if (worktreePathState(worktree.worktreePath, runtimePaths) !== "none")
+                continue;
+            const stat = await fs.stat(worktree.worktreePath).catch(error => {
+                if (isEnoent(error))
+                    return null;
+                throw error;
+            });
+            if (stat && Date.now() - stat.mtimeMs >= staleRuntimeReadinessAgeMs) {
+                stale.push(worktree.worktreePath);
+            }
+        }
+        return stale;
+    }
+    async scanManagedCandidates(metadataRoot, worktreeRoot, activeWorktrees, runtimePaths) {
+        const candidates = [];
+        let protectedWorktrees = 0;
+        let skippedUnownedDirectories = 0;
+        const visit = async (currentPath, root = false) => {
+            const entries = await fs.readdir(currentPath, { withFileTypes: true }).catch(error => {
+                if (isEnoent(error))
+                    return [];
+                throw error;
+            });
+            let containsManagedDirectory = false;
+            let containsUnownedContent = false;
+            for (const entry of entries) {
+                if (entry.name === ".forge-cleanup-quarantine") {
+                    containsUnownedContent = true;
+                    continue;
+                }
+                const entryPath = path.join(currentPath, entry.name);
+                const stat = await fs.lstat(entryPath).catch(error => {
+                    if (isEnoent(error))
+                        return null;
+                    throw error;
+                });
+                if (!stat)
+                    continue;
+                if (stat.isSymbolicLink() || !stat.isDirectory()) {
+                    containsUnownedContent = true;
+                    continue;
+                }
+                const realEntry = await fs.realpath(entryPath).catch(error => {
+                    if (isEnoent(error))
+                        return null;
+                    throw error;
+                });
+                if (!realEntry)
+                    continue;
+                if (!isSubPath(worktreeRoot, realEntry)) {
+                    throw new Error(`Managed worktree cleanup path escaped ${worktreeRoot}: ${realEntry}.`);
+                }
+                const activeState = worktreePathState(realEntry, activeWorktrees);
+                const runtimeState = worktreePathState(realEntry, runtimePaths);
+                if (activeState === "active" || runtimeState === "active") {
+                    protectedWorktrees += 1;
+                    containsManagedDirectory = true;
+                    continue;
+                }
+                if (activeState === "ancestor" || runtimeState === "ancestor") {
+                    containsManagedDirectory = await visit(realEntry) || containsManagedDirectory;
+                    continue;
+                }
+                if (await forgeManagedCandidateIdentity(metadataRoot, realEntry)) {
+                    candidates.push(realEntry);
+                    containsManagedDirectory = true;
+                    continue;
+                }
+                if (await visit(realEntry)) {
+                    containsManagedDirectory = true;
+                    continue;
+                }
+                skippedUnownedDirectories += 1;
+                containsUnownedContent = true;
+            }
+            return !containsUnownedContent && (root || containsManagedDirectory);
+        };
+        const rootRemovalSafe = await visit(worktreeRoot, true);
+        return { candidates, protectedWorktrees, skippedUnownedDirectories, rootRemovalSafe };
+    }
+    async readRuntimeLeases() {
+        const ledgerRoot = path.join(this.stateRoot, "runtime-ledger", "host");
+        const entries = await fs.readdir(ledgerRoot, { withFileTypes: true }).catch(error => {
+            if (isEnoent(error))
+                return [];
+            throw error;
+        });
+        const leases = [];
+        for (const entry of entries) {
+            if (!entry.name.endsWith(".json"))
+                continue;
+            if (!entry.isFile() || entry.isSymbolicLink()) {
+                throw new Error(`Refusing managed worktree cleanup because runtime ledger ${entry.name} is not a regular file.`);
+            }
+            const target = path.join(ledgerRoot, entry.name);
+            const value = await readRuntimeLedger(target, entry.name);
+            const runtimeLease = isRecord(value) ? value.runtimeLease : null;
+            if (!validRuntimeIsolationLease(runtimeLease) || runtimeLease.mode !== "host") {
+                throw new Error(`Refusing managed worktree cleanup because runtime ledger ${entry.name} has no trustworthy host lease.`);
+            }
+            leases.push(runtimeLease);
+        }
+        return leases;
+    }
+    async worktreeMetadataRoot(repoPath) {
+        const commonDirRaw = (await this.git.run(repoPath, ["rev-parse", "--git-common-dir"])).trim();
+        const commonDirPath = path.isAbsolute(commonDirRaw) ? commonDirRaw : path.resolve(repoPath, commonDirRaw);
+        return path.join(await fs.realpath(commonDirPath), "worktrees");
+    }
+}
+async function resolveRuntimeLeasePath(leasePath) {
+    const resolved = path.resolve(leasePath);
+    const before = await fs.lstat(resolved).catch(error => {
+        if (isEnoent(error))
+            return null;
+        throw error;
+    });
+    if (!before)
+        return await resolvePathIdentity(resolved);
+    if (before.isSymbolicLink() || !before.isDirectory()) {
+        throw new Error(`Refusing managed worktree cleanup because runtime lease path ${resolved} is redirected or is not a directory.`);
+    }
+    const real = await fs.realpath(resolved);
+    const after = await fs.lstat(resolved);
+    if (after.isSymbolicLink()
+        || !after.isDirectory()
+        || (before.dev !== 0 && before.ino !== 0 && after.dev !== 0 && after.ino !== 0
+            && (before.dev !== after.dev || before.ino !== after.ino))) {
+        throw new Error(`Refusing managed worktree cleanup because runtime lease path ${resolved} changed while being resolved.`);
+    }
+    return real;
+}
+async function readRuntimeLedger(target, entryName) {
+    const pathStat = await fs.lstat(target).catch(error => {
+        if (isEnoent(error))
+            return null;
+        throw error;
+    });
+    if (!pathStat) {
+        throw new Error(`Refusing managed worktree cleanup because runtime ledger ${entryName} disappeared.`);
+    }
+    validateRuntimeLedgerStat(entryName, pathStat);
+    let handle;
+    try {
+        handle = await fs.open(target, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (isEnoent(error) || errorCode(error) === "ELOOP") {
+            throw new Error(`Refusing managed worktree cleanup because runtime ledger ${entryName} is not a regular file.`, { cause: error });
+        }
+        throw new Error(`Refusing managed worktree cleanup because runtime ledger ${entryName} could not be opened safely.`, { cause: error });
+    }
+    try {
+        const openedStat = await handle.stat();
+        const reopenedPathStat = await fs.lstat(target);
+        validateRuntimeLedgerStat(entryName, openedStat);
+        validateRuntimeLedgerStat(entryName, reopenedPathStat);
+        validateSameRuntimeLedgerFile(entryName, pathStat, openedStat);
+        validateSameRuntimeLedgerFile(entryName, openedStat, reopenedPathStat);
+        const content = await handle.readFile("utf8");
+        const afterStat = await handle.stat();
+        const afterPathStat = await fs.lstat(target);
+        validateRuntimeLedgerStat(entryName, afterStat);
+        validateRuntimeLedgerStat(entryName, afterPathStat);
+        validateSameRuntimeLedgerFile(entryName, openedStat, afterStat);
+        validateSameRuntimeLedgerFile(entryName, afterStat, afterPathStat);
+        if (openedStat.size !== afterStat.size || Buffer.byteLength(content, "utf8") !== afterStat.size) {
+            throw new Error(`Refusing managed worktree cleanup because runtime ledger ${entryName} changed while being read.`);
+        }
+        try {
+            return JSON.parse(content);
+        }
+        catch (error) {
+            throw new Error(`Refusing managed worktree cleanup because runtime ledger ${entryName} is invalid.`, { cause: error });
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+function validateRuntimeLedgerStat(entryName, stat) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(`Refusing managed worktree cleanup because runtime ledger ${entryName} is not a regular file.`);
+    }
+    if (stat.size > 256 * 1024) {
+        throw new Error(`Refusing managed worktree cleanup because runtime ledger ${entryName} is oversized.`);
+    }
+}
+function validateSameRuntimeLedgerFile(entryName, before, after) {
+    if (before.dev !== 0 && before.ino !== 0 && after.dev !== 0 && after.ino !== 0
+        && (before.dev !== after.dev || before.ino !== after.ino)) {
+        throw new Error(`Refusing managed worktree cleanup because runtime ledger ${entryName} changed while being read.`);
+    }
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function emptyResult(worktreeRoot, force) {
+    return {
+        worktreeRoot: path.resolve(worktreeRoot),
+        removedWorktrees: 0,
+        candidateWorktrees: 0,
+        protectedWorktrees: 0,
+        skippedUnownedDirectories: 0,
+        removedRoot: false,
+        dryRun: !force,
+    };
+}
+async function resolveSafeManagedRoot(worktreeRoot) {
+    const rootPath = path.resolve(worktreeRoot);
+    const rootStat = await fs.lstat(rootPath).catch(error => {
+        if (isEnoent(error))
+            return null;
+        throw error;
+    });
+    if (!rootStat)
+        return null;
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        throw new Error(`Refusing cleanup for redirected or non-directory managed worktree root ${rootPath}.`);
+    }
+    const parentPath = path.dirname(rootPath);
+    const parentStat = await fs.lstat(parentPath);
+    if (parentStat.isSymbolicLink() || !parentStat.isDirectory()) {
+        throw new Error(`Refusing cleanup for redirected managed worktree root parent ${parentPath}.`);
+    }
+    const [realParent, realRoot] = await Promise.all([fs.realpath(parentPath), fs.realpath(rootPath)]);
+    if (!samePath(path.join(realParent, path.basename(rootPath)), realRoot)) {
+        throw new Error(`Refusing cleanup for redirected managed worktree root ${rootPath}.`);
+    }
+    return realRoot;
+}
+async function forgeManagedCandidateIdentity(metadataRoot, candidatePath) {
+    const gitFile = path.join(candidatePath, ".git");
+    const stat = await fs.lstat(gitFile).catch(error => {
+        if (isEnoent(error))
+            return null;
+        throw error;
+    });
+    if (!stat || stat.isSymbolicLink() || !stat.isFile() || stat.size > 16 * 1024)
+        return null;
+    const contents = (await fs.readFile(gitFile, "utf8")).trim();
+    if (!contents.toLowerCase().startsWith("gitdir:"))
+        return null;
+    const gitDir = contents.slice("gitdir:".length).trim();
+    if (!gitDir)
+        return null;
+    const candidateGitDir = path.resolve(candidatePath, gitDir);
+    return !samePath(metadataRoot, candidateGitDir) && isSubPath(metadataRoot, candidateGitDir)
+        ? contents
+        : null;
+}
+async function quarantineAndRemoveCandidate(worktreeRoot, candidatePath, expectedIdentity) {
+    const quarantineRoot = path.join(worktreeRoot, ".forge-cleanup-quarantine");
+    await ensureSafeQuarantineRoot(worktreeRoot, quarantineRoot);
+    const quarantinePath = path.join(quarantineRoot, randomUUID());
+    try {
+        await fs.rename(candidatePath, quarantinePath);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return false;
+        throw error;
+    }
+    const quarantinedIdentity = await readGitFileIdentity(quarantinePath);
+    if (quarantinedIdentity !== expectedIdentity) {
+        await fs.rename(quarantinePath, candidatePath).catch(() => undefined);
+        throw new Error(`Refusing cleanup because managed worktree ownership changed while quarantining ${candidatePath}.`);
+    }
+    await fs.rm(quarantinePath, { recursive: true, force: true });
+    await fs.rmdir(quarantineRoot).catch(error => {
+        if (!isEnoent(error) && error.code !== "ENOTEMPTY")
+            throw error;
+    });
+    return true;
+}
+async function readGitFileIdentity(candidatePath) {
+    const gitFile = path.join(candidatePath, ".git");
+    const stat = await fs.lstat(gitFile).catch(error => {
+        if (isEnoent(error))
+            return null;
+        throw error;
+    });
+    if (!stat || stat.isSymbolicLink() || !stat.isFile() || stat.size > 16 * 1024)
+        return null;
+    return (await fs.readFile(gitFile, "utf8")).trim();
+}
+async function ensureSafeQuarantineRoot(worktreeRoot, quarantineRoot) {
+    await fs.mkdir(quarantineRoot, { recursive: true, mode: 0o700 });
+    const stat = await fs.lstat(quarantineRoot);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`Refusing cleanup through redirected quarantine root ${quarantineRoot}.`);
+    }
+    const realQuarantine = await fs.realpath(quarantineRoot);
+    if (!isSubPath(worktreeRoot, realQuarantine)) {
+        throw new Error(`Cleanup quarantine escaped managed worktree root ${worktreeRoot}.`);
+    }
+}
+async function quarantineAndRemoveRoot(worktreeRoot) {
+    const parent = path.dirname(worktreeRoot);
+    const quarantinePath = path.join(parent, `.forge-cleanup-${path.basename(worktreeRoot)}-${randomUUID()}`);
+    await fs.rename(worktreeRoot, quarantinePath);
+    await fs.rm(quarantinePath, { recursive: true, force: true });
+}
+function parseWorktreeListing(repoPath, output) {
+    const worktrees = [];
+    let current = null;
+    for (const field of output.split("\0")) {
+        if (field.startsWith("worktree ")) {
+            if (current)
+                worktrees.push(current);
+            const rawPath = field.slice("worktree ".length);
+            current = {
+                worktreePath: path.resolve(path.isAbsolute(rawPath) ? rawPath : path.join(repoPath, rawPath)),
+                prunable: false,
+                branchName: null,
+            };
+        }
+        else if (field.startsWith("prunable") && current) {
+            current.prunable = true;
+        }
+        else if (field.startsWith("branch ") && current) {
+            current.branchName = field.slice("branch ".length).trim();
+        }
+    }
+    if (current)
+        worktrees.push(current);
+    return worktrees;
+}
+function isRuntimeReadinessWorktree(worktree) {
+    return worktree.branchName?.startsWith("refs/heads/runtime-readiness-") === true
+        || path.basename(worktree.worktreePath).startsWith("runtime-readiness-");
+}
+function activePaths(worktrees) {
+    return worktrees.filter(entry => !entry.prunable).map(entry => entry.worktreePath);
+}
+function worktreePathState(candidate, activePathsToCheck) {
+    if (activePathsToCheck.some(activePath => samePath(activePath, candidate)))
+        return "active";
+    if (activePathsToCheck.some(activePath => isSubPath(candidate, activePath)))
+        return "ancestor";
+    return "none";
+}
+function uniquePaths(values) {
+    return values.filter((value, index) => values.findIndex(candidate => samePath(candidate, value)) === index);
+}
+function samePath(left, right) {
+    const normalizedLeft = path.resolve(left);
+    const normalizedRight = path.resolve(right);
+    return process.platform === "win32"
+        ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+        : normalizedLeft === normalizedRight;
+}
+function isEnoent(error) {
+    return error?.code === "ENOENT";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/cleanup/cleanup.types.d.ts

@@ -1,6 +1,16 @@
+export type CleanupMode = "stale" | "merged" | "all";
 export interface CleanupRequest {
     readonly repoRoot: string;
+    readonly allowedRepoRoot?: string;
+    readonly mode: CleanupMode;
+    readonly force: boolean;
 }
 export interface CleanupResult {
+    readonly worktreeRoot: string;
     readonly removedWorktrees: number;
+    readonly candidateWorktrees: number;
+    readonly protectedWorktrees: number;
+    readonly skippedUnownedDirectories: number;
+    readonly removedRoot: boolean;
+    readonly dryRun: boolean;
 }

package/dist/cleanup/index.d.ts

@@ -1,2 +1,2 @@
-export { NoopCleanupService } from "./cleanup.service.js";
+export { ManagedWorktreeCleanupService } from "./cleanup.service.js";
 export type { CleanupService } from "./cleanup.base.js";

package/dist/cleanup/index.js

@@ -1 +1 @@
-export { NoopCleanupService } from "./cleanup.service.js";
+export { ManagedWorktreeCleanupService } from "./cleanup.service.js";

package/dist/cleanup/internals.d.ts

@@ -1,3 +1,3 @@
-export { NoopCleanupService } from "./cleanup.service.js";
+export { ManagedWorktreeCleanupService } from "./cleanup.service.js";
 export type { CleanupService } from "./cleanup.base.js";
-export type { CleanupRequest, CleanupResult } from "./cleanup.types.js";
+export type { CleanupMode, CleanupRequest, CleanupResult } from "./cleanup.types.js";

package/dist/cleanup/internals.js

@@ -1 +1 @@
-export { NoopCleanupService } from "./cleanup.service.js";
+export { ManagedWorktreeCleanupService } from "./cleanup.service.js";

package/dist/cli/cli.help.js

@@ -16,9 +16,11 @@ export function helpText() {
         "  connect *        Start the runner bridge and wait for Forge dispatches",
         "  pair *           Pair this machine with Forge and save runner credentials",
         "  status *         Show config, runner identity, repos, provider CLIs, and updates",
+        "  server *         Show or change the saved Forge server URL",
         "  add-repo *       Map a Forge repo label/name to a local checkout path",
         "  remove-repo *    Remove a saved repo mapping",
         "  cleanup *        Prune managed bridge worktrees",
+        "  sandbox *        Initialize, diagnose, smoke-test, or reap Docker sandboxes",
         "  version *        Print the installed bridge package version",
         "  help *           Display help for command",
         "  run-once *       Internal: run one dispatch packet from JSON",
@@ -29,6 +31,7 @@ export function helpText() {
         "  forge-bridge pair 1234-5678 --server https://srv1493013.tail66073d.ts.net:8443 --repo-root \"%USERPROFILE%\\ForgeRepos\"",
         "  forge-bridge connect",
         "  forge-bridge status --check-updates",
+        "  forge-bridge server set http://localhost:5208",
         "  forge-bridge add-repo Forge D:\\Programming\\repos\\Forge",
         "  forge-bridge cleanup --stale",
         "",
@@ -99,6 +102,23 @@ export function commandHelpText(command) {
                 "  forge-bridge status --check-updates",
                 "",
             ].join("\n");
+        case "server":
+            return [
+                "Forge Bridge — server",
+                "Show or change the saved Forge server URL.",
+                "",
+                "Usage:",
+                "  forge-bridge server show",
+                "  forge-bridge server set <url>",
+                "",
+                "The saved runner credentials are retained. Pair again when switching to a different Forge deployment.",
+                "FORGE_URL overrides the saved server when that environment variable is set.",
+                "",
+                "Examples:",
+                "  forge-bridge server set http://localhost:5208",
+                "  forge-bridge server set https://srv1493013.tail66073d.ts.net:8443",
+                "",
+            ].join("\n");
         case "add-repo":
             return [
                 "Forge Bridge — add-repo",
@@ -133,6 +153,32 @@ export function commandHelpText(command) {
                 "  forge-bridge cleanup --all --force",
                 "",
             ].join("\n");
+        case "sandbox":
+            return [
+                "Forge Bridge — sandbox",
+                "Configure local Docker sandbox placement or inspect a repository-owned sandbox contract.",
+                "",
+                "Usage:",
+                "  forge-bridge sandbox on [--allow-open-public]",
+                "  forge-bridge sandbox off",
+                "  forge-bridge sandbox status",
+                "  forge-bridge sandbox init [--repo <path>]",
+                "  forge-bridge sandbox doctor [--repo <path>] [--require-pinned-base]",
+                "  forge-bridge sandbox smoke [--repo <path>] [--report <path>] [--require-pinned-base] [--probe-loopback-port]",
+                "  forge-bridge sandbox reap",
+                "",
+                "`sandbox on` keeps unrestricted public networking denied unless the explicit",
+                "developer-only --allow-open-public option is supplied. The local policy is",
+                "saved in bridge.json and takes effect after the connected bridge restarts.",
+                "Environment variables remain higher-priority operator overrides.",
+                "",
+                "The smoke command builds the repository Dockerfile, runs a disposable hardened",
+                "container, verifies exact-label teardown, and writes a redacted JSON report.",
+                "The optional port probe publishes 127.0.0.1::8080 only for the disposable fixture",
+                "and verifies Docker-assigned host-port discovery; normal sandboxes publish no ports.",
+                "Stop the connected bridge first so the Docker ownership lock can be acquired.",
+                "",
+            ].join("\n");
         case "run-once":
             return [
                 "Forge Bridge — run-once",
@@ -148,7 +194,7 @@ export function commandHelpText(command) {
                 "Internal MCP server used by provider CLIs to report Forge phase artifacts.",
                 "",
                 "Usage:",
-                "  forge-bridge mcp --worktree <path> --work-item-id <id> --phase <phase>",
+                "  forge-bridge mcp --worktree <path> --work-item-id <id> --phase <phase>  # includes ci-repair",
                 "",
             ].join("\n");
         case "version":