@ricsam/r5d-worker 0.0.121 → 0.0.123

package/dist/mjs/main.mjs

@@ -25,6 +25,13 @@ import { Database } from "bun:sqlite";
 import { installCliUpdate, readInstalledCliVersion } from "./cli-update.mjs";
 import { gitTransportSecurityArgs, workerGitProcessEnvironment } from "./git-process-environment.mjs";
 import { terminateProcessTree } from "./process-tree.mjs";
+import { ProjectCheckoutGarbageCollector } from "./project-checkout-garbage.mjs";
+import {
+  assertControlCommandArgv,
+  CONTROL_COMMAND_RUNTIME_MS,
+  controlCommandEnvironment,
+  resolveControlCommandExecutable
+} from "./control-command-policy.mjs";
 import { createPtyOutputCoalescer } from "./pty-output-coalescer.mjs";
 import { openWorkerPortForwardRelay } from "./port-forward-client.mjs";
 import {
@@ -176,6 +183,26 @@ const PTY_FOREGROUND_POLL_MS = 1e3;
 const PTY_FOREGROUND_IDLE_ENABLED = process.env.R5D_PTY_FOREGROUND_IDLE !== "0";
 const PTY_TMP_PATH_PREFIX = "r5d-worker-tmp://";
 let workerCommandLauncher;
+const trustedControlPath = process.env.PATH;
+let capacityReportTimer;
+let capacityReportSocket = null;
+let lastCapacityReport;
+function scheduleCapacityReport(force = false) {
+  if (force) lastCapacityReport = void 0;
+  if (capacityReportTimer) return;
+  capacityReportTimer = setTimeout(() => {
+    capacityReportTimer = void 0;
+    const ws = capacityReportSocket;
+    if (!ws || ws.readyState !== WebSocket.OPEN || !workerCommandLauncher) return;
+    const capacity = { ...workerCommandLauncher.capacityReport(), reportedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    const { reportedAt: _reportedAt, ...comparable } = capacity;
+    const serialized = JSON.stringify(comparable);
+    if (serialized === lastCapacityReport) return;
+    lastCapacityReport = serialized;
+    sendWorkerMessage(ws, { type: "capacity_report", capacity });
+  }, 100);
+  capacityReportTimer.unref?.();
+}
 const activeProcesses = /* @__PURE__ */ new Map();
 const credentialBearingProcessGroups = /* @__PURE__ */ new Map();
 const credentialBearingProcessGroupTargets = /* @__PURE__ */ new Map();
@@ -293,6 +320,15 @@ let workerAdmissionGeneration = 0;
 const workspaceMutationGate = new WorkspaceMutationGate();
 let workspaceSyncQueue = Promise.resolve();
 let startupProjectSnapshotRecoveryCompleted = false;
+const checkoutGarbageCollectors = /* @__PURE__ */ new Map();
+function checkoutGarbageCollectorFor(projectsRoot) {
+  let collector = checkoutGarbageCollectors.get(projectsRoot);
+  if (!collector) {
+    collector = new ProjectCheckoutGarbageCollector({ projectsRoot });
+    checkoutGarbageCollectors.set(projectsRoot, collector);
+  }
+  return collector;
+}
 const workspaceSyncSingleFlight = {
   runExclusive(operation) {
     const queued = workspaceMutationGate.runSync(operation);
@@ -2784,6 +2820,10 @@ function cancelWorkerCommandLaunch(resources) {
   });
 }
 async function acquireWorkerCommandLaunch(ws, message, assertAdmission) {
+  if (message.type === "exec_start" && message.commandClass === "control") {
+    assertControlCommandArgv(message.argv);
+    if (message.interactive) throw new Error("Control commands cannot be interactive");
+  }
   const id = message.type === "pty_open" ? `pty:${message.ptyId}` : message.runId;
   const operationId = message.type === "pty_open" ? id : `exec:${id}`;
   sendWorkerMessage(ws, { type: "heartbeat_lease", operationId, active: true });
@@ -2792,6 +2832,7 @@ async function acquireWorkerCommandLaunch(ws, message, assertAdmission) {
       id,
       kind: message.type,
       ..."workspaceEffect" in message && message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {},
+      ...message.type === "exec_start" && message.commandClass === "control" ? { commandClass: "control" } : {},
       ..."sessionId" in message && message.sessionId ? { sessionId: message.sessionId } : {},
       assertAdmission: () => {
         assertAdmission();
@@ -2939,8 +2980,17 @@ async function executeStreamingCommand(input) {
     });
     const cwd = resolveCommandCwd(input.resolvedTarget.rootPath, input.message.cwd);
     const interactive = input.message.interactive === true;
+    const control = input.message.commandClass === "control";
+    let argv = input.message.argv;
+    let environment = workerChildProcessEnvironment([githubProcessEnv(), input.message.env ?? {}, targetProcessEnv2]);
+    if (control) {
+      assertControlCommandArgv(argv);
+      if (interactive) throw new Error("Control commands cannot be interactive");
+      argv = [resolveControlCommandExecutable(trustedControlPath, (program, options) => Bun.which(program, options)), ...argv.slice(1)];
+      environment = controlCommandEnvironment(environment, trustedControlPath);
+    }
     input.assertAdmission();
-    const subprocess = Bun.spawn(input.resources.wrap(input.message.argv), {
+    const subprocess = Bun.spawn(input.resources.wrap(argv), {
       cwd,
       // Without an explicit stdin the process reads /dev/null and interactive
       // prompts see immediate EOF; "pipe" keeps stdin open for exec_stdin.
@@ -2948,7 +2998,7 @@ async function executeStreamingCommand(input) {
       stdout: "pipe",
       stderr: "pipe",
       detached: true,
-      env: workerChildProcessEnvironment([githubProcessEnv(), input.message.env ?? {}, targetProcessEnv2])
+      env: environment
     });
     spawnedProcess = subprocess;
     credentialBearingProcessGroups.set(subprocess.pid, subprocess);
@@ -2963,12 +3013,13 @@ async function executeStreamingCommand(input) {
       pid: subprocess.pid,
       processGroupId: process.platform === "win32" ? void 0 : subprocess.pid,
       credentialId: input.message.credentialId,
-      argv: input.message.argv,
+      argv,
       command: input.message.command,
       cwd,
       startedAt: (/* @__PURE__ */ new Date()).toISOString(),
       ...interactive ? { interactive: true, stdin: subprocess.stdin } : {},
-      ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
+      ...input.message.workspaceEffect === "none" ? { workspaceEffect: "none" } : {},
+      ...control ? { commandClass: "control" } : {}
     });
     settlePreparation();
     started = true;
@@ -2980,7 +3031,8 @@ async function executeStreamingCommand(input) {
       pid: subprocess.pid,
       ...process.platform === "win32" ? {} : { processGroupId: subprocess.pid }
     });
-    if (input.message.timeoutMs) {
+    const timeoutMs = control ? Math.min(input.message.timeoutMs ?? CONTROL_COMMAND_RUNTIME_MS, CONTROL_COMMAND_RUNTIME_MS) : input.message.timeoutMs;
+    if (timeoutMs) {
       timeout = setTimeout(() => {
         timedOut = true;
         cancelWorkerCommandLaunch(input.resources);
@@ -2991,7 +3043,7 @@ async function executeStreamingCommand(input) {
 `
           );
         });
-      }, input.message.timeoutMs);
+      }, timeoutMs);
     }
     const [exitCode] = await Promise.all([
       subprocess.exited,
@@ -3154,7 +3206,8 @@ function buildActiveProcessReports() {
     ...active.cwd ? { cwd: active.cwd } : {},
     startedAt: active.startedAt,
     ...active.interactive ? { interactive: true } : {},
-    ...active.workspaceEffect === "none" ? { workspaceEffect: "none" } : {}
+    ...active.workspaceEffect === "none" ? { workspaceEffect: "none" } : {},
+    ...active.commandClass ? { commandClass: active.commandClass } : {}
   }));
 }
 function sendActiveProcessReport(ws) {
@@ -3676,6 +3729,7 @@ async function startWorker(options, projectRuntime = {
   validateLabel(label);
   if (!workerCommandLauncher) {
     const launcher = await createWorkerCommandLauncher({
+      onCapacityChange: () => scheduleCapacityReport(),
       configuration: process.env.R5D_WORKER_COMMAND_LAUNCHER,
       env: commandLauncherEnvironment(),
       onFailure: handleWorkerCommandLauncherFailure
@@ -3723,6 +3777,12 @@ async function startWorker(options, projectRuntime = {
   projectRuntime.initializedWorkspaceState = initializedWorkspaceState;
   const projectWorkspaceStateStore = initializedWorkspaceState.store;
   let projectWorkspaceState = initializedWorkspaceState.store.read();
+  const checkoutGarbageCollector = checkoutGarbageCollectorFor(projectsRoot);
+  const staleStagedCheckouts = checkoutGarbageCollector.sweep();
+  if (staleStagedCheckouts > 0) {
+    process.stderr.write(`[r5d-worker] collecting ${staleStagedCheckouts} deleted checkout(s) left from an earlier run
+`);
+  }
   const { projectConfigById, readyProjectIds, reconciledProjectConfigFingerprints } = projectRuntime;
   const pendingCheckouts = /* @__PURE__ */ new Map();
   const lastObservedProjectHeads = /* @__PURE__ */ new Map();
@@ -3837,6 +3897,7 @@ async function startWorker(options, projectRuntime = {
 `
         );
       }
+      if (deleted.stagedForCollectionPath) checkoutGarbageCollector.enqueue(deleted.stagedForCollectionPath);
     }
     const planSourcePath = path.join(planRoot, project.projectId, ...branchName.split("/"));
     fs.rmSync(planSourcePath, { recursive: true, force: true });
@@ -3920,6 +3981,7 @@ async function startWorker(options, projectRuntime = {
 `
       );
     }
+    if (deleted.stagedForCollectionPath) checkoutGarbageCollector.enqueue(deleted.stagedForCollectionPath);
     fs.rmSync(path.join(planRoot, project.projectId, ...branchName.split("/")), { recursive: true, force: true });
     readyProjectIds.delete(project.projectId);
     reconciledProjectConfigFingerprints.delete(project.projectId);
@@ -5854,6 +5916,8 @@ async function startWorker(options, projectRuntime = {
           workspaceIncidentConfigDeferralV1: true,
           workspaceConfigResetToCanonicalV1: true,
           projectBranchDeletionFastAckV1: true,
+          projectBranchDeletionStagedRemovalV1: true,
+          commandControlLaneV1: workerCommandLauncher?.supportsControlLane === true,
           projectMirrorLeaseV1: true,
           projectMirrorRefsTokensV1: true,
           projectBranchWorkingTreeModeV1: true
@@ -5955,7 +6019,9 @@ async function startWorker(options, projectRuntime = {
         if (admission !== "new") {
           const response = recoveryStore.response(operationRequestId);
           if (response && admission !== "unknown") sendReplayWorkerMessage(ws, response);
-          return;
+          if (!(admission === "unknown" && message.type === "delete_project_branch" && recoveryStore.readmitUnknownBranchDeletion(operationRequestId))) {
+            return;
+          }
         }
       }
       const messageAdmissionGeneration = workerAdmissionGeneration;
@@ -5978,6 +6044,8 @@ async function startWorker(options, projectRuntime = {
         });
       };
       if (message.type === "connected") {
+        capacityReportSocket = ws;
+        scheduleCapacityReport(true);
         return;
       }
       if (message.type === "project_mirror_refs_tokens") {
@@ -6733,8 +6801,10 @@ async function startWorker(options, projectRuntime = {
         const runCommand = async () => {
           try {
             const resolvedTarget = resolveMessageTarget(message.target);
-            process.stdout.write(`[r5d-worker] exec_start ${message.runId}: ${message.argv.join(" ")}
-`);
+            process.stdout.write(
+              `[r5d-worker] exec_start ${message.runId}${message.commandClass === "control" ? " (control)" : ""}: ${message.argv.join(" ")}
+`
+            );
             await executeStreamingCommand({
               resources,
               ws,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.121",
+  "version": "0.0.123",
   "type": "module"
 }

package/dist/mjs/project-checkout-garbage.mjs

@@ -0,0 +1,150 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const PROJECT_DELETED_CHECKOUTS_DIRECTORY = ".r5d-deleted";
+function isRealDirectory(candidate) {
+  try {
+    return fs.lstatSync(candidate).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function stageProjectCheckoutForDeletion(projectRoot, branchName, checkoutPath) {
+  const garbageRoot = path.join(projectRoot, PROJECT_DELETED_CHECKOUTS_DIRECTORY);
+  if (!isRealDirectory(checkoutPath)) throw new Error(`Cannot stage ${checkoutPath} for deletion: not a directory`);
+  fs.mkdirSync(garbageRoot, { recursive: true });
+  if (!isRealDirectory(garbageRoot)) throw new Error(`Cannot stage ${checkoutPath} for deletion: ${garbageRoot} is not a directory`);
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const target = path.join(garbageRoot, `${branchName.replace(/\//g, "__")}-${timestamp}-${randomUUID().slice(0, 8)}`);
+  fs.renameSync(checkoutPath, target);
+  return target;
+}
+function isStagedProjectCheckoutPath(projectsRoot, candidate) {
+  const relative = path.relative(path.resolve(projectsRoot), path.resolve(candidate));
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return false;
+  const segments = relative.split(path.sep);
+  return segments.length === 4 && segments[2] === PROJECT_DELETED_CHECKOUTS_DIRECTORY && segments[3] !== "" && !segments[3].startsWith(".");
+}
+function ownedStagedPath(projectsRoot, candidate) {
+  const root = path.resolve(projectsRoot);
+  const resolved = path.resolve(candidate);
+  if (!isStagedProjectCheckoutPath(root, resolved)) return null;
+  let current = root;
+  for (const segment of path.relative(root, path.dirname(resolved)).split(path.sep)) {
+    current = path.join(current, segment);
+    if (!isRealDirectory(current)) return null;
+  }
+  let stat;
+  try {
+    stat = fs.lstatSync(resolved);
+  } catch {
+    return null;
+  }
+  if (stat.isSymbolicLink()) return { kind: "link" };
+  return stat.isDirectory() ? { kind: "directory" } : null;
+}
+function realDirectoryEntries(directory) {
+  if (!isRealDirectory(directory)) return [];
+  try {
+    return fs.readdirSync(directory, { withFileTypes: true }).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+function discoverStagedProjectCheckouts(projectsRoot) {
+  const root = path.resolve(projectsRoot);
+  const staged = [];
+  for (const namespace of realDirectoryEntries(root)) {
+    if (namespace.startsWith(".")) continue;
+    for (const project of realDirectoryEntries(path.join(root, namespace))) {
+      if (project.startsWith(".")) continue;
+      const garbageRoot = path.join(root, namespace, project, PROJECT_DELETED_CHECKOUTS_DIRECTORY);
+      for (const entry of realDirectoryEntries(garbageRoot)) {
+        const candidate = path.join(garbageRoot, entry);
+        if (ownedStagedPath(root, candidate)) staged.push(candidate);
+      }
+    }
+  }
+  return staged;
+}
+async function removeStagedProjectCheckout(stagedPath) {
+  if (fs.lstatSync(stagedPath).isSymbolicLink()) {
+    fs.unlinkSync(stagedPath);
+    return;
+  }
+  if (process.platform === "win32") {
+    await fs.promises.rm(stagedPath, { recursive: true, force: true });
+    return;
+  }
+  const command = ["rm", "-rf", "--", stagedPath];
+  if (Bun.which("nice")) command.unshift("nice", "-n", "19");
+  if (process.platform === "linux" && Bun.which("ionice")) command.unshift("ionice", "-c", "3");
+  const child = Bun.spawn(command, { stdin: "ignore", stdout: "ignore", stderr: "pipe" });
+  const [exitCode, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+  if (exitCode !== 0) throw new Error(`rm exited ${exitCode}: ${stderr.trim()}`);
+  if (fs.existsSync(stagedPath)) throw new Error("staged checkout still exists after removal");
+}
+class ProjectCheckoutGarbageCollector {
+  projectsRoot;
+  remove;
+  log;
+  queued = /* @__PURE__ */ new Set();
+  tail = Promise.resolve();
+  collectedCount = 0;
+  constructor(options) {
+    this.projectsRoot = path.resolve(options.projectsRoot);
+    this.remove = options.remove ?? removeStagedProjectCheckout;
+    this.log = options.log ?? ((message) => process.stderr.write(`${message}
+`));
+  }
+  /** Number of removals that have completed successfully. */
+  get collected() {
+    return this.collectedCount;
+  }
+  /** Resolves once everything queued so far has been attempted. */
+  get idle() {
+    return this.tail;
+  }
+  enqueue(stagedPath) {
+    const resolved = path.resolve(stagedPath);
+    if (!ownedStagedPath(this.projectsRoot, resolved)) {
+      throw new Error(`Refusing to collect ${stagedPath}: not a staged checkout under ${this.projectsRoot}`);
+    }
+    if (this.queued.has(resolved)) return;
+    this.queued.add(resolved);
+    this.tail = this.tail.then(async () => {
+      try {
+        const owned = ownedStagedPath(this.projectsRoot, resolved);
+        if (owned) {
+          const startedAt = performance.now();
+          await this.remove(resolved);
+          this.collectedCount += 1;
+          this.log(`[r5d-worker] collected deleted checkout ${resolved} in ${Math.round(performance.now() - startedAt)}ms`);
+        } else if (fs.existsSync(resolved) || isRealDirectory(path.dirname(resolved))) {
+          this.log(`[r5d-worker] skipped deleted checkout ${resolved}: no longer an owned staged checkout`);
+        }
+      } catch (error) {
+        this.log(
+          `[r5d-worker] deleted checkout ${resolved} could not be collected yet: ${error instanceof Error ? error.message : String(error)}`
+        );
+      } finally {
+        this.queued.delete(resolved);
+      }
+    });
+  }
+  /** Enqueue every staged checkout left behind by an earlier process. */
+  sweep() {
+    const staged = discoverStagedProjectCheckouts(this.projectsRoot);
+    for (const stagedPath of staged) this.enqueue(stagedPath);
+    return staged.length;
+  }
+}
+export {
+  PROJECT_DELETED_CHECKOUTS_DIRECTORY,
+  ProjectCheckoutGarbageCollector,
+  discoverStagedProjectCheckouts,
+  isStagedProjectCheckoutPath,
+  ownedStagedPath,
+  removeStagedProjectCheckout,
+  stageProjectCheckoutForDeletion
+};

package/dist/mjs/project-worktrees.mjs

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { gitCredentialUsernameConfigKey, gitTransportSecurityArgs, workerGitProcessEnvironment } from "./git-process-environment.mjs";
 import { validateManagedBranchName } from "./managed-paths.mjs";
+import { stageProjectCheckoutForDeletion } from "./project-checkout-garbage.mjs";
 import {
   canonicalizeLocalProjectMirrorRefs,
   parseProjectMirrorRefListing,
@@ -1290,6 +1291,7 @@ function deleteLinkedProjectBranch(input) {
   const primaryCommonDir = commonGitDirectory(primaryPath);
   if (!primaryCommonDir) throw new Error("Primary project checkout is unavailable");
   let movedAsidePath;
+  let stagedForCollectionPath;
   if (fs.existsSync(checkoutPath)) {
     const checkoutCommonDir = fs.lstatSync(checkoutPath).isDirectory() ? commonGitDirectory(checkoutPath) : null;
     if (checkoutCommonDir !== primaryCommonDir) {
@@ -1299,7 +1301,8 @@ function deleteLinkedProjectBranch(input) {
       if (projectWorktreeOperationInProgress(checkoutPath)) {
         throw new Error(`Project branch ${input.branchName} has an in-progress Git operation`);
       }
-      git(primaryPath, ["worktree", "remove", "--force", checkoutPath], `remove linked worktree ${input.branchName}`);
+      stagedForCollectionPath = stageProjectCheckoutForDeletion(input.projectRoot, input.branchName, checkoutPath);
+      git(primaryPath, ["worktree", "prune"], `prune linked worktree ${input.branchName}`);
     }
   } else {
     tryGit(primaryPath, ["worktree", "prune"]);
@@ -1308,7 +1311,11 @@ function deleteLinkedProjectBranch(input) {
   if (tryGit(primaryPath, ["show-ref", "--verify", "--quiet", branchRef])) {
     git(primaryPath, ["branch", "-D", input.branchName], `delete project branch ${input.branchName}`);
   }
-  return { branchName: input.branchName, ...movedAsidePath ? { movedAsidePath } : {} };
+  return {
+    branchName: input.branchName,
+    ...movedAsidePath ? { movedAsidePath } : {},
+    ...stagedForCollectionPath ? { stagedForCollectionPath } : {}
+  };
 }
 function removeProjectWorktrees(input) {
   const projectRoot = path.resolve(input.projectRoot);

package/dist/mjs/recovery-store.mjs

@@ -64,6 +64,19 @@ class WorkerRecoveryStore {
   isUnknown(requestId) {
     return this.row(requestId)?.state === "unknown";
   }
+  /**
+   * Re-admit an operation whose crash outcome is unknown so it can run again
+   * and record a result. Only a branch deletion qualifies: it is idempotent
+   * for its exact incarnation (durable tombstone plus incarnation preflight),
+   * so a rerun converges on the same outcome. Every other unknown operation
+   * keeps the no-replay invariant.
+   */
+  readmitUnknownBranchDeletion(requestId) {
+    const row = this.row(requestId);
+    if (!row || row.state !== "unknown" || row.request_type !== "delete_project_branch") return false;
+    this.db.run("UPDATE operations SET state='accepted', response=NULL WHERE request_id=?", [row.request_id]);
+    return true;
+  }
   unknown(requestId) {
     const row = this.row(requestId);
     if (row) this.db.run("UPDATE operations SET state='unknown' WHERE request_id=?", [row.request_id]);

package/dist/types/command-launcher.d.ts

@@ -2,9 +2,42 @@ export type CommandLaunchRequest = {
     id: string;
     kind: "exec" | "exec_start" | "pty_open";
     workspaceEffect?: "none";
+    /** An explicitly classified short coordination command; the launcher keeps a bounded lane for these. */
+    commandClass?: "control";
     sessionId?: string;
     assertAdmission: () => void;
 };
+export type CommandLaunchLane = "general" | "utility" | "control";
+export type CommandLaunchCapacity = {
+    generalSlots: number;
+    utilitySlots: number;
+    controlSlots: number;
+    controlRuntimeMs: number;
+    queueTimeoutMs: number;
+};
+export type CommandLaunchLaneReport = {
+    /** Null when no launcher bounds this lane (direct execution). */
+    slots: number | null;
+    active: Array<{
+        id: string;
+        sessionId?: string;
+        since: string;
+    }>;
+    queued: Array<{
+        id: string;
+        sessionId?: string;
+        since: string;
+    }>;
+};
+/** Who holds and who waits for each lane, as the worker sees its own admissions. */
+export type CommandLaunchCapacityReport = {
+    /** False for a direct worker: nothing is bounded and nothing can be starved. */
+    bounded: boolean;
+    controlRuntimeMs: number | null;
+    lanes: Record<CommandLaunchLane, CommandLaunchLaneReport>;
+};
+/** The same lane rule the managed launcher applies; kept here so reports match admissions. */
+export declare function commandLaunchLane(request: Pick<CommandLaunchRequest, "kind" | "workspaceEffect" | "commandClass">): CommandLaunchLane;
 export type CommandLaunchLease = {
     wrap(argv: string[]): string[];
     cancel(): Promise<void>;
@@ -33,6 +66,7 @@ export declare class WorkerCommandLauncher {
     private initialized;
     private closePromise?;
     private sequence;
+    private capacity?;
     constructor(options?: {
         argv?: string[];
         env?: NodeJS.ProcessEnv;
@@ -40,9 +74,17 @@ export declare class WorkerCommandLauncher {
         onStderr?: (text: string) => void;
         requestTimeoutMs?: number;
         acquisitionTimeoutMs?: number;
+        /** Called after any admission changes lane, phase, or is released. */
+        onCapacityChange?: () => void;
     });
     initialize(): Promise<void>;
     get activeIds(): string[];
+    /** The lane totals the launcher declared at initialization; undefined for a direct worker or an older launcher. */
+    get declaredCapacity(): CommandLaunchCapacity | undefined;
+    get supportsControlLane(): boolean;
+    /** Current admissions per lane, for the worker's capacity report. */
+    capacityReport(): CommandLaunchCapacityReport;
+    private notifyCapacityChange;
     acquire(request: CommandLaunchRequest): Promise<CommandLaunchLease>;
     cancel(id: string): Promise<void>;
     cancelSession(sessionId: string): Promise<void>;

package/dist/types/control-command-policy.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Which agent shell invocations may run in the managed launcher's bounded
+ * `control` lane: exactly one plain `r5dctl` coordination/diagnosis command.
+ *
+ * The lane exists so an agent can inspect capacity, message another session,
+ * or stop its own runs while every general slot is held by long work
+ * (incident 9). It is bounded (small memory, few PIDs, a runtime limit), so
+ * only commands that are short HTTP calls to the platform qualify. The
+ * classifier fails closed: anything the shell would interpret (operators,
+ * substitutions, expansions, quoting the tokenizer cannot prove literal,
+ * environment assignments, wrapper programs, paths) is refused and keeps its
+ * ordinary general-lane shell semantics. The resulting argv is validated a
+ * second time by the worker before it is spawned without a shell.
+ */
+export declare const CONTROL_COMMAND_PROGRAM = "r5dctl";
+/** Worker-side runtime bound for a control run; the launcher enforces its own limit as a backstop. */
+export declare const CONTROL_COMMAND_RUNTIME_MS = 120000;
+export declare const CONTROL_COMMAND_MAX_ARGV = 64;
+export declare const CONTROL_COMMAND_MAX_LENGTH = 4096;
+export type ControlCommandClassification = {
+    control: true;
+    argv: string[];
+} | {
+    control: false;
+    reason: string;
+};
+/**
+ * Validate an argv as an allowed r5dctl coordination invocation. Used on the
+ * server after tokenizing, and again on the worker before spawning.
+ */
+export declare function assertControlCommandArgv(argv: readonly string[]): void;
+/**
+ * Locate the installed CLI through the worker's own, operator-controlled
+ * search path. The command's cwd, its environment, and any checkout-local
+ * shim play no part, so a project cannot substitute the executable the
+ * reserved lane runs.
+ */
+export declare function resolveControlCommandExecutable(trustedPath: string | undefined, which: (program: string, options: {
+    PATH: string;
+}) => string | null, program?: string): string;
+/**
+ * The environment a control spawn receives: everything the platform sets for
+ * the run (credentials, session identity, declared project values) minus any
+ * variable that could load code into the CLI process or redirect which
+ * executable runs, with the worker's own PATH restored.
+ */
+export declare function controlCommandEnvironment(environment: NodeJS.ProcessEnv, trustedPath: string | undefined): Record<string, string>;
+/**
+ * Classify an agent shell command. Only a plain `r5dctl` coordination
+ * invocation becomes a control command; the returned argv is spawned without a
+ * shell. Everything else keeps its ordinary shell semantics and lane.
+ */
+export declare function classifyControlCommand(command: string): ControlCommandClassification;

package/dist/types/main.d.ts

@@ -137,6 +137,11 @@ export type WorkerSessionTarget = {
     rootProfile: "visible_projects" | "canonical_sync";
 };
 type WorkerClientMessage = WorkerRecoveryClientMessage | {
+    type: "capacity_report";
+    capacity: import("./command-launcher").CommandLaunchCapacityReport & {
+        reportedAt: string;
+    };
+} | {
     type: "hello";
     resumableProtocol: typeof WORKER_RESUMABLE_PROTOCOL;
     runtimeId: string;
@@ -172,6 +177,7 @@ type WorkerClientMessage = WorkerRecoveryClientMessage | {
         startedAt: string;
         interactive?: boolean;
         workspaceEffect?: "none";
+        commandClass?: "control";
     }>;
 } | {
     type: "pty_opened";
@@ -397,6 +403,7 @@ type WorkerServerMessage = WorkerRecoveryServerMessage | {
     timeoutMs?: number;
     interactive?: boolean;
     workspaceEffect?: "none";
+    commandClass?: "control";
 } | {
     type: "exec_stdin";
     requestId: string;

package/dist/types/project-checkout-garbage.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Where a deleted branch checkout waits for collection. Staging is the only
+ * platform write into this directory and a live checkout always lives at
+ * `<projectRoot>/<branch>`, so a crash between staging and collection leaves
+ * nothing that a later sweep could confuse with a replacement branch. The
+ * filesystem is user-managed, though, so the collector never trusts the name
+ * alone: it removes only real directories or leaf links that sit under a real
+ * garbage directory of a real project directory (see `ownedStagedPath`).
+ * Distinct from `.r5d-removed`, which preserves paths that were not this
+ * project's worktree.
+ */
+export declare const PROJECT_DELETED_CHECKOUTS_DIRECTORY = ".r5d-deleted";
+/**
+ * Rename a checkout this project owns out of the active namespace. One
+ * same-filesystem rename takes milliseconds whatever the tree holds, so the
+ * branch mutation lease is released long before the bytes are gone. The
+ * garbage directory must be a real directory: a planted link would make the
+ * later collection walk through it, so staging refuses rather than continue.
+ */
+export declare function stageProjectCheckoutForDeletion(projectRoot: string, branchName: string, checkoutPath: string): string;
+/** True when `candidate` is lexically a direct entry of some project's garbage directory under `projectsRoot`. */
+export declare function isStagedProjectCheckoutPath(projectsRoot: string, candidate: string): boolean;
+/**
+ * Whether a lexically staged path is safe to remove right now: every ancestor
+ * below the projects root is a real directory (a linked namespace, project,
+ * or garbage directory would let a removal reach an unrelated tree through
+ * the link), and the entry itself is a real directory or a leaf link. Checked
+ * again immediately before the removal starts, never only at enqueue time.
+ */
+export declare function ownedStagedPath(projectsRoot: string, candidate: string): {
+    kind: "directory" | "link";
+} | null;
+/** Every owned staged checkout under `<projectsRoot>/<namespace>/<project>/.r5d-deleted/`; linked ancestors are not followed. */
+export declare function discoverStagedProjectCheckouts(projectsRoot: string): string[];
+/**
+ * Delete a staged tree in a child process so a large recursive removal never
+ * runs on the worker event loop, at the lowest CPU and (where supported) I/O
+ * priority so live agents on the same volume keep their share. A leaf link is
+ * unlinked in place; its target is never followed.
+ */
+export declare function removeStagedProjectCheckout(stagedPath: string): Promise<void>;
+type Logger = (message: string) => void;
+/**
+ * Collects staged checkouts one at a time, outside every workspace lease.
+ * Entries are enqueued right after staging and by `sweep()` at worker start,
+ * so a crash at any point converges on the next start. A failed removal is
+ * logged and left for the next sweep.
+ */
+export declare class ProjectCheckoutGarbageCollector {
+    private readonly projectsRoot;
+    private readonly remove;
+    private readonly log;
+    private readonly queued;
+    private tail;
+    private collectedCount;
+    constructor(options: {
+        projectsRoot: string;
+        remove?: (stagedPath: string) => Promise<void>;
+        log?: Logger;
+    });
+    /** Number of removals that have completed successfully. */
+    get collected(): number;
+    /** Resolves once everything queued so far has been attempted. */
+    get idle(): Promise<void>;
+    enqueue(stagedPath: string): void;
+    /** Enqueue every staged checkout left behind by an earlier process. */
+    sweep(): number;
+}
+export {};

package/dist/types/project-worktrees.d.ts

@@ -209,6 +209,12 @@ export declare function deleteLinkedProjectBranch(input: {
     branchName: string;
     /** Where a path that was not this project's linked worktree was set aside instead of being deleted. */
     movedAsidePath?: string;
+    /**
+     * Where the linked worktree's tree now waits for garbage collection. The
+     * branch is already gone from Git; the caller hands this path to the
+     * collector so the recursive removal runs outside every workspace lease.
+     */
+    stagedForCollectionPath?: string;
 };
 export declare function removeProjectWorktrees(input: {
     projectRoot: string;