@indigoai-us/hq-cli 5.314.0 → 5.315.0

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

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+import { spawnSync } from "node:child_process";
+/** Parent pid via `ps` (macOS and Linux), or null when it cannot be read. */
+export const defaultParentOf = (pid) => {
+    const r = spawnSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8" });
+    if (r.status !== 0 || typeof r.stdout !== "string")
+        return null;
+    const n = Number.parseInt(r.stdout.trim(), 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+};
+/** True when `ancestorPid` is `startPid` itself or one of its ancestors. */
+export function isAncestorProcess(ancestorPid, startPid = process.pid, parentOf = defaultParentOf, maxDepth = 64) {
+    if (!Number.isInteger(ancestorPid) || ancestorPid <= 1)
+        return false;
+    let pid = startPid;
+    for (let depth = 0; pid !== null && pid > 1 && depth < maxDepth; depth++) {
+        if (pid === ancestorPid)
+            return true;
+        pid = parentOf(pid);
+    }
+    return false;
+}
+//# sourceMappingURL=self-process.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * session.json — the model CLI's own session id so each DM turn resumes the
+ * same conversation (one headless invocation per DM, resumed by id).
+ * Non-owner DMs get a separate file per peer. Rooms get their own file per channel (session-room-<channelId>.json) so the
+ * owner's DM context is never carried into a group chat, and vice versa.
+ */
+import { type BotSessionScope } from "./paths.js";
+import type { BotRuntimeId } from "./config.js";
+export interface BotSessionFile {
+    v: 1;
+    runtime: BotRuntimeId;
+    sessionId: string;
+    turns: number;
+    updatedAt: string;
+}
+export declare function readBotSession(dir: string, runtime: BotRuntimeId, scope?: BotSessionScope): BotSessionFile | null;
+export declare function writeBotSession(dir: string, session: BotSessionFile, scope?: BotSessionScope): void;
+export declare function clearBotSession(dir: string, scope?: BotSessionScope): void;
+//# sourceMappingURL=session.d.ts.map

package/dist/lib/bot/session.js

@@ -0,0 +1,39 @@
+/**
+ * session.json — the model CLI's own session id so each DM turn resumes the
+ * same conversation (one headless invocation per DM, resumed by id).
+ * Non-owner DMs get a separate file per peer. Rooms get their own file per channel (session-room-<channelId>.json) so the
+ * owner's DM context is never carried into a group chat, and vice versa.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { botSessionPath } from "./paths.js";
+export function readBotSession(dir, runtime, scope = "dm") {
+    const p = botSessionPath(dir, scope);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (raw.v !== 1 || raw.runtime !== runtime || typeof raw.sessionId !== "string")
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeBotSession(dir, session, scope = "dm") {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = botSessionPath(dir, scope);
+    const tmp = path.join(dir, `.session.tmp.${process.pid}.${Date.now()}`);
+    fs.writeFileSync(tmp, `${JSON.stringify(session, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+}
+export function clearBotSession(dir, scope = "dm") {
+    try {
+        fs.unlinkSync(botSessionPath(dir, scope));
+    }
+    catch {
+        /* already gone */
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/lib/bot/setup-explain.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The setup bot's instant "Explain HQ first" answer.
+ *
+ * The setup bot's first question is whether to explain HQ or jump straight in,
+ * with "Explain HQ first" as a suggested reply. The explanation is fixed text,
+ * so a click on that button does not need a model turn: the runner sends the
+ * text from the setup worker's `skills/explain-hq.md` at once, and the bot's
+ * next turn starts with a note saying the explanation already went out.
+ *
+ * The text has one home, the worker file. The model reads the same file when
+ * someone asks for the explanation in their own words, so the two paths never
+ * drift. Anything unexpected (file missing or malformed, the question not
+ * pending, any other message) falls back to the normal model turn.
+ */
+/** The suggested reply that triggers the instant answer. Exact match only. */
+export declare const EXPLAIN_HQ_SUGGESTION = "Explain HQ first";
+/** Where the explanation lives, relative to the setup worker folder. */
+export declare const EXPLAIN_HQ_FILE: string;
+/**
+ * Put in front of the next message from the person, so the model knows the
+ * explanation went out without it. It never reaches the person.
+ */
+export declare const SETUP_EXPLAINED_NOTE: string;
+export interface SetupExplainer {
+    /** The explanation, word for word (shared with the model path). */
+    explanation: string;
+    /** What the app adds after it: a line offering to continue, and suggestions. */
+    closing: string;
+    /** The whole message the app sends. */
+    reply: string;
+}
+/** Parse the worker file. Null when it is not the shape the app can send. */
+export declare function parseSetupExplainer(body: string): SetupExplainer | null;
+/** Read the explanation from the setup worker folder the bot runs. */
+export declare function loadSetupExplainer(hqRoot: string, workerDir: string): SetupExplainer | null;
+export type SetupProgressIntro = "asked" | "answered" | "finished" | null;
+/** What the model's progress note says about the opening question. */
+export declare function readSetupProgressIntro(memoryDir: string): SetupProgressIntro;
+export interface SetupIntroState {
+    v: 1;
+    /** The bot's latest owner-DM reply asked the explain-or-jump question. */
+    offeredAt?: string;
+    /** The app sent the explanation (never sent twice). */
+    explainedAt?: string;
+    /** The model has not yet been told that the explanation went out. */
+    notePending?: boolean;
+}
+export declare function readSetupIntroState(dir: string): SetupIntroState;
+export declare function patchSetupIntroState(dir: string, patch: Partial<Omit<SetupIntroState, "v">>): SetupIntroState;
+/** A bot reply that asks the explain-or-jump question (the words or the button). */
+export declare function replyOffersExplain(reply: string): boolean;
+/**
+ * The instant answer is due only when ALL of these hold: the message is exactly
+ * the button text with nothing attached, the question is pending (the bot's
+ * last reply offered it, or its note says it asked), and the explanation has
+ * not gone out yet (neither by the app nor, per the note, by the model).
+ */
+export declare function setupExplainDue(input: {
+    text: string;
+    attachments: number;
+    state: SetupIntroState;
+    progress: SetupProgressIntro;
+}): boolean;
+//# sourceMappingURL=setup-explain.d.ts.map

package/dist/lib/bot/setup-explain.js

@@ -0,0 +1,141 @@
+/**
+ * The setup bot's instant "Explain HQ first" answer.
+ *
+ * The setup bot's first question is whether to explain HQ or jump straight in,
+ * with "Explain HQ first" as a suggested reply. The explanation is fixed text,
+ * so a click on that button does not need a model turn: the runner sends the
+ * text from the setup worker's `skills/explain-hq.md` at once, and the bot's
+ * next turn starts with a note saying the explanation already went out.
+ *
+ * The text has one home, the worker file. The model reads the same file when
+ * someone asks for the explanation in their own words, so the two paths never
+ * drift. Anything unexpected (file missing or malformed, the question not
+ * pending, any other message) falls back to the normal model turn.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** The suggested reply that triggers the instant answer. Exact match only. */
+export const EXPLAIN_HQ_SUGGESTION = "Explain HQ first";
+/** Where the explanation lives, relative to the setup worker folder. */
+export const EXPLAIN_HQ_FILE = path.join("skills", "explain-hq.md");
+/** The setup bot's progress note in its memory folder (setup worker.yaml). */
+const SETUP_PROGRESS_FILE = "setup-progress.md";
+/** Runner-owned state, in the bot's own folder (never the model's memory). */
+const SETUP_INTRO_STATE_FILE = "setup-intro.json";
+const EXPLANATION_HEADING = /^##[ \t]+The explanation[ \t]*$/m;
+const CLOSING_HEADING = /^##[ \t]+After the explanation, when the app sends it[ \t]*$/m;
+/**
+ * Put in front of the next message from the person, so the model knows the
+ * explanation went out without it. It never reaches the person.
+ */
+export const SETUP_EXPLAINED_NOTE = `[Note from the HQ app: the person clicked "${EXPLAIN_HQ_SUGGESTION}", and the app already sent them the explanation ` +
+    `from skills/explain-hq.md word for word, ending by asking whether to start the setup. The explain-or-jump question is answered. ` +
+    "Write `Intro: explained` in your progress note, do not explain HQ again, and carry on with the first unfinished setup step. " +
+    "Their reply to that message follows.]";
+/** The text between a heading and the next `## ` heading (or the end). */
+function sectionAfter(body, heading) {
+    const match = heading.exec(body);
+    if (!match)
+        return null;
+    const rest = body.slice(match.index + match[0].length);
+    const next = /^##[ \t]/m.exec(rest);
+    return (next ? rest.slice(0, next.index) : rest).trim();
+}
+/** True when the closing carries exactly one well-formed suggestions block. */
+function hasSuggestionsBlock(closing) {
+    const fence = /^```hq-block\n(.+)\n```$/m.exec(closing);
+    if (!fence)
+        return false;
+    try {
+        const parsed = JSON.parse(fence[1]);
+        const block = parsed.blocks?.[0];
+        return (parsed.v === 1 &&
+            block?.kind === "suggestions" &&
+            Array.isArray(block.items) &&
+            block.items.length >= 2 &&
+            block.items.every((item) => typeof item === "string" && item.trim().length > 0));
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse the worker file. Null when it is not the shape the app can send. */
+export function parseSetupExplainer(body) {
+    const text = body.replace(/\r\n/g, "\n");
+    const explanation = sectionAfter(text, EXPLANATION_HEADING);
+    const closing = sectionAfter(text, CLOSING_HEADING);
+    if (!explanation || !closing)
+        return null;
+    // The closing must end with the block (nothing after it) so the app shows the buttons.
+    if (!closing.endsWith("```") || !hasSuggestionsBlock(closing))
+        return null;
+    return { explanation, closing, reply: `${explanation}\n\n${closing}` };
+}
+/** Read the explanation from the setup worker folder the bot runs. */
+export function loadSetupExplainer(hqRoot, workerDir) {
+    try {
+        return parseSetupExplainer(fs.readFileSync(path.resolve(hqRoot, workerDir, EXPLAIN_HQ_FILE), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** What the model's progress note says about the opening question. */
+export function readSetupProgressIntro(memoryDir) {
+    let note;
+    try {
+        note = fs.readFileSync(path.join(memoryDir, SETUP_PROGRESS_FILE), "utf8");
+    }
+    catch {
+        return null;
+    }
+    if (/^Status:[ \t]*finished/im.test(note))
+        return "finished";
+    if (/^Intro:[ \t]*(explained|skipped)\b/im.test(note))
+        return "answered";
+    if (/^Intro:[ \t]*asked\b/im.test(note))
+        return "asked";
+    return null;
+}
+export function readSetupIntroState(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, SETUP_INTRO_STATE_FILE), "utf8"));
+        return parsed && parsed.v === 1 ? parsed : { v: 1 };
+    }
+    catch {
+        return { v: 1 };
+    }
+}
+export function patchSetupIntroState(dir, patch) {
+    const next = { ...readSetupIntroState(dir), ...patch, v: 1 };
+    for (const key of Object.keys(next)) {
+        if (next[key] === undefined)
+            delete next[key];
+    }
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = path.join(dir, SETUP_INTRO_STATE_FILE);
+    const tmp = `${dest}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+    return next;
+}
+/** A bot reply that asks the explain-or-jump question (the words or the button). */
+export function replyOffersExplain(reply) {
+    return reply.includes(`"${EXPLAIN_HQ_SUGGESTION}"`) || /explain HQ to you/i.test(reply);
+}
+/**
+ * The instant answer is due only when ALL of these hold: the message is exactly
+ * the button text with nothing attached, the question is pending (the bot's
+ * last reply offered it, or its note says it asked), and the explanation has
+ * not gone out yet (neither by the app nor, per the note, by the model).
+ */
+export function setupExplainDue(input) {
+    if (input.text !== EXPLAIN_HQ_SUGGESTION || input.attachments > 0)
+        return false;
+    if (input.state.explainedAt)
+        return false;
+    if (input.progress === "answered" || input.progress === "finished")
+        return false;
+    return Boolean(input.state.offeredAt) || input.progress === "asked";
+}
+//# sourceMappingURL=setup-explain.js.map

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

@@ -0,0 +1,32 @@
+/**
+ * A long reply, cut into posts HQ Cloud will actually accept.
+ *
+ * `POST /v1/notify/dm` refuses a body over DM_BODY_MAX characters with
+ * `400: Message body exceeds 4000 characters`. Nothing used to split, so a
+ * model answer over the limit was sent whole, refused, saved on the in-flight
+ * marker and re-sent identically on every poll — the answer was lost, the
+ * person was never told, and the bot asked the API to do the impossible about
+ * twice a second for as long as it ran.
+ *
+ * `splitBody` is the fix, and it is pure so it can be tested on its own:
+ *
+ * - a body at or under the limit comes back untouched, as one part
+ * - a longer body is cut on paragraph boundaries first, then on sentence
+ *   boundaries, and only hard-wrapped when a single sentence is still too long
+ * - a fenced code block is kept whole when it fits; when it cannot fit, the
+ *   fence is closed at the end of one part and reopened (with its language) at
+ *   the start of the next, so neither part renders as broken markdown
+ * - when there is more than one part, each is prefixed `(2/3)` on its own line
+ *   so the reader can see the order; the prefix is paid for out of the limit,
+ *   never added on top of it
+ *
+ * Every returned part is guaranteed to be at most `max` characters long.
+ */
+/** The largest body HQ Cloud accepts on a DM or channel post. */
+export declare const DM_BODY_MAX = 4000;
+/**
+ * One outbound body as the ordered parts to post, each at most `max`
+ * characters. A body that already fits comes back unchanged.
+ */
+export declare function splitBody(body: string, max?: number): string[];
+//# sourceMappingURL=split.d.ts.map

package/dist/lib/bot/split.js

@@ -0,0 +1,241 @@
+/**
+ * A long reply, cut into posts HQ Cloud will actually accept.
+ *
+ * `POST /v1/notify/dm` refuses a body over DM_BODY_MAX characters with
+ * `400: Message body exceeds 4000 characters`. Nothing used to split, so a
+ * model answer over the limit was sent whole, refused, saved on the in-flight
+ * marker and re-sent identically on every poll — the answer was lost, the
+ * person was never told, and the bot asked the API to do the impossible about
+ * twice a second for as long as it ran.
+ *
+ * `splitBody` is the fix, and it is pure so it can be tested on its own:
+ *
+ * - a body at or under the limit comes back untouched, as one part
+ * - a longer body is cut on paragraph boundaries first, then on sentence
+ *   boundaries, and only hard-wrapped when a single sentence is still too long
+ * - a fenced code block is kept whole when it fits; when it cannot fit, the
+ *   fence is closed at the end of one part and reopened (with its language) at
+ *   the start of the next, so neither part renders as broken markdown
+ * - when there is more than one part, each is prefixed `(2/3)` on its own line
+ *   so the reader can see the order; the prefix is paid for out of the limit,
+ *   never added on top of it
+ *
+ * Every returned part is guaranteed to be at most `max` characters long.
+ */
+/** The largest body HQ Cloud accepts on a DM or channel post. */
+export const DM_BODY_MAX = 4000;
+const FENCE_RE = /^[ \t]*(`{3,}|~{3,})(.*)$/;
+function bare(line) {
+    return line.replace(/\r?\n$/, "");
+}
+/**
+ * The body as paragraphs and whole fenced code blocks, in order. Concatenating
+ * every `raw` reproduces the input exactly, so nothing is lost or reflowed
+ * before a cut is actually needed.
+ */
+function segmentize(body) {
+    const segments = [];
+    let buf = "";
+    let fence = null;
+    const flush = (fenceOpen) => {
+        if (buf)
+            segments.push({ raw: buf, fenceOpen });
+        buf = "";
+    };
+    for (const line of body.split(/(?<=\n)/)) {
+        const text = bare(line);
+        if (fence) {
+            buf += line;
+            const m = FENCE_RE.exec(text);
+            // A closing fence is the same character, at least as long, and bare.
+            if (m && m[1][0] === fence.marker[0] && m[1].length >= fence.marker.length && m[2].trim() === "") {
+                flush(fence.open);
+                fence = null;
+            }
+            continue;
+        }
+        const m = FENCE_RE.exec(text);
+        if (m) {
+            flush(null);
+            fence = { open: text.trimEnd(), marker: m[1] };
+            buf = line;
+            continue;
+        }
+        if (text.trim() === "") {
+            // A blank line closes the paragraph it follows.
+            if (buf)
+                buf += line;
+            else
+                buf = line;
+            flush(null);
+            continue;
+        }
+        buf += line;
+    }
+    flush(fence ? fence.open : null);
+    return segments;
+}
+/** Break points inside a paragraph: after sentence-ending punctuation, or at a line end. */
+function splitSentences(text) {
+    const parts = [];
+    const re = /(?:[.!?…]["'”’)\]]*|\n)[ \t]*\n?[ \t]*/g;
+    let start = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const end = m.index + m[0].length;
+        if (end <= start) {
+            re.lastIndex = start + 1;
+            continue;
+        }
+        parts.push(text.slice(start, end));
+        start = end;
+    }
+    if (start < text.length)
+        parts.push(text.slice(start));
+    return parts.length > 0 ? parts : [text];
+}
+/** Last resort: a run of text with no usable break, cut at whitespace when there is any. */
+function hardWrap(text, budget) {
+    const out = [];
+    let rest = text;
+    while (rest.length > budget) {
+        const window = rest.slice(0, budget);
+        const ws = Math.max(window.lastIndexOf(" "), window.lastIndexOf("\n"));
+        const cut = ws > 0 && ws >= Math.floor(budget * 0.6) ? ws : budget;
+        const piece = rest.slice(0, cut).trim();
+        if (piece)
+            out.push(piece);
+        rest = rest.slice(cut).replace(/^[ \t\n]+/, "");
+    }
+    const tail = rest.trim();
+    if (tail)
+        out.push(tail);
+    return out;
+}
+/** A code block too long for one part: closed and reopened around every cut. */
+function splitFenced(segment, budget) {
+    const open = segment.fenceOpen ?? "```";
+    const marker = FENCE_RE.exec(open)?.[1] ?? "```";
+    const overhead = open.length + marker.length + 2; // the two fence lines and their newlines
+    const inner = budget - overhead;
+    if (inner < 1)
+        return splitPlain(segment.raw, budget);
+    const lines = segment.raw.split(/(?<=\n)/).slice(1);
+    const last = lines[lines.length - 1];
+    if (last !== undefined) {
+        const m = FENCE_RE.exec(bare(last));
+        if (m && m[1][0] === marker[0] && m[2].trim() === "")
+            lines.pop();
+    }
+    const pieces = [];
+    let buf = "";
+    const emit = () => {
+        const code = buf.replace(/\n+$/, "");
+        buf = "";
+        if (code.trim() === "")
+            return;
+        pieces.push(`${open}\n${code}\n${marker}`);
+    };
+    for (const line of lines) {
+        if ((buf + line).replace(/\n+$/, "").length <= inner) {
+            buf += line;
+            continue;
+        }
+        emit();
+        const one = bare(line);
+        if (one.length <= inner) {
+            buf = line;
+            continue;
+        }
+        for (const wrapped of hardWrap(one, inner)) {
+            buf = wrapped;
+            emit();
+        }
+    }
+    emit();
+    return pieces.length > 0 ? pieces : splitPlain(segment.raw, budget);
+}
+/** A paragraph too long for one part: sentences first, hard wrap only if one sentence is still too long. */
+function splitPlain(text, budget) {
+    const out = [];
+    let buf = "";
+    const flush = () => {
+        const t = buf.trim();
+        buf = "";
+        if (t)
+            out.push(t);
+    };
+    for (const sentence of splitSentences(text)) {
+        if ((buf + sentence).trim().length <= budget) {
+            buf += sentence;
+            continue;
+        }
+        flush();
+        if (sentence.trim().length <= budget) {
+            buf = sentence;
+            continue;
+        }
+        for (const wrapped of hardWrap(sentence.trim(), budget))
+            out.push(wrapped);
+    }
+    flush();
+    return out.length > 0 ? out : hardWrap(text.trim(), budget);
+}
+function pack(body, budget) {
+    const out = [];
+    let acc = "";
+    const flush = () => {
+        const t = acc.trim();
+        acc = "";
+        if (t)
+            out.push(t);
+    };
+    for (const segment of segmentize(body)) {
+        if ((acc + segment.raw).trim().length <= budget) {
+            acc += segment.raw;
+            continue;
+        }
+        flush();
+        if (segment.raw.trim().length <= budget) {
+            acc = segment.raw;
+            continue;
+        }
+        for (const piece of segment.fenceOpen ? splitFenced(segment, budget) : splitPlain(segment.raw, budget)) {
+            out.push(piece);
+        }
+    }
+    flush();
+    return out;
+}
+/** `(2/3)` and its newline, at the widest the count can make it. */
+function prefixWidth(count) {
+    return `(${count}/${count})\n`.length;
+}
+function label(parts) {
+    if (parts.length < 2)
+        return parts;
+    return parts.map((part, i) => `(${i + 1}/${parts.length})\n${part}`);
+}
+/**
+ * One outbound body as the ordered parts to post, each at most `max`
+ * characters. A body that already fits comes back unchanged.
+ */
+export function splitBody(body, max = DM_BODY_MAX) {
+    const limit = Math.max(1, Math.floor(max));
+    if (body.length <= limit)
+        return [body];
+    let reserve = prefixWidth(2);
+    let parts = [];
+    for (let round = 0; round < 6; round += 1) {
+        parts = pack(body, Math.max(1, limit - reserve));
+        const needed = parts.length > 1 ? prefixWidth(parts.length) : 0;
+        if (needed <= reserve)
+            break;
+        reserve = needed;
+    }
+    if (parts.length === 0)
+        parts = [body.trim() || body];
+    // Belt and braces: whatever the shape of the input, no part may exceed the limit.
+    return label(parts).flatMap((part) => (part.length <= limit ? [part] : hardWrap(part, limit)));
+}
+//# sourceMappingURL=split.js.map

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

@@ -0,0 +1,57 @@
+/**
+ * status.json — atomic, metadata-only runtime status (local-bots US-003).
+ */
+import type { BotRuntimeId } from "./config.js";
+import type { RuntimeSignInIssue } from "./runtime-sign-in.js";
+export type BotState = "starting" | "running" | "stopped" | "failed";
+export interface BotStatusFile {
+    v: 1;
+    pid: number;
+    state: BotState;
+    runtime: BotRuntimeId;
+    startedAt: string;
+    lastActivityAt: string;
+    /** Model-CLI restarts since this process started. */
+    restarts: number;
+    /** Consecutive model-CLI failures inside the failure window. */
+    recentFailures: number;
+    lastHeartbeatAt?: string;
+    lastHeartbeatOk?: boolean;
+    /** Last heartbeat error, when lastHeartbeatOk is false. */
+    lastHeartbeatError?: string;
+    /** A heartbeat stopped permanently until the bot is restarted with corrected identity config. */
+    lastHeartbeatReason?: "identity_mismatch";
+    lastHeartbeatConfiguredAgentUid?: string;
+    lastHeartbeatTokenAgentUid?: string;
+    lastInboxPollAt?: string;
+    lastInboxPollOk?: boolean;
+    /** Last inbox poll error, when lastInboxPollOk is false. */
+    lastInboxError?: string;
+    /** Bounded, redacted stderr excerpt of the last model-CLI failure. */
+    lastError?: string;
+    /** Inbound DMs answered since start. */
+    repliesSent: number;
+    /** True only after this process has installed its graceful promotion signal. */
+    canDrainForPromotion?: boolean;
+    /**
+     * Claude only: permission mode the bot settled on after a fallback
+     * (e.g. "auto" when this Claude Code's settings disable bypassPermissions).
+     * Persisted so later turns skip the failed attempt.
+     */
+    claudePermissionMode?: string;
+    /**
+     * Set while the coding tool's sign-in is broken (a turn failed for that
+     * reason); cleared by the next turn that works. `null` = known to work.
+     */
+    runtimeSignIn?: RuntimeSignInIssue | null;
+    /** hq-cli version this process loaded (a bot keeps it until it restarts). */
+    cliVersion?: string;
+    updatedAt: string;
+}
+export declare function defaultBotStatus(pid: number, runtime: BotRuntimeId, now?: () => Date): BotStatusFile;
+export declare function readBotStatus(dir: string): BotStatusFile | null;
+export declare function writeBotStatus(dir: string, status: BotStatusFile): void;
+export declare function patchBotStatus(dir: string, patch: Partial<BotStatusFile>, fallback: () => BotStatusFile, now?: () => Date): BotStatusFile;
+/** Live process check for a status file's pid. */
+export declare function isPidAlive(pid: number): boolean;
+//# sourceMappingURL=status.d.ts.map