@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/bot/runtime/sanitize.js

@@ -0,0 +1,28 @@
+/**
+ * Model control-token stripping for bot replies.
+ *
+ * A model can leak a raw control token as visible text — grok posted a bare
+ * `<|eos|>` as a room reply on 2026-09-25. These tokens are never meant for a
+ * person, so they are removed from both the in-between progress messages and
+ * the final reply before anything is posted.
+ *
+ * The generic `<|...|>` form covers any single control token in that shape
+ * (`<|eos|>`, `<|endoftext|>`, `<|im_end|>`, `<|eot_id|>`, and any other).
+ * Whitespace-only reply after stripping is empty, and callers apply the same
+ * empty-reply handling they already have (silent on an unmentioned room turn).
+ */
+/** Any single control token of the form `<|...|>` (no nested `<|`/`|>`). */
+const CONTROL_TOKEN_RE = /<\|(?:(?!<\||\|>).)*\|>/g;
+/** Remove every `<|...|>` control token from `text`, leaving the rest intact. */
+export function stripControlTokens(text) {
+    if (!text)
+        return text;
+    return text.replace(CONTROL_TOKEN_RE, "");
+}
+/** True when `text` is nothing but control tokens and whitespace. */
+export function isOnlyControlTokens(text) {
+    if (!text.trim())
+        return false;
+    return stripControlTokens(text).trim() === "";
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/lib/bot/runtime/types.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Model-CLI runtime adapters (local-bots US-003).
+ *
+ * One headless invocation per inbound DM, resumed by the CLI's own session id
+ * so context carries across turns and across restarts. The CLI runs under the
+ * OWNER's login (claude / codex / grok) — no Indigo-billed model keys.
+ */
+export interface RuntimeTurnInput {
+    /** The owner's DM text (the user turn). */
+    prompt: string;
+    /** Absolute path of the rendered system prompt file. */
+    systemPromptFile: string;
+    /** The system prompt text (for runtimes that cannot take a file). */
+    systemPrompt: string;
+    /** Working directory — the owner's HQ root, so skills and `hq` work. */
+    cwd: string;
+    /** Pre-approve every tool/command (headless bots cannot prompt). Default true. */
+    autoApprove?: boolean;
+    /** Claude only: explicit permission mode (a remembered fallback) — beats autoApprove. */
+    permissionMode?: string;
+    /** The owner's HQ root: runtimes with a write sandbox must allow it too,
+     *  or the bot cannot edit its own memory notes under personal/workers/. */
+    hqRoot?: string;
+    /**
+     * Directories outside cwd/hqRoot the turn must be able to READ (the bot's
+     * downloaded chat attachments). Claude restricts file tools to its working
+     * dirs outside bypassPermissions, so it gets `--add-dir` for each. Codex
+     * (read-anywhere in every sandbox mode) and Grok (--always-approve / ACP
+     * auto-allow) already read them and ignore this.
+     */
+    readDirs?: string[];
+    /** Previous session id to resume, if any. */
+    sessionId?: string;
+    /** Optional model override. */
+    model?: string;
+    /** Thinking level for the CLI (runtimes fall back to medium). */
+    effort?: string;
+    /**
+     * The session id to start a NEW session under (ignored when resuming).
+     * Set by the run loop when the bot is company-bound so the hooks' session
+     * meta file and the CLI session share one id.
+     */
+    newSessionId?: string;
+    /** Environment for the runtime process (default: process.env). */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Called for each event parsed from the runtime's stdout WHILE the turn runs
+     * (a finished assistant message, a tool call). Exceptions are swallowed.
+     */
+    onEvent?: (event: RuntimeStreamEvent) => void;
+    /** Aborting kills the runtime process (owner stop); the turn then fails with `aborted`. */
+    signal?: AbortSignal;
+    /** Runtime host platform; set by runRuntimeTurn and injectable for platform tests. */
+    platform?: NodeJS.Platform;
+}
+/**
+ * What a runtime's streaming output means to the bot, per stdout line:
+ * - `message`: one whole assistant message worth posting as progress
+ * - `tool`: the model started a tool (name only — never arguments or results)
+ * Reasoning/thinking content, token deltas, tool payloads and tool results are
+ * never surfaced.
+ */
+export type RuntimeStreamEvent = {
+    kind: "message";
+    text: string;
+} | {
+    kind: "tool";
+    name: string;
+};
+export interface RuntimeTurnResult {
+    text: string;
+    sessionId?: string;
+}
+export interface SpawnResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+}
+export interface SpawnOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** Kill the process after this long. Undefined = no limit (the default). */
+    timeoutMs?: number;
+    /** Each complete stdout line as it arrives (the trailing partial line on close). */
+    onStdoutLine?: (line: string) => void;
+    /** Kill the process when aborted. */
+    signal?: AbortSignal;
+    /** Optional full input stream for CLIs that accept prompts through stdin. */
+    stdin?: string;
+    /** Optional interactive protocol implemented over the child stdin/stdout streams. */
+    protocol?: SpawnProtocol;
+}
+export type SpawnProtocol = {
+    kind: "grok-acp";
+    prompt: string;
+    sessionId?: string;
+};
+export interface SpawnLike {
+    (command: string, args: string[], options: SpawnOptions): Promise<SpawnResult>;
+}
+export declare class RuntimeError extends Error {
+    readonly stderrExcerpt: string;
+    readonly exitCode: number | null;
+    /** False when the runtime process never started (missing binary, spawn error): safe to retry. */
+    readonly started: boolean;
+    /** True when the turn was ended on purpose (owner stop), not by a model failure. */
+    readonly aborted: boolean;
+    constructor(message: string, stderrExcerpt: string, exitCode: number | null, opts?: {
+        started?: boolean;
+        aborted?: boolean;
+    });
+}
+export interface BotRuntime {
+    readonly id: "claude" | "codex" | "grok";
+    /** Executable name looked up on PATH (or an absolute path). */
+    readonly binary: string;
+    /**
+     * Optional: the executable to spawn for this turn when `binary` is not on
+     * PATH (e.g. Claude Code that only exists inside the Claude desktop app).
+     * Resolved per turn so an app update that swaps the version folder is picked up.
+     */
+    resolveBinary?(env: NodeJS.ProcessEnv, cwd?: string, platform?: NodeJS.Platform): string;
+    /** Optional full prompt stream sent through stdin instead of argv. */
+    stdinInput?(input: RuntimeTurnInput): string | undefined;
+    /** Optional bidirectional process protocol for this runtime. */
+    spawnProtocol?(input: RuntimeTurnInput): SpawnProtocol | undefined;
+    /** Build the argv for one turn. Pure. */
+    buildArgs(input: RuntimeTurnInput, scratch: {
+        outputFile: string;
+        newSessionId: string;
+    }): string[];
+    /** Parse the CLI's stdout (and optional output file) into the reply. Pure. */
+    parseOutput(stdout: string, extra: {
+        outputFile?: string;
+        outputFileText?: string;
+    }): RuntimeTurnResult;
+    /** Optional: events in ONE stdout line of the streaming output format. Pure. */
+    parseStreamLine?(line: string): RuntimeStreamEvent[];
+    /**
+     * Optional: the human-readable reason for a failed turn (non-zero exit),
+     * mined from stdout/stderr — e.g. the API's "usage limit" or "model
+     * requires a newer CLI" message — so the owner sees the real cause instead
+     * of the CLI's last stderr chatter. Return undefined when nothing better
+     * than the stderr excerpt is known. Pure.
+     */
+    failureReason?(stdout: string, stderr: string): string | undefined;
+}
+/**
+ * Turns have no time limit: a turn runs until the model process exits (the
+ * owner can still stop the bot). `HQ_BOT_TURN_TIMEOUT_MS` is an escape hatch;
+ * unset, empty, zero or invalid means unlimited.
+ */
+export declare const TURN_TIMEOUT_ENV = "HQ_BOT_TURN_TIMEOUT_MS";
+export declare function turnTimeoutMs(env?: NodeJS.ProcessEnv): number | undefined;
+/** Parse one NDJSON line; null when it is not a JSON object. */
+export declare function parseJsonLine(line: string): Record<string, unknown> | null;
+export declare function stderrExcerpt(stderr: string, max?: number): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/bot/runtime/types.js

