@indigoai-us/hq-cli 5.123.0 → 5.123.1

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/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;
@@ -50,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,6 +111,9 @@ 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})`);
@@ -125,6 +139,7 @@ export function collectDaemonDoctor(deps = {}) {
         companiesOnline,
         spoolDepth,
         heldCount,
+        heldWithNoLocalEvidence,
         deadLetterCount,
         unattributedEvents,
         outboxDepth: outbox.depth,
@@ -162,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}`);

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;
 }

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

@@ -11,6 +11,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { CLI_VERSION } from "../../../../cli-version.js";
 import { createWorkSessionDeliverer } from "../../client.js";
 import { meshJson, resolveActiveMembershipCompany } from "../../api.js";
 import { ensureCognitoToken } from "../../../../utils/cognito-session.js";
@@ -31,10 +32,14 @@ import { defaultDaemonState, patchDaemonState, writeDaemonState, } from "./state
 import { workMeshHeldPath } from "../paths.js";
 import { noteHookSessionsFromSpoolFile, TRANSCRIPT_WATCH_INTERVAL_MS, TranscriptWatcher, } from "./transcript-watch.js";
 import { resolveMeshEmitMode, runsEmitPath, } from "./mode.js";
+import { hasCliVersionDrift, readInstalledCliVersion } from "./version-drift.js";
+import { readDaemonConfig } from "./config.js";
 export const SPOOL_DEBOUNCE_MS = 2_000;
 export const FLUSH_INTERVAL_MS = 10_000;
 /** Keep startup recovery bounded: the next daemon start continues the backlog. */
 export const HELD_BACKFILL_STARTUP_BATCH_SIZE = 100;
