@indigoai-us/hq-cli 5.202.1 → 5.204.0

package/dist/lib/monitor.js

@@ -0,0 +1,519 @@
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { formatMonitorEvent as formatDropboxMonitorEvent } from "./lanes/dropbox.js";
+import { LanesError } from "./lanes/errors.js";
+import { readProcStarttime } from "./lanes/spawn.js";
+export const MONITOR_SCHEMA_VERSION = "hq-monitor.v1";
+export const MONITOR_FLAG = "monitor.enabled";
+export const MONITOR_FLAG_DEFAULT = false;
+export const MONITOR_DEFAULT_TIMEOUT_MS = 5 * 60_000;
+export const MONITOR_DEFAULT_CHECKIN_MS = 55 * 60_000;
+export const MONITOR_PROMPT_CACHE_TTL_MS = 60 * 60_000;
+export const MONITOR_BATCH_WINDOW_MS = 200;
+export const MONITOR_POLL_INTERVAL_MS = 1_000;
+export const MONITOR_RATE_WINDOW_MS = 10_000;
+/** Sustained stdout floods stop after 3 windows; the per-window cap can be overridden with HQ_MONITOR_MAX_EVENTS_PER_WINDOW. */
+export const MONITOR_MAX_EVENTS_PER_WINDOW = 60;
+export const MONITOR_MAX_FLOOD_WINDOWS = 3;
+export const MONITOR_LOCK_STALE_MS = 30_000;
+export const MONITOR_MAX_TIMER_DELAY_MS = 2_147_000_000;
+const SESSION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const SAFE_LANE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const RUNTIME_ENV = {
+    claude: "CLAUDE_CODE_SESSION_ID",
+    codex: "CODEX_THREAD_ID",
+    grok: "GROK_SESSION_ID",
+};
+const RUNTIME_COMMANDS = new Set(["claude", "codex", "grok"]);
+function monitorError(error, message, details = {}) {
+    return new LanesError(error, message, details);
+}
+/** This guard is first in monitor start so a conflicting invocation has no side effects. */
+export function assertMonitorTimeoutCompatibility(persistent, timeoutProvided) {
+    if (persistent && timeoutProvided) {
+        throw monitorError("persistent_timeout_conflict", "--persistent cannot be used with --timeout.", {});
+    }
+}
+export function parseMonitorDuration(value, kind) {
+    const errorName = kind === "timeout" ? "monitor_timeout_invalid" : "monitor_checkin_invalid";
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/i.exec(value.trim());
+    if (!match) {
+        throw monitorError(errorName, `Invalid --${kind} duration ${JSON.stringify(value)}. Use a number with optional ms, s, m, or h suffix.`, { value });
+    }
+    const amount = Number(match[1]);
+    const unit = (match[2] ?? "ms").toLowerCase();
+    const multiplier = unit === "h" ? 3_600_000 : unit === "m" ? 60_000 : unit === "s" ? 1_000 : 1;
+    const milliseconds = amount * multiplier;
+    if (!Number.isFinite(milliseconds) || milliseconds <= 0 || milliseconds > Number.MAX_SAFE_INTEGER) {
+        throw monitorError(errorName, `Invalid --${kind} duration ${JSON.stringify(value)}. Duration must be positive and finite.`, { value });
+    }
+    const rounded = Math.ceil(milliseconds);
+    if (kind === "checkin" && rounded >= MONITOR_PROMPT_CACHE_TTL_MS) {
+        throw monitorError("checkin_exceeds_cache_ttl", "--checkin must be less than 60 minutes so the prompt cache can be reused.", { checkin_ms: rounded, cache_ttl_ms: MONITOR_PROMPT_CACHE_TTL_MS });
+    }
+    return rounded;
+}
+function assertLaneTargetId(laneId) {
+    if (!SAFE_LANE_ID_RE.test(laneId) || laneId === "." || laneId === "..") {
+        throw monitorError("monitor_target_invalid", `Invalid lane target ${JSON.stringify(laneId)}.`, { lane_id: laneId });
+    }
+}
+export function assertMonitorSessionId(sessionId) {
+    if (!SESSION_ID_RE.test(sessionId)) {
+        throw monitorError("monitor_session_id_invalid", "Session ids must contain only letters, numbers, underscores, or hyphens and be 1–128 characters long.", { session_id: sessionId });
+    }
+}
+export function parseMonitorTarget(value) {
+    const laneMatch = /^lane:(.+)$/.exec(value);
+    if (laneMatch?.[1]) {
+        assertLaneTargetId(laneMatch[1]);
+        return { kind: "lane", laneId: laneMatch[1] };
+    }
+    const sessionMatch = /^session:(claude|codex|grok):(.+)$/.exec(value);
+    if (sessionMatch?.[1] && sessionMatch[2]) {
+        const provider = sessionMatch[1];
+        assertMonitorSessionId(sessionMatch[2]);
+        return { kind: "session", provider, sessionId: sessionMatch[2] };
+    }
+    throw monitorError("monitor_target_invalid", "--target must be lane:<lane-id> or session:<claude|codex|grok>:<session-id>.", { target: value });
+}
+export function monitorTargetKey(target) {
+    return target.kind === "lane"
+        ? `lane:${target.laneId}`
+        : `session:${target.provider}:${target.sessionId}`;
+}
+export function detectMonitorTarget(options) {
+    const laneId = options.env.HQ_LANE_ID?.trim();
+    if (laneId) {
+        assertLaneTargetId(laneId);
+        return { kind: "lane", laneId };
+    }
+    const runtime = findNearestMonitorRuntime({
+        parentPid: options.parentPid,
+        readProcess: options.readProcess,
+    });
+    if (runtime) {
+        const provider = runtime.provider;
+        const sessionId = options.env[RUNTIME_ENV[provider]]?.trim() ?? "";
+        if (!sessionId) {
+            throw monitorError("monitor_target_unresolved", `Found ${provider} in the parent process chain but ${RUNTIME_ENV[provider]} is unset; pass --target explicitly.`, { provider, env_var: RUNTIME_ENV[provider] });
+        }
+        assertMonitorSessionId(sessionId);
+        return { kind: "session", provider, sessionId };
+    }
+    throw monitorError("monitor_target_unresolved", "Could not find a Claude, Codex, or Grok session in the parent process chain; pass --target lane:<id> or --target session:<provider>:<id>.", {});
+}
+/** The nearest runtime process in the caller chain, shared by target detection and hook mapping. */
+export function findNearestMonitorRuntime(options) {
+    let pid = options.parentPid;
+    const visited = new Set();
+    while (Number.isInteger(pid) && pid > 1 && !visited.has(pid)) {
+        visited.add(pid);
+        const entry = options.readProcess(pid);
+        if (!entry)
+            return null;
+        const command = path.basename(entry.command).replace(/\.exe$/i, "").toLowerCase();
+        if (RUNTIME_COMMANDS.has(command))
+            return { provider: command, pid };
+        pid = entry.ppid;
+    }
+    return null;
+}
+export function monitorSessionDir(hqRoot, provider, sessionId) {
+    assertMonitorSessionId(sessionId);
+    return path.join(hqRoot, "workspace", "monitors", "sessions", `${provider}-${sessionId}`);
+}
+export function monitorSessionHasActiveMarkers(hqRoot, provider, sessionId) {
+    const activeDir = path.join(monitorSessionDir(hqRoot, provider, sessionId), "active");
+    try {
+        return fs.readdirSync(activeDir).some((name) => !name.startsWith("."));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+export function monitorSessionHasActiveMarkerForOwner(hqRoot, provider, sessionId, owner) {
+    const activeDir = path.join(monitorSessionDir(hqRoot, provider, sessionId), "active");
+    let names;
+    try {
+        names = fs.readdirSync(activeDir).filter((name) => !name.startsWith("."));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    return names.some((name) => {
+        const marker = JSON.parse(fs.readFileSync(path.join(activeDir, name), "utf8"));
+        const markerOwner = marker.owner;
+        return markerOwner !== undefined && markerOwner !== null
+            && markerOwner.pid === owner.pid
+            && markerOwner.starttime === owner.starttime;
+    });
+}
+export function monitorSessionHasInboxFile(hqRoot, provider, sessionId) {
+    return fs.existsSync(path.join(monitorSessionDir(hqRoot, provider, sessionId), "dropbox", "inbox.jsonl"));
+}
+export function monitorSessionInboxHasEvents(hqRoot, provider, sessionId) {
+    const inbox = path.join(monitorSessionDir(hqRoot, provider, sessionId), "dropbox", "inbox.jsonl");
+    try {
+        return fs.readFileSync(inbox, "utf8").split(/\r?\n/).some((line) => line.trim() !== "");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+export function monitorSessionHasWork(hqRoot, provider, sessionId) {
+    return monitorSessionHasActiveMarkers(hqRoot, provider, sessionId)
+        || monitorSessionHasInboxFile(hqRoot, provider, sessionId);
+}
+export function monitorDir(hqRoot, monitorId) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(monitorId)) {
+        throw monitorError("monitor_id_invalid", `Invalid monitor id ${JSON.stringify(monitorId)}.`, { monitor_id: monitorId });
+    }
+    return path.join(hqRoot, "workspace", "monitors", monitorId);
+}
+export function makeMonitorId() {
+    return `mon_${Date.now().toString(36)}_${randomUUID().replaceAll("-", "")}`;
+}
+export function formatMonitorEvent(input) {
+    return formatDropboxMonitorEvent({
+        text: input.text,
+        kind: "monitor_event",
+        monitor_id: input.monitorId,
+        description: input.description,
+        sequence: input.sequence,
+    });
+}
+export function nextMonitorEventSequence(state) {
+    return (state.event_sequence ?? 0) + 1;
+}
+export function nextMonitorTimeoutDelay(timeoutMs, elapsedMs) {
+    return Math.max(0, Math.min(timeoutMs - elapsedMs, MONITOR_MAX_TIMER_DELAY_MS));
+}
+export function recordMonitorEventState(state, event) {
+    return {
+        ...state,
+        event_sequence: event.seq,
+        event_count: state.event_count + (event.delivery === "delivered" ? 1 : 0),
+    };
+}
+/** Keep the supervisor alive until its command has closed so TERM escalation can run. */
+export function requestMonitorStop(childPid, terminate, finishWithoutChild) {
+    if (childPid === null) {
+        finishWithoutChild();
+        return;
+    }
+    terminate();
+}
+export function parseHookSessionId(payloadText) {
+    let payload;
+    try {
+        payload = JSON.parse(payloadText);
+    }
+    catch (err) {
+        throw monitorError("monitor_hook_payload_invalid", `Hook payload is not valid JSON: ${err instanceof Error ? err.message : String(err)}.`, {});
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        throw monitorError("monitor_hook_payload_invalid", "Hook payload must be a JSON object with session_id.", {});
+    }
+    const sessionId = payload.session_id;
+    if (typeof sessionId !== "string") {
+        throw monitorError("monitor_hook_session_id_missing", "Hook payload has no string session_id.", {});
+    }
+    assertMonitorSessionId(sessionId);
+    return sessionId;
+}
+export function recordHookSessionMapping(hqRoot, provider, environmentSessionId, payloadSessionId, runtime) {
+    assertMonitorSessionId(payloadSessionId);
+    const environmentId = environmentSessionId?.trim();
+    if (!environmentId || environmentId === payloadSessionId || !runtime || runtime.provider !== provider)
+        return;
+    assertMonitorSessionId(environmentId);
+    const mappingPath = sessionMappingPath(hqRoot, runtime);
+    writeJsonAtomic(mappingPath, {
+        provider,
+        runtime_pid: runtime.pid,
+        runtime_starttime: runtime.starttime,
+        environment_session_id: environmentId,
+        payload_session_id: payloadSessionId,
+    });
+}
+export function resolveMappedSessionId(hqRoot, provider, environmentSessionId, runtime) {
+    assertMonitorSessionId(environmentSessionId);
+    if (!runtime || runtime.provider !== provider)
+        return environmentSessionId;
+    const mappingPath = sessionMappingPath(hqRoot, runtime);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(mappingPath, "utf8"));
+        const mapped = parsed.payload_session_id;
+        if (parsed.provider === provider &&
+            parsed.runtime_pid === runtime.pid &&
+            parsed.runtime_starttime === runtime.starttime &&
+            parsed.environment_session_id === environmentSessionId &&
+            typeof mapped === "string") {
+            assertMonitorSessionId(mapped);
+            return mapped;
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw monitorError("monitor_session_map_unreadable", `Could not read session map: ${err instanceof Error ? err.message : String(err)}.`, { path: mappingPath });
+        }
+    }
+    return environmentSessionId;
+}
+function sessionMappingPath(hqRoot, runtime) {
+    return path.join(hqRoot, "workspace", "monitors", "session-map", `${runtime.provider}-${runtime.pid}-${runtime.starttime}.json`);
+}
+function writeJsonAtomic(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    try {
+        fs.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        fs.rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+function readJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw monitorError("monitor_state_unreadable", `Could not read ${filePath}: ${err instanceof Error ? err.message : String(err)}.`, { path: filePath });
+    }
+}
+function targetStorageDir(hqRoot, targetKey) {
+    const key = createHash("sha256").update(targetKey).digest("hex");
+    return path.join(hqRoot, "workspace", "monitors", "targets", key);
+}
+function defaultPidIsAlive(pid, starttime, readStarttime) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return false;
+        if (code !== "EPERM")
+            throw err;
+    }
+    if (starttime === null)
+        return true;
+    const current = readStarttime(pid);
+    return current === null || current === starttime;
+}
+async function acquireTargetLock(lockFile, deps) {
+    fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+    const token = randomUUID();
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const owner = { token, pid: process.pid, starttime: readProcStarttime(process.pid), at: deps.now().getTime() };
+        try {
+            fs.writeFileSync(lockFile, `${JSON.stringify(owner)}\n`, { flag: "wx", mode: 0o600 });
+            return { token, pid: owner.pid, starttime: owner.starttime };
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        const existing = readJson(lockFile);
+        if (existing && Number.isInteger(existing.pid)) {
+            const start = typeof existing.starttime === "number" ? existing.starttime : null;
+            if (deps.pidIsAlive(existing.pid, start))
+                return null;
+        }
+        else {
+            try {
+                const age = deps.now().getTime() - fs.statSync(lockFile).mtimeMs;
+                if (age < MONITOR_LOCK_STALE_MS)
+                    return null;
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                throw err;
+            }
+        }
+        try {
+            fs.unlinkSync(lockFile);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+    return null;
+}
+function releaseTargetLock(lockFile, token) {
+    const current = readJson(lockFile);
+    if (current?.token !== token)
+        return;
+    try {
+        fs.unlinkSync(lockFile);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}
+export async function withMonitorTargetLock(hqRoot, targetKey, operation, options = {}) {
+    const dir = targetStorageDir(hqRoot, targetKey);
+    const activityPath = path.join(dir, "activity.json");
+    const lockFile = path.join(dir, "activity.lock");
+    const deps = {
+        now: options.now ?? (() => new Date()),
+        pidIsAlive: options.pidIsAlive ?? ((pid, starttime) => defaultPidIsAlive(pid, starttime, readProcStarttime)),
+        sleep: options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    };
+    let owner = null;
+    for (let attempt = 0; attempt < 100 && owner === null; attempt += 1) {
+        owner = await acquireTargetLock(lockFile, deps);
+        if (owner === null)
+            await deps.sleep(10);
+    }
+    if (!owner)
+        throw monitorError("monitor_target_lock_busy", `Could not acquire target delivery lock for ${targetKey}.`, { target: targetKey });
+    try {
+        return await operation(activityPath);
+    }
+    finally {
+        releaseTargetLock(lockFile, owner.token);
+    }
+}
+export async function recordMonitorTargetDelivery(hqRoot, targetKey, now = () => new Date(), kind = "monitor_event") {
+    await withMonitorTargetLock(hqRoot, targetKey, (activityPath) => {
+        recordMonitorTargetDeliveryAtPath(activityPath, now, kind);
+    }, { now });
+}
+export async function recordMonitorTargetActivity(hqRoot, targetKey, now = () => new Date()) {
+    const target = parseMonitorTarget(targetKey);
+    if (target.kind === "session" && !monitorSessionHasWork(hqRoot, target.provider, target.sessionId))
+        return;
+    await withMonitorTargetLock(hqRoot, targetKey, (activityPath) => {
+        const current = readJson(activityPath);
+        const activityAt = now().getTime();
+        writeJsonAtomic(activityPath, current
+            ? { ...current, last_activity_ms: activityAt }
+            : {
+                last_delivery_ms: activityAt,
+                last_delivery_kind: "start",
+                checkin_count: 0,
+                last_activity_ms: activityAt,
+            });
+    }, { now });
+}
+export function recordMonitorTargetDeliveryAtPath(activityPath, now = () => new Date(), kind = "monitor_event") {
+    const current = readJson(activityPath);
+    writeJsonAtomic(activityPath, {
+        last_delivery_ms: now().getTime(),
+        last_delivery_kind: kind,
+        checkin_count: current?.checkin_count ?? 0,
+        ...(current?.last_activity_ms === undefined ? {} : { last_activity_ms: current.last_activity_ms }),
+        ...(current?.last_checkin_attempt_ms === undefined ? {} : { last_checkin_attempt_ms: current.last_checkin_attempt_ms }),
+    });
+}
+function monitorIsLive(state, deps) {
+    return state?.status === "running" && state.pid !== null &&
+        deps.pidIsAlive(state.pid, state.starttime);
+}
+function activeTargetMonitors(hqRoot, targetKey, deps) {
+    const root = path.join(hqRoot, "workspace", "monitors");
+    let names;
+    try {
+        names = fs.readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && entry.name !== "sessions" && entry.name !== "targets")
+            .map((entry) => entry.name);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const monitors = [];
+    for (const name of names) {
+        const dir = path.join(root, name);
+        const meta = readJson(path.join(dir, "meta.json"));
+        const state = readJson(path.join(dir, "state.json"));
+        if (meta?.target_key !== targetKey || !monitorIsLive(state, deps))
+            continue;
+        monitors.push({ meta, state });
+    }
+    return monitors;
+}
+/** Elapsed idle time in whole units; live timers never land on exact multiples. */
+export function formatElapsed(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes >= 60) {
+        const hours = Math.floor(minutes / 60);
+        const rest = minutes % 60;
+        return rest === 0 ? `${hours}h` : `${hours}h ${rest}m`;
+    }
+    if (minutes >= 1)
+        return `${minutes}m`;
+    return `${Math.max(0, Math.floor(ms / 1_000))}s`;
+}
+function formatCheckinText(elapsedMs, monitors) {
+    const descriptions = monitors.map(({ meta }) => meta.description).join(", ");
+    return `hq monitor check-in — idle for ${formatElapsed(elapsedMs)}; ${monitors.length} monitor(s) still armed: ${descriptions}. If you are idle, confirm nothing needs action and end your turn. If you are mid-task, ignore this and continue.`;
+}
+export async function runMonitorCheckinTick(hqRoot, targetKey, deps) {
+    if (!(await deps.isWakeable(targetKey)))
+        return { sent: false, sequence: null, text: null, outcome: null };
+    return withMonitorTargetLock(hqRoot, targetKey, async (activityPath) => {
+        const monitors = activeTargetMonitors(hqRoot, targetKey, deps);
+        const eligible = monitors.filter(({ meta }) => meta.checkin_ms !== null && meta.checkin_ms > 0);
+        if (monitors.length === 0 || eligible.length === 0) {
+            return { sent: false, sequence: null, text: null, outcome: null };
+        }
+        const shortestInterval = Math.min(...eligible.map(({ meta }) => meta.checkin_ms));
+        const nowMs = deps.now().getTime();
+        const activity = readJson(activityPath);
+        const targetActivityAt = await deps.readTargetActivityAt?.(targetKey) ?? null;
+        if (!activity) {
+            writeJsonAtomic(activityPath, {
+                last_delivery_ms: targetActivityAt ?? nowMs,
+                last_delivery_kind: "start",
+                checkin_count: 0,
+                ...(targetActivityAt === null ? {} : { last_activity_ms: targetActivityAt }),
+            });
+            return { sent: false, sequence: null, text: null, outcome: null };
+        }
+        const lastActivityMs = Math.max(activity.last_delivery_ms, activity.last_activity_ms ?? Number.NEGATIVE_INFINITY, targetActivityAt ?? Number.NEGATIVE_INFINITY);
+        const elapsed = nowMs - lastActivityMs;
+        if (elapsed < shortestInterval)
+            return { sent: false, sequence: null, text: null, outcome: null };
+        if (activity.last_checkin_attempt_ms !== undefined && nowMs - activity.last_checkin_attempt_ms < shortestInterval) {
+            return { sent: false, sequence: null, text: null, outcome: null };
+        }
+        const text = formatCheckinText(elapsed, monitors);
+        const sequence = activity.checkin_count + 1;
+        const delivery = await deps.deliver(text, sequence);
+        if (!delivery.delivered) {
+            writeJsonAtomic(activityPath, { ...activity, last_checkin_attempt_ms: nowMs });
+            return { sent: false, sequence: null, text, outcome: delivery.outcome };
+        }
+        writeJsonAtomic(activityPath, {
+            last_delivery_ms: nowMs,
+            last_delivery_kind: "checkin",
+            checkin_count: sequence,
+            last_checkin_attempt_ms: nowMs,
+        });
+        return { sent: true, sequence, text, outcome: delivery.outcome };
+    }, { now: deps.now, pidIsAlive: deps.pidIsAlive, sleep: deps.sleep });
+}
+export function readMonitorPidLiveness(pid, starttime, readStarttime = readProcStarttime) {
+    if (pid === null || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    return defaultPidIsAlive(pid, starttime, readStarttime);
+}
+//# sourceMappingURL=monitor.js.map

package/dist/main.js

@@ -53,6 +53,7 @@ import { registerCommandsWithRecovery } from "./startup-registration.js";
 import { installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTreeTornError, } from "./utils/install-tree-torn.js";
 import { isVaultAccessDeniedError, vaultAccessDeniedMessage, } from "./utils/vault-access-denied-error.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
+import { runGlobalNetworkLifecycle } from "./utils/cli-network-lifecycle.js";
 /**
  * Total time one CLI invocation may await foreground network work. This spans
  * the hard version decision, pre-action observability, and release-health
@@ -152,7 +153,7 @@ export function handleStreamError(err, deps = defaultStreamErrorDependencies) {
 }
 process.stdout.on("error", (err) => handleStreamError(err));
 process.stderr.on("error", (err) => handleStreamError(err));
-initSentry();
+runGlobalNetworkLifecycle(process.argv, () => initSentry());
 const program = new Command();
 program
     .name("hq")
@@ -166,13 +167,15 @@ program.hook("preAction", async () => {
     // regardless, because the timer cannot be serviced while the event loop is
     // blocked. Keep anything added here asynchronous, or separately cheap: this
     // hook is on the path of EVERY hq command.
-    const budget = activeForegroundNetworkBudget;
-    if (!budget)
-        return;
-    await budget.waitFor(OBSERVABILITY_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => Promise.all([
-        emitCliSessionStarted(timeoutMs),
-        reportCliClientHealthInvocation({ timeoutMs }),
-    ]));
+    await runGlobalNetworkLifecycle(process.argv, async () => {
+        const budget = activeForegroundNetworkBudget;
+        if (!budget)
+            return;
+        await budget.waitFor(OBSERVABILITY_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => Promise.all([
+            emitCliSessionStarted(timeoutMs),
+            reportCliClientHealthInvocation({ timeoutMs }),
+        ]));
+    });
 });
 export async function runCli() {
     const foregroundNetworkBudget = new ForegroundNetworkBudget();
@@ -180,17 +183,19 @@ export async function runCli() {
     // Begin one registry refresh without awaiting it. Every command gate reads
     // only the client's held snapshot and falls back locally, so an offline or
     // slow registry cannot delay command parsing or alter a command failure.
-    void kickFlagRegistryReadiness();
+    runGlobalNetworkLifecycle(process.argv, () => {
+        void kickFlagRegistryReadiness();
+    });
     // Set when a self-update re-exec'd this command on a newer CLI: the child
     // already did the work, so this process only has to carry its exit status
     // out (after the finally block's telemetry, hence not process.exit here).
     let reexecStatus = null;
     try {
-        Sentry.addBreadcrumb({
+        runGlobalNetworkLifecycle(process.argv, () => Sentry.addBreadcrumb({
             category: "command",
             message: sanitizeArgv(process.argv.slice(2)).join(" "),
             level: "info",
-        });
+        }));
         // Version handling, both halves. Skipped for inspection flags
         // (`--version`, `--help`) so users debugging a broken install can still
         // introspect what they have, and silent on any failure — neither half may
@@ -204,7 +209,9 @@ export async function runCli() {
         //    it (hq-pro's `updateRecommended` and the cached npm latest from
         //    `version-check.ts`); whichever fires first re-execs, and the child
         //    carries a guard env so it can never update again.
-        if (!shouldSkipGate(process.argv)) {
+        const versionAction = await runGlobalNetworkLifecycle(process.argv, async () => {
+            if (shouldSkipGate(process.argv))
+                return "continue";
             const gate = (await foregroundNetworkBudget.waitFor(VERSION_GATE_FOREGROUND_WAIT_MS, FINALIZATION_FOREGROUND_WAIT_MS, (timeoutMs) => enforceVersionGate(async (decision) => {
                 const outcome = await autoUpdateAndReexec(process.argv, decision.latestVersion);
                 if (outcome.action === "reexec")
@@ -212,16 +219,19 @@ export async function runCli() {
                 return outcome.action === "reexec";
             }, { timeoutMs }))) ?? "continue";
             if (gate === "reexec")
-                return;
+                return "reexec";
             const cachedLatest = staleAgainstCachedLatest();
             if (cachedLatest) {
                 const outcome = await autoUpdateAndReexec(process.argv, cachedLatest);
                 if (outcome.action === "reexec") {
                     reexecStatus = outcome.reexecStatus ?? 0;
-                    return;
+                    return "reexec";
                 }
             }
-        }
+            return "continue";
+        });
+        if (versionAction === "reexec")
+            return;
         // Register every contributor for the selected root only. Root help and
         // unknown-command recovery use generated metadata, so they keep the full
         // Commander surface without evaluating every command implementation.
@@ -256,19 +266,21 @@ export async function runCli() {
     finally {
         // Plan-limit nag (US-016): stderr-only, never throws, never touches
         // process.exitCode — safe to run after exit codes have been set.
-        emitPlanLimitNag();
-        // Release health: finalize the per-run session before the flush.
-        finishSentrySession();
-        // Neither task may turn a successful command into Node's
-        // `unsettled top-level await` exit. They are observability-only after the
-        // command has completed, so a bounded best-effort wait is the terminal
-        // lifecycle boundary for this invocation. The budget reserves this 500 ms
-        // slice even when the command itself was long-running.
-        const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
-        await settleWithin([
-            refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
-            Sentry.flush(releaseHealthTimeoutMs),
-        ], releaseHealthTimeoutMs);
+        await runGlobalNetworkLifecycle(process.argv, async () => {
+            emitPlanLimitNag();
+            // Release health: finalize the per-run session before the flush.
+            finishSentrySession();
+            // Neither task may turn a successful command into Node's
+            // `unsettled top-level await` exit. They are observability-only after the
+            // command has completed, so a bounded best-effort wait is the terminal
+            // lifecycle boundary for this invocation. The budget reserves this 500 ms
+            // slice even when the command itself was long-running.
+            const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
+            await settleWithin([
+                refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
+                Sentry.flush(releaseHealthTimeoutMs),
+            ], releaseHealthTimeoutMs);
+        });
         // Last, so it wins over anything the (skipped) command path would have
         // set: the re-exec'd child's status IS this invocation's result.
         if (reexecStatus !== null)

package/dist/utils/cli-network-lifecycle.d.ts

@@ -0,0 +1,4 @@
+export declare function isMonitorFastPathCommand(argv: readonly string[]): boolean;
+/** Skip process-wide network lifecycle work for hooks and detached monitor supervisors. */
+export declare function runGlobalNetworkLifecycle<T>(argv: readonly string[], operation: () => T): T | undefined;
+//# sourceMappingURL=cli-network-lifecycle.d.ts.map

package/dist/utils/cli-network-lifecycle.js

@@ -0,0 +1,11 @@
+const MONITOR_HIDDEN_NETWORK_BYPASS = new Set(["drain", "wait", "enabled", "_run"]);
+export function isMonitorFastPathCommand(argv) {
+    return argv[2] === "monitor" && MONITOR_HIDDEN_NETWORK_BYPASS.has(argv[3] ?? "");
+}
+/** Skip process-wide network lifecycle work for hooks and detached monitor supervisors. */
+export function runGlobalNetworkLifecycle(argv, operation) {
+    if (isMonitorFastPathCommand(argv))
+        return undefined;
+    return operation();
+}
+//# sourceMappingURL=cli-network-lifecycle.js.map

package/package.json

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