@indigoai-us/hq-cli 5.116.0 → 5.117.1

package/dist/lib/bot/local-name.js

@@ -0,0 +1,114 @@
+/**
+ * Which folder under ~/.hq/bots/ a cloud bot belongs to.
+ *
+ * HQ gives a bot's cloud record a slug carrying the owner's suffix: a bot
+ * created here as `qa-x` is `qa-x-rg13gzm4` in the cloud. Deriving the local
+ * name from the slug alone meant re-adopting that bot built a SECOND directory
+ * next to the first — `~/.hq/bots/qa-x-rg13gzm4/` beside `~/.hq/bots/qa-x/` —
+ * with a second LaunchAgent label and a second memory folder, while the
+ * original kept live machine credentials that nothing would ever clean up and
+ * `hq bot rm qa-x` could no longer reach.
+ *
+ * One bot, one directory. So:
+ *
+ *   1. If any directory here already carries this bot's agent uid — in its
+ *      bot.json, or (when a wipe took the config but left the credentials) in
+ *      its machine-creds.json — that IS the bot's directory. Reuse it and
+ *      repair in place.
+ *   2. Otherwise strip the owner's suffix off the slug, so a bot created here
+ *      comes back under the name it was created with.
+ *   3. Unless that name is already taken by a DIFFERENT bot, in which case the
+ *      full slug keeps the two apart.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readBotConfig } from "./config.js";
+import { readBotCredsIdentity } from "./creds.js";
+import { botDir, botsRoot, isValidBotName } from "./paths.js";
+/** The shortest tail that can be an owner suffix; below this, stripping is guesswork. */
+const MIN_OWNER_SUFFIX = 4;
+/** A cloud name as a folder name here, or null when it cannot be one. */
+export function botNameFromSlug(value) {
+    const slug = (value ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/g, "");
+    return slug && isValidBotName(slug) ? slug : null;
+}
+/** Every bot directory on this computer, with the identity it holds. */
+export function localBotDirectories(root) {
+    const base = root ?? botsRoot();
+    let entries;
+    try {
+        entries = fs.readdirSync(base, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(base, entry.name);
+        const agentUid = readBotConfig(dir)?.agentUid ?? readBotCredsIdentity(dir)?.entityUid ?? null;
+        out.push({ name: entry.name, dir, agentUid });
+    }
+    return out;
+}
+/** The directory this identity already has here, however it is named. */
+export function findLocalBotByAgentUid(agentUid, root) {
+    const wanted = (agentUid ?? "").trim();
+    if (!wanted)
+        return null;
+    return localBotDirectories(root).find((d) => d.agentUid === wanted) ?? null;
+}
+/**
+ * `qa-x-rg13gzm4` → `qa-x`, when `rg13gzm4` is this owner's suffix. The suffix
+ * is whatever tail of the owner's uid HQ appended, so it is recognised by
+ * matching the tail against the uid rather than by assuming its length.
+ * Anything unrecognised is left exactly as it is.
+ */
+export function stripOwnerSuffix(slug, ownerUid) {
+    const owner = (ownerUid ?? "").trim().toLowerCase();
+    if (!owner)
+        return slug;
+    const cut = slug.lastIndexOf("-");
+    if (cut <= 0)
+        return slug;
+    const tail = slug.slice(cut + 1);
+    if (tail.length < MIN_OWNER_SUFFIX || !owner.endsWith(tail))
+        return slug;
+    const base = slug.slice(0, cut);
+    return isValidBotName(base) ? base : slug;
+}
+/**
+ * The folder name this cloud bot has (or should have) on this computer, or
+ * null when its name cannot be a folder name here at all.
+ *
+ * `ownerUid` is the signed-in account, used when the listing did not say who
+ * owns the bot; the listing's own `ownerUid` wins when it is there.
+ */
+export function localNameForRemoteBot(bot, opts = {}) {
+    const root = opts.root;
+    const existing = bot.agentUid ? findLocalBotByAgentUid(bot.agentUid, root) : null;
+    if (existing)
+        return existing.name;
+    const slug = botNameFromSlug(bot.slug) ?? botNameFromSlug(bot.name);
+    if (!slug)
+        return null;
+    const stripped = stripOwnerSuffix(slug, bot.ownerUid ?? opts.ownerUid ?? null);
+    if (stripped === slug)
+        return slug;
+    // Two different bots may want the same short name. The one that is here
+    // already keeps it; the newcomer keeps its full slug, so neither is lost.
+    const taken = localBotDirectories(root).find((d) => d.name === stripped);
+    if (taken && taken.agentUid !== bot.agentUid)
+        return slug;
+    if (!taken && fs.existsSync(botDir(stripped, root)))
+        return slug;
+    return stripped;
+}
+//# sourceMappingURL=local-name.js.map

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

@@ -55,6 +55,15 @@ export declare const RECENT_MESSAGES_LIMIT = 15;
 export declare const RECENT_MESSAGE_MAX_CHARS = 400;
 /** Model turns a bot runs at once (each on a different conversation). */
 export declare const MAX_PARALLEL_TURNS = 2;
+/**
+ * Failed attempts to deliver ONE saved message before the bot stops trying.
+ * A body the server refuses (too long, malformed) is refused identically every
+ * time, so retrying it on every 2s poll only hammers the API and leaves the
+ * person with no answer and no explanation.
+ */
+export declare const RECOVERY_ATTEMPT_LIMIT = 5;
+/** What the person sees when a reply could not be delivered at all. */
+export declare const UNDELIVERABLE_REPLY_TEXT = "I wrote a reply but couldn't deliver it. Ask me again and I'll keep it shorter.";
 export type SleepFn = (ms: number) => Promise<void>;
 export interface BotRunDeps {
     dir: string;

package/dist/lib/bot/run.js

@@ -50,6 +50,7 @@ import { readBotCredsIdentity } from "./creds.js";
 import { isProcessed, markProcessed, readInboxState } from "./inbox-state.js";
 import { clearInflight, patchInflight, readInflight, readInflightTurns, writeInflight } from "./inflight.js";
 import { ProgressPoster } from "./progress.js";
+import { splitBody } from "./split.js";
 import { createBotLogger } from "./log.js";
 import { buildSystemPrompt, introDmText, nonOwnerRefusalText, readPromptSources } from "./prompt.js";
 import { FALLBACK_CLAUDE_PERMISSION_MODE, isClaudeBypassDisabled } from "./runtime/claude.js";
@@ -70,6 +71,15 @@ export const RECENT_MESSAGES_LIMIT = 15;
 export const RECENT_MESSAGE_MAX_CHARS = 400;
 /** Model turns a bot runs at once (each on a different conversation). */
 export const MAX_PARALLEL_TURNS = 2;
+/**
+ * Failed attempts to deliver ONE saved message before the bot stops trying.
+ * A body the server refuses (too long, malformed) is refused identically every
+ * time, so retrying it on every 2s poll only hammers the API and leaves the
+ * person with no answer and no explanation.
+ */
+export const RECOVERY_ATTEMPT_LIMIT = 5;
+/** What the person sees when a reply could not be delivered at all. */
+export const UNDELIVERABLE_REPLY_TEXT = "I wrote a reply but couldn't deliver it. Ask me again and I'll keep it shorter.";
 export const KICKOFF_MESSAGE_ID = "kickoff";
 /**
  * The environment a model turn's `hq` commands run in.
@@ -148,6 +158,23 @@ class FailureWindow {
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * A body posted as several parts where an early part got through and a later
+ * one did not: `delivered` is how many parts the person has, so a retry starts
+ * where it stopped instead of repeating what they already read.
+ */
+class PartialPostError extends Error {
+    parts;
+    delivered;
+    failure;
+    constructor(parts, delivered, failure) {
+        super(failure instanceof Error ? failure.message : String(failure));
+        this.parts = parts;
+        this.delivered = delivered;
+        this.failure = failure;
+        this.name = "PartialPostError";
+    }
+}
 export function preflightCreds(dir, config) {
     const identity = readBotCredsIdentity(dir);
     if (!identity)
@@ -549,16 +576,79 @@ export async function runBot(deps) {
         }
     };
     const failureReason = (outcome) => outcome.aborted ? STOPPED_BY_OWNER_REASON : `${runtime.id} stopped with an error: ${outcome.excerpt.slice(0, 160)}`;
-    const sendToTarget = (target, body, rootEventId) => {
+    const postOne = (target, body, rootEventId) => {
         const root = rootEventId ? { rootEventId } : {};
         return target.kind === "dm"
             ? api.sendDm({ toPersonUid: target.peerUid, body, ...root })
             : api.sendChannelMessage({ channelId: target.channelId, body, ...root });
     };
+    /**
+     * Post `parts` in order, starting at `from`. A failure throws a
+     * PartialPostError naming how many parts got through, so the caller can save
+     * exactly the remainder.
+     */
+    const sendParts = async (target, parts, from, rootEventId, onDelivered) => {
+        for (let i = Math.max(0, from); i < parts.length; i += 1) {
+            try {
+                await postOne(target, parts[i], rootEventId);
+            }
+            catch (err) {
+                throw new PartialPostError(parts, i, err);
+            }
+            onDelivered?.(i + 1);
+        }
+    };
+    /** Every outbound body goes through here, so nothing over the limit is ever posted whole. */
+    const sendToTarget = (target, body, rootEventId) => sendParts(target, splitBody(body), 0, rootEventId);
+    /**
+     * A `send` for one conversation that remembers how much of its last failed
+     * body got through, so the in-flight marker can record the remainder.
+     */
+    const trackingSend = (target, rootEventId) => {
+        const last = { value: null };
+        const send = async (body) => {
+            try {
+                await sendToTarget(target, body, rootEventId);
+                last.value = null;
+            }
+            catch (err) {
+                last.value = err instanceof PartialPostError && err.delivered > 0 ? { parts: err.parts, delivered: err.delivered } : null;
+                throw err;
+            }
+        };
+        const saved = (reply) => {
+            const parts = splitBody(reply);
+            const partial = last.value;
+            const sameBody = partial !== null && partial.parts.length === parts.length && partial.parts.every((p, i) => p === parts[i]);
+            return { reply, replyParts: parts, replyPartsDelivered: sameBody ? partial.delivered : 0 };
+        };
+        return { send, saved };
+    };
+    /** Close a marker out: clear the thinking reaction, ack the message, forget it. */
+    const closeMarker = async (marker, isKickoff) => {
+        if (marker.target.kind === "dm" && marker.reactionEventId) {
+            await api
+                .setReaction({ peerUid: marker.target.peerUid, messageId: marker.reactionEventId, emoji: THINKING_EMOJI }, false)
+                .catch(() => false);
+        }
+        if (!isKickoff) {
+            markProcessed(dir, marker.messageId, now().toISOString());
+            await api.ackInbox(config.agentUid, marker.messageId).catch((err) => {
+                log("warn", `ack for recovered ${marker.messageId} failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        clearInflight(dir, marker.messageId);
+    };
     /**
      * A turn that was cut off by a restart (or whose answer never got posted):
      * tell the person instead of running it again. Returns false when the post
      * failed, so the marker stays for the next try.
+     *
+     * The retry is bounded. Some bodies can never be delivered (the server
+     * refuses them however often they are sent), and re-sending one on every
+     * poll used to hammer the API for ever while the person saw nothing at all.
+     * After RECOVERY_ATTEMPT_LIMIT consecutive failures the bot posts one short
+     * apology it can actually deliver, closes the marker, and stops.
      */
     const recoverInflight = async (marker) => {
         const isKickoff = marker.messageId === KICKOFF_MESSAGE_ID;
@@ -566,26 +656,26 @@ export async function runBot(deps) {
             clearInflight(dir, marker.messageId);
             return true;
         }
-        const body = marker.reply ?? didNotFinishText(RESTARTED_REASON, (marker.progressPosted ?? 0) > 0);
+        const parts = marker.replyParts ?? splitBody(marker.reply ?? didNotFinishText(RESTARTED_REASON, (marker.progressPosted ?? 0) > 0));
+        const from = marker.replyParts ? Math.min(Math.max(0, marker.replyPartsDelivered ?? 0), parts.length) : 0;
         try {
-            await sendToTarget(marker.target, body, marker.rootEventId);
+            await sendParts(marker.target, parts, from, marker.rootEventId, (count) => patchInflight(dir, marker.messageId, { replyParts: parts, replyPartsDelivered: count }));
         }
         catch (err) {
-            log("warn", `could not tell the owner about unfinished ${marker.messageId}: ${err instanceof Error ? err.message : String(err)}`);
+            const reason = err instanceof Error ? err.message : String(err);
+            const attempt = (marker.recoveryFailures ?? 0) + 1;
+            if (attempt >= RECOVERY_ATTEMPT_LIMIT) {
+                log("warn", `gave up delivering the reply to ${marker.messageId} after ${attempt} attempts (${reason}); told the owner instead`);
+                await postOne(marker.target, UNDELIVERABLE_REPLY_TEXT, marker.rootEventId).catch(() => undefined);
+                await closeMarker(marker, isKickoff);
+                return true;
+            }
+            const delivered = err instanceof PartialPostError ? err.delivered : from;
+            patchInflight(dir, marker.messageId, { replyParts: parts, replyPartsDelivered: delivered, recoveryFailures: attempt });
+            log("warn", `could not tell the owner about unfinished ${marker.messageId} (attempt ${attempt}/${RECOVERY_ATTEMPT_LIMIT}): ${reason}`);
             return false;
         }
-        if (marker.target.kind === "dm" && marker.reactionEventId) {
-            await api
-                .setReaction({ peerUid: marker.target.peerUid, messageId: marker.reactionEventId, emoji: THINKING_EMOJI }, false)
-                .catch(() => false);
-        }
-        if (!isKickoff) {
-            markProcessed(dir, marker.messageId, now().toISOString());
-            await api.ackInbox(config.agentUid, marker.messageId).catch((err) => {
-                log("warn", `ack for recovered ${marker.messageId} failed: ${err instanceof Error ? err.message : String(err)}`);
-            });
-        }
-        clearInflight(dir, marker.messageId);
+        await closeMarker(marker, isKickoff);
         log("info", marker.reply ? `posted the saved reply for ${marker.messageId}` : `told the owner ${marker.messageId} did not finish (restart); not re-run`);
         return true;
     };
@@ -611,19 +701,20 @@ export async function runBot(deps) {
             }
         };
         const target = { kind: "dm", peerUid };
+        const { send, saved } = trackingSend(target);
         const { outcome, poster } = await runTurnWithProgress({
             marker: { messageId: KICKOFF_MESSAGE_ID, target, ...(thinking && introEventId ? { reactionEventId: introEventId } : {}) },
             prompt,
             sessionScope: "dm",
             tReceived,
-            send: (body) => api.sendDm({ toPersonUid: peerUid, body }),
+            send,
             // The intro already said the bot is starting, and the app shows it thinking.
             workingNotice: false,
         });
         await clearThinking();
         if (outcome.ok) {
             if (poster.postedCount === 0) {
-                patchInflight(dir, KICKOFF_MESSAGE_ID, { reply: outcome.reply });
+                patchInflight(dir, KICKOFF_MESSAGE_ID, saved(outcome.reply));
                 log("warn", "kickoff reply failed to send; it is posted on the next start");
                 return;
             }
@@ -640,7 +731,7 @@ export async function runBot(deps) {
             clearInflight(dir, KICKOFF_MESSAGE_ID);
             patchBotConfig(dir, { kickoffPendingSignIn: true });
             markSignInBroken(outcome.excerpt);
-            await tellSignInNeeded("dm", (body) => api.sendDm({ toPersonUid: peerUid, body }), true);
+            await tellSignInNeeded("dm", send, true);
             return;
         }
         if (readBotConfig(dir)?.kickoffPendingSignIn)
@@ -652,7 +743,7 @@ export async function runBot(deps) {
             ? `${didNotFinishText(failureReason(outcome), poster.postedCount > 0)} Send me any message and I'll pick up from there.`
             : `Sorry — I couldn't get started on my own (${runtime.id} failed: ${outcome.excerpt.slice(0, 160)}). Send me any message and I'll pick up from there, or check that ${runtime.id} is signed in on this computer.`;
         try {
-            await api.sendDm({ toPersonUid: peerUid, body });
+            await send(body);
             clearInflight(dir, KICKOFF_MESSAGE_ID);
         }
         catch {
@@ -747,7 +838,7 @@ export async function runBot(deps) {
         const sessionScope = target.kind === "room" ? target.sessionScope : "dm";
         const prompt = target.kind === "room" ? await buildRoomTurn(item, target, text) : text;
         const markerTarget = target.kind === "dm" ? { kind: "dm", peerUid: target.peerUid } : { kind: "room", channelId: target.channelId };
-        const send = (body) => sendToTarget(markerTarget, body, item.rootEventId);
+        const { send, saved } = trackingSend(markerTarget, item.rootEventId);
         const { outcome, poster } = await runTurnWithProgress({
             marker: {
                 messageId: id,
@@ -766,9 +857,11 @@ export async function runBot(deps) {
         });
         if (outcome.ok) {
             if (poster.postedCount === 0) {
-                // The work finished but nothing reached the chat: keep the answer so
-                // the next poll (or a restart) posts it instead of running again.
-                patchInflight(dir, id, { reply: outcome.reply });
+                // The work finished but nothing reached the chat: keep the answer —
+                // in the parts it will be posted as, and how many of them already got
+                // through — so the next poll (or a restart) delivers the remainder
+                // instead of running the turn again or repeating what was read.
+                patchInflight(dir, id, saved(outcome.reply));
                 await clearThinking();
                 log("warn", `reply to ${id} could not be posted; it is retried on the next poll`);
                 return;

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

@@ -0,0 +1,51 @@
+/**
+ * Can this Mac run the bot HQ has under this cloud record?
+ *
+ * One predicate, asked in every place that decides: `hq bot restore`, `hq bot
+ * adopt` and `hq bot list --remote`. They used to ask a weaker question than
+ * the runtime did — restore filtered on `computeMode` alone while
+ * `hq bot run`'s preflight compares BOTH `computeMode` and `botKind` against
+ * the bot.json it is about to run (`run.ts`, "is not a <kind> local bot") — so
+ * the two disagreed by construction.
+ *
+ * A real account showed what that cost: a company bot came back through
+ * `hq bot restore`, was counted as restored with `failed: 0` and `ok: true`,
+ * and then failed at every start, forever, with a LaunchAgent relaunching it
+ * at each login. Machine credentials, a state directory and a synced memory
+ * folder were created for a bot that could never run.
+ *
+ * The rule here is the runtime's rule, asked before anything is written: the
+ * bot must run on a computer (`computeMode: "local"`), and the kind this
+ * installation would run it as — from the settings the cloud kept for it — must
+ * be the kind the cloud record says it is. A company bot whose saved settings
+ * do not say "company" (the case above: no saved settings at all, so the adopt
+ * defaults to personal) is exactly the bot the runtime refuses, and it is now
+ * refused here instead, before it costs anything.
+ */
+import type { MyLocalBot } from "./api.js";
+/**
+ * Why a bot HQ lists for this account cannot run on this computer. Contract:
+ * the desktop app and the `--json` consumers switch on these values.
+ *
+ *   cloud-compute  the record runs in HQ Cloud, not on any computer
+ *   company-bot    it acts as a company member, and nothing here can run it
+ *                  as one — the runtime would refuse it at every start
+ *   kind-mismatch  anything else the runtime's identity preflight would refuse
+ */
+export type BotNotRunnableReason = "cloud-compute" | "company-bot" | "kind-mismatch";
+export interface RemoteBotRunnability {
+    runnable: boolean;
+    reason: BotNotRunnableReason | null;
+    /** One plain sentence for a person, naming no `agt_` uid. Null when runnable. */
+    message: string | null;
+}
+/** The record fields the decision reads — nothing else is consulted. */
+export type RemoteBotRunnabilityInput = Pick<MyLocalBot, "botKind" | "computeMode" | "localConfig">;
+/**
+ * The one answer restore, adopt and `list --remote` all use. `name` only
+ * shapes the sentence; the decision itself reads the record.
+ */
+export declare function remoteBotRunnability(bot: RemoteBotRunnabilityInput, name?: string): RemoteBotRunnability;
+/** True when this cloud record is a bot this computer can actually run. */
+export declare function isRemoteBotRunnableHere(bot: RemoteBotRunnabilityInput): boolean;
+//# sourceMappingURL=runnable.d.ts.map

package/dist/lib/bot/runnable.js

@@ -0,0 +1,65 @@
+/**
+ * Can this Mac run the bot HQ has under this cloud record?
+ *
+ * One predicate, asked in every place that decides: `hq bot restore`, `hq bot
+ * adopt` and `hq bot list --remote`. They used to ask a weaker question than
+ * the runtime did — restore filtered on `computeMode` alone while
+ * `hq bot run`'s preflight compares BOTH `computeMode` and `botKind` against
+ * the bot.json it is about to run (`run.ts`, "is not a <kind> local bot") — so
+ * the two disagreed by construction.
+ *
+ * A real account showed what that cost: a company bot came back through
+ * `hq bot restore`, was counted as restored with `failed: 0` and `ok: true`,
+ * and then failed at every start, forever, with a LaunchAgent relaunching it
+ * at each login. Machine credentials, a state directory and a synced memory
+ * folder were created for a bot that could never run.
+ *
+ * The rule here is the runtime's rule, asked before anything is written: the
+ * bot must run on a computer (`computeMode: "local"`), and the kind this
+ * installation would run it as — from the settings the cloud kept for it — must
+ * be the kind the cloud record says it is. A company bot whose saved settings
+ * do not say "company" (the case above: no saved settings at all, so the adopt
+ * defaults to personal) is exactly the bot the runtime refuses, and it is now
+ * refused here instead, before it costs anything.
+ */
+import { effectiveBotKind } from "./config.js";
+import { parseBotLocalConfig } from "./local-config.js";
+import { BOT_RESTORE_DEFAULTS } from "./local-config.js";
+/** The kind this installation would run the bot as, from the settings the cloud kept. */
+function kindHere(bot) {
+    const local = parseBotLocalConfig(bot.localConfig);
+    return effectiveBotKind({
+        kind: local?.kind ?? BOT_RESTORE_DEFAULTS.kind,
+        ...(local?.workerId ? { workerId: local.workerId } : {}),
+    });
+}
+function sentence(reason, name) {
+    const subject = name ? `"${name}"` : "That bot";
+    if (reason === "cloud-compute")
+        return `${subject} runs in the cloud, not on a computer, so there is nothing to bring back here.`;
+    if (reason === "company-bot") {
+        return `${subject} is a company bot: it runs in HQ Cloud for its company, not on this Mac, so there is nothing to bring back here.`;
+    }
+    return `${subject} is not set up as the kind of bot this computer can run, so there is nothing to bring back here.`;
+}
+/**
+ * The one answer restore, adopt and `list --remote` all use. `name` only
+ * shapes the sentence; the decision itself reads the record.
+ */
+export function remoteBotRunnability(bot, name) {
+    if ((bot.computeMode ?? "local") !== "local") {
+        return { runnable: false, reason: "cloud-compute", message: sentence("cloud-compute", name) };
+    }
+    const record = bot.botKind === "company" ? "company" : "personal";
+    const here = kindHere(bot);
+    if (record !== here) {
+        const reason = record === "company" ? "company-bot" : "kind-mismatch";
+        return { runnable: false, reason, message: sentence(reason, name) };
+    }
+    return { runnable: true, reason: null, message: null };
+}
+/** True when this cloud record is a bot this computer can actually run. */
+export function isRemoteBotRunnableHere(bot) {
+    return remoteBotRunnability(bot).runnable;
+}
+//# sourceMappingURL=runnable.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/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