@loucompanion/forge-bridge 0.1.3-dev.b6be5e7f9668 → 0.1.3-dev.ba7d36726eda

package/dist/bridge/bridge.types.d.ts

@@ -1,7 +1,33 @@
-import type { RunOnceResultPacket, RunnerDispatchEvent } from "../session/session.types.js";
+import type { ApiKeySecretGrant, DispatchSandboxResourceRequest, RunOnceResultPacket, RunnerDispatchEvent } from "../session/session.types.js";
+import type { SandboxFeatureMatrix } from "../sandbox/sandbox.types.js";
+import type { HostRuntimeCapacitySnapshot } from "../runtime/host-runtime-lease.js";
 export interface BridgeServiceConfig {
     readonly serverUrl: string;
     readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly trustDomainId: string;
+    readonly maxConcurrentSandboxes: number;
+    readonly maxConcurrentSandboxBuilds: number;
+    readonly sandboxPidCapacity: number;
+    readonly dockerEnabled: boolean;
+    readonly allowOpenPublicSandbox: boolean;
+    readonly sandboxPublicationMode?: "bridge_push" | "shared_filesystem";
+    readonly dockerExecutable: string;
+    readonly dockerContext: string;
+    readonly sandboxStateRoot: string;
+    readonly requireRootlessDocker: boolean;
+    readonly diskHighWatermarkPercent: number;
+    readonly diskLowWatermarkPercent: number;
+    readonly minimumWorkspaceBytes: number;
+    readonly sandboxHostMemoryReserveBytes?: number;
+    readonly defaultSandboxWorkerMemoryLimitBytes: number;
+    readonly defaultSandboxServiceMemoryLimitBytes: number;
+    readonly sandboxRuntimeOverheadBytes: number;
+    readonly sandboxMemorySampleIntervalMs: number;
+    readonly imageRetentionCount: number;
+    readonly imageRetentionTtlMs: number;
+    readonly auditRetentionCount: number;
+    readonly auditRetentionTtlMs: number;
     readonly deviceToken: string;
     readonly deviceName: string;
     readonly defaultRepoRoot: string;
@@ -17,6 +43,8 @@ export interface BridgeServiceConfig {
     readonly supportsManagedForgeArtifacts: boolean;
     readonly supportsRunnerAuthoredPhaseArtifacts: boolean;
     readonly supportsDraftRunOnce: boolean;
+    readonly supportsDraftAttachments: boolean;
+    readonly supportsDraftImageAttachments: boolean;
     readonly version: string;
     readonly protocolVersion: number;
     readonly minServerVersion?: string | null;
@@ -52,17 +80,63 @@ export interface BridgeCapabilities {
     readonly repoMappings?: readonly BridgeRepoMapping[] | null;
     readonly os?: string | null;
     readonly sandboxProfiles?: readonly string[] | null;
+    readonly runnerInstanceId?: string | null;
+    readonly trustDomainId?: string | null;
+    readonly sandboxRuntimes?: readonly string[] | null;
+    readonly sandboxRuntimeVersion?: string | null;
+    readonly sandboxFeatures?: SandboxFeatureMatrix | null;
+    readonly sandboxPublicationModes?: readonly string[] | null;
+    readonly sandboxAuthModes?: Readonly<Record<string, readonly string[]>> | null;
+    readonly maxConcurrentSandboxes?: number | null;
+    readonly reservedSandboxCount?: number | null;
+    readonly activeSandboxCount?: number | null;
+    readonly startingSandboxCount?: number | null;
+    readonly degradedReservationCount?: number | null;
+    readonly availableMemoryBytes?: number | null;
+    readonly availableCpuMillis?: number | null;
+    readonly availableWorkspaceBytes?: number | null;
+    readonly diskLow?: boolean | null;
+    readonly preflightGeneration?: number | null;
+    readonly sandboxUnavailableCode?: string | null;
+    readonly sandboxUnavailableReason?: string | null;
+    readonly sandboxMemoryCapacity?: SandboxMemoryCapacityDiagnostics | null;
+    readonly hostRuntime?: HostRuntimeCapacitySnapshot | null;
     readonly supportsApiSecretGrant?: boolean | null;
     readonly supportsManagedWorktrees?: boolean | null;
     readonly supportsManagedForgeArtifacts?: boolean | null;
     readonly supportsRunnerAuthoredPhaseArtifacts?: boolean | null;
     readonly supportsDraftRunOnce?: boolean | null;
+    readonly supportsDraftAttachments?: boolean | null;
+    readonly supportsDraftImageAttachments?: boolean | null;
+}
+export interface SandboxMemoryCapacityDiagnostics {
+    readonly defaultWorkerMemoryLimitBytes: number;
+    readonly defaultServiceMemoryLimitBytes: number;
+    readonly runtimeOverheadBytes: number;
+    readonly hostReserveBytes: number;
+    readonly activeReservationBytes: number;
+    readonly daemonTotalBytes: number;
+    readonly daemonAvailableBytes: number;
+    readonly availableForAdmissionBytes: number;
 }
 export interface BridgeHelloRequest {
     readonly version: string;
     readonly protocolVersion: number;
     readonly capabilities: BridgeCapabilities;
     readonly minServerVersion?: string | null;
+    readonly runnerInstanceId: string;
+}
+export interface BridgePublishCredential {
+    readonly username: string;
+    readonly secret: string;
+    readonly remoteUrl: string;
+    readonly expiresAt: string;
+}
+export interface BridgePublishGrantRedemptionResponse {
+    readonly accepted: boolean;
+    readonly code?: string | null;
+    readonly message?: string | null;
+    readonly credential?: BridgePublishCredential | null;
 }
 export interface BridgeHeartbeatRequest {
     readonly status?: string | null;
@@ -78,17 +152,77 @@ export interface BridgeCallbackAck {
 export interface BridgeDispatchEventCallback {
     readonly leaseId: string;
     readonly fencingToken: string;
+    readonly dispatchAttemptId?: string | null;
+    readonly runnerInstanceId?: string | null;
     readonly event: RunnerDispatchEvent;
 }
 export interface BridgeDispatchResultCallback {
     readonly leaseId: string;
     readonly fencingToken: string;
+    readonly dispatchAttemptId?: string | null;
+    readonly runnerInstanceId?: string | null;
     readonly result: RunOnceResultPacket;
 }
+export interface BridgeOfferDecisionCallback {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly accepted: boolean;
+    readonly code?: string | null;
+    readonly message?: string | null;
+    readonly reservedUntil?: string | null;
+    readonly reservedResources?: DispatchSandboxResourceRequest | null;
+    readonly sandboxConfigCommitSha?: string | null;
+}
+export interface BridgeDispatchStartedCallback {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+}
+export interface BridgeSecretGrantRedemptionRequest {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly grantId: string;
+}
+export interface BridgeSecretGrantRedemptionResponse extends BridgeCallbackAck {
+    readonly grant?: ApiKeySecretGrant | null;
+}
+export interface BridgeLeaseUpdateRequest {
+    readonly dispatchAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly expiresAt: string;
+}
 export interface BridgeCancelRequest {
     readonly leaseId: string;
     readonly fencingToken: string;
     readonly reason?: string | null;
 }
+export interface BridgeReapRequest {
+    readonly runnerId: string;
+    readonly runnerInstanceId: string;
+    readonly requestedAt: string;
+    readonly reason?: string | null;
+}
+export interface BridgeAttemptSnapshotItem {
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly runnerInstanceId: string;
+    readonly status: string;
+    readonly expiresAt: string;
+}
+export interface BridgeAttemptSnapshotResponse extends BridgeCallbackAck {
+    readonly attempts?: readonly BridgeAttemptSnapshotItem[] | null;
+    readonly generatedAt?: string | null;
+}
 export type BridgeDispatchHandler = (dispatch: unknown) => Promise<void>;
+export type BridgeOfferHandler = (dispatch: unknown) => Promise<void>;
+export type BridgeStartHandler = (dispatch: unknown) => Promise<void>;
+export type BridgeLeaseUpdateHandler = (request: BridgeLeaseUpdateRequest) => Promise<void>;
 export type BridgeCancelHandler = (request: BridgeCancelRequest) => Promise<void>;
+export type BridgeReapHandler = (request: BridgeReapRequest) => Promise<void>;

package/dist/cleanup/cleanup.service.d.ts

@@ -1,5 +1,16 @@
+import { GitClient } from "../shared/git/git.js";
+import type { WorktreeLifecycleCoordinator } from "../worktree/worktree.base.js";
 import type { CleanupService } from "./cleanup.base.js";
 import type { CleanupRequest, CleanupResult } from "./cleanup.types.js";
-export declare class NoopCleanupService implements CleanupService {
-    run(_request: CleanupRequest): Promise<CleanupResult>;
+export declare class ManagedWorktreeCleanupService implements CleanupService {
+    private readonly stateRoot;
+    private readonly git;
+    private readonly coordinator;
+    constructor(stateRoot?: string, git?: GitClient, coordinator?: WorktreeLifecycleCoordinator);
+    run(request: CleanupRequest): Promise<CleanupResult>;
+    private runLocked;
+    private listWorktrees;
+    private scanManagedCandidates;
+    private readRuntimeLeases;
+    private worktreeMetadataRoot;
 }

package/dist/cleanup/cleanup.service.js

@@ -1,5 +1,437 @@
-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 } from "../shared/path/path.js";
+import { validRuntimeIsolationLease } from "../runtime/runtime-isolation-lease.js";
+import { defaultWorktreeCoordinatorStateRoot, resolveManagedWorktreeRootForRepo, } from "../worktree/worktree-paths.js";
+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 = await resolveExistingDirectoryPath(request.repoRoot);
+        const worktreeRoot = resolveManagedWorktreeRootForRepo(repoPath, request.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 metadataRoot = await this.worktreeMetadataRoot(repoPath);
+        const activeWorktrees = activePaths(listedWorktrees);
+        const activeRuntimePaths = runtimeLeases
+            .filter(lease => lease.state !== "released")
+            .map(lease => path.resolve(lease.worktreePath));
+        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 currentlyProtected = [
+                ...activePaths(currentWorktrees),
+                ...currentLeases.filter(lease => lease.state !== "released").map(lease => path.resolve(lease.worktreePath)),
+            ];
+            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 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 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,
+            };
+        }
+        else if (field.startsWith("prunable") && current) {
+            current.prunable = true;
+        }
+    }
+    if (current)
+        worktrees.push(current);
+    return worktrees;
+}
+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";