@indigoai-us/hq-cli 5.319.0 → 5.320.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [5.320.0] — 2026-10-02
+- Write session-journal titles as escaped YAML strings so free-form titles remain parseable.
+- Added a default-off hq-flags gate that lets lane list pollers skip remote owner refreshes to reduce poll latency.
+- Publish per-process package-use leases so Desktop updates can wait for active hq-cli work without native locks.
+
 ## [5.319.0] — 2026-10-02
 - Let `hq access` use ACL-checked company presigned reads when STS vend rejects a truncated write-policy scope.
 - Lead autopilot on an Outpost can wake leads that were created on that Outpost, behind the default-off `lanes.autopilot-outpost-native-leads` flag. Before, those leads were skipped as a host mismatch and got no wakes.

package/assets/scaffold/core/scripts/session-journal.sh

@@ -43,6 +43,41 @@ slugify() {
     | cut -c1-40
 }
 
+yaml_double_quoted() {
+  local value="$1" output='"' character next codepoint hex
+  local LC_ALL=C index
+  for ((index = 0; index < ${#value}; index++)); do
+    character="${value:index:1}"
+    if [[ "$character" == $'\xc2' ]] && (( index + 1 < ${#value} )); then
+      next="${value:index+1:1}"
+      printf -v codepoint '%d' "'${next}"
+      if (( codepoint >= 128 && codepoint <= 159 )); then
+        printf -v hex '%04x' "$codepoint"
+        output+="\\u$hex"
+        index=$((index + 1))
+        continue
+      fi
+    fi
+    case "$character" in
+      \\) output+='\\' ;;
+      '"') output+='\"' ;;
+      $'\n') output+='\n' ;;
+      $'\r') output+='\r' ;;
+      $'\t') output+='\t' ;;
+      *)
+        if [[ "$character" == [[:cntrl:]] ]]; then
+          printf -v codepoint '%d' "'${character}"
+          printf -v hex '%02x' "$codepoint"
+          output+="\\x$hex"
+        else
+          output+="$character"
+        fi
+        ;;
+    esac
+  done
+  printf '%s"' "$output"
+}
+
 # Counters are per-session. A date-global counter lets concurrent Claude and
 # Codex tasks trip (and reset) each other's journal reminders.
 counter_key() {
@@ -140,6 +175,9 @@ case "$cmd" in
 
     slug="$(slugify "$title")"
     [ -z "$slug" ] && slug="entry"
+    yaml_title="$(yaml_double_quoted "$title")"
+    yaml_slug="$slug"
+    [[ "$slug" != *$'\n'* ]] || yaml_slug="$(yaml_double_quoted "$slug")"
     JOURNAL_WRITE_LOCK=""
     acquire_journal_write_lock "$dir" || { warn "write: failed to acquire journal lock"; exit 0; }
     trap release_journal_write_lock EXIT
@@ -161,8 +199,8 @@ case "$cmd" in
         {
           printf -- '---\n'
           printf 'ts: %s\n' "$(now_iso_z)"
-          printf 'title: %s\n' "$title"
-          printf 'slug: %s\n' "$slug"
+          printf 'title: %s\n' "$yaml_title"
+          printf 'slug: %s\n' "$yaml_slug"
           if [ -n "$files_csv" ]; then
             printf 'files:\n'
             old_ifs="$IFS"

package/dist/bin/hq-auth-refresh.d.ts

@@ -11,7 +11,9 @@
  * non-interactively.
  */
 import "../node-preflight.js";
+import { acquireCurrentPackageUseLease } from "../utils/package-use-lease.js";
 import "../node-network-compat.js";
-import { refreshCachedSession } from "../utils/cognito-session.js";
+import type { refreshCachedSession } from "../utils/cognito-session.js";
 export declare function runAuthRefresh(refreshSession?: typeof refreshCachedSession): Promise<number>;
+export declare function startAuthRefresh(acquireLease?: typeof acquireCurrentPackageUseLease): Promise<number>;
 //# sourceMappingURL=hq-auth-refresh.d.ts.map

package/dist/bin/hq-auth-refresh.js

@@ -13,15 +13,16 @@
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "../node-preflight.js";
+import { acquireCurrentPackageUseLease } from "../utils/package-use-lease.js";
 import "../node-network-compat.js";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
-import { finishSentrySession, initSentry, Sentry } from "../sentry.js";
-import { refreshCachedSession } from "../utils/cognito-session.js";
-export async function runAuthRefresh(refreshSession = refreshCachedSession) {
+export async function runAuthRefresh(refreshSession) {
+    const { finishSentrySession, Sentry } = await import("../sentry.js");
+    const { refreshCachedSession: refresh } = await import("../utils/cognito-session.js");
     let exitCode = 1;
     try {
-        const result = await refreshSession();
+        const result = await (refreshSession ?? refresh)();
         if (result.refreshed) {
             exitCode = 0;
         }
@@ -41,8 +42,42 @@ export async function runAuthRefresh(refreshSession = refreshCachedSession) {
     }
     return exitCode;
 }
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+function isPackageUseUpdatePendingError(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        error.name === "PackageUseUpdatePendingError");
+}
+function packageUseErrorClass(error) {
+    if (!error || typeof error !== "object")
+        return "unknown";
+    const value = error;
+    if (typeof value.code === "string")
+        return value.code;
+    if (value.cause && typeof value.cause === "object") {
+        const cause = value.cause;
+        if (typeof cause.code === "string")
+            return cause.code;
+        if (typeof cause.name === "string")
+            return cause.name;
+    }
+    return typeof value.name === "string" ? value.name : "unknown";
+}
+export async function startAuthRefresh(acquireLease = acquireCurrentPackageUseLease) {
+    try {
+        acquireLease();
+    }
+    catch (error) {
+        if (isPackageUseUpdatePendingError(error)) {
+            process.stderr.write(`hq-auth-refresh: ${error instanceof Error ? error.message : "The HQ CLI package is being updated"}\n`);
+            return 1;
+        }
+        process.stderr.write(`hq-auth-refresh: package-use lease unavailable (${packageUseErrorClass(error)}); continuing without lease\n`);
+    }
+    const { initSentry } = await import("../sentry.js");
     initSentry();
-    void runAuthRefresh().then((exitCode) => process.exit(exitCode));
+    return runAuthRefresh();
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    void startAuthRefresh().then((exitCode) => process.exit(exitCode));
 }
 //# sourceMappingURL=hq-auth-refresh.js.map

package/dist/commands/core-session-journal-native.js

@@ -24,7 +24,35 @@ const counterKey = (value) => {
     return key.length > 96 ? key.slice(0, 96) : key;
 };
 const slugify = (value) => value.toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-").replace(/^-+/, "").replace(/-+$/, "").slice(0, 40);
+    .split("\n")
+    .map((line) => line.replace(/[^a-z0-9]+/g, "-").replace(/^-+/, "").replace(/-+$/, "").slice(0, 40))
+    .join("\n");
+function yamlDoubleQuoted(value) {
+    let escaped = "";
+    for (const character of value) {
+        const codePoint = character.codePointAt(0) ?? 0;
+        if (character === "\\")
+            escaped += "\\\\";
+        else if (character === '"')
+            escaped += '\\"';
+        else if (character === "\n")
+            escaped += "\\n";
+        else if (character === "\r")
+            escaped += "\\r";
+        else if (character === "\t")
+            escaped += "\\t";
+        else if (codePoint < 0x20 || codePoint === 0x7f) {
+            escaped += `\\x${codePoint.toString(16).padStart(2, "0")}`;
+        }
+        else if (codePoint >= 0x80 && codePoint <= 0x9f) {
+            escaped += `\\u${codePoint.toString(16).padStart(4, "0")}`;
+        }
+        else {
+            escaped += character;
+        }
+    }
+    return `"${escaped}"`;
+}
 const warning = (message) => { process.stderr.write(`session-journal: ${message}\n`); };
 const journalDir = (root, date) => path.join(root, "workspace/threads/journal", date);
 const hasFile = (file) => {
@@ -211,6 +239,7 @@ export function runSessionJournalFast(args, _stdin, cwd, hqRoot, dependencies =
             return 0;
         }
         const slug = slugify(title) || "entry";
+        const yamlSlug = slug.includes("\n") ? yamlDoubleQuoted(slug) : slug;
         const body = bodyFile && hasFile(bodyFile)
             ? fs.readFileSync(bodyFile, "utf8")
             : "## Goal\n\n## Findings\n\n## Decisions\n\n## Next\n";
@@ -226,7 +255,7 @@ export function runSessionJournalFast(args, _stdin, cwd, hqRoot, dependencies =
             for (let attempt = 0; attempt < 10_000; attempt += 1) {
                 seq = nextSequence(dir);
                 output = path.join(dir, `${seq}-${slug}.md`);
-                const lines = ["---\n", `ts: ${nowIso()}\n`, `title: ${title}\n`, `slug: ${slug}\n`];
+                const lines = ["---\n", `ts: ${nowIso()}\n`, `title: ${yamlDoubleQuoted(title)}\n`, `slug: ${yamlSlug}\n`];
                 if (files) {
                     lines.push("files:\n");
                     for (const file of files.split(","))

package/dist/commands/lanes.js

@@ -35,7 +35,7 @@ import { withCliFeatureUsed } from "../utils/cli-telemetry.js";
 import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
 import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
 import { readLanesFlagLocalOverride, readLanesRegistryFlag, readLanesRegistryFlagFailOff } from "../lib/lanes/registry-flag.js";
-import { LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG } from "../lib/lanes/flag-keys.js";
+import { LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, } from "../lib/lanes/flag-keys.js";
 import { CODEX_ROLLOUT_RETENTION_FLAG, configuredCodexRolloutHomes, lowDiskGuardEnabledForLane, retainCodexRollouts } from "../lib/lanes/disk-guard.js";
 import { isControllerAliasOutpostId } from "../lib/lanes/admission-host.js";
 import { runLeadAutopilotPass } from "../lib/lanes/autopilot.js";
@@ -1337,6 +1337,7 @@ async function refreshRemoteLaneMirrors(ctx, hqRoot, records, parentLaneIds, opt
         updated: new Map(),
         unverifiedRemote: new Map(),
         missingOnOwner: new Map(),
+        skippedRemoteRefresh: new Set(),
     };
     const now = ctx.now();
     const nowMs = now.getTime();
@@ -1378,6 +1379,7 @@ async function refreshRemoteLaneMirrors(ctx, hqRoot, records, parentLaneIds, opt
     if (candidates.length === 0)
         return result;
     const enabledByCompany = new Map();
+    const skipRefreshByCompany = new Map();
     const enabledCandidates = [];
     for (const lane of candidates) {
         const company = resolveLaneCompany(hqRoot, lane).company;
@@ -1392,8 +1394,20 @@ async function refreshRemoteLaneMirrors(ctx, hqRoot, records, parentLaneIds, opt
             });
             enabledByCompany.set(companyKey, enabled);
         }
-        if (enabled)
-            enabledCandidates.push(lane);
+        if (!enabled)
+            continue;
+        if (options.skipRemoteRefreshForCompany) {
+            let skipRefresh = skipRefreshByCompany.get(companyKey);
+            if (skipRefresh === undefined) {
+                skipRefresh = await options.skipRemoteRefreshForCompany(company);
+                skipRefreshByCompany.set(companyKey, skipRefresh);
+            }
+            if (skipRefresh) {
+                result.skippedRemoteRefresh.add(lane.lane_id);
+                continue;
+            }
+        }
+        enabledCandidates.push(lane);
     }
     if (enabledCandidates.length === 0)
         return result;
@@ -4950,7 +4964,12 @@ async function runList(ctx, opts) {
     }
     const remoteRead = ctx.env[REMOTE_LANE_READ_ENV] === "1";
     const remoteRefresh = remoteRead
-        ? { updated: new Map(), unverifiedRemote: new Map(), missingOnOwner: new Map() }
+        ? {
+            updated: new Map(),
+            unverifiedRemote: new Map(),
+            missingOnOwner: new Map(),
+            skippedRemoteRefresh: new Set(),
+        }
         : await refreshRemoteLaneMirrors(ctx, hqRoot, laneSource, new Set(laneSource
             .filter((lane) => matchesLaneFilters(lane, false))
             .map((lane) => lane.lane_id)), {
@@ -4958,6 +4977,7 @@ async function runList(ctx, opts) {
             laneIds: new Set(laneSource
                 .filter((lane) => matchesLaneFilters(lane, false))
                 .map((lane) => lane.lane_id)),
+            skipRemoteRefreshForCompany: (company) => readLanesRegistryFlagFailOff(LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, { company, env: ctx.env }),
         });
     for (const [laneId, updated] of remoteRefresh.updated) {
         const index = laneSource.findIndex((lane) => lane.lane_id === laneId);
@@ -4995,6 +5015,7 @@ async function runList(ctx, opts) {
     const ownerEligibleLaneIds = new Set();
     for (const lane of selectedLanes) {
         if (remoteRead ||
+            remoteRefresh.skippedRemoteRefresh.has(lane.lane_id) ||
             lane.host.kind !== "outpost" ||
             isTerminalLaneState(lane.state) ||
             laneRunsHere(lane, host)) {
@@ -5034,6 +5055,7 @@ async function runList(ctx, opts) {
     const livenessBySession = new Map();
     let livenessDeps;
     const lanes = selectedLanes.map((lane) => {
+        const overdue = Boolean(lane.overdue) || isOverdue(hqRoot, lane.lane_id, now);
         const remoteQueued = lane.state === "queued" &&
             lane.host.kind === "outpost" &&
             !laneRunsHere(lane, host);
@@ -5052,7 +5074,7 @@ async function runList(ctx, opts) {
                     queued_details: lane.queued_reason === "low_disk" ? lane.queued_details : undefined,
                 }
                 : {}),
-            overdue: Boolean(lane.overdue) || isOverdue(hqRoot, lane.lane_id, now),
+            overdue,
             stalled: Boolean(lane.stalled),
             // Listing is observational. Reconcile owns durable liveness transitions.
             senior_lost: lane.state === "running" && lane.senior.kind === "session" && lane.senior.id
@@ -7873,6 +7895,7 @@ async function runReconcile(ctx, opts, recoverQueuedMessages) {
             updated: new Map(),
             unverifiedRemote: new Map(),
             missingOnOwner: new Map(),
+            skippedRemoteRefresh: new Set(),
         }
         : await refreshRemoteLaneMirrors(ctx, hqRoot, loadAllLanes(hqRoot));
     const remoteLost = [];

package/dist/index.d.ts

@@ -3,8 +3,17 @@ import "./node-preflight.js";
 import "./node-network-compat-fast.js";
 import { isVersionRequest } from "./version-request.js";
 import { isFastCoreRequest } from "./fast-scaffold.js";
+type PackageUseLeaseLoader = () => Promise<void>;
+declare function isNpmPackageEntry(entryUrl: string): boolean;
+declare function dispatchWithPackageUseLease(entryUrl: string, dispatch: () => void, loadLease?: PackageUseLeaseLoader): void | Promise<void>;
+declare function runCliEntry(entryUrl: string, dispatch: () => void, loadLease?: PackageUseLeaseLoader): void | Promise<void>;
 export declare const __test__: {
     isVersionRequest: typeof isVersionRequest;
     isFastCoreRequest: typeof isFastCoreRequest;
+    dispatchWithPackageUseLease: typeof dispatchWithPackageUseLease;
+    runCliEntry: typeof runCliEntry;
+    isNpmPackageEntry: typeof isNpmPackageEntry;
+    acquirePackageUseLease: (prefix: string, version: string, stateDirectory?: string) => Promise<import("./utils/package-use-lease.js").PackageUseLease>;
 };
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -17,77 +17,149 @@ import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.
 // command never run (HQ-CLI-W). Sets process.exitCode only, never process.exit,
 // so runCli's finally still finalizes release health and flushes Sentry.
 installProcessRejectionBoundary();
-if (isVersionRequest(process.argv)) {
-    // Bare `--version` is the CLI semver only (the contract field updaters
-    // 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("./lib/flag-registry.js").then(({ kickFlagRegistryReadiness }) => {
-            kickFlagRegistryReadiness();
-            return import("./utils/version-report.js").then(({ runVersionCommand }) => runVersionCommand(process.argv));
+function dispatchCliEntry() {
+    if (isVersionRequest(process.argv)) {
+        // Bare `--version` is the CLI semver only (the contract field updaters
+        // 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("./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`);
+            });
+        }
+    }
+    else if (parseFastCore(process.argv)?.entry.kind === "native" &&
+        (process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "true" ||
+            process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "1")) {
+        // An explicit enabled override has already decided the global gate. Skip the
+        // snapshot reader import on hot native plumbing paths; runFastCore still
+        // checks the command-family flag before choosing native or shell rollback.
+        void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv));
+    }
+    else if (parseFastCore(process.argv)?.entry.kind === "native") {
+        // Native routes are default-off. Resolve the company-scoped persisted flag
+        // without loading the command graph; a miss or stale snapshot takes the
+        // existing full-graph route.
+        void import("./native-fast-route.js").then(async ({ nativeFastRouteEnabled }) => {
+            if (await nativeFastRouteEnabled(process.argv)) {
+                const { runFastCore } = await import("./fast-core.js");
+                await runFastCore(process.argv);
+            }
+            else {
+                const { runCli } = await import("./main.js");
+                await runCli();
+            }
         });
     }
-    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`);
+    else if (parseSecretsEnvFastRequest(process.argv)) {
+        const request = parseSecretsEnvFastRequest(process.argv);
+        void import("./secrets-env-fast-route.js").then(async (route) => {
+            await route.dispatchSecretsEnvFastRequest(request, {
+                isEnabled: () => route.secretsEnvFastRouteEnabled(request),
+                runFast: async () => {
+                    const { runSecretsEnvFastPath } = await import("./secrets-env-fast-path.js");
+                    return runSecretsEnvFastPath(request);
+                },
+                runCurrent: async () => {
+                    const { runCli } = await import("./main.js");
+                    await runCli();
+                },
+            });
         });
     }
+    else if (isFastCoreRequest(process.argv)) {
+        // Hot relocated plumbing (`hq core hq-session`, `hq core checkpoint-stop-gate`)
+        // dispatches straight to the bundled-script runner, so it never pays for the
+        // ~60-module command graph main.ts imports. See src/fast-scaffold.ts.
+        void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv));
+    }
+    else {
+        // Keep the command lifecycle detached from module evaluation, as it was
+        // before the fast --version split. Some best-effort teardown work uses
+        // unref'd handles; top-level-awaiting runCli() makes Node turn an otherwise
+        // successful command into exit 13 when that teardown promise remains pending.
+        // A floated rejection here no longer exits 0 silently: the boundary installed
+        // above turns it into a non-zero exit (HQ-CLI-W).
+        void import("./main.js").then(({ runCli }) => runCli());
+    }
 }
-else if (parseFastCore(process.argv)?.entry.kind === "native" &&
-    (process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "true" ||
-        process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "1")) {
-    // An explicit enabled override has already decided the global gate. Skip the
-    // snapshot reader import on hot native plumbing paths; runFastCore still
-    // checks the command-family flag before choosing native or shell rollback.
-    void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv));
+function isNpmPackageEntry(entryUrl) {
+    return /\/node_modules\/@indigoai-us\/hq-cli\/dist\/index\.js$/i.test(entryUrl);
 }
-else if (parseFastCore(process.argv)?.entry.kind === "native") {
-    // Native routes are default-off. Resolve the company-scoped persisted flag
-    // without loading the command graph; a miss or stale snapshot takes the
-    // existing full-graph route.
-    void import("./native-fast-route.js").then(async ({ nativeFastRouteEnabled }) => {
-        if (await nativeFastRouteEnabled(process.argv)) {
-            const { runFastCore } = await import("./fast-core.js");
-            await runFastCore(process.argv);
-        }
-        else {
-            const { runCli } = await import("./main.js");
-            await runCli();
-        }
-    });
+function isPackageUseUpdatePendingError(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        error.name === "PackageUseUpdatePendingError");
 }
-else if (parseSecretsEnvFastRequest(process.argv)) {
-    const request = parseSecretsEnvFastRequest(process.argv);
-    void import("./secrets-env-fast-route.js").then(async (route) => {
-        await route.dispatchSecretsEnvFastRequest(request, {
-            isEnabled: () => route.secretsEnvFastRouteEnabled(request),
-            runFast: async () => {
-                const { runSecretsEnvFastPath } = await import("./secrets-env-fast-path.js");
-                return runSecretsEnvFastPath(request);
-            },
-            runCurrent: async () => {
-                const { runCli } = await import("./main.js");
-                await runCli();
-            },
-        });
-    });
+function packageUseErrorClass(error) {
+    if (!error || typeof error !== "object")
+        return "unknown";
+    const value = error;
+    if (typeof value.code === "string")
+        return value.code;
+    if (value.cause && typeof value.cause === "object") {
+        const cause = value.cause;
+        if (typeof cause.code === "string")
+            return cause.code;
+        if (typeof cause.name === "string")
+            return cause.name;
+    }
+    return typeof value.name === "string" ? value.name : "unknown";
 }
-else if (isFastCoreRequest(process.argv)) {
-    // Hot relocated plumbing (`hq core hq-session`, `hq core checkpoint-stop-gate`)
-    // dispatches straight to the bundled-script runner, so it never pays for the
-    // ~60-module command graph main.ts imports. See src/fast-scaffold.ts.
-    void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv));
+function dispatchWithPackageUseLease(entryUrl, dispatch, loadLease = async () => {
+    const { acquireCurrentPackageUseLease } = await import("./utils/package-use-lease.js");
+    acquireCurrentPackageUseLease();
+}) {
+    if (!isNpmPackageEntry(entryUrl)) {
+        dispatch();
+        return;
+    }
+    return loadLease().then(dispatch, (error) => {
+        if (isPackageUseUpdatePendingError(error))
+            throw error;
+        process.stderr.write(`hq-cli package-use lease unavailable (${packageUseErrorClass(error)}); continuing without lease\n`);
+        dispatch();
+    });
 }
-else {
-    // Keep the command lifecycle detached from module evaluation, as it was
-    // before the fast --version split. Some best-effort teardown work uses
-    // unref'd handles; top-level-awaiting runCli() makes Node turn an otherwise
-    // successful command into exit 13 when that teardown promise remains pending.
-    // A floated rejection here no longer exits 0 silently: the boundary installed
-    // above turns it into a non-zero exit (HQ-CLI-W).
-    void import("./main.js").then(({ runCli }) => runCli());
+function runCliEntry(entryUrl, dispatch, loadLease) {
+    const handlePendingUpdate = (error) => {
+        if (!isPackageUseUpdatePendingError(error))
+            throw error;
+        const message = error instanceof Error
+            ? error.message
+            : "The HQ CLI package is being updated";
+        process.stderr.write(`hq-cli: ${message}\n`);
+        process.exitCode = 1;
+    };
+    try {
+        const result = dispatchWithPackageUseLease(entryUrl, dispatch, loadLease);
+        return result?.catch(handlePendingUpdate);
+    }
+    catch (error) {
+        handlePendingUpdate(error);
+    }
 }
-export const __test__ = { isVersionRequest, isFastCoreRequest };
+// Local builds and benchmark fixtures are not installed in an npm prefix.
+// Keep their fast route free of package-use filesystem work; npm installs still
+// publish a lease before dispatch.
+void runCliEntry(import.meta.url, dispatchCliEntry);
+export const __test__ = {
+    isVersionRequest,
+    isFastCoreRequest,
+    dispatchWithPackageUseLease,
+    runCliEntry,
+    isNpmPackageEntry,
+    acquirePackageUseLease: async (prefix, version, stateDirectory) => {
+        const lease = await import("./utils/package-use-lease.js");
+        return lease.acquirePackageUseLease(prefix, version, stateDirectory);
+    },
+};
 //# sourceMappingURL=index.js.map

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

@@ -12,6 +12,8 @@ import { type HostApp } from "./supervisor.js";
 export declare const LOG_ROTATE_BYTES: number;
 /** Exit code for "restart me": non-zero so every service manager relaunches (Windows tasks only restart on failure). */
 export declare const RESTART_EXIT_CODE = 75;
+/** Route an updater request through the daemon's existing graceful handoff. */
+export declare function handoffForPackageUpdateRequest(requested: boolean, restartDaemon: () => void): void;
 export interface RunDaemonOptions {
     foreground?: boolean;
     /** Started by the OS unit, which relaunches the daemon whenever it exits. */

package/dist/lib/daemon/run.js

@@ -12,6 +12,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { CLI_VERSION } from "../../cli-version.js";
+import { currentPackageUseUpdateRequested } from "../../utils/package-use-lease.js";
 import { isLocalDependencyInstall, resolveRunningInstall } from "../../utils/version-gate.js";
 import { agentKitPaths } from "../agent-kit/paths.js";
 import { readBotConfig } from "../bot/config.js";
@@ -39,6 +40,11 @@ import { userToolDirs } from "./tools.js";
 export const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
 /** Exit code for "restart me": non-zero so every service manager relaunches (Windows tasks only restart on failure). */
 export const RESTART_EXIT_CODE = 75;
+/** Route an updater request through the daemon's existing graceful handoff. */
+export function handoffForPackageUpdateRequest(requested, restartDaemon) {
+    if (requested)
+        restartDaemon();
+}
 const LEGACY_PROBE_TTL_MS = 60_000;
 /** A flag read that has not answered by then counts as off. */
 const HANDOFF_FLAG_TIMEOUT_MS = 10_000;
@@ -603,7 +609,10 @@ export async function runDaemon(opts) {
                 log("info", `rotated ${n} log file(s)`);
             return true;
         },
-        takeRequests: () => takeControlRequests(paths.requestsDir),
+        takeRequests: () => {
+            handoffForPackageUpdateRequest(currentPackageUseUpdateRequested(), restartDaemon);
+            return takeControlRequests(paths.requestsDir);
+        },
         restartDaemon: () => restartDaemon(),
         writeState: (state) => writeJsonAtomic(paths.statePath, state),
         log,

package/dist/lib/lanes/flag-keys.d.ts

@@ -4,6 +4,9 @@ export declare const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-bala
 export declare const LANE_ENVELOPE_REPAIR_CONTINUE_FLAG = "lanes.envelope-repair-continue";
 /** Count only children with live work against their senior's hire grant. */
 export declare const LANE_HIRE_GRANT_FINISHED_LANES_FLAG = "lanes.hire-grant-count-live-only";
+/** Skips owner refreshes during ordinary lane list polling when explicitly enabled. */
+export declare const LANE_LIST_SKIP_REMOTE_REFRESH_FLAG = "lanes.list-skip-remote-refresh";
+export declare const LANE_LIST_SKIP_REMOTE_REFRESH_DEFAULT_ENABLED = false;
 /** Enables missed-deadline lead nudges and second-miss operator escalation. */
 export declare const LANE_AUTOPILOT_MISSED_DEADLINE_ESCALATION_FLAG = "lanes.autopilot-missed-deadline-escalation";
 export declare const LANE_AUTOPILOT_NUDGE_DEDUPE_FLAG = "lanes.autopilot-nudge-dedupe";

package/dist/lib/lanes/flag-keys.js

@@ -4,6 +4,9 @@ export const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-balancing";
 export const LANE_ENVELOPE_REPAIR_CONTINUE_FLAG = "lanes.envelope-repair-continue";
 /** Count only children with live work against their senior's hire grant. */
 export const LANE_HIRE_GRANT_FINISHED_LANES_FLAG = "lanes.hire-grant-count-live-only";
+/** Skips owner refreshes during ordinary lane list polling when explicitly enabled. */
+export const LANE_LIST_SKIP_REMOTE_REFRESH_FLAG = "lanes.list-skip-remote-refresh";
+export const LANE_LIST_SKIP_REMOTE_REFRESH_DEFAULT_ENABLED = false;
 /** Enables missed-deadline lead nudges and second-miss operator escalation. */
 export const LANE_AUTOPILOT_MISSED_DEADLINE_ESCALATION_FLAG = "lanes.autopilot-missed-deadline-escalation";
 export const LANE_AUTOPILOT_NUDGE_DEDUPE_FLAG = "lanes.autopilot-nudge-dedupe";

package/dist/utils/package-use-lease.d.ts

@@ -0,0 +1,25 @@
+export declare class PackageUseUpdatePendingError extends Error {
+    constructor(message: string);
+}
+export interface PackageUseLease {
+    readonly leasePath: string;
+    release(): void;
+}
+export interface PackageUseLeaseRecord {
+    pid: number;
+    start_time_ms: number;
+    hq_version: string;
+}
+export declare function npmPrefix(root: string, platform?: NodeJS.Platform): string | null;
+export declare function packageUseLeaseDirectory(prefix: string, stateDirectory?: string): string;
+export declare function packageUseUpdateRequestPath(prefix: string, stateDirectory?: string): string;
+declare function waitForUpdateRequest(requestPath: string, timeoutMs: number): void;
+export declare function acquirePackageUseLease(prefix: string, hqVersion: string, stateDirectory?: string): PackageUseLease;
+export declare function acquireCurrentPackageUseLease(): PackageUseLease | null;
+/** True while the desktop updater owns the per-prefix update request. */
+export declare function currentPackageUseUpdateRequested(): boolean;
+export declare const __test__: {
+    waitForUpdateRequest: typeof waitForUpdateRequest;
+};
+export {};
+//# sourceMappingURL=package-use-lease.d.ts.map

package/dist/utils/package-use-lease.js

@@ -0,0 +1,213 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { performance } from "node:perf_hooks";
+const CLI_NAME = "@indigoai-us/hq-cli";
+const UPDATE_REQUEST = "update.pending.json";
+export class PackageUseUpdatePendingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PackageUseUpdatePendingError";
+    }
+}
+function errorLabel(error) {
+    if (error && typeof error === "object") {
+        const value = error;
+        if (typeof value.code === "string")
+            return value.code;
+        if (typeof value.name === "string")
+            return value.name;
+    }
+    return "unknown error";
+}
+function readPackage(directory) {
+    try {
+        return JSON.parse(readFileSync(path.join(directory, "package.json"), "utf8"));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        throw new Error(`Unable to inspect the HQ CLI install (${errorLabel(error)})`, { cause: error });
+    }
+}
+function findCliPackage(directory) {
+    while (true) {
+        const pkg = readPackage(directory);
+        if (pkg?.name === CLI_NAME) {
+            return { root: directory, version: typeof pkg.version === "string" ? pkg.version : "unknown" };
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+}
+function isPnpmGlobal(root) {
+    const normalized = root.replace(/\\/g, "/").replace(/\/+$/, "");
+    const parts = normalized.split("/").filter(Boolean);
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        if (parts[i] === "global" && (/^\d+$/.test(parts[i + 1]) || /^v\d+$/.test(parts[i + 1])))
+            return true;
+    }
+    const home = process.env.PNPM_HOME?.replace(/\\/g, "/").replace(/\/+$/, "");
+    const globalRoot = home ? `${home}/global` : null;
+    const left = process.platform === "win32" ? normalized.toLowerCase() : normalized;
+    const right = globalRoot && process.platform === "win32" ? globalRoot.toLowerCase() : globalRoot;
+    return Boolean(right && (left === right || left.startsWith(`${right}/`)));
+}
+function isBunGlobal(root) {
+    const parts = root.replace(/\\/g, "/").split("/").filter(Boolean);
+    return parts.some((part, i) => part === "install" && parts[i + 1] === "global" && parts[i + 2] === "node_modules");
+}
+export function npmPrefix(root, platform = process.platform) {
+    const normalized = root.replace(/\\/g, "/").replace(/\/+$/, "");
+    const parts = normalized.split("/");
+    const index = parts.lastIndexOf("node_modules");
+    if (index < 0)
+        return null;
+    const end = parts[index - 1] === "lib" ? index - 1 : index;
+    const prefix = parts.slice(0, end).join("/");
+    if (platform === "win32" && /^[a-z]:$/i.test(prefix))
+        return `${prefix}/`;
+    if (!prefix && normalized.startsWith("/"))
+        return "/";
+    return prefix || null;
+}
+function packageUseStateDirectory() {
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA;
+        if (!localAppData)
+            throw new Error("LOCALAPPDATA is unavailable for the HQ CLI package-use lease");
+        return path.join(localAppData, "hq-cli", "state", "package-use");
+    }
+    return path.join(process.env.XDG_STATE_HOME?.trim() || path.join(os.homedir(), ".local", "state"), "hq-cli", "package-use");
+}
+function normalizedPrefix(prefix) {
+    let canonical = realpathSync.native(prefix).replace(/\\/g, "/");
+    canonical = canonical.replace(/^\\\\\?\\UNC\\/i, "//").replace(/^\\\\\?\\/, "");
+    return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+export function packageUseLeaseDirectory(prefix, stateDirectory = packageUseStateDirectory()) {
+    const digest = createHash("sha256").update(normalizedPrefix(prefix), "utf8").digest("hex");
+    return path.join(stateDirectory, digest);
+}
+export function packageUseUpdateRequestPath(prefix, stateDirectory) {
+    return path.join(packageUseLeaseDirectory(prefix, stateDirectory), UPDATE_REQUEST);
+}
+function waitForUpdateRequest(requestPath, timeoutMs) {
+    const started = Date.now();
+    const sleeper = new Int32Array(new SharedArrayBuffer(4));
+    while (true) {
+        try {
+            const request = JSON.parse(readFileSync(requestPath, "utf8"));
+            const pid = request.pid;
+            if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+                throw new Error("invalid update request");
+            }
+            try {
+                process.kill(pid, 0);
+            }
+            catch (error) {
+                if (error.code === "ESRCH") {
+                    rmSync(requestPath, { force: true });
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw new Error(`Unable to read the HQ CLI update request (${errorLabel(error)})`, { cause: error });
+        }
+        if (Date.now() - started >= timeoutMs) {
+            throw new PackageUseUpdatePendingError("The HQ CLI package is being updated; retry after the update finishes");
+        }
+        Atomics.wait(sleeper, 0, 0, 100);
+    }
+}
+export function acquirePackageUseLease(prefix, hqVersion, stateDirectory) {
+    const directory = packageUseLeaseDirectory(prefix, stateDirectory);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const requestPath = path.join(directory, UPDATE_REQUEST);
+    const record = {
+        pid: process.pid,
+        start_time_ms: Math.floor(performance.timeOrigin),
+        hq_version: hqVersion,
+    };
+    const leasePath = path.join(directory, `${record.pid}-${record.start_time_ms}.json`);
+    const tempPath = `${leasePath}.${Math.random().toString(36).slice(2)}.tmp`;
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        process.removeListener("exit", releaseOnExit);
+        try {
+            rmSync(leasePath, { force: true });
+        }
+        catch (error) {
+            process.stderr.write(`hq-cli package-use lease release failed (${errorLabel(error)})\n`);
+        }
+    };
+    const releaseOnExit = () => release();
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        waitForUpdateRequest(requestPath, 30_000);
+        try {
+            writeFileSync(tempPath, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 });
+            renameSync(tempPath, leasePath);
+        }
+        catch (error) {
+            rmSync(tempPath, { force: true });
+            throw new Error(`Unable to publish the HQ CLI package-use lease (${errorLabel(error)})`, { cause: error });
+        }
+        if (!exists(requestPath)) {
+            process.once("exit", releaseOnExit);
+            return { leasePath, release };
+        }
+        rmSync(leasePath, { force: true });
+    }
+    throw new PackageUseUpdatePendingError("An HQ CLI update is waiting for the package lease; retry when it finishes");
+}
+function exists(file) {
+    try {
+        readFileSync(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export function acquireCurrentPackageUseLease() {
+    const pkg = findCliPackage(path.dirname(fileURLToPath(import.meta.url)));
+    if (!pkg || isPnpmGlobal(pkg.root) || isBunGlobal(pkg.root))
+        return null;
+    const prefix = npmPrefix(pkg.root);
+    if (!prefix)
+        return null;
+    if (process.platform !== "win32") {
+        const parts = pkg.root.replace(/\\/g, "/").replace(/\/+$/, "").split("/").filter(Boolean);
+        const nodeModules = parts.lastIndexOf("node_modules");
+        if (nodeModules > 0 && parts[nodeModules - 1] !== "lib")
+            return null;
+    }
+    return acquirePackageUseLease(prefix, pkg.version);
+}
+/** True while the desktop updater owns the per-prefix update request. */
+export function currentPackageUseUpdateRequested() {
+    const pkg = findCliPackage(path.dirname(fileURLToPath(import.meta.url)));
+    if (!pkg || isPnpmGlobal(pkg.root) || isBunGlobal(pkg.root))
+        return false;
+    const prefix = npmPrefix(pkg.root);
+    if (!prefix)
+        return false;
+    return exists(packageUseUpdateRequestPath(prefix));
+}
+export const __test__ = {
+    waitForUpdateRequest,
+};
+//# sourceMappingURL=package-use-lease.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.319.0",
+  "version": "5.320.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {