@indigoai-us/hq-cli 5.345.201 → 5.345.203

package/dist/lib/bot/jobs/meeting-rider.js

@@ -12,7 +12,7 @@ import { meetingSignalSourceRef, cursorPath } from "../../signals/incremental.js
 import { readAllLanes } from "../../lanes/store.js";
 import { runSignals } from "../../signals/engine.js";
 import { emitBotEvent, EVENT_PAYLOAD_BYTES } from "../events.js";
-import { executiveRiderEnabled } from "../executive-settings.js";
+import { executiveEnabled } from "../executive-settings.js";
 export { isExecutiveBot } from "../executive-settings.js";
 import { readLocalJobsStrict, withJobsLock, writeLocalJobs } from "../local-jobs.js";
 import { readBuiltinJobsMarker, writeBuiltinJobsMarker } from "./hot-signal-sync.js";
@@ -56,7 +56,7 @@ export function ensureMeetingRiderJob(dir) {
     });
 }
 export function meetingRiderSettings(hqRoot, home = os.homedir()) {
-    const enabled = executiveRiderEnabled(home);
+    const enabled = executiveEnabled(home);
     let interval = 20;
     try {
         const settings = yaml.load(fs.readFileSync(path.join(hqRoot, "core/settings/signals.yaml"), "utf8"));

package/dist/lib/bot/jobs/signal-to-lane.d.ts

@@ -7,9 +7,10 @@ export declare function ensureSignalToLaneJobs(dir: string, config: BotConfig, c
 /** Only new locally extracted signals reach here; cloud upload/garden is separate. */
 export declare function emitExecutiveSignalWritten(hqRoot: string, company: string, payload: Record<string, string>, root?: string, home?: string): boolean;
 /** Persist intent before publishing a new signal file; ordinary redo creates none. */
-export declare function prepareSignalPublication(hqRoot: string, company: string, payload: Record<string, string>): void;
+/** Records nothing while no opted-in Executive serves the company, so no backlog builds up. */
+export declare function prepareSignalPublication(hqRoot: string, company: string, payload: Record<string, string>, root?: string, home?: string): void;
 /** A pre-append crash retries; a post-append crash uses the event journal's dedupe. */
-export declare function flushSignalPublications(hqRoot: string, company: string, emit?: typeof emitExecutiveSignalWritten): void;
+export declare function flushSignalPublications(hqRoot: string, company: string, emit?: typeof emitExecutiveSignalWritten, root?: string, home?: string): void;
 type Create = (input: {
     hqRoot: string;
     company: string;

package/dist/lib/bot/jobs/signal-to-lane.js

@@ -41,10 +41,10 @@ export function ensureSignalToLaneJobs(dir, config, companies = signalLaneCompan
         return jobs.filter(job => job.context?.jobKind === SIGNAL_TO_LANE_JOB_KIND);
     });
 }
-/** Only new locally extracted signals reach here; cloud upload/garden is separate. */
-export function emitExecutiveSignalWritten(hqRoot, company, payload, root = botsRoot(), home) {
+/** The opted-in Executive bot dir serving this HQ root and company, if any. */
+function executiveFor(hqRoot, company, root = botsRoot(), home) {
     if (!fs.existsSync(root))
-        return false;
+        return null;
     for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
         if (!entry.isDirectory())
             continue;
@@ -54,10 +54,17 @@ export function emitExecutiveSignalWritten(hqRoot, company, payload, root = bots
             continue;
         if (!signalLaneCompanies(config).includes(company))
             continue;
-        emitBotEvent(dir, "signal.written", { ...payload, company }, new Date(), prior => prior.event === "signal.written" && prior.payload.company === company && prior.payload.signal_id === payload.signal_id);
-        return true;
+        return dir;
     }
-    return false;
+    return null;
+}
+/** Only new locally extracted signals reach here; cloud upload/garden is separate. */
+export function emitExecutiveSignalWritten(hqRoot, company, payload, root = botsRoot(), home) {
+    const dir = executiveFor(hqRoot, company, root, home);
+    if (!dir)
+        return false;
+    emitBotEvent(dir, "signal.written", { ...payload, company }, new Date(), prior => prior.event === "signal.written" && prior.payload.company === company && prior.payload.signal_id === payload.signal_id);
+    return true;
 }
 function publicationDir(hqRoot, company) {
     if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(company))
@@ -65,8 +72,11 @@ function publicationDir(hqRoot, company) {
     return path.join(hqRoot, "workspace", "signal-publications", company);
 }
 /** Persist intent before publishing a new signal file; ordinary redo creates none. */
-export function prepareSignalPublication(hqRoot, company, payload) {
+/** Records nothing while no opted-in Executive serves the company, so no backlog builds up. */
+export function prepareSignalPublication(hqRoot, company, payload, root = botsRoot(), home) {
     const dir = publicationDir(hqRoot, company);
+    if (!executiveFor(hqRoot, company, root, home))
+        return;
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     const file = path.join(dir, createHash("sha256").update(payload.signal_id).digest("hex") + ".json");
     const tmp = `${file}.${randomUUID()}.tmp`;
@@ -74,12 +84,25 @@ export function prepareSignalPublication(hqRoot, company, payload) {
     fs.renameSync(tmp, file);
 }
 /** A pre-append crash retries; a post-append crash uses the event journal's dedupe. */
-export function flushSignalPublications(hqRoot, company, emit = emitExecutiveSignalWritten) {
+export function flushSignalPublications(hqRoot, company, emit = emitExecutiveSignalWritten, root = botsRoot(), home) {
     const dir = publicationDir(hqRoot, company);
     if (!fs.existsSync(dir))
         return;
+    // With the Executive off, drop stale intents so a later opt-in does not
+    // turn past action items into a burst of lanes.
+    const optedIn = executiveFor(hqRoot, company, root, home) !== null;
     for (const name of fs.readdirSync(dir).filter(name => /^[a-f0-9]{64}\.json$/.test(name))) {
         const file = path.join(dir, name);
+        if (!optedIn) {
+            try {
+                fs.unlinkSync(file);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            continue;
+        }
         let payload;
         try {
             payload = JSON.parse(fs.readFileSync(file, "utf8"));

package/dist/lib/bot/run.js

@@ -50,7 +50,7 @@ import { ensureSignalToLaneJobs, runSignalToLane, SIGNAL_TO_LANE_JOB_KIND } from
  * Everything with a side effect is injectable so the loop is unit-testable.
  */
 import { createMeetingRider, defaultMeetingRiderDeps, ensureMeetingRiderJob, MEETING_RIDER_JOB_KIND } from "./jobs/meeting-rider.js";
-import { executiveRiderEnabled, isExecutiveBot } from "./executive-settings.js";
+import { executiveEnabled, isExecutiveBot } from "./executive-settings.js";
 import { createMeetingDetect, defaultMeetingDetectDeps, resolveDetectedMeeting } from "./jobs/meeting-detect.js";
 import { botAuthEnv, describeBotAuth, formatBotAuth } from "./runtime-auth.js";
 import { ownerContextBlock } from "./owner-context.js";
@@ -435,7 +435,7 @@ export async function runBot(deps) {
     eventHandlers[MEETING_RIDER_JOB_KIND] = async ({ item }) => {
         if (!isExecutiveBot(config))
             return { status: "skipped-precondition", output: "Not the Executive" };
-        if (!executiveRiderEnabled())
+        if (!executiveEnabled())
             return { status: "skipped-precondition", output: "rider disabled" };
         meetingRider.start(await resolveDetectedMeeting(config.hqRoot, typeof item.context === "object" ? item.context?.payload : undefined, meetingDetectDeps.list));
         return { status: "succeeded", output: "Meeting rider accepted" };
@@ -2905,7 +2905,7 @@ export async function runBot(deps) {
     }
     if (isExecutiveBot(config)) {
         try {
-            if (ensureMeetingRiderJob(dir) && executiveRiderEnabled())
+            if (ensureMeetingRiderJob(dir) && executiveEnabled())
                 meetingRider.resume();
         }
         catch {

package/dist/lib/capacity/codex-availability.d.ts

@@ -0,0 +1,6 @@
+import type { NowLimit } from "./ledger.js";
+/** A newer snapshot supersedes omitted windows within the same account. */
+export declare function codexSnapshotStale(limit: NowLimit, limits: readonly NowLimit[]): boolean;
+/** Credits can keep Codex serving after a plan window runs out. */
+export declare function hasCodexCreditRoom(limits: readonly NowLimit[], nowMs: number): boolean;
+//# sourceMappingURL=codex-availability.d.ts.map

package/dist/lib/capacity/codex-availability.js

@@ -0,0 +1,33 @@
+const MAX_CREDIT_AGE_MS = 24 * 36e5;
+/** A newer snapshot supersedes omitted windows within the same account. */
+export function codexSnapshotStale(limit, limits) {
+    if (limit.source !== "codex-jsonl" && limit.source !== "codex-app-server" && limit.source !== "refusal")
+        return false;
+    const at = Date.parse(limit.observedAt);
+    return limits.some((other) => other.accountId === limit.accountId
+        && (other.source === "codex-jsonl" || other.source === "codex-app-server")
+        && Date.parse(other.observedAt) > at);
+}
+/** Credits can keep Codex serving after a plan window runs out. */
+export function hasCodexCreditRoom(limits, nowMs) {
+    return limits.some((credit) => {
+        if (credit.kind !== "credits" || !credit.limitId.endsWith(":credits"))
+            return false;
+        const at = Date.parse(credit.observedAt);
+        if (!Number.isFinite(at) || at > nowMs || nowMs - at > MAX_CREDIT_AGE_MS)
+            return false;
+        if (codexSnapshotStale(credit, limits) || credit.state !== "ok")
+            return false;
+        if (credit.resetsAt && Date.parse(credit.resetsAt) <= nowMs)
+            return false;
+        if (credit.hasCredits !== true || credit.spendControlReached === true)
+            return false;
+        const sameAccount = limits.filter((limit) => limit.accountId === credit.accountId);
+        if (sameAccount.some((limit) => !codexSnapshotStale(limit, limits)
+            && limit.spendControlReached === true))
+            return false;
+        const balance = credit.balance === null ? NaN : Number(credit.balance);
+        return credit.unlimited === true || (Number.isFinite(balance) && balance > 0);
+    });
+}
+//# sourceMappingURL=codex-availability.js.map

package/dist/lib/capacity/ledger.d.ts

@@ -1,14 +1,3 @@
-/**
- * Personal capacity ledger under ~/.hq/capacity/.
- *
- * Daily files events-YYYY-MM-DD.jsonl are the append-only event log (one
- * O_APPEND write under 4 KB). rebuildNow() replays those files, plus a
- * legacy events.jsonl if a fixture dropped one, into now.json. The now.json
- * rewrite holds a TTL lock reclaimed after 30 seconds.
- *
- * Root is HQ_CAPACITY_ROOT, or an explicit option, so tests never touch the
- * real home directory. No network, child process, or provider call.
- */
 export declare const CAPACITY_DIRNAME = "capacity";
 export declare const CAPACITY_LOCK_TTL_MS = 30000;
 export declare const CAPACITY_LOCK_NAME = "now.lock";

package/dist/lib/capacity/ledger.js

@@ -1,3 +1,4 @@
+import { codexSnapshotStale, hasCodexCreditRoom } from "./codex-availability.js";
 /**
  * Personal capacity ledger under ~/.hq/capacity/.
  *
@@ -857,11 +858,26 @@ function materialize(events, ctx) {
             return a.reading.limit.limitId.localeCompare(b.reading.limit.limitId);
         })
             .map((limit) => toNowLimit(limit, ctx.nowMs));
+        if (provider === "codex") {
+            for (const limit of limits) {
+                if (codexSnapshotStale(limit, limits)) {
+                    limit.state = "unknown";
+                    limit.usedPercent = null;
+                    limit.burnRatePercentPerHour = null;
+                    limit.lastError = "superseded by a newer Codex snapshot";
+                }
+            }
+        }
         const failed = bucket.failure !== null && bucket.failure.at >= bucket.latestReadingAt;
         let state = "ok";
         for (const limit of limits) {
-            if (STATE_RANK[limit.state] > STATE_RANK[state])
-                state = limit.state;
+            if (provider === "codex" && codexSnapshotStale(limit, limits))
+                continue;
+            const availableState = provider === "codex" && limit.state === "exhausted"
+                && hasCodexCreditRoom(limits.filter((row) => row.accountId === limit.accountId), ctx.nowMs)
+                ? "ok" : limit.state;
+            if (STATE_RANK[availableState] > STATE_RANK[state])
+                state = availableState;
         }
         if (failed)
             state = "unknown";
@@ -878,6 +894,15 @@ function materialize(events, ctx) {
         }
         const unscopedFailure = bucket.failure !== null && bucket.failure.at >= bucket.latestReadingAt;
         attachAccounts(entry, events, unscopedFailure);
+        if (provider === "codex" && !failed && entry.accounts?.length) {
+            for (const account of entry.accounts) {
+                if (account.authState === "ok" && account.state === "exhausted"
+                    && hasCodexCreditRoom(account.limits, ctx.nowMs))
+                    account.state = "ok";
+            }
+            const live = entry.accounts.filter((account) => account.authState !== "expired" && account.authState !== "signed_out" && !account.signedOut);
+            entry.state = live.length === 0 ? "unknown" : live.reduce((state, account) => STATE_RANK[account.state] > STATE_RANK[state] ? account.state : state, "ok");
+        }
         return entry;
     });
     return {
@@ -1039,6 +1064,8 @@ function clusterAccounts(provider, events) {
         if (!blocked) {
             state = "ok";
             for (const limit of limits) {
+                if (provider.provider === "codex" && codexSnapshotStale(limit, limits))
+                    continue;
                 if (STATE_RANK[limit.state] > STATE_RANK[state])
                     state = limit.state;
             }
@@ -1182,7 +1209,7 @@ function deriveLimit(reading, nowMs) {
     // A passed reset beats both a refusal and a 100% reading. The newest
     // observedAt wins in materialize, so a later fetched or observed percent
     // below 100 replaces this refusal before the reset.
-    if (!Number.isNaN(resetsAtMs) && resetsAtMs < nowMs) {
+    if (!Number.isNaN(resetsAtMs) && resetsAtMs <= nowMs) {
         return { state: "reset-pending", usedPercent: null, secondsToReset: null, lastError: null };
     }
     const percent = reading.limit.usedPercent;

package/dist/lib/capacity/route.js

@@ -1,3 +1,4 @@
+import { codexSnapshotStale, hasCodexCreditRoom } from "./codex-availability.js";
 /**
  * Pure router for `hq capacity route` and `hq lanes create --account auto`.
  *
@@ -368,7 +369,7 @@ export function pickAccount(input) {
                 if (resetPassed) {
                     return { limit, used: 0, readAge, resetPassed: true };
                 }
-                if (readAge > LIMIT_STALE_MS) {
+                if (readAge > LIMIT_STALE_MS || (providerId === "codex" && codexSnapshotStale(limit, account.limits ?? []))) {
                     return { limit, used: null, readAge, resetPassed: false };
                 }
                 const used = typeof limit.usedPercent === "number" ? limit.usedPercent : null;
@@ -393,14 +394,18 @@ export function pickAccount(input) {
             }
             const exhausted = viewRows.find((row) => !row.resetPassed
                 && row.readAge <= LIMIT_STALE_MS
+                && !(providerId === "codex" && codexSnapshotStale(row.limit, account.limits ?? []))
                 && (row.limit.state === "exhausted" || (typeof row.used === "number" && row.used >= 100)));
             if (exhausted) {
+                const codexCredits = providerId === "codex" && hasCodexCreditRoom(account.limits ?? [], nowMs);
                 const extraRoom = providerId === "claude" && hasExtraUsageRoom(account);
-                if (extraRoom && input.allowExtraUsage === true) {
+                if (codexCredits || (extraRoom && input.allowExtraUsage === true)) {
                     const live = liveLaneCount(lanes, providerId, laneMatch.id);
                     const weekly = applicable.find((l) => l.kind === "weekly_all");
                     const whyParts = [
-                        `${labelLimit(exhausted.limit)} used up; runs on paid extra usage (--allow-extra-usage)`,
+                        codexCredits
+                            ? `${labelLimit(exhausted.limit)} used up; runs on available Codex credits`
+                            : `${labelLimit(exhausted.limit)} used up; runs on paid extra usage (--allow-extra-usage)`,
                     ];
                     if (live)
                         whyParts.push(`${live} live lane${live === 1 ? "" : "s"} already on it`);
@@ -515,7 +520,8 @@ export function pickAccount(input) {
             });
         }
     }
-    ranked.sort((a, b) => b.score - a.score
+    ranked.sort((a, b) => Number(a.extra_usage === true) - Number(b.extra_usage === true)
+        || b.score - a.score
         || b.headroom - a.headroom
         || a.reading_age_h - b.reading_age_h
         || a.provider.localeCompare(b.provider));
@@ -524,7 +530,7 @@ export function pickAccount(input) {
         if (!requested.includes(p))
             continue;
         const best = ranked.find((r) => r.provider === p);
-        if (best && best.headroom >= floor) {
+        if (best && !best.extra_usage && best.headroom >= floor) {
             pick = best;
             break;
         }

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

@@ -98,6 +98,9 @@ export declare const FLEET_BOTS_UPDATE_INITIAL_DELAY_SEC = 120;
 export declare const SYNC_CORE_RECONCILE_UNIT = "sync-core";
 export declare const SYNC_CORE_RECONCILE_INTERVAL_SEC = 600;
 export declare const SYNC_CORE_MANIFEST_UNIT = "sync-core-manifest";
+export declare const SYNC_CORE_SELFCHECK_UNIT = "sync-core-selfcheck";
+/** The self-check looks hourly; it DMs the owner at most once a day for the same units (selfcheck.ts). */
+export declare const SYNC_CORE_SELFCHECK_INTERVAL_SEC = 3600;
 export declare const SYNC_CORE_MANIFEST_INTERVAL_SEC: number;
 export declare const SYNC_CORE_LEGACY_SETTLE_MS: number;
 export interface PlanContext {

package/dist/lib/daemon/catalog.js

@@ -98,6 +98,9 @@ export const FLEET_BOTS_UPDATE_INITIAL_DELAY_SEC = 120;
 export const SYNC_CORE_RECONCILE_UNIT = "sync-core";
 export const SYNC_CORE_RECONCILE_INTERVAL_SEC = 600;
 export const SYNC_CORE_MANIFEST_UNIT = "sync-core-manifest";
+export const SYNC_CORE_SELFCHECK_UNIT = "sync-core-selfcheck";
+/** The self-check looks hourly; it DMs the owner at most once a day for the same units (selfcheck.ts). */
+export const SYNC_CORE_SELFCHECK_INTERVAL_SEC = 3600;
 export const SYNC_CORE_MANIFEST_INTERVAL_SEC = 24 * 3600;
 export const SYNC_CORE_LEGACY_SETTLE_MS = 10 * 60 * 1000;
 function base(service, over = {}) {
@@ -265,9 +268,19 @@ function planService(service, ctx) {
                     ]),
                 });
             });
+            const selfcheck = engines.length === 0 ? [] : [base(service, {
+                    id: SYNC_CORE_SELFCHECK_UNIT,
+                    description: "tells the signed-in person by DM when a sync engine unit has been held or failing for over 30 minutes",
+                    kind: "scheduled",
+                    intervalSec: SYNC_CORE_SELFCHECK_INTERVAL_SEC,
+                    initialDelaySec: 35 * 60,
+                    command: { type: "hq", args: ["daemon", "service", "sync-core-selfcheck"] },
+                    env: { HQ_NO_UPDATE_CHECK: "1" },
+                    blocked: firstBlock([[!ctx.signedIn, NOT_SIGNED_IN]]),
+                })];
             const manifestScopes = engineOwnedManifestScopes(ctx.vaultSync, ctx.syncCoreVaults);
             if (manifestScopes.length === 0)
-                return [reconcile, ...engines];
+                return [reconcile, ...engines, ...selfcheck];
             const manifest = base(service, {
                 id: SYNC_CORE_MANIFEST_UNIT,
                 description: `uploads a daily sync-audit manifest for ${manifestScopes.map((scope) => scope.kind === "personal" ? "the personal vault" : `the ${scope.slug} vault`).join(", ")}`,
@@ -286,7 +299,7 @@ function planService(service, ctx) {
                     [!ctx.signedIn, NOT_SIGNED_IN],
                 ]),
             });
-            return [reconcile, ...engines, manifest];
+            return [reconcile, ...engines, manifest, ...selfcheck];
         }
         case "mesh": {
             const args = ["mesh", "daemon", "run", ...(ctx.hqRoot ? ["--hq-root", ctx.hqRoot] : [])];

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

@@ -7,6 +7,8 @@
 import { type ServiceName } from "./catalog.js";
 import { type MachineType } from "./machine-type.js";
 import { type DaemonPaths } from "./paths.js";
+/** The updater's postinstall may run in the short gap before the desktop app relaunches its daemon. */
+export declare function recentlyHostedDaemon(paths: DaemonPaths, alive?: (pid: number) => boolean): boolean;
 /** A live daemon runs `unitId` (or held it after it was stopped from outside). */
 export declare function daemonSupervises(paths: DaemonPaths, unitId: string, alive?: (pid: number) => boolean): boolean;
 /** Current supervisor hold, including its explicit recovery command; never infer one from stale state. */

package/dist/lib/daemon/handoff.js

@@ -20,10 +20,14 @@ import { writeControlRequest } from "./requests.js";
 const OWNED = new Set(["running", "backoff", "exited", "idle", "stopped", "held"]);
 const RECENT_HOSTED_DAEMON_MS = 5 * 60_000;
 /** The updater's postinstall may run in the short gap before the desktop app relaunches its daemon. */
-function recentlyHostedDaemon(paths) {
+export function recentlyHostedDaemon(paths, alive = (pid) => isDaemonProcess(pid)) {
     if (!fs.existsSync(paths.statePath))
         return false;
     const state = JSON.parse(fs.readFileSync(paths.statePath, "utf8"));
+    // A different live daemon holds the lock: the hosted daemon that wrote this state is gone, not restarting.
+    const lockPid = runningDaemonPid(paths.lockPath, alive);
+    if (lockPid !== null && state.pid !== lockPid)
+        return false;
     const age = Date.now() - (state.updatedAt ?? 0);
     return state.host === "desktop" && age >= 0 && age <= RECENT_HOSTED_DAEMON_MS;
 }
@@ -85,7 +89,10 @@ export function askDaemonToStop(paths, unitId) {
 /** A live daemon runs as the desktop app's child, which counts as installed even though no OS unit exists. */
 export function hostedDaemonRunning(paths, alive = (pid) => isDaemonProcess(pid)) {
     try {
-        return liveState(paths, alive)?.host === "desktop";
+        // state.json outlives the daemon that wrote it: count it only when it is the lock holder's.
+        const lockPid = runningDaemonPid(paths.lockPath, alive);
+        const state = liveState(paths, alive);
+        return state?.host === "desktop" && state.pid === lockPid;
     }
     catch {
         return false;

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

@@ -163,6 +163,105 @@ export declare function classifyWindowsTask(run: RunCommand, task: string, host:
 /** What to tell the user when HQ did not stop pid `pid` because it could not verify it. */
 export declare function oldDaemonWarning(pid: number, reason: string): string;
 export declare function installDaemonUnit(host: DaemonHost, options: InstallOptions, deps: InstallDeps): DaemonUnitResult;
+/** Install-level bootstrap retries after launchd left the job unloaded. */
+export declare const DAEMON_BOOTSTRAP_RETRIES = 3;
+export declare const DAEMON_BOOTSTRAP_RETRY_MS = 2000;
+/**
+ * Bootstrap the daemon agent again when an install left it unloaded, up to
+ * DAEMON_BOOTSTRAP_RETRIES times, then kickstart it. Returns the error that
+ * says the agent is not loaded when every retry failed.
+ */
+export declare function retryLaunchdBootstrap(plistPath: string, run: RunCommand, uid: number, sleep?: SleepFn): {
+    ok: boolean;
+    error?: string;
+};
+export interface RefreshDaemonPlistResult {
+    /**
+     * - `none`: no daemon plist here (not installed; nothing to upgrade);
+     * - `current`: the plist already loads without HQ.app;
+     * - `rewritten`: the plist was rewritten; it was not loaded, so nothing was reloaded;
+     * - `reloaded`: the plist was rewritten and launchd now runs the new definition.
+     */
+    action: "none" | "current" | "rewritten" | "reloaded";
+    plistPath: string;
+    /** The rewrite or reload did not finish; what is left and how to fix it. */
+    error?: string;
+}
+/**
+ * Upgrade a daemon LaunchAgent written by an older install (run through the
+ * HQ.app launcher and associated with the app's bundle, which launchd skips
+ * at login) to the app-independent form, and reload it when it is loaded.
+ *
+ * Nothing but `hq daemon install` used to rewrite the unit, so a machine that
+ * only ever self-updated kept the old plist. This runs from `hq daemon start`,
+ * and from the detached helper the managed daemon spawns at startup when it
+ * finds the old plist (see daemonPlistNeedsRefresh). It must not run inside
+ * the daemon's own job: the bootout would end the caller before the bootstrap.
+ */
+export declare function refreshDaemonPlist(host: Pick<DaemonHost, "home" | "uid">, deps: {
+    run: RunCommand;
+    sleep?: SleepFn;
+}): RefreshDaemonPlistResult;
+/** The daemon plist on disk still runs through HQ.app or names its bundle. */
+export declare function daemonPlistNeedsRefresh(home: string): boolean;
+/**
+ * Who runs the daemon right now, as the service manager and the pid lock see it:
+ *
+ * - `managed`: the OS unit is loaded (and, where the manager reports one, its
+ *   pid is the daemon holding the lock), so it comes back after a crash or login;
+ * - `unmanaged`: a daemon holds the lock, but the OS unit is not loaded or runs
+ *   a different process (started by hand, or as the desktop app's child);
+ * - `not-loaded`: the OS unit is not loaded and no daemon runs.
+ */
+export type DaemonSupervision = "managed" | "unmanaged" | "not-loaded";
+export interface DaemonServiceStatus {
+    supervision: DaemonSupervision;
+    /** Which service manager was asked. */
+    manager: "launchd" | "systemd-user" | "systemd-system" | "schtasks" | "none";
+    /** The unit file (plist, unit, task) is present. */
+    unitInstalled: boolean;
+    /** The manager has the unit loaded / enabled. */
+    loaded: boolean;
+    /** The manager reports the unit's process as running. */
+    active: boolean;
+    /** The manager's pid for the unit, when it reports one. */
+    managerPid?: number;
+    /** The pid of the live daemon holding the lock, or null. */
+    daemonPid: number | null;
+    /** One line for people: what the manager said. */
+    detail: string;
+    /**
+     * Problems with the unit that do not change who runs the daemon now, such
+     * as a plist launchd skips at login. One line each, with the fix.
+     */
+    warnings?: string[];
+}
+export declare function describeSupervision(status: DaemonServiceStatus): string;
+/**
+ * Ask launchd, systemd or Task Scheduler whether the daemon's unit is loaded,
+ * and combine that with the pid lock. `daemonPid` is the live daemon from the
+ * lock (null when none runs).
+ */
+export declare function daemonServiceStatus(host: Pick<DaemonHost, "platform" | "home" | "uid" | "systemUnitDir" | "windowsSid" | "windowsUser">, run: RunCommand, daemonPid: number | null): DaemonServiceStatus;
+export interface StartDaemonResult {
+    /**
+     * What was done: nothing (already running), loaded the unit, started it, or
+     * reloaded it after rewriting an older install's plist (macOS).
+     */
+    action: "already-running" | "loaded" | "started" | "reloaded";
+    status: DaemonServiceStatus;
+    /** macOS: what happened to an older install's plist before starting. */
+    refresh?: RefreshDaemonPlistResult;
+}
+/**
+ * `hq daemon start`: load the daemon's OS unit when the manager does not have
+ * it, then start it. The unit file must already exist (the caller installs it
+ * first when it does not). Throws when the manager refuses.
+ */
+export declare function startDaemonUnit(host: DaemonHost, deps: InstallDeps & {
+    daemonPid: () => number | null;
+    waitMs?: number;
+}): StartDaemonResult;
 /**
  * PowerShell script that lists Windows sessions as `id|state|DOMAIN\user`
  * lines through WTSEnumerateSessions and WTSQuerySessionInformation. State is