@ricsam/r5d-worker 0.0.28 → 0.0.30

package/README.md

@@ -19,6 +19,10 @@ Visible branch checkouts are the user/agent workbench. Their `origin` remains th
 
 Worker labels are mandatory and unique per user. Choose labels that describe host capabilities, such as `macos`, `linux`, `ios`, or `ec2-build`.
 
+`r5d-worker start` keeps a lightweight supervisor process attached to the launching terminal or service. When both r5d CLIs are updated from User Settings, the connected runtime verifies the installed versions, exits with a reload signal, and the supervisor reconnects using the new worker package. Updates only run while the worker has no active commands or shells.
+
+One-click updates use the current user's global npm prefix and never invoke `sudo`. If that prefix is not writable, User Settings provides the exact command to run manually.
+
 The agent runs commands through the virtual shell command:
 
 ```sh

package/dist/cjs/cli-update.cjs

@@ -0,0 +1,108 @@
+"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 cli_update_exports = {};
+__export(cli_update_exports, {
+  getManualCliUpdateCommand: () => getManualCliUpdateCommand,
+  installCliUpdate: () => installCliUpdate,
+  parseCliVersion: () => parseCliVersion,
+  readInstalledCliVersion: () => readInstalledCliVersion,
+  runCommand: () => runCommand
+});
+module.exports = __toCommonJS(cli_update_exports);
+const UPDATE_OUTPUT_LIMIT = 8e3;
+function collectOutput(value) {
+  if (!value || typeof value === "number") {
+    return Promise.resolve("");
+  }
+  return new Response(value).text();
+}
+async function runCommand(argv) {
+  const child = Bun.spawn(argv, {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([collectOutput(child.stdout), collectOutput(child.stderr), child.exited]);
+  return { exitCode, stdout, stderr };
+}
+function parseCliVersion(cliName, output) {
+  const escapedName = cliName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = output.trim().match(new RegExp(`(?:^|\\n)${escapedName}\\s+(\\S+)`));
+  return match?.[1]?.trim() || null;
+}
+function readInstalledCliVersion(cliName) {
+  try {
+    const result = Bun.spawnSync([cliName, "--version"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: process.env
+    });
+    if (result.exitCode !== 0) {
+      return null;
+    }
+    return parseCliVersion(cliName, Buffer.from(result.stdout).toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function getManualCliUpdateCommand(input) {
+  return `npm install -g --omit=dev ${shellQuote(input.workerPackageSpec)} ${shellQuote(input.r5dctlPackageSpec)}`;
+}
+function commandErrorDetail(result) {
+  const detail = `${result.stderr.trim()}${result.stderr.trim() && result.stdout.trim() ? "\n" : ""}${result.stdout.trim()}`.trim();
+  if (!detail) {
+    return `exit code ${result.exitCode}`;
+  }
+  return detail.slice(-UPDATE_OUTPUT_LIMIT);
+}
+async function readVerifiedVersion(cliName, targetVersion, runner) {
+  const result = await runner([cliName, "--version"]);
+  const installedVersion = result.exitCode === 0 ? parseCliVersion(cliName, result.stdout) : null;
+  if (!installedVersion) {
+    throw new Error(`${cliName} was installed but is not runnable: ${commandErrorDetail(result)}`);
+  }
+  if (installedVersion !== targetVersion) {
+    throw new Error(`${cliName} ${installedVersion} was installed; expected ${targetVersion}`);
+  }
+  return installedVersion;
+}
+async function installCliUpdate(input, runner = runCommand) {
+  const installArgs = ["npm", "install", "-g", "--omit=dev", input.workerPackageSpec, input.r5dctlPackageSpec];
+  const result = await runner(installArgs);
+  if (result.exitCode !== 0) {
+    throw new Error(`CLI update failed: ${commandErrorDetail(result)}
+Run manually: ${getManualCliUpdateCommand(input)}`);
+  }
+  const [installedWorkerVersion, installedR5dctlVersion] = await Promise.all([
+    readVerifiedVersion("r5d-worker", input.targetWorkerVersion, runner),
+    readVerifiedVersion("r5dctl", input.targetR5dctlVersion, runner)
+  ]);
+  return { installedWorkerVersion, installedR5dctlVersion };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getManualCliUpdateCommand,
+  installCliUpdate,
+  parseCliVersion,
+  readInstalledCliVersion,
+  runCommand
+});

package/dist/cjs/main.cjs

@@ -46,8 +46,11 @@ var import_node_path = __toESM(require("node:path"), 1);
 var import_node_crypto = require("node:crypto");
 var import_node_os = __toESM(require("node:os"), 1);
 var import_node_child_process = require("node:child_process");
+var import_cli_update = require("./cli-update.cjs");
 var import_git_identity = require("./git-identity.cjs");
 var import_heartbeat = require("./heartbeat.cjs");
+var import_process_tree = require("./process-tree.cjs");
+var import_supervisor = require("./supervisor.cjs");
 const import_meta = {};
 const DEFAULT_BASE_URL = "https://r5d.dev";
 const WORKER_PACKAGE_NAME = "@ricsam/r5d-worker";
@@ -1815,6 +1818,7 @@ async function executeCommand(input) {
       cwd,
       stdout: "pipe",
       stderr: "pipe",
+      detached: true,
       env: {
         ...process.env,
         ...containerRegistryEnv(),
@@ -1836,7 +1840,12 @@ async function executeCommand(input) {
     });
     if (input.message.timeoutMs) {
       timeout = setTimeout(() => {
-        subprocess.kill("SIGTERM");
+        void (0, import_process_tree.terminateProcessTree)(subprocess).catch((error) => {
+          process.stderr.write(
+            `[r5d-worker] failed to terminate timed-out command ${input.message.runId}: ${error instanceof Error ? error.message : String(error)}
+`
+          );
+        });
       }, input.message.timeoutMs);
     }
     const [stdout, stderr, exitCode] = await Promise.all([
@@ -1872,6 +1881,8 @@ async function executeCommand(input) {
 async function executeStreamingCommand(input) {
   const startedAt = Date.now();
   let started = false;
+  let timedOut = false;
+  let timeout;
   try {
     if (cancelledProcessRuns.delete(input.message.runId)) {
       sendWorkerMessage(input.ws, {
@@ -1912,6 +1923,7 @@ async function executeStreamingCommand(input) {
       cwd,
       stdout: "pipe",
       stderr: "pipe",
+      detached: true,
       env: {
         ...process.env,
         ...containerRegistryEnv(),
@@ -1938,6 +1950,17 @@ async function executeStreamingCommand(input) {
       requestId: input.message.requestId,
       runId: input.message.runId
     });
+    if (input.message.timeoutMs) {
+      timeout = setTimeout(() => {
+        timedOut = true;
+        void (0, import_process_tree.terminateProcessTree)(subprocess).catch((error) => {
+          process.stderr.write(
+            `[r5d-worker] failed to terminate timed-out process ${input.message.runId}: ${error instanceof Error ? error.message : String(error)}
+`
+          );
+        });
+      }, input.message.timeoutMs);
+    }
     const [exitCode] = await Promise.all([
       subprocess.exited,
       streamCommandOutput(subprocess.stdout, (data) => {
@@ -1961,7 +1984,8 @@ async function executeStreamingCommand(input) {
       type: "exec_exit",
       runId: input.message.runId,
       exitCode,
-      durationMs: Date.now() - startedAt
+      durationMs: Date.now() - startedAt,
+      ...timedOut ? { timedOut: true } : {}
     });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -1981,6 +2005,9 @@ async function executeStreamingCommand(input) {
       });
     }
   } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
     activeProcesses.delete(input.message.runId);
     cancelledProcessRuns.delete(input.message.runId);
   }
@@ -2358,6 +2385,9 @@ async function startWorker(options) {
   import_node_fs.default.mkdirSync(planRoot, { recursive: true });
   const manifestByProjectId = /* @__PURE__ */ new Map();
   let repositorySyncQueue = Promise.resolve();
+  let repositorySyncInProgress = false;
+  let cliUpdateInProgress = false;
+  let reloadAfterClose = false;
   const ws = new WebSocket(websocketUrl(baseUrl, label), {
     headers: {
       Authorization: `Bearer ${token}`
@@ -2391,6 +2421,10 @@ async function startWorker(options) {
         arch: process.arch,
         pid: process.pid,
         version: getWorkerVersion(),
+        r5dctlVersion: (0, import_cli_update.readInstalledCliVersion)("r5dctl"),
+        capabilities: {
+          updateClis: true
+        },
         projectRoot: projectsRoot,
         artifactRoot,
         planRoot
@@ -2418,32 +2452,49 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "sync_projects") {
+        if (cliUpdateInProgress) {
+          sendWorkerMessage(ws, {
+            type: "sync_projects_result",
+            requestId: message.requestId,
+            result: {
+              status: "blocked",
+              results: [],
+              blockedBy: []
+            }
+          });
+          return;
+        }
         let syncResult = { status: "completed", results: [], blockedBy: [] };
         const executeSync = async () => {
-          syncResult = await syncManifestProjectsFromInternal({
-            baseUrl,
-            token,
-            projectsRoot,
-            syncRoot,
-            manifests: [...manifestByProjectId.values()],
-            projectIds: message.projectIds
-          });
-          for (const result of syncResult.results) {
-            if (result.status !== "synced") continue;
-            try {
-              await syncProjectPlans({
-                baseUrl,
-                token,
-                projectId: result.projectId,
-                branchName: result.branchName,
-                planRoot
-              });
-            } catch (error) {
-              process.stderr.write(
-                `[r5d-worker] plan sync skipped for ${result.projectId}/${result.branchName}: ${error instanceof Error ? error.message : String(error)}
+          repositorySyncInProgress = true;
+          try {
+            syncResult = await syncManifestProjectsFromInternal({
+              baseUrl,
+              token,
+              projectsRoot,
+              syncRoot,
+              manifests: [...manifestByProjectId.values()],
+              projectIds: message.projectIds
+            });
+            for (const result of syncResult.results) {
+              if (result.status !== "synced") continue;
+              try {
+                await syncProjectPlans({
+                  baseUrl,
+                  token,
+                  projectId: result.projectId,
+                  branchName: result.branchName,
+                  planRoot
+                });
+              } catch (error) {
+                process.stderr.write(
+                  `[r5d-worker] plan sync skipped for ${result.projectId}/${result.branchName}: ${error instanceof Error ? error.message : String(error)}
 `
-              );
+                );
+              }
             }
