@ricsam/r5d-worker 0.0.121 → 0.0.123

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

@@ -0,0 +1,190 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var project_checkout_garbage_exports = {};
+__export(project_checkout_garbage_exports, {
+  PROJECT_DELETED_CHECKOUTS_DIRECTORY: () => PROJECT_DELETED_CHECKOUTS_DIRECTORY,
+  ProjectCheckoutGarbageCollector: () => ProjectCheckoutGarbageCollector,
+  discoverStagedProjectCheckouts: () => discoverStagedProjectCheckouts,
+  isStagedProjectCheckoutPath: () => isStagedProjectCheckoutPath,
+  ownedStagedPath: () => ownedStagedPath,
+  removeStagedProjectCheckout: () => removeStagedProjectCheckout,
+  stageProjectCheckoutForDeletion: () => stageProjectCheckoutForDeletion
+});
+module.exports = __toCommonJS(project_checkout_garbage_exports);
+var import_node_crypto = require("node:crypto");
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+const PROJECT_DELETED_CHECKOUTS_DIRECTORY = ".r5d-deleted";
+function isRealDirectory(candidate) {
+  try {
+    return import_node_fs.default.lstatSync(candidate).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function stageProjectCheckoutForDeletion(projectRoot, branchName, checkoutPath) {
+  const garbageRoot = import_node_path.default.join(projectRoot, PROJECT_DELETED_CHECKOUTS_DIRECTORY);
+  if (!isRealDirectory(checkoutPath)) throw new Error(`Cannot stage ${checkoutPath} for deletion: not a directory`);
+  import_node_fs.default.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 = import_node_path.default.join(garbageRoot, `${branchName.replace(/\//g, "__")}-${timestamp}-${(0, import_node_crypto.randomUUID)().slice(0, 8)}`);
+  import_node_fs.default.renameSync(checkoutPath, target);
+  return target;
+}
+function isStagedProjectCheckoutPath(projectsRoot, candidate) {
+  const relative = import_node_path.default.relative(import_node_path.default.resolve(projectsRoot), import_node_path.default.resolve(candidate));
+  if (!relative || relative.startsWith("..") || import_node_path.default.isAbsolute(relative)) return false;
+  const segments = relative.split(import_node_path.default.sep);
+  return segments.length === 4 && segments[2] === PROJECT_DELETED_CHECKOUTS_DIRECTORY && segments[3] !== "" && !segments[3].startsWith(".");
+}
+function ownedStagedPath(projectsRoot, candidate) {
+  const root = import_node_path.default.resolve(projectsRoot);
+  const resolved = import_node_path.default.resolve(candidate);
+  if (!isStagedProjectCheckoutPath(root, resolved)) return null;
+  let current = root;
+  for (const segment of import_node_path.default.relative(root, import_node_path.default.dirname(resolved)).split(import_node_path.default.sep)) {
+    current = import_node_path.default.join(current, segment);
+    if (!isRealDirectory(current)) return null;
+  }
+  let stat;
+  try {
+    stat = import_node_fs.default.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 import_node_fs.default.readdirSync(directory, { withFileTypes: true }).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+function discoverStagedProjectCheckouts(projectsRoot) {
+  const root = import_node_path.default.resolve(projectsRoot);
+  const staged = [];
+  for (const namespace of realDirectoryEntries(root)) {
+    if (namespace.startsWith(".")) continue;
+    for (const project of realDirectoryEntries(import_node_path.default.join(root, namespace))) {
+      if (project.startsWith(".")) continue;
+      const garbageRoot = import_node_path.default.join(root, namespace, project, PROJECT_DELETED_CHECKOUTS_DIRECTORY);
+      for (const entry of realDirectoryEntries(garbageRoot)) {
+        const candidate = import_node_path.default.join(garbageRoot, entry);
+        if (ownedStagedPath(root, candidate)) staged.push(candidate);
+      }
+    }
+  }
+  return staged;
+}
+async function removeStagedProjectCheckout(stagedPath) {
+  if (import_node_fs.default.lstatSync(stagedPath).isSymbolicLink()) {
+    import_node_fs.default.unlinkSync(stagedPath);
+    return;
+  }
+  if (process.platform === "win32") {
+    await import_node_fs.default.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 (import_node_fs.default.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 = import_node_path.default.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 = import_node_path.default.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 (import_node_fs.default.existsSync(resolved) || isRealDirectory(import_node_path.default.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;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PROJECT_DELETED_CHECKOUTS_DIRECTORY,
+  ProjectCheckoutGarbageCollector,
+  discoverStagedProjectCheckouts,
+  isStagedProjectCheckoutPath,
+  ownedStagedPath,
+  removeStagedProjectCheckout,
+  stageProjectCheckoutForDeletion
+});

package/dist/cjs/project-worktrees.cjs

@@ -61,6 +61,7 @@ var import_node_os = __toESM(require("node:os"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var import_git_process_environment = require("./git-process-environment.cjs");
 var import_managed_paths = require("./managed-paths.cjs");
+var import_project_checkout_garbage = require("./project-checkout-garbage.cjs");
 var import_project_mirror_refs_token = require("./project-mirror-refs-token.cjs");
 var import_working_tree_mirror = require("./working-tree-mirror.cjs");
 const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
@@ -1340,6 +1341,7 @@ function deleteLinkedProjectBranch(input) {
   const primaryCommonDir = commonGitDirectory(primaryPath);
   if (!primaryCommonDir) throw new Error("Primary project checkout is unavailable");
   let movedAsidePath;
+  let stagedForCollectionPath;
   if (import_node_fs.default.existsSync(checkoutPath)) {
     const checkoutCommonDir = import_node_fs.default.lstatSync(checkoutPath).isDirectory() ? commonGitDirectory(checkoutPath) : null;
     if (checkoutCommonDir !== primaryCommonDir) {
@@ -1349,7 +1351,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 = (0, import_project_checkout_garbage.stageProjectCheckoutForDeletion)(input.projectRoot, input.branchName, checkoutPath);
+      git(primaryPath, ["worktree", "prune"], `prune linked worktree ${input.branchName}`);
     }
   } else {
     tryGit(primaryPath, ["worktree", "prune"]);
@@ -1358,7 +1361,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 = import_node_path.default.resolve(input.projectRoot);

package/dist/cjs/recovery-store.cjs

@@ -98,6 +98,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/mjs/command-launcher.mjs

@@ -1,4 +1,11 @@
 import { spawn } from "node:child_process";
+function commandLaunchLane(request) {
+  if (request.commandClass === "control") {
+    if (request.kind !== "exec_start") throw new Error("Control commands must be exec_start launches");
+    return "control";
+  }
+  return request.kind === "exec" && request.workspaceEffect === "none" ? "utility" : "general";
+}
 class CommandLauncherUnavailableError extends Error {
   constructor(message, cause) {
     super(message, { cause });
@@ -86,12 +93,14 @@ class WorkerCommandLauncher {
   initialized = false;
   closePromise;
   sequence = 0;
+  capacity;
   async initialize() {
     this.assertHealthy();
     if (this.initialized) return;
     if (this.child) {
       try {
-        await this.rpc("initialize");
+        const result = await this.rpc("initialize");
+        this.capacity = parseCapacity(result.capacity);
       } catch (error) {
         this.fail(error instanceof Error ? error : new Error(String(error)));
         await this.close();
@@ -103,19 +112,63 @@ class WorkerCommandLauncher {
   get activeIds() {
     return [...this.launches.keys()];
   }
+  /** The lane totals the launcher declared at initialization; undefined for a direct worker or an older launcher. */
+  get declaredCapacity() {
+    return this.capacity;
+  }
+  get supportsControlLane() {
+    return this.initialized && (this.mode === "direct" || (this.capacity?.controlSlots ?? 0) > 0);
+  }
+  /** Current admissions per lane, for the worker's capacity report. */
+  capacityReport() {
+    const bounded = this.child !== void 0;
+    const lanes = {
+      general: { slots: bounded ? this.capacity?.generalSlots ?? null : null, active: [], queued: [] },
+      utility: { slots: bounded ? this.capacity?.utilitySlots ?? null : null, active: [], queued: [] },
+      control: { slots: bounded ? this.capacity?.controlSlots ?? null : null, active: [], queued: [] }
+    };
+    for (const record of this.launches.values()) {
+      if (record.released) continue;
+      const entry = {
+        id: record.request.id,
+        ...record.request.sessionId ? { sessionId: record.request.sessionId } : {},
+        since: record.since
+      };
+      (record.phase === "active" ? lanes[record.lane].active : lanes[record.lane].queued).push(entry);
+    }
+    return { bounded, controlRuntimeMs: bounded ? this.capacity?.controlRuntimeMs ?? null : null, lanes };
+  }
+  notifyCapacityChange() {
+    try {
+      this.options.onCapacityChange?.();
+    } catch {
+    }
+  }
   async acquire(request) {
     this.assertHealthy();
     if (!this.initialized) throw new Error("Command launcher is not initialized");
     request.assertAdmission();
     if (this.launches.has(request.id)) throw new Error(`Duplicate command launch identity: ${request.id}`);
+    const lane = commandLaunchLane(request);
+    if (lane === "control" && !this.supportsControlLane)
+      throw new Error("Update the worker command launcher before running control commands");
     let rejectAdmission;
     const cancellation = new Promise((_resolve, reject) => {
       rejectAdmission = reject;
     });
     void cancellation.catch(() => {
     });
-    const record = { request, revoked: false, released: false, rejectAdmission };
+    const record = {
+      request,
+      lane,
+      phase: this.child ? "queued" : "active",
+      since: (/* @__PURE__ */ new Date()).toISOString(),
+      revoked: false,
+      released: false,
+      rejectAdmission
+    };
     this.launches.set(request.id, record);
+    this.notifyCapacityChange();
     let prefix = [];
     let admissionTimer;
     try {
@@ -141,6 +194,9 @@ class WorkerCommandLauncher {
           }
         }, 100);
         prefix = await Promise.race([acquisition, cancellation]);
+        record.phase = "active";
+        record.since = (/* @__PURE__ */ new Date()).toISOString();
+        this.notifyCapacityChange();
       }
       request.assertAdmission();
       this.assertHealthy();
@@ -240,6 +296,7 @@ class WorkerCommandLauncher {
       }
       record.released = true;
       this.launches.delete(record.request.id);
+      this.notifyCapacityChange();
     })();
   }
   assertHealthy() {
@@ -301,6 +358,21 @@ class WorkerCommandLauncher {
     return this.failure;
   }
 }
+function parseCapacity(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const candidate = value;
+  const numbers = ["generalSlots", "utilitySlots", "controlSlots", "controlRuntimeMs", "queueTimeoutMs"];
+  if (!numbers.every((key) => typeof candidate[key] === "number" && Number.isSafeInteger(candidate[key]) && candidate[key] >= 0)) {
+    throw new Error("Command launcher initialize returned an invalid capacity");
+  }
+  return {
+    generalSlots: candidate.generalSlots,
+    utilitySlots: candidate.utilitySlots,
+    controlSlots: candidate.controlSlots,
+    controlRuntimeMs: candidate.controlRuntimeMs,
+    queueTimeoutMs: candidate.queueTimeoutMs
+  };
+}
 async function createWorkerCommandLauncher(options = {}) {
   const launcher = new WorkerCommandLauncher({ ...options, argv: parseCommandLauncher(options.configuration) });
   await launcher.initialize();
@@ -310,6 +382,7 @@ export {
   CommandLaunchCancelledError,
   CommandLauncherUnavailableError,
   WorkerCommandLauncher,
+  commandLaunchLane,
   commandLauncherEnvironment,
   createWorkerCommandLauncher,
   parseCommandLauncher

package/dist/mjs/control-command-policy.mjs

@@ -0,0 +1,146 @@
+const CONTROL_COMMAND_PROGRAM = "r5dctl";
+const CONTROL_COMMAND_RUNTIME_MS = 12e4;
+const CONTROL_COMMAND_MAX_ARGV = 64;
+const CONTROL_COMMAND_MAX_LENGTH = 4096;
+const CONTROL_GLOBAL_FLAGS_WITH_VALUE = /* @__PURE__ */ new Set(["-p", "--project", "-s", "--session", "-b", "--branch"]);
+const CONTROL_GLOBAL_FLAGS = /* @__PURE__ */ new Set(["--json", "-h", "--help", "-v", "--version"]);
+const REFUSED_ANYWHERE = /* @__PURE__ */ new Set(["-f", "--follow", "--watch", "--base-url", "--config", "--token", "--api-key"]);
+const CONTROL_VERBS = {
+  session: /* @__PURE__ */ new Set(["status", "stop", "prompt", "claim", "claims", "process-log"]),
+  sessions: /* @__PURE__ */ new Set(["recent"]),
+  describe: /* @__PURE__ */ new Set(["project", "branch", "session", "branch-operation", "branch-deletion"]),
+  get: /* @__PURE__ */ new Set(["projects", "branches", "sessions", "envs", "env"]),
+  conversation: /* @__PURE__ */ new Set(["overview", "inspect-node", "inspect-work"]),
+  ps: /* @__PURE__ */ new Set(["list", "history", "inspect", "stop"]),
+  workspace: /* @__PURE__ */ new Set(["status"]),
+  auth: /* @__PURE__ */ new Set(["status"]),
+  create: /* @__PURE__ */ new Set(["session"]),
+  update: /* @__PURE__ */ new Set(["session"]),
+  delete: /* @__PURE__ */ new Set(["session"]),
+  "answer-questions": null,
+  "answer-env-request": null
+};
+const CODE_LOADING_ENV_PATTERN = /^(NODE_OPTIONS|NODE_PATH|NODE_REPL_EXTERNAL_MODULE|BUN_OPTIONS|BUN_CONFIG_[A-Z_]+|LD_PRELOAD|LD_LIBRARY_PATH|LD_AUDIT|DYLD_[A-Z_]+|PATH|PATHEXT|PYTHONPATH|PERL5OPT|RUBYOPT|SHELL|ENV|BASH_ENV)$/i;
+const BARE_WORD = /^[A-Za-z0-9_@%+=:,./-]+$/;
+const DOUBLE_QUOTED_FORBIDDEN = /[$`\\!]/;
+function tokenizePlainInvocation(command) {
+  if (command.length > CONTROL_COMMAND_MAX_LENGTH) return { reason: "command is longer than the control lane allows" };
+  if (/[\r\n]/.test(command)) return { reason: "multi-line commands are shell scripts" };
+  const argv = [];
+  let index = 0;
+  while (index < command.length) {
+    const char = command[index];
+    if (char === " " || char === "	") {
+      index += 1;
+      continue;
+    }
+    let word = "";
+    let quotedParts = 0;
+    let bareParts = 0;
+    while (index < command.length && command[index] !== " " && command[index] !== "	") {
+      const current = command[index];
+      if (current === "'") {
+        const end = command.indexOf("'", index + 1);
+        if (end < 0) return { reason: "unterminated single quote" };
+        word += command.slice(index + 1, end);
+        quotedParts += 1;
+        index = end + 1;
+        continue;
+      }
+      if (current === '"') {
+        const end = command.indexOf('"', index + 1);
+        if (end < 0) return { reason: "unterminated double quote" };
+        const inner = command.slice(index + 1, end);
+        if (DOUBLE_QUOTED_FORBIDDEN.test(inner)) return { reason: "double-quoted text would be expanded by the shell" };
+        word += inner;
+        quotedParts += 1;
+        index = end + 1;
+        continue;
+      }
+      let bare = "";
+      while (index < command.length && !/[\s'"]/.test(command[index])) {
+        bare += command[index];
+        index += 1;
+      }
+      if (!BARE_WORD.test(bare)) return { reason: `shell syntax in "${bare}" is not part of a plain invocation` };
+      word += bare;
+      bareParts += 1;
+    }
+    if (quotedParts + bareParts > 1) return { reason: "adjacent quoted and bare text is shell concatenation" };
+    argv.push(word);
+    if (argv.length > CONTROL_COMMAND_MAX_ARGV) return { reason: "too many arguments for a control command" };
+  }
+  if (argv.length === 0) return { reason: "empty command" };
+  return { argv };
+}
+function assertControlCommandArgv(argv) {
+  if (argv.length === 0 || argv.length > CONTROL_COMMAND_MAX_ARGV) throw new Error("Control commands are a single r5dctl invocation");
+  if (argv[0] !== CONTROL_COMMAND_PROGRAM) throw new Error(`Control commands must start with ${CONTROL_COMMAND_PROGRAM}`);
+  if (argv.reduce((length, argument) => length + (typeof argument === "string" ? argument.length : 0) + 1, 0) > CONTROL_COMMAND_MAX_LENGTH)
+    throw new Error("Control command arguments exceed the length limit");
+  for (const argument of argv) {
+    if (typeof argument !== "string" || argument.includes("\0") || /[\r\n]/.test(argument)) throw new Error("Control command arguments must be plain text");
+    if (REFUSED_ANYWHERE.has(argument.split("=", 1)[0])) throw new Error(`Control command option is not allowed (${argument.split("=", 1)[0]})`);
+    if (argument === "--") throw new Error("Control commands cannot use `--`");
+  }
+  let position = 1;
+  while (position < argv.length) {
+    const argument = argv[position];
+    if (CONTROL_GLOBAL_FLAGS.has(argument)) {
+      position += 1;
+      continue;
+    }
+    if (CONTROL_GLOBAL_FLAGS_WITH_VALUE.has(argument)) {
+      if (position + 1 >= argv.length) throw new Error(`Missing value for ${argument}`);
+      position += 2;
+      continue;
+    }
+    if (argument.startsWith("-")) throw new Error(`Global flag ${argument} is not allowed in a control command`);
+    break;
+  }
+  const verb = argv[position];
+  if (verb === void 0) throw new Error("Control commands need a coordination verb (for example `r5dctl ps list`)");
+  const allowed = Object.hasOwn(CONTROL_VERBS, verb) ? CONTROL_VERBS[verb] : void 0;
+  if (allowed === void 0) throw new Error(`r5dctl ${verb} is not a coordination command`);
+  if (allowed === null) return;
+  const subject = argv[position + 1];
+  if (subject === void 0 || !allowed.has(subject)) {
+    throw new Error(`r5dctl ${verb}${subject ? ` ${subject}` : ""} is not a coordination command`);
+  }
+}
+function resolveControlCommandExecutable(trustedPath, which, program = CONTROL_COMMAND_PROGRAM) {
+  const resolved = trustedPath ? which(program, { PATH: trustedPath }) : null;
+  if (!resolved) throw new Error(`${program} is not installed on the worker's trusted PATH; control commands are unavailable until it is`);
+  return resolved;
+}
+function controlCommandEnvironment(environment, trustedPath) {
+  const result = {};
+  for (const [key, value] of Object.entries(environment)) {
+    if (value === void 0 || CODE_LOADING_ENV_PATTERN.test(key)) continue;
+    result[key] = value;
+  }
+  if (trustedPath !== void 0) result.PATH = trustedPath;
+  return result;
+}
+function classifyControlCommand(command) {
+  const tokenized = tokenizePlainInvocation(command.trim());
+  if ("reason" in tokenized) return { control: false, reason: tokenized.reason };
+  const { argv } = tokenized;
+  if (argv[0] !== CONTROL_COMMAND_PROGRAM) return { control: false, reason: "not an r5dctl invocation" };
+  try {
+    assertControlCommandArgv(argv);
+  } catch (error) {
+    return { control: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+  return { control: true, argv };
+}
+export {
+  CONTROL_COMMAND_MAX_ARGV,
+  CONTROL_COMMAND_MAX_LENGTH,
+  CONTROL_COMMAND_PROGRAM,
+  CONTROL_COMMAND_RUNTIME_MS,
+  assertControlCommandArgv,
+  classifyControlCommand,
+  controlCommandEnvironment,
+  resolveControlCommandExecutable
+};