@indigoai-us/hq-cli 5.122.2 → 5.123.1

package/dist/lib/mesh/live/daemon/board-refresh.js

@@ -1,6 +1,9 @@
 /**
  * Refresh ~/.hq/work-context/sessions/<sid>/board.md for bound sessions
- * from GET /companies/{companyUid}/board at most every 60s.
+ * from the ProjectView read route at most every 60s.
+ *
+ * Board JSON remains the fallback for older projects, but story status is
+ * authoritative in ProjectView because `hq mesh story` writes there.
  * Metadata-only snapshot — never prompts or tokens.
  */
 import * as fs from "node:fs";
@@ -115,9 +118,72 @@ export async function refreshBoundSessionBoards(deps) {
     }
     return { refreshed, skipped, errors };
 }
+function storiesFromProject(project) {
+    const storiesRaw = Array.isArray(project.stories) ? project.stories : [];
+    const stories = [];
+    for (const s of storiesRaw) {
+        if (!s || typeof s !== "object" || Array.isArray(s))
+            continue;
+        const row = s;
+        const id = typeof row.id === "string"
+            ? row.id
+            : typeof row.storyId === "string"
+                ? row.storyId
+                : typeof row.taskId === "string"
+                    ? row.taskId
+                    : "";
+        if (!id)
+            continue;
+        stories.push({
+            id,
+            title: typeof row.title === "string"
+                ? row.title.slice(0, 120)
+                : typeof row.name === "string"
+                    ? row.name.slice(0, 120)
+                    : undefined,
+            status: typeof row.status === "string" ? row.status : undefined,
+        });
+    }
+    return stories;
+}
+function projectViewSnapshot(raw, companyUid, projectId) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const project = raw;
+    if (project.companyUid !== companyUid || project.projectId !== projectId)
+        return null;
+    return {
+        projectId,
+        projectName: typeof project.name === "string"
+            ? project.name
+            : typeof project.title === "string"
+                ? project.title
+                : undefined,
+        stories: storiesFromProject(project),
+    };
+}
+function isMissingProject(error) {
+    // hq-pro's GET ProjectView handler emits PROJECT_VIEW_NOT_FOUND; retain the
+    // legacy PROJECT_NOT_FOUND code for compatibility with older producers.
+    return (error instanceof Error &&
+        /^404\s+(?:PROJECT_VIEW_NOT_FOUND|PROJECT_NOT_FOUND)\b/.test(error.message));
+}
 /** Build a BoardReader from meshJson-compatible fetch. */
 export function createVaultBoardReader(opts) {
     return async (companyUid, projectId) => {
+        // ProjectView is the live story-status source. Only use board.json when
+        // this project has not been migrated into ProjectView yet.
+        try {
+            const view = await opts.getJson(`/v1/work-mesh/projects/${encodeURIComponent(projectId)}?companyUid=${encodeURIComponent(companyUid)}`);
+            const snapshot = projectViewSnapshot(view, companyUid, projectId);
+            if (snapshot)
+                return snapshot;
+            throw new Error("ProjectView response did not match the requested company and project");
+        }
+        catch (error) {
+            if (!isMissingProject(error))
+                throw error;
+        }
         const raw = await opts.getJson(`/companies/${encodeURIComponent(companyUid)}/board`);
         if (!raw || typeof raw !== "object")
             return null;
@@ -140,35 +206,10 @@ export function createVaultBoardReader(opts) {
             const id = typeof p.id === "string" ? p.id : typeof p.projectId === "string" ? p.projectId : "";
             if (id !== projectId)
                 continue;
-            const storiesRaw = Array.isArray(p.stories)
-                ? p.stories
-                : Array.isArray(p.tasks)
-                    ? p.tasks
-                    : [];
-            const stories = [];
-            for (const s of storiesRaw) {
-                if (!s || typeof s !== "object" || Array.isArray(s))
-                    continue;
-                const row = s;
-                const sid = typeof row.id === "string"
-                    ? row.id
-                    : typeof row.storyId === "string"
-                        ? row.storyId
-                        : typeof row.taskId === "string"
-                            ? row.taskId
-                            : "";
-                if (!sid)
-                    continue;
-                stories.push({
-                    id: sid,
-                    title: typeof row.title === "string"
-                        ? row.title.slice(0, 120)
-                        : typeof row.name === "string"
-                            ? row.name.slice(0, 120)
-                            : undefined,
-                    status: typeof row.status === "string" ? row.status : undefined,
-                });
-            }
+            const stories = storiesFromProject({
+                ...p,
+                stories: Array.isArray(p.stories) ? p.stories : p.tasks,
+            });
             return {
                 projectId,
                 projectName: typeof p.name === "string"

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

@@ -0,0 +1,9 @@
+export interface DaemonConfig {
+    trustedHqRoots: string[];
+}
+export declare function daemonConfigPath(daemonDirectory: string): string;
+export declare function verifyHqRoot(candidate: string | undefined): string | null;
+export declare function readDaemonConfig(daemonDirectory: string): DaemonConfig;
+/** Record a verified local HQ checkout without trusting a caller-supplied path at runtime. */
+export declare function registerTrustedHqRoot(daemonDirectory: string, candidate: string | undefined): DaemonConfig;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1,45 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export function daemonConfigPath(daemonDirectory) {
+    return path.join(daemonDirectory, "config.json");
+}
+export function verifyHqRoot(candidate) {
+    if (!candidate?.trim())
+        return null;
+    try {
+        const root = fs.realpathSync(candidate);
+        return fs.statSync(path.join(root, "companies", "manifest.yaml")).isFile()
+            ? root
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readDaemonConfig(daemonDirectory) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(daemonConfigPath(daemonDirectory), "utf8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return { trustedHqRoots: [] };
+        const roots = raw.trustedHqRoots;
+        if (!Array.isArray(roots))
+            return { trustedHqRoots: [] };
+        return { trustedHqRoots: roots.filter((root) => typeof root === "string")
+                .map(verifyHqRoot).filter((root) => Boolean(root)) };
+    }
+    catch {
+        return { trustedHqRoots: [] };
+    }
+}
+/** Record a verified local HQ checkout without trusting a caller-supplied path at runtime. */
+export function registerTrustedHqRoot(daemonDirectory, candidate) {
+    const root = verifyHqRoot(candidate);
+    const current = readDaemonConfig(daemonDirectory);
+    if (!root || current.trustedHqRoots.includes(root))
+        return current;
+    const next = { trustedHqRoots: [...current.trustedHqRoots, root] };
+    fs.mkdirSync(daemonDirectory, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(daemonConfigPath(daemonDirectory), `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    return next;
+}
+//# sourceMappingURL=config.js.map

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

@@ -49,6 +49,11 @@ export interface PresenceCompany {
     companyUid: string;
     presenceTopic: string;
 }
+export interface DroppedPresenceCompany {
+    companyUid: string;
+    /** Server-supplied cause when available; otherwise a deliberately neutral label. */
+    reason: string;
+}
 export interface Contract3Bundle {
     contractVersion: 3;
     credentials: IotCredentials;
@@ -58,7 +63,7 @@ export interface Contract3Bundle {
     actorUid: string;
     actorType: "human" | "agent";
     companies: PresenceCompany[];
-    droppedCompanies: string[];
+    droppedCompanies: DroppedPresenceCompany[];
     expiresAt: string;
 }
 export type CredentialsFetcher = () => Promise<Contract3Bundle>;

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

@@ -229,9 +229,25 @@ export function normalizeContract3Bundle(raw) {
     if (!expiresAt) {
         throw new Error("contract-3 vend missing expiresAt");
     }
-    const dropped = Array.isArray(r.droppedCompanies)
-        ? r.droppedCompanies.filter((x) => typeof x === "string")
-        : [];
+    const droppedCompanies = [];
+    for (const item of Array.isArray(r.droppedCompanies) ? r.droppedCompanies : []) {
+        if (typeof item === "string" && item.trim()) {
+            droppedCompanies.push({ companyUid: item, reason: "unknown" });
+            continue;
+        }
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const row = item;
+        const companyUid = typeof row.companyUid === "string" ? row.companyUid.trim() : "";
+        if (!companyUid)
+            continue;
+        droppedCompanies.push({
+            companyUid,
+            reason: typeof row.reason === "string" && row.reason.trim()
+                ? row.reason.trim()
+                : "not included",
+        });
+    }
     return {
         contractVersion: 3,
         credentials: {
@@ -246,7 +262,7 @@ export function normalizeContract3Bundle(raw) {
         actorUid,
         actorType,
         companies,
-        droppedCompanies: dropped,
+        droppedCompanies,
         expiresAt,
     };
 }

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

@@ -17,6 +17,8 @@ export interface DaemonDoctorReport {
     subscribed: boolean;
     spoolDepth: number;
     heldCount: number;
+    /** Distinct held sessions with neither bound state nor local company evidence. */
+    heldWithNoLocalEvidence: number;
     deadLetterCount: number;
     /** Events in any local queue still marked no-company / NEEDS_COMPANY / NONE. */
     unattributedEvents: UnattributedEventCounts;
@@ -32,6 +34,8 @@ export interface DaemonDoctorReport {
     actorKind: CognitoActorKind;
     /** Credential vend refused (disabled / unsupported / 403). */
     presenceRefusal?: DaemonStateFile["presenceRefusal"];
+    /** Companies the current presence credential did not include. */
+    presenceDroppedCompanies: NonNullable<DaemonStateFile["presenceDroppedCompanies"]>;
     /** Pending events awaiting a retry drain (POST /v1/mesh/events). */
     emitRetryDepth: number;
     /** Last successful direct-emit POST time. */
@@ -48,6 +52,8 @@ export interface DaemonDoctorDeps {
     home?: string;
     meshRoot?: string;
     workContextRoot?: string;
+    /** Independently configured HQ root for held-event evidence checks. */
+    hqRoot?: string;
     env?: NodeJS.ProcessEnv;
     isProcessAlive?: (pid: number) => boolean;
     now?: () => number;

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

@@ -5,13 +5,16 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import { describeCognitoTokenSource, } from "../../../../utils/cognito-session.js";
-import { outboxStats, } from "../../../work-context/outbox.js";
+import { listOutboxOperations, outboxStats, } from "../../../work-context/outbox.js";
+import { readSessionState } from "../../../work-context/state.js";
 import { workContextRoot } from "../../../work-context/paths.js";
 import { countJsonlLines, countUnattributedEvents, } from "../spool.js";
 import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../paths.js";
 import { daemonDir, daemonPidPath } from "./paths.js";
 import { readEmitState } from "../emit.js";
 import { emitRetryDepth } from "../emit-retry.js";
+import { hasCurrentAcknowledgedRegistration, readHeldSessions, refWithLocalCompanyEvidence, } from "../backfill-held.js";
+import { readDaemonConfig } from "./config.js";
 import { pidLockStatus, readPidLock } from "./pid-lock.js";
 import { readDaemonState } from "./state.js";
 export const UNHEALTHY_SPOOL_AGE_MS = 60_000;
@@ -77,6 +80,14 @@ export function collectDaemonDoctor(deps = {}) {
     const deadPath = workMeshDeadLetterPath(meshRoot);
     const spoolDepth = countJsonlLines(spoolPath);
     const heldCount = countJsonlLines(heldPath);
+    const trustedRoots = readDaemonConfig(dir).trustedHqRoots;
+    const outboxOperations = listOutboxOperations(ctxRoot);
+    const heldWithNoLocalEvidence = readHeldSessions(meshRoot).filter((ref) => {
+        const state = readSessionState(ref.sessionId, ctxRoot);
+        return (!state?.companyUid &&
+            !hasCurrentAcknowledgedRegistration(ref, state, outboxOperations, deps.hqRoot ?? env.HQ_ROOT?.trim(), trustedRoots) &&
+            !refWithLocalCompanyEvidence(ref, deps.hqRoot ?? env.HQ_ROOT?.trim(), trustedRoots, state));
+    }).length;
     const deadLetterCount = countJsonlLines(deadPath);
     const unattributedEvents = countUnattributedEvents(meshRoot);
     const outbox = outboxStats(ctxRoot);
@@ -100,11 +111,18 @@ export function collectDaemonDoctor(deps = {}) {
     if (emitMode === "legacy" && heldCount > 0) {
         unhealthyReasons.push(`held events awaiting company attribution=${heldCount}`);
     }
+    if (heldWithNoLocalEvidence > 0) {
+        unhealthyReasons.push(`held with no local evidence=${heldWithNoLocalEvidence}`);
+    }
     if (unattributedEvents.total > 0) {
         unhealthyReasons.push(`unattributed events=${unattributedEvents.total} ` +
             `(spool=${unattributedEvents.spool} held=${unattributedEvents.held} dead-letter=${unattributedEvents.deadLetter})`);
     }
     const presenceRefusal = state?.presenceRefusal ?? null;
+    const presenceDroppedCompanies = state?.presenceDroppedCompanies ?? [];
+    if (presenceDroppedCompanies.length > 0) {
+        unhealthyReasons.push(`presence unavailable for ${presenceDroppedCompanies.length} companies`);
+    }
     if (presenceRefusal) {
         unhealthyReasons.push(`presence credential refused (${presenceRefusal.code}); next retry ${presenceRefusal.nextRetryAt}`);
     }
@@ -121,6 +139,7 @@ export function collectDaemonDoctor(deps = {}) {
         companiesOnline,
         spoolDepth,
         heldCount,
+        heldWithNoLocalEvidence,
         deadLetterCount,
         unattributedEvents,
         outboxDepth: outbox.depth,
@@ -132,6 +151,7 @@ export function collectDaemonDoctor(deps = {}) {
         tokenSource: auth.tokenSource,
         actorKind: auth.actorKind,
         presenceRefusal,
+        presenceDroppedCompanies,
         emitMode,
         subscribed,
         emitRetryDepth: emitRetry,
@@ -157,7 +177,7 @@ export function formatDaemonDoctor(report) {
     if (report.emitMode === "legacy") {
         // Legacy emit path only: the spool/held/outbox queues do not exist in
         // receive-only (direct) mode.
-        lines.push(`spool depth: ${report.spoolDepth}`, `held: ${report.heldCount}`, `outbox depth: ${report.outboxDepth}`);
+        lines.push(`spool depth: ${report.spoolDepth}`, `held: ${report.heldCount}`, `held with no local evidence: ${report.heldWithNoLocalEvidence}`, `outbox depth: ${report.outboxDepth}`);
     }
     lines.push(`dead-letter: ${report.deadLetterCount}`, `unattributed events: ${report.unattributedEvents.total} ` +
         `(spool=${report.unattributedEvents.spool} held=${report.unattributedEvents.held} dead-letter=${report.unattributedEvents.deadLetter})`, `token source: ${report.tokenSource}`, `actor kind: ${report.actorKind}`);
@@ -174,6 +194,13 @@ export function formatDaemonDoctor(report) {
     if (report.presenceRefusal) {
         lines.push(`presence refusal: ${report.presenceRefusal.code} (HTTP ${report.presenceRefusal.status}); next retry at ${report.presenceRefusal.nextRetryAt}`);
     }
+    if (report.presenceDroppedCompanies.length > 0) {
+        lines.push(`presence not published for ${report.presenceDroppedCompanies.length} companies: ` +
+            report.presenceDroppedCompanies
+                .map((company) => `${company.companyUid} (${company.reason})`)
+                .join(", ") +
+            `; presence credential holds ${report.companiesOnline.length} companies; these were not included`);
+    }
     if (report.unhealthy) {
         lines.push(`health: UNHEALTHY`);
         for (const reason of report.unhealthyReasons) {

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

@@ -12,12 +12,14 @@ export type { DaemonStateFile, PresenceRefusalState } from "./state.js";
 export { appendDaemonLog, daemonLogLine, ensureDaemonLog, resolveDaemonAssetDir, rotateDaemonLogIfNeeded, } from "./log.js";
 export { BOARD_REFRESH_INTERVAL_MS, createVaultBoardReader, formatBoardMarkdown, refreshBoundSessionBoards, writeBoardMarkdown, } from "./board-refresh.js";
 export type { BoardReader, BoardRefreshDeps, BoardStorySnapshot } from "./board-refresh.js";
-export { buildInstallPaths, daemonServiceStatus, detectPlatform, installDaemonService, readAssetTemplate, renderLaunchdPlist, renderSystemdSystemUnit, renderSystemdUserUnit, resolveHqBinary, resolveNodeBinary, uninstallDaemonService, } from "./install.js";
+export { buildInstallPaths, daemonServiceStatus, detectPlatform, installDaemonService, readAssetTemplate, restartDaemonServiceIfInstalled, renderLaunchdPlist, renderSystemdSystemUnit, renderSystemdUserUnit, resolveHqBinary, resolveNodeBinary, uninstallDaemonService, } from "./install.js";
 export type { DaemonInstallPlatform, InstallPaths, InstallResult, } from "./install.js";
+export { daemonConfigPath, readDaemonConfig, registerTrustedHqRoot, verifyHqRoot } from "./config.js";
+export type { DaemonConfig } from "./config.js";
 export { UNHEALTHY_SPOOL_AGE_MS, collectDaemonDoctor, formatDaemonDoctor, } from "./doctor.js";
 export type { DaemonDoctorDeps, DaemonDoctorReport } from "./doctor.js";
 export { scopeBundleToAgentIdentity, } from "./credentials.js";
-export { FLUSH_INTERVAL_MS, SPOOL_DEBOUNCE_MS, runMeshDaemon, } from "./run.js";
+export { FLUSH_INTERVAL_MS, DAEMON_VERSION_DRIFT_EXIT_CODE, SPOOL_DEBOUNCE_MS, runMeshDaemon, } from "./run.js";
 export type { DaemonHandle, DaemonRunDeps } from "./run.js";
 export { TRANSCRIPT_ADAPTER_VERSION, TRANSCRIPT_EVENT_SOURCE, TRANSCRIPT_FRESH_MS, TRANSCRIPT_HOOK_COVER_MS, TRANSCRIPT_MARKER, TRANSCRIPT_SESSION_END_MS, TRANSCRIPT_TURN_QUIET_MS, TRANSCRIPT_WATCH_BACKOFF_DURATION_MS, TRANSCRIPT_WATCH_BACKOFF_ENTRIES, TRANSCRIPT_WATCH_ENTRY_CAP, TRANSCRIPT_WATCH_INTERVAL_MAX_MS, TRANSCRIPT_WATCH_INTERVAL_MS, TRANSCRIPT_WATCH_REVALIDATE_MS, TranscriptWatcher, createTranscriptDiscoverCache, decodeClaudeProjectDirName, defaultTranscriptFs, discoverTranscripts, discoverTranscriptsWithMeta, isTranscriptHookCovered, nextTranscriptWatchIntervalMs, noteHookSessionsFromSpoolFile, resolveTranscriptRegistration, sessionIdFromClaudeTranscriptPath, sessionIdFromCodexTranscriptPath, sortDiscoveries, } from "./transcript-watch.js";
 export type { DiscoveredTranscript, DiscoverScanMeta, DiscoverTranscriptsResult, TranscriptDiscoverCache, TranscriptFs, TranscriptKind, TranscriptWatchDeps, TranscriptWatchTickResult, } from "./transcript-watch.js";

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

@@ -6,9 +6,10 @@ export { CLOSE_LOG_ALWAYS_COUNT, CLOSE_LOG_INTERVAL_MS, CONNECT_STABLE_GRACE_MS,
 export { defaultDaemonState, patchDaemonState, readDaemonState, writeDaemonState, } from "./state.js";
 export { appendDaemonLog, daemonLogLine, ensureDaemonLog, resolveDaemonAssetDir, rotateDaemonLogIfNeeded, } from "./log.js";
 export { BOARD_REFRESH_INTERVAL_MS, createVaultBoardReader, formatBoardMarkdown, refreshBoundSessionBoards, writeBoardMarkdown, } from "./board-refresh.js";
-export { buildInstallPaths, daemonServiceStatus, detectPlatform, installDaemonService, readAssetTemplate, renderLaunchdPlist, renderSystemdSystemUnit, renderSystemdUserUnit, resolveHqBinary, resolveNodeBinary, uninstallDaemonService, } from "./install.js";
+export { buildInstallPaths, daemonServiceStatus, detectPlatform, installDaemonService, readAssetTemplate, restartDaemonServiceIfInstalled, renderLaunchdPlist, renderSystemdSystemUnit, renderSystemdUserUnit, resolveHqBinary, resolveNodeBinary, uninstallDaemonService, } from "./install.js";
+export { daemonConfigPath, readDaemonConfig, registerTrustedHqRoot, verifyHqRoot } from "./config.js";
 export { UNHEALTHY_SPOOL_AGE_MS, collectDaemonDoctor, formatDaemonDoctor, } from "./doctor.js";
 export { scopeBundleToAgentIdentity, } from "./credentials.js";
-export { FLUSH_INTERVAL_MS, SPOOL_DEBOUNCE_MS, runMeshDaemon, } from "./run.js";
+export { FLUSH_INTERVAL_MS, DAEMON_VERSION_DRIFT_EXIT_CODE, SPOOL_DEBOUNCE_MS, runMeshDaemon, } from "./run.js";
 export { TRANSCRIPT_ADAPTER_VERSION, TRANSCRIPT_EVENT_SOURCE, TRANSCRIPT_FRESH_MS, TRANSCRIPT_HOOK_COVER_MS, TRANSCRIPT_MARKER, TRANSCRIPT_SESSION_END_MS, TRANSCRIPT_TURN_QUIET_MS, TRANSCRIPT_WATCH_BACKOFF_DURATION_MS, TRANSCRIPT_WATCH_BACKOFF_ENTRIES, TRANSCRIPT_WATCH_ENTRY_CAP, TRANSCRIPT_WATCH_INTERVAL_MAX_MS, TRANSCRIPT_WATCH_INTERVAL_MS, TRANSCRIPT_WATCH_REVALIDATE_MS, TranscriptWatcher, createTranscriptDiscoverCache, decodeClaudeProjectDirName, defaultTranscriptFs, discoverTranscripts, discoverTranscriptsWithMeta, isTranscriptHookCovered, nextTranscriptWatchIntervalMs, noteHookSessionsFromSpoolFile, resolveTranscriptRegistration, sessionIdFromClaudeTranscriptPath, sessionIdFromCodexTranscriptPath, sortDiscoveries, } from "./transcript-watch.js";
 //# sourceMappingURL=index.js.map

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

@@ -23,6 +23,8 @@ export interface InstallPaths {
     systemdUnitPath: string;
     /** When true, render the root/ec2-user system unit instead of user unit. */
     systemUser?: string;
+    /** Verified HQ root to persist and pass to the installed service. */
+    hqRoot?: string;
 }
 export interface InstallResult {
     platform: DaemonInstallPlatform;
@@ -33,6 +35,26 @@ export interface InstallResult {
     running?: boolean;
     message: string;
 }
+/** Best-effort restart result used after an in-place CLI upgrade. */
+export interface RestartDaemonResult {
+    attempted: boolean;
+    restarted: boolean;
+    message?: string;
+}
+/**
+ * Restart the installed user daemon after a CLI upgrade. This is deliberately
+ * best-effort: an update must remain successful if a user has no service,
+ * launchctl/systemd is unavailable, or the user manager is not running.
+ */
+export declare function restartDaemonServiceIfInstalled(opts?: {
+    platform?: DaemonInstallPlatform;
+    home?: string;
+    uid?: number;
+    existsSync?: typeof fs.existsSync;
+    run?: (command: string, args: string[]) => {
+        status: number | null;
+    };
+}): RestartDaemonResult;
 export declare function detectPlatform(platform?: NodeJS.Platform): DaemonInstallPlatform;
 /**
  * HQ updates moved the CLI from toolchain/node/bin/hq to
@@ -53,6 +75,7 @@ export declare function buildInstallPaths(opts: {
     env?: NodeJS.ProcessEnv;
     argv?: string[];
     execPath?: string;
+    hqRoot?: string;
 }): InstallPaths;
 export declare function renderLaunchdPlist(paths: InstallPaths): string;
 export declare function renderSystemdUserUnit(paths: InstallPaths): string;
@@ -70,6 +93,10 @@ export declare function installDaemonService(opts: {
     mkdirSync?: typeof fs.mkdirSync;
     /** Optional: actually load the service (disabled in tests). */
     activate?: (platform: DaemonInstallPlatform, dest: string) => void;
+    /** Reload a rewritten user unit so a legacy Restart=on-failure unit migrates immediately. */
+    reloadSystemd?: () => {
+        status: number | null;
+    };
 }): InstallResult;
 export declare function uninstallDaemonService(opts: {
     platform?: DaemonInstallPlatform;

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

@@ -12,8 +12,54 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { spawnSync } from "node:child_process";
 import { resolveDaemonAssetDir } from "./log.js";
 import { LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, daemonDir, daemonLogPath, } from "./paths.js";
+import { registerTrustedHqRoot } from "./config.js";
+/**
+ * Restart the installed user daemon after a CLI upgrade. This is deliberately
+ * best-effort: an update must remain successful if a user has no service,
+ * launchctl/systemd is unavailable, or the user manager is not running.
+ */
+export function restartDaemonServiceIfInstalled(opts = {}) {
+    const platform = opts.platform ?? detectPlatform();
+    const home = opts.home ?? os.homedir();
+    const existsSync = opts.existsSync ?? fs.existsSync;
+    const run = opts.run ?? ((command, args) => spawnSync(command, args, { stdio: "ignore" }));
+    try {
+        if (platform === "darwin") {
+            const plist = path.join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+            if (!existsSync(plist))
+                return { attempted: false, restarted: false };
+            const uid = opts.uid ?? process.getuid?.();
+            if (typeof uid !== "number")
+                return { attempted: false, restarted: false };
+            const result = run("launchctl", ["kickstart", "-k", `gui/${uid}/${LAUNCHD_LABEL}`]);
+            return { attempted: true, restarted: result.status === 0 };
+        }
+        if (platform === "linux") {
+            const unit = path.join(home, ".config", "systemd", "user", SYSTEMD_UNIT_NAME);
+            if (existsSync(unit)) {
+                const result = run("systemctl", ["--user", "restart", SYSTEMD_UNIT_NAME]);
+                return { attempted: true, restarted: result.status === 0 };
+            }
+            const systemUnit = path.join("/etc", "systemd", "system", SYSTEMD_UNIT_NAME);
+            if (existsSync(systemUnit)) {
+                return {
+                    attempted: true,
+                    restarted: false,
+                    message: "system unit detected; restart requires the box's service manager",
+                };
+            }
+            return { attempted: false, restarted: false };
+        }
+    }
+    catch {
+        // The caller has already completed the update; service restart failure is
+        // intentionally non-fatal and will be retried by normal service recovery.
+    }
+    return { attempted: false, restarted: false };
+}
 export function detectPlatform(platform = process.platform) {
     if (platform === "darwin")
         return "darwin";
@@ -83,6 +129,7 @@ export function buildInstallPaths(opts) {
         systemdUserDir: path.join(home, ".config", "systemd", "user"),
         systemdUnitPath: path.join(home, ".config", "systemd", "user", SYSTEMD_UNIT_NAME),
         systemUser: opts.systemUser,
+        hqRoot: opts.hqRoot,
     };
 }
 export function renderLaunchdPlist(paths) {
@@ -116,6 +163,7 @@ export function renderLaunchdPlist(paths) {
     <string>${escapeXml(paths.home)}</string>
     <key>PATH</key>
     <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    ${paths.hqRoot ? `<key>HQ_ROOT</key>\n    <string>${escapeXml(paths.hqRoot)}</string>` : ""}
   </dict>
 </dict>
 </plist>
@@ -131,11 +179,11 @@ Wants=network-online.target
 Type=simple
 ExecStart=${shellQuote(paths.nodeBinary)} ${shellQuote(paths.hqBinary)} mesh daemon run
 WorkingDirectory=${paths.daemonDir}
-Restart=on-failure
+Restart=always
 RestartSec=5
 Environment=HOME=${paths.home}
 Environment=PATH=/usr/local/bin:/usr/bin:/bin
-StandardOutput=append:${paths.logPath}
+${paths.hqRoot ? `Environment=HQ_ROOT=${shellQuote(paths.hqRoot)}\n` : ""}StandardOutput=append:${paths.logPath}
 StandardError=append:${paths.logPath}
 
 [Install]
@@ -163,13 +211,13 @@ User=${user}
 Group=${user}
 ExecStart=${shellQuote(paths.nodeBinary)} ${shellQuote(paths.hqBinary)} mesh daemon run
 WorkingDirectory=/home/${user}/.hq/work-mesh/daemon
-Restart=on-failure
+Restart=always
 RestartSec=5
 Environment=HOME=/home/${user}
 Environment=PATH=/usr/local/bin:/usr/bin:/bin
 Environment=HQ_MACHINE_CREDS_FILE=/home/${user}/.hq-agent/machine-creds.json
 Environment=HQ_AGENT_IDENTITY_FILE=/var/lib/hq-agent/identity.json
-StandardOutput=append:/home/${user}/.hq/work-mesh/daemon/log
+${paths.hqRoot ? `Environment=HQ_ROOT=${shellQuote(paths.hqRoot)}\n` : ""}StandardOutput=append:/home/${user}/.hq/work-mesh/daemon/log
 StandardError=append:/home/${user}/.hq/work-mesh/daemon/log
 
 [Install]
@@ -195,6 +243,7 @@ export function installDaemonService(opts) {
     const writeFileSync = opts.writeFileSync ?? fs.writeFileSync;
     const mkdirSync = opts.mkdirSync ?? fs.mkdirSync;
     mkdirSync(paths.daemonDir, { recursive: true, mode: 0o700 });
+    registerTrustedHqRoot(paths.daemonDir, paths.hqRoot);
     if (platform === "darwin") {
         const rendered = renderLaunchdPlist(paths);
         mkdirSync(paths.launchAgentsDir, { recursive: true });
@@ -232,6 +281,7 @@ export function installDaemonService(opts) {
         const rendered = renderSystemdUserUnit(paths);
         mkdirSync(paths.systemdUserDir, { recursive: true });
         writeFileSync(paths.systemdUnitPath, rendered, { mode: 0o600 });
+        (opts.reloadSystemd ?? (() => spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" })))();
         opts.activate?.(platform, paths.systemdUnitPath);
         return {
             platform,

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

@@ -19,6 +19,8 @@ export declare const SPOOL_DEBOUNCE_MS = 2000;
 export declare const FLUSH_INTERVAL_MS = 10000;
 /** Keep startup recovery bounded: the next daemon start continues the backlog. */
 export declare const HELD_BACKFILL_STARTUP_BATCH_SIZE = 100;
+/** Non-zero exit reserved for CLI version drift so legacy Restart=on-failure units restart. */
+export declare const DAEMON_VERSION_DRIFT_EXIT_CODE = 75;
 /**
  * Only producer appends to spool.jsonl should wake the watcher. Every other
  * file in the work-mesh root (held.jsonl, spool.<ts>.claimed, held.<ts>.claimed,
@@ -80,6 +82,10 @@ export interface DaemonRunDeps {
     log?: (dir: string, line: string) => void;
     /** Stop after this many ms (tests). */
     runForMs?: number;
+    /** CLI version loaded by this daemon. Defaults to this package's version. */
+    daemonVersion?: string;
+    /** Read the currently installed CLI version behind the launch entrypoint. */
+    readInstalledCliVersion?: () => string | null;
     random?: () => number;
     now?: () => Date;
 }