@indigoai-us/hq-cli 5.272.0 → 5.273.0-alpha.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [5.273.0-alpha.0] — 2026-09-28
+
+### Added
+
+- `hq daemon sync` reports runner ownership and health, starts an immediate sync pass, pauses or resumes sync, and sets per-company sync mode. The daemon waits for an existing desktop runner to release its lease before starting its own.
+
 ## [5.272.0] — 2026-09-28
 
 ### Added

package/dist/command-catalog.generated.d.ts

@@ -9098,6 +9098,120 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Print machine-readable JSON";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "sync";
+        readonly description: "Inspect and control the daemon's company sync runner";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [{
+            readonly name: "status";
+            readonly description: "Show sync ownership, heartbeat, last pass and log path";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "now";
+            readonly description: "Start a fresh sync pass immediately";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "pause";
+            readonly description: "Pause daemon sync until resumed";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "resume";
+            readonly description: "Resume daemon sync after a pause";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "take-ownership";
+            readonly description: "Persist daemon ownership of desktop sync and reconcile";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "mode";
+            readonly description: "Read or change a company's sync footprint";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] [command]";
+            readonly arguments: readonly [];
+            readonly options: readonly [];
+            readonly subcommands: readonly [{
+                readonly name: "get";
+                readonly description: "Read a company's current all/shared sync mode";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] <company>";
+                readonly arguments: readonly [{
+                    readonly name: "company";
+                    readonly required: true;
+                    readonly variadic: false;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--json";
+                    readonly description: "Print machine-readable JSON";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "set";
+                readonly description: "Set a company's sync mode to all or shared";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] <company> <mode>";
+                readonly arguments: readonly [{
+                    readonly name: "company";
+                    readonly required: true;
+                    readonly variadic: false;
+                }, {
+                    readonly name: "mode";
+                    readonly required: true;
+                    readonly variadic: false;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--json";
+                    readonly description: "Print machine-readable JSON";
+                }];
+                readonly subcommands: readonly [];
+            }];
+        }];
     }, {
         readonly name: "logs";
         readonly description: "Print the supervisor log, or one service's log";

package/dist/command-catalog.generated.js

@@ -11767,6 +11767,150 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "sync",
+                "description": "Inspect and control the daemon's company sync runner",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "status",
+                        "description": "Show sync ownership, heartbeat, last pass and log path",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "now",
+                        "description": "Start a fresh sync pass immediately",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "pause",
+                        "description": "Pause daemon sync until resumed",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "resume",
+                        "description": "Resume daemon sync after a pause",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "take-ownership",
+                        "description": "Persist daemon ownership of desktop sync and reconcile",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "mode",
+                        "description": "Read or change a company's sync footprint",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] [command]",
+                        "arguments": [],
+                        "options": [],
+                        "subcommands": [
+                            {
+                                "name": "get",
+                                "description": "Read a company's current all/shared sync mode",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] <company>",
+                                "arguments": [
+                                    {
+                                        "name": "company",
+                                        "required": true,
+                                        "variadic": false
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--json",
+                                        "description": "Print machine-readable JSON"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "set",
+                                "description": "Set a company's sync mode to all or shared",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] <company> <mode>",
+                                "arguments": [
+                                    {
+                                        "name": "company",
+                                        "required": true,
+                                        "variadic": false
+                                    },
+                                    {
+                                        "name": "mode",
+                                        "required": true,
+                                        "variadic": false
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--json",
+                                        "description": "Print machine-readable JSON"
+                                    }
+                                ],
+                                "subcommands": []
+                            }
+                        ]
+                    }
+                ]
+            },
             {
                 "name": "logs",
                 "description": "Print the supervisor log, or one service's log",

package/dist/commands/daemon.d.ts

@@ -16,6 +16,7 @@
 import type { Command } from "commander";
 import { type LegacyUnit } from "../lib/daemon/legacy.js";
 import type { HostApp } from "../lib/daemon/supervisor.js";
+import { type SyncModeVaultClient } from "./sync-mode.js";
 import type { RunCommand } from "../lib/service-manager/launchd.js";
 export interface DaemonCommandDeps {
     env: NodeJS.ProcessEnv;
@@ -38,6 +39,8 @@ export interface DaemonCommandDeps {
     userHome: (user: string) => string;
     /** The pid is a live `hq daemon run`. */
     daemonAlive: (pid: number) => boolean;
+    /** Test seam for the company sync-mode commands. */
+    syncModeClient?: () => Promise<SyncModeVaultClient>;
     windowsUser?: string;
     windowsHeadlessLauncher?: string;
     systemUnitDir?: string;

package/dist/commands/daemon.js

@@ -18,7 +18,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { major as semverMajor, valid as validSemver } from "semver";
 import { DEFAULT_SERVICES, SERVICE_DESCRIPTIONS, enabledServices, hqCloudUnits } from "../lib/daemon/catalog.js";
-import { applyServiceToggle, readDaemonConfig, writeDaemonConfig } from "../lib/daemon/config.js";
+import { applyServiceToggle, effectiveSyncOwner, readDaemonConfig, writeDaemonConfig } from "../lib/daemon/config.js";
 import { daemonUnitInstalled } from "../lib/daemon/handoff.js";
 import { adoptLegacyUnits, readAdoptedUnits, restoreLegacyUnits } from "../lib/daemon/migrate.js";
 import { ROOT_REFUSAL, SYSTEM_UNIT_DIR, daemonRootRefusal, installDaemonUnit, installScopeFor, uninstallDaemonUnit, } from "../lib/daemon/install.js";
@@ -27,7 +27,10 @@ import { isDaemonProcess, runningDaemonPid } from "../lib/daemon/lock.js";
 import { bundledHqCloud } from "../lib/daemon/hq-cloud.js";
 import { MACHINE_TYPE_MARKER_PATH, detectMachineType, homeFromPasswd, } from "../lib/daemon/machine-type.js";
 import { daemonPaths } from "../lib/daemon/paths.js";
+import { processCommandLine } from "../lib/daemon/lock.js";
 import { writeControlRequest } from "../lib/daemon/requests.js";
+import { isSyncRunnerCommandLine, readWatchRunnerOwnerStatus, watchRunnerOwnerStatusPath } from "../lib/daemon/sync-runner.js";
+import { getSyncModeForCompany, setSyncMode } from "./sync-mode.js";
 import { resolveDefaultHqRoot } from "../utils/cognito-session.js";
 class DaemonCommandError extends Error {
 }
@@ -96,6 +99,7 @@ async function loadDefaults(over) {
         windowsUser: over.windowsUser ?? (platform === "win32" ? mesh.resolveWindowsUser(env) : ""),
         windowsHeadlessLauncher: over.windowsHeadlessLauncher ?? (platform === "win32" ? mesh.resolveWindowsHeadlessLauncher(env) : undefined),
         systemUnitDir: over.systemUnitDir ?? SYSTEM_UNIT_DIR,
+        syncModeClient: over.syncModeClient,
     };
 }
 function detect(d, flag, config) {
@@ -372,6 +376,135 @@ function queueRequest(d, request, what) {
     const running = runningDaemonPid(paths.lockPath, d.daemonAlive) !== null;
     d.out(running ? `Asked the daemon to ${what}.` : `Queued "${what}"; the daemon is not running, so it applies when it starts.`);
 }
+function daemonSyncModeClient(d) {
+    if (d.syncModeClient)
+        return d.syncModeClient();
+    return (async () => {
+        const [{ VaultClient }, { buildVaultConfig, ensureCognitoToken }] = await Promise.all([
+            import("@indigoai-us/hq-cloud"),
+            import("../utils/cognito-session.js"),
+        ]);
+        const token = await ensureCognitoToken();
+        return new VaultClient(buildVaultConfig(token));
+    })();
+}
+function daemonSyncStatus(d) {
+    const host = currentHost(d);
+    const { paths } = host;
+    const config = readDaemonConfig(paths.configPath);
+    const daemonPid = runningDaemonPid(paths.lockPath, d.daemonAlive);
+    const daemonState = daemonPid === null ? null : readState(paths);
+    const syncUnit = daemonState?.units.find((unit) => unit.id === "sync");
+    const hqRoot = config.hqRoot ?? d.env.HQ_ROOT?.trim();
+    let ownerStatusCandidate = null;
+    if (hqRoot) {
+        try {
+            ownerStatusCandidate = readWatchRunnerOwnerStatus(watchRunnerOwnerStatusPath(hqRoot, d.home, d.env));
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            d.err(`Could not read sync runner owner status; treating it as unavailable: ${detail}`);
+        }
+    }
+    const ownerCommandLine = ownerStatusCandidate
+        ? processCommandLine(ownerStatusCandidate.pid, { platform: d.platform, run: d.run })
+        : null;
+    const ownerStatus = ownerCommandLine && isSyncRunnerCommandLine(ownerCommandLine)
+        ? ownerStatusCandidate
+        : null;
+    return {
+        running: syncUnit?.status === "running",
+        paused: config.syncPaused === true,
+        syncOwner: effectiveSyncOwner(config, host.detected.type),
+        owner: ownerStatus?.owner ?? (syncUnit?.status === "running" ? "hq-daemon" : null),
+        runnerPid: ownerStatus?.pid ?? syncUnit?.pid ?? null,
+        hqCloudVersion: ownerStatus?.version ?? null,
+        lastHeartbeat: syncUnit?.lastHeartbeatAt ?? ownerStatus?.heartbeatAt ?? null,
+        lastPassResult: syncUnit?.lastPassResult ?? null,
+        unitStatus: syncUnit?.status ?? "not-running",
+        reason: syncUnit?.reason ?? null,
+        logPath: paths.unitLogPath("sync"),
+    };
+}
+async function runDaemonSyncStatus(d, opts) {
+    const status = daemonSyncStatus(d);
+    if (opts.json) {
+        d.out(JSON.stringify(status, null, 2));
+        return;
+    }
+    d.out(`Sync ${status.running ? "running" : status.unitStatus}${status.paused ? " (paused)" : ""}.`);
+    d.out(`Configured sync owner: ${status.syncOwner}.`);
+    d.out(`Owner: ${status.owner ?? "none"}; runner pid: ${status.runnerPid ?? "none"}; hq-cloud: ${status.hqCloudVersion ?? "unknown"}.`);
+    if (status.reason)
+        d.out(`Reason: ${status.reason}`);
+    d.out(`Log: ${status.logPath}`);
+}
+function queueDaemonSyncControl(d, request) {
+    const host = currentHost(d);
+    writeControlRequest(host.paths.requestsDir, request);
+    handOver(d, host);
+    return runningDaemonPid(host.paths.lockPath, d.daemonAlive) !== null;
+}
+async function runDaemonSyncNow(d, opts) {
+    const host = currentHost(d);
+    const config = readDaemonConfig(host.paths.configPath);
+    if (config.syncPaused)
+        throw new DaemonCommandError("sync is paused; run `hq daemon sync resume` first");
+    if (!enabledServices(host.detected.type, config).includes("sync")) {
+        throw new DaemonCommandError("sync is disabled for this machine; run `hq daemon enable sync` first");
+    }
+    const running = queueDaemonSyncControl(d, { action: "restart", unit: "sync" });
+    const result = { accepted: true, action: "restart-sync-runner", daemonRunning: running };
+    d.out(opts.json ? JSON.stringify(result, null, 2) : running ? "Asked the daemon to start a fresh sync pass." : "Queued a fresh sync pass for the next daemon start.");
+}
+async function runDaemonSyncPause(d, paused, opts) {
+    const host = currentHost(d);
+    const config = readDaemonConfig(host.paths.configPath);
+    if (config.syncPaused !== paused)
+        writeDaemonConfig(host.paths.configPath, { ...config, syncPaused: paused });
+    const daemonRunning = queueDaemonSyncControl(d, { action: "reconcile" });
+    const result = { paused, persisted: true, daemonRunning };
+    d.out(opts.json ? JSON.stringify(result, null, 2) : `Sync ${paused ? "paused" : "resumed"}${daemonRunning ? "" : "; the setting will apply when the daemon starts"}.`);
+}
+async function runDaemonSyncTakeOwnership(d, opts) {
+    const host = currentHost(d);
+    const config = readDaemonConfig(host.paths.configPath);
+    if (config.syncOwner !== "daemon")
+        writeDaemonConfig(host.paths.configPath, { ...config, syncOwner: "daemon" });
+    const daemonRunning = queueDaemonSyncControl(d, { action: "reconcile" });
+    const result = { syncOwner: "daemon", persisted: true, daemonRunning };
+    d.out(opts.json ? JSON.stringify(result, null, 2) : `Daemon sync ownership persisted${daemonRunning ? "; asked the daemon to reconcile" : "; it applies when the daemon starts"}.`);
+}
+async function runDaemonSyncModeGet(d, companySlug, opts) {
+    const result = await getSyncModeForCompany({ companySlug, vaultClient: await daemonSyncModeClient(d) });
+    const value = {
+        companySlug: result.companySlug,
+        membershipId: result.membershipId,
+        mode: result.config.syncMode,
+        isDefault: result.config.isDefault,
+        ...(result.config.updatedAt ? { updatedAt: result.config.updatedAt } : {}),
+    };
+    d.out(opts.json ? JSON.stringify(value, null, 2) : `${value.companySlug}: ${value.mode}${value.isDefault ? " (default)" : ""}`);
+}
+async function runDaemonSyncModeSet(d, companySlug, mode, opts) {
+    if (mode !== "all" && mode !== "shared") {
+        throw new DaemonCommandError(`Invalid sync mode '${mode}'. Use all or shared.`);
+    }
+    const result = await setSyncMode({
+        mode,
+        companySlug,
+        vaultClient: await daemonSyncModeClient(d),
+    });
+    const value = {
+        companySlug: result.companySlug,
+        membershipId: result.membershipId,
+        previousMode: result.previousMode,
+        mode: result.newMode,
+        isDefault: result.newConfig.isDefault,
+        ...(result.newConfig.updatedAt ? { updatedAt: result.newConfig.updatedAt } : {}),
+    };
+    d.out(opts.json ? JSON.stringify(value, null, 2) : `${value.companySlug}: ${value.previousMode} → ${value.mode}`);
+}
 async function runToggle(d, action, services) {
     const host = currentHost(d);
     const { paths } = host;
@@ -603,6 +736,45 @@ export function registerDaemonCommand(program, over = {}) {
         .description("Show the machine type and each service's state")
         .option("--json", "Print machine-readable JSON")
         .action(wrap((d, opts) => runStatus(d, opts)));
+    const sync = daemon
+        .command("sync")
+        .description("Inspect and control the daemon's company sync runner");
+    sync
+        .command("status")
+        .description("Show sync ownership, heartbeat, last pass and log path")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runDaemonSyncStatus(d, opts)));
+    sync
+        .command("now")
+        .description("Start a fresh sync pass immediately")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runDaemonSyncNow(d, opts)));
+    sync
+        .command("pause")
+        .description("Pause daemon sync until resumed")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runDaemonSyncPause(d, true, opts)));
+    sync
+        .command("resume")
+        .description("Resume daemon sync after a pause")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runDaemonSyncPause(d, false, opts)));
+    sync
+        .command("take-ownership")
+        .description("Persist daemon ownership of desktop sync and reconcile")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, opts) => runDaemonSyncTakeOwnership(d, opts)));
+    const mode = sync.command("mode").description("Read or change a company's sync footprint");
+    mode
+        .command("get <company>")
+        .description("Read a company's current all/shared sync mode")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, company, opts) => runDaemonSyncModeGet(d, company, opts)));
+    mode
+        .command("set <company> <mode>")
+        .description("Set a company's sync mode to all or shared")
+        .option("--json", "Print machine-readable JSON")
+        .action(wrap((d, company, mode, opts) => runDaemonSyncModeSet(d, company, mode, opts)));
     daemon
         .command("logs [unit]")
         .description("Print the supervisor log, or one service's log")

