@indigoai-us/hq-cli 5.108.0 → 5.108.2

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

@@ -0,0 +1,227 @@
+/**
+ * Contract-3 realtime credential vend + 80%-of-lifetime renewal.
+ * Never logs or persists credential material.
+ */
+import { DEFAULT_VAULT_API_URL } from "../../../../utils/cognito-session.js";
+import { vaultApiFetch } from "../../../../utils/vault-api.js";
+import { readAgentIdentityCompanyUid } from "../../../work-context/company.js";
+export const REALTIME_CREDENTIALS_PATH = "/v1/realtime/credentials";
+export const MQTT_KEEPALIVE_SECONDS = 15;
+/** Renew at 80% of credential lifetime. */
+export const CREDENTIAL_RENEWAL_FRACTION = 0.8;
+export const MIN_RENEWAL_DELAY_MS = 5_000;
+export const realTimerHost = {
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (h) => clearTimeout(h),
+    now: () => Date.now(),
+};
+export function renewalDelayMs(nowMs, expirationIso) {
+    const expMs = Date.parse(expirationIso);
+    if (Number.isNaN(expMs))
+        return 30 * 60_000;
+    const lifetime = expMs - nowMs;
+    return Math.max(MIN_RENEWAL_DELAY_MS, lifetime * CREDENTIAL_RENEWAL_FRACTION);
+}
+function actorUidFromTopic(topic) {
+    if (typeof topic !== "string")
+        return undefined;
+    const m = /^hq\/[^/]+\/presence\/((?:prs|agt)_[A-Za-z0-9]+)$/.exec(topic.trim());
+    return m?.[1];
+}
+function actorUidFromPersonalTopic(topic) {
+    if (typeof topic !== "string")
+        return undefined;
+    const m = /^hq\/((?:prs|agt)_[A-Za-z0-9]+)\//.exec(topic.trim());
+    return m?.[1];
+}
+export function normalizeContract3Bundle(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("contract-3 vend response is not an object");
+    }
+    const r = raw;
+    if (r.contractVersion !== 3) {
+        throw new Error(`expected contractVersion 3, got ${String(r.contractVersion)}`);
+    }
+    const creds = r.credentials;
+    if (!creds ||
+        typeof creds.accessKeyId !== "string" ||
+        typeof creds.secretAccessKey !== "string" ||
+        typeof creds.sessionToken !== "string") {
+        throw new Error("contract-3 vend missing credentials");
+    }
+    if (typeof r.clientId !== "string" || !r.clientId.trim()) {
+        throw new Error("contract-3 vend missing clientId");
+    }
+    if (typeof r.iotEndpoint !== "string" || !r.iotEndpoint.trim()) {
+        throw new Error("contract-3 vend missing iotEndpoint");
+    }
+    if (typeof r.region !== "string" || !r.region.trim()) {
+        throw new Error("contract-3 vend missing region");
+    }
+    const companiesRaw = Array.isArray(r.companies) ? r.companies : [];
+    const companies = [];
+    for (const item of companiesRaw) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const row = item;
+        if (typeof row.companyUid !== "string" || typeof row.presenceTopic !== "string") {
+            continue;
+        }
+        companies.push({
+            companyUid: row.companyUid,
+            presenceTopic: row.presenceTopic,
+        });
+    }
+    if (companies.length === 0) {
+        throw new Error("contract-3 vend returned no companies");
+    }
+    const topics = r.topics && typeof r.topics === "object" && !Array.isArray(r.topics)
+        ? r.topics
+        : null;
+    const actorUid = actorUidFromTopic(companies[0]?.presenceTopic) ||
+        actorUidFromPersonalTopic(topics?.dm) ||
+        actorUidFromPersonalTopic(r.topic) ||
+        "";
+    if (!actorUid) {
+        throw new Error("contract-3 vend could not derive actorUid");
+    }
+    const actorType = actorUid.startsWith("agt_")
+        ? "agent"
+        : "human";
+    const expiresAt = (typeof r.expiresAt === "string" && r.expiresAt) ||
+        (typeof creds.expiration === "string" && creds.expiration) ||
+        "";
+    if (!expiresAt) {
+        throw new Error("contract-3 vend missing expiresAt");
+    }
+    const dropped = Array.isArray(r.droppedCompanies)
+        ? r.droppedCompanies.filter((x) => typeof x === "string")
+        : [];
+    return {
+        contractVersion: 3,
+        credentials: {
+            accessKeyId: creds.accessKeyId,
+            secretAccessKey: creds.secretAccessKey,
+            sessionToken: creds.sessionToken,
+            expiration: expiresAt,
+        },
+        iotEndpoint: r.iotEndpoint,
+        region: r.region,
+        clientId: r.clientId,
+        actorUid,
+        actorType,
+        companies,
+        droppedCompanies: dropped,
+        expiresAt,
+    };
+}
+/**
+ * When `HQ_AGENT_IDENTITY_FILE` names a companyUid, keep only that company
+ * from the vend (must be present) and refuse every other company. Presence
+ * and session events then attribute to the box agent for its company only.
+ * No identity file → return the bundle unchanged (person laptop).
+ */
+export function scopeBundleToAgentIdentity(bundle, env = process.env) {
+    const identityUid = readAgentIdentityCompanyUid(env);
+    if (!identityUid)
+        return bundle;
+    const matched = bundle.companies.filter((c) => c.companyUid === identityUid);
+    if (matched.length === 0) {
+        throw new Error(`identity companyUid is not in the realtime vend; refusing to publish`);
+    }
+    return { ...bundle, companies: matched };
+}
+export function createContract3Fetcher(opts) {
+    return async () => {
+        let bundle;
+        if (opts.post) {
+            const res = await opts.post(REALTIME_CREDENTIALS_PATH, {
+                contractVersion: 3,
+            });
+            if (res.status < 200 || res.status >= 300) {
+                throw new Error(`credential vend failed: HTTP ${res.status}`);
+            }
+            bundle = normalizeContract3Bundle(res.body);
+        }
+        else {
+            const res = await vaultApiFetch({
+                token: opts.token,
+                path: REALTIME_CREDENTIALS_PATH,
+                method: "POST",
+                body: { contractVersion: 3 },
+                baseUrl: opts.baseUrl ?? DEFAULT_VAULT_API_URL,
+            });
+            const text = await res.text();
+            let body = {};
+            if (text) {
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = { raw: text.slice(0, 200) };
+                }
+            }
+            if (!res.ok) {
+                throw new Error(`credential vend failed: HTTP ${res.status}`);
+            }
+            bundle = normalizeContract3Bundle(body);
+        }
+        return scopeBundleToAgentIdentity(bundle, opts.env ?? process.env);
+    };
+}
+/**
+ * Proactive renewal: at 80% of lifetime, fetch fresh creds and call onRenewed.
+ * Does not drop the connection itself — caller reconnects with the new URL.
+ */
+export class CredentialRenewalManager {
+    fetchCredentials;
+    onRenewed;
+    onError;
+    timers;
+    retryDelayMs;
+    handle = null;
+    stopped = false;
+    constructor(fetchCredentials, onRenewed, onError = () => { }, timers = realTimerHost, retryDelayMs = 30_000) {
+        this.fetchCredentials = fetchCredentials;
+        this.onRenewed = onRenewed;
+        this.onError = onError;
+        this.timers = timers;
+        this.retryDelayMs = retryDelayMs;
+    }
+    schedule(bundle) {
+        if (this.stopped)
+            return;
+        this.clear();
+        const delay = renewalDelayMs(this.timers.now(), bundle.expiresAt);
+        this.handle = this.timers.setTimeout(() => void this.renew(), delay);
+    }
+    async renew() {
+        if (this.stopped)
+            return;
+        try {
+            const bundle = await this.fetchCredentials();
+            if (this.stopped)
+                return;
+            this.onRenewed(bundle);
+            this.schedule(bundle);
+        }
+        catch (err) {
+            this.onError(err);
+            if (this.stopped)
+                return;
+            this.clear();
+            this.handle = this.timers.setTimeout(() => void this.renew(), this.retryDelayMs);
+        }
+    }
+    stop() {
+        this.stopped = true;
+        this.clear();
+    }
+    clear() {
+        if (this.handle !== null) {
+            this.timers.clearTimeout(this.handle);
+            this.handle = null;
+        }
+    }
+}
+//# sourceMappingURL=credentials.js.map