@@ -0,0 +1,51 @@
+/**
+ * Model-CLI runtime adapters (local-bots US-003).
+ *
+ * One headless invocation per inbound DM, resumed by the CLI's own session id
+ * so context carries across turns and across restarts. The CLI runs under the
+ * OWNER's login (claude / codex / grok) — no Indigo-billed model keys.
+ */
+export class RuntimeError extends Error {
+    stderrExcerpt;
+    exitCode;
+    /** False when the runtime process never started (missing binary, spawn error): safe to retry. */
+    started;
+    /** True when the turn was ended on purpose (owner stop), not by a model failure. */
+    aborted;
+    constructor(message, stderrExcerpt, exitCode, opts = {}) {
+        super(message);
+        this.stderrExcerpt = stderrExcerpt;
+        this.exitCode = exitCode;
+        this.name = "RuntimeError";
+        this.started = opts.started ?? true;
+        this.aborted = opts.aborted ?? false;
+    }
+}
+/**
+ * Turns have no time limit: a turn runs until the model process exits (the
+ * owner can still stop the bot). `HQ_BOT_TURN_TIMEOUT_MS` is an escape hatch;
+ * unset, empty, zero or invalid means unlimited.
+ */
+export const TURN_TIMEOUT_ENV = "HQ_BOT_TURN_TIMEOUT_MS";
+export function turnTimeoutMs(env = process.env) {
+    const raw = Number(env[TURN_TIMEOUT_ENV]);
+    return Number.isFinite(raw) && raw > 0 ? raw : undefined;
+}
+/** Parse one NDJSON line; null when it is not a JSON object. */
+export function parseJsonLine(line) {
+    const t = line.trim();
+    if (!t.startsWith("{"))
+        return null;
+    try {
+        const v = JSON.parse(t);
+        return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function stderrExcerpt(stderr, max = 400) {
+    const lines = stderr.split("\n").map((l) => l.trim()).filter(Boolean);
+    return lines.slice(-6).join(" | ").slice(0, max);
+}
+//# sourceMappingURL=types.js.map

package/dist/lib/bot/runtime/windows.d.ts

@@ -0,0 +1,10 @@
+import { type SpawnPlan } from "../../../utils/windows-spawn.js";
+type ExistsSync = (candidate: string) => boolean;
+/** Resolve an npm-installed provider command using Windows PATH and PATHEXT. */
+export declare function resolveWindowsExecutable(name: string, env: NodeJS.ProcessEnv, existsSync?: ExistsSync, cwd?: string): string | null;
+/** Preserve non-Windows lookup. Windows returns the first PATH/PATHEXT match. */
+export declare function resolveRuntimeBinary(name: string, env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, existsSync?: ExistsSync, cwd?: string): string;
+/** Directly spawn native files; pass only batch shims through cmd.exe. */
+export declare function planBotRuntimeSpawn(command: string, args: readonly string[], env: NodeJS.ProcessEnv, platform?: NodeJS.Platform): SpawnPlan;
+export {};
+//# sourceMappingURL=windows.d.ts.map

package/dist/lib/bot/runtime/windows.js

@@ -0,0 +1,53 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildCmdExeSpawnPlan, isWindowsBatchFile, } from "../../../utils/windows-spawn.js";
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+const SUPPORTED_PATHEXT = new Set([".com", ".exe", ".cmd", ".bat"]);
+function envValue(env, name) {
+    const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name);
+    return key ? env[key] : undefined;
+}
+/** Resolve an npm-installed provider command using Windows PATH and PATHEXT. */
+export function resolveWindowsExecutable(name, env, existsSync = fs.existsSync, cwd = process.cwd()) {
+    const pathValue = envValue(env, "PATH") ?? "";
+    const rawExtensions = (envValue(env, "PATHEXT") || DEFAULT_PATHEXT)
+        .split(";")
+        .map((extension) => {
+        const trimmed = extension.trim();
+        if (!trimmed)
+            return "";
+        return (trimmed.startsWith(".") ? trimmed : "." + trimmed).toLowerCase();
+    });
+    const extensions = [...new Set(rawExtensions.filter((extension) => SUPPORTED_PATHEXT.has(extension)))];
+    if (extensions.includes(".exe")) {
+        extensions.splice(extensions.indexOf(".exe"), 1);
+        extensions.unshift(".exe");
+    }
+    const searchExtensions = path.win32.extname(name) ? [""] : extensions;
+    for (const rawDir of pathValue.split(";")) {
+        const dir = rawDir.trim().replace(/^"(.*)"$/, "$1");
+        if (!dir)
+            continue;
+        const absoluteDir = path.win32.resolve(cwd, dir);
+        for (const extension of searchExtensions) {
+            const candidate = path.win32.join(absoluteDir, name + extension);
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/** Preserve non-Windows lookup. Windows returns the first PATH/PATHEXT match. */
+export function resolveRuntimeBinary(name, env, platform = process.platform, existsSync = fs.existsSync, cwd = process.cwd()) {
+    if (platform !== "win32")
+        return name;
+    return resolveWindowsExecutable(name, env, existsSync, cwd) ?? name;
+}
+/** Directly spawn native files; pass only batch shims through cmd.exe. */
+export function planBotRuntimeSpawn(command, args, env, platform = process.platform) {
+    if (isWindowsBatchFile(command, platform)) {
+        return buildCmdExeSpawnPlan(command, args, env, platform);
+    }
+    return { cmd: command, args: [...args], shell: false };
+}
+//# sourceMappingURL=windows.js.map

package/dist/lib/bot/runtime-sign-in.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The bot's coding tool (Claude Code, Codex, Grok) is installed but its login
+ * no longer works: never signed in, expired, or revoked. The vendor CLI can
+ * still report itself as logged in (a saved but dead token), so the only
+ * reliable evidence is a turn that fails this way.
+ *
+ * Such a turn fails before the model does anything, so the message is safe to
+ * answer later. The bot says once that it needs a sign-in, keeps the message,
+ * and tries again on its own (and at once after `hq bot restart`).
+ */
+import type { BotRuntimeId } from "./config.js";
+/** Time between the bot's own retries while its sign-in is broken. */
+export declare const SIGN_IN_RETRY_MS = 60000;
+export declare function isRuntimeSignInFailure(text: string | undefined | null): boolean;
+export declare function runtimeDisplayName(runtime: BotRuntimeId | string): string;
+/** Reported in status.json and `hq bot list --json` while the sign-in is broken. */
+export interface RuntimeSignInIssue {
+    state: "expired";
+    runtime: BotRuntimeId;
+    since: string;
+}
+/** The one message a conversation gets when the bot cannot work until its tool signs in again. */
+export declare function signInNeededText(runtime: BotRuntimeId | string, kickoff?: boolean): string;
+//# sourceMappingURL=runtime-sign-in.d.ts.map

package/dist/lib/bot/runtime-sign-in.js

@@ -0,0 +1,31 @@
+/**
+ * The bot's coding tool (Claude Code, Codex, Grok) is installed but its login
+ * no longer works: never signed in, expired, or revoked. The vendor CLI can
+ * still report itself as logged in (a saved but dead token), so the only
+ * reliable evidence is a turn that fails this way.
+ *
+ * Such a turn fails before the model does anything, so the message is safe to
+ * answer later. The bot says once that it needs a sign-in, keeps the message,
+ * and tries again on its own (and at once after `hq bot restart`).
+ */
+/** Time between the bot's own retries while its sign-in is broken. */
+export const SIGN_IN_RETRY_MS = 60_000;
+const SIGN_IN_FAILURE = /failed to authenticate|authentication[_ ]failed|not logged in|not signed in|please (?:run \/login|log ?in|sign ?in)|(?:oauth|access|refresh) token (?:has been |was )?(?:expired|revoked|invalid)|oauth session expired|invalid api key|\b401\b|unauthori[sz]ed|login (?:required|expired)|sign-?in (?:required|expired)/i;
+/** Usage and rate limits are a different problem; a new sign-in does not fix them. */
+const NOT_SIGN_IN = /usage[_ ]limit|rate[_ ]limit|quota|too many requests|credits/i;
+export function isRuntimeSignInFailure(text) {
+    const t = (text ?? "").trim();
+    if (!t)
+        return false;
+    return SIGN_IN_FAILURE.test(t) && !NOT_SIGN_IN.test(t);
+}
+export function runtimeDisplayName(runtime) {
+    return runtime === "claude" ? "Claude Code" : runtime === "codex" ? "Codex" : runtime === "grok" ? "Grok" : runtime;
+}
+/** The one message a conversation gets when the bot cannot work until its tool signs in again. */
+export function signInNeededText(runtime, kickoff = false) {
+    const tool = runtimeDisplayName(runtime);
+    return (`I can't work right now: ${tool} needs you to sign in again on this computer. ` +
+        `Use "Sign in to ${tool}" in HQ, and I'll ${kickoff ? "get started" : "answer this"} as soon as it works again — no need to send it twice.`);
+}
+//# sourceMappingURL=runtime-sign-in.js.map

package/dist/lib/bot/scaffold.d.ts

@@ -0,0 +1,38 @@
+/**
+ * personal/workers/<name>/ scaffold for a local bot (local-bots US-005/US-006).
+ * Never overwrites an existing file (the bot edits its own memory).
+ */
+import * as fs from "node:fs";
+export interface ScaffoldResult {
+    /** personal/workers/<name> (absolute). */
+    dir: string;
+    /** The memory folder (absolute) — inside `dir` unless `memoryDir` was given. */
+    memoryDir: string;
+    created: string[];
+    kept: string[];
+}
+export interface ScaffoldOptions {
+    /**
+     * Memory folder override: hqRoot-relative or absolute (`--memory local`
+     * keeps it under ~/.hq/bots/<name>/memory, outside the synced tree).
+     * Default: personal/workers/<name>/memory.
+     */
+    memoryDir?: string;
+}
+export declare function renderWorkerYaml(name: string, agentUid: string, runtime: string, memoryDir?: string): string;
+export declare function renderPersonaMd(name: string): string;
+export declare function renderMemoryReadme(name: string): string;
+type ScaffoldFs = Pick<typeof fs, "existsSync" | "mkdirSync" | "writeFileSync">;
+/** Absolute memory folder for a scaffold: the override (relative to hqRoot unless absolute) or the default. */
+export declare function resolveScaffoldMemoryDir(hqRoot: string, name: string, memoryDir?: string): string;
+/**
+ * The memory folder + README only — the memory a bot keeps between
+ * conversations: personal/workers/<name>/memory/ by default, or the given
+ * `memoryDir` (absolute for local memory). Used on its own for worker-sourced
+ * bots, whose definition lives in the company tree and must not be written
+ * to. Never overwrites an existing file.
+ */
+export declare function scaffoldBotMemory(hqRoot: string, name: string, io?: ScaffoldFs, opts?: ScaffoldOptions): ScaffoldResult;
+export declare function scaffoldBotWorker(hqRoot: string, name: string, agentUid: string, runtime: string, io?: ScaffoldFs, opts?: ScaffoldOptions): ScaffoldResult;
+export {};
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/lib/bot/scaffold.js

@@ -0,0 +1,94 @@
+/**
+ * personal/workers/<name>/ scaffold for a local bot (local-bots US-005/US-006).
+ * Never overwrites an existing file (the bot edits its own memory).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { botWorkerRelDir } from "./paths.js";
+export function renderWorkerYaml(name, agentUid, runtime, memoryDir) {
+    const memory = (memoryDir?.trim() || `personal/workers/${name}/memory`).replace(/\/+$/, "");
+    return `worker:
+  id: ${name}
+  name: "${name}"
+  description: "Personal local HQ bot (${runtime}) — runs on this computer with the owner's permissions"
+  type: PersonalBot
+  version: "1.0"
+  kind: local-bot
+  agent_uid: ${agentUid}
+
+execution:
+  mode: resident
+  runtime: ${runtime}
+  managed_by: hq bot
+
+context:
+  base:
+    - personal/workers/${name}/persona.md
+    - ${memory}/
+`;
+}
+export function renderPersonaMd(name) {
+    return `# ${name}
+
+You are ${name}, a personal assistant bot that lives in this HQ.
+
+## Voice
+
+- Warm, direct, and brief. Answer the person, not the mechanics.
+- Ask one question at a time when something is genuinely ambiguous.
+- Never paste secrets, tokens, or credentials into a reply.
+
+## Standing instructions
+
+- Prefer HQ's own skills and \`hq\` commands over hand-rolled scripts.
+- When you finish a task, say what changed and where in one or two lines.
+- Keep durable facts about your owner in \`memory/\` (short markdown notes).
+`;
+}
+export function renderMemoryReadme(name) {
+    return `# ${name} memory
+
+Short markdown notes ${name} keeps between conversations: preferences, recurring
+context, and things the owner asked it to remember. ${name} may edit these files;
+you can too. Never store secrets here.
+`;
+}
+function writeIfMissing(io, file, body, result) {
+    if (io.existsSync(file)) {
+        result.kept.push(file);
+        return;
+    }
+    io.writeFileSync(file, body, { mode: 0o644 });
+    result.created.push(file);
+}
+/** Absolute memory folder for a scaffold: the override (relative to hqRoot unless absolute) or the default. */
+export function resolveScaffoldMemoryDir(hqRoot, name, memoryDir) {
+    const raw = memoryDir?.trim();
+    if (!raw)
+        return path.join(hqRoot, botWorkerRelDir(name), "memory");
+    return path.isAbsolute(raw) ? raw : path.join(hqRoot, raw);
+}
+/**
+ * The memory folder + README only — the memory a bot keeps between
+ * conversations: personal/workers/<name>/memory/ by default, or the given
+ * `memoryDir` (absolute for local memory). Used on its own for worker-sourced
+ * bots, whose definition lives in the company tree and must not be written
+ * to. Never overwrites an existing file.
+ */
+export function scaffoldBotMemory(hqRoot, name, io = fs, opts = {}) {
+    const dir = path.join(hqRoot, botWorkerRelDir(name));
+    const memoryDir = resolveScaffoldMemoryDir(hqRoot, name, opts.memoryDir);
+    const result = { dir, memoryDir, created: [], kept: [] };
+    io.mkdirSync(memoryDir, { recursive: true });
+    writeIfMissing(io, path.join(memoryDir, "README.md"), renderMemoryReadme(name), result);
+    return result;
+}
+export function scaffoldBotWorker(hqRoot, name, agentUid, runtime, io = fs, opts = {}) {
+    const result = scaffoldBotMemory(hqRoot, name, io, opts);
+    const { dir } = result;
+    io.mkdirSync(dir, { recursive: true });
+    writeIfMissing(io, path.join(dir, "worker.yaml"), renderWorkerYaml(name, agentUid, runtime, opts.memoryDir), result);
+    writeIfMissing(io, path.join(dir, "persona.md"), renderPersonaMd(name), result);
+    return result;
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/lib/bot/self-heal.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Self-heal for a launchd registration that outlived its bot.
+ *
+ * `hq bot run <name>` is what the LaunchAgent runs. When the bot's local
+ * config is gone — a wiped ~/.hq, a half-finished reinstall, a bot removed by
+ * hand — the run used to exit non-zero, and KeepAlive{SuccessfulExit:false}
+ * with ThrottleInterval 5 relaunched it every five seconds forever (one test
+ * Mac logged 267 identical "No bot named" lines). So the run now does two
+ * things instead: it exits 0, which KeepAlive does not restart, and it removes
+ * its own registration, so a stale plist cannot outlive the bot it points at.
+ *
+ * Order matters here because this code usually IS the launchd job: the log
+ * line is written and the plist unlinked first, and the `bootout` — which
+ * terminates the caller — goes last, in a detached session that survives it.
+ *
+ * Everything is injectable (platform, launchctl, fs, home) so tests never
+ * touch the real service manager or the real LaunchAgents folder.
+ */
+import { type BotDaemonDeps } from "./daemon.js";
+export interface OrphanDaemonOutcome {
+    name: string;
+    label: string;
+    /** True when a registration was found and taken away. */
+    removed: boolean;
+    /** The plist (or systemd unit) path, when it could be resolved. */
+    dest?: string;
+    /** Why nothing could be removed, when that is the case. */
+    problem?: string;
+    message: string;
+}
+/**
+ * Take away the startup registration of a bot that has no local config here.
+ * Never throws: an unresolvable `hq` binary or an unwritable LaunchAgents
+ * folder must not turn into a crash loop of its own.
+ */
+export declare function removeOrphanBotDaemon(opts: {
+    name: string;
+    botDir: string;
+    home?: string;
+    /**
+     * Called once the plist is gone and before the `bootout` — the last moment
+     * a caller that is itself the launchd job is still alive to print anything.
+     */
+    announce?: (outcome: OrphanDaemonOutcome) => void;
+}, deps?: BotDaemonDeps): OrphanDaemonOutcome;
+/**
+ * What `hq bot run <name>` prints, once, when the bot is not set up on this
+ * computer — plain enough that a person reading ~/.hq/bots/<name>/logs/bot.log
+ * knows exactly what to do next.
+ */
+export declare function orphanBotRunMessage(name: string, outcome: OrphanDaemonOutcome): string;
+//# sourceMappingURL=self-heal.d.ts.map

package/dist/lib/bot/self-heal.js

@@ -0,0 +1,79 @@
+/**
+ * Self-heal for a launchd registration that outlived its bot.
+ *
+ * `hq bot run <name>` is what the LaunchAgent runs. When the bot's local
+ * config is gone — a wiped ~/.hq, a half-finished reinstall, a bot removed by
+ * hand — the run used to exit non-zero, and KeepAlive{SuccessfulExit:false}
+ * with ThrottleInterval 5 relaunched it every five seconds forever (one test
+ * Mac logged 267 identical "No bot named" lines). So the run now does two
+ * things instead: it exits 0, which KeepAlive does not restart, and it removes
+ * its own registration, so a stale plist cannot outlive the bot it points at.
+ *
+ * Order matters here because this code usually IS the launchd job: the log
+ * line is written and the plist unlinked first, and the `bootout` — which
+ * terminates the caller — goes last, in a detached session that survives it.
+ *
+ * Everything is injectable (platform, launchctl, fs, home) so tests never
+ * touch the real service manager or the real LaunchAgents folder.
+ */
+import { buildBotDaemonPaths, uninstallBotDaemon } from "./daemon.js";
+import { launchdLabel } from "./paths.js";
+/**
+ * Take away the startup registration of a bot that has no local config here.
+ * Never throws: an unresolvable `hq` binary or an unwritable LaunchAgents
+ * folder must not turn into a crash loop of its own.
+ */
+export function removeOrphanBotDaemon(opts, deps = {}) {
+    const label = launchdLabel(opts.name);
+    const toOutcome = (result) => {
+        const removed = /^Removed /.test(result.message);
+        return {
+            name: opts.name,
+            label,
+            removed,
+            ...(result.dest ? { dest: result.dest } : {}),
+            message: removed
+                ? `Removed the startup agent ${label} so it stops relaunching.`
+                : `No startup agent for ${opts.name} to remove.`,
+        };
+    };
+    let result;
+    try {
+        const paths = buildBotDaemonPaths({
+            name: opts.name,
+            botDir: opts.botDir,
+            ...(opts.home ? { home: opts.home } : {}),
+            // The plist path depends only on the name and home; a placeholder keeps
+            // an environment without a resolvable `hq` on PATH from throwing here.
+            hqBinary: "hq",
+            nodeBinary: process.execPath,
+        });
+        result = uninstallBotDaemon(paths, {
+            ...deps,
+            // This runs inside the very job being removed, so the bootout has to
+            // outlive us: detached by default, overridable for tests and for callers
+            // that are not the job.
+            bootout: deps.bootout ?? "detached",
+            ...(opts.announce ? { announce: (r) => opts.announce(toOutcome(r)) } : {}),
+        });
+    }
+    catch (err) {
+        const problem = err instanceof Error ? err.message : String(err);
+        return { name: opts.name, label, removed: false, problem, message: `Could not remove the startup agent ${label}: ${problem}` };
+    }
+    return toOutcome(result);
+}
+/**
+ * What `hq bot run <name>` prints, once, when the bot is not set up on this
+ * computer — plain enough that a person reading ~/.hq/bots/<name>/logs/bot.log
+ * knows exactly what to do next.
+ */
+export function orphanBotRunMessage(name, outcome) {
+    const lines = [
+        `No bot named "${name}" is set up on this computer, so there is nothing to run.`,
+        outcome.message,
+        `Bring it back with: hq bot adopt ${name}   (or restore every bot you own: hq bot restore)`,
+    ];
+    return lines.join("\n");
+}
+//# sourceMappingURL=self-heal.js.map

package/dist/lib/bot/self-process.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Is this `hq` command running inside a bot's own turn?
+ *
+ * A bot's model turn is a child of the bot process, and the tools it runs are
+ * children of that. When the turn runs `hq bot stop <itself>`, the stop used
+ * to `launchctl bootout` the bot's own job. launchd then kills the whole job —
+ * the bot, the model turn, and the very `hq bot stop` asking — so the reply
+ * the turn was writing is lost (exit 137) and the job is left unloaded.
+ * Seen on 2026-09-24: george stopped itself mid-turn to break a bot-to-bot
+ * loop, and nothing was posted after the stop.
+ *
+ * The caller walks its own parent chain; `parentOf` is injectable for tests.
+ */
+export type ParentPidLookup = (pid: number) => number | null;
+/** Parent pid via `ps` (macOS and Linux), or null when it cannot be read. */
+export declare const defaultParentOf: ParentPidLookup;
+/** True when `ancestorPid` is `startPid` itself or one of its ancestors. */
+export declare function isAncestorProcess(ancestorPid: number, startPid?: number, parentOf?: ParentPidLookup, maxDepth?: number): boolean;
+//# sourceMappingURL=self-process.d.ts.map