@ricsam/r5d-worker 0.0.122 → 0.0.123

package/README.md

@@ -81,13 +81,16 @@ Operators may set `R5D_WORKER_COMMAND_LAUNCHER` to a JSON argv array, such as `[
 
 The launcher owns admission, OS isolation, budgets, and diagnostic evidence. Its JSONL protocol uses `{requestId, method, ...fields}` requests and `{requestId, result}` or `{requestId, error}` replies:
 
-- `initialize` returns `{}` once ready; failure prevents command admission.
-- `acquire` receives `{id, kind, workspaceEffect?, sessionId?}` and returns `{argvPrefix: string[]}`. The worker prepends this argv to the command or terminal shell without interpreting it.
+- `initialize` returns `{}` once ready; failure prevents command admission. A launcher that bounds concurrency may return `{capacity: {generalSlots, utilitySlots, controlSlots, controlRuntimeMs, queueTimeoutMs}}` so the worker can report lane totals.
+- `acquire` receives `{id, kind, workspaceEffect?, commandClass?, sessionId?}` and returns `{argvPrefix: string[]}`. The worker prepends this argv to the command or terminal shell without interpreting it. `commandClass: "control"` is sent only for an `exec_start` whose argv is one plain `r5dctl` coordination command (validated against the worker's own allowlist, spawned without a shell, resolved from the worker's own `PATH`, with code-loading environment variables removed, and stopped by the worker after `controlRuntimeMs`); a launcher may give such commands a small reserved lane.
+- `status` returns `{capacity, lanes: {general|utility|control: {slots, active: [{id, sessionId?, since}], queued: [...]}}}`; optional, for operator inspection.
 - `cancel` receives `{id}` and irreversibly revokes queued or acquired work. `release` receives `{id}` and acknowledges only after cleanup. Both must be idempotent, including release before a delayed acquisition response.
 - `diagnose` receives `{id}` and returns `{message?: string}` with launcher-specific evidence. The worker does not infer a memory failure from an exit signal.
 
 Requests must be processed concurrently so cancellation and cleanup cannot wait behind queued admission. Controller RPCs are bounded (10 seconds, or 90 seconds for acquisition); external policy must reject excessive queue waits within that bound. Controller loss or protocol failure stops command admission, preserves uncertain outcomes for recovery, reaps ordinary children, and restarts the runtime through its supervisor. It never falls back to direct spawning. Shutdown closes controller stdin; the controller must reap its jobs before exiting.
 
-Cancellation is checked again immediately before spawn. Transient disconnects preserve commands and terminals; expiry of the five-minute execution lease cancels agent work and closes terminals. File operations, communication recovery, and cancellation do not enter launcher admission. Internal worker maintenance subprocesses are also outside this hook. Deployment-specific limits and service protection are documented in [Worker deployment resources](../../docs/worker-deployment-resources.md).
+Cancellation is checked again immediately before spawn. Transient disconnects preserve commands and terminals; expiry of the five-minute execution lease cancels agent work and closes terminals. File operations, communication recovery, and cancellation do not enter launcher admission. Internal worker maintenance subprocesses are also outside this hook. The worker reports its own view of every lane (holders and queue, by run id) to the server with `capacity_report` whenever an admission changes; the platform exposes it through `r5dctl ps list` and `r5dctl workspace status`. Deployment-specific limits and service protection are documented in [Worker deployment resources](../../docs/worker-deployment-resources.md).
 
 When the connected `r5d-browser` requests a port forward, the worker opens each relayed connection only to `127.0.0.1` on the requested worker port. Browser-side and worker-side ports may differ. The worker never opens a public listener, and a disconnected worker leaves the browser's long-lived mapping unavailable until the same worker label reconnects.
+
+Control execution requires an initialized launcher that explicitly declares its control capacity (or direct execution without an external launcher), an updated worker, and r5dctl installed on the worker's own PATH. Missing control support is an update error; a control request never falls back to a general shell. Deploy the app and worker support assets, update the CLI/worker, and reconnect before resuming paused work.

package/dist/cjs/command-launcher.cjs

@@ -21,12 +21,20 @@ __export(command_launcher_exports, {
   CommandLaunchCancelledError: () => CommandLaunchCancelledError,
   CommandLauncherUnavailableError: () => CommandLauncherUnavailableError,
   WorkerCommandLauncher: () => WorkerCommandLauncher,
+  commandLaunchLane: () => commandLaunchLane,
   commandLauncherEnvironment: () => commandLauncherEnvironment,
   createWorkerCommandLauncher: () => createWorkerCommandLauncher,
   parseCommandLauncher: () => parseCommandLauncher
 });
 module.exports = __toCommonJS(command_launcher_exports);
 var import_node_child_process = require("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 });
@@ -114,12 +122,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();
@@ -131,19 +141,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 {
@@ -169,6 +223,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();
@@ -268,6 +325,7 @@ class WorkerCommandLauncher {
       }
       record.released = true;
       this.launches.delete(record.request.id);
+      this.notifyCapacityChange();
     })();
   }
   assertHealthy() {
@@ -329,6 +387,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();
@@ -339,6 +412,7 @@ async function createWorkerCommandLauncher(options = {}) {
   CommandLaunchCancelledError,
   CommandLauncherUnavailableError,
   WorkerCommandLauncher,
+  commandLaunchLane,
   commandLauncherEnvironment,
   createWorkerCommandLauncher,
   parseCommandLauncher

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

@@ -0,0 +1,177 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var control_command_policy_exports = {};
+__export(control_command_policy_exports, {
+  CONTROL_COMMAND_MAX_ARGV: () => CONTROL_COMMAND_MAX_ARGV,
+  CONTROL_COMMAND_MAX_LENGTH: () => CONTROL_COMMAND_MAX_LENGTH,
+  CONTROL_COMMAND_PROGRAM: () => CONTROL_COMMAND_PROGRAM,
+  CONTROL_COMMAND_RUNTIME_MS: () => CONTROL_COMMAND_RUNTIME_MS,
+  assertControlCommandArgv: () => assertControlCommandArgv,
+  classifyControlCommand: () => classifyControlCommand,
+  controlCommandEnvironment: () => controlCommandEnvironment,
+  resolveControlCommandExecutable: () => resolveControlCommandExecutable
+});
+module.exports = __toCommonJS(control_command_policy_exports);
+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 };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CONTROL_COMMAND_MAX_ARGV,
+  CONTROL_COMMAND_MAX_LENGTH,
+  CONTROL_COMMAND_PROGRAM,
+  CONTROL_COMMAND_RUNTIME_MS,
+  assertControlCommandArgv,
+  classifyControlCommand,
+  controlCommandEnvironment,
+  resolveControlCommandExecutable
+});

package/dist/cjs/main.cjs

@@ -75,6 +75,7 @@ var import_cli_update = require("./cli-update.cjs");
 var import_git_process_environment = require("./git-process-environment.cjs");
 var import_process_tree = require("./process-tree.cjs");
 var import_project_checkout_garbage = require("./project-checkout-garbage.cjs");
+var import_control_command_policy = require("./control-command-policy.cjs");
 var import_pty_output_coalescer = require("./pty-output-coalescer.cjs");
 var import_port_forward_client = require("./port-forward-client.cjs");
 var import_registry_auth = require("./registry-auth.cjs");
@@ -158,6 +159,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();
@@ -2775,6 +2796,10 @@ function cancelWorkerCommandLaunch(resources) {
   });
 }
 async function acquireWorkerCommandLaunch(ws, message, assertAdmission) {
+  if (message.type === "exec_start" && message.commandClass === "control") {
+    (0, import_control_command_policy.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 });
@@ -2783,6 +2808,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();
@@ -2930,8 +2956,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) {
+      (0, import_control_command_policy.assertControlCommandArgv)(argv);
+      if (interactive) throw new Error("Control commands cannot be interactive");
+      argv = [(0, import_control_command_policy.resolveControlCommandExecutable)(trustedControlPath, (program, options) => Bun.which(program, options)), ...argv.slice(1)];
+      environment = (0, import_control_command_policy.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.
@@ -2939,7 +2974,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);
@@ -2954,12 +2989,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;
@@ -2971,7 +3007,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 ?? import_control_command_policy.CONTROL_COMMAND_RUNTIME_MS, import_control_command_policy.CONTROL_COMMAND_RUNTIME_MS) : input.message.timeoutMs;
+    if (timeoutMs) {
       timeout = setTimeout(() => {
         timedOut = true;
         cancelWorkerCommandLaunch(input.resources);
@@ -2982,7 +3019,7 @@ async function executeStreamingCommand(input) {
 `
           );
         });
