@indigoai-us/hq-cli 5.342.11 → 5.342.12

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.342.12] — 2026-10-04
+
+- Record every lane worker resume with its launch time and trigger, and classify watcher, monitor-event, and pending-work wakes separately from keep-alive timer accuracy.
+
+- Hand off the package-use lease through a non-JSON marker after a re-executed CLI publishes its matching lease, and forward parent-only stop signals to the child.
+
 ## [5.342.11] — 2026-10-04
 - Release the CLI package-use lease before interactive login waits after resident modules preload.
 - Show the cached version update nudge after interactive commands when a newer cached release remains and its feature flag is enabled; avoid waiting for registry readiness when there is no nudge to show or repeating guidance after the updater already reported its result.

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

@@ -11147,7 +11147,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "keep-alive-audit";
-        readonly description: "Audit lead lane keep-alive timing. A later envelope proves another turn ran and may reclassify an expired stop as restarted_untimed when no launch record remains; late_restarts_after_window counts known launches after the grace window.";
+        readonly description: "Audit lead lane keep-alive timing. Durable worker-resume events retain launch time and trigger after bounded lane history rolls over; late_restarts_after_window counts known launches after the grace window.";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;

package/dist/command-catalog.generated.js

@@ -13537,7 +13537,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "keep-alive-audit",
-                "description": "Audit lead lane keep-alive timing. A later envelope proves another turn ran and may reclassify an expired stop as restarted_untimed when no launch record remains; late_restarts_after_window counts known launches after the grace window.",
+                "description": "Audit lead lane keep-alive timing. Durable worker-resume events retain launch time and trigger after bounded lane history rolls over; late_restarts_after_window counts known launches after the grace window.",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,

package/dist/commands/lanes-keep-alive-audit.js