+          } finally {
+            repositorySyncInProgress = false;
           }
         };
         const queued = repositorySyncQueue.then(executeSync, executeSync);
@@ -2475,6 +2526,43 @@ async function startWorker(options) {
         });
         return;
       }
+      if (message.type === "update_clis") {
+        if (cliUpdateInProgress) {
+          sendWorkerMessage(ws, {
+            type: "update_clis_result",
+            requestId: message.requestId,
+            error: "A CLI update is already in progress"
+          });
+          return;
+        }
+        if (activeProcesses.size > 0 || activePtys.size > 0 || repositorySyncInProgress) {
+          sendWorkerMessage(ws, {
+            type: "update_clis_result",
+            requestId: message.requestId,
+            error: "Worker is busy. Stop active commands and shells, then retry the CLI update."
+          });
+          return;
+        }
+        cliUpdateInProgress = true;
+        try {
+          const result = await (0, import_cli_update.installCliUpdate)(message);
+          sendWorkerMessage(ws, {
+            type: "update_clis_result",
+            requestId: message.requestId,
+            ...result
+          });
+          reloadAfterClose = true;
+          ws.close(1e3, "Activating updated CLIs");
+        } catch (error) {
+          cliUpdateInProgress = false;
+          sendWorkerMessage(ws, {
+            type: "update_clis_result",
+            requestId: message.requestId,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+        return;
+      }
       if (message.type === "ping") {
         lastServerHeartbeatAt = Date.now();
         ws.send(JSON.stringify({ type: "pong" }));
@@ -2482,23 +2570,41 @@ async function startWorker(options) {
       }
       if (message.type === "cancel") {
         const active = activeProcesses.get(message.runId);
+        let cancelled = true;
+        let cancelMessage;
         if (active) {
-          active.process.kill("SIGTERM");
+          try {
+            await (0, import_process_tree.terminateProcessTree)(active.process);
+            cancelMessage = `Stopped ${active.command}`;
+          } catch (error) {
+            cancelled = false;
+            cancelMessage = `Failed to stop ${active.command}: ${error instanceof Error ? error.message : String(error)}`;
+          }
         } else {
           cancelledProcessRuns.add(message.runId);
+          cancelMessage = "Cancellation queued before command start";
         }
         ws.send(
           JSON.stringify({
             type: "cancel_result",
             requestId: message.requestId,
             runId: message.runId,
-            cancelled: true,
-            message: active ? `Sent SIGTERM to ${active.command}` : "Cancellation queued before command start"
+            cancelled,
+            message: cancelMessage
           })
         );
         return;
       }
       if (message.type === "pty_open") {
+        if (cliUpdateInProgress) {
+          sendWorkerMessage(ws, {
+            type: "pty_error",
+            requestId: message.requestId,
+            ptyId: message.ptyId,
+            error: "Worker is activating a CLI update"
+          });
+          return;
+        }
         await repositorySyncQueue;
         const manifest = manifestByProjectId.get(message.projectId);
         const projectRoot = projectRootFor(projectsRoot, message.projectId, manifestByProjectId);
@@ -2520,6 +2626,16 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "exec") {
+        if (cliUpdateInProgress) {
+          sendWorkerMessage(ws, {
+            type: "exec_result",
+            requestId: message.requestId,
+            stdout: "",
+            stderr: "Worker is activating a CLI update",
+            exitCode: 1
+          });
+          return;
+        }
         await repositorySyncQueue;
         const manifest = manifestByProjectId.get(message.projectId);
         const projectRoot = projectRootFor(projectsRoot, message.projectId, manifestByProjectId);
@@ -2540,6 +2656,15 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "exec_start") {
+        if (cliUpdateInProgress) {
+          sendWorkerMessage(ws, {
+            type: "exec_start_error",
+            requestId: message.requestId,
+            runId: message.runId,
+            error: "Worker is activating a CLI update"
+          });
+          return;
+        }
         await repositorySyncQueue;
         sendWorkerMessage(ws, {
           type: "exec_accepted",
@@ -2637,6 +2762,9 @@ async function startWorker(options) {
     const reason = event.reason ? `: ${event.reason}` : "";
     process.stderr.write(`[r5d-worker] disconnected (${event.code}${reason})
 `);
+    if (reloadAfterClose) {
+      process.exit(import_supervisor.WORKER_RELOAD_EXIT_CODE);
+    }
     if (activeProcesses.size > 0) {
       const delayMs = 2e3;
       process.stderr.write(`[r5d-worker] ${activeProcesses.size} process(es) still active; reconnecting in ${delayMs}ms
@@ -2675,7 +2803,15 @@ async function main() {
     printVersion();
     return;
   }
-  await startWorker(parsed.options);
+  if (process.env[import_supervisor.WORKER_RUNTIME_ENV] === "1") {
+    delete process.env[import_supervisor.WORKER_RUNTIME_ENV];
+    await startWorker(parsed.options);
+    return;
+  }
+  const exitCode = await (0, import_supervisor.superviseWorkerRuntime)(process.argv.slice(2));
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
 }
 function isCliEntrypoint() {
   if (import_meta.main) {

package/dist/cjs/package.json

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

package/dist/cjs/process-tree.cjs

@@ -0,0 +1,117 @@
+"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 process_tree_exports = {};
+__export(process_tree_exports, {
+  terminateProcessTree: () => terminateProcessTree
+});
+module.exports = __toCommonJS(process_tree_exports);
+const DEFAULT_TERMINATION_GRACE_MS = 2e3;
+const DEFAULT_FORCE_KILL_WAIT_MS = 2e3;
+const PROCESS_GROUP_POLL_INTERVAL_MS = 25;
+const processTerminations = /* @__PURE__ */ new WeakMap();
+function errorCode(error) {
+  if (!error || typeof error !== "object" || !("code" in error)) {
+    return void 0;
+  }
+  return typeof error.code === "string" ? error.code : void 0;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isPosixProcessGroupRunning(processGroupId) {
+  try {
+    process.kill(-processGroupId, 0);
+    return true;
+  } catch (error) {
+    if (errorCode(error) === "ESRCH") {
+      return false;
+    }
+    if (errorCode(error) === "EPERM") {
+      return true;
+    }
+    throw error;
+  }
+}
+function signalPosixProcessGroup(processGroupId, signal) {
+  try {
+    process.kill(-processGroupId, signal);
+  } catch (error) {
+    if (errorCode(error) !== "ESRCH") {
+      throw error;
+    }
+  }
+}
+async function waitForPosixProcessGroupExit(processGroupId, timeoutMs) {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  while (isPosixProcessGroupRunning(processGroupId)) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      return false;
+    }
+    await delay(Math.min(PROCESS_GROUP_POLL_INTERVAL_MS, remainingMs));
+  }
+  return true;
+}
+async function runWindowsTaskkill(pid) {
+  const taskkill = Bun.spawn(["taskkill", "/PID", String(pid), "/T", "/F"], {
+    stdout: "ignore",
+    stderr: "pipe"
+  });
+  const [exitCode, stderr] = await Promise.all([
+    taskkill.exited,
+    taskkill.stderr ? new Response(taskkill.stderr).text() : Promise.resolve("")
+  ]);
+  if (exitCode !== 0 && !/not found|no running instance/i.test(stderr)) {
+    throw new Error(`Failed to terminate process tree ${pid}: ${stderr.trim() || `taskkill exited ${exitCode}`}`);
+  }
+}
+async function terminateProcessTreeOnce(subprocess, options) {
+  if (!Number.isSafeInteger(subprocess.pid) || subprocess.pid <= 0) {
+    throw new Error(`Cannot terminate invalid subprocess PID: ${subprocess.pid}`);
+  }
+  if (process.platform === "win32") {
+    await runWindowsTaskkill(subprocess.pid);
+    return;
+  }
+  const graceMs = options.graceMs ?? DEFAULT_TERMINATION_GRACE_MS;
+  const forceKillWaitMs = options.forceKillWaitMs ?? DEFAULT_FORCE_KILL_WAIT_MS;
+  signalPosixProcessGroup(subprocess.pid, "SIGTERM");
+  if (await waitForPosixProcessGroupExit(subprocess.pid, graceMs)) {
+    return;
+  }
+  signalPosixProcessGroup(subprocess.pid, "SIGKILL");
+  if (!await waitForPosixProcessGroupExit(subprocess.pid, forceKillWaitMs)) {
+    throw new Error(`Process group ${subprocess.pid} remained active after SIGKILL`);
+  }
+}
+function terminateProcessTree(subprocess, options = {}) {
+  const pending = processTerminations.get(subprocess);
+  if (pending) {
+    return pending;
+  }
+  const termination = terminateProcessTreeOnce(subprocess, options).finally(() => {
+    processTerminations.delete(subprocess);
+  });
+  processTerminations.set(subprocess, termination);
+  return termination;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  terminateProcessTree
+});

package/dist/cjs/supervisor.cjs

@@ -0,0 +1,58 @@
+"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 supervisor_exports = {};
+__export(supervisor_exports, {
+  WORKER_RELOAD_EXIT_CODE: () => WORKER_RELOAD_EXIT_CODE,
+  WORKER_RUNTIME_ENV: () => WORKER_RUNTIME_ENV,
+  superviseWorkerRuntime: () => superviseWorkerRuntime
+});
+module.exports = __toCommonJS(supervisor_exports);
+const WORKER_RUNTIME_ENV = "R5D_WORKER_INTERNAL_RUNTIME";
+const WORKER_RELOAD_EXIT_CODE = 75;
+function defaultRuntimeSpawner(argv, options) {
+  return Bun.spawn(argv, options);
+}
+async function superviseWorkerRuntime(argv, env = process.env, spawnRuntime = defaultRuntimeSpawner) {
+  if (!process.argv[1]) {
+    throw new Error("Cannot locate the r5d-worker entrypoint");
+  }
+  while (true) {
+    const runtime = spawnRuntime([process.execPath, process.argv[1], ...argv], {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: {
+        ...env,
+        [WORKER_RUNTIME_ENV]: "1"
+      }
+    });
+    const exitCode = await runtime.exited;
+    if (exitCode === WORKER_RELOAD_EXIT_CODE) {
+      process.stdout.write("[r5d-worker] activating updated worker runtime\n");
+      continue;
+    }
+    return exitCode;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WORKER_RELOAD_EXIT_CODE,
+  WORKER_RUNTIME_ENV,
+  superviseWorkerRuntime
+});

package/dist/mjs/cli-update.mjs

@@ -0,0 +1,80 @@
+const UPDATE_OUTPUT_LIMIT = 8e3;
+function collectOutput(value) {
+  if (!value || typeof value === "number") {
+    return Promise.resolve("");
+  }
+  return new Response(value).text();
+}
+async function runCommand(argv) {
+  const child = Bun.spawn(argv, {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([collectOutput(child.stdout), collectOutput(child.stderr), child.exited]);
+  return { exitCode, stdout, stderr };
+}
+function parseCliVersion(cliName, output) {
+  const escapedName = cliName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = output.trim().match(new RegExp(`(?:^|\\n)${escapedName}\\s+(\\S+)`));
+  return match?.[1]?.trim() || null;
+}
+function readInstalledCliVersion(cliName) {
+  try {
+    const result = Bun.spawnSync([cliName, "--version"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: process.env
+    });
+    if (result.exitCode !== 0) {
+      return null;
+    }
+    return parseCliVersion(cliName, Buffer.from(result.stdout).toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function getManualCliUpdateCommand(input) {
+  return `npm install -g --omit=dev ${shellQuote(input.workerPackageSpec)} ${shellQuote(input.r5dctlPackageSpec)}`;
+}
+function commandErrorDetail(result) {
+  const detail = `${result.stderr.trim()}${result.stderr.trim() && result.stdout.trim() ? "\n" : ""}${result.stdout.trim()}`.trim();
+  if (!detail) {
+    return `exit code ${result.exitCode}`;
+  }
+  return detail.slice(-UPDATE_OUTPUT_LIMIT);
+}
+async function readVerifiedVersion(cliName, targetVersion, runner) {
+  const result = await runner([cliName, "--version"]);
+  const installedVersion = result.exitCode === 0 ? parseCliVersion(cliName, result.stdout) : null;
+  if (!installedVersion) {
+    throw new Error(`${cliName} was installed but is not runnable: ${commandErrorDetail(result)}`);
+  }
+  if (installedVersion !== targetVersion) {
+    throw new Error(`${cliName} ${installedVersion} was installed; expected ${targetVersion}`);
+  }
+  return installedVersion;
+}
+async function installCliUpdate(input, runner = runCommand) {
+  const installArgs = ["npm", "install", "-g", "--omit=dev", input.workerPackageSpec, input.r5dctlPackageSpec];
+  const result = await runner(installArgs);
+  if (result.exitCode !== 0) {
+    throw new Error(`CLI update failed: ${commandErrorDetail(result)}
+Run manually: ${getManualCliUpdateCommand(input)}`);
+  }
+  const [installedWorkerVersion, installedR5dctlVersion] = await Promise.all([
+    readVerifiedVersion("r5d-worker", input.targetWorkerVersion, runner),
+    readVerifiedVersion("r5dctl", input.targetR5dctlVersion, runner)
+  ]);
+  return { installedWorkerVersion, installedR5dctlVersion };
+}
+export {
+  getManualCliUpdateCommand,
+  installCliUpdate,
+  parseCliVersion,
+  readInstalledCliVersion,
+  runCommand
+};

package/dist/mjs/main.mjs

@@ -4,8 +4,11 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 import os, { hostname } from "node:os";
 import { spawn as spawnChildProcess } from "node:child_process";
+import { installCliUpdate, readInstalledCliVersion } from "./cli-update.mjs";
 import { configureVisibleGitIdentity } from "./git-identity.mjs";
 import { hasWorkerHeartbeatTimedOut, WORKER_HEARTBEAT_INTERVAL_MS } from "./heartbeat.mjs";
+import { terminateProcessTree } from "./process-tree.mjs";
+import { superviseWorkerRuntime, WORKER_RELOAD_EXIT_CODE, WORKER_RUNTIME_ENV } from "./supervisor.mjs";
 const DEFAULT_BASE_URL = "https://r5d.dev";
 const WORKER_PACKAGE_NAME = "@ricsam/r5d-worker";
 const LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$/;
@@ -1772,6 +1775,7 @@ async function executeCommand(input) {
       cwd,
       stdout: "pipe",
       stderr: "pipe",
+      detached: true,
       env: {
         ...process.env,
         ...containerRegistryEnv(),
@@ -1793,7 +1797,12 @@ async function executeCommand(input) {
     });
     if (input.message.timeoutMs) {
       timeout = setTimeout(() => {
-        subprocess.kill("SIGTERM");
+        void terminateProcessTree(subprocess).catch((error) => {
+          process.stderr.write(
+            `[r5d-worker] failed to terminate timed-out command ${input.message.runId}: ${error instanceof Error ? error.message : String(error)}
+`
+          );
+        });
       }, input.message.timeoutMs);
     }
     const [stdout, stderr, exitCode] = await Promise.all([
@@ -1829,6 +1838,8 @@ async function executeCommand(input) {
 async function executeStreamingCommand(input) {
   const startedAt = Date.now();
   let started = false;
+  let timedOut = false;
+  let timeout;
   try {
     if (cancelledProcessRuns.delete(input.message.runId)) {
       sendWorkerMessage(input.ws, {
@@ -1869,6 +1880,7 @@ async function executeStreamingCommand(input) {
       cwd,
       stdout: "pipe",
       stderr: "pipe",
+      detached: true,
       env: {
         ...process.env,
         ...containerRegistryEnv(),
@@ -1895,6 +1907,17 @@ async function executeStreamingCommand(input) {
       requestId: input.message.requestId,
       runId: input.message.runId
     });
+    if (input.message.timeoutMs) {
+      timeout = setTimeout(() => {
+        timedOut = true;
+        void terminateProcessTree(subprocess).catch((error) => {
+          process.stderr.write(
+            `[r5d-worker] failed to terminate timed-out process ${input.message.runId}: ${error instanceof Error ? error.message : String(error)}
+`
+          );
+        });
+      }, input.message.timeoutMs);
+    }
     const [exitCode] = await Promise.all([
       subprocess.exited,
       streamCommandOutput(subprocess.stdout, (data) => {
@@ -1918,7 +1941,8 @@ async function executeStreamingCommand(input) {
       type: "exec_exit",
       runId: input.message.runId,
       exitCode,
-      durationMs: Date.now() - startedAt
+      durationMs: Date.now() - startedAt,
+      ...timedOut ? { timedOut: true } : {}
     });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -1938,6 +1962,9 @@ async function executeStreamingCommand(input) {
       });
     }
   } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
     activeProcesses.delete(input.message.runId);
     cancelledProcessRuns.delete(input.message.runId);
   }
@@ -2315,6 +2342,9 @@ async function startWorker(options) {
   fs.mkdirSync(planRoot, { recursive: true });
   const manifestByProjectId = /* @__PURE__ */ new Map();
   let repositorySyncQueue = Promise.resolve();
+  let repositorySyncInProgress = false;
+  let cliUpdateInProgress = false;
+  let reloadAfterClose = false;
   const ws = new WebSocket(websocketUrl(baseUrl, label), {
     headers: {
       Authorization: `Bearer ${token}`
@@ -2348,6 +2378,10 @@ async function startWorker(options) {
         arch: process.arch,
         pid: process.pid,
         version: getWorkerVersion(),
+        r5dctlVersion: readInstalledCliVersion("r5dctl"),
+        capabilities: {
+          updateClis: true
+        },
         projectRoot: projectsRoot,
         artifactRoot,
         planRoot
@@ -2375,32 +2409,49 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "sync_projects") {
+        if (cliUpdateInProgress) {
+          sendWorkerMessage(ws, {
+            type: "sync_projects_result",
+            requestId: message.requestId,
+            result: {
+              status: "blocked",
+              results: [],
+              blockedBy: []
+            }
+          });
+          return;
+        }
         let syncResult = { status: "completed", results: [], blockedBy: [] };
         const executeSync = async () => {
-          syncResult = await syncManifestProjectsFromInternal({
-            baseUrl,
-            token,
-            projectsRoot,
-            syncRoot,
-            manifests: [...manifestByProjectId.values()],
-            projectIds: message.projectIds
-          });
-          for (const result of syncResult.results) {
-            if (result.status !== "synced") continue;
-            try {
-              await syncProjectPlans({
-                baseUrl,
-                token,
-                projectId: result.projectId,
-                branchName: result.branchName,
-                planRoot
-              });
-            } catch (error) {
-              process.stderr.write(
-                `[r5d-worker] plan sync skipped for ${result.projectId}/${result.branchName}: ${error instanceof Error ? error.message : String(error)}
+          repositorySyncInProgress = true;
+          try {
+            syncResult = await syncManifestProjectsFromInternal({
+              baseUrl,
+              token,
+              projectsRoot,
+              syncRoot,
+              manifests: [...manifestByProjectId.values()],
+              projectIds: message.projectIds
+            });
+            for (const result of syncResult.results) {
+              if (result.status !== "synced") continue;
+              try {
+                await syncProjectPlans({
+                  baseUrl,
+                  token,
+                  projectId: result.projectId,
+                  branchName: result.branchName,
+                  planRoot
+                });
+              } catch (error) {
+                process.stderr.write(
+                  `[r5d-worker] plan sync skipped for ${result.projectId}/${result.branchName}: ${error instanceof Error ? error.message : String(error)}
 `
-              );
+                );
+              }
             }
+          } finally {
+            repositorySyncInProgress = false;
           }
         };
         const queued = repositorySyncQueue.then(executeSync, executeSync);
@@ -2432,6 +2483,43 @@ async function startWorker(options) {
         });
         return;
       }
+      if (message.type === "update_clis") {
+        if (cliUpdateInProgress) {
+          sendWorkerMessage(ws, {
+            type: "update_clis_result",
+            requestId: message.requestId,
+            error: "A CLI update is already in progress"
+          });
+          return;
+        }
+        if (activeProcesses.size > 0 || activePtys.size > 0 || repositorySyncInProgress) {
+          sendWorkerMessage(ws, {
+            type: "update_clis_result",
+            requestId: message.requestId,
+            error: "Worker is busy. Stop active commands and shells, then retry the CLI update."
+          });
+          return;
+        }
+        cliUpdateInProgress = true;
+        try {
+          const result = await installCliUpdate(message);
+          sendWorkerMessage(ws, {
+            type: "update_clis_result",
+            requestId: message.requestId,
+            ...result
+          });
+          reloadAfterClose = true;
+          ws.close(1e3, "Activating updated CLIs");
+        } catch (error) {
+          cliUpdateInProgress = false;
+          sendWorkerMessage(ws, {
+            type: "update_clis_result",
+            requestId: message.requestId,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+        return;
+      }
       if (message.type === "ping") {
         lastServerHeartbeatAt = Date.now();
         ws.send(JSON.stringify({ type: "pong" }));
@@ -2439,23 +2527,41 @@ async function startWorker(options) {
       }
       if (message.type === "cancel") {
         const active = activeProcesses.get(message.runId);
+        let cancelled = true;
+        let cancelMessage;
         if (active) {
-          active.process.kill("SIGTERM");
+          try {
+            await terminateProcessTree(active.process);
+            cancelMessage = `Stopped ${active.command}`;
+          } catch (error) {
+            cancelled = false;
+            cancelMessage = `Failed to stop ${active.command}: ${error instanceof Error ? error.message : String(error)}`;
+          }
         } else {
           cancelledProcessRuns.add(message.runId);
+          cancelMessage = "Cancellation queued before command start";
         }
         ws.send(
           JSON.stringify({
             type: "cancel_result",
             requestId: message.requestId,
             runId: message.runId,
-            cancelled: true,
-            message: active ? `Sent SIGTERM to ${active.command}` : "Cancellation queued before command start"
+            cancelled,
+            message: cancelMessage
           })
         );
         return;
       }
       if (message.type === "pty_open") {
+        if (cliUpdateInProgress) {
+          sendWorkerMessage(ws, {
+            type: "pty_error",
+            requestId: message.requestId,
+            ptyId: message.ptyId,
+            error: "Worker is activating a CLI update"
+          });
+          return;
+        }
         await repositorySyncQueue;
         const manifest = manifestByProjectId.get(message.projectId);
         const projectRoot = projectRootFor(projectsRoot, message.projectId, manifestByProjectId);
@@ -2477,6 +2583,16 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "exec") {
+        if (cliUpdateInProgress) {
+          sendWorkerMessage(ws, {
+            type: "exec_result",
+            requestId: message.requestId,
+            stdout: "",
+            stderr: "Worker is activating a CLI update",
+            exitCode: 1
+          });
+          return;
+        }
         await repositorySyncQueue;
         const manifest = manifestByProjectId.get(message.projectId);
         const projectRoot = projectRootFor(projectsRoot, message.projectId, manifestByProjectId);
@@ -2497,6 +2613,15 @@ async function startWorker(options) {
         return;
       }
       if (message.type === "exec_start") {
+        if (cliUpdateInProgress) {
+          sendWorkerMessage(ws, {
+            type: "exec_start_error",
+            requestId: message.requestId,
+            runId: message.runId,
+            error: "Worker is activating a CLI update"
+          });
+          return;
+        }
         await repositorySyncQueue;
         sendWorkerMessage(ws, {
           type: "exec_accepted",
@@ -2594,6 +2719,9 @@ async function startWorker(options) {
     const reason = event.reason ? `: ${event.reason}` : "";
     process.stderr.write(`[r5d-worker] disconnected (${event.code}${reason})
 `);
+    if (reloadAfterClose) {
+      process.exit(WORKER_RELOAD_EXIT_CODE);
+    }
     if (activeProcesses.size > 0) {
       const delayMs = 2e3;
       process.stderr.write(`[r5d-worker] ${activeProcesses.size} process(es) still active; reconnecting in ${delayMs}ms
@@ -2632,7 +2760,15 @@ async function main() {
     printVersion();
     return;
   }
-  await startWorker(parsed.options);
+  if (process.env[WORKER_RUNTIME_ENV] === "1") {
+    delete process.env[WORKER_RUNTIME_ENV];
+    await startWorker(parsed.options);
+    return;
+  }
+  const exitCode = await superviseWorkerRuntime(process.argv.slice(2));
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
 }
 function isCliEntrypoint() {
   if (import.meta.main) {

package/dist/mjs/package.json

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

package/dist/mjs/process-tree.mjs

@@ -0,0 +1,93 @@
+const DEFAULT_TERMINATION_GRACE_MS = 2e3;
+const DEFAULT_FORCE_KILL_WAIT_MS = 2e3;
+const PROCESS_GROUP_POLL_INTERVAL_MS = 25;
+const processTerminations = /* @__PURE__ */ new WeakMap();
+function errorCode(error) {
+  if (!error || typeof error !== "object" || !("code" in error)) {
+    return void 0;
+  }
+  return typeof error.code === "string" ? error.code : void 0;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isPosixProcessGroupRunning(processGroupId) {
+  try {
+    process.kill(-processGroupId, 0);
+    return true;
+  } catch (error) {
+    if (errorCode(error) === "ESRCH") {
+      return false;
+    }
+    if (errorCode(error) === "EPERM") {
+      return true;
+    }
+    throw error;
+  }
+}
+function signalPosixProcessGroup(processGroupId, signal) {
+  try {
+    process.kill(-processGroupId, signal);
+  } catch (error) {
+    if (errorCode(error) !== "ESRCH") {
+      throw error;
+    }
+  }
+}
+async function waitForPosixProcessGroupExit(processGroupId, timeoutMs) {
+  const deadline = Date.now() + Math.max(0, timeoutMs);
+  while (isPosixProcessGroupRunning(processGroupId)) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      return false;
+    }
+    await delay(Math.min(PROCESS_GROUP_POLL_INTERVAL_MS, remainingMs));
+  }
+  return true;
+}
+async function runWindowsTaskkill(pid) {
+  const taskkill = Bun.spawn(["taskkill", "/PID", String(pid), "/T", "/F"], {
+    stdout: "ignore",
+    stderr: "pipe"
+  });
+  const [exitCode, stderr] = await Promise.all([
+    taskkill.exited,
+    taskkill.stderr ? new Response(taskkill.stderr).text() : Promise.resolve("")
+  ]);
+  if (exitCode !== 0 && !/not found|no running instance/i.test(stderr)) {
+    throw new Error(`Failed to terminate process tree ${pid}: ${stderr.trim() || `taskkill exited ${exitCode}`}`);
+  }
+}
+async function terminateProcessTreeOnce(subprocess, options) {
+  if (!Number.isSafeInteger(subprocess.pid) || subprocess.pid <= 0) {
+    throw new Error(`Cannot terminate invalid subprocess PID: ${subprocess.pid}`);
+  }
+  if (process.platform === "win32") {
+    await runWindowsTaskkill(subprocess.pid);
+    return;
+  }
+  const graceMs = options.graceMs ?? DEFAULT_TERMINATION_GRACE_MS;
+  const forceKillWaitMs = options.forceKillWaitMs ?? DEFAULT_FORCE_KILL_WAIT_MS;
+  signalPosixProcessGroup(subprocess.pid, "SIGTERM");
+  if (await waitForPosixProcessGroupExit(subprocess.pid, graceMs)) {
+    return;
+  }
+  signalPosixProcessGroup(subprocess.pid, "SIGKILL");
+  if (!await waitForPosixProcessGroupExit(subprocess.pid, forceKillWaitMs)) {
+    throw new Error(`Process group ${subprocess.pid} remained active after SIGKILL`);
+  }
+}
+function terminateProcessTree(subprocess, options = {}) {
+  const pending = processTerminations.get(subprocess);
+  if (pending) {
+    return pending;
+  }
+  const termination = terminateProcessTreeOnce(subprocess, options).finally(() => {
+    processTerminations.delete(subprocess);
+  });
+  processTerminations.set(subprocess, termination);
+  return termination;
+}
+export {
+  terminateProcessTree
+};

package/dist/mjs/supervisor.mjs

@@ -0,0 +1,32 @@
+const WORKER_RUNTIME_ENV = "R5D_WORKER_INTERNAL_RUNTIME";
+const WORKER_RELOAD_EXIT_CODE = 75;
+function defaultRuntimeSpawner(argv, options) {
+  return Bun.spawn(argv, options);
+}
+async function superviseWorkerRuntime(argv, env = process.env, spawnRuntime = defaultRuntimeSpawner) {
+  if (!process.argv[1]) {
+    throw new Error("Cannot locate the r5d-worker entrypoint");
+  }
+  while (true) {
+    const runtime = spawnRuntime([process.execPath, process.argv[1], ...argv], {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: {
+        ...env,
+        [WORKER_RUNTIME_ENV]: "1"
+      }
+    });
+    const exitCode = await runtime.exited;
+    if (exitCode === WORKER_RELOAD_EXIT_CODE) {
+      process.stdout.write("[r5d-worker] activating updated worker runtime\n");
+      continue;
+    }
+    return exitCode;
+  }
+}
+export {
+  WORKER_RELOAD_EXIT_CODE,
+  WORKER_RUNTIME_ENV,
+  superviseWorkerRuntime
+};

package/dist/types/cli-update.d.ts

@@ -0,0 +1,21 @@
+export type CommandResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type CommandRunner = (argv: string[]) => Promise<CommandResult>;
+export type CliUpdateRequest = {
+    workerPackageSpec: string;
+    r5dctlPackageSpec: string;
+    targetWorkerVersion: string;
+    targetR5dctlVersion: string;
+};
+export type CliUpdateResult = {
+    installedWorkerVersion: string;
+    installedR5dctlVersion: string;
+};
+export declare function runCommand(argv: string[]): Promise<CommandResult>;
+export declare function parseCliVersion(cliName: "r5d-worker" | "r5dctl", output: string): string | null;
+export declare function readInstalledCliVersion(cliName: "r5d-worker" | "r5dctl"): string | null;
+export declare function getManualCliUpdateCommand(input: Pick<CliUpdateRequest, "workerPackageSpec" | "r5dctlPackageSpec">): string;
+export declare function installCliUpdate(input: CliUpdateRequest, runner?: CommandRunner): Promise<CliUpdateResult>;

package/dist/types/process-tree.d.ts

@@ -0,0 +1,16 @@
+export type KillableSubprocess = {
+    readonly pid: number;
+    readonly exited: Promise<number>;
+    kill(signal?: number | NodeJS.Signals): void;
+};
+type TerminateProcessTreeOptions = {
+    graceMs?: number;
+    forceKillWaitMs?: number;
+};
+/**
+ * Terminates a subprocess spawned with `detached: true` and every descendant
+ * that remains in its process group. Concurrent termination requests share one
+ * cleanup attempt.
+ */
+export declare function terminateProcessTree(subprocess: KillableSubprocess, options?: TerminateProcessTreeOptions): Promise<void>;
+export {};

package/dist/types/supervisor.d.ts

@@ -0,0 +1,13 @@
+export declare const WORKER_RUNTIME_ENV = "R5D_WORKER_INTERNAL_RUNTIME";
+export declare const WORKER_RELOAD_EXIT_CODE = 75;
+type RuntimeProcess = {
+    exited: Promise<number>;
+};
+export type RuntimeSpawner = (argv: string[], options: {
+    stdin: "inherit";
+    stdout: "inherit";
+    stderr: "inherit";
+    env: Record<string, string | undefined>;
+}) => RuntimeProcess;
+export declare function superviseWorkerRuntime(argv: string[], env?: Record<string, string | undefined>, spawnRuntime?: RuntimeSpawner): Promise<number>;
+export {};

package/package.json

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