-      }, input.message.timeoutMs);
+      }, timeoutMs);
     }
     const [exitCode] = await Promise.all([
       subprocess.exited,
@@ -3145,7 +3182,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) {
@@ -3667,6 +3705,7 @@ async function startWorker(options, projectRuntime = {
   validateLabel(label);
   if (!workerCommandLauncher) {
     const launcher = await (0, import_command_launcher.createWorkerCommandLauncher)({
+      onCapacityChange: () => scheduleCapacityReport(),
       configuration: process.env.R5D_WORKER_COMMAND_LAUNCHER,
       env: (0, import_command_launcher.commandLauncherEnvironment)(),
       onFailure: handleWorkerCommandLauncherFailure
@@ -5854,6 +5893,7 @@ async function startWorker(options, projectRuntime = {
           workspaceConfigResetToCanonicalV1: true,
           projectBranchDeletionFastAckV1: true,
           projectBranchDeletionStagedRemovalV1: true,
+          commandControlLaneV1: workerCommandLauncher?.supportsControlLane === true,
           projectMirrorLeaseV1: true,
           projectMirrorRefsTokensV1: true,
           projectBranchWorkingTreeModeV1: true
@@ -5980,6 +6020,8 @@ async function startWorker(options, projectRuntime = {
         });
       };
       if (message.type === "connected") {
+        capacityReportSocket = ws;
+        scheduleCapacityReport(true);
         return;
       }
       if (message.type === "project_mirror_refs_tokens") {
@@ -6735,8 +6777,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/cjs/package.json

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

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
+};

package/dist/mjs/main.mjs

@@ -26,6 +26,12 @@ 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 {
@@ -177,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();
@@ -2794,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 });
@@ -2802,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();
@@ -2949,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.
@@ -2958,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);
@@ -2973,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;
@@ -2990,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);
@@ -3001,7 +3043,7 @@ async function executeStreamingCommand(input) {
 `
           );
         });
-      }, input.message.timeoutMs);
+      }, timeoutMs);
     }
     const [exitCode] = await Promise.all([
       subprocess.exited,
@@ -3164,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) {
@@ -3686,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
@@ -5873,6 +5917,7 @@ async function startWorker(options, projectRuntime = {
           workspaceConfigResetToCanonicalV1: true,
           projectBranchDeletionFastAckV1: true,
           projectBranchDeletionStagedRemovalV1: true,
+          commandControlLaneV1: workerCommandLauncher?.supportsControlLane === true,
           projectMirrorLeaseV1: true,
           projectMirrorRefsTokensV1: true,
           projectBranchWorkingTreeModeV1: true
@@ -5999,6 +6044,8 @@ async function startWorker(options, projectRuntime = {
         });
       };
       if (message.type === "connected") {
+        capacityReportSocket = ws;
+        scheduleCapacityReport(true);
         return;
       }
       if (message.type === "project_mirror_refs_tokens") {
@@ -6754,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.122",
+  "version": "0.0.123",
   "type": "module"
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.122",
+  "version": "0.0.123",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",