@indigoai-us/hq-cli 5.345.169 → 5.345.171

package/dist/lib/bot/local-config.js

@@ -9,7 +9,7 @@
  * checks the result before it leaves this machine: a bot's machine credentials
  * live only in ~/.hq/bots/<name>/machine-creds.json and never travel here.
  */
-import { botMemoryMode, effectiveBotCompanies, effectiveBotKind, isBotKind, isBotMemoryMode, isBotRuntimeId, } from "./config.js";
+import { botMemoryMode, effectiveBotCompanies, effectiveBotKind, isBotKind, isBotEngineMetadata, isBotMemoryMode, isBotRuntimeId, } from "./config.js";
 /** Same limit the server enforces on the stored value. */
 const BOT_LOCAL_CONFIG_MAX_BYTES = 8 * 1024;
 /** Key names the server rejects outright (case-insensitive, substring). */
@@ -41,7 +41,8 @@ export function buildBotLocalConfig(config) {
     const companies = effectiveBotCompanies(config);
     const local = {
         v: 1,
-        runtime: config.runtime,
+        ...(config.engine ? {} : { runtime: config.runtime }),
+        ...(config.engine ? { engine: config.engine } : {}),
         workerSource: config.workerSource ?? "scaffold",
         ...(config.workerId ? { workerId: config.workerId } : {}),
         ...(config.companySlug ? { companySlug: config.companySlug } : {}),
@@ -80,6 +81,8 @@ export function parseBotLocalConfig(value) {
     const runtime = str("runtime");
     if (isBotRuntimeId(runtime))
         out.runtime = runtime;
+    if (isBotEngineMetadata(raw.engine))
+        out.engine = raw.engine;
     const workerSource = str("workerSource");
     if (workerSource === "worker" || workerSource === "scaffold")
         out.workerSource = workerSource;

package/dist/lib/bot/promote.d.ts

@@ -1,5 +1,14 @@
 import type { BotApi, BotPromotionState } from "./api.js";
 import type { BotConfig } from "./config.js";
+import type { BotMachineCreds } from "./creds.js";
+/** A bot whose process and HQ machine credential live outside its state folder,
+ * such as an HQ Fleet Runtime bot: promotion stops its service through the
+ * runtime and reads the credential from the runtime's secure store.
+ */
+export interface LocalBotPromotionRuntime {
+    stop(): void;
+    machineCredential(): BotMachineCreds;
+}
 /** One recoverable local-to-cloud step, used by CLI and desktop. Never kills the
  * local runtime, recopies provider login files, or changes another bot.
  */
@@ -9,6 +18,7 @@ export declare function promoteLocalBot(input: {
     companyUid: string;
     api: BotApi;
     drainTimeoutMs?: number;
+    runtime?: LocalBotPromotionRuntime;
 }): Promise<{
     promotion: BotPromotionState;
     pending: boolean;

package/dist/lib/bot/promote.js

@@ -41,7 +41,7 @@ function readPrivateJson(file, limit) {
  * local runtime, recopies provider login files, or changes another bot.
  */
 export async function promoteLocalBot(input) {
-    const { dir, config, companyUid, api } = input;
+    const { dir, config, companyUid, api, runtime } = input;
     const existing = await api.promotionStatus(config.agentUid, companyUid);
     const holdFile = path.join(dir, "promotion-hold.json");
     const localHold = fs.existsSync(holdFile) ? readPrivateJson(holdFile, 2048) : null;
@@ -58,6 +58,7 @@ export async function promoteLocalBot(input) {
         recordActivePromotion(dir, hold, existing);
         return { promotion: existing, pending: false };
     }
+    runtime?.stop();
     await waitForPromotionDrain(dir, input.drainTimeoutMs ?? 60_000);
     const file = path.join(dir, `promotion-snapshot-${operationId}.json`);
     if (!fs.existsSync(file)) {
@@ -83,7 +84,7 @@ export async function promoteLocalBot(input) {
         throw new Error("Frozen snapshot does not match the cloud operation");
     let state = existing;
     if (!state || state.phase === "preparing") {
-        const machine = readPrivateJson(botCredsPath(dir), 8192);
+        const machine = runtime ? runtime.machineCredential() : readPrivateJson(botCredsPath(dir), 8192);
         if (!machine || typeof machine !== "object" || typeof machine.secret !== "string")
             throw new Error("Invalid bot machine credential");
         try {

package/dist/lib/bot/run.d.ts

@@ -54,6 +54,7 @@ import { type BotLogger } from "./log.js";
 import { type CodingToolActivity, type DetectCodingToolActivityInput } from "./coding-tool-activity.js";
 import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "./runtime/index.js";
 import { type BotSessionScope } from "./paths.js";
+import { type DecisionDmClient } from "./decisions.js";
 import type { VaultObjectDownloader } from "../agent-kit/attachment-download.js";
 import { type HeartbeatAgentUidSource, type HeartbeatCredsSource, type HeartbeatIdentityMismatchReporter } from "../heartbeat-identity.js";
 import { type BotState, type BotStatusFile } from "./status.js";
@@ -188,6 +189,12 @@ export interface BotRunDeps {
      * never read the real home folder.
      */
     detectCodingToolActivity?: (input: DetectCodingToolActivityInput) => CodingToolActivity;
+    /**
+     * US-005: the decisions client (`hq decide`), called with the bot's own
+     * machine token. Owner DMs that answer a decision talking in this owner-bot
+     * thread are recorded through it. Unset leaves every owner DM on the model path.
+     */
+    decisions?: DecisionDmClient;
 }
 export declare const KICKOFF_MESSAGE_ID = "kickoff";
 /**

package/dist/lib/bot/run.js

@@ -74,6 +74,7 @@ import { runRuntimeTurn, RuntimeError } from "./runtime/index.js";
 import { botAttachmentsDir, dmSessionScope, isDmSessionScope } from "./paths.js";
 import { briefJobRunId, briefJobSessionScope, isBriefJobSessionScope } from "./brief-job.js";
 import { appendDmHistory, dmHistoryHasModelThread, markDmHistoryModelTurn, readDmHistory, withRecentDmHistory } from "./dm-history.js";
+import { handleDecisionDm, looksLikePick, DECISIONS_NOT_LIVE_REPLY, readDecisionTalkState, writeDecisionTalkState } from "./decisions.js";
 import { attachmentTurnBlock, downloadTurnAttachments } from "./attachments.js";
 import { inboxEntryAttachments } from "../agent-kit/inbox-state.js";
 import { isAgentSender, isDmItem, isMetaNonReply, resolveReplyTarget } from "./room-policy.js";
@@ -1942,6 +1943,104 @@ export async function runBot(deps) {
         log("info", `answered ${id} with the setup explanation (no model turn)`);
         return true;
     };
+    /**
+     * US-005: an owner DM about a decision talking in this owner-bot thread.
+     * Returns `done` when the message was answered here with no model turn
+     * (a recorded pick, an ambiguity question, or a failure line), or a note for
+     * the model turn. A send failure leaves the message unacked for the next poll.
+     */
+    let decisionsNotLiveUntil = 0;
+    const DECISIONS_NOT_LIVE_RECHECK_MS = 10 * 60 * 1000;
+    const runDecisionDm = async (item, text) => {
+        const decisionClient = deps.decisions;
+        if (!decisionClient || item.fromPersonUid !== config.ownerUid)
+            return { done: false };
+        let result;
+        const pendingReply = readDecisionTalkState(dir).pending?.[item.messageId];
+        if (pendingReply !== undefined) {
+            // Decided on an earlier poll (the pick may already be saved): only resend.
+            result = { kind: "reply", text: pendingReply, recorded: false };
+        }
+        else if (now().getTime() < decisionsNotLiveUntil) {
+            result = looksLikePick(text) ? { kind: "reply", text: DECISIONS_NOT_LIVE_REPLY, recorded: false, notLive: true } : { kind: "none" };
+        }
+        else {
+            let companyUids = null;
+            if (deps.ownerContext) {
+                try {
+                    const ctx = await deps.ownerContext();
+                    if (ctx.status === "ok")
+                        companyUids = ctx.companies.map((company) => company.companyUid);
+                }
+                catch (err) {
+                    log("warn", `decision company check failed (${err instanceof Error ? err.message : String(err)}); no pick is recorded`);
+                }
+            }
+            const talk = readDecisionTalkState(dir);
+            result = await handleDecisionDm({
+                text,
+                speakerUid: item.fromPersonUid,
+                ...(item.rootEventId ? { rootEventId: item.rootEventId } : {}),
+                ownerUid: config.ownerUid,
+                agentUid: config.agentUid,
+                companyUids,
+                nowMs: now().getTime(),
+                restated: new Set(Object.keys(talk.restated)),
+            }, decisionClient);
+            if (result.kind !== "model" && result.notLive) {
+                decisionsNotLiveUntil = now().getTime() + DECISIONS_NOT_LIVE_RECHECK_MS;
+                log("warn", "decisions API returned 404 (not deployed here); decision picks are off for 10 minutes");
+            }
+            if (result.kind === "model" && result.restate) {
+                try {
+                    await sendToTarget({ kind: "dm", peerUid: config.ownerUid }, result.restate, item.rootEventId, "human");
+                    const latest = readDecisionTalkState(dir);
+                    writeDecisionTalkState(dir, { ...latest, restated: { ...latest.restated, [result.decisionId]: now().toISOString() } });
+                }
+                catch (err) {
+                    log("warn", `decision restate for ${result.decisionId} not sent (${err instanceof Error ? err.message : String(err)})`);
+                }
+            }
+        }
+        if (result.kind === "none")
+            return { done: false };
+        if (result.kind === "model")
+            return { done: false, note: result.note };
+        const id = item.messageId;
+        const setPending = (text) => {
+            const state = readDecisionTalkState(dir);
+            const pending = { ...(state.pending ?? {}) };
+            if (text === null)
+                delete pending[id];
+            else
+                pending[id] = text;
+            writeDecisionTalkState(dir, { v: 1, restated: state.restated, ...(Object.keys(pending).length ? { pending } : {}) });
+        };
+        try {
+            setPending(result.text);
+        }
+        catch (err) {
+            log("warn", `decision reply for ${id} not saved locally (${err instanceof Error ? err.message : String(err)})`);
+        }
+        try {
+            await sendToTarget({ kind: "dm", peerUid: config.ownerUid }, result.text, item.rootEventId, "human");
+        }
+        catch (err) {
+            log("warn", `decision reply for ${id} could not be sent (${err instanceof Error ? err.message : String(err)}); it is retried on the next poll`);
+            return { done: true };
+        }
+        markProcessed(dir, id, now().toISOString());
+        try {
+            setPending(null);
+        }
+        catch {
+            // A stale entry is harmless: the message is processed and never re-read.
+        }
+        await api.ackInbox(config.agentUid, id);
+        setStatus({ repliesSent: (readStatus()?.repliesSent ?? 0) + 1, lastActivityAt: now().toISOString() });
+        log("info", `answered ${id} for decision ${result.decisionId ?? "(none)"}${result.recorded ? " (pick recorded)" : ""}, no model turn`);
+        return { done: true };
+    };
     const handleItem = async (item) => {
         const id = item.messageId;
         const inboxState = readInboxState(dir);
@@ -2005,6 +2104,9 @@ export async function runBot(deps) {
         const ownerDm = target.kind === "dm" && target.peerUid === config.ownerUid;
         if (isSetupBot && ownerDm && (await sendSetupExplanation(item, messageText, attachmentRefs.length)))
             return;
+        const decisionTurn = ownerDm && messageText ? await runDecisionDm(item, messageText) : { done: false };
+        if (decisionTurn.done)
+            return;
         const attempt = (attempts.get(id) ?? 0) + 1;
         attempts.set(id, attempt);
         const reactionId = item.eventId ?? id;
@@ -2100,7 +2202,8 @@ export async function runBot(deps) {
         // answering every note re-posted that question (three times in a row on
         // 2026-10-12). Such a turn may stay quiet.
         const appSetupNote = isSetupBot && ownerDm && isAppSetupNote(messageText);
-        const prompt = target.kind === "room" ? await buildRoomTurn(item, target, text) : target.peerUid === config.ownerUid ? (appSetupNote ? `${APP_SETUP_NOTE_TURN_NOTE}\n\n${ownerText}` : ownerText) :
+        const ownerTurnText = decisionTurn.note ? `${decisionTurn.note}\n\n${ownerText}` : ownerText;
+        const prompt = target.kind === "room" ? await buildRoomTurn(item, target, text) : target.peerUid === config.ownerUid ? (appSetupNote ? `${APP_SETUP_NOTE_TURN_NOTE}\n\n${ownerTurnText}` : ownerTurnText) :
             `[HQ DM sender: ${target.peerUid}; owner: ${config.ownerUid}; sender is not the owner.]\n\n${text}`;
         const markerTarget = target.kind === "dm" ? { kind: "dm", peerUid: target.peerUid } : { kind: "room", channelId: target.channelId };
         const { sendProgress, sendToPerson, saved } = trackingSend(markerTarget, item.rootEventId);

package/dist/lib/bot/runtime/index.js

@@ -1,7 +1,6 @@
 import { execFileSync, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { planBotRuntimeSpawn } from "./windows.js";
 import { GrokAcpClient } from "./grok-acp.js";
@@ -9,6 +8,7 @@ import { createClaudeRuntime } from "./claude.js";
 import { createCodexRuntime } from "./codex.js";
 import { createGrokRuntime, grokRetryArgsAfterInvalidOutputFormat, probeGrokOutputFormat } from "./grok.js";
 import { stripControlTokens } from "./sanitize.js";
+import { createTurnScratchDir } from "./scratch-dir.js";
 import { isRuntimeVersionTooOld, versionTooOldModel } from "../runtime-failure.js";
 import { parseJsonLine, RuntimeError, turnTimeoutMs, stderrExcerpt, MAX_MODEL_FALLBACK_RETRIES, } from "./types.js";
 export * from "./types.js";
@@ -345,10 +345,13 @@ export function forgetModelFallbacks() {
  */
 export async function runRuntimeTurn(runtime, input, deps = {}) {
     const spawnImpl = deps.spawnImpl ?? defaultSpawn;
-    const scratchDir = deps.scratchDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "hq-bot-turn-"));
+    const turnEnv = input.env ?? deps.env ?? process.env;
+    const turnPlatform = deps.platform ?? input.platform ?? process.platform;
+    const scratch = deps.scratchDir ? { dir: deps.scratchDir } : createTurnScratchDir("hq-bot-turn-", { platform: turnPlatform });
+    const scratchDir = scratch.dir;
     const outputFile = path.join(scratchDir, "last-message.txt");
     const newSessionId = input.newSessionId ?? (deps.newSessionId ?? randomUUID)();
-    const turnInput = { ...input, platform: deps.platform ?? input.platform ?? process.platform };
+    const turnInput = { ...input, platform: turnPlatform };
     const nowMs = deps.now ?? Date.now;
     const memoKey = fallbackKey(runtime, input.model);
     const memo = rememberedModelFallbacks.get(memoKey);
@@ -358,7 +361,8 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
     const args = runtime.buildArgs(remembered ? { ...turnInput, model: remembered.to } : turnInput, { outputFile, newSessionId });
     // Enforce at the model boundary too: old plists and direct `bot run` callers
     // may lack the guard. A bot prompt must never quit the user's desktop app.
-    const baseEnv = { ...(input.env ?? deps.env ?? process.env), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
+    // When TMPDIR was unwritable, hand the runtime CLI the working temp root too.
+    const baseEnv = { ...turnEnv, ...(scratch.fallbackRoot ? { TMPDIR: scratch.fallbackRoot } : {}), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
     const env = { ...(runtime.runtimeEnv?.(baseEnv) ?? baseEnv), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
     const binary = runtime.resolveBinary?.(env, input.cwd, turnInput.platform) ?? runtime.binary;
     const stdin = runtime.stdinInput?.(turnInput);

package/dist/lib/bot/runtime/scratch-dir.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-turn scratch folder for the local bot runtime (feedback_f0131909).
+ *
+ * A bot started by launchd/systemd at login can inherit a TMPDIR it cannot
+ * write yet (an external volume that is not mounted or not yet readable by the
+ * agent), so `mkdtemp` failed with EPERM on every turn until `hq bot restart`
+ * re-launched it with a working TMPDIR. Try the configured folder first, then
+ * /tmp, then ~/.hq/tmp. When TMPDIR works nothing changes.
+ */
+export interface TurnScratchDir {
+    /** The created scratch folder. */
+    dir: string;
+    /** The temp root used, when it is not the configured one. */
+    fallbackRoot?: string;
+}
+export interface TurnScratchDeps {
+    /** The configured temp root. Defaults to os.tmpdir(), exactly as before. */
+    tmpdir?: string;
+    platform?: NodeJS.Platform;
+    home?: string;
+    warn?: (line: string) => void;
+}
+export declare function createTurnScratchDir(prefix: string, deps?: TurnScratchDeps): TurnScratchDir;
+//# sourceMappingURL=scratch-dir.d.ts.map

package/dist/lib/bot/runtime/scratch-dir.js

@@ -0,0 +1,41 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** Warn once per unwritable folder per bot process, not on every turn. */
+const warned = new Set();
+/** Errors that mean "this folder cannot be used"; anything else is rethrown. */
+const UNUSABLE = new Set(["EPERM", "EACCES", "ENOENT", "ENOTDIR", "EROFS"]);
+export function createTurnScratchDir(prefix, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const home = deps.home ?? os.homedir();
+    const warn = deps.warn ?? ((line) => process.stderr.write(`${line}\n`));
+    const configured = deps.tmpdir ?? os.tmpdir();
+    const fallbacks = [];
+    if (platform !== "win32")
+        fallbacks.push("/tmp");
+    fallbacks.push(path.join(home, ".hq", "tmp"));
+    let firstError;
+    for (const root of [configured, ...fallbacks.filter((f) => f !== configured)]) {
+        try {
+            if (root !== configured)
+                fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+            const dir = fs.mkdtempSync(path.join(root, prefix));
+            if (root === configured) {
+                warned.delete(configured);
+                return { dir };
+            }
+            if (!warned.has(configured))
+                warn(`hq bot: temp folder ${configured} is not writable (${firstError?.code ?? "error"}); using ${root} instead. Fix TMPDIR or run hq bot restart.`);
+            warned.add(configured);
+            return { dir, fallbackRoot: root };
+        }
+        catch (err) {
+            const e = err;
+            if (!e.code || !UNUSABLE.has(e.code))
+                throw err;
+            firstError ??= e;
+        }
+    }
+    throw new Error(`hq bot cannot create a temporary folder: ${configured} is not writable (${firstError?.code ?? "error"}), and ${fallbacks.join(" and ")} did not work either. Fix TMPDIR or run hq bot restart.`);
+}
+//# sourceMappingURL=scratch-dir.js.map

package/dist/lib/caller-principal.d.ts

@@ -0,0 +1,4 @@
+export declare function callerIsMachinePrincipal(env?: NodeJS.ProcessEnv): boolean;
+/** True when the token names an agent (agt_) or outpost (out_) identity. */
+export declare function tokenIsMachinePrincipal(token: string): boolean;
+//# sourceMappingURL=caller-principal.d.ts.map

package/dist/lib/caller-principal.js

@@ -0,0 +1,40 @@
+/**
+ * Whether the current caller is a machine principal (a local bot, an
+ * agent-kit agent, a hosted agent or an outpost) or a person login.
+ *
+ * The answer comes from the credentials the request will actually use, never
+ * from a user flag:
+ * - CLI sends go through `ensureCognitoToken()`, which picks machine tokens
+ *   exactly when `wantsMachineCognitoTokens()` is true (HQ_MACHINE_CREDS_FILE
+ *   set and valid, or the default machine creds file on a box with no person
+ *   session). This check reads local state only and makes no network call.
+ * - Callers that already hold a token (the agent-kit MCP tools) use
+ *   `tokenIsMachinePrincipal`, which reads the token's identity claims.
+ */
+import { wantsMachineCognitoTokens } from "../utils/machine-principal-state.js";
+import { peekIdToken } from "../utils/id-token.js";
+export function callerIsMachinePrincipal(env = process.env) {
+    try {
+        return wantsMachineCognitoTokens({}, env);
+    }
+    catch {
+        return false;
+    }
+}
+const MACHINE_ENTITY_TYPES = new Set(["agent", "outpost", "company-outpost"]);
+/** True when the token names an agent (agt_) or outpost (out_) identity. */
+export function tokenIsMachinePrincipal(token) {
+    let claims;
+    try {
+        claims = peekIdToken(token);
+    }
+    catch {
+        return false;
+    }
+    const type = claims["custom:entityType"];
+    if (typeof type === "string" && MACHINE_ENTITY_TYPES.has(type))
+        return true;
+    const uid = claims["custom:entityUid"];
+    return typeof uid === "string" && /^(agt|out)_/.test(uid);
+}
+//# sourceMappingURL=caller-principal.js.map

package/dist/lib/capacity/collectors/grok.js

@@ -192,7 +192,10 @@ export function mapGrokBillingBody(body, options) {
 export async function collectGrok(options = {}) {
     const ledger = ledgerOptions(options);
     const root = ledger.root ?? capacityRoot(ledger.env, ledger.home);
-    const scoped = { ...ledger, root };
+    // Forward the injected clock so ledger retention and now.json use the same
+    // instant as observedAt; otherwise retention runs on the wall clock and can
+    // delete readings this call just wrote.
+    const scoped = { ...ledger, root, now: options.now ?? ledger.now };
     if (readCollectorMark(scoped)?.enabled === false && !options.allowDisabled) {
         return { readings: [], failures: [], view: null, skipped: "disabled", accountId: null };
     }
@@ -474,7 +477,10 @@ function stampAccount(row, options, planType) {
 async function collectEnumeratedGrok(options) {
     const ledger = ledgerOptions(options);
     const root = ledger.root ?? capacityRoot(ledger.env, ledger.home);
-    const scoped = { ...ledger, root };
+    // Forward the injected clock so ledger retention and now.json use the same
+    // instant as observedAt; otherwise retention runs on the wall clock and can
+    // delete readings this call just wrote.
+    const scoped = { ...ledger, root, now: options.now ?? ledger.now };
     const clock = options.now ?? ledger.now ?? (() => new Date());
     const cliVersion = options.cliVersion ?? readInstalledGrokVersion(options.readVersion);
     const groups = new Map();

package/dist/lib/cli-flag-keys.d.ts

@@ -1,6 +1,8 @@
 /** hq-flags keys used by CLI-wide routes. */
 export declare const CLI_COMMAND_HELP_CATALOG_FLAG = "cli.command-help-catalog";
 export declare const MULTI_COMPANY_SESSION_LOCK_FLAG = "hooks.multi-company-session-lock";
+/** Kill switch (default on) for company-scoped `hq core rebuild-index` root indexes. */
+export declare const CORE_COMPANY_INDEX_SCOPE_FLAG = "cli.rebuild-index-company-scope";
 /**
  * hq-flags key for HQ Storage (`hq storage` and Settings > Storage in the
  * desktop app). Shared with hq-desktop-app, so it carries no `cli.` prefix,

package/dist/lib/cli-flag-keys.js

@@ -1,6 +1,8 @@
 /** hq-flags keys used by CLI-wide routes. */
 export const CLI_COMMAND_HELP_CATALOG_FLAG = "cli.command-help-catalog";
 export const MULTI_COMPANY_SESSION_LOCK_FLAG = "hooks.multi-company-session-lock";
+/** Kill switch (default on) for company-scoped `hq core rebuild-index` root indexes. */
+export const CORE_COMPANY_INDEX_SCOPE_FLAG = "cli.rebuild-index-company-scope";
 /**
  * hq-flags key for HQ Storage (`hq storage` and Settings > Storage in the
  * desktop app). Shared with hq-desktop-app, so it carries no `cli.` prefix,

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

@@ -11,6 +11,7 @@
  */
 import type { MachineType } from "./machine-type.js";
 import type { SyncOwner } from "./config.js";
+import type { SyncCoreCanaryPlan } from "./sync-core-canary.js";
 import type { RemoteControlPoolsConfig } from "./remote-control-pools.js";
 import { type SyncRunnerProcess } from "./sync-runner.js";
 import { type VaultSyncSwitches } from "../vault-sync-switches.js";
@@ -112,6 +113,9 @@ export interface PlanContext {
     vaultSync?: VaultSyncSwitches;
     /** Persisted/effective owner selected for this machine. */
     syncOwner: SyncOwner;
+    syncCoreCanary?: SyncCoreCanaryPlan;
+    legacySyncReadyForCore?: boolean;
+    syncCoreCanaryRunning?: boolean;
     /** A legacy desktop app or sync unit is still managing sync. */
     desktopAppManagesSync: boolean;
     /** Full process list, or null when the daemon could not read it. */

package/dist/lib/daemon/catalog.js

@@ -123,33 +123,13 @@ function planService(service, ctx) {
     const agentMachine = ctx.machineType === "agent-kit" || ctx.machineType === "agent-box";
     switch (service) {
         case "sync": {
-            if (!ctx.syncRunnerPath)
-                return [unavailable(service, "the hq-cloud sync runner is missing from this CLI install")];
-            const unit = base(service, {
-                command: {
-                    type: "node",
-                    script: ctx.syncRunnerPath,
-                    args: [
-                        "--companies",
-                        "--direction",
-                        "both",
-                        "--on-conflict",
-                        "keep",
-                        "--hq-root",
-                        ctx.hqRoot ?? "",
-                        "--watch",
-                        ...(ctx.instantSyncEnabled === false ? [] : ["--event-push"]),
-                        "--owner",
-                        SYNC_RUNNER_OWNER,
-                    ],
-                },
-                env: {
-                    ...ctx.legacySyncEnv,
-                    ...(ctx.vaultSync ? vaultSkipEnv(ctx.vaultSync) : {}),
-                    HQ_SYNC_PASS_REQUEST_DIR: ctx.syncPassRequestsDir,
-                },
-                heartbeatTimeoutMs: ctx.syncHeartbeatTimeoutMs,
-            });
+            const vaultSync = ctx.syncCoreCanaryRunning
+                ? {
+                    allOff: ctx.vaultSync?.allOff === true,
+                    personalOff: true,
+                    offCompanies: ctx.vaultSync?.offCompanies ?? new Set(),
+                }
+                : ctx.vaultSync;
             let ownerBlock;
             if (ctx.machineType === "desktop" && ctx.syncOwner === "desktop-app" && ctx.desktopAppManagesSync) {
                 ownerBlock = "the desktop app is still managing sync (run `hq daemon sync take-ownership` after it stops its runner)";
@@ -163,7 +143,7 @@ function planService(service, ctx) {
                     ? "could not check for an existing sync runner; waiting to avoid starting a duplicate"
                     : syncRunnerUnleasedBlockReason(ctx.hqRoot, ctx.syncRunnerProcesses, ctx.syncRunnerOwnerPid, ctx.platform, ctx.daemonSyncRunnerPids);
             }
-            unit.blocked = firstBlock([
+            const commonBlock = firstBlock([
                 [ctx.syncPaused, "sync is paused (run `hq daemon sync resume`)"],
                 [
                     ctx.vaultSync?.allOff === true,
@@ -173,7 +153,61 @@ function planService(service, ctx) {
                 [!ctx.signedIn, NOT_SIGNED_IN],
                 [!!ownerBlock, ownerBlock ?? ""],
             ]);
-            return [unit];
+            const unit = ctx.syncRunnerPath
+                ? base(service, {
+                    command: {
+                        type: "node",
+                        script: ctx.syncRunnerPath,
+                        args: [
+                            "--companies",
+                            "--direction",
+                            "both",
+                            "--on-conflict",
+                            "keep",
+                            "--hq-root",
+                            ctx.hqRoot ?? "",
+                            "--watch",
+                            ...(ctx.instantSyncEnabled === false ? [] : ["--event-push"]),
+                            "--owner",
+                            SYNC_RUNNER_OWNER,
+                        ],
+                    },
+                    env: {
+                        ...ctx.legacySyncEnv,
+                        ...(vaultSync ? vaultSkipEnv(vaultSync) : {}),
+                        HQ_SYNC_PASS_REQUEST_DIR: ctx.syncPassRequestsDir,
+                    },
+                    heartbeatTimeoutMs: ctx.syncHeartbeatTimeoutMs,
+                    blocked: commonBlock,
+                })
+                : unavailable(service, "the hq-cloud sync runner is missing from this CLI install");
+            if (!ctx.syncCoreCanary)
+                return [unit];
+            const core = base(service, {
+                id: "sync-core-canary",
+                description: ctx.syncCoreCanary.fullVault
+                    ? "keeps the personal vault in sync with sync-core"
+                    : "keeps one personal-vault canary in sync with sync-core",
+                command: ctx.syncCoreCanary.binaryPath
+                    ? { type: "exec", file: ctx.syncCoreCanary.binaryPath, args: ["start", "--loop"] }
+                    : null,
+                env: {
+                    HQ_SYNC_ENGINE: "rust-test",
+                    HQ_SYNC_MODE: "full",
+                    HQ_SYNC_PROTOCOL: "1",
+                    ...(ctx.syncCoreCanary.vaultUid ? { HQ_SYNC_CANARY_VAULT: ctx.syncCoreCanary.vaultUid } : {}),
+                    ...(ctx.syncCoreCanary.canaryPath ? { HQ_SYNC_CANARY_PATH: ctx.syncCoreCanary.canaryPath } : {}),
+                    ...(ctx.syncCoreCanary.fullVault ? { HQ_SYNC_FULL_VAULT: "1" } : {}),
+                },
+                heartbeatTimeoutMs: 180_000,
+                blocked: firstBlock([
+                    [!!commonBlock, commonBlock?.reason ?? ""],
+                    [!!ctx.syncCoreCanary.blockedReason, ctx.syncCoreCanary.blockedReason ?? ""],
+                    [ctx.vaultSync?.personalOff !== true, "turn the personal vault off in the current sync before starting the sync-core canary"],
+                    [ctx.legacySyncReadyForCore !== true, "waiting for legacy sync to run its company-only plan"],
+                ]),
+            });
+            return [unit, core];
         }
         case "mesh": {
             const args = ["mesh", "daemon", "run", ...(ctx.hqRoot ? ["--hq-root", ctx.hqRoot] : [])];

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

@@ -18,12 +18,19 @@ export interface DaemonConfig {
     instantSyncEnabled?: boolean;
     /** Explicit desktop handoff; absent values preserve the legacy per-machine owner. */
     syncOwner?: SyncOwner;
+    syncCoreCanary?: SyncCoreCanaryConfig;
+    syncCoreCanaryError?: string;
+    syncCoreCanaryInvalid?: unknown;
     /** Services turned on here beyond the machine type's defaults. */
     enable: string[];
     /** Default services turned off here. */
     disable: string[];
 }
 export type SyncOwner = "daemon" | "desktop-app";
+export interface SyncCoreCanaryConfig {
+    binaryPath: string;
+    vaultUid: string;
+}
 export declare function effectiveSyncOwner(config: Pick<DaemonConfig, "syncOwner">, machineType: MachineType): SyncOwner;
 export declare function readDaemonConfig(file: string): DaemonConfig;
 export declare function writeDaemonConfig(file: string, config: DaemonConfig): void;

package/dist/lib/daemon/config.js

@@ -19,6 +19,27 @@ function emptyDaemonConfig() {
 function stringList(value) {
     return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
 }
+function syncCoreCanary(value, file) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { error: `hq daemon config at ${file} has invalid syncCoreCanary`, invalid: value };
+    }
+    const candidate = value;
+    if (typeof candidate.binaryPath !== "string" || !path.isAbsolute(candidate.binaryPath)) {
+        return {
+            error: `hq daemon config at ${file} has invalid syncCoreCanary: binaryPath must be absolute`,
+            invalid: value,
+        };
+    }
+    if (typeof candidate.vaultUid !== "string" || !/^prs_[A-Za-z0-9][A-Za-z0-9_-]*$/.test(candidate.vaultUid)) {
+        return {
+            error: `hq daemon config at ${file} has invalid syncCoreCanary: vaultUid must name one personal vault`,
+            invalid: value,
+        };
+    }
+    return { config: { binaryPath: candidate.binaryPath, vaultUid: candidate.vaultUid } };
+}
 export function readDaemonConfig(file) {
     let text;
     try {
@@ -51,6 +72,13 @@ export function readDaemonConfig(file) {
         config.machineType = obj.machineType;
     if (obj.syncOwner === "daemon" || obj.syncOwner === "desktop-app")
         config.syncOwner = obj.syncOwner;
+    const parsedCanary = syncCoreCanary(obj.syncCoreCanary, file);
+    if (parsedCanary.config)
+        config.syncCoreCanary = parsedCanary.config;
+    if (parsedCanary.error)
+        config.syncCoreCanaryError = parsedCanary.error;
+    if (parsedCanary.error)
+        config.syncCoreCanaryInvalid = parsedCanary.invalid;
     if (typeof obj.hqRoot === "string" && obj.hqRoot.trim())
         config.hqRoot = obj.hqRoot;
     if (typeof obj.hqCloudVersion === "string" && validSemver(obj.hqCloudVersion) === obj.hqCloudVersion) {
@@ -73,6 +101,10 @@ export function writeDaemonConfig(file, config) {
         ordered.instantSyncEnabled = config.instantSyncEnabled;
     if (config.syncOwner)
         ordered.syncOwner = config.syncOwner;
+    if (config.syncCoreCanary)
+        ordered.syncCoreCanary = config.syncCoreCanary;
+    else if (config.syncCoreCanaryError)
+        ordered.syncCoreCanary = config.syncCoreCanaryInvalid;
     ordered.enable = config.enable;
     ordered.disable = config.disable;
     fs.writeFileSync(tmp, `${JSON.stringify(ordered, null, 2)}\n`, { mode: 0o600 });