package/dist/commands/sync-mode.d.ts

@@ -70,6 +70,15 @@ export interface SetSyncModeResult {
 export interface ShowSyncModesOptions {
     vaultClient: SyncModeVaultClient;
 }
+export interface GetSyncModeOptions {
+    companySlug: string;
+    vaultClient: SyncModeVaultClient;
+}
+export interface GetSyncModeResult {
+    membershipId: string;
+    companySlug: string;
+    config: MembershipSyncConfig;
+}
 export interface ShowSyncModesRow {
     companySlug: string;
     companyName?: string;
@@ -100,6 +109,8 @@ export declare function setSyncMode(options: SetSyncModeOptions): Promise<SetSyn
  * stable table output.
  */
 export declare function showSyncModes(options: ShowSyncModesOptions): Promise<ShowSyncModesRow[]>;
+/** Read one company's effective sync mode without hiding API read failures. */
+export declare function getSyncModeForCompany(options: GetSyncModeOptions): Promise<GetSyncModeResult>;
 /**
  * Render the `--show` table as plain text. No external dep — hq-cli doesn't
  * use cli-table3, so we hand-format columns to match the existing chalk +

package/dist/commands/sync-mode.js

@@ -163,6 +163,36 @@ export async function showSyncModes(options) {
     rows.sort((a, b) => a.companySlug.localeCompare(b.companySlug));
     return rows;
 }
+/** Read one company's effective sync mode without hiding API read failures. */
+export async function getSyncModeForCompany(options) {
+    const { companySlug, vaultClient } = options;
+    const memberships = await vaultClient.listMyMemberships();
+    const enriched = await Promise.all(memberships.map(async (membership) => {
+        try {
+            const entity = await vaultClient.entity.get(membership.companyUid);
+            return { ok: true, membership, slug: entity.slug };
+        }
+        catch (error) {
+            return { ok: false, membership, error };
+        }
+    }));
+    const match = enriched.find((row) => row.ok && row.slug === companySlug);
+    if (!match) {
+        const failedLookup = enriched.find((row) => !row.ok);
+        if (failedLookup && !failedLookup.ok)
+            throw failedLookup.error;
+        throw new Error(`No membership found for company '${companySlug}'.`);
+    }
+    for (const failedLookup of enriched) {
+        if (!failedLookup.ok) {
+            const detail = failedLookup.error instanceof Error ? failedLookup.error.message : String(failedLookup.error);
+            console.error(`getSyncModeForCompany: entity lookup failed for membership ${failedLookup.membership.membershipKey} while resolving '${companySlug}': ${detail}`);
+        }
+    }
+    const membershipId = match.membership.membershipKey;
+    const config = await vaultClient.getMembershipSyncConfig(membershipId);
+    return { membershipId, companySlug, config };
+}
 // ── Table rendering (used by CLI action, separable for tests) ──────────────
 /**
  * Render the `--show` table as plain text. No external dep — hq-cli doesn't

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

@@ -10,6 +10,8 @@
  * them instead of silently dropping them.
  */
 import type { MachineType } from "./machine-type.js";
+import type { SyncOwner } from "./config.js";
+import { type SyncRunnerProcess } from "./sync-runner.js";
 export declare const SERVICE_NAMES: readonly ["sync", "mesh", "heartbeat", "inbox", "bots", "remote-control", "codex-remote-control", "session-host", "lanes-reconcile", "search-index", "jobs-reconcile", "updater", "housekeeping"];
 export type ServiceName = (typeof SERVICE_NAMES)[number];
 export declare function isServiceName(value: unknown): value is ServiceName;
@@ -51,6 +53,8 @@ export interface UnitPlan {
     restart: "always" | "on-failure";
     intervalSec?: number;
     initialDelaySec?: number;
+    /** Kill and restart this child after silence on its liveness stream. */
+    heartbeatTimeoutMs?: number;
     command: UnitCommand | null;
     env: Record<string, string>;
     blocked?: UnitBlock;
@@ -68,11 +72,23 @@ export interface PlanContext {
     sessionHostRunnerPath: string | null;
     /** Environment retained from legacy outpost sync systemd drop-ins. */
     legacySyncEnv: Record<string, string>;
+    /** Keep the local sync runner stopped until the operator resumes it. */
+    syncPaused: boolean;
+    /** Persisted/effective owner selected for this machine. */
+    syncOwner: SyncOwner;
+    /** 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. */
+    syncRunnerProcesses: readonly SyncRunnerProcess[] | null;
+    /** PID recorded in the watch-owner status, when it is readable. */
+    syncRunnerOwnerPid: number | null;
+    /** Sync runner children already started by this daemon before their lease is written. */
+    daemonSyncRunnerPids?: ReadonlySet<number>;
+    /** The protocol-event heartbeat watchdog timeout for the sync runner. */
+    syncHeartbeatTimeoutMs: number;
     signedIn: boolean;
     /** ~/.hq-agent/kit.json exists. */
     kitConfigured: boolean;
-    /** The HQ desktop app runs its own sync on this machine. */
-    desktopAppManagesSync: boolean;
     bots: readonly string[];
     /** Name of a pre-daemon unit that still runs this unit id, or null. */
     legacyOwner: (unitId: string) => string | null;

package/dist/lib/daemon/catalog.js

@@ -9,6 +9,7 @@
  * with no entrypoint yet stay in the catalog as `unavailable` so status shows
  * them instead of silently dropping them.
  */
+import { SYNC_RUNNER_OWNER, syncRunnerUnleasedBlockReason } from "./sync-runner.js";
 export const SERVICE_NAMES = [
     "sync",
     "mesh",
@@ -127,14 +128,29 @@ function planService(service, ctx) {
                 command: {
                     type: "node",
                     script: ctx.syncRunnerPath,
-                    args: ["--companies", "--direction", "both", "--on-conflict", "keep", "--hq-root", ctx.hqRoot ?? "", "--watch", "--event-push"],
+                    args: ["--companies", "--direction", "both", "--on-conflict", "keep", "--hq-root", ctx.hqRoot ?? "", "--watch", "--event-push", "--owner", SYNC_RUNNER_OWNER],
                 },
                 env: { ...ctx.legacySyncEnv },
+                heartbeatTimeoutMs: ctx.syncHeartbeatTimeoutMs,
             });
+            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)";
+            }
+            else if (ctx.machineType === "desktop" &&
+                ctx.syncOwner === "daemon" &&
+                !ctx.syncPaused &&
+                ctx.hqRoot &&
+                ctx.signedIn) {
+                ownerBlock = ctx.syncRunnerProcesses === null
+                    ? "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([
-                [ctx.desktopAppManagesSync, "the HQ desktop app is handling sync on this machine"],
+                [ctx.syncPaused, "sync is paused (run `hq daemon sync resume`)"],
                 [!ctx.hqRoot, NO_HQ_ROOT],
                 [!ctx.signedIn, NOT_SIGNED_IN],
+                [!!ownerBlock, ownerBlock ?? ""],
             ]);
             return [unit];
         }