@indigoai-us/hq-cli 5.345.6 → 5.345.8

package/CHANGELOG.md

@@ -2,10 +2,24 @@
 
 ## [Unreleased]
 
+## [5.345.8] — 2026-10-05
+- Prioritize due lead keep-alive retries and honor due next-check times ahead of later backoff deadlines behind an hq-flags gate.
+- Drain bot turns before replacing a running bot after a daemon plan change.
+
+## [5.345.7] — 2026-10-05
+- Retry a just-published hq-cli version when npm briefly reports `notarget`.
+- Wait for an active sync pass to finish before restarting sync after a CLI update.
+- Add bounded context to captured missing-module errors targeting hq-cli's own dist output.
+- Recover interrupted agent inbox polls without duplicating mirrored journal entries.
+- Record the actual launch time, trigger, and caller for resumed lane workers even when legacy launch history is missing.
+
 ## [5.345.6] — 2026-10-05
 - `hq mesh context default set <slug> --count-usage` now works for people signed in with a normal HQ account. It previously refused with "the signed-in person could not be determined". An opt-in saved by 5.344.0 is ignored; run the command again to opt in.
 - `hq daemon sync status` now identifies the executing runner and derives its hq-cloud version from the owner status or runner package when needed.
 
+## [5.345.5] — 2026-10-05
+- `hq daemon sync status` now identifies the executing runner and derives its hq-cloud version from the owner status or runner package when needed.
+
 ## [5.345.4] — 2026-10-05
 - Run a pinned or newer managed hq-cloud sync runner ahead of the staged sync bundle, so daemon sync no longer stays on the hq-cloud version bundled with the CLI after an update or pin (hq-cli#1547).
 - Avoid dispatching the global hook when the working directory is inside an HQ root.

package/dist/commands/__fixtures__/make-tar.d.ts

@@ -22,7 +22,7 @@
  * lists whatever bytes we wrote, so the guard sees the real attack everywhere.
  */
 /** ustar typeflag values we use. */
-export type TarType = 'file' | 'symlink' | 'hardlink';
+type TarType = 'file' | 'symlink' | 'hardlink';
 export interface TarEntrySpec {
     /** Recorded entry name — written VERBATIM (may contain `..`, be absolute…). */
     name: string;
@@ -32,15 +32,7 @@ export interface TarEntrySpec {
     /** File content (regular files only). */
     content?: string | Buffer;
 }
-/**
- * Build one 512-byte ustar header (plus content blocks for regular files) for a
- * single entry. The header checksum is computed exactly per spec: sum every
- * header byte treating the 8 checksum bytes themselves as ASCII spaces, then
- * write that sum as 6 octal digits + NUL + space.
- */
-export declare function makeTarEntry(spec: TarEntrySpec): Buffer;
-/** Concatenate entries and append the two zero blocks that end every tar. */
-export declare function makeTar(entries: TarEntrySpec[]): Buffer;
 /** Build the tar, gzip it, and write it to `outPath`. Returns `outPath`. */
 export declare function writeMaliciousTarGz(outPath: string, entries: TarEntrySpec[]): string;
+export {};
 //# sourceMappingURL=make-tar.d.ts.map

package/dist/commands/__fixtures__/make-tar.js

@@ -50,7 +50,7 @@ function writeOctal(buf, offset, width, value) {
  * header byte treating the 8 checksum bytes themselves as ASCII spaces, then
  * write that sum as 6 octal digits + NUL + space.
  */
-export function makeTarEntry(spec) {
+function makeTarEntry(spec) {
     const type = spec.type ?? 'file';
     const content = type === 'file'
         ? Buffer.isBuffer(spec.content)
@@ -89,7 +89,7 @@ export function makeTarEntry(spec) {
     return Buffer.concat([header, content, Buffer.alloc(pad)]);
 }
 /** Concatenate entries and append the two zero blocks that end every tar. */
-export function makeTar(entries) {
+function makeTar(entries) {
     const blocks = entries.map(makeTarEntry);
     blocks.push(Buffer.alloc(BLOCK * 2)); // end-of-archive marker
     return Buffer.concat(blocks);

package/dist/commands/agent-enroll.d.ts

@@ -17,18 +17,16 @@
 import { Command } from "commander";
 import { generateHostKeyPair } from "../lib/agent-kit/creds.js";
 import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
-export declare const ENROLL_PATH = "/v1/agents/enroll";
 /** Canonical code: un-grouped, uppercase (server hashes exactly this). */
 export declare function normalizeEnrollmentCode(raw: string): string;
 /** 24 chars of Crockford base32 (no I, L, O, U). */
 export declare function isWellFormedEnrollmentCode(code: string): boolean;
-export interface HostInfo {
+interface HostInfo {
     os: string;
     arch: string;
     hostname: string;
     cliVersion: string;
 }
-export declare function collectHostInfo(): HostInfo;
 export type ExistingIdentity = {
     kind: "none";
 } | {
@@ -143,4 +141,5 @@ export interface EnrollResult {
 /** Pure-ish orchestration so tests can drive it without a TTY or network. */
 export declare function enrollHost(opts: EnrollOptions, deps?: EnrollDeps): Promise<EnrollResult>;
 export declare function registerAgentEnrollCommand(agent: Command): void;
+export {};
 //# sourceMappingURL=agent-enroll.d.ts.map

package/dist/commands/agent-enroll.js

@@ -25,7 +25,7 @@ import { networkTransportErrorCode } from "../utils/network-transport-error.js";
 import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, planGateErrorFromPayload, } from "../utils/plan-gate-error.js";
 import { generateHostKeyPair, machineCredsFileExists, readExternalMachineCreds, writeHostKeyPair, writeMachineCreds, } from "../lib/agent-kit/creds.js";
 import { DEFAULT_LOCAL_AGENT_NAME, agentKitPaths, localAgentDir, } from "../lib/agent-kit/paths.js";
-export const ENROLL_PATH = "/v1/agents/enroll";
+const ENROLL_PATH = "/v1/agents/enroll";
 /** Canonical code: un-grouped, uppercase (server hashes exactly this). */
 export function normalizeEnrollmentCode(raw) {
     return raw.replace(/[\s-]+/g, "").toUpperCase();
@@ -34,7 +34,7 @@ export function normalizeEnrollmentCode(raw) {
 export function isWellFormedEnrollmentCode(code) {
     return /^[0-9A-HJKMNP-TV-Z]{24}$/.test(code);
 }
-export function collectHostInfo() {
+function collectHostInfo() {
     return {
         os: `${os.platform()} ${os.release()}`,
         arch: os.arch(),

package/dist/commands/mcp-status.d.ts

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import { type SafeWriteEnv } from './mcp-registration.js';
 /** A server's presence on ONE runtime surface. */
-export type PresenceState = 
+type PresenceState = 
 /** The server def is present (and parsed) on this runtime. */
 'present'
 /** The runtime parsed fine but this server is not registered there. */
@@ -30,7 +30,7 @@ export interface RuntimeServerStatus {
     healthy?: boolean;
 }
 /** A single HQ-owned MCP server's cross-runtime status. */
-export interface McpServerStatus {
+interface McpServerStatus {
     /** The bare server name (the `mcpServers` / `mcp_servers` key). */
     server: string;
     /** The pack that owns it (`_hqPack` provenance). */
@@ -59,7 +59,7 @@ export interface McpServerStatus {
     drifted: boolean;
 }
 /** A runtime's top-level status. */
-export interface RuntimeStatus {
+interface RuntimeStatus {
     /** Whether the runtime is installed (Claude is always; Codex iff `~/.codex` exists). */
     installed: boolean;
     /** Whether the runtime's config parsed (false => unparseable). */
@@ -133,4 +133,5 @@ export declare function renderMcpCapabilities(caps: McpCapabilities): string;
  * {@link registerReindexCommand} and the subcommand-group pattern in index.ts.
  */
 export declare function registerMcpCommand(program: Command): void;
+export {};
 //# sourceMappingURL=mcp-status.d.ts.map

package/dist/commands/reindex.d.ts

@@ -5,12 +5,6 @@ import { Command } from 'commander';
  * layout scan and Git's status output rather than recursively walking trees.
  */
 export declare function removeStaleHqWorktrees(hqRoot: string, now?: number, deadline?: number): void;
-/**
- * Check hook health without relying on lifecycle hooks. A fully disabled
- * configuration is repaired only after a successful reindex; partial and
- * malformed configurations remain untouched and receive recovery guidance.
- */
-export declare function repairExtremeHookDrift(hqRoot: string, allowRepair?: boolean): void;
 /**
  * Stop the generated project settings from silently downgrading an operator who
  * chose Bypass mode globally.

package/dist/commands/reindex.js

@@ -491,7 +491,7 @@ function runSilently(operation) {
  * configuration is repaired only after a successful reindex; partial and
  * malformed configurations remain untouched and receive recovery guidance.
  */
-export function repairExtremeHookDrift(hqRoot, allowRepair = true) {
+function repairExtremeHookDrift(hqRoot, allowRepair = true) {
     // `hq reindex` can still be invoked from an arbitrary directory. Never turn
     // an absent settings file there into a rescue attempt.
     if (!isHqRoot(hqRoot))

package/dist/commands/safe-extract.d.ts

@@ -45,7 +45,7 @@ export declare const DEFAULT_CAPS: ExtractCaps;
 export declare class UnsafeArchiveError extends Error {
     constructor(message: string);
 }
-export type EntryType = 'file' | 'dir' | 'symlink' | 'hardlink' | 'other';
+type EntryType = 'file' | 'dir' | 'symlink' | 'hardlink' | 'other';
 export interface TarEntry {
     type: EntryType;
     /** Entry path as recorded in the archive (may contain `..`, be absolute…). */
@@ -108,14 +108,6 @@ export declare function resolveContainedPath(targetDir: string, entryName: strin
  * way the final location must be contained in the pack dir.
  */
 export declare function assertLinkTargetContained(packDir: string, entryAbs: string, linkTarget: string): void;
-/**
- * List a gzip-compressed tarball's entries via `tar -tvf` (no extraction).
- * argv form, never a shell string, keeps hostile filenames out of shell syntax.
- * Windows drive paths always use a basename relative to the archive directory.
- * GNU tar cannot parse `C:\\...` as remote `host:path`, and Windows' bundled
- * bsdtar accepts the same relative argv without GNU-only `--force-local`.
- */
-export declare function listTarball(tarballPath: string, opts?: Pick<SafeExtractOptions, 'platform' | 'execFileSync'>): TarEntry[];
 /**
  * Pre-flight validation against the entry headers. Enforces (a) containment of
  * every entry name under `targetDir`, (b) containment of every link target
@@ -123,14 +115,6 @@ export declare function listTarball(tarballPath: string, opts?: Pick<SafeExtract
  * UnsafeArchiveError on the first violation — default-deny.
  */
 export declare function validateEntries(entries: TarEntry[], targetDir: string, caps?: ExtractCaps): void;
-/**
- * Walk everything actually written under `stagingDir` and assert that no entry
- * — and, for symlinks, no link target — escapes. This is the defense-in-depth
- * backstop: it does not trust the pre-flight scan OR the tar binary. Uses
- * realpath on the link's PARENT (which exists) plus lstat to inspect links
- * without following them off-tree.
- */
-export declare function assertExtractContained(stagingDir: string): void;
 export interface SafeExtractOptions {
     caps?: ExtractCaps;
     /** Test seam for platform-specific argv construction. */
@@ -158,4 +142,5 @@ export interface SafeExtractOptions {
  * so a half-extracted pack can never be wired.
  */
 export declare function safeExtractTarball(tarballPath: string, finalDir: string, opts?: SafeExtractOptions): void;
+export {};
 //# sourceMappingURL=safe-extract.d.ts.map

package/dist/commands/safe-extract.js

@@ -219,7 +219,7 @@ function tarballArgvLocation(tarballPath, platform) {
  * GNU tar cannot parse `C:\\...` as remote `host:path`, and Windows' bundled
  * bsdtar accepts the same relative argv without GNU-only `--force-local`.
  */
-export function listTarball(tarballPath, opts = {}) {
+function listTarball(tarballPath, opts = {}) {
     const platform = opts.platform ?? process.platform;
     const location = tarballArgvLocation(tarballPath, platform);
     const out = (opts.execFileSync ?? execFileSync)('tar', ['-tvf', location.archiveArg], {
@@ -277,7 +277,7 @@ export function validateEntries(entries, targetDir, caps = DEFAULT_CAPS) {
  * realpath on the link's PARENT (which exists) plus lstat to inspect links
  * without following them off-tree.
  */
-export function assertExtractContained(stagingDir) {
+function assertExtractContained(stagingDir) {
     const realRoot = fs.realpathSync(stagingDir);
     const walk = (dir) => {
         for (const dirent of fs.readdirSync(dir, { withFileTypes: true })) {

package/dist/commands/search.d.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-export type SearchMode = 'keyword' | 'semantic' | 'hybrid';
+type SearchMode = 'keyword' | 'semantic' | 'hybrid';
 export type SearchOptions = {
     mode?: SearchMode;
     collection?: string;
@@ -32,4 +32,5 @@ export declare function normalizeQueryForQmd(query: string): string;
 export declare function buildSearchArgs(query: string, options?: SearchOptions): string[];
 export declare function buildGetArgs(document: string, options?: Pick<SearchOptions, 'collection'>): string[];
 export declare function registerSearchCommand(program: Command): void;
+export {};
 //# sourceMappingURL=search.d.ts.map

package/dist/lazy-commands.d.ts

@@ -5,12 +5,6 @@ export type LazyCommand = {
     /** Registers every contributor for this root and no unrelated root. */
     register: (program: Command) => Promise<void>;
 };
-/**
- * One entry for every root, including groups that are assembled by several
- * registrar modules. The routing metadata itself is generated from the eager
- * command graph and checked in tests and the build.
- */
-export declare const LAZY_COMMANDS: readonly LazyCommand[];
 /**
  * Keep the registration seam at register-all.js. Besides making one place own
  * the graph, this lets the torn-install recovery wrap failures while an update

package/dist/lazy-commands.js

@@ -9,7 +9,7 @@ const commandCatalog = COMMAND_CATALOG;
  * registrar modules. The routing metadata itself is generated from the eager
  * command graph and checked in tests and the build.
  */
-export const LAZY_COMMANDS = commandCatalog.map((command) => ({
+const LAZY_COMMANDS = commandCatalog.map((command) => ({
     name: command.name,
     register: async (program) => {
         const registered = await registerCommandRoot(program, command.name);

package/dist/lib/agent-kit/run/inbox.js

@@ -54,10 +54,34 @@ export function writeSeenIds(paths, seen) {
     const list = [...seen].slice(-MAX_SEEN_IDS);
     writePrivateFile(path.join(paths.inboxDir, SEEN_IDS_NAME), JSON.stringify(list), 0o600);
 }
+function inboxJournalContains(paths, id) {
+    const journal = path.join(paths.inboxDir, INBOX_JSONL_NAME);
+    if (!fs.existsSync(journal))
+        return false;
+    for (const line of fs.readFileSync(journal, "utf8").split("\n")) {
+        if (!line)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            // An interrupted append can leave one malformed final record; it does
+            // not prove that this item made it into the durable journal.
+            continue;
+        }
+        if (entry && typeof entry === "object" && entry.id === id)
+            return true;
+    }
+    return false;
+}
 export function mirrorInboxItem(paths, item) {
     const dest = path.join(paths.inboxDir, `${item.id}.json`);
+    const recoveringInterruptedMirror = fs.existsSync(dest);
     writePrivateFile(dest, `${JSON.stringify(item.raw, null, 2)}\n`, 0o600);
-    fs.appendFileSync(path.join(paths.inboxDir, INBOX_JSONL_NAME), `${JSON.stringify({ id: item.id, mirroredAt: new Date().toISOString(), ...item.raw })}\n`, { mode: 0o600 });
+    if (!recoveringInterruptedMirror || !inboxJournalContains(paths, item.id)) {
+        fs.appendFileSync(path.join(paths.inboxDir, INBOX_JSONL_NAME), `${JSON.stringify({ id: item.id, mirroredAt: new Date().toISOString(), ...item.raw })}\n`, { mode: 0o600 });
+    }
     return dest;
 }
 export const INBOX_ERROR_BODY_MAX = 300;
@@ -148,7 +172,6 @@ export async function pollInboxOnce(deps) {
     const fresh = extractInboxItems(res.body).filter((i) => !seen.has(i.id));
     for (const item of fresh) {
         mirrorInboxItem(deps.paths, item);
-        seen.add(item.id);
         if (deps.ack) {
             try {
                 const status = await ackItem(token, item.id);
@@ -159,9 +182,12 @@ export async function pollInboxOnce(deps) {
                 deps.log("warn", `ack ${item.id} failed: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
+        // Persist each completed item before starting another one. If shutdown
+        // interrupts a later ack or mirror, earlier items will not be replayed.
+        seen.add(item.id);
+        writeSeenIds(deps.paths, seen);
     }
     if (fresh.length > 0) {
-        writeSeenIds(deps.paths, seen);
         deps.log("info", `inbox mirrored ${fresh.length} item(s)`);
         try {
             await warmCache(token, deps.agentUid);

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

@@ -27,6 +27,7 @@ import type { ControlRequest } from "./requests.js";
 import { syncPassResult } from "./sync-runner.js";
 export declare const STOP_ESCALATION_MS = 10000;
 export declare const CLI_UPDATE_SYNC_IDLE_MAX_MS: number;
+export declare const CLI_UPDATE_SYNC_IDLE_KILL_GRACE_MS = 60000;
 /** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
 export declare const HANDOFF_STAGGER_MS = 15000;
 /** How long a draining unit may take to finish its work before it gets SIGTERM. */

package/dist/lib/daemon/supervisor.js

@@ -28,6 +28,7 @@ const BACKOFF_MAX_MS = 60_000;
 const HEALTHY_RUN_MS = 60_000;
 export const STOP_ESCALATION_MS = 10_000;
 export const CLI_UPDATE_SYNC_IDLE_MAX_MS = 10 * 60_000;
+export const CLI_UPDATE_SYNC_IDLE_KILL_GRACE_MS = 60_000;
 const MESH_OWNER_RECHECK_MS = 15_000;
 const MESH_OWNER_LOG_INTERVAL_MS = 10 * 60_000;
 /** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
@@ -92,6 +93,7 @@ export function createSupervisor(deps) {
     let deferredCliRestart = false;
     let deferredCliRestartTimer;
     let cliRestartInProgress = false;
+    let pendingSyncCommandRestart;
     const snapshot = () => ({
         version: 1,
         pid: deps.pid,
@@ -125,15 +127,26 @@ export function createSupervisor(deps) {
             clearT(deferredCliRestartTimer);
         deferredCliRestartTimer = undefined;
     };
-    const runDeferredCliRestart = () => {
+    const clearPendingSyncCommandRestart = (slot) => {
+        if (!pendingSyncCommandRestart || (slot && pendingSyncCommandRestart.slot !== slot))
+            return;
+        if (pendingSyncCommandRestart.timer !== undefined)
+            clearT(pendingSyncCommandRestart.timer);
+        pendingSyncCommandRestart = undefined;
+    };
+    const runDeferredCliRestart = (idleTimeout = false) => {
         if (!deferredCliRestart)
             return;
+        clearPendingSyncCommandRestart();
         clearDeferredCliRestart();
         cliRestartInProgress = true;
         const sync = [...slots.values()].find((slot) => slot.plan.service === "sync" && slot.child);
-        if (sync)
-            terminate(sync);
-        deps.log("info", "sync runner is between passes; restarting daemon onto the updated CLI");
+        if (sync) {
+            terminate(sync, undefined, false, idleTimeout ? CLI_UPDATE_SYNC_IDLE_KILL_GRACE_MS : STOP_ESCALATION_MS);
+        }
+        deps.log(idleTimeout ? "warn" : "info", idleTimeout
+            ? "sync pass remained active for 10 minutes; restarting daemon onto the updated CLI"
+            : "sync runner is between passes; restarting daemon onto the updated CLI");
         const releaseHold = () => {
             cliRestartInProgress = false;
             const currentSync = [...slots.values()].find((slot) => slot.plan.service === "sync");
@@ -163,6 +176,17 @@ export function createSupervisor(deps) {
             releaseHold();
         }
     };
+    const finishPendingSyncCommandRestart = (idleTimeout = false) => {
+        const pending = pendingSyncCommandRestart;
+        if (!pending)
+            return;
+        clearPendingSyncCommandRestart(pending.slot);
+        if (deferredCliRestart) {
+            runDeferredCliRestart(idleTimeout);
+            return;
+        }
+        pending.onFinish(idleTimeout);
+    };
     const requestCliUpdateRestart = () => {
         if (!deps.restartDaemon)
             return;
@@ -173,7 +197,10 @@ export function createSupervisor(deps) {
         }
         if (sync.syncPassActive === false) {
             deferredCliRestart = true;
-            runDeferredCliRestart();
+            if (pendingSyncCommandRestart?.slot === sync)
+                finishPendingSyncCommandRestart();
+            else
+                runDeferredCliRestart();
             return;
         }
         if (deferredCliRestart) {
@@ -182,7 +209,25 @@ export function createSupervisor(deps) {
         }
         deferredCliRestart = true;
         deps.log("info", "deferring CLI-update restart until sync is idle (maximum 10 minutes)");
-        deferredCliRestartTimer = setT(runDeferredCliRestart, CLI_UPDATE_SYNC_IDLE_MAX_MS);
+        if (pendingSyncCommandRestart?.slot === sync)
+            return;
+        deferredCliRestartTimer = setT(() => runDeferredCliRestart(true), CLI_UPDATE_SYNC_IDLE_MAX_MS);
+    };
+    const deferSyncCommandRestart = (slot, onFinish) => {
+        if (slot.syncPassActive === false) {
+            onFinish(false);
+            return;
+        }
+        if (pendingSyncCommandRestart?.slot === slot)
+            return;
+        clearPendingSyncCommandRestart();
+        const pending = { slot, onFinish };
+        pendingSyncCommandRestart = pending;
+        deps.log("info", `deferring restart of ${slot.plan.id} until its sync pass is idle (maximum 10 minutes)`);
+        // A pending CLI restart already owns the same 10-minute idle window.
+        if (!deferredCliRestart) {
+            pending.timer = setT(() => finishPendingSyncCommandRestart(true), CLI_UPDATE_SYNC_IDLE_MAX_MS);
+        }
     };
     const setBlocked = (slot) => {
         const block = slot.plan.blocked;
@@ -204,7 +249,8 @@ export function createSupervisor(deps) {
      * `drain`, a unit that has a drain signal gets it first and SIGTERM only
      * after HANDOFF_DRAIN_MAX_MS; SIGKILL follows SIGTERM after STOP_ESCALATION_MS.
      */
-    const terminate = (slot, then, drain = false) => {
+    const terminate = (slot, then, drain = false, killGraceMs = STOP_ESCALATION_MS) => {
+        clearPendingSyncCommandRestart(slot);
         clearTimer(slot);
         clearHeartbeatTimer(slot);
         const child = slot.child;
@@ -227,9 +273,9 @@ export function createSupervisor(deps) {
                 slot.killTimer = undefined;
                 if (slot.child !== child)
                     return;
-                deps.log("warn", `${slot.plan.id} did not exit within ${STOP_ESCALATION_MS / 1_000} s of SIGTERM; sending SIGKILL${lastProtocolHint(slot)}`);
+                deps.log("warn", `${slot.plan.id} did not exit within ${killGraceMs / 1_000} s of SIGTERM; sending SIGKILL${lastProtocolHint(slot)}`);
                 signalChild(slot, child, "SIGKILL");
-            }, STOP_ESCALATION_MS);
+            }, killGraceMs);
         };
         const drainSignal = drain ? slot.plan.drainSignal : undefined;
         if (drainSignal) {
@@ -309,8 +355,12 @@ export function createSupervisor(deps) {
                         slot.syncPassActive = true;
                     }
                 }
-                if (deferredCliRestart && slot.syncPassActive === false)
-                    runDeferredCliRestart();
+                if (slot.syncPassActive === false) {
+                    if (pendingSyncCommandRestart?.slot === slot)
+                        finishPendingSyncCommandRestart();
+                    else if (deferredCliRestart)
+                        runDeferredCliRestart();
+                }
             }
             const at = now();
             slot.state.lastHeartbeatAt = new Date(at).toISOString();
@@ -357,6 +407,11 @@ export function createSupervisor(deps) {
             if (slot.child !== child)
                 return;
             slot.child = undefined;
+            if (pendingSyncCommandRestart?.slot === slot) {
+                clearPendingSyncCommandRestart(slot);
+                if (deferredCliRestart)
+                    runDeferredCliRestart();
+            }
             clearHeartbeatTimer(slot);
             if (slot.killTimer !== undefined) {
                 clearT(slot.killTimer);
@@ -628,6 +683,7 @@ export function createSupervisor(deps) {
             existing.blockedReads = 0;
             const adopted = existing.adopted === true;
             existing.adopted = false;
+            const hadDrainSignal = existing.plan.drainSignal !== undefined;
             const key = planKey(plan, deps.cliVersion);
             const wasBlocked = existing.plan.blocked !== undefined;
             const changed = key !== existing.key;
@@ -652,6 +708,34 @@ export function createSupervisor(deps) {
                 else
                     activate(existing);
             }
+            else if (changed && cliRestartInProgress && plan.service === "sync" && existing.child) {
+                // The deferred CLI restart owns this stop; do not queue a second
+                // replacement through the adopted-unit handoff path.
+                terminate(existing);
+            }
+            else if (changed && plan.service === "sync" && existing.child) {
+                existing.attempts = 0;
+                existing.state.restarts = 0;
+                const replaceWhenIdle = () => {
+                    if (adopted) {
+                        deps.log("info", `will replace ${plan.id}: it runs an older CLI or command`);
+                        handoffQueue.push(existing);
+                        pumpHandoff();
+                    }
+                    else {
+                        deps.log("info", `restarting ${plan.id}: its command changed`);
+                        terminate(existing, () => activate(existing));
+                    }
+                };
+                deferSyncCommandRestart(existing, (idleTimeout) => {
+                    if (!idleTimeout) {
+                        replaceWhenIdle();
+                        return;
+                    }
+                    deps.log("warn", `${plan.id} sync pass did not become idle within 10 minutes; stopping it to apply the changed command`);
+                    terminate(existing, () => activate(existing), false, CLI_UPDATE_SYNC_IDLE_KILL_GRACE_MS);
+                });
+            }
             else if (changed && adopted && existing.child) {
                 deps.log("info", `will replace ${plan.id}: it runs an older CLI or command`);
                 handoffQueue.push(existing);
@@ -663,7 +747,7 @@ export function createSupervisor(deps) {
                 if (cliRestartInProgress && plan.service === "sync")
                     terminate(existing);
                 else
-                    terminate(existing, () => activate(existing));
+                    terminate(existing, () => activate(existing), hadDrainSignal);
             }
         }
         slots = next;
@@ -878,6 +962,7 @@ export function createSupervisor(deps) {
             if (handoffTimer !== undefined)
                 clearT(handoffTimer);
             clearDeferredCliRestart();
+            clearPendingSyncCommandRestart();
             const childOwners = new Map();
             for (const slot of slots.values()) {
                 if (slot.child)

package/dist/lib/doctor/__testing__/fake-hq-tree.d.ts

@@ -25,7 +25,7 @@
  * which stands up a throwaway HQ tree with `mktemp -d` and stubbed hook scripts.
  */
 /** Claude/Codex lifecycle events a hook can be registered against. */
-export type HookEventName = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "SessionStart" | "Stop" | "SubagentStop" | "PreCompact" | "Notification";
+type HookEventName = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "SessionStart" | "Stop" | "SubagentStop" | "PreCompact" | "Notification";
 /** The three `hook-gate.sh` allowlist profiles. */
 export type GateProfile = "minimal" | "standard" | "strict";
 /** Canonical ordering of the gate profiles. */
@@ -35,7 +35,7 @@ export declare const GATE_PROFILES: readonly GateProfile[];
  * canonical `.claude/hooks/` scripts; only Codex runs duplicated copies, so the
  * Codex mirror is the entire drift surface the doctor has to watch.
  */
-export interface FakeCodexMirrorSpec {
+interface FakeCodexMirrorSpec {
     /** Whether the mirror file is written to `.codex/hooks/`. Default: true. */
     present?: boolean;
     /**
@@ -99,7 +99,7 @@ export interface FakeHookSpec {
  * written by default (declare a hook's `codex` spec explicitly, or set
  * `legacyHooksJson`, to model pre-adapter leftovers).
  */
-export interface FakeCodexAdapterSpec {
+interface FakeCodexAdapterSpec {
     /** Events wired to the adapter in config.toml. Default: the shipped eight. */
     events?: string[];
     /** Whether the adapter script is written. Default: true. */
@@ -111,10 +111,8 @@ export interface FakeCodexAdapterSpec {
     /** Whether a leftover `.codex/hooks.json` is still written. Default: false. */
     legacyHooksJson?: boolean;
 }
-/** The lifecycle events the shipped `.codex/config.toml` wires. */
-export declare const ADAPTER_DEFAULT_EVENTS: readonly string[];
 /** Declares the `.grok/hooks/` state. */
-export interface FakeGrokSpec {
+interface FakeGrokSpec {
     /** Whether the `.grok/hooks/` scaffold is created at all. Default: true. */
     present?: boolean;
     /** Whether `hq-grok-hook-adapter.sh` carries the executable bit. Default: true. */
@@ -147,7 +145,7 @@ export interface FakeHqTreeSpec {
     prefix?: string;
 }
 /** Manifest entry describing a materialised Codex mirror. */
-export interface FakeCodexManifestEntry {
+interface FakeCodexManifestEntry {
     /** Absolute path where the mirror lives (whether or not it was written). */
     scriptPath: string;
     /** Whether the mirror file exists on disk. */
@@ -162,7 +160,7 @@ export interface FakeCodexManifestEntry {
     drifted: boolean;
 }
 /** Manifest entry describing a materialised hook across all platforms. */
-export interface FakeHookManifestEntry {
+interface FakeHookManifestEntry {
     id: string;
     /** Absolute path of the Claude script (whether or not it was written). */
     scriptPath: string;
@@ -184,7 +182,7 @@ export interface FakeHookManifestEntry {
     codex: FakeCodexManifestEntry | null;
 }
 /** A structured description of everything {@link buildFakeHqTree} wrote. */
-export interface FakeHqTreeManifest {
+interface FakeHqTreeManifest {
     root: string;
     claudeSettingsPath: string;
     claudeHooksDir: string;
@@ -224,4 +222,5 @@ export declare function trackedFakeHqTreeRoots(): string[];
  * when the process exits.
  */
 export declare function buildFakeHqTree(spec?: FakeHqTreeSpec): FakeHqTree;
+export {};
 //# sourceMappingURL=fake-hq-tree.d.ts.map

package/dist/lib/doctor/__testing__/fake-hq-tree.js

@@ -39,7 +39,7 @@ const EXECUTABLE_MODE = 0o755;
 const NON_EXECUTABLE_MODE = 0o644;
 const DEFAULT_PREFIX = "hq-doctor-fake-";
 /** The lifecycle events the shipped `.codex/config.toml` wires. */
-export const ADAPTER_DEFAULT_EVENTS = [
+const ADAPTER_DEFAULT_EVENTS = [
     "SessionStart",
     "UserPromptSubmit",
     "PreToolUse",