@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/bot/daemon.js

@@ -0,0 +1,552 @@
+/**
+ * Per-bot launchd user agent (local-bots US-005). macOS only for this PRD;
+ * Linux writes a systemd user unit as a best-effort extra.
+ *
+ *   ~/Library/LaunchAgents/ai.getindigo.hq-bot.<name>.plist
+ *     ProgramArguments: <node> <hq> bot run <name>
+ *     RunAtLoad + KeepAlive{SuccessfulExit:false}  — starts at login, restarts
+ *     on crash, but a clean exit 0 (bot disabled via `hq bot stop`) stays down.
+ *
+ * `launchctl` is injected so tests never touch the real service manager.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { resolveHqBinary, resolveNodeBinary, preferStableHqBinary } from "../mesh/live/daemon/install.js";
+import { botLogPath, launchdLabel } from "./paths.js";
+import { reloadLaunchd } from "../service-manager/launchd.js";
+import { nodeBinaryProblem, preferStableNodeBinary } from "../node-binary.js";
+export function detectBotPlatform(platform = process.platform) {
+    if (platform === "darwin")
+        return "darwin";
+    if (platform === "linux")
+        return "linux";
+    return "other";
+}
+export function defaultPathEntries(home) {
+    const toolchain = path.join(home, "Library", "Application Support", "Indigo HQ", "toolchain");
+    return [
+        // launchd does not load shell profiles; npm CLIs also need env node.
+        path.join(toolchain, "node", "bin"),
+        path.join(toolchain, "npm-global", "bin"),
+        path.join(home, ".local", "bin"),
+        path.join(home, ".grok", "bin"),
+        path.join(home, "Library", "pnpm"),
+        path.join(home, ".npm-global", "bin"),
+        "/opt/homebrew/bin",
+        "/usr/local/bin",
+        "/usr/bin",
+        "/bin",
+    ];
+}
+export function buildBotDaemonPaths(opts) {
+    const home = opts.home ?? os.homedir();
+    const env = opts.env ?? process.env;
+    const label = launchdLabel(opts.name);
+    return {
+        home,
+        name: opts.name,
+        label,
+        hqBinary: opts.hqBinary ?? resolveHqBinary(opts.argv, env),
+        nodeBinary: opts.nodeBinary ?? resolveNodeBinary(opts.execPath, env),
+        botDir: opts.botDir,
+        logPath: botLogPath(opts.botDir),
+        plistPath: path.join(home, "Library", "LaunchAgents", `${label}.plist`),
+        systemdUnitPath: path.join(home, ".config", "systemd", "user", `hq-bot-${opts.name}.service`),
+        pathEntries: defaultPathEntries(home),
+        hqRoot: opts.hqRoot,
+    };
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+export function renderBotLaunchdPlist(p) {
+    const envRows = [
+        ["HOME", p.home],
+        ["PATH", p.pathEntries.join(":")],
+        ["HQ_NO_UPDATE_CHECK", "1"],
+        ...(p.hqRoot ? [["HQ_ROOT", p.hqRoot]] : []),
+    ]
+        .map(([k, v]) => `    <key>${escapeXml(k)}</key>\n    <string>${escapeXml(v)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(p.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXml(p.nodeBinary)}</string>
+    <string>${escapeXml(p.hqBinary)}</string>
+    <string>bot</string>
+    <string>run</string>
+    <string>${escapeXml(p.name)}</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(p.hqRoot ?? p.botDir)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
+  <key>ProcessType</key>
+  <!-- Interactive, not Background: launchd throttles Background processes
+       (CPU/IO/network), which doubled every model turn (63 s vs 28 s for the
+       same Grok call, 2026-09-11). The bot answers a person in real time. -->
+  <string>Interactive</string>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(p.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(p.logPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envRows}
+  </dict>
+</dict>
+</plist>
+`;
+}
+export function renderBotSystemdUnit(p) {
+    const q = (v) => (/^[A-Za-z0-9_./:-]+$/.test(v) ? v : `'${v.replace(/'/g, `'\\''`)}'`);
+    return `[Unit]
+Description=HQ local bot ${p.name}
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${q(p.nodeBinary)} ${q(p.hqBinary)} bot run ${p.name}
+WorkingDirectory=${p.hqRoot ?? p.botDir}
+Restart=on-failure
+RestartSec=5
+Environment=HOME=${p.home}
+Environment=PATH=${p.pathEntries.join(":")}
+Environment=HQ_NO_UPDATE_CHECK=1
+${p.hqRoot ? `Environment=HQ_ROOT=${p.hqRoot}\n` : ""}StandardOutput=append:${p.logPath}
+StandardError=append:${p.logPath}
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function launchdDomain(uid = os.userInfo().uid) {
+    return `gui/${uid}`;
+}
+function blockingSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function shQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Detached `launchctl bootout` that outlives the process asking for it. */
+function defaultSpawnDetached(command, args, options) {
+    const child = spawn(command, args, options);
+    child.unref();
+}
+/**
+ * Take the job out of the launchd session.
+ *
+ * When `deps.bootout` is "detached" the call is handed to a new session
+ * (`sh -c 'sleep 1; exec launchctl bootout …'`) so the caller can be the job
+ * being removed: the caller exits 0 first — which KeepAlive{SuccessfulExit:
+ * false} leaves alone — and the grandchild, in a session launchd is not
+ * tearing down, finishes the job a second later.
+ */
+function bootoutLaunchd(p, deps) {
+    const target = `${launchdDomain(deps.uid)}/${p.label}`;
+    if (deps.bootout === "detached") {
+        (deps.spawnDetached ?? defaultSpawnDetached)("/bin/sh", ["-c", `sleep 1; exec launchctl bootout ${shQuote(target)}`], { detached: true, windowsHide: true, stdio: "ignore" });
+        return;
+    }
+    deps.launchctl?.(["bootout", target]);
+}
+/**
+ * `launchctl bootout` returns before the job is actually gone; a `bootstrap`
+ * issued right away fails with EIO and the old job then finishes unloading,
+ * leaving nothing running. Shared with the mesh daemon and kit services:
+ * wait for the unload, then bootstrap with backoff.
+ */
+function rebootstrapLaunchd(p, deps) {
+    const launchctl = deps.launchctl;
+    const run = (_cmd, args) => {
+        const r = launchctl(args);
+        return { status: r.ok ? 0 : 1, stdout: r.stdout, stderr: r.stderr };
+    };
+    return reloadLaunchd(p.plistPath, run, deps.uid ?? os.userInfo().uid, { sleep: deps.sleepMs ?? blockingSleep });
+}
+function launchdLoaded(p, deps) {
+    if (!deps.launchctl)
+        return false;
+    return deps.launchctl(["print", `${launchdDomain(deps.uid)}/${p.label}`]).ok;
+}
+export function launchdPlistProgramArguments(plist) {
+    const block = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (!block)
+        return [];
+    return [...block[1].matchAll(/<string>([^<]*)<\/string>/g)].map((m) => m[1]);
+}
+/** The hq script path baked into an installed unit, or null if none. */
+export function installedDaemonHqBinary(p, io = fs) {
+    if (io.existsSync(p.plistPath)) {
+        const args = launchdPlistProgramArguments(io.readFileSync(p.plistPath, "utf8"));
+        return args[1] ?? null;
+    }
+    if (io.existsSync(p.systemdUnitPath)) {
+        const unit = io.readFileSync(p.systemdUnitPath, "utf8");
+        const m = unit.match(/^ExecStart=\S+\s+(\S+)/m);
+        return m?.[1] ?? null;
+    }
+    return null;
+}
+/** The node binary baked into an installed unit, or null if none. */
+export function installedDaemonNodeBinary(p, io = fs) {
+    if (io.existsSync(p.plistPath)) {
+        const args = launchdPlistProgramArguments(io.readFileSync(p.plistPath, "utf8"));
+        return args[0] ?? null;
+    }
+    if (io.existsSync(p.systemdUnitPath)) {
+        const unit = io.readFileSync(p.systemdUnitPath, "utf8");
+        const m = unit.match(/^ExecStart=(\S+)/m);
+        return m?.[1] ?? null;
+    }
+    return null;
+}
+/**
+ * What is wrong with the node path baked into the bot's installed unit:
+ * "missing" (launchd can no longer start the bot — a `brew upgrade node`
+ * removed the versioned Cellar directory), "versioned" (it still exists, but
+ * the next upgrade removes it; a stable alias for the same binary exists), or
+ * null when the unit is fine or not installed.
+ */
+export function botDaemonNodeProblem(p, deps = {}) {
+    const io = deps.fsImpl ?? fs;
+    let node;
+    try {
+        node = installedDaemonNodeBinary(p, {
+            existsSync: (q) => io.existsSync(q),
+            readFileSync: (q) => (deps.readFile ?? ((f) => fs.readFileSync(f, "utf8")))(q),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!node)
+        return null;
+    const nodeOpts = deps.nodeIo ? { io: deps.nodeIo } : {};
+    const problem = nodeBinaryProblem(node, nodeOpts);
+    if (!problem)
+        return null;
+    // Prefer the stable alias of the node the unit already ran (same install),
+    // so a repair run from another node (an nvm shell) does not switch runtimes.
+    const stable = preferStableNodeBinary(node, nodeOpts);
+    return { nodeBinary: node, problem, replacement: stable !== node ? stable : null };
+}
+/**
+ * Rewrite the unit when its hq path is missing or is the pre-move
+ * toolchain/node/bin/hq while toolchain/npm-global/bin/hq exists, or when its
+ * node path is missing or a versioned directory an upgrade will remove.
+ *
+ * A node-only repair keeps the hq script the unit already runs, so repairing
+ * from a worktree or a one-off build never repoints the bot at that build.
+ */
+export function repairBotDaemonIfStale(p, deps = {}) {
+    const io = deps.fsImpl ?? fs;
+    const readFile = deps.readFile ?? ((f) => fs.readFileSync(f, "utf8"));
+    let current;
+    try {
+        current = installedDaemonHqBinary(p, {
+            existsSync: (q) => io.existsSync(q),
+            readFileSync: (q) => readFile(q),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!current)
+        return null;
+    const hqStale = !io.existsSync(current) || preferStableHqBinary(current) !== current;
+    const found = botDaemonNodeProblem(p, { fsImpl: io, readFile, ...(deps.nodeIo ? { nodeIo: deps.nodeIo } : {}) });
+    // Rewriting only helps when it changes the node path.
+    const nodeTarget = found ? (found.replacement ?? p.nodeBinary) : p.nodeBinary;
+    const node = found && found.nodeBinary !== nodeTarget ? found : null;
+    // A plist already rewritten on disk (`hq doctor --fix`) whose loaded job still
+    // runs the versioned or missing node needs a reload all the same.
+    const loaded = loadedLaunchdProgram(p, deps);
+    const loadedStale = !!loaded && loaded !== nodeTarget && nodeBinaryProblem(loaded, deps.nodeIo ? { io: deps.nodeIo } : {}) !== null;
+    if (!hqStale && !node && !loadedStale)
+        return null;
+    return installBotDaemon({ ...p, nodeBinary: nodeTarget, ...(hqStale ? {} : { hqBinary: current }) }, deps);
+}
+/**
+ * The in-job half of the node-path self-heal, run by `hq bot run` when it is
+ * itself the launchd job. A `bootout` from inside the job kills the caller,
+ * so this only rewrites the plist and hands the reload to a detached shell in
+ * its own session; the caller then exits 0, which KeepAlive{SuccessfulExit:
+ * false} leaves alone, and the shell boots the old definition out and
+ * bootstraps the rewritten one (RunAtLoad starts the bot again). Runs before
+ * the bot takes any message, so no turn is cut short.
+ *
+ * Returns null (and changes nothing) unless the unit's node path is a
+ * versioned directory with a stable alias for the same binary.
+ */
+export function healBotDaemonNodeFromJob(p, deps = {}) {
+    const platform = deps.platform ?? detectBotPlatform();
+    if (platform !== "darwin")
+        return null;
+    const io = deps.fsImpl ?? fs;
+    const readFile = deps.readFile ?? ((f) => fs.readFileSync(f, "utf8"));
+    const nodeOpts = deps.nodeIo ? { io: deps.nodeIo } : {};
+    const file = botDaemonNodeProblem(p, { fsImpl: io, readFile, ...(deps.nodeIo ? { nodeIo: deps.nodeIo } : {}) });
+    const fileTarget = file?.replacement ?? null;
+    const fileNeedsRewrite = !!file && file.problem === "versioned" && !!fileTarget;
+    // The plist may already be stable (rewritten by `hq doctor --fix`) while the
+    // loaded definition — what launchd execs on the next respawn — is not.
+    const loaded = loadedLaunchdProgram(p, deps);
+    const loadedTarget = loaded ? preferStableNodeBinary(loaded, nodeOpts) : null;
+    const loadedStale = !!loaded && !!loadedTarget && loadedTarget !== loaded && nodeBinaryProblem(loaded, nodeOpts) === "versioned";
+    if (!fileNeedsRewrite && !loadedStale)
+        return null;
+    if (fileNeedsRewrite) {
+        let hq;
+        try {
+            hq = installedDaemonHqBinary(p, { existsSync: (q) => io.existsSync(q), readFileSync: (q) => readFile(q) });
+        }
+        catch {
+            return null;
+        }
+        // Rewrite only the file here (no launchctl: a bootout would kill us).
+        installBotDaemon({ ...p, nodeBinary: fileTarget, hqBinary: hq ?? p.hqBinary }, { ...deps, platform, launchctl: undefined });
+    }
+    const domain = launchdDomain(deps.uid);
+    const target = `${domain}/${p.label}`;
+    const script = [
+        "sleep 1",
+        `launchctl bootout ${shQuote(target)} >/dev/null 2>&1`,
+        `i=0; while launchctl print ${shQuote(target)} >/dev/null 2>&1 && [ $i -lt 40 ]; do sleep 0.25; i=$((i+1)); done`,
+        `for d in 0 1 2 4; do sleep $d; launchctl bootstrap ${shQuote(domain)} ${shQuote(p.plistPath)} >/dev/null 2>&1 && exit 0; done`,
+        "exit 1",
+    ].join("; ");
+    (deps.spawnDetached ?? defaultSpawnDetached)("/bin/sh", ["-c", script], { detached: true, windowsHide: true, stdio: "ignore" });
+    return fileNeedsRewrite ? { from: file.nodeBinary, to: fileTarget } : { from: loaded, to: loadedTarget };
+}
+/** `program = …` of the loaded job (`launchctl print`), or null when not loaded or unknown. */
+export function loadedLaunchdProgram(p, deps) {
+    if (!deps.launchctl)
+        return null;
+    const r = deps.launchctl(["print", `${launchdDomain(deps.uid)}/${p.label}`]);
+    if (!r.ok)
+        return null;
+    const m = /^\s*program = (.+?)\s*$/m.exec(r.stdout);
+    return m?.[1] ?? null;
+}
+/**
+ * Rewrite the plist's node path to the stable alias WITHOUT touching launchd:
+ * no bootout, no bootstrap, so a running bot's turn is never cut short and a
+ * stopped bot is not started. The new path applies at the next login, the next
+ * `hq bot start`, or the bot's next start (which reloads its own job). This is
+ * what `hq doctor --fix` runs, including unattended at session start.
+ */
+export function rewriteBotDaemonNodePath(p, deps = {}) {
+    const platform = deps.platform ?? detectBotPlatform();
+    if (platform !== "darwin")
+        return null;
+    const io = deps.fsImpl ?? fs;
+    const readFile = deps.readFile ?? ((f) => fs.readFileSync(f, "utf8"));
+    const file = botDaemonNodeProblem(p, { fsImpl: io, readFile, ...(deps.nodeIo ? { nodeIo: deps.nodeIo } : {}) });
+    const to = file ? (file.replacement ?? p.nodeBinary) : null;
+    if (!file || !to || file.nodeBinary === to)
+        return null;
+    let hq;
+    try {
+        hq = installedDaemonHqBinary(p, { existsSync: (q) => io.existsSync(q), readFileSync: (q) => readFile(q) });
+    }
+    catch {
+        return null;
+    }
+    installBotDaemon({ ...p, nodeBinary: to, hqBinary: hq ?? p.hqBinary }, { fsImpl: deps.fsImpl, platform });
+    return { from: file.nodeBinary, to };
+}
+export function installBotDaemon(p, deps = {}) {
+    const platform = deps.platform ?? detectBotPlatform();
+    const io = deps.fsImpl ?? fs;
+    io.mkdirSync(p.botDir, { recursive: true, mode: 0o700 });
+    io.mkdirSync(path.dirname(p.logPath), { recursive: true, mode: 0o700 });
+    if (platform === "darwin") {
+        io.mkdirSync(path.dirname(p.plistPath), { recursive: true });
+        // Replace rather than overwrite, so re-adopting a bot over the stale plist
+        // a wiped ~/.hq left behind lands a fresh file at 0600 (writeFileSync
+        // keeps the mode an existing file already has).
+        if (io.existsSync(p.plistPath))
+            io.unlinkSync(p.plistPath);
+        io.writeFileSync(p.plistPath, renderBotLaunchdPlist(p), { mode: 0o600 });
+        let loaded = false;
+        if (deps.launchctl) {
+            // bootout first so a re-install picks up a changed plist.
+            const r = rebootstrapLaunchd(p, deps);
+            if (!r.ok) {
+                const detail = `launchctl bootstrap failed after ${r.bootstrapAttempts} attempts: ${(r.error ?? "").slice(0, 200)}`;
+                if (r.loaded) {
+                    // The previous definition survived the bootout; keep it running.
+                    deps.launchctl(["kickstart", "-k", `${launchdDomain(deps.uid)}/${p.label}`]);
+                }
+                return {
+                    platform,
+                    action: "install",
+                    installed: true,
+                    loaded: r.loaded,
+                    dest: p.plistPath,
+                    message: r.loaded
+                        ? `Wrote ${p.plistPath} but ${detail}. The previous definition of ${p.label} is still loaded and was restarted; the rewritten plist is not active yet.`
+                        : `Wrote ${p.plistPath} but ${detail}. ${p.label} is NOT loaded. Load it with: launchctl bootstrap ${launchdDomain(deps.uid)} ${p.plistPath}`,
+                };
+            }
+            loaded = true;
+        }
+        return {
+            platform,
+            action: "install",
+            installed: true,
+            loaded,
+            dest: p.plistPath,
+            message: `Installed LaunchAgent ${p.label} (${loaded ? "loaded" : "not loaded"})`,
+        };
+    }
+    if (platform === "linux") {
+        io.mkdirSync(path.dirname(p.systemdUnitPath), { recursive: true });
+        io.writeFileSync(p.systemdUnitPath, renderBotSystemdUnit(p), { mode: 0o600 });
+        return {
+            platform,
+            action: "install",
+            installed: true,
+            loaded: false,
+            dest: p.systemdUnitPath,
+            message: `Wrote systemd user unit ${p.systemdUnitPath}. Enable with: systemctl --user daemon-reload && systemctl --user enable --now hq-bot-${p.name}.service`,
+        };
+    }
+    return {
+        platform,
+        action: "install",
+        installed: false,
+        loaded: false,
+        message: `No service manager integration on this platform; run: ${p.nodeBinary} ${p.hqBinary} bot run ${p.name}`,
+    };
+}
+export function uninstallBotDaemon(p, deps = {}) {
+    const platform = deps.platform ?? detectBotPlatform();
+    const io = deps.fsImpl ?? fs;
+    if (platform === "darwin") {
+        // Order is load-bearing. `bootout` used to run first, which is fine from a
+        // shell and fatal from inside the job: when the orphan self-heal is itself
+        // the launchd job, bootout kills it, so the unlink below and the log line
+        // the person reads never happened — on a real Mac the stale plist survived
+        // and RunAtLoad resurrected the orphan at every login. Remove the file
+        // first, say so, and boot out last (detached when the caller is the job).
+        const existed = io.existsSync(p.plistPath);
+        if (existed)
+            io.unlinkSync(p.plistPath);
+        const result = {
+            platform,
+            action: "uninstall",
+            installed: false,
+            loaded: false,
+            dest: p.plistPath,
+            message: existed ? `Removed LaunchAgent ${p.label}` : `LaunchAgent ${p.label} was not installed`,
+        };
+        deps.announce?.(result);
+        bootoutLaunchd(p, deps);
+        return result;
+    }
+    if (platform === "linux") {
+        const existed = io.existsSync(p.systemdUnitPath);
+        if (existed)
+            io.unlinkSync(p.systemdUnitPath);
+        const result = {
+            platform,
+            action: "uninstall",
+            installed: false,
+            loaded: false,
+            dest: p.systemdUnitPath,
+            message: existed ? `Removed systemd unit for ${p.name}` : `No systemd unit for ${p.name}`,
+        };
+        deps.announce?.(result);
+        return result;
+    }
+    return { platform, action: "uninstall", installed: false, loaded: false, message: "Nothing to uninstall on this platform" };
+}
+export function botDaemonStatus(p, deps = {}) {
+    const platform = deps.platform ?? detectBotPlatform();
+    const io = deps.fsImpl ?? fs;
+    if (platform === "darwin") {
+        const installed = io.existsSync(p.plistPath);
+        const loaded = installed && launchdLoaded(p, deps);
+        const node = installed ? botDaemonNodeProblem(p, { fsImpl: io }) : null;
+        const nodeNote = node?.problem === "missing"
+            ? `; node binary missing (${node.nodeBinary}) — launchd cannot start it; run: hq bot start ${p.name}`
+            : "";
+        return {
+            platform,
+            action: "status",
+            installed,
+            loaded,
+            dest: p.plistPath,
+            ...(node ? { nodeBinary: node.nodeBinary, nodeProblem: node.problem } : {}),
+            message: installed
+                ? `LaunchAgent ${p.label}: ${loaded ? "loaded" : "installed (not loaded)"}${nodeNote}`
+                : `LaunchAgent ${p.label}: not installed`,
+        };
+    }
+    if (platform === "linux") {
+        const installed = io.existsSync(p.systemdUnitPath);
+        return {
+            platform,
+            action: "status",
+            installed,
+            loaded: false,
+            dest: p.systemdUnitPath,
+            message: installed ? `systemd unit for ${p.name}: installed` : `systemd unit for ${p.name}: not installed`,
+        };
+    }
+    return { platform, action: "status", installed: false, loaded: false, message: "No service manager integration on this platform" };
+}
+/** Load an installed LaunchAgent (idempotent: already-loaded is fine). */
+export function startBotDaemon(p, deps = {}) {
+    const platform = deps.platform ?? detectBotPlatform();
+    const io = deps.fsImpl ?? fs;
+    if (platform !== "darwin" || !deps.launchctl || !io.existsSync(p.plistPath)) {
+        return { ...botDaemonStatus(p, deps), action: "start" };
+    }
+    if (launchdLoaded(p, deps)) {
+        // Already loaded: kick the job so a stopped (exit-0) bot runs again.
+        deps.launchctl(["kickstart", `${launchdDomain(deps.uid)}/${p.label}`]);
+        return { platform, action: "start", installed: true, loaded: true, dest: p.plistPath, message: `LaunchAgent ${p.label} kicked` };
+    }
+    const r = deps.launchctl(["bootstrap", launchdDomain(deps.uid), p.plistPath]);
+    const loaded = r.ok || launchdLoaded(p, deps);
+    return {
+        platform,
+        action: "start",
+        installed: true,
+        loaded,
+        dest: p.plistPath,
+        message: loaded ? `LaunchAgent ${p.label} loaded` : `launchctl bootstrap failed: ${(r.stderr || r.stdout).trim().slice(0, 200)}`,
+    };
+}
+/** Unload the job (plist stays, so the bot returns at next login unless disabled). */
+export function stopBotDaemon(p, deps = {}) {
+    const platform = deps.platform ?? detectBotPlatform();
+    if (platform === "darwin" && deps.launchctl) {
+        deps.launchctl(["bootout", `${launchdDomain(deps.uid)}/${p.label}`]);
+    }
+    return { ...botDaemonStatus(p, deps), action: "stop" };
+}
+//# sourceMappingURL=daemon.js.map

package/dist/lib/bot/inbox-poll-backoff-flag.d.ts

@@ -0,0 +1,24 @@
+import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-client";
+import { type BotConfig } from "./config.js";
+export declare const INBOX_POLL_BACKOFF_FLAG = "agents.inbox-poll-backoff-local-cli";
+export declare const INBOX_POLL_BACKOFF_FLAG_FALLBACK = false;
+export declare const INBOX_POLL_BACKOFF_FLAG_TIMEOUT_MS = 2000;
+export declare const INBOX_POLL_BACKOFF_FLAG_CACHE_MS: number;
+type InboxPollBackoffFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
+export interface InboxPollBackoffFlagReaderDependencies {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => InboxPollBackoffFlagClient;
+    getToken?: FlagClientOptions["getToken"];
+    fetch?: typeof fetch;
+    now?: () => number;
+    reportFailure?: (error: unknown) => void;
+}
+export declare function safeErrorClass(error: unknown): string;
+/**
+ * Create a per-bot reader. The flag client is opened at most once per three
+ * minutes; a missing identity, failed request, or malformed snapshot keeps
+ * idle polling at its existing two-second interval.
+ */
+export declare function createInboxPollBackoffFlagReader(config: Pick<BotConfig, "kind" | "workerId" | "companies" | "companySlug" | "hqRoot">, dependencies?: InboxPollBackoffFlagReaderDependencies): () => Promise<boolean>;
+export {};
+//# sourceMappingURL=inbox-poll-backoff-flag.d.ts.map