@indigoai-us/hq-cli 5.109.16 → 5.110.0

package/dist/lib/bot/run.js

@@ -0,0 +1,787 @@
+/**
+ * The resident bot process: `hq bot run <name>` (local-bots US-003/US-004).
+ *
+ * - pid lock in ~/.hq/bots/<name>/pid; status.json is the observable state
+ * - refuses to start unless the creds file names this bot's agt_ AND the
+ *   server-side record is owned by the configured owner
+ * - heartbeat every 30s (POST /v1/agents/{uid}/heartbeat, agent JWT)
+ * - inbox poll every 5s: owner DMs go to ONE headless model turn (resumed by
+ *   session id); the reply is sent as the bot; the message is acked only after
+ *   the reply is sent; processed ids persist so a crash between reply and ack
+ *   never answers twice
+ * - non-owner DM senders get a fixed refusal and never reach the model
+ * - first start only: the intro DM, then (when bot.json has `kickoff`) ONE
+ *   model turn on that prompt as if the owner sent it, answered in the DM, so
+ *   a guided bot starts working without waiting for the owner to type
+ * - room items (channels / group chats): answered when the bot is @mentioned,
+ *   or when the owner posts in a small group (see room-policy.ts); claimed
+ *   first (first-claim-wins), one session per room, reply posted in the room
+ * - while a turn runs, each finished assistant message is posted as its own
+ *   message (progress.ts); turns have no time limit
+ * - every received message gets a reply: a turn that fails after the model
+ *   started (error, crash, owner stop, restart) posts one "did not finish"
+ *   message and is NOT run again — it may already have done outward things.
+ *   inflight.json marks the turn in progress so a restart can say so.
+ * - failures before the model starts (missing binary) retry with backoff;
+ *   5 model failures in 10 minutes → state `failed` and a clean exit (launchd
+ *   does not respawn a clean exit). Owner stops never count.
+ *
+ * Everything with a side effect is injectable so the loop is unit-testable.
+ */
+import { ownerContextBlock } from "./owner-context.js";
+import { randomUUID } from "node:crypto";
+import { hasPromotionHold } from "./promotion-hold.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fullJitterDelayMs } from "../mesh/live/backoff.js";
+import { acquirePidLock, defaultPidLockDeps, releasePidLock } from "../mesh/live/daemon/pid-lock.js";
+import { patchBotConfig, readBotConfig } from "./config.js";
+import { ensureBotSessionMeta } from "./company-bind.js";
+import { readBotCredsIdentity } from "./creds.js";
+import { isProcessed, markProcessed, readInboxState } from "./inbox-state.js";
+import { clearInflight, patchInflight, readInflight, writeInflight } from "./inflight.js";
+import { ProgressPoster } from "./progress.js";
+import { createBotLogger } from "./log.js";
+import { buildSystemPrompt, introDmText, nonOwnerRefusalText, readPromptSources } from "./prompt.js";
+import { FALLBACK_CLAUDE_PERMISSION_MODE, isClaudeBypassDisabled } from "./runtime/claude.js";
+import { runRuntimeTurn, RuntimeError } from "./runtime/index.js";
+import { isDmItem, resolveReplyTarget } from "./room-policy.js";
+import { clearBotSession, readBotSession, writeBotSession } from "./session.js";
+import { defaultBotStatus, patchBotStatus, readBotStatus } from "./status.js";
+export const INBOX_POLL_INTERVAL_MS = 2_000;
+export const HEARTBEAT_INTERVAL_MS = 30_000;
+export const FAILURE_WINDOW_MS = 10 * 60 * 1000;
+export const FAILURE_LIMIT = 5;
+export const MAX_ATTEMPTS_PER_MESSAGE = 3;
+export const THINKING_EMOJI = "👀";
+export const ROOM_THINKING_STATUS = "is thinking…";
+export const RECENT_MESSAGES_LIMIT = 15;
+export const RECENT_MESSAGE_MAX_CHARS = 400;
+export const KICKOFF_MESSAGE_ID = "kickoff";
+/** The core worker HQ's setup bot runs. */
+export const SETUP_WORKER_ID = "setup";
+/** The one message a person gets when a turn on their message did not finish. */
+export function didNotFinishText(reason, progressPosted) {
+    const r = reason.trim().replace(/[.\s]+$/, "");
+    return `I didn't finish that — ${r}.${progressPosted ? " The messages above show how far I got." : ""}`;
+}
+/** Owner stop, `hq bot stop` or `hq bot restart`: all arrive as the same signal. */
+export const STOPPED_BY_OWNER_REASON = "I was stopped before I was done";
+export const RESTARTED_REASON = "I was restarted while I was working on it";
+class FailureWindow {
+    windowMs;
+    limit;
+    stamps = [];
+    constructor(windowMs, limit) {
+        this.windowMs = windowMs;
+        this.limit = limit;
+    }
+    record(nowMs) {
+        this.stamps.push(nowMs);
+        while (this.stamps.length && nowMs - this.stamps[0] > this.windowMs)
+            this.stamps.shift();
+        return this.stamps.length;
+    }
+    count(nowMs) {
+        while (this.stamps.length && nowMs - this.stamps[0] > this.windowMs)
+            this.stamps.shift();
+        return this.stamps.length;
+    }
+    exceeded(nowMs) {
+        return this.count(nowMs) >= this.limit;
+    }
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function preflightCreds(dir, config) {
+    const identity = readBotCredsIdentity(dir);
+    if (!identity)
+        return `No machine credentials for bot "${config.name}" — run: hq bot create ${config.name}`;
+    if (identity.entityUid !== config.agentUid) {
+        return `Credentials in ${dir} belong to ${identity.entityUid}, not this bot (${config.agentUid}); refusing to start`;
+    }
+    return null;
+}
+export async function runBot(deps) {
+    const now = deps.now ?? (() => new Date());
+    const sleep = deps.sleep ?? defaultSleep;
+    const log = deps.log ?? createBotLogger(deps.dir, now);
+    const pid = deps.pid ?? process.pid;
+    const { dir, config, api, runtime } = deps;
+    const runTurn = deps.runTurn ?? ((rt, input) => runRuntimeTurn(rt, input));
+    const inboxIntervalMs = deps.inboxIntervalMs ?? INBOX_POLL_INTERVAL_MS;
+    const heartbeatIntervalMs = deps.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const fallback = () => defaultBotStatus(pid, config.runtime, now);
+    const setStatus = (patch) => patchBotStatus(dir, patch, fallback, now);
+    let state = "starting";
+    let stopping = false;
+    /** Aborts the model turn in progress (owner stop). */
+    let currentTurn = null;
+    let resolveDone;
+    const done = new Promise((r) => (resolveDone = r));
+    // Only override isProcessAlive when a caller injected one: spreading an
+    // explicit `undefined` over defaultPidLockDeps() would erase the default and
+    // crash the daemon at startup ("deps.isProcessAlive is not a function").
+    // Model turns run in the owner's HQ root so every skill, policy and `hq`
+    // command resolves the way it does for the owner. (A scratch cwd was tried
+    // on 2026-09-11 for speed; it cost the bot its skills and memory writes.)
+    const turnCwd = config.hqRoot;
+    // HQ's setup bot is a guided conversation: no "working on it" filler between steps.
+    const isSetupBot = config.workerId === SETUP_WORKER_ID;
+    const lockDeps = defaultPidLockDeps({
+        pid,
+        ...(deps.isProcessAlive ? { isProcessAlive: deps.isProcessAlive } : {}),
+    });
+    const finish = async (final, code, reason) => {
+        if (state === "stopped" || state === "failed")
+            return;
+        state = final;
+        setStatus({ state: final, ...(final === "failed" ? { lastError: reason.slice(0, 400) } : {}) });
+        log(final === "failed" ? "error" : "info", `bot ${final}: ${reason}`);
+        if (!deps.skipPidLock)
+            releasePidLock(dir, lockDeps);
+        resolveDone(final);
+        exit(code);
+    };
+    // ── Preflight: creds, pid lock, owner verification ─────────────────────────
+    const credsProblem = preflightCreds(dir, config);
+    if (credsProblem) {
+        setStatus({ state: "failed", lastError: credsProblem, pid });
+        log("error", credsProblem);
+        resolveDone("failed");
+        exit(0);
+        return { stop: async () => { }, done, status: () => null };
+    }
+    if (config.enabled === false) {
+        setStatus({ state: "stopped", pid });
+        log("info", "bot is disabled (hq bot start to enable)");
+        resolveDone("stopped");
+        exit(0);
+        return { stop: async () => { }, done, status: () => null };
+    }
+    if (!deps.skipPidLock) {
+        const lock = acquirePidLock(dir, lockDeps);
+        if (!lock.ok) {
+            const msg = `bot "${config.name}" is already running (pid ${lock.owner.pid})`;
+            log("warn", msg);
+            resolveDone("stopped");
+            exit(0);
+            return { stop: async () => { }, done, status: () => null };
+        }
+    }
+    if (hasPromotionHold(dir)) {
+        await finish("stopped", 0, "local bot held for cloud promotion");
+        return { stop: async () => { }, done, status: () => null };
+    }
+    setStatus({ ...fallback(), pid, state: "starting", canDrainForPromotion: false });
+    log("info", `starting ${config.name} (${config.runtime}) as ${config.agentUid} for ${config.ownerUid}`);
+    try {
+        const record = await api.getAgent(config.agentUid);
+        // Promotion keeps the identity and owner. Ownership alone must not let
+        // an old local installation start consuming the cloud bot's inbox.
+        if (record.uid !== config.agentUid || record.computeMode !== "local" || record.botKind !== "personal") {
+            await finish("failed", 0, `identity ${config.agentUid} is not a personal local bot; this installation cannot run it`);
+            return { stop: async () => { }, done, status: () => null };
+        }
+        const owner = record.ownerUid ?? null;
+        if (owner !== config.ownerUid) {
+            await finish("failed", 0, `identity ${config.agentUid} is owned by ${owner ?? "nobody"}, not ${config.ownerUid}`);
+            return { stop: async () => { }, done, status: () => null };
+        }
+    }
+    catch (err) {
+        await finish("failed", 0, `could not verify bot identity: ${err instanceof Error ? err.message : String(err)}`);
+        return { stop: async () => { }, done, status: () => null };
+    }
+    // ── System prompt ──────────────────────────────────────────────────────────
+    const systemPrompt = deps.systemPromptOverride ??
+        buildSystemPrompt({
+            botName: config.name,
+            agentUid: config.agentUid,
+            ownerUid: config.ownerUid,
+            hqRoot: config.hqRoot,
+            workerDir: config.workerDir,
+            workerSource: config.workerSource,
+            workerId: config.workerId,
+            companySlug: config.companySlug,
+            memoryDir: config.memoryDir,
+            sources: readPromptSources(config.hqRoot, config.workerDir, undefined, {
+                memoryDir: config.memoryDir,
+                workerSource: config.workerSource,
+                companySlug: config.companySlug,
+            }),
+        });
+    const systemPromptFile = path.join(dir, "system-prompt.md");
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(systemPromptFile, systemPrompt, { mode: 0o600 });
+    if (hasPromotionHold(dir)) {
+        await finish("stopped", 0, "local bot held for cloud promotion");
+        return { stop: async () => { }, done, status: () => null };
+    }
+    state = "running";
+    setStatus({ state: "running", lastActivityAt: now().toISOString() });
+    log("info", "running");
+    // Read before the kickoff can write its own marker: whatever is here now was
+    // left by a previous run that was cut off mid-turn.
+    const leftover = readInflight(dir);
+    // ── Intro DM (once) ────────────────────────────────────────────────────────
+    // The kickoff turn is tied to the intro: it runs only in the start that sent
+    // the intro, so introSentAt (persisted before the turn) guarantees it never
+    // runs again on a restart.
+    let kickoffAfterIntro = null;
+    if (!config.introSentAt) {
+        try {
+            const sent = await api.sendDm({ toPersonUid: config.ownerUid, body: introDmText(config.name, config.runtime, config.intro) });
+            patchBotConfig(dir, { introSentAt: now().toISOString() });
+            log("info", "intro DM sent to owner");
+            if (config.kickoff?.trim())
+                kickoffAfterIntro = { ...(sent?.eventId ? { introEventId: sent.eventId } : {}) };
+        }
+        catch (err) {
+            log("warn", `intro DM failed (will retry next start): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── Heartbeat loop ─────────────────────────────────────────────────────────
+    const failures = new FailureWindow(FAILURE_WINDOW_MS, FAILURE_LIMIT);
+    let modelHealth = "ok";
+    const heartbeatLoop = (async () => {
+        while (!stopping && state === "running") {
+            try {
+                // The server's component vocabulary is the fleet one (sync/model/task…);
+                // runtime → model, inbox → task, sync → sync.
+                await api.heartbeat(config.agentUid, { model: modelHealth, task: "ok", sync: "ok" });
+                setStatus({ lastHeartbeatAt: now().toISOString(), lastHeartbeatOk: true });
+            }
+            catch (err) {
+                setStatus({ lastHeartbeatAt: now().toISOString(), lastHeartbeatOk: false });
+                log("warn", `heartbeat failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            await sleep(heartbeatIntervalMs);
+        }
+    })();
+    // ── Inbox loop ─────────────────────────────────────────────────────────────
+    const attempts = new Map();
+    /** Build the user turn for a room trigger: header + recent transcript + the message. */
+    const buildRoomTurn = async (item, target, text) => {
+        const name = (item.channelName ?? "").trim() || target.channelId;
+        const members = typeof item.memberCount === "number" ? `${item.memberCount} members` : "group";
+        const from = (item.fromDisplayName ?? "").trim() || item.fromPersonUid || "unknown";
+        const header = `[#${name} · ${members} · from ${from}]`;
+        let recent = "";
+        try {
+            const rows = await api.fetchChannelMessages(target.channelId, RECENT_MESSAGES_LIMIT);
+            const lines = rows
+                .filter((m) => !(item.eventId && m.eventId === item.eventId))
+                .map((m) => `- ${m.fromDisplayName ?? m.fromPersonUid ?? "someone"}: ${m.body.replace(/\s+/g, " ").slice(0, RECENT_MESSAGE_MAX_CHARS)}`);
+            if (lines.length > 0)
+                recent = `Recent messages:\n${lines.join("\n")}\n\n`;
+        }
+        catch (err) {
+            log("warn", `recent messages for ${target.channelId} unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return `${header}\n${recent}${from}: ${text}`;
+    };
+    /**
+     * One model turn in the given session scope: company bind, the Claude
+     * bypass → auto fallback, and the session file update on success. Throws
+     * the runtime error on failure (callers account for it via recordTurnFailure).
+     */
+    const executeTurn = async (prompt, sessionScope, tReceived, stream = {}) => {
+        const session = readBotSession(dir, config.runtime, sessionScope);
+        // Company bind (worker-sourced bots): HQ's company hooks key on
+        // workspace/sessions/<sid>/meta.yaml, so the session id is fixed up front
+        // and the meta file written before every turn (idempotent; covers session
+        // resets). Claude gets the full hook set via its payload session id;
+        // Codex/Grok only see HQ_SESSION_ID.
+        const sid = session?.sessionId ?? randomUUID();
+        let bind = {};
+        if (config.companySlug) {
+            try {
+                ensureBotSessionMeta(config.hqRoot, sid, config.companySlug, undefined, now);
+                bind = { newSessionId: sid, env: { ...process.env, HQ_SESSION_ID: sid } };
+            }
+            catch (err) {
+                log("warn", `company bind failed for ${config.companySlug}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Only the owner's own DM session (DMs and the kickoff). Room prompts must
+        // keep their [#channel …] header first, and a room turn can be triggered
+        // by other people, who must not be handed the owner's companies.
+        if (deps.ownerContext && sessionScope === "dm") {
+            try {
+                prompt = `${ownerContextBlock(await deps.ownerContext(), config.agentUid)}\n\n${prompt}`;
+            }
+            catch (err) {
+                log("warn", `owner context unavailable: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const tTurnStart = now().getTime();
+        // Model and thinking level are read fresh each turn, so a change from the
+        // bot's profile (`hq bot set`) applies to the next message without a restart.
+        const live = readBotConfig(dir) ?? config;
+        const attemptTurn = (permissionMode) => runTurn(runtime, {
+            prompt,
+            systemPrompt,
+            systemPromptFile,
+            cwd: turnCwd,
+            hqRoot: config.hqRoot,
+            autoApprove: config.autoApprove !== false,
+            ...(permissionMode ? { permissionMode } : {}),
+            sessionId: session?.sessionId,
+            ...(live.model ? { model: live.model } : {}),
+            ...(live.effort ? { effort: live.effort } : {}),
+            ...bind,
+            ...stream,
+        });
+        let turn;
+        const remembered = readStatus()?.claudePermissionMode;
+        try {
+            turn = await attemptTurn(remembered);
+        }
+        catch (err) {
+            // Claude Code can have bypassPermissions switched off by managed
+            // settings. Fall back to "auto" (no prompts, classifier-approved) once
+            // and remember it, so the bot keeps working without an operator.
+            const detail = err instanceof RuntimeError ? `${err.message}\n${err.stderrExcerpt}` : err instanceof Error ? err.message : String(err);
+            const aborted = err instanceof RuntimeError && err.aborted;
+            if (aborted || runtime.id !== "claude" || remembered || config.autoApprove === false || !isClaudeBypassDisabled(detail)) {
+                throw Object.assign(err instanceof Error ? err : new Error(String(err)), { resumedSession: Boolean(session) });
+            }
+            log("warn", `bypassPermissions is disabled for this Claude Code; falling back to permission mode "${FALLBACK_CLAUDE_PERMISSION_MODE}"`);
+            setStatus({ claudePermissionMode: FALLBACK_CLAUDE_PERMISSION_MODE });
+            try {
+                turn = await attemptTurn(FALLBACK_CLAUDE_PERMISSION_MODE);
+            }
+            catch (retryErr) {
+                throw Object.assign(retryErr instanceof Error ? retryErr : new Error(String(retryErr)), { resumedSession: Boolean(session) });
+            }
+        }
+        modelHealth = "ok";
+        log("info", `model turn done in ${Math.round((now().getTime() - tTurnStart) / 1000)}s (${Math.round((tTurnStart - tReceived) / 1000)}s before it)`);
+        if (turn.sessionId) {
+            writeBotSession(dir, {
+                v: 1,
+                runtime: config.runtime,
+                sessionId: turn.sessionId,
+                turns: (session?.turns ?? 0) + 1,
+                updatedAt: now().toISOString(),
+            }, sessionScope);
+        }
+        return turn;
+    };
+    /** Failure bookkeeping shared by every model turn: window, health, status, log, stale session. */
+    const recordTurnFailure = (err, sessionScope) => {
+        const excerpt = err instanceof RuntimeError ? err.stderrExcerpt : err instanceof Error ? err.message : String(err);
+        const count = failures.record(now().getTime());
+        modelHealth = count >= FAILURE_LIMIT ? "failed" : "degraded";
+        setStatus({ restarts: (readStatus()?.restarts ?? 0) + 1, recentFailures: count, lastError: excerpt.slice(0, 400) });
+        log("error", `model turn failed (${count}/${FAILURE_LIMIT} in window): ${excerpt}`);
+        // A resumed session that no longer exists must not poison every turn.
+        const resumed = Boolean(err?.resumedSession);
+        if (resumed && /session|resume|not found/i.test(excerpt))
+            clearBotSession(dir, sessionScope);
+        return { excerpt, count };
+    };
+    /**
+     * One model turn that posts its in-between messages as it goes. Writes the
+     * in-flight marker first; the caller clears it once the message is answered.
+     */
+    const runTurnWithProgress = async (args) => {
+        const { messageId } = args.marker;
+        writeInflight(dir, { v: 1, ...args.marker, startedAt: now().toISOString() });
+        let running = true;
+        let posted = 0;
+        const poster = new ProgressPoster({
+            ...deps.progress,
+            ...(args.workingNotice === false ? { workingNoticeMs: 0 } : {}),
+            send: async (body) => {
+                try {
+                    await args.send(body);
+                }
+                catch (err) {
+                    log("warn", `post for ${messageId} failed: ${err instanceof Error ? err.message : String(err)}`);
+                    return false;
+                }
+                posted += 1;
+                patchInflight(dir, messageId, { progressPosted: posted });
+                if (running && args.afterProgressPost)
+                    await args.afterProgressPost().catch(() => undefined);
+                return true;
+            },
+        });
+        const controller = new AbortController();
+        currentTurn = controller;
+        poster.start();
+        try {
+            const turn = await executeTurn(args.prompt, args.sessionScope, args.tReceived, {
+                onEvent: (event) => {
+                    if (event.kind === "message")
+                        poster.message(event.text);
+                },
+                signal: controller.signal,
+            });
+            running = false;
+            await poster.finish(turn.text);
+            return { outcome: { ok: true, reply: turn.text.trim() || "(no reply)" }, poster };
+        }
+        catch (err) {
+            running = false;
+            await poster.abandon();
+            const excerpt = err instanceof RuntimeError ? err.stderrExcerpt : err instanceof Error ? err.message : String(err);
+            const aborted = (err instanceof RuntimeError && err.aborted) || controller.signal.aborted;
+            const started = !(err instanceof RuntimeError) || err.started;
+            return { outcome: { ok: false, started, aborted, excerpt, error: err }, poster };
+        }
+        finally {
+            if (currentTurn === controller)
+                currentTurn = null;
+        }
+    };
+    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 root = rootEventId ? { rootEventId } : {};
+        return target.kind === "dm"
+            ? api.sendDm({ toPersonUid: target.peerUid, body, ...root })
+            : api.sendChannelMessage({ channelId: target.channelId, body, ...root });
+    };
+    /**
+     * 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.
+     */
+    const recoverInflight = async (marker) => {
+        const isKickoff = marker.messageId === KICKOFF_MESSAGE_ID;
+        if (!isKickoff && isProcessed(readInboxState(dir), marker.messageId)) {
+            clearInflight(dir, marker.messageId);
+            return true;
+        }
+        const body = marker.reply ?? didNotFinishText(RESTARTED_REASON, (marker.progressPosted ?? 0) > 0);
+        try {
+            await sendToTarget(marker.target, body, marker.rootEventId);
+        }
+        catch (err) {
+            log("warn", `could not tell the owner about unfinished ${marker.messageId}: ${err instanceof Error ? err.message : String(err)}`);
+            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);
+        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;
+    };
+    /**
+     * First-start kickoff: ONE model turn on config.kickoff in the owner DM
+     * session, as if the owner had sent it, answered as a DM (with its
+     * in-between messages). The thinking reaction goes on the intro message
+     * (there is no owner message to mark). A failure never crashes the loop.
+     */
+    const runKickoff = async (introEventId) => {
+        const prompt = (config.kickoff ?? "").trim();
+        if (!prompt || stopping || state !== "running")
+            return;
+        const peerUid = config.ownerUid;
+        const tReceived = now().getTime();
+        log("info", `kickoff turn starting (${prompt.length} chars)`);
+        const thinking = introEventId
+            ? await api.setReaction({ peerUid, messageId: introEventId, emoji: THINKING_EMOJI }, true).catch(() => false)
+            : false;
+        const clearThinking = async () => {
+            if (thinking && introEventId) {
+                await api.setReaction({ peerUid, messageId: introEventId, emoji: THINKING_EMOJI }, false).catch(() => false);
+            }
+        };
+        const target = { kind: "dm", peerUid };
+        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 }),
+            // 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 });
+                log("warn", "kickoff reply failed to send; it is posted on the next start");
+                return;
+            }
+            clearInflight(dir, KICKOFF_MESSAGE_ID);
+            const st = readStatus();
+            setStatus({ repliesSent: (st?.repliesSent ?? 0) + 1, lastActivityAt: now().toISOString() });
+            log("info", `kickoff reply sent (${outcome.reply.length} chars)`);
+            return;
+        }
+        let count = 0;
+        if (!outcome.aborted)
+            count = recordTurnFailure(outcome.error, "dm").count;
+        const body = outcome.started && (outcome.aborted || poster.postedCount > 0)
+            ? `${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 });
+            clearInflight(dir, KICKOFF_MESSAGE_ID);
+        }
+        catch {
+            /* the marker stays: the next start says it did not finish */
+        }
+        log("error", `kickoff turn ${outcome.aborted ? "stopped by the owner" : `failed (${count}/${FAILURE_LIMIT} in window)`}; not retried`);
+        if (!outcome.aborted && failures.exceeded(now().getTime())) {
+            await finish("failed", 0, `${FAILURE_LIMIT} model failures in 10 minutes; last: ${outcome.excerpt}`);
+        }
+    };
+    const handleItem = async (item) => {
+        const id = item.messageId;
+        const inboxState = readInboxState(dir);
+        if (isProcessed(inboxState, id)) {
+            // Replied before a crash; only the ack was lost.
+            await api.ackInbox(config.agentUid, id);
+            clearInflight(dir, id);
+            log("info", `acked already-processed ${id}`);
+            return;
+        }
+        // A turn on this message already started once and was cut off: say so,
+        // never run it again.
+        const inflight = readInflight(dir);
+        if (inflight?.messageId === id) {
+            await recoverInflight(inflight);
+            return;
+        }
+        const sender = item.fromPersonUid ?? "";
+        if (isDmItem(item) && sender !== config.ownerUid) {
+            // Never reaches the model. Best-effort refusal (a stranger → bot DM is
+            // 404 on the server by design), then ack so it never comes back.
+            try {
+                if (sender)
+                    await api.sendDm({ toPersonUid: sender, body: nonOwnerRefusalText(config.name) });
+            }
+            catch {
+                /* refusal delivery is best-effort */
+            }
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            log("info", `refused non-owner DM ${id}`);
+            return;
+        }
+        const target = resolveReplyTarget(item, config);
+        if (!target) {
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            log("info", `ignored inbox item ${id} (${item.channel || "dm"}${item.channelScope ? ` ${item.channelScope}` : ""}, not addressed to me)`);
+            return;
+        }
+        const text = (item.text ?? "").trim();
+        if (!text) {
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            return;
+        }
+        const attempt = (attempts.get(id) ?? 0) + 1;
+        attempts.set(id, attempt);
+        const reactionId = item.eventId ?? id;
+        const tReceived = now().getTime();
+        const where = target.kind === "room" ? `room ${target.channelId}` : "dm";
+        log("info", `received ${id} (${text.length} chars, ${where})`);
+        // Rooms: an UNMENTIONED responder (owner's plain message in a group)
+        // claims first so the owner's several bots produce one answer, not one
+        // each. A bot that was @mentioned never claims — it was asked by name and
+        // must answer even if a sibling bot was faster. The same claimer
+        // re-acquires on a retry (server lease), so the claim is safe to repeat
+        // when a failed turn leaves the item un-acked.
+        if (target.kind === "room" && !target.mentioned) {
+            const claimed = await api.claimChannelUnit(target.channelId, target.unitId);
+            if (!claimed) {
+                markProcessed(dir, id, now().toISOString());
+                await api.ackInbox(config.agentUid, id);
+                attempts.delete(id);
+                log("info", `skipped ${id}: claimed by another responder`);
+                return;
+            }
+        }
+        // Thinking indicator: DMs use a reaction; rooms use the ephemeral
+        // agent-status wake (cleared client-side by a post, so it is re-posted
+        // after each in-between message). It stays on until the turn ends.
+        const thinking = target.kind === "dm"
+            ? await api.setReaction({ peerUid: target.peerUid, messageId: reactionId, emoji: THINKING_EMOJI }, true)
+            : false;
+        if (target.kind === "room")
+            await api.postAgentStatus(target.channelId, ROOM_THINKING_STATUS, target.rootEventId);
+        const clearThinking = async () => {
+            if (thinking && target.kind === "dm") {
+                await api.setReaction({ peerUid: target.peerUid, messageId: reactionId, emoji: THINKING_EMOJI }, false);
+            }
+        };
+        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 { outcome, poster } = await runTurnWithProgress({
+            marker: {
+                messageId: id,
+                target: markerTarget,
+                ...(item.rootEventId ? { rootEventId: item.rootEventId } : {}),
+                ...(thinking ? { reactionEventId: reactionId } : {}),
+            },
+            prompt,
+            sessionScope,
+            tReceived,
+            send,
+            workingNotice: !isSetupBot,
+            ...(target.kind === "room"
+                ? { afterProgressPost: () => api.postAgentStatus(target.channelId, ROOM_THINKING_STATUS, target.rootEventId) }
+                : {}),
+        });
+        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 });
+                await clearThinking();
+                log("warn", `reply to ${id} could not be posted; it is retried on the next poll`);
+                return;
+            }
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            clearInflight(dir, id);
+            attempts.delete(id);
+            await clearThinking();
+            const st = readStatus();
+            setStatus({ repliesSent: (st?.repliesSent ?? 0) + 1, lastActivityAt: now().toISOString() });
+            log("info", `replied to ${id} (${outcome.reply.length} chars, ${where}, ${poster.postedCount} post${poster.postedCount === 1 ? "" : "s"})`);
+            return;
+        }
+        await clearThinking();
+        if (!outcome.started) {
+            // The model never ran (e.g. the binary is missing): nothing happened
+            // outside this Mac, so retrying is safe.
+            clearInflight(dir, id);
+            const { excerpt } = recordTurnFailure(outcome.error, sessionScope);
+            if (failures.exceeded(now().getTime())) {
+                await finish("failed", 0, `${FAILURE_LIMIT} model failures in 10 minutes; last: ${excerpt}`);
+                return;
+            }
+            if (attempt >= MAX_ATTEMPTS_PER_MESSAGE) {
+                try {
+                    await send(`Sorry — I couldn't answer that one (${runtime.id} kept failing: ${excerpt.slice(0, 160)}). Try again in a bit, or check that ${runtime.id} is signed in on this computer.`);
+                }
+                catch {
+                    /* best-effort */
+                }
+                markProcessed(dir, id, now().toISOString());
+                await api.ackInbox(config.agentUid, id);
+                attempts.delete(id);
+                return;
+            }
+            await sleep(fullJitterDelayMs(failures.count(now().getTime()), { random: deps.random }));
+            return; // leave un-acked; retried on the next poll
+        }
+        // The model started: it may already have done things, so never re-run.
+        if (!outcome.aborted)
+            recordTurnFailure(outcome.error, sessionScope);
+        try {
+            await send(didNotFinishText(failureReason(outcome), poster.postedCount > 0));
+        }
+        catch (err) {
+            // Leave it un-acked with the marker: the next poll says it did not finish.
+            log("warn", `could not post "did not finish" for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        markProcessed(dir, id, now().toISOString());
+        await api.ackInbox(config.agentUid, id);
+        clearInflight(dir, id);
+        attempts.delete(id);
+        log("error", `turn on ${id} ${outcome.aborted ? "stopped by the owner" : "failed"} after it started; told the owner, not re-run`);
+        if (!outcome.aborted && failures.exceeded(now().getTime())) {
+            await finish("failed", 0, `${FAILURE_LIMIT} model failures in 10 minutes; last: ${outcome.excerpt}`);
+        }
+    };
+    // The kickoff runs alongside the heartbeat, before the first inbox poll, so
+    // an owner message sent meanwhile is answered after it in the same session.
+    const kickoff = kickoffAfterIntro
+        ? runKickoff(kickoffAfterIntro.introEventId).catch((err) => {
+            log("error", `kickoff turn crashed: ${err instanceof Error ? err.message : String(err)}`);
+        })
+        : Promise.resolve();
+    const inboxLoop = (async () => {
+        // A turn cut off by the last restart is reported before anything new runs.
+        if (leftover) {
+            try {
+                await recoverInflight(leftover);
+            }
+            catch (err) {
+                log("warn", `recovering ${leftover.messageId} failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        await kickoff;
+        while (!stopping && state === "running") {
+            if (hasPromotionHold(dir))
+                break;
+            try {
+                const items = await api.pullInbox(config.agentUid);
+                setStatus({ lastInboxPollAt: now().toISOString() });
+                for (const item of items) {
+                    if (stopping || state !== "running" || hasPromotionHold(dir))
+                        break;
+                    try {
+                        await handleItem(item);
+                    }
+                    catch (err) {
+                        log("warn", `inbox item ${item.messageId} failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            }
+            catch (err) {
+                log("warn", `inbox poll failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (stopping || state !== "running")
+                break;
+            await sleep(inboxIntervalMs);
+        }
+    })();
+    function readStatus() {
+        return readBotStatus(dir);
+    }
+    const stop = async (mode = "abort") => {
+        if (stopping) {
+            if (mode === "abort")
+                currentTurn?.abort();
+            return;
+        }
+        stopping = true;
+        // End the turn in progress; its message gets "did not finish", not silence.
+        // Promotion instead drains that turn, including its reply and ACK, before
+        // the coordinator snapshots memory and starts the cloud consumer.
+        if (mode === "abort")
+            currentTurn?.abort();
+        await Promise.allSettled([heartbeatLoop, inboxLoop]);
+        await finish("stopped", 0, mode === "drain" ? "promotion drain completed" : "stop requested");
+    };
+    const onSignal = () => {
+        void stop();
+    };
+    const events = deps.processEvents ?? process;
+    events.once("SIGTERM", onSignal);
+    events.once("SIGINT", onSignal);
+    events.once("SIGUSR2", () => { void stop("drain"); });
+    void inboxLoop.then(() => { if (hasPromotionHold(dir))
+        void stop("drain"); });
+    setStatus({ canDrainForPromotion: true });
+    void Promise.allSettled([heartbeatLoop, inboxLoop]).then(() => {
+        if (state === "running")
+            void finish("stopped", 0, "loops ended");
+    });
+    return { stop, done, status: readStatus };
+}
+//# sourceMappingURL=run.js.map