@indigoai-us/hq-cli 5.304.0 → 5.306.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [5.306.0] — 2026-10-01
+- End long install-tree waits early when a named retired npm sibling's deep activity scan is incomplete, report the recovery as unverified, and give safe wait-and-repair guidance.
+
+## [5.305.0] — 2026-10-01
+
+- Work Mesh project discovery skips projects whose matching local lifecycle state is archived or retired.
+
+- `hq lanes show` now treats a newer terminal primary mirror as authoritative when an Outpost owner snapshot is behind, avoiding a misleading refresh warning while preserving warnings for nonterminal conflicts.
+- Self-updates detect an unwritable npm global prefix before install, show the command to repair that install, and report the handled permission state as a rate-limited warning.
+- Keep Work Mesh held events unique by event ID across retries, including interrupted overflow recovery.
+- Added `hq mcp list` as an alias for the existing MCP status command. `hq version` can show cached CLI update guidance on stderr when the default-off `cli.version-update-nudge` flag is enabled. Bare `hq --version` prints only the installed CLI semver and starts no flag or network work.
+- Keep-alive no longer lets a newer terminal lane or a same-profile lane under a distinct lane senior supersede a running lane.
+- With `cli.company-errors-sdk-warning` enabled, `hq people` uses shared active-company guidance when local metadata is missing, and files commands show the AWS SDK Node-version notice only with verbose diagnostics.
+- Remove the unrelated secret-sharing hint from active member listings.
+
 ## [5.304.0] — 2026-10-01
 - `hq lanes show` skips owner refresh only when a failed Outpost dispatch explicitly recorded `pickup_persisted: false` and no owner heartbeat; it reports `remote_refresh: "skipped_undispatched"` in that case.
 
@@ -46,6 +61,7 @@
 
 ## [5.300.0] — 2026-09-30
 - `hq files unshare --with agt_...` removes a grant made to an agent. Before, agent uids were rejected as invalid principals.
+- `hq daemon` no longer drops remote-control sessions when claude or codex is reinstalled at the same version or when hq-cli is released. The daemon's plan leaves out the tool's path (the host finds it when it starts), the host restarts a session only for a new tool version, and a tool that looks missing for one plan read does not pause the session. On outpost primary, a long-running Claude session's auto-updater reinstalled claude every few minutes and each reinstall restarted remote-control two or three times.
 - With the default-off hq-flags gate `files.share-empty-prefix-warning`, `hq files share` warns when a granted prefix has no files. A failed or timed-out list check does not block the grant.
 - Recognize pnpm v11+ global installs and handle Windows drive-path tar archives without waiting for the asynchronous feature-flag snapshot.
 - Self-update failure reports now include the npm error code and a sanitized reason.

package/dist/command-catalog.generated.d.ts