package/dist/lib/mesh/live/daemon/doctor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * hq mesh daemon doctor — running/MQTT/companies/spool/held/dead-letter/
+ * outbox/last-flush, and unhealthy when unacked spool age > 60s while online.
+ */
+import { type CognitoActorKind, type CognitoTokenSource } from "../../../../utils/cognito-session.js";
+import { type DaemonStateFile } from "./state.js";
+export declare const UNHEALTHY_SPOOL_AGE_MS = 60000;
+export interface DaemonDoctorReport {
+    running: boolean;
+    pid?: number;
+    mqttState: string;
+    companiesOnline: string[];
+    spoolDepth: number;
+    heldCount: number;
+    deadLetterCount: number;
+    outboxDepth: number;
+    lastFlushAt?: string;
+    lastFlushResult?: DaemonStateFile["lastFlushResult"];
+    unhealthy: boolean;
+    unhealthyReasons: string[];
+    oldestSpoolAgeMs?: number;
+    /** person login cache vs machine-creds mint. */
+    tokenSource: CognitoTokenSource;
+    /** human | agent | unknown — from token claims / machine signal. */
+    actorKind: CognitoActorKind;
+}
+export interface DaemonDoctorDeps {
+    home?: string;
+    meshRoot?: string;
+    workContextRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    isProcessAlive?: (pid: number) => boolean;
+    now?: () => number;
+}
+export declare function collectDaemonDoctor(deps?: DaemonDoctorDeps): DaemonDoctorReport;
+export declare function formatDaemonDoctor(report: DaemonDoctorReport): string[];
+//# sourceMappingURL=doctor.d.ts.map

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

