@indigoai-us/hq-cli 5.345.171 → 5.345.172

package/dist/lib/daemon/catalog.js

@@ -9,10 +9,13 @@
  * with no entrypoint yet stay in the catalog as `unavailable` so status shows
  * them instead of silently dropping them.
  */
+import * as path from "node:path";
+import { syncCoreUnitId } from "../sync-core/engine-home.js";
 import { SYNC_RUNNER_OWNER, syncRunnerUnleasedBlockReason } from "./sync-runner.js";
 import { vaultSkipEnv } from "../vault-sync-switches.js";
 export const SERVICE_NAMES = [
     "sync",
+    "sync-core",
     "mesh",
     "heartbeat",
     "inbox",
@@ -31,6 +34,7 @@ export function isServiceName(value) {
 }
 export const SERVICE_DESCRIPTIONS = {
     sync: "keeps company vaults in sync with the cloud",
+    "sync-core": "moves vaults to the new sync engine when their company's switch is on",
     mesh: "Work Mesh Live presence",
     heartbeat: "reports this machine's status to HQ",
     inbox: "picks up the agent's incoming messages and tasks",
@@ -46,9 +50,10 @@ export const SERVICE_DESCRIPTIONS = {
 };
 /** The services each machine type runs without being asked. */
 export const DEFAULT_SERVICES = {
-    desktop: ["sync", "mesh", "heartbeat", "bots", "lanes-reconcile", "search-index", "updater", "housekeeping"],
+    desktop: ["sync", "sync-core", "mesh", "heartbeat", "bots", "lanes-reconcile", "search-index", "updater", "housekeeping"],
     "self-hosted": [
         "sync",
+        "sync-core",
         "mesh",
         "heartbeat",
         "bots",
@@ -79,6 +84,9 @@ export function enabledServices(machineType, overrides) {
     const defaults = DEFAULT_SERVICES[machineType];
     return SERVICE_NAMES.filter((s) => (defaults.includes(s) || overrides.enable.includes(s)) && !overrides.disable.includes(s));
 }
+export const SYNC_CORE_RECONCILE_UNIT = "sync-core";
+export const SYNC_CORE_RECONCILE_INTERVAL_SEC = 600;
+export const SYNC_CORE_LEGACY_SETTLE_MS = 10 * 60 * 1000;
 function base(service, over = {}) {
     return {
         id: service,
@@ -123,11 +131,12 @@ function planService(service, ctx) {
     const agentMachine = ctx.machineType === "agent-kit" || ctx.machineType === "agent-box";
     switch (service) {
         case "sync": {
-            const vaultSync = ctx.syncCoreCanaryRunning
+            const running = ctx.syncCoreRunning;
+            const vaultSync = running && (running.personal || running.companies.size > 0)
                 ? {
                     allOff: ctx.vaultSync?.allOff === true,
-                    personalOff: true,
-                    offCompanies: ctx.vaultSync?.offCompanies ?? new Set(),
+                    personalOff: ctx.vaultSync?.personalOff === true || running.personal,
+                    offCompanies: new Set([...(ctx.vaultSync?.offCompanies ?? []), ...running.companies]),
                 }
                 : ctx.vaultSync;
             let ownerBlock;
@@ -181,33 +190,67 @@ function planService(service, ctx) {
                     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" } : {}),
+            return [unit];
+        }
+        case "sync-core": {
+            if (ctx.platform !== "darwin" && ctx.platform !== "linux") {
+                return [unavailable(service, "the new sync engine runs on macOS and Linux only")];
+            }
+            const reconcile = base(service, {
+                id: SYNC_CORE_RECONCILE_UNIT,
+                kind: "scheduled",
+                intervalSec: SYNC_CORE_RECONCILE_INTERVAL_SEC,
+                initialDelaySec: 30,
+                command: {
+                    type: "hq",
+                    args: ["daemon", "service", "sync-core-reconcile", ...(ctx.hqRoot ? ["--hq-root", ctx.hqRoot] : [])],
                 },
-                heartbeatTimeoutMs: 180_000,
+                env: { HQ_NO_UPDATE_CHECK: "1" },
                 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"],
+                    [!ctx.hqRoot, NO_HQ_ROOT],
+                    [!ctx.signedIn, NOT_SIGNED_IN],
                 ]),
             });
-            return [unit, core];
+            const now = ctx.now ?? Date.now();
+            const engines = (ctx.syncCoreVaults ?? []).map((vault) => {
+                const full = vault.phase === "full";
+                const legacyOff = vault.kind === "personal"
+                    ? ctx.vaultSync?.personalOff === true
+                    : ctx.vaultSync?.offCompanies.has(vault.slug ?? "") === true;
+                const offSince = vault.legacyOffSince ? Date.parse(vault.legacyOffSince) : Number.NaN;
+                const settled = Number.isFinite(offSince) && now - offSince >= SYNC_CORE_LEGACY_SETTLE_MS;
+                const legacyReady = ctx.legacySyncReadyForCore === true && (!ctx.desktopAppManagesSync || settled);
+                const what = vault.kind === "personal" ? "the personal vault" : `the ${vault.slug} vault`;
+                return base(service, {
+                    id: syncCoreUnitId(vault.uid),
+                    description: full
+                        ? `keeps ${what} in sync with the new sync engine (${vault.release})`
+                        : `warms the new sync engine's index for ${what} (${vault.release}, read-only)`,
+                    command: { type: "exec", file: vault.binaryPath, args: ["start", "--loop"] },
+                    env: {
+                        HOME: vault.engineHome,
+                        HQ_STATE_DIR: path.join(ctx.home, ".hq"),
+                        HQ_SYNC_ENGINE: "rust-test",
+                        HQ_SYNC_MODE: full ? "full" : "readonly",
+                        ...(full ? { HQ_SYNC_FULL_VAULT: "1" } : {}),
+                        HQ_SYNC_PROTOCOL: "1",
+                        HQ_SYNC_CORE_RELEASE: vault.release,
+                    },
+                    heartbeatTimeoutMs: 180_000,
+                    blocked: firstBlock([
+                        [ctx.syncPaused, "sync is paused (run `hq daemon sync resume`)"],
+                        [ctx.vaultSync?.allOff === true, "cloud sync is off for every vault on this computer (turn it back on in HQ Settings > Sync)"],
+                        [!ctx.hqRoot, NO_HQ_ROOT],
+                        [!ctx.signedIn, NOT_SIGNED_IN],
+                        [!!vault.blockedReason, vault.blockedReason ?? ""],
+                        [full && !legacyOff, `waiting for the current sync to be turned off for ${what}`],
+                        [full && !legacyReady, ctx.legacySyncReadyForCore !== true
+                                ? "waiting for the current sync to run its plan without this vault"
+                                : "waiting for the desktop app's sync to pick up the off-switch"],
+                    ]),
+                });
+            });
+            return [reconcile, ...engines];
         }
         case "mesh": {
             const args = ["mesh", "daemon", "run", ...(ctx.hqRoot ? ["--hq-root", ctx.hqRoot] : [])];

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

@@ -18,19 +18,12 @@ 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,27 +19,6 @@ 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 {
@@ -72,13 +51,6 @@ 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) {
@@ -101,10 +73,6 @@ 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 });

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

@@ -14,7 +14,7 @@ import { type HostApp, type Supervisor } from "./supervisor.js";
 export declare const LOG_ROTATE_BYTES: number;
 /** Exit code for "restart me": non-zero so every service manager relaunches (Windows tasks only restart on failure). */
 export declare const RESTART_EXIT_CODE = 75;
-export declare function planUnitsWithSyncCoreInterlock(services: readonly ServiceName[], context: PlanContext, supervisor: Pick<Supervisor, "runningPlanKey"> | null | undefined): UnitPlan[];
+export declare function planUnitsWithSyncCoreInterlock(services: readonly ServiceName[], context: PlanContext, supervisor: Pick<Supervisor, "runningPlanKey" | "state"> | null | undefined): UnitPlan[];
 /** A bounded shutdown deadline that can account for sync push persistence. */
 export declare function createShutdownCap(): {
     promise: Promise<"timeout">;
@@ -94,6 +94,10 @@ export declare function daemonSyncUnitIsPresent(units: readonly {
 export declare function resolveSyncRunnerPath(): string | null;
 /** The hosted desktop app uses this env value when planning daemon services. */
 export declare function daemonInstantSyncEnabled(env: NodeJS.ProcessEnv, configured?: boolean): boolean;
+/**
+ * The bots the daemon runs itself. A bot on the HQ Fleet Runtime has its own
+ * background service, so it is not one of them.
+ */
 export declare function listLocalBots(root?: string): string[];
 export declare function windowsTaskExists(taskName: string): boolean;
 export declare function probeLegacyUnits(platform: NodeJS.Platform, home: string): LegacyUnit[];

package/dist/lib/daemon/run.js

@@ -18,11 +18,12 @@ import { anywhereRuntimeAllowed, readHqAnywherePersonSetting, stickyPersonSettin
 import { currentPackageUseLeaseInstall, currentPackageUseUpdateRequested } from "../../utils/package-use-lease.js";
 import { isLocalDependencyInstall, resolveRunningInstall } from "../../utils/version-gate.js";
 import { agentKitPaths } from "../agent-kit/paths.js";
-import { readBotConfig } from "../bot/config.js";
+import { HQ_FLEET_RUNTIME_ENGINE_ID, readBotConfig } from "../bot/config.js";
 import { botsRoot } from "../bot/paths.js";
 import { CLAUDE_RUNNER_SCRIPT, CODEX_RUNNER_SCRIPT, enabledServices, planUnits } from "./catalog.js";
 import { effectiveSyncOwner, readDaemonConfig } from "./config.js";
-import { inspectSyncCoreCanary } from "./sync-core-canary.js";
+import { inspectEngineHome } from "../sync-core/engine-home.js";
+import { readSyncCoreRolloutState } from "../sync-core/rollout-state.js";
 import { assertPersonalServiceSessionCapability, readRemoteControlPoolsConfig, remoteControlPoolSecretsEnv, } from "./remote-control-pools.js";
 import { loadLanesConfig } from "../lanes/config.js";
 import { daemonLanesReconcileHandler } from "../lanes/daemon-reconcile.js";
@@ -64,17 +65,48 @@ export const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
 export const RESTART_EXIT_CODE = 75;
 const NON_SYNC_SHUTDOWN_CAP_MS = STOP_ESCALATION_MS + 5_000;
 const SYNC_RUNNER_SHUTDOWN_CAP_MS = STOP_ESCALATION_MS + SYNC_RUNNER_PERSIST_GRACE_MS + 5_000;
+function syncCoreVaultPlans(home, hqRoot, platform) {
+    const state = readSyncCoreRolloutState(home);
+    if (!state)
+        return [];
+    return state.vaults.map((vault) => inspectEngineHome(home, hqRoot, {
+        uid: vault.uid,
+        kind: vault.kind,
+        ...(vault.slug ? { slug: vault.slug } : {}),
+        phase: vault.phase,
+        engineHome: vault.engineHome,
+        binaryPath: state.binaryPath,
+        release: state.release,
+        ...(vault.legacyOffSince ? { legacyOffSince: vault.legacyOffSince } : {}),
+    }, platform));
+}
+const rememberedSyncCoreVaults = new Map();
 export function planUnitsWithSyncCoreInterlock(services, context, supervisor) {
-    const syncCoreCanaryRunning = supervisor?.runningPlanKey("sync-core-canary") !== undefined;
+    const companies = new Set();
+    let personal = false;
+    for (const vault of context.syncCoreVaults ?? []) {
+        rememberedSyncCoreVaults.set(vault.uid, { kind: vault.kind, slug: vault.slug, full: vault.phase === "full" });
+    }
+    for (const unit of supervisor?.state().units ?? []) {
+        if (!unit.id.startsWith("sync-core:") || supervisor?.runningPlanKey(unit.id) === undefined)
+            continue;
+        const vault = rememberedSyncCoreVaults.get(unit.id.slice("sync-core:".length));
+        if (!vault?.full)
+            continue;
+        if (vault.kind === "personal")
+            personal = true;
+        else if (vault.slug)
+            companies.add(vault.slug);
+    }
     const transitionContext = {
         ...context,
-        syncCoreCanaryRunning,
+        syncCoreRunning: { personal, companies },
         legacySyncReadyForCore: false,
     };
     const waiting = planUnits(services, transitionContext);
     const legacy = waiting.find((unit) => unit.id === "sync");
     const legacySyncReadyForCore = legacy !== undefined
-        && supervisor?.runningPlanKey("sync") === planKey(legacy, CLI_VERSION);
+        && (legacy.blocked !== undefined || supervisor?.runningPlanKey("sync") === planKey(legacy, CLI_VERSION));
     return planUnits(services, { ...transitionContext, legacySyncReadyForCore });
 }
 /** A bounded shutdown deadline that can account for sync push persistence. */
@@ -260,12 +292,21 @@ export function resolveSyncRunnerPath() {
 export function daemonInstantSyncEnabled(env, configured) {
     return configured ?? env.HQ_DAEMON_INSTANT_SYNC !== "0";
 }
+/**
+ * The bots the daemon runs itself. A bot on the HQ Fleet Runtime has its own
+ * background service, so it is not one of them.
+ */
 export function listLocalBots(root = botsRoot()) {
     if (!fs.existsSync(root))
         return [];
     return fs
         .readdirSync(root, { withFileTypes: true })
-        .filter((d) => d.isDirectory() && readBotConfig(path.join(root, d.name)) !== null)
+        .filter((d) => {
+        if (!d.isDirectory())
+            return false;
+        const config = readBotConfig(path.join(root, d.name));
+        return config !== null && config.engine?.id !== HQ_FLEET_RUNTIME_ENGINE_ID;
+    })
         .map((d) => d.name)
         .sort();
 }
@@ -978,11 +1019,7 @@ export async function runDaemon(opts) {
                 return switches;
             })(),
             syncOwner,
-            syncCoreCanary: config.syncCoreCanaryError
-                ? { blockedReason: config.syncCoreCanaryError }
-                : config.syncCoreCanary
-                    ? inspectSyncCoreCanary(home, hqRoot, config.syncCoreCanary, platform)
-                    : undefined,
+            syncCoreVaults: syncCoreVaultPlans(home, hqRoot, platform),
             desktopAppManagesSync: appManagesSync,
             syncRunnerProcesses,
             syncRunnerOwnerPid,

package/dist/lib/daemon/supervisor.js

@@ -87,7 +87,7 @@ function keyHash(key) {
     return createHash("sha256").update(key).digest("hex");
 }
 function recoverableHold(plan, hold) {
-    return plan.kind === "long-running" && (plan.service === "sync" || plan.service === "mesh")
+    return plan.kind === "long-running" && (plan.service === "sync" || plan.service === "sync-core" || plan.service === "mesh")
         && hold?.kind === "exhausted" && hold.cause === "transient";
 }
 function heldReason(unitId, hold) {
@@ -388,6 +388,8 @@ export function createSupervisor(deps) {
         const cause = classifyExit(evidence);
         if (cause.kind !== "permanent")
             return false;
+        if (slot.plan.service === "sync-core" && cause.cause === "bad-config")
+            return false;
         slot.failures += 1;
         holdUnit(slot, "permanent", cause.cause, cause.detail);
         return true;

package/dist/lib/sync-core/engine-home.d.ts

@@ -0,0 +1,44 @@
+export type SyncCoreVaultKind = "personal" | "company";
+export type SyncCoreVaultPhase = "warming" | "full";
+export interface SyncCoreVault {
+    uid: string;
+    kind: SyncCoreVaultKind;
+    slug?: string;
+}
+export interface SyncCoreVaultPlan extends SyncCoreVault {
+    phase: SyncCoreVaultPhase;
+    engineHome: string;
+    binaryPath: string;
+    release: string;
+    legacyOffSince?: string;
+    blockedReason?: string;
+}
+export declare const SYNC_CORE_REQUESTS_PER_DAY = 20000;
+export declare function syncCoreEngineHome(home: string, vaultUid: string): string;
+export declare function syncCoreUnitId(vaultUid: string): string;
+export declare function isSyncCoreVaultUid(value: unknown): value is string;
+export declare function engineConfigToml(vault: SyncCoreVault, hqRoot: string, phase: SyncCoreVaultPhase): string;
+export interface WriteEngineHomeOptions {
+    home: string;
+    hqRoot: string;
+    vault: SyncCoreVault;
+    phase: SyncCoreVaultPhase;
+    tokenFile: string;
+}
+export declare function writeEngineHome(opts: WriteEngineHomeOptions): {
+    engineHome: string;
+    changed: boolean;
+};
+export interface SyncCorePlanFigures {
+    at: string;
+    uploads: number;
+    downloads: number;
+    deletes: number;
+    remoteRows: number;
+    localFiles: number;
+}
+export declare function engineReadOnlyPlan(engineHome: string, vaultUid: string): SyncCorePlanFigures | null;
+export declare function clearEngineStatus(home: string, vaultUid: string): void;
+export declare function removeEngineOwnership(home: string, vaultUid: string): void;
+export declare function inspectEngineHome(home: string, hqRoot: string | undefined, plan: SyncCoreVaultPlan, platform: NodeJS.Platform): SyncCoreVaultPlan;
+//# sourceMappingURL=engine-home.d.ts.map

package/dist/lib/sync-core/engine-home.js

@@ -0,0 +1,193 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parse as parseToml } from "smol-toml";
+export const SYNC_CORE_REQUESTS_PER_DAY = 20_000;
+export function syncCoreEngineHome(home, vaultUid) {
+    return path.join(home, ".hq", "sync-core", "engines", vaultUid);
+}
+export function syncCoreUnitId(vaultUid) {
+    return `sync-core:${vaultUid}`;
+}
+export function isSyncCoreVaultUid(value) {
+    return typeof value === "string" && /^(prs|cmp)_[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value);
+}
+export function engineConfigToml(vault, hqRoot, phase) {
+    const lines = [
+        "[sync]",
+        'engine = "rust-test"',
+        `mode = ${phase === "full" ? '"full"' : '"readonly"'}`,
+        ...(phase === "full" ? ["full_vault = true"] : []),
+        `vaults = [${JSON.stringify(vault.uid)}]`,
+        `hq_root = ${JSON.stringify(hqRoot)}`,
+        `requests_per_day = ${SYNC_CORE_REQUESTS_PER_DAY}`,
+    ];
+    if (vault.kind === "company") {
+        lines.push("[sync.roots]", `${vault.uid} = ${JSON.stringify(`companies/${vault.slug}`)}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function replaceSymlink(link, target) {
+    try {
+        if (fs.lstatSync(link).isSymbolicLink() && fs.readlinkSync(link) === target)
+            return;
+        fs.rmSync(link, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    fs.symlinkSync(target, link);
+}
+function writeIfChanged(file, text) {
+    try {
+        if (fs.readFileSync(file, "utf8") === text)
+            return false;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, text, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    return true;
+}
+export function writeEngineHome(opts) {
+    const engineHome = syncCoreEngineHome(opts.home, opts.vault.uid);
+    const hq = path.join(engineHome, ".hq");
+    const root = path.join(hq, "sync-core");
+    fs.mkdirSync(path.join(root, "owned"), { recursive: true, mode: 0o700 });
+    replaceSymlink(path.join(hq, "menubar.json"), path.join(opts.home, ".hq", "menubar.json"));
+    replaceSymlink(path.join(hq, "work-mesh"), path.join(opts.home, ".hq", "work-mesh"));
+    replaceSymlink(path.join(hq, "cognito-tokens.json"), opts.tokenFile);
+    const configChanged = writeIfChanged(path.join(root, "config.toml"), engineConfigToml(opts.vault, opts.hqRoot, opts.phase));
+    const ownedPath = path.join(root, "owned", `${opts.vault.uid}.json`);
+    let ownedChanged = false;
+    if (opts.phase === "full") {
+        ownedChanged = writeIfChanged(ownedPath, `${JSON.stringify({ vault: opts.vault.uid })}\n`);
+    }
+    else if (fs.existsSync(ownedPath)) {
+        fs.rmSync(ownedPath, { force: true });
+        ownedChanged = true;
+    }
+    return { engineHome, changed: configChanged || ownedChanged };
+}
+function count(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+export function engineReadOnlyPlan(engineHome, vaultUid) {
+    let status;
+    try {
+        status = record(JSON.parse(fs.readFileSync(path.join(engineHome, ".hq", "sync-core", "status.json"), "utf8")));
+    }
+    catch {
+        return null;
+    }
+    if (record(status?.mode)?.value !== "readonly")
+        return null;
+    const lastPlan = record(status?.last_plan);
+    if (!lastPlan || typeof lastPlan.at_ms !== "number" || lastPlan.at_ms <= 0)
+        return null;
+    const vaults = Array.isArray(lastPlan.vaults) ? lastPlan.vaults : [];
+    const run = vaults.map(record).find((v) => v?.vault === vaultUid);
+    if (!run)
+        return null;
+    const errors = Array.isArray(lastPlan.errors) ? lastPlan.errors : [];
+    if (errors.some((e) => {
+        const vault = record(e)?.vault;
+        return vault === vaultUid || typeof vault !== "string";
+    }))
+        return null;
+    const ops = record(record(run.plan)?.ops_by_action) ?? {};
+    return {
+        at: new Date(lastPlan.at_ms).toISOString(),
+        uploads: count(ops.upload),
+        downloads: count(ops.download),
+        deletes: count(ops.delete_local) + count(ops.delete_remote),
+        remoteRows: count(record(run.remote)?.rows),
+        localFiles: count(record(run.local)?.files),
+    };
+}
+export function clearEngineStatus(home, vaultUid) {
+    fs.rmSync(path.join(syncCoreEngineHome(home, vaultUid), ".hq", "sync-core", "status.json"), { force: true });
+}
+export function removeEngineOwnership(home, vaultUid) {
+    fs.rmSync(path.join(syncCoreEngineHome(home, vaultUid), ".hq", "sync-core", "owned", `${vaultUid}.json`), { force: true });
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function blocked(plan, blockedReason) {
+    return { ...plan, blockedReason };
+}
+export function inspectEngineHome(home, hqRoot, plan, platform) {
+    if (platform !== "darwin" && platform !== "linux")
+        return blocked(plan, "the sync engine requires macOS or Linux");
+    try {
+        if (!fs.statSync(plan.binaryPath).isFile())
+            return blocked(plan, "the sync engine binary is missing");
+        fs.accessSync(plan.binaryPath, fs.constants.X_OK);
+    }
+    catch {
+        return blocked(plan, "the sync engine binary is missing or not executable");
+    }
+    if (plan.engineHome !== syncCoreEngineHome(home, plan.uid)) {
+        return blocked(plan, `the engine home for ${plan.uid} is not under this user's sync-core folder`);
+    }
+    const configPath = path.join(plan.engineHome, ".hq", "sync-core", "config.toml");
+    let sync;
+    try {
+        sync = record(record(parseToml(fs.readFileSync(configPath, "utf8")))?.sync);
+    }
+    catch {
+        return blocked(plan, `the engine config at ${configPath} is missing or invalid`);
+    }
+    if (!sync || sync.engine !== "rust-test")
+        return blocked(plan, "the engine config must select engine rust-test");
+    if (plan.phase === "full" && (sync.mode !== "full" || sync.full_vault !== true)) {
+        return blocked(plan, "the engine config must select engine rust-test in full-vault mode");
+    }
+    if (plan.phase === "warming" && sync.mode !== "readonly") {
+        return blocked(plan, "the engine config must select readonly mode while the index warms");
+    }
+    const vaults = sync.vaults;
+    if (!Array.isArray(vaults) || vaults.length !== 1 || vaults[0] !== plan.uid) {
+        return blocked(plan, `the engine config must name exactly ${plan.uid}`);
+    }
+    if (!hqRoot || typeof sync.hq_root !== "string" || path.resolve(sync.hq_root) !== path.resolve(hqRoot)) {
+        return blocked(plan, "the engine config must use the daemon's HQ folder");
+    }
+    if (plan.kind === "company") {
+        const roots = record(sync.roots);
+        if (!plan.slug || roots?.[plan.uid] !== `companies/${plan.slug}`) {
+            return blocked(plan, `the engine config must map ${plan.uid} to companies/${plan.slug ?? "<slug>"}`);
+        }
+        if (!fs.existsSync(path.join(hqRoot, "companies", plan.slug))) {
+            return blocked(plan, `companies/${plan.slug} does not exist under the HQ folder`);
+        }
+    }
+    const ownedPath = path.join(plan.engineHome, ".hq", "sync-core", "owned", `${plan.uid}.json`);
+    if (plan.phase === "full") {
+        try {
+            const owned = record(JSON.parse(fs.readFileSync(ownedPath, "utf8")));
+            if (owned?.vault !== plan.uid)
+                throw new Error("mismatch");
+        }
+        catch {
+            return blocked(plan, `the engine ownership record for ${plan.uid} is missing or invalid`);
+        }
+    }
+    else if (fs.existsSync(ownedPath)) {
+        return blocked(plan, `the engine ownership record for ${plan.uid} must not exist while the index warms`);
+    }
+    for (const link of ["menubar.json", "work-mesh", "cognito-tokens.json"]) {
+        try {
+            fs.readlinkSync(path.join(plan.engineHome, ".hq", link));
+        }
+        catch {
+            return blocked(plan, `the engine home for ${plan.uid} is missing its ${link} link`);
+        }
+    }
+    return plan;
+}
+//# sourceMappingURL=engine-home.js.map

package/dist/lib/sync-core/flag.d.ts

@@ -0,0 +1,17 @@
+import { type FlagClientOptions, type FlagResolution } from "@indigoai-us/hq-flags-client";
+export declare const SYNC_RUST_ENGINE_ROLLOUT_FLAG = "sync.rust-engine-rollout";
+export interface RolloutFlagClient {
+    ready(): Promise<void>;
+    explain(flagKey: string, options?: {
+        fallback?: boolean;
+    }): FlagResolution;
+    close(): void;
+}
+export interface ReadCompanyRolloutFlagOptions {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => RolloutFlagClient;
+}
+export declare class RolloutFlagReadError extends Error {
+}
+export declare function readCompanyRolloutFlag(companyUid: string, token: string, options?: ReadCompanyRolloutFlagOptions): Promise<boolean>;
+//# sourceMappingURL=flag.d.ts.map