@@ -2,7 +2,7 @@ import { buildKeepAliveAudit, formatKeepAliveAuditText } from "../lib/lanes/keep
 export function registerLaneKeepAliveAuditCommand(parent, deps) {
     parent
         .command("keep-alive-audit")
-        .description("Audit lead lane keep-alive timing. A later envelope proves another turn ran and may reclassify an expired stop as restarted_untimed when no launch record remains; late_restarts_after_window counts known launches after the grace window.")
+        .description("Audit lead lane keep-alive timing. Durable worker-resume events retain launch time and trigger after bounded lane history rolls over; late_restarts_after_window counts known launches after the grace window.")
         .option("--since <iso>", "Include stopped turns at or after this ISO date-time")
         .option("--lane <id>", "Audit one exact lane id")
         .option("--json", "Print the report as JSON")

package/dist/lib/lanes/keep-alive-audit.d.ts

@@ -1,8 +1,9 @@
-type KeepAliveAuditVerdict = "on_time" | "late" | "early_wake" | "message_wake" | "self_wake" | "early_by_keep_alive" | "restarted_untimed" | "not_restarted" | "keep_alive_off" | "waiting";
+type KeepAliveAuditVerdict = "on_time" | "late" | "early_wake" | "message_wake" | "work_triggered" | "self_wake" | "early_by_keep_alive" | "restarted_untimed" | "not_restarted" | "keep_alive_off" | "waiting";
 interface KeepAliveAuditRestart {
     at: string | null;
     trigger: string;
     caller: string | null;
+    workerEvent?: boolean;
 }
 interface KeepAliveAuditRow {
     lane: string;

package/dist/lib/lanes/keep-alive-audit.js

@@ -55,6 +55,7 @@ const VERDICTS = [
     "late",
     "early_wake",
     "message_wake",
+    "work_triggered",
     "self_wake",
     "early_by_keep_alive",
     "restarted_untimed",
@@ -68,6 +69,50 @@ function parseTime(value) {
     const parsed = Date.parse(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
+function readLaneWorkerResumeEvents(hqRoot, laneId) {
+    const root = fs.realpathSync(hqRoot);
+    const eventsPath = path.join(laneRunDir(root, laneId), "watcher", "events.jsonl");
+    if (!withinRoot(root, eventsPath)) {
+        throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher event path escapes the HQ root for ${laneId}`, { lane_id: laneId });
+    }
+    let text;
+    try {
+        const stat = fs.lstatSync(eventsPath);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane watcher events must be a regular file: ${eventsPath}`, { lane_id: laneId, path: eventsPath });
+        }
+        const realPath = fs.realpathSync(eventsPath);
+        if (!withinRoot(root, realPath)) {
+            throw new LanesError("keep_alive_audit_path_invalid", `Lane watcher event file escapes the HQ root for ${laneId}`, { lane_id: laneId, path: eventsPath });
+        }
+        text = fs.readFileSync(realPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const events = [];
+    for (const [index, line] of text.split(/\r?\n/).entries()) {
+        if (!line.trim())
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(value) || value.event !== "lane_worker_resumed")
+            continue;
+        const at = parseTime(value.resumed_at);
+        if (at === undefined || typeof value.reason !== "string" || !value.reason.trim()) {
+            throw new LanesError("keep_alive_audit_event_invalid", `Lane worker resume event has invalid timing or reason: ${eventsPath}:${index + 1}`, { lane_id: laneId, path: eventsPath, line: index + 1 });
+        }
+        events.push({ at, reason: value.reason, caller: typeof value.caller === "string" ? value.caller : null });
+    }
+    return events.sort((a, b) => a.at - b.at);
+}
 function iso(ms) {
     return new Date(ms).toISOString();
 }
@@ -176,9 +221,7 @@ function readKeepAliveResumeEvents(hqRoot, laneId) {
         if (nextEligibleAt === undefined) {
             throw new LanesError("keep_alive_audit_event_invalid", `Keep-alive resume event has invalid timing fields: ${eventsPath}:${index + 1}`, { lane_id: laneId, path: eventsPath, line: index + 1 });
         }
-        const reason = value.reason === "pending_work" || value.reason === "next_check_at_due" || value.reason === "backoff"
-            ? value.reason
-            : undefined;
+        const reason = typeof value.reason === "string" ? value.reason : undefined;
         events.push({ at, nextEligibleAt, ...(reason === undefined ? {} : { reason }) });
     }
     return events.sort((a, b) => a.at - b.at);
@@ -286,7 +329,18 @@ function laneWasKeepAliveOffAtStop(lane, stoppedAt) {
     const optedInAt = parseTime(lane.keep_alive_opted_in_at);
     return optedInAt === undefined || optedInAt > stoppedAt;
 }
-function firstRestartAfter(lane, stop, nextEnvelopeMs) {
+function firstRestartAfter(lane, stop, nextEnvelopeMs, workerResumeEvents) {
+    const recordedWorkerResume = workerResumeEvents
+        .filter((event) => event.at > stop.mtimeMs && (nextEnvelopeMs === undefined || event.at < nextEnvelopeMs))
+        .sort((a, b) => a.at - b.at)[0];
+    if (recordedWorkerResume !== undefined) {
+        return {
+            at: iso(recordedWorkerResume.at),
+            trigger: recordedWorkerResume.reason,
+            caller: recordedWorkerResume.caller,
+            workerEvent: true,
+        };
+    }
     const restart = (lane.resume_history ?? [])
         .map((entry) => ({ entry, at: parseTime(entry.at) }))
         .filter(({ entry, at }) => at !== undefined && at > stop.mtimeMs && (nextEnvelopeMs === undefined || at < nextEnvelopeMs) && typeof entry.trigger === "string")
@@ -329,6 +383,14 @@ function classifyVerdict(input) {
     if (restart?.trigger === "unknown" && laneWasKeepAliveOffAtStop(lane, input.stoppedAt))
         return "keep_alive_off";
     if (restart) {
+        if (restart.trigger === "pending_work" || restart.trigger === "watcher" || restart.trigger === "monitor_event")
+            return "work_triggered";
+        const workEvidenceEnd = input.nextEnvelopeAt ?? Number.POSITIVE_INFINITY;
+        const triggeredWork = restart.workerEvent !== true && input.resumeEvents
+            .filter((event) => event.at > input.stoppedAt && event.at < workEvidenceEnd && event.at <= (restart.at === null ? Number.POSITIVE_INFINITY : Date.parse(restart.at)))
+            .some((event) => event.reason === "pending_work" || event.reason === "watcher" || event.reason === "monitor_event");
+        if (triggeredWork)
+            return "work_triggered";
         if (restart.at === null)
             return "restarted_untimed";
         const restartAt = Date.parse(restart.at);
@@ -336,12 +398,14 @@ function classifyVerdict(input) {
             return "self_wake";
         if (restart.trigger === "message" || restart.trigger === "answered_questions")
             return "message_wake";
-        if (restart.trigger === "keep_alive") {
+        if (restart.trigger === "keep_alive" || restart.trigger === "next_check_at_due" || restart.trigger === "backoff") {
             const event = input.resumeEvents
                 .filter((candidate) => candidate.at > input.stoppedAt && candidate.at <= restartAt + 2 * 60_000)
                 .sort((left, right) => Math.abs(left.at - restartAt) - Math.abs(right.at - restartAt))[0];
             if (event?.reason === "pending_work")
-                return "message_wake";
+                return "work_triggered";
+            if (event?.reason === "watcher" || event?.reason === "monitor_event")
+                return "work_triggered";
             if (event?.reason === undefined &&
                 (hasDeliveredDropboxEvidence(input.hqRoot, lane.lane_id, input.stoppedAt, restartAt) ||
                     hasMessageResumeEvidence(lane, input.stoppedAt, restartAt) ||
@@ -384,6 +448,7 @@ export function buildKeepAliveAudit(input) {
         try {
             const { allMtimes, stops } = readStopEnvelopes(input.hqRoot, lane.lane_id);
             const keepAliveResumeEvents = readKeepAliveResumeEvents(input.hqRoot, lane.lane_id);
+            const laneWorkerResumeEvents = readLaneWorkerResumeEvents(input.hqRoot, lane.lane_id);
             const doneClassifications = readDoneClassifications(input.hqRoot, lane.lane_id);
             for (const stop of stops) {
                 if (stop.mtimeMs < sinceMs || stop.mtimeMs > nowMs)
@@ -391,7 +456,7 @@ export function buildKeepAliveAudit(input) {
                 if (!doneClassifications.some((at) => at >= stop.mtimeMs && at - stop.mtimeMs <= 10 * 60_000))
                     continue;
                 const nextEnvelopeMs = allMtimes.find((mtime) => mtime > stop.mtimeMs);
-                const restart = firstRestartAfter(lane, stop, nextEnvelopeMs);
+                const restart = firstRestartAfter(lane, stop, nextEnvelopeMs, laneWorkerResumeEvents);
                 const due = dueTime(stop, keepAliveResumeEvents);
                 rows.push({
                     lane: lane.lane_id,
@@ -402,7 +467,7 @@ export function buildKeepAliveAudit(input) {
                     due_at: iso(due.at),
                     due_reason: due.reason,
                     restart,
-                    verdict: classifyVerdict({ dueAt: due.at, stoppedAt: stop.mtimeMs, nextCheckAt: stop.nextCheckAt, restart, lane, nowMs, resumeEvents: keepAliveResumeEvents, hqRoot: input.hqRoot }),
+                    verdict: classifyVerdict({ dueAt: due.at, stoppedAt: stop.mtimeMs, nextCheckAt: stop.nextCheckAt, restart, lane, nowMs, resumeEvents: keepAliveResumeEvents, ...(nextEnvelopeMs === undefined ? {} : { nextEnvelopeAt: nextEnvelopeMs }), hqRoot: input.hqRoot }),
                 });
             }
         }

package/dist/lib/lanes/spawn.js

@@ -56,6 +56,70 @@ const PROVIDER_COMMAND = {
     codex: "codex",
     grok: "grok",
 };
+function keepAliveResumeReason(runDir, pendingResume) {
+    if (pendingResume?.keep_alive !== true || typeof pendingResume.at !== "string")
+        return undefined;
+    const eventsPath = path.join(runDir, "watcher", "events.jsonl");
+    let content;
+    try {
+        content = fs.readFileSync(eventsPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "keep_alive";
+        throw err;
+    }
+    for (const line of content.split(/\r?\n/).reverse()) {
+        if (!line.trim())
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            const event = value;
+            if (event.event === "keep_alive_resume" && event.at === pendingResume.at && typeof event.reason === "string") {
+                return event.reason;
+            }
+        }
+    }
+    return "keep_alive";
+}
+function appendLaneWorkerResumeEvent(input) {
+    const eventsPath = path.join(laneRunDir(input.hqRoot, input.laneId), "watcher", "events.jsonl");
+    fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
+    let separator = "";
+    try {
+        const fd = fs.openSync(eventsPath, "r");
+        try {
+            const size = fs.fstatSync(fd).size;
+            if (size > 0) {
+                const lastByte = Buffer.alloc(1);
+                fs.readSync(fd, lastByte, 0, 1, size - 1);
+                if (lastByte[0] !== 0x0a)
+                    separator = "\n";
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    fs.appendFileSync(eventsPath, `${separator}${JSON.stringify({
+        event: "lane_worker_resumed",
+        lane_id: input.laneId,
+        resumed_at: input.resumedAt,
+        reason: input.reason,
+        ...(input.caller === undefined ? {} : { caller: input.caller }),
+        ...(input.turnId === undefined ? {} : { turn_id: input.turnId }),
+    })}\n`, "utf8");
+}
 export function providerCommandOnPath(command, pathEnv) {
     // Test and embedded callers can intentionally omit PATH and delegate lookup
     // to their spawn implementation. A present PATH is authoritative.
@@ -2081,6 +2145,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             trigger.kind === "resume" || trigger.kind === "message"
             ? "user"
             : undefined);
+    const resumeReason = keepAliveResumeReason(runDir, pendingResume) ?? resumeHistoryTrigger;
     let statusGateHeartbeat;
     try {
         statusGateHeartbeat = managerStatusGateHeartbeat(hqRoot, existing, laneTurnId, nowIso);
@@ -2356,6 +2421,14 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 ...(resumeHistoryCaller ? { caller: resumeHistoryCaller } : {}),
             }),
         }));
+        appendLaneWorkerResumeEvent({
+            hqRoot,
+            laneId: lane.lane_id,
+            resumedAt: nowIso,
+            reason: resumeReason,
+            ...(resumeHistoryCaller === undefined ? {} : { caller: resumeHistoryCaller }),
+            turnId: laneTurnId,
+        });
     }
     return laneLaunchResult(readLane(hqRoot, lane.lane_id));
 }
@@ -2670,6 +2743,12 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
             ...(callerLaneId ? { caller: callerLaneId } : {}),
         }),
     }));
+    appendLaneWorkerResumeEvent({
+        hqRoot,
+        laneId: lane.lane_id,
+        resumedAt: startedAt,
+        reason: "envelope_repair",
+    });
     return workerPid;
 }
 export { PROVIDER_HOME_ENV, PROVIDER_COMMAND };

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

@@ -1,3 +1,4 @@
+export declare const PACKAGE_USE_LEASE_HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_LEASE_HANDOFF";
 export declare class PackageUseUpdatePendingError extends Error {
     constructor(message: string);
 }
@@ -10,11 +11,24 @@ export interface PackageUseLeaseRecord {
     start_time_ms: number;
     hq_version: string;
 }
+export interface PackageUseLeaseHandoff {
+    readonly envValue: string;
+    waitForChild(pid: number, childAlive: () => boolean): Promise<boolean>;
+    cleanup(): void;
+}
 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;
+/**
+ * Create a bounded, per-reexec rendezvous in the current lease directory.
+ * The child confirms readiness only after publishing its own atomic lease.
+ */
+export declare function createPackageUseLeaseHandoff(lease: PackageUseLease, timeoutMs?: number): PackageUseLeaseHandoff;
+export declare function createCurrentPackageUseLeaseHandoff(timeoutMs?: number): PackageUseLeaseHandoff | null;
+/** Publish this process's lease identity to a parent waiting in the same prefix. */
+export declare function publishPackageUseLeaseHandoff(lease: PackageUseLease, env?: NodeJS.ProcessEnv): boolean;
 export declare function acquireCurrentPackageUseLease(): PackageUseLease | null;
 /** Release this process's package-use lease after a long-running command has loaded its package modules. */
 export declare function releaseCurrentPackageUseLease(): void;
@@ -30,6 +44,7 @@ export declare function currentPackageUseUpdatePending(): boolean;
 export declare function currentPackageUseUpdateRequested(): boolean;
 export declare const __test__: {
     waitForUpdateRequest: typeof waitForUpdateRequest;
+    setCurrentPackageUseLease(lease: PackageUseLease | null): void;
 };
 export {};
 //# sourceMappingURL=package-use-lease.d.ts.map

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

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -6,6 +6,8 @@ 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 const PACKAGE_USE_LEASE_HANDOFF_ENV = "HQ_CLI_PACKAGE_USE_LEASE_HANDOFF";
+const HANDOFF_TIMEOUT_MS = 2_000;
 export class PackageUseUpdatePendingError extends Error {
     constructor(message) {
         super(message);
@@ -172,6 +174,93 @@ export function acquirePackageUseLease(prefix, hqVersion, stateDirectory) {
     }
     throw new PackageUseUpdatePendingError("An HQ CLI update is waiting for the package lease; retry when it finishes");
 }
+/**
+ * Create a bounded, per-reexec rendezvous in the current lease directory.
+ * The child confirms readiness only after publishing its own atomic lease.
+ */
+export function createPackageUseLeaseHandoff(lease, timeoutMs = HANDOFF_TIMEOUT_MS) {
+    const directory = path.dirname(lease.leasePath);
+    const markerPath = path.join(directory, `.reexec-${process.pid}-${randomBytes(12).toString("hex")}.handoff`);
+    let cleaned = false;
+    const cleanup = () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        process.removeListener("exit", cleanup);
+        try {
+            rmSync(markerPath, { force: true });
+            rmSync(`${markerPath}.tmp`, { force: true });
+        }
+        catch (error) {
+            process.stderr.write(`hq-cli package-use lease handoff cleanup failed (${errorLabel(error)})\n`);
+        }
+    };
+    process.once("exit", cleanup);
+    return {
+        envValue: markerPath,
+        async waitForChild(pid, childAlive) {
+            const deadline = Date.now() + timeoutMs;
+            while (childAlive() && Date.now() <= deadline) {
+                try {
+                    const marker = JSON.parse(readFileSync(markerPath, "utf8"));
+                    if (marker.pid === pid && Number.isSafeInteger(marker.start_time_ms) && typeof marker.lease_name === "string") {
+                        const leasePath = path.join(directory, marker.lease_name);
+                        if (path.basename(leasePath) === marker.lease_name) {
+                            const record = JSON.parse(readFileSync(leasePath, "utf8"));
+                            if (record.pid === pid && record.start_time_ms === marker.start_time_ms)
+                                return true;
+                        }
+                    }
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT" && !(error instanceof SyntaxError)) {
+                        process.stderr.write(`hq-cli package-use lease handoff check failed (${errorLabel(error)})\n`);
+                    }
+                }
+                await new Promise((resolve) => setTimeout(resolve, 25));
+            }
+            return false;
+        },
+        cleanup,
+    };
+}
+export function createCurrentPackageUseLeaseHandoff(timeoutMs = HANDOFF_TIMEOUT_MS) {
+    return currentPackageUseLease ? createPackageUseLeaseHandoff(currentPackageUseLease, timeoutMs) : null;
+}
+/** Publish this process's lease identity to a parent waiting in the same prefix. */
+export function publishPackageUseLeaseHandoff(lease, env = process.env) {
+    const markerPath = env[PACKAGE_USE_LEASE_HANDOFF_ENV];
+    if (!markerPath)
+        return false;
+    const directory = path.dirname(lease.leasePath);
+    if (path.dirname(path.resolve(markerPath)) !== path.resolve(directory)) {
+        delete env[PACKAGE_USE_LEASE_HANDOFF_ENV];
+        return false;
+    }
+    const match = /^(\d+)-(\d+)\.json$/.exec(path.basename(lease.leasePath));
+    if (!match || Number(match[1]) !== process.pid) {
+        delete env[PACKAGE_USE_LEASE_HANDOFF_ENV];
+        return false;
+    }
+    const record = {
+        pid: process.pid,
+        start_time_ms: Number(match[2]),
+        lease_name: path.basename(lease.leasePath),
+    };
+    const tempPath = `${markerPath}.tmp`;
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 });
+        renameSync(tempPath, markerPath);
+        delete env[PACKAGE_USE_LEASE_HANDOFF_ENV];
+        return true;
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        delete env[PACKAGE_USE_LEASE_HANDOFF_ENV];
+        process.stderr.write(`hq-cli package-use lease handoff publish failed (${errorLabel(error)})\n`);
+        return false;
+    }
+}
 function exists(file) {
     try {
         readFileSync(file);
@@ -198,6 +287,7 @@ export function acquireCurrentPackageUseLease() {
     }
     const lease = acquirePackageUseLease(prefix, pkg.version);
     currentPackageUseLease = lease;
+    publishPackageUseLeaseHandoff(lease);
     return lease;
 }
 /** Release this process's package-use lease after a long-running command has loaded its package modules. */
@@ -260,5 +350,8 @@ export function currentPackageUseUpdateRequested() {
 }
 export const __test__ = {
     waitForUpdateRequest,
+    setCurrentPackageUseLease(lease) {
+        currentPackageUseLease = lease;
+    },
 };
 //# sourceMappingURL=package-use-lease.js.map

package/dist/utils/self-update.d.ts

@@ -56,6 +56,7 @@
  * Opt-outs: `HQ_NO_UPDATE_CHECK=1` (the shared knob that also silences
  * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
  */
+import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import { type RunningInstall, type UpdateResult } from "./version-gate.js";
 import { type RestartDaemonResult } from "../lib/mesh/live/daemon/install.js";
@@ -145,6 +146,10 @@ export interface SelfUpdateDeps {
     renamePath?: typeof fs.renameSync;
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
     reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
+    /** Async process-spawn seam for lease handoff tests. */
+    spawnReexec?: typeof spawn;
+    /** stdin TTY probe for re-exec signal forwarding tests. */
+    stdinIsTTY?: () => boolean;
     acquireLock?: () => (() => void) | null;
     /**
      * Read-your-writes convergence check run after a "successful" install:

package/dist/utils/self-update.js

@@ -56,7 +56,7 @@
  * Opt-outs: `HQ_NO_UPDATE_CHECK=1` (the shared knob that also silences
  * version-check), `hq rescue --no-self-update`, and the re-exec guard env.
  */
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -70,6 +70,7 @@ import { canStageInstall, stagedNpmInstall } from "./staged-install.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
 import { restartDaemonServiceIfInstalled } from "../lib/mesh/live/daemon/install.js";
+import { createCurrentPackageUseLeaseHandoff, PACKAGE_USE_LEASE_HANDOFF_ENV, releaseCurrentPackageUseLease, } from "./package-use-lease.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
  * One update + one re-exec per user invocation, ever.
@@ -596,18 +597,101 @@ export function acquireUpdateLock(now = Date.now()) {
  * command. Returns the child's exit status, or null when the child could not be
  * started at all (e.g. `hq` not on PATH in a minimal-PATH parent).
  */
-function reexecHq(argv, env) {
+async function reexecHq(argv, env, spawnProcess = spawn, stdinIsTTY = () => process.stdin.isTTY === true) {
     const plan = buildSpawnPlan("hq", argv);
-    const result = spawnSync(plan.cmd, plan.args, {
-        stdio: "inherit",
-        shell: plan.shell,
-        env,
-    });
-    if (result.error)
+    const handoff = createCurrentPackageUseLeaseHandoff();
+    const childEnv = handoff
+        ? { ...env, [PACKAGE_USE_LEASE_HANDOFF_ENV]: handoff.envValue }
+        : env;
+    let childForSignals;
+    let childSpawned = false;
+    let childClosed = false;
+    let spawnedChild;
+    const pendingSignals = [];
+    const reexecSignals = process.platform === "win32"
+        ? ["SIGINT", "SIGTERM"]
+        : ["SIGINT", "SIGTERM", "SIGHUP"];
+    const forwardSignal = (signal) => {
+        if (signal === "SIGINT" && stdinIsTTY())
+            return;
+        if (childClosed)
+            return;
+        if (!childForSignals || !childSpawned) {
+            pendingSignals.push(signal);
+            return;
+        }
+        if (childForSignals.exitCode === null && childForSignals.signalCode === null) {
+            childForSignals.kill(signal);
+        }
+    };
+    const signalHandlers = new Map(reexecSignals.map((signal) => [signal, () => forwardSignal(signal)]));
+    for (const [signal, handler] of signalHandlers)
+        process.on(signal, handler);
+    const removeSignalHandlers = () => {
+        for (const [signal, handler] of signalHandlers)
+            process.removeListener(signal, handler);
+    };
+    // spawnSync left default parent signal handling in place, so a parent-only
+    // SIGTERM or SIGHUP could terminate it. Forward stop signals to the async
+    // child while keeping this process waiting for the child's exit status.
+    try {
+        spawnedChild = spawnProcess(plan.cmd, plan.args, {
+            stdio: "inherit",
+            shell: plan.shell,
+            env: childEnv,
+        });
+        childForSignals = spawnedChild;
+    }
+    catch (error) {
+        removeSignalHandlers();
+        handoff?.cleanup();
+        process.stderr.write(`hq-cli re-exec spawn failed (${reexecErrorClass(error)})\n`);
         return null;
-    // A signal-killed child has status null; surface it as a failure exit rather
-    // than pretending the command completed.
-    return result.status ?? 1;
+    }
+    return new Promise((resolve) => {
+        let alive = true;
+        let spawnFailed = false;
+        spawnedChild.once("error", (error) => {
+            spawnFailed = true;
+            process.stderr.write(`hq-cli re-exec spawn failed (${reexecErrorClass(error)})\n`);
+        });
+        spawnedChild.once("spawn", () => {
+            childSpawned = true;
+            for (const signal of pendingSignals.splice(0)) {
+                if (spawnedChild.exitCode === null && spawnedChild.signalCode === null)
+                    spawnedChild.kill(signal);
+            }
+            if (!handoff || spawnedChild.pid === undefined)
+                return;
+            void handoff.waitForChild(spawnedChild.pid, () => alive).then((matched) => {
+                if (matched && alive) {
+                    releaseCurrentPackageUseLease();
+                    handoff.cleanup();
+                }
+            }).catch((error) => {
+                process.stderr.write(`hq-cli package-use lease handoff wait failed (${error instanceof Error ? error.name : "unknown"})\n`);
+            });
+        });
+        spawnedChild.once("close", (code, _signal) => {
+            alive = false;
+            childClosed = true;
+            pendingSignals.length = 0;
+            removeSignalHandlers();
+            handoff?.cleanup();
+            // The former spawnSync path returned null on spawn failure and 1 for a signal.
+            resolve(spawnFailed ? null : code ?? 1);
+        });
+    });
+}
+function reexecErrorClass(error) {
+    if (error && typeof error === "object") {
+        const code = error.code;
+        if (typeof code === "string" && /^[A-Z0-9_]{1,32}$/.test(code))
+            return code;
+        if (error instanceof Error)
+            return error.name;
+    }
+    return "unknown";
 }
 async function updateAndReexec(argv, flavor, known, deps) {
     const env = deps.env ?? process.env;
@@ -829,7 +913,11 @@ async function updateAndReexec(argv, flavor, known, deps) {
         return { action: "updated", latest };
     }
     const childEnv = { ...env, [REEXEC_GUARD_ENV]: "1" };
-    const status = (deps.reexec ?? reexecHq)([...argv.slice(2)], childEnv);
+    const status = deps.spawnReexec
+        ? await reexecHq([...argv.slice(2)], childEnv, deps.spawnReexec, deps.stdinIsTTY)
+        : deps.reexec
+            ? deps.reexec([...argv.slice(2)], childEnv)
+            : await reexecHq([...argv.slice(2)], childEnv, spawn, deps.stdinIsTTY);
     if (status === null) {
         console.error(chalk.yellow(`⚠ Updated hq-cli to ${latest}, but couldn't re-launch \`hq\` from PATH; ` +
             `continuing the ${flavor.noun} on ${current}.`));

package/package.json

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