@@ -0,0 +1,139 @@
+/**
+ * hq mesh daemon doctor — running/MQTT/companies/spool/held/dead-letter/
+ * outbox/last-flush, and unhealthy when unacked spool age > 60s while online.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { describeCognitoTokenSource, } from "../../../../utils/cognito-session.js";
+import { outboxStats, } from "../../../work-context/outbox.js";
+import { workContextRoot } from "../../../work-context/paths.js";
+import { countJsonlLines, } from "../spool.js";
+import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../paths.js";
+import { daemonDir, daemonPidPath } from "./paths.js";
+import { pidLockStatus, readPidLock } from "./pid-lock.js";
+import { readDaemonState } from "./state.js";
+export const UNHEALTHY_SPOOL_AGE_MS = 60_000;
+function oldestJsonlAgeMs(filePath, nowMs) {
+    if (!fs.existsSync(filePath))
+        return undefined;
+    try {
+        const text = fs.readFileSync(filePath, "utf8");
+        let oldest;
+        for (const line of text.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const obj = JSON.parse(line);
+                const at = (typeof obj.at === "string" && obj.at) ||
+                    (typeof obj.heldAt === "string" && obj.heldAt) ||
+                    (obj.event && typeof obj.event.at === "string" && obj.event.at) ||
+                    undefined;
+                if (!at)
+                    continue;
+                const t = Date.parse(at);
+                if (!Number.isFinite(t))
+                    continue;
+                const age = nowMs - t;
+                if (oldest === undefined || age > oldest)
+                    oldest = age;
+            }
+            catch {
+                /* skip */
+            }
+        }
+        return oldest;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function collectDaemonDoctor(deps = {}) {
+    const home = deps.home ?? os.homedir();
+    const env = deps.env ?? process.env;
+    const meshRoot = deps.meshRoot ?? workMeshRoot(home, env);
+    const ctxRoot = deps.workContextRoot ?? workContextRoot(home, env);
+    const dir = daemonDir(meshRoot, home, env);
+    const now = deps.now ?? Date.now;
+    const isProcessAlive = deps.isProcessAlive ??
+        ((pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    const lockDeps = { isProcessAlive };
+    const lockPath = daemonPidPath(dir);
+    const lock = pidLockStatus(lockPath, lockDeps);
+    const record = readPidLock(lockPath);
+    const running = lock === "held";
+    const state = readDaemonState(dir);
+    const spoolPath = workMeshSpoolPath(meshRoot);
+    const heldPath = workMeshHeldPath(meshRoot);
+    const deadPath = workMeshDeadLetterPath(meshRoot);
+    const spoolDepth = countJsonlLines(spoolPath);
+    const heldCount = countJsonlLines(heldPath);
+    const deadLetterCount = countJsonlLines(deadPath);
+    const outbox = outboxStats(ctxRoot);
+    const mqttState = state?.mqttState ?? (running ? "unknown" : "closed");
+    const companiesOnline = state?.companiesOnline ?? [];
+    const oldestSpoolAgeMs = oldestJsonlAgeMs(spoolPath, now());
+    const unhealthyReasons = [];
+    const online = mqttState === "connected" && companiesOnline.length > 0;
+    if (online &&
+        spoolDepth > 0 &&
+        oldestSpoolAgeMs !== undefined &&
+        oldestSpoolAgeMs > UNHEALTHY_SPOOL_AGE_MS) {
+        unhealthyReasons.push(`unacknowledged spool age ${Math.round(oldestSpoolAgeMs / 1000)}s exceeds 60s while online`);
+    }
+    if (deadLetterCount > 0) {
+        unhealthyReasons.push(`dead-letter count=${deadLetterCount}`);
+    }
+    const auth = describeCognitoTokenSource({ home, env });
+    return {
+        running,
+        pid: running ? record?.pid : undefined,
+        mqttState,
+        companiesOnline,
+        spoolDepth,
+        heldCount,
+        deadLetterCount,
+        outboxDepth: outbox.depth,
+        lastFlushAt: state?.lastFlushAt,
+        lastFlushResult: state?.lastFlushResult,
+        unhealthy: unhealthyReasons.length > 0,
+        unhealthyReasons,
+        oldestSpoolAgeMs,
+        tokenSource: auth.tokenSource,
+        actorKind: auth.actorKind,
+    };
+}
+export function formatDaemonDoctor(report) {
+    const lines = [
+        `daemon: ${report.running ? `running pid=${report.pid}` : "not running"}`,
+        `mqtt: ${report.mqttState}`,
+        `companies online: ${report.companiesOnline.length ? report.companiesOnline.join(", ") : "(none)"}`,
+        `spool depth: ${report.spoolDepth}`,
+        `held: ${report.heldCount}`,
+        `dead-letter: ${report.deadLetterCount}`,
+        `outbox depth: ${report.outboxDepth}`,
+        `token source: ${report.tokenSource}`,
+        `actor kind: ${report.actorKind}`,
+        `last flush: ${report.lastFlushAt ?? "(never)"}${report.lastFlushResult
+            ? ` ok=${report.lastFlushResult.ok} posted=${report.lastFlushResult.posted}`
+            : ""}`,
+    ];
+    if (report.unhealthy) {
+        lines.push(`health: UNHEALTHY`);
+        for (const reason of report.unhealthyReasons) {
+            lines.push(`  - ${reason}`);
+        }
+    }
+    else {
+        lines.push(`health: ok`);
+    }
+    return lines;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/lib/mesh/live/daemon/index.d.ts

@@ -0,0 +1,24 @@
+export { DAEMON_DIRNAME, DAEMON_LOG_MAX_BYTES, DAEMON_LOG_NAME, DAEMON_PID_NAME, DAEMON_STATE_NAME, LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, daemonDir, daemonLogPath, daemonPidPath, daemonStatePath, sessionBoardPath, } from "./paths.js";
+export { acquirePidLock, defaultPidLockDeps, parsePidLock, pidLockStatus, readPidLock, releasePidLock, resolveDaemonDir, } from "./pid-lock.js";
+export type { PidLockDeps, PidLockRecord, PidLockResult } from "./pid-lock.js";
+export { CREDENTIAL_RENEWAL_FRACTION, MQTT_KEEPALIVE_SECONDS, REALTIME_CREDENTIALS_PATH, CredentialRenewalManager, createContract3Fetcher, normalizeContract3Bundle, realTimerHost, renewalDelayMs, } from "./credentials.js";
+export type { Contract3Bundle, CredentialsFetcher, PresenceCompany, TimerHost, } from "./credentials.js";
+export { amzDateOf, hex, presignIotWssUrl, rfc3986Encode } from "./presign.js";
+export type { IotCredentials } from "./presign.js";
+export { PresenceClient, backoffDelayMs, buildPresencePayload, defaultMqttConnect, isOwnPresenceTopic, } from "./presence.js";
+export type { MeshMqttClientLike, MqttConnectFn, MqttConnectionState, PresenceClientOptions, PresencePayload, } from "./presence.js";
+export { defaultDaemonState, patchDaemonState, readDaemonState, writeDaemonState, } from "./state.js";
+export type { DaemonStateFile } from "./state.js";
+export { appendDaemonLog, daemonLogLine, ensureDaemonLog, resolveDaemonAssetDir, rotateDaemonLogIfNeeded, } from "./log.js";
+export { BOARD_REFRESH_INTERVAL_MS, createVaultBoardReader, formatBoardMarkdown, refreshBoundSessionBoards, writeBoardMarkdown, } from "./board-refresh.js";
+export type { BoardReader, BoardRefreshDeps, BoardStorySnapshot } from "./board-refresh.js";
+export { buildInstallPaths, daemonServiceStatus, detectPlatform, installDaemonService, readAssetTemplate, renderLaunchdPlist, renderSystemdSystemUnit, renderSystemdUserUnit, resolveHqBinary, resolveNodeBinary, uninstallDaemonService, } from "./install.js";
+export type { DaemonInstallPlatform, InstallPaths, InstallResult, } from "./install.js";
+export { UNHEALTHY_SPOOL_AGE_MS, collectDaemonDoctor, formatDaemonDoctor, } from "./doctor.js";
+export type { DaemonDoctorDeps, DaemonDoctorReport } from "./doctor.js";
+export { scopeBundleToAgentIdentity, } from "./credentials.js";
+export { FLUSH_INTERVAL_MS, SPOOL_DEBOUNCE_MS, runMeshDaemon, } from "./run.js";
+export type { DaemonHandle, DaemonRunDeps } from "./run.js";
+export { TRANSCRIPT_ADAPTER_VERSION, TRANSCRIPT_EVENT_SOURCE, TRANSCRIPT_FRESH_MS, TRANSCRIPT_HOOK_COVER_MS, TRANSCRIPT_MARKER, TRANSCRIPT_SESSION_END_MS, TRANSCRIPT_TURN_QUIET_MS, TRANSCRIPT_WATCH_INTERVAL_MS, TranscriptWatcher, decodeClaudeProjectDirName, defaultTranscriptFs, discoverTranscripts, isTranscriptHookCovered, noteHookSessionsFromSpoolFile, resolveTranscriptRegistration, sessionIdFromClaudeTranscriptPath, sessionIdFromCodexTranscriptPath, } from "./transcript-watch.js";
+export type { DiscoveredTranscript, TranscriptFs, TranscriptKind, TranscriptWatchDeps, TranscriptWatchTickResult, } from "./transcript-watch.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,14 @@
+export { DAEMON_DIRNAME, DAEMON_LOG_MAX_BYTES, DAEMON_LOG_NAME, DAEMON_PID_NAME, DAEMON_STATE_NAME, LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, daemonDir, daemonLogPath, daemonPidPath, daemonStatePath, sessionBoardPath, } from "./paths.js";
+export { acquirePidLock, defaultPidLockDeps, parsePidLock, pidLockStatus, readPidLock, releasePidLock, resolveDaemonDir, } from "./pid-lock.js";
+export { CREDENTIAL_RENEWAL_FRACTION, MQTT_KEEPALIVE_SECONDS, REALTIME_CREDENTIALS_PATH, CredentialRenewalManager, createContract3Fetcher, normalizeContract3Bundle, realTimerHost, renewalDelayMs, } from "./credentials.js";
+export { amzDateOf, hex, presignIotWssUrl, rfc3986Encode } from "./presign.js";
+export { PresenceClient, backoffDelayMs, buildPresencePayload, defaultMqttConnect, isOwnPresenceTopic, } from "./presence.js";
+export { defaultDaemonState, patchDaemonState, readDaemonState, writeDaemonState, } from "./state.js";
+export { appendDaemonLog, daemonLogLine, ensureDaemonLog, resolveDaemonAssetDir, rotateDaemonLogIfNeeded, } from "./log.js";
+export { BOARD_REFRESH_INTERVAL_MS, createVaultBoardReader, formatBoardMarkdown, refreshBoundSessionBoards, writeBoardMarkdown, } from "./board-refresh.js";
+export { buildInstallPaths, daemonServiceStatus, detectPlatform, installDaemonService, readAssetTemplate, renderLaunchdPlist, renderSystemdSystemUnit, renderSystemdUserUnit, resolveHqBinary, resolveNodeBinary, uninstallDaemonService, } from "./install.js";
+export { UNHEALTHY_SPOOL_AGE_MS, collectDaemonDoctor, formatDaemonDoctor, } from "./doctor.js";
+export { scopeBundleToAgentIdentity, } from "./credentials.js";
+export { FLUSH_INTERVAL_MS, SPOOL_DEBOUNCE_MS, runMeshDaemon, } from "./run.js";
+export { TRANSCRIPT_ADAPTER_VERSION, TRANSCRIPT_EVENT_SOURCE, TRANSCRIPT_FRESH_MS, TRANSCRIPT_HOOK_COVER_MS, TRANSCRIPT_MARKER, TRANSCRIPT_SESSION_END_MS, TRANSCRIPT_TURN_QUIET_MS, TRANSCRIPT_WATCH_INTERVAL_MS, TranscriptWatcher, decodeClaudeProjectDirName, defaultTranscriptFs, discoverTranscripts, isTranscriptHookCovered, noteHookSessionsFromSpoolFile, resolveTranscriptRegistration, sessionIdFromClaudeTranscriptPath, sessionIdFromCodexTranscriptPath, } from "./transcript-watch.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,83 @@
+/**
+ * User-level service install for hq mesh daemon.
+ *
+ * - macOS: LaunchAgent ai.getindigo.hq-mesh-daemon
+ * - Linux: systemd user unit hq-mesh-daemon.service
+ *   (documented fallback: root-owned unit running as ec2-user)
+ *
+ * The unit embeds the hq binary resolved at install time. Logs go to
+ * ~/.hq/work-mesh/daemon/log (rotation at 5MB handled by the daemon).
+ * Tests must not actually install services — use a temp HOME/prefix.
+ */
+import * as fs from "node:fs";
+export type DaemonInstallPlatform = "darwin" | "linux" | "other";
+export interface InstallPaths {
+    home: string;
+    hqBinary: string;
+    nodeBinary: string;
+    daemonDir: string;
+    logPath: string;
+    launchAgentsDir: string;
+    plistPath: string;
+    systemdUserDir: string;
+    systemdUnitPath: string;
+    /** When true, render the root/ec2-user system unit instead of user unit. */
+    systemUser?: string;
+}
+export interface InstallResult {
+    platform: DaemonInstallPlatform;
+    action: "install" | "uninstall" | "status";
+    paths: InstallPaths;
+    rendered?: string;
+    dest?: string;
+    running?: boolean;
+    message: string;
+}
+export declare function detectPlatform(platform?: NodeJS.Platform): DaemonInstallPlatform;
+/** Resolve the hq binary the current shell uses (argv[1] or PATH). */
+export declare function resolveHqBinary(argv?: string[], env?: NodeJS.ProcessEnv): string;
+export declare function resolveNodeBinary(execPath?: string, env?: NodeJS.ProcessEnv): string;
+export declare function buildInstallPaths(opts: {
+    home?: string;
+    hqBinary?: string;
+    nodeBinary?: string;
+    meshRoot?: string;
+    systemUser?: string;
+    env?: NodeJS.ProcessEnv;
+    argv?: string[];
+    execPath?: string;
+}): InstallPaths;
+export declare function renderLaunchdPlist(paths: InstallPaths): string;
+export declare function renderSystemdUserUnit(paths: InstallPaths): string;
+/**
+ * Root-owned unit running as ec2-user (agent boxes without a user session bus).
+ * Documented fallback — written only when --system-user is passed.
+ */
+export declare function renderSystemdSystemUnit(paths: InstallPaths): string;
+export declare function installDaemonService(opts: {
+    platform?: DaemonInstallPlatform;
+    paths?: InstallPaths;
+    /** When set, write the system unit template (does not sudo-install). */
+    systemUser?: string;
+    writeFileSync?: typeof fs.writeFileSync;
+    mkdirSync?: typeof fs.mkdirSync;
+    /** Optional: actually load the service (disabled in tests). */
+    activate?: (platform: DaemonInstallPlatform, dest: string) => void;
+}): InstallResult;
+export declare function uninstallDaemonService(opts: {
+    platform?: DaemonInstallPlatform;
+    paths?: InstallPaths;
+    unlinkSync?: typeof fs.unlinkSync;
+    existsSync?: typeof fs.existsSync;
+    deactivate?: (platform: DaemonInstallPlatform, dest: string) => void;
+}): InstallResult;
+export declare function daemonServiceStatus(opts: {
+    platform?: DaemonInstallPlatform;
+    paths?: InstallPaths;
+    existsSync?: typeof fs.existsSync;
+    /** Optional live probe (launchctl/systemctl); tests inject. */
+    isLoaded?: (platform: DaemonInstallPlatform, dest: string) => boolean;
+}): InstallResult;
+/** Read baked template files from assets/ (optional; renderers are primary). */
+export declare function readAssetTemplate(name: "launchd.plist.template" | "systemd.user.service.template" | "systemd.system.service.template"): string | null;
+//# sourceMappingURL=install.d.ts.map