@indigoai-us/hq-cli 5.167.0 → 5.168.0

package/dist/commands/outpost-pruner.js

@@ -0,0 +1,125 @@
+import { spawnSync } from "node:child_process";
+import * as os from "node:os";
+import * as path from "node:path";
+import { outpostWorktreePrunerEnabled, OUTPOST_WORKTREE_PRUNER_FLAG } from "../lib/lanes/outpost-worktree-pruner-flag.js";
+import { OUTPOST_WORKTREE_PRUNER_DEFAULT_MIN_AGE_DAYS, runOutpostWorktreePruner, } from "../lib/lanes/outpost-worktree-pruner.js";
+import { defaultOutpostPrunerSystemdDir, installOutpostPrunerTimers, uninstallOutpostPrunerTimers, } from "../lib/lanes/outpost-pruner-install.js";
+import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
+function errorType(error) {
+    return error instanceof Error ? error.name : "UnknownError";
+}
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+function printErrorJson(event, error, fields = {}) {
+    printJson({ event, ...fields, error: errorType(error) });
+}
+function runSystemctl(binary, args) {
+    const result = spawnSync(binary, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+function systemdRoot(option) {
+    return path.resolve(option ?? defaultOutpostPrunerSystemdDir(os.homedir()));
+}
+function skippedResult(trigger, minAgeDays, reason) {
+    return {
+        event: "outpost.worktree_pruner.run",
+        trigger,
+        dry_run: false,
+        feature_enabled: false,
+        skipped: reason,
+        flag: OUTPOST_WORKTREE_PRUNER_FLAG,
+        min_age_days: minAgeDays,
+        candidates: [],
+        removed: [],
+        kept: [],
+        bytes_freed: 0,
+        bytes_freed_basis: "statfs_available_byte_delta",
+        package_store: { attempted: false, reason: "not_run" },
+    };
+}
+export function registerOutpostPrunerCommand(lanes) {
+    const pruner = lanes
+        .command("outpost-pruner")
+        .description("Inspect, install, and run safe outpost worktree pruning");
+    pruner
+        .command("run")
+        .description("Run the guarded outpost worktree and user-cache cleanup")
+        .option("--trigger <kind>", "pressure | daily | manual", "manual")
+        .option("--min-age-days <days>", "Minimum age before cleanup (1–365 days)", (value) => Number(value), OUTPOST_WORKTREE_PRUNER_DEFAULT_MIN_AGE_DAYS)
+        .option("--dry-run", "List eligible worktrees without deleting files")
+        .action(async (options) => {
+        const trigger = options.trigger ?? "manual";
+        const minAgeDays = options.minAgeDays ?? OUTPOST_WORKTREE_PRUNER_DEFAULT_MIN_AGE_DAYS;
+        try {
+            if (!["pressure", "daily", "manual"].includes(trigger)) {
+                throw new TypeError("invalid trigger");
+            }
+            const featureEnabled = options.dryRun ? false : await outpostWorktreePrunerEnabled();
+            if (!options.dryRun && !featureEnabled) {
+                printJson(skippedResult(trigger, minAgeDays, "feature_flag_off"));
+                return;
+            }
+            const result = runOutpostWorktreePruner({
+                hqRoot: resolveLanesHqRoot(),
+                trigger,
+                dryRun: Boolean(options.dryRun),
+                featureEnabled,
+                minAgeDays,
+            });
+            printJson({ ...result, flag: OUTPOST_WORKTREE_PRUNER_FLAG });
+        }
+        catch (error) {
+            printErrorJson("outpost.worktree_pruner.run", error, {
+                trigger,
+                dry_run: Boolean(options.dryRun),
+            });
+            process.exitCode = 1;
+        }
+    });
+    pruner
+        .command("install")
+        .description("Write the pressure and daily systemd user timers")
+        .option("--systemd-root <path>", "Systemd user unit directory")
+        .option("--enable", "Enable both timers after writing the units")
+        .action((options) => {
+        try {
+            const result = installOutpostPrunerTimers({
+                systemdRoot: systemdRoot(options.systemdRoot),
+                hqRoot: resolveLanesHqRoot(),
+                home: os.homedir(),
+                enable: Boolean(options.enable),
+                runCommand: options.enable ? runSystemctl : undefined,
+            });
+            printJson(result);
+        }
+        catch (error) {
+            printErrorJson("outpost.worktree_pruner.install", error);
+            process.exitCode = 1;
+        }
+    });
+    pruner
+        .command("uninstall")
+        .description("Disable and remove the pressure and daily systemd user timers")
+        .option("--systemd-root <path>", "Systemd user unit directory")
+        .option("--disable", "Disable both timers before removing their units")
+        .action((options) => {
+        try {
+            const result = uninstallOutpostPrunerTimers({
+                systemdRoot: systemdRoot(options.systemdRoot),
+                disable: Boolean(options.disable),
+                runCommand: options.disable ? runSystemctl : undefined,
+            });
+            printJson(result);
+        }
+        catch (error) {
+            printErrorJson("outpost.worktree_pruner.uninstall", error);
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=outpost-pruner.js.map

package/dist/lib/daemon/catalog.d.ts

@@ -10,7 +10,7 @@
  * them instead of silently dropping them.
  */
 import type { MachineType } from "./machine-type.js";
-export declare const SERVICE_NAMES: readonly ["sync", "mesh", "heartbeat", "inbox", "bots", "remote-control", "session-host", "lanes-reconcile", "search-index", "jobs-reconcile", "updater", "housekeeping"];
+export declare const SERVICE_NAMES: readonly ["sync", "mesh", "heartbeat", "inbox", "bots", "remote-control", "codex-remote-control", "session-host", "lanes-reconcile", "search-index", "jobs-reconcile", "updater", "housekeeping"];
 export type ServiceName = (typeof SERVICE_NAMES)[number];
 export declare function isServiceName(value: unknown): value is ServiceName;
 export declare const SERVICE_DESCRIPTIONS: Record<ServiceName, string>;
@@ -79,7 +79,17 @@ export interface PlanContext {
     tmuxPath: string | null;
     /** Short host name, used to name this machine's remote-control session. */
     hostName: string;
+    /** The session name the box's own runner used (`--name` in its script), kept when the daemon takes over. */
+    remoteControlName: string | null;
+    /** Absolute path of the login user's codex binary, or null. */
+    codexPath: string | null;
+    /** The box's Codex remote-control runner script, when it has one. */
+    codexRunnerScript: string | null;
 }
+/** Written by outpost provisioning; the daemon runs it rather than re-implementing Codex login and relay setup. */
+export declare const CODEX_RUNNER_SCRIPT = "/usr/local/bin/outpost-codex-runner.sh";
+/** The outpost's Claude runner script, read for the session name it uses. */
+export declare const CLAUDE_RUNNER_SCRIPT = "/usr/local/bin/outpost-runner.sh";
 /** Turn enabled services into concrete units for this host. */
 export declare function planUnits(services: readonly ServiceName[], ctx: PlanContext): UnitPlan[];
 //# sourceMappingURL=catalog.d.ts.map

package/dist/lib/daemon/catalog.js

@@ -16,6 +16,7 @@ export const SERVICE_NAMES = [
     "inbox",
     "bots",
     "remote-control",
+    "codex-remote-control",
     "session-host",
     "lanes-reconcile",
     "search-index",
@@ -33,16 +34,17 @@ export const SERVICE_DESCRIPTIONS = {
     inbox: "picks up the agent's incoming messages and tasks",
     bots: "runs local bots",
     "remote-control": "keeps Claude remote control running",
+    "codex-remote-control": "keeps Codex remote control running",
     "session-host": "lets the desktop app open this machine's Claude sessions",
     "lanes-reconcile": "cleans up stalled background lanes",
     "search-index": "keeps local search up to date",
     "jobs-reconcile": "keeps scheduled jobs matched to the cloud",
-    updater: "keeps the hq CLI and Codex up to date",
+    updater: "keeps the hq CLI, Claude, Codex and Grok up to date",
     housekeeping: "rotates daemon logs",
 };
 /** The services each machine type runs without being asked. */
 export const DEFAULT_SERVICES = {
-    desktop: ["sync", "mesh", "heartbeat", "bots", "lanes-reconcile", "search-index", "housekeeping"],
+    desktop: ["sync", "mesh", "heartbeat", "bots", "lanes-reconcile", "search-index", "updater", "housekeeping"],
     "self-hosted": [
         "sync",
         "mesh",
@@ -59,6 +61,7 @@ export const DEFAULT_SERVICES = {
         "mesh",
         "heartbeat",
         "remote-control",
+        "codex-remote-control",
         "session-host",
         "lanes-reconcile",
         "search-index",
@@ -93,6 +96,10 @@ function firstBlock(checks) {
     const hit = checks.find(([blocked]) => blocked);
     return hit ? { state: "waiting", reason: hit[1] } : undefined;
 }
+/** Written by outpost provisioning; the daemon runs it rather than re-implementing Codex login and relay setup. */
+export const CODEX_RUNNER_SCRIPT = "/usr/local/bin/outpost-codex-runner.sh";
+/** The outpost's Claude runner script, read for the session name it uses. */
+export const CLAUDE_RUNNER_SCRIPT = "/usr/local/bin/outpost-runner.sh";
 const NO_HQ_ROOT = "no HQ folder configured (run `hq daemon install --hq-root <path>`)";
 const NOT_SIGNED_IN = "not signed in (run `hq login`)";
 const KIT_NOT_SET_UP = "the agent kit is not set up on this machine (run `hq agent kit install`)";
@@ -205,9 +212,6 @@ function planService(service, ctx) {
                     intervalSec: 6 * 3600,
                     initialDelaySec: 900,
                     command: { type: "hq", args: ["daemon", "service", "self-update"] },
-                    blocked: firstBlock([
-                        [!ctx.cliSelfUpdatable, "this hq CLI is not a global install, so it is updated with the project or app that owns it"],
-                    ]),
                 }),
             ];
         case "jobs-reconcile": {
@@ -232,12 +236,33 @@ function planService(service, ctx) {
                 }),
             ];
         }
+        case "codex-remote-control": {
+            if (ctx.platform === "win32")
+                return [unavailable(service, "not supported on Windows")];
+            const script = ctx.codexRunnerScript;
+            return [
+                base(service, {
+                    command: {
+                        type: "hq",
+                        args: ["daemon", "service", "codex-remote-control", "--script", script ?? "", "--codex", ctx.codexPath ?? ""],
+                    },
+                    env: ctx.hqRoot ? { HQ_ROOT: ctx.hqRoot } : {},
+                    blocked: firstBlock([
+                        [!script, `this machine has no Codex remote-control runner (${CODEX_RUNNER_SCRIPT})`],
+                        [!ctx.codexPath, "the codex CLI is not installed"],
+                        [!ctx.tmuxPath, "tmux is not installed (Codex remote control runs inside tmux)"],
+                        [!ctx.hqRoot, NO_HQ_ROOT],
+                    ]),
+                }),
+            ];
+        }
         case "remote-control": {
             if (ctx.platform === "win32")
                 return [unavailable(service, "not supported on Windows yet")];
             // Outposts keep the runner's session name and permission mode.
             const outpost = ctx.machineType === "outpost";
-            const args = ["daemon", "service", "remote-control", "--claude", ctx.claudePath ?? "", "--name", outpost ? "outpost-1" : ctx.hostName];
+            const name = ctx.remoteControlName ?? (outpost ? "outpost-1" : ctx.hostName);
+            const args = ["daemon", "service", "remote-control", "--claude", ctx.claudePath ?? "", "--name", name];
             if (outpost)
                 args.push("--permission-mode", "bypassPermissions");
             return [

package/dist/lib/daemon/install.d.ts

@@ -64,6 +64,13 @@ export interface DaemonUnitResult {
 export interface InstallDeps {
     run: RunCommand;
 }
+export declare const ROOT_REFUSAL = "hq daemon runs its services as the machine's login user, never as root.";
+/**
+ * Why the daemon must not run here as root, or null when it may. Agent kits
+ * are the one exception: they run in containers where root is often the only
+ * account.
+ */
+export declare function daemonRootRefusal(isRoot: boolean, machineType: MachineType): string | null;
 /** Boxes run the daemon as a system unit; everything else per user. */
 export declare function installScopeFor(machineType: MachineType): InstallScope;
 export declare function planDaemonUnit(host: DaemonHost, options: InstallOptions): DaemonUnitPlan;

package/dist/lib/daemon/install.js

@@ -21,10 +21,22 @@ import { activateLaunchd, deactivateLaunchd, launchdPlistPath, renderLaunchdPlis
 import { activateSystemd, deactivateSystemd, renderSystemdUserUnit, systemdUnitPath, } from "../service-manager/systemd.js";
 import { escapeXml, shellQuote } from "../service-manager/types.js";
 import { readPidLock } from "../mesh/live/daemon/pid-lock.js";
+import { userToolDirs } from "./tools.js";
 export const DAEMON_LAUNCHD_LABEL = "ai.getindigo.hq-daemon";
 export const DAEMON_SYSTEMD_UNIT = "hq-daemon.service";
 export const DAEMON_WINDOWS_TASK = "ai.getindigo.hq-daemon";
 export const SYSTEM_UNIT_DIR = "/etc/systemd/system";
+export const ROOT_REFUSAL = "hq daemon runs its services as the machine's login user, never as root.";
+/**
+ * Why the daemon must not run here as root, or null when it may. Agent kits
+ * are the one exception: they run in containers where root is often the only
+ * account.
+ */
+export function daemonRootRefusal(isRoot, machineType) {
+    if (!isRoot || machineType === "agent-kit")
+        return null;
+    return `${ROOT_REFUSAL} Run it as that user instead of root.`;
+}
 /** Boxes run the daemon as a system unit; everything else per user. */
 export function installScopeFor(machineType) {
     return machineType === "outpost" || machineType === "agent-box" ? "system" : "user";
@@ -55,7 +67,9 @@ function renderSystemdSystemUnit(host, user, userHome) {
     const env = {
         ...host.env,
         HOME: userHome,
-        PATH: host.env?.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+        // The login user's own tools come first, so the daemon runs (and can
+        // update) their Claude, Codex and Grok rather than root's copies in /usr.
+        PATH: [...userToolDirs(userHome), host.env?.PATH ?? "/usr/local/bin:/usr/bin:/bin"].join(":"),
     };
     const envLines = Object.entries(env)
         .sort(([a], [b]) => a.localeCompare(b))
@@ -163,8 +177,10 @@ export function planDaemonUnit(host, options) {
     if (host.platform === "linux") {
         if (options.scope === "system") {
             if (!options.runAsUser) {
-                throw new Error("A system install needs the box's login user. Provisioning writes it to /etc/hq/machine-type (user=<name>).");
+                throw new Error("A system install needs the box's login user: pass --user <name>, or provisioning writes it to /etc/hq/machine-type (user=<name>).");
             }
+            if (options.runAsUser === "root")
+                throw new Error(ROOT_REFUSAL);
             if (!options.runAsHome)
                 throw new Error(`Could not find the home directory of ${options.runAsUser}.`);
             return {

package/dist/lib/daemon/legacy.js

@@ -19,9 +19,14 @@ const SYSTEM_UNITS = [
     ["hq-agent-inbox.service", "inbox"],
     ["hq-agent-qmd-index.timer", "search-index"],
     ["outpost-jobs-reconcile.timer", "jobs-reconcile"],
+    // The runners' watchdogs restart the old runners, so they are taken over with them.
     ["outpost-runner.service", "remote-control"],
-    ["outpost-codex-runner.service", "remote-control"],
+    ["outpost-runner-watchdog.timer", "remote-control"],
+    ["outpost-rc-watchdog.timer", "remote-control"],
+    ["outpost-codex-runner.service", "codex-remote-control"],
+    ["outpost-codex-watchdog.timer", "codex-remote-control"],
     ["hq-cli-update.timer", "updater"],
+    ["outpost-codex-update.timer", "updater"],
 ];
 const KIND_LABEL = {
     launchd: "LaunchAgent",

package/dist/lib/daemon/machine-type.d.ts

@@ -6,6 +6,7 @@
  *   1. `--machine-type` flag
  *   2. the type saved in ~/.hq/daemon/config.json by an earlier install
  *   3. /etc/hq/machine-type, written by box provisioning (may name a login user)
+ *   3b. an outpost runner unit (outposts provisioned before the marker)
  *   4. agent-kit machine credentials present → agent-kit
  *   5. running in a container → agent-kit
  *   6. macOS or Windows → desktop
@@ -14,7 +15,9 @@
 export declare const MACHINE_TYPES: readonly ["desktop", "self-hosted", "outpost", "agent-box", "agent-kit"];
 export type MachineType = (typeof MACHINE_TYPES)[number];
 export declare const MACHINE_TYPE_MARKER_PATH = "/etc/hq/machine-type";
-export type MachineTypeSource = "flag" | "config" | "marker" | "agent-kit-creds" | "container" | "platform";
+export type MachineTypeSource = "flag" | "config" | "marker" | "outpost-units" | "agent-kit-creds" | "container" | "platform";
+/** The Claude runner unit outpost provisioning installs; its `User=` is the box's login user. */
+export declare const OUTPOST_RUNNER_UNIT = "/etc/systemd/system/outpost-runner.service";
 export interface MachineTypeResult {
     type: MachineType;
     source: MachineTypeSource;

package/dist/lib/daemon/machine-type.js

@@ -6,6 +6,7 @@
  *   1. `--machine-type` flag
  *   2. the type saved in ~/.hq/daemon/config.json by an earlier install
  *   3. /etc/hq/machine-type, written by box provisioning (may name a login user)
+ *   3b. an outpost runner unit (outposts provisioned before the marker)
  *   4. agent-kit machine credentials present → agent-kit
  *   5. running in a container → agent-kit
  *   6. macOS or Windows → desktop
@@ -15,6 +16,8 @@ import * as path from "node:path";
 import { AGENT_DIR_ENV, MACHINE_CREDS_NAME, agentRootDir } from "../agent-kit/paths.js";
 export const MACHINE_TYPES = ["desktop", "self-hosted", "outpost", "agent-box", "agent-kit"];
 export const MACHINE_TYPE_MARKER_PATH = "/etc/hq/machine-type";
+/** The Claude runner unit outpost provisioning installs; its `User=` is the box's login user. */
+export const OUTPOST_RUNNER_UNIT = "/etc/systemd/system/outpost-runner.service";
 export function isMachineType(value) {
     return typeof value === "string" && MACHINE_TYPES.includes(value);
 }
@@ -46,7 +49,8 @@ export function parseMachineTypeMarker(text) {
         return null;
     if (user !== undefined && !ACCOUNT_NAME.test(user))
         return null;
-    return user ? { type, user } : { type };
+    // The daemon never runs as root, so root is never taken as the login user.
+    return user && user !== "root" ? { type, user } : { type };
 }
 function platformName(platform) {
     if (platform === "darwin")
@@ -72,12 +76,29 @@ function readMarker(deps, warnings) {
         return null;
     }
 }
-/** Box types run as the login user the provisioning marker names, however the type itself was chosen. */
+/** The login user the outpost runner unit runs as, or undefined (never root). */
+function outpostRunnerUser(deps) {
+    if (!deps.existsSync(OUTPOST_RUNNER_UNIT))
+        return undefined;
+    let text;
+    try {
+        text = deps.readFileSync(OUTPOST_RUNNER_UNIT);
+    }
+    catch {
+        return undefined;
+    }
+    const user = /^\s*User\s*=\s*(\S+)\s*$/m.exec(text)?.[1];
+    return user && user !== "root" && ACCOUNT_NAME.test(user) ? user : undefined;
+}
+/**
+ * Box types run as the login user the provisioning marker names, or else the
+ * user the outpost runner unit runs as, however the type itself was chosen.
+ */
 function withMarkerUser(result, deps) {
     if (result.type !== "outpost" && result.type !== "agent-box")
         return result;
     const warnings = [];
-    const user = readMarker(deps, warnings)?.user;
+    const user = readMarker(deps, warnings)?.user ?? outpostRunnerUser(deps);
     return withWarnings(user ? { ...result, runAsUser: user } : result, warnings);
 }
 /**
@@ -106,12 +127,11 @@ export function detectMachineType(flag, deps) {
     const warnings = [];
     const marker = readMarker(deps, warnings);
     if (marker) {
-        return {
-            type: marker.type,
-            source: "marker",
-            detail: `from ${MACHINE_TYPE_MARKER_PATH}`,
-            ...(marker.user ? { runAsUser: marker.user } : {}),
-        };
+        return withMarkerUser({ type: marker.type, source: "marker", detail: `from ${MACHINE_TYPE_MARKER_PATH}` }, deps);
+    }
+    // Outposts provisioned before the marker existed still have their runner unit.
+    if (deps.platform === "linux" && deps.existsSync(OUTPOST_RUNNER_UNIT)) {
+        return withWarnings(withMarkerUser({ type: "outpost", source: "outpost-units", detail: `outpost runner at ${OUTPOST_RUNNER_UNIT}` }, deps), warnings);
     }
     const kitCreds = hostAgentCredsPath(deps.home, deps.env);
     if (deps.existsSync(kitCreds)) {

package/dist/lib/daemon/migrate.js

@@ -165,8 +165,8 @@ function moveBack(unit, to) {
         return;
     moveFile(unit.movedTo, to);
 }
-const SYSTEM_UNIT_NAME = /^[A-Za-z0-9@._-]+\.service$/;
-/** A system record entry may only put a .service file back into the system unit folder, from the root-owned store. */
+const SYSTEM_UNIT_NAME = /^[A-Za-z0-9@._-]+\.(service|timer)$/;
+/** A system record entry may only put a .service or .timer file back into the system unit folder, from the root-owned store. */
 function checkSystemEntry(unit, deps) {
     const expectedPath = path.join(deps.systemUnitDir, unit.name);
     const expectedSaved = path.join(deps.systemAdoptedDir, savedName(unit));

package/dist/lib/daemon/remote-control.d.ts

@@ -1,13 +1,19 @@
 /**
- * The `remote-control` service host (`hq daemon service remote-control`).
+ * The remote-control service hosts (`hq daemon service remote-control` and
+ * `codex-remote-control`).
  *
- * Like the outpost runner, `claude remote-control` runs inside a detached tmux
- * session so Claude has a terminal. This host process starts the session and
- * watches it; the daemon supervises the host:
+ * Like the outpost runners, the command (`claude remote-control`, or the box's
+ * Codex runner) runs inside a detached tmux session so it has a terminal. This
+ * host process starts the session and watches it; the daemon supervises the
+ * host:
  *
  * - the session ends -> the host exits 1 and the daemon restarts it with
  *   backoff (replacing the runner's `while true` loop and its watchdogs);
- * - the daemon stops the host -> the host kills the session and exits 0.
+ * - the daemon stops the host -> the host kills the session and exits 0;
+ * - the tool's binary changes on disk (the updater installed a new version) ->
+ *   once the session has been quiet for 10 minutes, or after 2 hours at the
+ *   latest, the host kills the session and exits 0, and the daemon starts it
+ *   again on the new version.
  *
  * The tmux server is a private socket (`-L hq-daemon`), so it never touches a
  * user's own tmux sessions.
@@ -15,16 +21,33 @@
 import type { RunCommand } from "../service-manager/launchd.js";
 export declare const TMUX_SOCKET = "hq-daemon";
 export declare const TMUX_SESSION = "remote-control";
+export declare const CODEX_TMUX_SESSION = "codex-remote-control";
 export declare function remoteControlArgs(opts: {
     name: string;
     permissionMode?: string;
 }): string[];
+/**
+ * The session name a box's own runner script passes to `claude remote-control`
+ * (`--name outpost-1-2`), so taking the runner over keeps the name people see.
+ */
+export declare function runnerSessionName(script: string): string | null;
+/** A tool updated on disk restarts its session once quiet this long... */
+export declare const IDLE_BEFORE_RESTART_MS: number;
+/** ...or after this long, however busy the session is. */
+export declare const MAX_RESTART_WAIT_MS: number;
 export interface RemoteControlHostDeps {
     tmux: string;
-    claude: string;
-    hqRoot: string;
-    name: string;
-    permissionMode?: string;
+    /** tmux session name on the daemon's private socket. */
+    session: string;
+    /** Folder the command starts in (the HQ folder). */
+    cwd: string;
+    /** The command to keep running, binary first. */
+    argv: string[];
+    /** Name used in log lines ("claude remote-control"). */
+    label: string;
+    /** Identity of the tool's binary on disk; a change means it was updated. Null when it cannot be read. */
+    binaryFingerprint: () => string | null;
+    now: () => number;
     run: RunCommand;
     sleep: (ms: number) => Promise<void>;
     pollMs: number;

package/dist/lib/daemon/remote-control.js

@@ -1,46 +1,90 @@
 /**
- * The `remote-control` service host (`hq daemon service remote-control`).
+ * The remote-control service hosts (`hq daemon service remote-control` and
+ * `codex-remote-control`).
  *
- * Like the outpost runner, `claude remote-control` runs inside a detached tmux
- * session so Claude has a terminal. This host process starts the session and
- * watches it; the daemon supervises the host:
+ * Like the outpost runners, the command (`claude remote-control`, or the box's
+ * Codex runner) runs inside a detached tmux session so it has a terminal. This
+ * host process starts the session and watches it; the daemon supervises the
+ * host:
  *
  * - the session ends -> the host exits 1 and the daemon restarts it with
  *   backoff (replacing the runner's `while true` loop and its watchdogs);
- * - the daemon stops the host -> the host kills the session and exits 0.
+ * - the daemon stops the host -> the host kills the session and exits 0;
+ * - the tool's binary changes on disk (the updater installed a new version) ->
+ *   once the session has been quiet for 10 minutes, or after 2 hours at the
+ *   latest, the host kills the session and exits 0, and the daemon starts it
+ *   again on the new version.
  *
  * The tmux server is a private socket (`-L hq-daemon`), so it never touches a
  * user's own tmux sessions.
  */
 export const TMUX_SOCKET = "hq-daemon";
 export const TMUX_SESSION = "remote-control";
+export const CODEX_TMUX_SESSION = "codex-remote-control";
 export function remoteControlArgs(opts) {
     const args = ["remote-control", "--name", opts.name, "--spawn=same-dir"];
     if (opts.permissionMode)
         args.push("--permission-mode", opts.permissionMode);
     return args;
 }
+/**
+ * The session name a box's own runner script passes to `claude remote-control`
+ * (`--name outpost-1-2`), so taking the runner over keeps the name people see.
+ */
+export function runnerSessionName(script) {
+    const m = /remote-control\b[^\n]*?--name[= ]+"?([^\s"]+)"?/.exec(script);
+    return m ? m[1] : null;
+}
+/** A tool updated on disk restarts its session once quiet this long... */
+export const IDLE_BEFORE_RESTART_MS = 10 * 60_000;
+/** ...or after this long, however busy the session is. */
+export const MAX_RESTART_WAIT_MS = 2 * 60 * 60_000;
 export async function runRemoteControlHost(deps) {
     const tmux = (...args) => deps.run(deps.tmux, ["-L", TMUX_SOCKET, ...args]);
-    const killSession = () => tmux("kill-session", "-t", TMUX_SESSION);
+    const killSession = () => tmux("kill-session", "-t", deps.session);
+    /** When the session last printed anything, in ms; null when tmux cannot say. */
+    const lastActivity = () => {
+        const r = tmux("display-message", "-p", "-t", deps.session, "#{window_activity}");
+        const secs = r.status === 0 ? Number.parseInt(r.stdout.trim(), 10) : Number.NaN;
+        return Number.isFinite(secs) ? secs * 1000 : null;
+    };
     // A session left by an earlier host (for example after a crash) is replaced.
     killSession();
-    const started = tmux("new-session", "-d", "-s", TMUX_SESSION, "-x", "200", "-y", "50", "-c", deps.hqRoot, deps.claude, ...remoteControlArgs({ name: deps.name, permissionMode: deps.permissionMode }));
+    const started = tmux("new-session", "-d", "-s", deps.session, "-x", "200", "-y", "50", "-c", deps.cwd, ...deps.argv);
     if (started.status !== 0) {
         deps.log(`could not start the tmux session: ${started.stderr.trim() || `tmux exited ${started.status}`}`);
         return 1;
     }
-    deps.log(`claude remote-control started as "${deps.name}" in ${deps.hqRoot}`);
+    deps.log(`${deps.label} started in ${deps.cwd}`);
+    const startedWith = deps.binaryFingerprint();
+    let updatedAt = null;
     for (;;) {
         if (deps.signal.aborted) {
             killSession();
-            deps.log("stopped remote control");
+            deps.log(`stopped ${deps.label}`);
             return 0;
         }
-        if (tmux("has-session", "-t", TMUX_SESSION).status !== 0) {
-            deps.log("the remote-control session ended");
+        if (tmux("has-session", "-t", deps.session).status !== 0) {
+            deps.log(`the ${deps.label} session ended`);
             return 1;
         }
+        const now = deps.now();
+        if (updatedAt === null) {
+            const current = deps.binaryFingerprint();
+            if (startedWith !== null && current !== null && current !== startedWith) {
+                updatedAt = now;
+                deps.log(`${deps.label}: the tool was updated; restarting onto it once the session is quiet (within 2 hours)`);
+            }
+        }
+        if (updatedAt !== null) {
+            const activity = lastActivity();
+            const quiet = activity !== null && now - activity >= IDLE_BEFORE_RESTART_MS;
+            if (quiet || now - updatedAt >= MAX_RESTART_WAIT_MS) {
+                killSession();
+                deps.log(`${deps.label}: restarting onto the updated tool${quiet ? "" : " (the session stayed busy for 2 hours)"}`);
+                return 0;
+            }
+        }
         await deps.sleep(deps.pollMs);
     }
 }

package/dist/lib/daemon/run.d.ts

@@ -25,6 +25,12 @@ export declare function windowsTaskExists(taskName: string): boolean;
 export declare function probeLegacyUnits(platform: NodeJS.Platform, home: string): LegacyUnit[];
 /** Absolute path of `name` on PATH, or null. */
 export declare function findOnPath(name: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * A tool the login user installed (~/.local/bin, ~/.npm-global/bin,
+ * ~/.grok/bin) before anything on PATH, so a box runs and updates the user's
+ * own copy instead of one root installed under /usr.
+ */
+export declare function findUserBinary(name: string, env: NodeJS.ProcessEnv, home: string): string | null;
 /** This CLI is a global package install the updater can replace (not a dev checkout or a project dependency). */
 export declare function cliSelfUpdatable(): boolean;
 /** The HQ desktop app process is running here (it runs its own sync). */