@indigoai-us/hq-cli 5.296.0 → 5.297.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.297.0] — 2026-09-30
+- When enabled by hq-flags, show the quarantined work-context outbox count and latest reason in hq doctor and mesh daemon status.
+- `hq daemon` now exits after shutdown when handles remain open, and its mesh service waits when another live mesh daemon owns the process lock.
+
 ## [5.296.0] — 2026-09-30
 - Upgrade varlock to 1.21.1. `hq run` skips Varlock cache setup and reports malformed env files promptly without sending them to Sentry.
 - Record bounded actor and trigger history for lane worker starts and expose it through `hq lanes show --json`. Preserve history through conflict merges and envelope repair, and record answered-question callers for immediate and queued resumes.

package/dist/commands/mesh.js

@@ -2129,7 +2129,9 @@ async function runDaemonInstall(opts) {
     // `hq daemon` runs mesh on this machine: installing a second unit would run it twice.
     // An explicit --hq-root is verified the same way as below and saved for the daemon.
     const explicitRoot = opts.hqRoot ? resolveInstallHqRoot({ explicit: opts.hqRoot }).root : undefined;
-    const handedOff = opts.systemUser ? null : handOffInstallHere(["mesh"], process.env, { hqRoot: explicitRoot });
+    const handedOff = opts.systemUser
+        ? null
+        : handOffInstallHere(["mesh"], process.env, { hqRoot: explicitRoot, ifStale: opts.ifStale });
     if (handedOff) {
         console.log(opts.json ? JSON.stringify({ ok: true, action: "hq-daemon", reinstalled: false, message: handedOff }) : handedOff);
         return;

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

@@ -51,5 +51,6 @@ export declare function handOffInstall(opts: {
 /** handOffInstall for this machine and user, for the older install commands. */
 export declare function handOffInstallHere(services: readonly ServiceName[], env?: NodeJS.ProcessEnv, opts?: {
     hqRoot?: string;
+    ifStale?: boolean;
 }): string | null;
 //# sourceMappingURL=handoff.d.ts.map

package/dist/lib/daemon/handoff.js

@@ -17,6 +17,15 @@ import { daemonPaths } from "./paths.js";
 import { writeControlRequest } from "./requests.js";
 /** Statuses where the daemon itself owns the unit's process. */
 const OWNED = new Set(["running", "backoff", "exited", "idle", "stopped"]);
+const RECENT_HOSTED_DAEMON_MS = 5 * 60_000;
+/** The updater's postinstall may run in the short gap before the desktop app relaunches its daemon. */
+function recentlyHostedDaemon(paths) {
+    if (!fs.existsSync(paths.statePath))
+        return false;
+    const state = JSON.parse(fs.readFileSync(paths.statePath, "utf8"));
+    const age = Date.now() - (state.updatedAt ?? 0);
+    return state.host === "desktop" && age >= 0 && age <= RECENT_HOSTED_DAEMON_MS;
+}
 /** The live daemon's state, or null when no daemon is running. */
 function liveState(paths, alive) {
     if (runningDaemonPid(paths.lockPath, alive) === null)
@@ -124,14 +133,21 @@ export function handOffInstall(opts) {
 export function handOffInstallHere(services, env = process.env, opts = {}) {
     const home = os.homedir();
     const paths = daemonPaths(home, env);
+    const config = readDaemonConfig(paths.configPath);
+    if (opts.ifStale && services.every((service) => config.disable.includes(service))) {
+        return `hq daemon has ${services.join(", ")} disabled, so the older service will not be installed.`;
+    }
     const installed = daemonUnitInstalled({
         platform: process.platform,
         home,
         windowsTaskExists: (task) => spawnSync("schtasks.exe", ["/Query", "/TN", task], { encoding: "utf8", windowsHide: true }).status === 0,
     }) || hostedDaemonRunning(paths);
-    if (!installed)
+    if (!installed) {
+        if (opts.ifStale && services.includes("mesh") && recentlyHostedDaemon(paths)) {
+            return `hq daemon recently hosted mesh on this machine, so the older mesh service will not be installed during its restart.`;
+        }
         return null;
-    const config = readDaemonConfig(paths.configPath);
+    }
     const machineType = detectMachineType(undefined, {
         platform: process.platform,
         env,

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

@@ -32,4 +32,11 @@ export declare function findLegacyUnits(deps: LegacyProbeDeps): LegacyUnit[];
  * own checks, because `hq daemon migrate` will never take them over.
  */
 export declare function legacyOwnerLookup(units: readonly LegacyUnit[]): (unitId: string) => string | null;
+/** A daemon-managed macOS mesh service takes over the old LaunchAgent on startup. */
+export declare function legacyMeshUnitsToRetire(units: readonly LegacyUnit[], opts: {
+    platform: NodeJS.Platform;
+    managed: boolean;
+    hosted: boolean;
+    meshEnabled: boolean;
+}): LegacyUnit[];
 //# sourceMappingURL=legacy.d.ts.map

package/dist/lib/daemon/legacy.js

@@ -122,4 +122,10 @@ export function legacyOwnerLookup(units) {
         return hit ? describeLegacyUnit(hit) : null;
     };
 }
+/** A daemon-managed macOS mesh service takes over the old LaunchAgent on startup. */
+export function legacyMeshUnitsToRetire(units, opts) {
+    if (opts.platform !== "darwin" || (!opts.managed && !opts.hosted) || !opts.meshEnabled)
+        return [];
+    return units.filter((unit) => unit.service === "mesh" && unit.kind === "launchd" && unit.migratable);
+}
 //# sourceMappingURL=legacy.js.map

package/dist/lib/daemon/lock.js

@@ -43,7 +43,7 @@ export function processCommandLine(pid, deps = defaultCommandLineDeps()) {
             "-Command",
             `(Get-CimInstance Win32_Process -Filter "ProcessId=${Math.trunc(pid)}").CommandLine`,
         ])
-        : deps.run("ps", ["-o", "command=", "-p", String(pid)]);
+        : deps.run("ps", ["-ww", "-o", "args=", "-p", String(pid)]);
     if (r.status !== 0)
         return null;
     const line = r.stdout.trim();

package/dist/lib/daemon/run.js

@@ -19,9 +19,12 @@ import { botsRoot } from "../bot/paths.js";
 import { CLAUDE_RUNNER_SCRIPT, CODEX_RUNNER_SCRIPT, enabledServices, planUnits } from "./catalog.js";
 import { effectiveSyncOwner, readDaemonConfig } from "./config.js";
 import { SUPERVISOR_HANDOFF_FLAG, readDaemonFlag } from "./flag.js";
-import { findLegacyUnits, legacyOwnerLookup } from "./legacy.js";
+import { findLegacyUnits, legacyMeshUnitsToRetire, legacyOwnerLookup } from "./legacy.js";
 import { readLegacySyncEnv } from "./legacy-sync-env.js";
-import { acquireDaemonLock, releaseDaemonLock } from "./lock.js";
+import { acquireDaemonLock, isProcessAlive, processCommandLine, releaseDaemonLock } from "./lock.js";
+import { adoptLegacyUnits } from "./migrate.js";
+import { daemonDir as meshDaemonDir, daemonPidPath as meshDaemonPidPath } from "../mesh/live/daemon/paths.js";
+import { readPidLock } from "../mesh/live/daemon/pid-lock.js";
 import { daemonRootRefusal } from "./install.js";
 import { detectMachineType } from "./machine-type.js";
 import { appendPrivate, daemonPaths, ensurePrivateDir, openPrivateAppend } from "./paths.js";
@@ -332,6 +335,54 @@ export async function runDaemon(opts) {
         }
         return legacyCache.units;
     };
+    const legacyMesh = legacyMeshUnitsToRetire(legacyUnits(), {
+        platform,
+        managed: opts.managed === true,
+        hosted: opts.host !== undefined,
+        meshEnabled: enabledServices(machineType, initial).includes("mesh"),
+    });
+    if (legacyMesh.length > 0) {
+        try {
+            const uid = process.getuid?.() ?? 0;
+            const result = adoptLegacyUnits(legacyMesh, {
+                run: (command, args) => {
+                    const r = spawnSync(command, args, { encoding: "utf8", windowsHide: true, timeout: 15_000 });
+                    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+                },
+                uid,
+                isRoot: uid === 0,
+                adoptedDir: path.join(paths.root, "adopted"),
+                recordPath: path.join(paths.root, "adopted.json"),
+                systemAdoptedDir: "/var/lib/hq/daemon/adopted",
+                systemRecordPath: "/var/lib/hq/daemon/adopted.json",
+                systemUnitDir: "/etc/systemd/system",
+            });
+            for (const unit of result.adopted)
+                log("info", `retired legacy ${unit.unitId} unit ${unit.name}; hq daemon now owns mesh`);
+            for (const failure of result.failed)
+                log("warn", `could not retire legacy ${failure.unit.unitId} unit ${failure.unit.name}: ${failure.error}`);
+        }
+        catch (err) {
+            log("error", `could not retire legacy mesh units: ${err.message}`);
+        }
+        legacyCache = null;
+    }
+    const meshOwnerReason = () => {
+        const lockPath = meshDaemonPidPath(meshDaemonDir(undefined, home, env));
+        const owner = readPidLock(lockPath);
+        if (!owner || owner.pid === process.pid || !isProcessAlive(owner.pid))
+            return undefined;
+        const command = processCommandLine(owner.pid, {
+            platform,
+            run: (file, args) => {
+                const r = spawnSync(file, args, { encoding: "utf8", windowsHide: true, timeout: 15_000 });
+                return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+            },
+        });
+        if (command && !/\bmesh\s+daemon\s+run\b/.test(command))
+            return undefined;
+        return `mesh daemon already running (pid ${owner.pid}); waiting for it to exit`;
+    };
     let warnedMissingPin = null;
     const daemonSyncRunnerPids = new Set();
     const plan = () => {
@@ -554,6 +605,7 @@ export async function runDaemon(opts) {
                 return undefined;
             }
         },
+        meshOwnerReason,
         cliVersion: CLI_VERSION,
         adopt,
     });
@@ -603,6 +655,9 @@ export async function runDaemon(opts) {
                     log("info", "all services stopped");
                 releaseDaemonLock(paths.lockPath);
                 resolve(exitCode);
+                // Pipes, sockets and unrelated timers can outlive a clean shutdown.
+                // Keep restart and signal exits bounded just like the handoff path.
+                setTimeout(() => process.exit(exitCode), 5_000).unref();
             });
         };
         /** Exit for a restart but leave the services running for the next daemon to adopt. */

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

@@ -107,6 +107,8 @@ export interface SupervisorDeps {
     requestPollMs?: number;
     /** Read hq-cloud's lease status after it exits with the lease-conflict code. */
     syncOwnerBlockReason?: () => string | undefined;
+    /** A separate mesh daemon currently owns its pid lock after our mesh child exits. */
+    meshOwnerReason?: () => string | undefined;
     /** The running CLI's version; part of the key of units that run `hq` commands. */
     cliVersion?: string;
     /** Services to take over from the previous daemon instead of starting them. */

package/dist/lib/daemon/supervisor.js

@@ -27,6 +27,7 @@ export const BACKOFF_BASE_MS = 1_000;
 export const BACKOFF_MAX_MS = 60_000;
 export const HEALTHY_RUN_MS = 60_000;
 export const STOP_ESCALATION_MS = 10_000;
+const MESH_OWNER_RECHECK_MS = 15_000;
 /** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
 export const HANDOFF_STAGGER_MS = 15_000;
 /** How long a draining unit may take to finish its work before it gets SIGTERM. */
@@ -294,6 +295,31 @@ export function createSupervisor(deps) {
                 emit();
                 return;
             }
+            const meshOwnerReason = slot.plan.service === "mesh" ? deps.meshOwnerReason?.() : undefined;
+            if (meshOwnerReason) {
+                const waitForOwner = (reason) => {
+                    slot.state.status = "waiting";
+                    slot.state.reason = reason;
+                    slot.state.nextRunAt = now() + MESH_OWNER_RECHECK_MS;
+                    deps.log("warn", `${reason}; retrying mesh ownership check in ${MESH_OWNER_RECHECK_MS}ms`);
+                    slot.timer = setT(() => {
+                        slot.timer = undefined;
+                        const current = deps.meshOwnerReason?.();
+                        if (current)
+                            waitForOwner(current);
+                        else {
+                            slot.attempts = 0;
+                            delete slot.state.reason;
+                            delete slot.state.nextRunAt;
+                            startLong(slot);
+                        }
+                        emit();
+                    }, MESH_OWNER_RECHECK_MS);
+                };
+                waitForOwner(meshOwnerReason);
+                emit();
+                return;
+            }
             deps.log("warn", `${slot.plan.id} exited (code=${code ?? "null"} signal=${signal ?? "none"})`);
             if (ranFor >= HEALTHY_RUN_MS)
                 slot.attempts = 0;

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

@@ -8,6 +8,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { readDeviceConfig, } from "../../work-context/config.js";
 import { outboxStats, listOutboxOperations } from "../../work-context/outbox.js";
+import { outboxQuarantineStatusEnabled } from "../../work-context/outbox-quarantine-status-flag.js";
 import { workContextRoot, workContextSessionsDir } from "../../work-context/paths.js";
 import { countJsonlLines, deadLetterNonEmpty, } from "../../mesh/live/spool.js";
 import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../../mesh/live/paths.js";
@@ -87,11 +88,14 @@ function runChecks(deps) {
         target: path.join(root, "outbox"),
         message: `Outbox queued depth=${stats.depth} (acked=${stats.acked}).`,
     });
+    const showQuarantineReason = stats.quarantined > 0 && outboxQuarantineStatusEnabled();
     results.push({
         status: stats.quarantined > 0 ? "WARN" : "PASS",
         checkId: "work-context.outbox-quarantined",
         target: path.join(root, "outbox"),
-        message: `Outbox quarantined count=${stats.quarantined}.`,
+        message: `Outbox quarantined count=${stats.quarantined}${showQuarantineReason
+            ? ` (last reason=${stats.lastQuarantineReason ?? "unknown"})`
+            : ""}.`,
     });
     // Default-company mode + migration capability (US-017B)
     try {

package/dist/lib/mesh/live/daemon/doctor.d.ts

@@ -25,6 +25,8 @@ export interface DaemonDoctorReport {
     /** Events in any local queue still marked no-company / NEEDS_COMPANY / NONE. */
     unattributedEvents: UnattributedEventCounts;
     outboxDepth: number;
+    outboxQuarantined?: number;
+    outboxLastQuarantineReason?: string;
     lastFlushAt?: string;
     lastFlushResult?: DaemonStateFile["lastFlushResult"];
     unhealthy: boolean;

package/dist/lib/mesh/live/daemon/doctor.js

@@ -9,6 +9,7 @@ import { describeCognitoTokenSource, formatCognitoSubject, loadMachineCachedToke
 import { listOutboxOperations, outboxStats, } from "../../../work-context/outbox.js";
 import { readSessionState } from "../../../work-context/state.js";
 import { workContextRoot } from "../../../work-context/paths.js";
+import { outboxQuarantineStatusEnabled } from "../../../work-context/outbox-quarantine-status-flag.js";
 import { formatDroppedPresenceCompany } from "./credentials.js";
 import { countJsonlLines, countUnattributedEvents, } from "../spool.js";
 import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../paths.js";
@@ -258,6 +259,12 @@ export function collectDaemonDoctor(deps = {}) {
         deadLetterCount,
         unattributedEvents,
         outboxDepth: outbox.depth,
+        ...(outbox.quarantined > 0 && outboxQuarantineStatusEnabled()
+            ? {
+                outboxQuarantined: outbox.quarantined,
+                outboxLastQuarantineReason: outbox.lastQuarantineReason ?? undefined,
+            }
+            : {}),
         lastFlushAt: state?.lastFlushAt,
         lastFlushResult: state?.lastFlushResult,
         unhealthy: unhealthyReasons.length > 0,
@@ -302,6 +309,9 @@ export function formatDaemonDoctor(report) {
         // receive-only (direct) mode.
         lines.push(`spool depth: ${report.spoolDepth}`, `held: ${report.heldCount}${report.heldCount > 0 ? " (needs_company; not sent as NONE)" : ""}`, `held with no local evidence: ${report.heldWithNoLocalEvidence}`, `outbox depth: ${report.outboxDepth}`);
     }
+    if (report.outboxQuarantined !== undefined) {
+        lines.push(`outbox quarantined: ${report.outboxQuarantined} (last reason=${report.outboxLastQuarantineReason ?? "unknown"})`);
+    }
     if (report.emitMode !== "legacy" && report.heldCount > 0) {
         lines.push(`held: ${report.heldCount} (needs_company; not sent as NONE)`);
     }

package/dist/lib/work-context/outbox-quarantine-status-flag.d.ts

@@ -0,0 +1,4 @@
+export declare const OUTBOX_QUARANTINE_STATUS_FLAG = "agents.work-context-outbox-quarantine-status";
+export declare const OUTBOX_QUARANTINE_STATUS_FALLBACK = false;
+export declare function outboxQuarantineStatusEnabled(): boolean;
+//# sourceMappingURL=outbox-quarantine-status-flag.d.ts.map

package/dist/lib/work-context/outbox-quarantine-status-flag.js

@@ -0,0 +1,7 @@
+import { resolveProcessFlagGate } from "../flag-registry.js";
+export const OUTBOX_QUARANTINE_STATUS_FLAG = "agents.work-context-outbox-quarantine-status";
+export const OUTBOX_QUARANTINE_STATUS_FALLBACK = false;
+export function outboxQuarantineStatusEnabled() {
+    return resolveProcessFlagGate(OUTBOX_QUARANTINE_STATUS_FLAG, { fallback: OUTBOX_QUARANTINE_STATUS_FALLBACK }, () => OUTBOX_QUARANTINE_STATUS_FALLBACK);
+}
+//# sourceMappingURL=outbox-quarantine-status-flag.js.map

package/dist/lib/work-context/outbox.d.ts

@@ -118,6 +118,7 @@ export interface OutboxStats {
     quarantined: number;
     queued: number;
     acked: number;
+    lastQuarantineReason: string | null;
 }
 export declare function outboxStats(root: string): OutboxStats;
 export type DeliverFn = (op: OutboxOperation) => Promise<{

package/dist/lib/work-context/outbox.js

@@ -458,11 +458,17 @@ export function listOutboxOperations(root, deps = {}) {
 }
 export function outboxStats(root) {
     const ops = listOutboxOperations(root);
+    const quarantinedOps = ops.filter((o) => o.delivery === "quarantined");
+    const latestQuarantine = quarantinedOps.reduce((latest, op) => !latest || op.updatedAt > latest.updatedAt ||
+        (op.updatedAt === latest.updatedAt && op.operationId > latest.operationId)
+        ? op
+        : latest, null);
     return {
         depth: ops.filter((o) => o.delivery === "queued").length,
-        quarantined: ops.filter((o) => o.delivery === "quarantined").length,
+        quarantined: quarantinedOps.length,
         queued: ops.filter((o) => o.delivery === "queued").length,
         acked: ops.filter((o) => o.delivery === "acked").length,
+        lastQuarantineReason: latestQuarantine?.lastErrorCode ?? null,
     };
 }
 function isOutboxDue(op, nowIso) {

package/package.json

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