+/** Non-zero exit reserved for CLI version drift so legacy Restart=on-failure units restart. */
+export 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,
@@ -76,7 +81,15 @@ export async function runMeshDaemon(deps = {}) {
         ((d, line) => appendDaemonLog(d, daemonLogLine("info", line, now)));
     const processEvents = deps.processEvents ?? process;
     const exit = deps.exit ?? ((code) => process.exit(code));
+    const daemonVersion = deps.daemonVersion ?? CLI_VERSION;
+    const installedCliVersion = deps.readInstalledCliVersion ?? readInstalledCliVersion;
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const configuredRoots = readDaemonConfig(dir).trustedHqRoots;
+    const trustedRoots = [...new Set([
+            ...(deps.hqRoot ? [deps.hqRoot] : []),
+            ...(env.HQ_ROOT?.trim() ? [env.HQ_ROOT.trim()] : []),
+            ...configuredRoots,
+        ])];
     ensureDaemonLog(dir);
     const lockDeps = deps.pidLock ?? defaultPidLockDeps({ isProcessAlive: alive });
     const lock = acquirePidLock(dir, lockDeps);
@@ -132,6 +145,7 @@ export async function runMeshDaemon(deps = {}) {
             return backfillHeldSessions({
                 workMeshRoot: meshRoot,
                 workContextRoot: ctxRoot,
+                hqRoots: trustedRoots,
                 limit: deps.heldBackfillBatchSize ?? HELD_BACKFILL_STARTUP_BATCH_SIZE,
                 env,
                 reconcile: (observation) => reconcileObservation(observation, {
@@ -223,15 +237,28 @@ export async function runMeshDaemon(deps = {}) {
         }
     }
     let stopped = false;
+    let restartRequested = false;
     let flushInFlight = null;
     let debounceHandle = null;
     let flushIntervalHandle = null;
+    let versionIntervalHandle = null;
     let boardIntervalHandle = null;
     let transcriptIntervalHandle = null;
     let watcher = null;
     /** Shared with transcript watcher: sessionIds seen on the hook/spool path. */
     const lastHookEventAt = new Map();
     let transcriptWatcher = null;
+    const requestRestartForVersionDrift = () => {
+        if (stopped || restartRequested)
+            return restartRequested;
+        const installedVersion = installedCliVersion();
+        if (!hasCliVersionDrift(daemonVersion, installedVersion))
+            return false;
+        restartRequested = true;
+        log(dir, `cli upgraded ${daemonVersion} -> ${installedVersion}, restarting`);
+        exit(DAEMON_VERSION_DRIFT_EXIT_CODE);
+        return true;
+    };
     if (emitPath && deps.enableTranscriptWatch !== false) {
         const hqRoot = deps.hqRoot ?? env.HQ_ROOT?.trim() ?? undefined;
         const getToken = deps.getToken ?? defaultGetToken;
@@ -273,7 +300,12 @@ export async function runMeshDaemon(deps = {}) {
     }
     const doFlushCycle = async (reason, opts = {}) => {
         // Refuse new cycles after stop, except the forced shutdown flush.
-        if (stopped && !opts.force)
+        if ((stopped || restartRequested) && !opts.force)
+            return;
+        // A long-lived daemon retains its loaded JS after a global CLI upgrade.
+        // The service unit resolves the binary again on restart, so exiting lets
+        // launchd/systemd bring up the upgraded implementation.
+        if (!opts.force && requestRestartForVersionDrift())
             return;
         if (flushInFlight) {
             await flushInFlight;
@@ -405,6 +437,14 @@ export async function runMeshDaemon(deps = {}) {
             boardIntervalHandle = timers.setTimeout(boardTick, BOARD_REFRESH_INTERVAL_MS);
         });
     }, BOARD_REFRESH_INTERVAL_MS);
+    // Version drift is independent of the legacy spool flush. Direct-mode
+    // daemons have no flush cycle, so they still need the same periodic restart
+    // check after an in-place CLI upgrade.
+    versionIntervalHandle = timers.setTimeout(function versionTick() {
+        if (stopped || requestRestartForVersionDrift())
+            return;
+        versionIntervalHandle = timers.setTimeout(versionTick, FLUSH_INTERVAL_MS);
+    }, FLUSH_INTERVAL_MS);
     const runTranscriptTick = async () => {
         if (!transcriptWatcher || stopped)
             return;
@@ -447,7 +487,7 @@ export async function runMeshDaemon(deps = {}) {
     }
     // Initial pass. Board refresh runs in both modes; the flush + transcript
     // scan are legacy emit-path only.
-    if (emitPath) {
+    if (!requestRestartForVersionDrift() && emitPath) {
         void doFlushCycle("start");
     }
     void refreshFn().catch(() => undefined);
@@ -463,6 +503,8 @@ export async function runMeshDaemon(deps = {}) {
             timers.clearTimeout(debounceHandle);
         if (flushIntervalHandle !== null)
             timers.clearTimeout(flushIntervalHandle);
+        if (versionIntervalHandle !== null)
+            timers.clearTimeout(versionIntervalHandle);
         if (boardIntervalHandle !== null)
             timers.clearTimeout(boardIntervalHandle);
         if (transcriptIntervalHandle !== null) {

package/dist/lib/mesh/live/daemon/version-drift.d.ts

@@ -0,0 +1,5 @@
+/** Version installed behind the entrypoint that launched this daemon. */
+export declare function readInstalledCliVersion(entry?: string): string | null;
+/** A missing/unreadable installed version is not proof of a safe restart. */
+export declare function hasCliVersionDrift(daemonVersion: string, installedVersion: string | null | undefined): installedVersion is string;
+//# sourceMappingURL=version-drift.d.ts.map

package/dist/lib/mesh/live/daemon/version-drift.js

@@ -0,0 +1,47 @@
+/**
+ * Read the version of the CLI package currently selected by the daemon's
+ * launch entrypoint. The daemon keeps the version it was loaded with in
+ * memory; an npm/pnpm upgrade can repoint this entrypoint without restarting
+ * that process.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+function packageVersionAtOrAbove(entry) {
+    let dir;
+    try {
+        dir = path.dirname(fs.realpathSync(entry));
+    }
+    catch {
+        return null;
+    }
+    // A CLI entrypoint is normally <package>/dist/index.js. Keep the walk
+    // bounded so a malformed entrypoint never traverses an entire filesystem.
+    for (let i = 0; i < 8; i += 1) {
+        const pkgPath = path.join(dir, "package.json");
+        try {
+            const parsed = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            if (parsed.name === "@indigoai-us/hq-cli" &&
+                typeof parsed.version === "string" &&
+                parsed.version.trim()) {
+                return parsed.version.trim();
+            }
+        }
+        catch {
+            // No package manifest at this level; continue walking upward.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Version installed behind the entrypoint that launched this daemon. */
+export function readInstalledCliVersion(entry = process.argv[1]) {
+    return entry ? packageVersionAtOrAbove(entry) : null;
+}
+/** A missing/unreadable installed version is not proof of a safe restart. */
+export function hasCliVersionDrift(daemonVersion, installedVersion) {
+    return Boolean(installedVersion && installedVersion !== daemonVersion);
+}
+//# sourceMappingURL=version-drift.js.map

package/dist/lib/mesh/live/paths.d.ts

@@ -6,6 +6,8 @@ export declare const WORK_MESH_DIRNAME = "work-mesh";
 export declare function workMeshRoot(home?: string, env?: NodeJS.ProcessEnv): string;
 export declare function workMeshSpoolPath(root?: string): string;
 export declare function workMeshHeldPath(root?: string): string;
+/** Rotating cursor for bounded daemon-start held-event recovery. */
+export declare function workMeshHeldBackfillCursorPath(root?: string): string;
 export declare function workMeshDeadLetterPath(root?: string): string;
 export declare function workMeshDroppedReceiptPath(root?: string): string;
 /** Claim path: spool.<ts>.claimed (never reuse spool.jsonl for claim). */

package/dist/lib/mesh/live/paths.js

@@ -17,6 +17,10 @@ export function workMeshSpoolPath(root) {
 export function workMeshHeldPath(root) {
     return path.join(root ?? workMeshRoot(), "held.jsonl");
 }
+/** Rotating cursor for bounded daemon-start held-event recovery. */
+export function workMeshHeldBackfillCursorPath(root) {
+    return path.join(root ?? workMeshRoot(), "held-backfill-cursor.json");
+}
 export function workMeshDeadLetterPath(root) {
     return path.join(root ?? workMeshRoot(), "dead-letter.jsonl");
 }

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

@@ -10,7 +10,7 @@ import { EXIT_INVALID_IDENTITY, EXIT_NOT_TRACKING, EXIT_OK, InvalidDecisionOrigi
 import { decisionFromCandidates, } from "./organize.js";
 import { resolveProjectTask, shouldAskAfter } from "./project.js";
 import { deriveRemoteOwnerSlug, deriveRepoIdentityKey } from "./repo-remote.js";
-import { enqueueOutbox, markOutboxAcked, markOutboxQuarantined, markOutboxQueued, replayOutbox, writeAckedRegisterState, } from "./outbox.js";
+import { enqueueOutbox, listOutboxOperations, markOutboxAcked, markOutboxQuarantined, markOutboxQueued, replayOutbox, writeAckedRegisterState, } from "./outbox.js";
 import { mergeLocalSessionFields, readSessionState, writeSessionState, } from "./state.js";
 function resultOf(parts) {
     const out = {
@@ -293,12 +293,10 @@ export async function reconcileObservation(obs, deps) {
             startedAt,
             ...(typeof toolWrites === "number" ? { toolWrites } : {}),
             ...(hasTurn ? { hasTurn: true } : {}),
-            // Preserve prior binding ids for visibility; do not auto-switch.
+            // Preserve prior scope for visibility; its receipt belongs to the
+            // quarantined binding and must not suppress a later retry.
             ...(prior?.projectId ? { projectId: prior.projectId } : {}),
             ...(prior?.taskId ? { taskId: prior.taskId } : {}),
-            ...(prior?.bindingEpisodeId
-                ? { bindingEpisodeId: prior.bindingEpisodeId }
-                : {}),
             ...transcriptFields,
             decision: {
                 decisionId: `conflict_${sessionId}`,
@@ -325,7 +323,7 @@ export async function reconcileObservation(obs, deps) {
                 askAfter: false,
                 ...(correctionPath ? { correctionPath } : {}),
             },
-        }, prior), deps.root);
+        }, prior, { preserveBindingEpisode: false }), deps.root);
         return {
             result: resultOf({
                 kind: "company_conflict",
@@ -491,6 +489,69 @@ export async function reconcileObservation(obs, deps) {
         prior.bindingEpisodeId
         ? "needs_project"
         : registerClassification;
+    // Re-observing an already acknowledged binding is normal for hooks and the
+    // resident daemon. A fresh clientOperationId must not turn that observation
+    // into a second semantic register operation: the prior receipt is the stable
+    // identity for this exact company/project/task binding.
+    const acknowledgedPrior = prior?.bindingEpisodeId &&
+        prior.companyUid === resolvedCompany.uid &&
+        prior.companySlug === resolvedCompany.slug &&
+        prior.projectId === projectId &&
+        prior.taskId === taskId &&
+        listOutboxOperations(deps.root).some((operation) => operation.kind === "register" &&
+            operation.delivery === "acked" &&
+            operation.sessionId === sessionId &&
+            operation.receiptId === prior.bindingEpisodeId &&
+            operation.companyUid === resolvedCompany.uid &&
+            operation.companySlug === resolvedCompany.slug &&
+            operation.projectId === projectId &&
+            operation.taskId === taskId)
+        ? prior
+        : null;
+    if (acknowledgedPrior) {
+        // Activity is local progress, not binding identity. Retain the receipt
+        // without another register while carrying hook counters forward so the
+        // normal clarification threshold still advances.
+        writeSessionState(mergeLocalSessionFields({
+            contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+            sessionId,
+            companyUid: acknowledgedPrior.companyUid,
+            companySlug: acknowledgedPrior.companySlug,
+            contextStatus: stateClassification,
+            projectId,
+            taskId,
+            bindingEpisodeId: acknowledgedPrior.bindingEpisodeId,
+            updatedAt: nowIso,
+            startedAt,
+            ...(typeof toolWrites === "number" ? { toolWrites } : {}),
+            ...(hasTurn ? { hasTurn: true } : {}),
+            ...(decision ? { decision } : {}),
+            ...transcriptFields,
+        }, prior), deps.root);
+        const kind = registerClassification === "bound"
+            ? "bound"
+            : registerClassification === "needs_task"
+                ? "needs_task"
+                : registerClassification === "needs_project"
+                    ? "needs_project"
+                    : "queued";
+        diagnostics.push(`binding unchanged; retained receipt=${acknowledgedPrior.bindingEpisodeId}`);
+        return {
+            result: resultOf({
+                kind,
+                classification: registerClassification,
+                delivery: "acked",
+                sessionId,
+                clientOperationId: obs.clientOperationId,
+                companyUid: resolvedCompany.uid,
+                projectId,
+                taskId,
+                bindingEpisodeId: acknowledgedPrior.bindingEpisodeId,
+            }),
+            exitCode: EXIT_OK,
+            diagnostics,
+        };
+    }
     let outboxOp;
     try {
         outboxOp = enqueueOutbox({