@@ -3622,7 +3622,7 @@ export declare const COMMAND_CATALOG: readonly [{
     readonly subcommands: readonly [{
         readonly name: "status";
         readonly description: "Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)";
-        readonly aliases: readonly [];
+        readonly aliases: readonly ["list"];
         readonly hidden: false;
         readonly usage: "[options]";
         readonly arguments: readonly [];
@@ -9664,7 +9664,7 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly arguments: readonly [];
             readonly options: readonly [{
                 readonly flags: "--claude <path>";
-                readonly description: "claude binary";
+                readonly description: "claude binary (default: the one installed for this user)";
             }, {
                 readonly flags: "--name <name>";
                 readonly description: "remote-control session name";
@@ -9685,7 +9685,7 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "the box's Codex runner script";
             }, {
                 readonly flags: "--codex <path>";
-                readonly description: "codex binary, watched for updates";
+                readonly description: "codex binary, watched for updates (default: the one installed for this user)";
             }];
             readonly subcommands: readonly [];
         }];

package/dist/command-catalog.generated.js

@@ -4674,7 +4674,9 @@ export const COMMAND_CATALOG = [
             {
                 "name": "status",
                 "description": "Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)",
-                "aliases": [],
+                "aliases": [
+                    "list"
+                ],
                 "hidden": false,
                 "usage": "[options]",
                 "arguments": [],
@@ -12455,7 +12457,7 @@ export const COMMAND_CATALOG = [
                         "options": [
                             {
                                 "flags": "--claude <path>",
-                                "description": "claude binary"
+                                "description": "claude binary (default: the one installed for this user)"
                             },
                             {
                                 "flags": "--name <name>",
@@ -12482,7 +12484,7 @@ export const COMMAND_CATALOG = [
                             },
                             {
                                 "flags": "--codex <path>",
-                                "description": "codex binary, watched for updates"
+                                "description": "codex binary, watched for updates (default: the one installed for this user)"
                             }
                         ],
                         "subcommands": []

package/dist/command-registration-plan.js

@@ -85,6 +85,7 @@ export const REGISTRATION_PLAN = [
 ];
 async function executePlan(program, steps) {
     const parents = new Map([["program", program]]);
+    let filesRuntimeConfigured = false;
     for (const step of steps) {
         if (step.type === "group") {
             const group = program.command(step.name, step.hidden ? { hidden: true } : {});
@@ -94,6 +95,13 @@ async function executePlan(program, steps) {
         const parent = parents.get(step.parent);
         if (!parent)
             throw new Error(`Missing command parent '${step.parent}' for '${step.exportName}'`);
+        if (step.root === "files" && !filesRuntimeConfigured) {
+            // The SDK emits its Node support notice during module evaluation. Set
+            // its narrow suppression switch before loading any files command module.
+            const { configureAwsSdkNodeVersionWarningOutput } = await import("./lib/aws-sdk-node-warning-output.js");
+            configureAwsSdkNodeVersionWarningOutput();
+            filesRuntimeConfigured = true;
+        }
         const imported = await import(step.module);
         const register = imported[step.exportName];
         if (!register)

package/dist/commands/daemon.js

@@ -627,25 +627,9 @@ async function runServiceSelfUpdate(d) {
     if (!result.ok)
         process.exitCode = 1;
 }
-/** Size, mtime and real path of a binary: changes whenever a new version is installed over it. */
-function binaryFingerprint(bin) {
-    try {
-        const real = fs.realpathSync(bin);
-        const st = fs.statSync(real);
-        return `${real}:${st.size}:${st.mtimeMs}`;
-    }
-    catch {
-        return null;
-    }
-}
 async function runTmuxService(d, opts) {
-    const { installFingerprint, runRemoteControlHost } = await import("../lib/daemon/remote-control.js");
+    const { runRemoteControlHost, toolFingerprint } = await import("../lib/daemon/remote-control.js");
     const { findOnPath } = await import("../lib/daemon/run.js");
-    const { resolveRunningInstall } = await import("../utils/version-gate.js");
-    // The daemon keeps this host running across a CLI update, so a new hq-cli
-    // install also counts as an update and restarts the session once it is quiet.
-    const cliRoot = resolveRunningInstall().packageRoot;
-    const watched = cliRoot ? [opts.watch, path.join(cliRoot, "package.json")] : [opts.watch];
     const hqRoot = d.env.HQ_ROOT?.trim();
     if (!hqRoot)
         throw new DaemonCommandError(`${opts.label} needs HQ_ROOT (the daemon sets it from the saved HQ folder)`);
@@ -663,7 +647,9 @@ async function runTmuxService(d, opts) {
             cwd: hqRoot,
             argv: opts.argv,
             label: opts.label,
-            binaryFingerprint: () => installFingerprint(watched, binaryFingerprint),
+            // Only a new version of the tool restarts the session: not a same-version
+            // reinstall, and not an hq-cli release (the host's own code rarely matters).
+            binaryFingerprint: () => toolFingerprint(opts.watch),
             now: () => Date.now(),
             run: d.run,
             pollMs: 5_000,
@@ -683,22 +669,37 @@ async function runTmuxService(d, opts) {
         process.off("SIGINT", stop);
     }
 }
+/** The claude or codex a remote-control host runs: --claude/--codex, else the one installed now. */
+async function hostTool(d, name, given) {
+    const [{ serviceTool }, { findUserBinary }] = await Promise.all([
+        import("../lib/daemon/remote-control.js"),
+        import("../lib/daemon/run.js"),
+    ]);
+    try {
+        return serviceTool(name, given, (tool) => findUserBinary(tool, d.env, d.home));
+    }
+    catch (err) {
+        throw new DaemonCommandError(err.message);
+    }
+}
 async function runServiceRemoteControl(d, opts) {
     const { TMUX_SESSION, remoteControlArgs } = await import("../lib/daemon/remote-control.js");
+    const claude = await hostTool(d, "claude", opts.claude);
     await runTmuxService(d, {
         session: TMUX_SESSION,
-        argv: [opts.claude, ...remoteControlArgs({ name: opts.name, permissionMode: opts.permissionMode })],
+        argv: [claude, ...remoteControlArgs({ name: opts.name, permissionMode: opts.permissionMode })],
         label: "claude remote-control",
-        watch: opts.claude,
+        watch: claude,
     });
 }
 async function runServiceCodexRemoteControl(d, opts) {
     const { CODEX_TMUX_SESSION } = await import("../lib/daemon/remote-control.js");
+    const codex = await hostTool(d, "codex", opts.codex);
     await runTmuxService(d, {
         session: CODEX_TMUX_SESSION,
         argv: ["bash", opts.script],
         label: "codex remote-control",
-        watch: opts.codex,
+        watch: codex,
     });
 }
 export function registerDaemonCommand(program, over = {}) {
@@ -839,7 +840,7 @@ export function registerDaemonCommand(program, over = {}) {
     service
         .command("remote-control")
         .description("Keep `claude remote-control` running in a tmux session in the HQ folder")
-        .requiredOption("--claude <path>", "claude binary")
+        .option("--claude <path>", "claude binary (default: the one installed for this user)")
         .requiredOption("--name <name>", "remote-control session name")
         .option("--permission-mode <mode>", "claude --permission-mode")
         .action(wrap((d, opts) => runServiceRemoteControl(d, opts)));
@@ -847,7 +848,7 @@ export function registerDaemonCommand(program, over = {}) {
         .command("codex-remote-control")
         .description("Keep the box's Codex remote-control runner going in a tmux session, restarting it after a Codex update")
         .requiredOption("--script <path>", "the box's Codex runner script")
-        .requiredOption("--codex <path>", "codex binary, watched for updates")
+        .option("--codex <path>", "codex binary, watched for updates (default: the one installed for this user)")
         .action(wrap((d, opts) => runServiceCodexRemoteControl(d, opts)));
     return daemon;
 }

package/dist/commands/lanes.js

@@ -5065,6 +5065,19 @@ async function refreshOutpostLaneCopiesForShow(ctx, lane, localLanes) {
             return syncLaneRecordFromOwner(ctx.hqRoot(), laneId, outpostId, ownerLane, undefined, { allowNonTerminal: true });
         }
         catch (err) {
+            if (isLanesError(err) && err.error === "outpost_lane_sync_conflict") {
+                const ownerVersion = err.details.owner_version;
+                const primaryVersion = err.details.primary_version;
+                if (typeof ownerVersion === "number" &&
+                    typeof primaryVersion === "number" &&
+                    ownerVersion < primaryVersion) {
+                    const currentPrimary = readLane(ctx.hqRoot(), laneId);
+                    if (currentPrimary.version === primaryVersion &&
+                        isTerminalLaneState(currentPrimary.state)) {
+                        return currentPrimary;
+                    }
+                }
+            }
             const detail = isLanesError(err)
                 ? `${err.error}: ${err.message}`
                 : `outpost_lane_sync_unavailable: ${dispatchErrorMessage(err)}`;

package/dist/commands/mcp-status.js

@@ -374,6 +374,7 @@ export function registerMcpCommand(program) {
         .description('MCP pack observability (read-only) across Claude + Codex');
     mcp
         .command('status')
+        .alias('list')
         .description('Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)')
         .option('--json', 'Emit the structured report as JSON (for CI / scripting)')
         .action((opts) => {

package/dist/commands/members.js

@@ -672,7 +672,6 @@ export function registerMembersCommand(program) {
                 const name = m.personName ?? m.personSlug ?? "";
                 console.log([email.padEnd(emailW), m.role.padEnd(roleW), name].join("  "));
             }
-            console.log(chalk.gray("Share a secret with a member: hq secrets share <path> --with <email>"));
         }
         catch (err) {
             if (err instanceof InviteHttpError) {

package/dist/commands/people.d.ts

@@ -17,6 +17,9 @@ import { resolveNameToEmail, type PersonRecord } from "../utils/people.js";
 export type FetchPeopleRoster = (hqRoot: string, companySlug: string) => Promise<PersonRecord[]>;
 interface PeopleCommandDeps {
     fetchRoster?: FetchPeopleRoster;
+    /** Test seam for the shared active-membership ambiguity resolver. */
+    resolveMissingManifestMemberships?: () => Promise<void>;
+    companySelectionGuidanceEnabled?: () => boolean;
 }
 interface PeopleLookupOpts {
     localOnly?: boolean;

package/dist/commands/people.js

@@ -19,6 +19,7 @@ import { findHqRoot } from "../utils/manifest.js";
 import { manifestPath } from "./cloud-provision.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { getCompanyUid } from "../utils/vault-api.js";
+import { companyErrorsSdkWarningEnabled } from "../lib/company-errors-sdk-warning-flag.js";
 import { listActiveMembers } from "./members.js";
 import { assertSafeCompanySlug, listCompanyPeople, searchPeople, resolveNameToEmail, companyPeopleDir, } from "../utils/people.js";
 function slugify(value) {
@@ -108,6 +109,29 @@ export function resolveCompanySlug(hqRoot, explicit) {
     throw new Error("Multiple companies found — re-run with --company <slug> to pick one:\n" +
         slugs.map((s) => `  --company ${s}`).join("\n"));
 }
+async function resolvePeopleCompanySlug(hqRoot, explicit, localOnly, deps) {
+    try {
+        return resolveCompanySlug(hqRoot, explicit);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const ambiguous = message.includes("companies/manifest.yaml not found") ||
+            message.startsWith("Multiple companies found");
+        const enabled = (deps.companySelectionGuidanceEnabled ?? companyErrorsSdkWarningEnabled)();
+        if (!explicit && !localOnly && enabled && ambiguous) {
+            const resolveMemberships = deps.resolveMissingManifestMemberships ??
+                (async () => {
+                    const token = await ensureCognitoToken();
+                    await getCompanyUid(token, undefined);
+                });
+            // The shared resolver throws members-style guidance for multiple active
+            // companies. A single membership cannot provide a local slug without a
+            // manifest, so preserve the existing missing-manifest error in that case.
+            await resolveMemberships();
+        }
+        throw error;
+    }
+}
 /** Resolve the HQ root: explicit override (tests) → cwd walk-up. */
 function resolveHqRoot(opts) {
     return opts.hqRoot ?? findHqRoot();
@@ -192,7 +216,7 @@ export function registerPeopleCommand(program, deps = {}) {
         try {
             const scope = people.opts();
             const hqRoot = resolveHqRoot(scope);
-            const slug = resolveCompanySlug(hqRoot, scope.company);
+            const slug = await resolvePeopleCompanySlug(hqRoot, scope.company, opts.localOnly, deps);
             let records = listCompanyPeople(hqRoot, slug);
             if (!opts.localOnly) {
                 const roster = await tryFetchRoster(deps.fetchRoster ?? fetchMembershipRoster, hqRoot, slug);
@@ -223,7 +247,7 @@ export function registerPeopleCommand(program, deps = {}) {
         try {
             const scope = people.opts();
             const hqRoot = resolveHqRoot(scope);
-            const slug = resolveCompanySlug(hqRoot, scope.company);
+            const slug = await resolvePeopleCompanySlug(hqRoot, scope.company, opts.localOnly, deps);
             const matches = await searchPeopleWithRosterFallback({
                 hqRoot,
                 slug,
@@ -255,7 +279,7 @@ export function registerPeopleCommand(program, deps = {}) {
         try {
             const scope = people.opts();
             const hqRoot = resolveHqRoot(scope);
-            const slug = resolveCompanySlug(hqRoot, scope.company);
+            const slug = await resolvePeopleCompanySlug(hqRoot, scope.company, opts.localOnly, deps);
             const result = await resolvePersonWithRosterFallback({
                 hqRoot,
                 slug,

package/dist/index.js

@@ -22,9 +22,14 @@ if (isVersionRequest(process.argv)) {
     // compare). `hq version` and `--json` print the labelled HQ/CLI report.
     // Lazy so this path still skips the command graph.
     if (wantsLabelledVersionReport(process.argv)) {
-        void import("./utils/version-report.js").then(({ runVersionCommand }) => runVersionCommand(process.argv));
+        void import("./lib/flag-registry.js").then(({ kickFlagRegistryReadiness }) => {
+            kickFlagRegistryReadiness();
+            return import("./utils/version-report.js").then(({ runVersionCommand }) => runVersionCommand(process.argv));
+        });
     }
     else {
+        // Keep the benchmarked updater fast route limited to the installed semver.
+        // Registry checks and flag resolution belong to the regular command path.
         void import("./cli-version.js").then(({ CLI_VERSION }) => {
             process.stdout.write(`${CLI_VERSION}\n`);
         });

package/dist/lazy-commands.js

@@ -55,8 +55,11 @@ function commandForToken(token) {
  * preserve the complete help and unknown-command recovery surfaces.
  */
 export function findLazyCommand(argv) {
-    const first = argv[2];
-    const token = first === "help" ? argv[3] : first;
+    let commandIndex = 2;
+    while (argv[commandIndex] === "--verbose")
+        commandIndex += 1;
+    const first = argv[commandIndex];
+    const token = first === "help" ? argv[commandIndex + 1] : first;
     if (typeof token !== "string" || token.startsWith("-"))
         return null;
     const command = commandForToken(token);

package/dist/lib/aws-sdk-node-warning-output.d.ts

@@ -0,0 +1,12 @@
+export declare const AWS_SDK_NODE_VERSION_WARNING_ENV = "AWS_SDK_JS_NODE_VERSION_SUPPORT_WARNING_DISABLED";
+export interface AwsSdkWarningOutputOptions {
+    argv?: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    enabled?: boolean;
+}
+/**
+ * Configure the AWS SDK's documented, warning-specific switch before loading
+ * the files command and its SDK clients. No other SDK warnings are affected.
+ */
+export declare function configureAwsSdkNodeVersionWarningOutput(options?: AwsSdkWarningOutputOptions): void;
+//# sourceMappingURL=aws-sdk-node-warning-output.d.ts.map

package/dist/lib/aws-sdk-node-warning-output.js

@@ -0,0 +1,22 @@
+import { companyErrorsSdkWarningEnabled } from "./company-errors-sdk-warning-flag.js";
+export const AWS_SDK_NODE_VERSION_WARNING_ENV = "AWS_SDK_JS_NODE_VERSION_SUPPORT_WARNING_DISABLED";
+/**
+ * Configure the AWS SDK's documented, warning-specific switch before loading
+ * the files command and its SDK clients. No other SDK warnings are affected.
+ */
+export function configureAwsSdkNodeVersionWarningOutput(options = {}) {
+    const env = options.env ?? process.env;
+    const argv = options.argv ?? process.argv;
+    const enabled = options.enabled ?? companyErrorsSdkWarningEnabled();
+    if (!enabled)
+        return;
+    const verbose = argv.includes("--verbose");
+    const debug = /^(1|true|yes)$/i.test(env.HQ_DEBUG?.trim() ?? "");
+    if (verbose || debug) {
+        delete env[AWS_SDK_NODE_VERSION_WARNING_ENV];
+    }
+    else {
+        env[AWS_SDK_NODE_VERSION_WARNING_ENV] = "true";
+    }
+}
+//# sourceMappingURL=aws-sdk-node-warning-output.js.map

package/dist/lib/company-errors-sdk-warning-flag.d.ts

@@ -0,0 +1,5 @@
+export declare const COMPANY_ERRORS_SDK_WARNING_FLAG = "cli.company-errors-sdk-warning";
+export declare const COMPANY_ERRORS_SDK_WARNING_FALLBACK = false;
+/** One default-off rollout gate for the two US-163 CLI compatibility fixes. */
+export declare function companyErrorsSdkWarningEnabled(): boolean;
+//# sourceMappingURL=company-errors-sdk-warning-flag.d.ts.map

package/dist/lib/company-errors-sdk-warning-flag.js

@@ -0,0 +1,8 @@
+import { resolveProcessFlagGate } from "./flag-registry.js";
+export const COMPANY_ERRORS_SDK_WARNING_FLAG = "cli.company-errors-sdk-warning";
+export const COMPANY_ERRORS_SDK_WARNING_FALLBACK = false;
+/** One default-off rollout gate for the two US-163 CLI compatibility fixes. */
+export function companyErrorsSdkWarningEnabled() {
+    return resolveProcessFlagGate(COMPANY_ERRORS_SDK_WARNING_FLAG, {}, () => COMPANY_ERRORS_SDK_WARNING_FALLBACK);
+}
+//# sourceMappingURL=company-errors-sdk-warning-flag.js.map

package/dist/lib/daemon/catalog.js

@@ -283,7 +283,9 @@ function planService(service, ctx) {
                 base(service, {
                     command: {
                         type: "hq",
-                        args: ["daemon", "service", "codex-remote-control", "--script", script ?? "", "--codex", ctx.codexPath ?? ""],
+                        // No codex path: the host finds codex itself, so a reinstall that
+                        // briefly moves the link cannot change the plan and restart it.
+                        args: ["daemon", "service", "codex-remote-control", "--script", script ?? ""],
                     },
                     // Restarting the host ends the tmux session people are using.
                     keepAcrossCliUpdates: true,
@@ -303,7 +305,9 @@ function planService(service, ctx) {
             // Outposts keep the runner's session name and permission mode.
             const outpost = ctx.machineType === "outpost";
             const name = ctx.remoteControlName ?? (outpost ? "outpost-1" : ctx.hostName);
-            const args = ["daemon", "service", "remote-control", "--claude", ctx.claudePath ?? "", "--name", name];
+            // No claude path: the host finds claude itself, so a reinstall that
+            // briefly moves the link cannot change the plan and restart the session.
+            const args = ["daemon", "service", "remote-control", "--name", name];
             if (outpost)
                 args.push("--permission-mode", "bypassPermissions");
             return [

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

@@ -10,10 +10,12 @@
  * - 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 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.
+ * - a new version of the tool is installed (the updater, or the tool's own
+ *   auto-updater) -> 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. Reinstalling the same version
+ *   (a long-running Claude session's auto-updater does that every few
+ *   minutes) and hq-cli releases leave the session alone.
  *
  * The tmux server is a private socket (`-L hq-daemon`), so it never touches a
  * user's own tmux sessions.
@@ -32,11 +34,20 @@ export declare function remoteControlArgs(opts: {
  */
 export declare function runnerSessionName(script: string): string | null;
 /**
- * Fingerprint of what a host runs: the tool first, then other installs it
- * depends on (the hq-cli package). Null while the tool cannot be read; an
- * unreadable extra install is left out rather than hiding a tool update.
+ * Which version of a tool is installed: the npm package that installs the
+ * binary (`name@version`), else the binary's real path and size. A native
+ * install's link points at a versioned file, so its real path is the version.
+ * The mtime is left out on purpose: reinstalling the same version rewrites
+ * the file, and that must not restart the session. Null while the tool
+ * cannot be read.
  */
-export declare function installFingerprint(paths: readonly string[], fingerprint: (file: string) => string | null): string | null;
+export declare function toolFingerprint(bin: string): string | null;
+/**
+ * The tool a host runs: the path it was given, else the one found now. The
+ * daemon's plan leaves the path out, so a reinstall that briefly removes the
+ * tool's link cannot change the plan and restart the session.
+ */
+export declare function serviceTool(name: string, given: string | undefined, find: (name: string) => string | null): string;
 /** 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. */

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

@@ -10,14 +10,18 @@
  * - 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 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.
+ * - a new version of the tool is installed (the updater, or the tool's own
+ *   auto-updater) -> 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. Reinstalling the same version
+ *   (a long-running Claude session's auto-updater does that every few
+ *   minutes) and hq-cli releases leave the session alone.
  *
  * The tmux server is a private socket (`-L hq-daemon`), so it never touches a
  * user's own tmux sessions.
  */
+import * as fs from "node:fs";
+import * as path from "node:path";
 export const TMUX_SOCKET = "hq-daemon";
 export const TMUX_SESSION = "remote-control";
 export const CODEX_TMUX_SESSION = "codex-remote-control";
@@ -35,17 +39,63 @@ export function runnerSessionName(script) {
     const m = /remote-control\b[^\n]*?--name[= ]+"?([^\s"]+)"?/.exec(script);
     return m ? m[1] : null;
 }
+/** How far above the binary to look for the package that installs it (bin/claude.exe sits one level down). */
+const PACKAGE_SEARCH_DEPTH = 3;
 /**
- * Fingerprint of what a host runs: the tool first, then other installs it
- * depends on (the hq-cli package). Null while the tool cannot be read; an
- * unreadable extra install is left out rather than hiding a tool update.
+ * Which version of a tool is installed: the npm package that installs the
+ * binary (`name@version`), else the binary's real path and size. A native
+ * install's link points at a versioned file, so its real path is the version.
+ * The mtime is left out on purpose: reinstalling the same version rewrites
+ * the file, and that must not restart the session. Null while the tool
+ * cannot be read.
  */
-export function installFingerprint(paths, fingerprint) {
-    const [tool, ...rest] = paths;
-    const toolFp = tool === undefined ? null : fingerprint(tool);
-    if (toolFp === null)
+export function toolFingerprint(bin) {
+    let real;
+    let size;
+    try {
+        real = fs.realpathSync(bin);
+        size = fs.statSync(real).size;
+    }
+    catch {
+        return null;
+    }
+    let dir = path.dirname(real);
+    for (let i = 0; i < PACKAGE_SEARCH_DEPTH; i++) {
+        const version = packageVersionFor(dir, real);
+        if (version)
+            return version;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return `${real}:${size}`;
+}
+/** `name@version` when `<dir>/package.json` declares `real` as one of its bins. */
+function packageVersionFor(dir, real) {
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    }
+    catch {
         return null;
-    return [toolFp, ...rest.map(fingerprint).filter((fp) => fp !== null)].join("|");
+    }
+    if (typeof pkg.name !== "string" || typeof pkg.version !== "string")
+        return null;
+    const bins = typeof pkg.bin === "string" ? [pkg.bin] : pkg.bin && typeof pkg.bin === "object" ? Object.values(pkg.bin) : [];
+    const installs = bins.some((b) => typeof b === "string" && path.resolve(dir, b) === real);
+    return installs ? `${pkg.name}@${pkg.version}` : null;
+}
+/**
+ * The tool a host runs: the path it was given, else the one found now. The
+ * daemon's plan leaves the path out, so a reinstall that briefly removes the
+ * tool's link cannot change the plan and restart the session.
+ */
+export function serviceTool(name, given, find) {
+    const tool = given?.trim() || find(name);
+    if (!tool)
+        throw new Error(`the ${name} CLI is not installed`);
+    return tool;
 }
 /** A tool updated on disk restarts its session once quiet this long... */
 export const IDLE_BEFORE_RESTART_MS = 10 * 60_000;

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

@@ -123,6 +123,8 @@ export interface Supervisor {
     /** Stop supervising without signalling any child; returns the long-running units left running. */
     release(): ReleasedUnit[];
 }
+/** Plan reads in a row that must find a running remote-control host blocked before it is paused. */
+export declare const BLOCKED_READS_BEFORE_PAUSE = 2;
 export declare function backoffMs(attempt: number): number;
 /**
  * What a unit's process was started from; a unit whose key changes is

package/dist/lib/daemon/supervisor.js

@@ -33,6 +33,8 @@ const MESH_OWNER_LOG_INTERVAL_MS = 10 * 60_000;
 export const HANDOFF_STAGGER_MS = 15_000;
 /** How long a draining unit may take to finish its work before it gets SIGTERM. */
 export const HANDOFF_DRAIN_MAX_MS = 15 * 60_000;
+/** Plan reads in a row that must find a running remote-control host blocked before it is paused. */
+export const BLOCKED_READS_BEFORE_PAUSE = 2;
 export function backoffMs(attempt) {
     return Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** Math.max(0, attempt));
 }
@@ -505,6 +507,15 @@ export function createSupervisor(deps) {
                 continue;
             }
             next.set(plan.id, existing);
+            // A remote-control host is what people's sessions run in. Its tool can
+            // look missing for one plan read while it is being reinstalled, so it is
+            // only paused once the tool is missing on two reads in a row.
+            if (plan.blocked && existing.plan.blocked === undefined && existing.child && plan.keepAcrossCliUpdates) {
+                existing.blockedReads = (existing.blockedReads ?? 0) + 1;
+                if (existing.blockedReads < BLOCKED_READS_BEFORE_PAUSE)
+                    continue;
+            }
+            existing.blockedReads = 0;
             const adopted = existing.adopted === true;
             existing.adopted = false;
             const key = planKey(plan, deps.cliVersion);

package/dist/lib/doctor/checks/work-context.js

@@ -10,7 +10,7 @@ import { readDeviceConfig, } from "../../work-context/config.js";
 import { outboxStats, listOutboxOperations } from "../../work-context/outbox.js";
 import { outboxQuarantineStatusEnabled } from "../../work-context/outbox-quarantine-status-flag.js";
 import { workContextRoot, workContextSessionsDir } from "../../work-context/paths.js";
-import { countJsonlLines, deadLetterNonEmpty, } from "../../mesh/live/spool.js";
+import { countDistinctHeldEvents, countJsonlLines, deadLetterNonEmpty, } from "../../mesh/live/spool.js";
 import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../../mesh/live/paths.js";
 import { collectDaemonDoctor, formatDaemonDoctor, } from "../../mesh/live/daemon/doctor.js";
 export const WORK_CONTEXT_FAMILY_ID = "work-context";
@@ -139,7 +139,7 @@ function runChecks(deps) {
     const heldPath = workMeshHeldPath(meshRoot);
     const deadLetterPath = workMeshDeadLetterPath(meshRoot);
     const spoolDepth = countJsonlLines(spoolPath);
-    const heldDepth = countJsonlLines(heldPath);
+    const heldDepth = countDistinctHeldEvents(heldPath);
     results.push({
         status: "PASS",
         checkId: "work-context.spool-depth",