@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/bot/run.js

@@ -0,0 +1,1881 @@
+/**
+ * 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 2s: 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
+ * - any correspondent can message the bot; each sender has a separate session
+ * - 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
+ * - job items (channel "job"): a run the cloud fired on an EventBridge
+ *   schedule. Nothing is scheduled on this computer. The run is one model turn
+ *   in its own session (one per jobId), reported in the owner's DM with a
+ *   "scheduled job" header through the same split/recovery path as every other
+ *   reply, and reported back to the cloud EXACTLY ONCE — nothing else clears
+ *   the job's in-progress flag. A run whose staleAfter has passed still runs,
+ *   once, labelled a catch-up; older pending runs of the same job are reported
+ *   skipped-precondition instead of piling up.
+ * - delivered room items (channels / group chats) are eligible for replies; claimed
+ *   first (first-claim-wins), one session per room, reply posted in the room
+ * - conversations run side by side: up to MAX_PARALLEL_TURNS turns at once,
+ *   one lane per model session (one DM correspondent, or one room). Messages
+ *   in the same lane run in order, so a session is never resumed by two turns
+ *   at once and a thread's answers never arrive out of sequence.
+ * - 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.
+ * - a turn that fails because the coding tool's sign-in no longer works
+ *   (runtime-sign-in.ts) is not a failure of the message: the bot says once
+ *   per conversation that it needs a sign-in, keeps the message un-acked,
+ *   holds new turns, and tries again every SIGN_IN_RETRY_MS (and at once
+ *   after a restart). A turn that works clears it.
+ * - 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 { BotApiError } from "./api.js";
+import { effectiveBotCompanies, effectiveBotKind, patchBotConfig, readBotConfig, resolveBotMemoryDir, SETUP_BOT_WORKER_ID } 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, readInflightTurns, writeInflight } from "./inflight.js";
+import { containsNoReplySentinel, ProgressPoster, } from "./progress.js";
+import { splitBody } from "./split.js";
+import { createBotLogger } from "./log.js";
+import { buildSystemPrompt, introDmText, readPromptSources } from "./prompt.js";
+import { loadSetupExplainer, patchSetupIntroState, readSetupIntroState, readSetupProgressIntro, replyOffersExplain, SETUP_EXPLAINED_NOTE, setupExplainDue, } from "./setup-explain.js";
+import { FALLBACK_CLAUDE_PERMISSION_MODE, isClaudeBypassDisabled } from "./runtime/claude.js";
+import { runRuntimeTurn, RuntimeError } from "./runtime/index.js";
+import { botAttachmentsDir, dmSessionScope } from "./paths.js";
+import { attachmentTurnBlock, downloadTurnAttachments } from "./attachments.js";
+import { inboxEntryAttachments } from "../agent-kit/inbox-state.js";
+import { isAgentSender, isDmItem, isMetaNonReply, resolveReplyTarget } from "./room-policy.js";
+import { buildJobTurnPrompt, isCatchUpRun, isJobItem, jobReportHeader, jobRunOutput, machineTimeZone, planJobRuns, stripJobHeader, SUPERSEDED_DISPOSITION } from "./job-run.js";
+import { botJobQuietOptionEnabled } from "./job-quiet-flag.js";
+import { clearPendingJobCompletion, isCompletionDue, isCompletionExpired, isCompletionForOtherAgent, readPendingJobCompletions, recordPendingJobCompletion } from "./job-completions.js";
+import { isRuntimeSignInFailure, SIGN_IN_RETRY_MS, signInNeededText } from "./runtime-sign-in.js";
+import { HQ_BOT_AGENT_UID_ENV } from "../../commands/onboard-bot-membership.js";
+import { captureHeartbeatIdentityMismatch, identityMismatchMessage, isHeartbeatIdentityMismatch, } from "../heartbeat-identity.js";
+import { clearBotSession, readBotSession, writeBotSession } from "./session.js";
+import { defaultBotStatus, patchBotStatus, readBotStatus } from "./status.js";
+import { CLI_VERSION } from "../../cli-version.js";
+import { CLI_UPDATE_RESTART_EXIT_CODE } from "./cli-update.js";
+import { createInboxPollBackoffFlagReader, safeErrorClass } from "./inbox-poll-backoff-flag.js";
+export const INBOX_POLL_INTERVAL_MS = 2_000;
+export const HEARTBEAT_INTERVAL_MS = 30_000;
+/** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
+export const API_BACKOFF_BASE_MS = 4_000;
+/** Ceiling for exponential poll/heartbeat backoff. */
+export const API_BACKOFF_CAP_MS = 5 * 60_000;
+/** Honor Retry-After up to this; a bogus 30-day header must not park the bot. */
+export const API_RETRY_AFTER_CAP_MS = 15 * 60_000;
+export const API_RETRY_AFTER_FLOOR_MS = 1_000;
+/**
+ * How long to wait after a failed inbox poll or heartbeat.
+ * 429/5xx (and transport errors) back off exponentially, honouring Retry-After
+ * when present. Other 4xx keep the normal interval so a 401 is not stretched.
+ */
+export function apiPollDelayMs(opts) {
+    const intervalMs = Math.max(0, opts.intervalMs);
+    const status = opts.err instanceof BotApiError ? opts.err.status : undefined;
+    const retryable = status === 429 || (typeof status === "number" && status >= 500) || !(opts.err instanceof BotApiError);
+    if (!retryable)
+        return intervalMs;
+    const retryAfter = opts.err instanceof BotApiError ? opts.err.retryAfterMs : undefined;
+    const header = typeof retryAfter === "number" && Number.isFinite(retryAfter)
+        ? Math.min(API_RETRY_AFTER_CAP_MS, Math.max(API_RETRY_AFTER_FLOOR_MS, retryAfter))
+        : 0;
+    const base = Math.max(intervalMs * 2, API_BACKOFF_BASE_MS);
+    const attempt = Math.max(0, opts.attempt);
+    const exp = Math.min(API_BACKOFF_CAP_MS, base * 2 ** attempt);
+    const random = opts.random ?? Math.random;
+    const jittered = Math.floor(exp * (1 + 0.2 * random()));
+    return Math.min(API_BACKOFF_CAP_MS, Math.max(intervalMs, exp, header, jittered));
+}
+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;
+/** 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.";
+/**
+ * The same, for a scheduled run. Nobody asked, so "ask me again" is wrong: the
+ * run DID finish, and its outcome is still recorded with the job in HQ.
+ */
+export const UNDELIVERABLE_JOB_REPORT_TEXT = "This scheduled run finished, but I couldn't deliver its report here. Its result is saved with the job's run history.";
+/**
+ * Scheduled work must never crowd out the people the bot talks to. A job turn
+ * can run for a long time, so at most ONE runs at a time, and a job never takes
+ * the last free slot: a DM or a room message can always start immediately
+ * instead of waiting, with no explanation, behind two long jobs.
+ */
+export const MAX_PARALLEL_JOB_TURNS = 1;
+export const KICKOFF_MESSAGE_ID = "kickoff";
+/**
+ * The environment a model turn's `hq` commands run in.
+ *
+ * The bot process carries its own machine identity in HQ_MACHINE_CREDS_FILE /
+ * HQ_MACHINE_TOKEN_STATE_DIR so its inbox, heartbeat and posts are the bot's.
+ * What a turn inherits depends on the bot's kind:
+ * - A PERSONAL bot acts as its owner on every turn (DMs, the kickoff, rooms):
+ *   everything the owner asks for — a company, a bot, an invite, a share —
+ *   belongs to the owner's account, and the cloud rightly refuses a bot that
+ *   tries to own it ("No person entity found"). Stripping the marker makes
+ *   every `hq` command in the turn use the owner's sign-in, the same one the
+ *   desktop app shares, so no command needs a special case. The bot's id
+ *   (never a credential) rides along in HQ_BOT_AGENT_UID so what the owner
+ *   creates in the turn — a company — can add the bot as a member afterwards.
+ * - A COMPANY bot acts as itself on every turn, like a cloud agent: the
+ *   machine identity stays, and the cloud evaluates it through its own
+ *   company memberships. It never acts as the owner, in DMs or in rooms.
+ * Pure so the rule is unit-testable.
+ */
+export function turnEnv(base, kind, agentUid, companySlug) {
+    const env = { ...base };
+    delete env[HQ_BOT_AGENT_UID_ENV];
+    if (kind === "personal") {
+        delete env.HQ_MACHINE_CREDS_FILE;
+        delete env.HQ_MACHINE_TOKEN_STATE_DIR;
+        if (agentUid)
+            env[HQ_BOT_AGENT_UID_ENV] = agentUid;
+    }
+    else if (companySlug?.trim()) {
+        env.HQ_SPAWN_COMPANY = companySlug.trim();
+    }
+    return env;
+}
+/** The core worker HQ's setup bot runs. */
+export const SETUP_WORKER_ID = SETUP_BOT_WORKER_ID;
+/** 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." : ""}`;
+}
+export { containsNoReplySentinel };
+/** Grok emits is_error with this message when the model produces only reasoning tokens. */
+export function isReasoningOnlyError(excerpt) {
+    return excerpt.includes("reasoning_only");
+}
+/** 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";
+/**
+ * The lane an inbox item runs in: the model session its turn resumes. Owner
+ * DMs retain the legacy DM session; other senders and rooms each have their
+ * own, and so does each scheduled job (two different jobs must never share a
+ * model session, and a job must never pollute the owner's DM conversation).
+ * An item that never reaches a model turn gets a lane of its own.
+ */
+export function inboxLaneKey(item, config) {
+    if (isDmItem(item))
+        return dmSessionScope(item.fromPersonUid ?? "", config.ownerUid);
+    const target = resolveReplyTarget(item, config);
+    if (target?.kind === "room" || target?.kind === "job")
+        return target.sessionScope;
+    return `item:${item.messageId}`;
+}
+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, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+/**
+ * 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)
+        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 random = deps.random ?? Math.random;
+    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 inboxPollBackoffEnabled = deps.inboxPollBackoffEnabled ?? createInboxPollBackoffFlagReader(config);
+    const jobQuietOptionEnabled = deps.jobQuietOptionEnabled ?? botJobQuietOptionEnabled;
+    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 turns in progress (owner stop). */
+    const currentTurns = new Set();
+    const maxParallelTurns = Math.max(1, deps.maxParallelTurns ?? MAX_PARALLEL_TURNS);
+    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;
+    /**
+     * Setup bot, owner DM: remember whether the bot's latest reply asked the
+     * explain-or-jump question, so a click on "Explain HQ first" can be answered
+     * at once (setup-explain.ts). Never lets a bookkeeping error touch the turn.
+     */
+    const noteSetupReply = (reply) => {
+        if (!isSetupBot)
+            return;
+        try {
+            const offered = replyOffersExplain(reply);
+            const current = readSetupIntroState(dir);
+            if (offered && !current.offeredAt)
+                patchSetupIntroState(dir, { offeredAt: now().toISOString() });
+            else if (!offered && current.offeredAt)
+                patchSetupIntroState(dir, { offeredAt: undefined });
+        }
+        catch (err) {
+            log("warn", `setup intro state not updated: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    // Scheduled runs are reported in the owner's own zone: "every weekday at 9am"
+    // was set up here, so "due 13:00 UTC" would read as the wrong time.
+    const timeZone = machineTimeZone();
+    // Personal: every turn acts as the owner. Company: every turn acts as the bot.
+    const kind = effectiveBotKind(config);
+    const companies = effectiveBotCompanies(config);
+    const lockDeps = defaultPidLockDeps({
+        pid,
+        ...(deps.isProcessAlive ? { isProcessAlive: deps.isProcessAlive } : {}),
+    });
+    const finish = async (final, code, reason, beforeExit) => {
+        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);
+        try {
+            beforeExit?.();
+        }
+        catch (err) {
+            log("error", `before exit: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        resolveDone(final);
+        exit(code);
+    };
+    const cliVersion = deps.cliUpdate?.runningVersion ?? CLI_VERSION;
+    /** Set once an update restart is due: no new turns, then exit for the supervisor. */
+    let cliUpdatePending = null;
+    const pollForCliUpdate = () => {
+        const update = deps.cliUpdate?.poll(log) ?? null;
+        if (!update)
+            return false;
+        cliUpdatePending = update;
+        stopping = true;
+        const busy = running.size;
+        log("info", `hq-cli updated ${update.from} -> ${update.to}; restarting to load it${busy ? ` after ${busy} running turn${busy === 1 ? "" : "s"} finish${busy === 1 ? "es" : ""}` : ""}`);
+        return true;
+    };
+    // ── 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, idle: () => true };
+    }
+    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, idle: () => true };
+    }
+    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, idle: () => true };
+        }
+    }
+    if (hasPromotionHold(dir)) {
+        await finish("stopped", 0, "local bot held for cloud promotion");
+        return { stop: async () => { }, done, status: () => null, idle: () => true };
+    }
+    // A restart is the owner's "try again" after signing in: start clean.
+    setStatus({ ...fallback(), pid, state: "starting", canDrainForPromotion: false, runtimeSignIn: null, cliVersion });
+    log("info", `starting ${config.name} on hq-cli ${cliVersion} (${config.runtime}, ${kind} bot${companies.length ? ` of ${companies.join(", ")}` : ""}) as ${config.agentUid} for ${config.ownerUid}`);
+    deps.cliUpdate?.startup(log);
+    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 !== kind) {
+            await finish("failed", 0, `identity ${config.agentUid} is not a ${kind} local bot; this installation cannot run it`);
+            return { stop: async () => { }, done, status: () => null, idle: () => true };
+        }
+        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, idle: () => true };
+        }
+    }
+    catch (err) {
+        await finish("failed", 0, `could not verify bot identity: ${err instanceof Error ? err.message : String(err)}`);
+        return { stop: async () => { }, done, status: () => null, idle: () => true };
+    }
+    // ── System prompt ──────────────────────────────────────────────────────────
+    const systemPrompt = deps.systemPromptOverride ??
+        buildSystemPrompt({
+            botName: config.name,
+            ...(config.displayName ? { displayName: config.displayName } : {}),
+            agentUid: config.agentUid,
+            ownerUid: config.ownerUid,
+            hqRoot: config.hqRoot,
+            workerDir: config.workerDir,
+            workerSource: config.workerSource,
+            workerId: config.workerId,
+            companySlug: config.companySlug,
+            kind,
+            companies,
+            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, idle: () => true };
+    }
+    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 leftovers = readInflightTurns(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 && config.kickoffPendingSignIn && config.kickoff?.trim()) {
+        // The kickoff was held for a sign-in on an earlier run; this start retries it.
+        kickoffAfterIntro = {};
+    }
+    else if (!config.introSentAt) {
+        try {
+            const sent = await api.sendDm({ toPersonUid: config.ownerUid, body: introDmText(config.name, config.runtime, config.intro, { kind: effectiveBotKind(config), companies: effectiveBotCompanies(config) }) });
+            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";
+    // ── Coding tool sign-in ────────────────────────────────────────────────────
+    const signInRetryMs = Math.max(0, deps.signInRetryMs ?? SIGN_IN_RETRY_MS);
+    let signInIssue = null;
+    let nextSignInRetryAt = 0;
+    /** Conversations already told this time that the bot needs a sign-in. */
+    const toldAboutSignIn = new Set();
+    const markSignInBroken = (excerpt) => {
+        nextSignInRetryAt = now().getTime() + signInRetryMs;
+        modelHealth = "degraded";
+        if (signInIssue)
+            return;
+        signInIssue = { state: "expired", runtime: config.runtime, since: now().toISOString() };
+        setStatus({ runtimeSignIn: signInIssue, lastError: excerpt.slice(0, 400) });
+        log("warn", `${runtime.id} needs to sign in again on this computer; holding turns and retrying every ${Math.round(signInRetryMs / 1000)}s`);
+    };
+    const markSignInWorks = () => {
+        if (!signInIssue)
+            return;
+        signInIssue = null;
+        toldAboutSignIn.clear();
+        setStatus({ runtimeSignIn: null });
+        log("info", `${runtime.id} sign-in works again; resuming`);
+    };
+    /** Say once per conversation that the bot cannot work until its tool signs in. */
+    const tellSignInNeeded = async (conversation, post, kickoff = false) => {
+        if (toldAboutSignIn.has(conversation))
+            return;
+        try {
+            await post(signInNeededText(config.runtime, kickoff));
+            toldAboutSignIn.add(conversation);
+        }
+        catch (err) {
+            log("warn", `could not say that ${runtime.id} needs a sign-in: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    const heartbeatLoop = (async () => {
+        let heartbeatFails = 0;
+        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" });
+                heartbeatFails = 0;
+                setStatus({
+                    lastHeartbeatAt: now().toISOString(),
+                    lastHeartbeatOk: true,
+                    lastHeartbeatError: undefined,
+                    lastHeartbeatReason: undefined,
+                    lastHeartbeatConfiguredAgentUid: undefined,
+                    lastHeartbeatTokenAgentUid: undefined,
+                });
+                await sleep(heartbeatIntervalMs);
+            }
+            catch (err) {
+                if (err instanceof BotApiError &&
+                    isHeartbeatIdentityMismatch({ status: err.status, code: err.code, message: err.detail })) {
+                    const tokenLabel = err.tokenAgentUid ?? "unknown";
+                    const reason = identityMismatchMessage("heartbeat", config.agentUid, tokenLabel);
+                    setStatus({
+                        lastHeartbeatOk: false,
+                        lastHeartbeatError: reason.slice(0, 400),
+                        lastHeartbeatReason: "identity_mismatch",
+                        lastHeartbeatConfiguredAgentUid: config.agentUid,
+                        ...(err.tokenAgentUid ? { lastHeartbeatTokenAgentUid: err.tokenAgentUid } : {}),
+                    });
+                    log("warn", reason);
+                    (deps.reportIdentityMismatch ?? captureHeartbeatIdentityMismatch)({
+                        runner: "bot",
+                        configuredAgentUid: config.agentUid,
+                        ...(err.tokenAgentUid ? { tokenAgentUid: err.tokenAgentUid } : {}),
+                        agentUidSource: deps.agentUidSource ?? "config_file",
+                        credsSource: deps.credsSource ?? "default",
+                    });
+                    break;
+                }
+                heartbeatFails += 1;
+                const message = err instanceof Error ? err.message : String(err);
+                setStatus({ lastHeartbeatOk: false, lastHeartbeatError: message.slice(0, 400) });
+                log("warn", `heartbeat failed: ${message}`);
+                await sleep(apiPollDelayMs({ err, attempt: heartbeatFails - 1, intervalMs: heartbeatIntervalMs, random }));
+            }
+        }
+    })();
+    // ── Inbox loop ─────────────────────────────────────────────────────────────
+    const attempts = new Map();
+    const inboxBackoffSteps = [inboxIntervalMs, 10_000, 20_000, 30_000];
+    let inboxBackoffIndex = 0;
+    let inboxWaitGeneration = 0;
+    let activeInboxWait = null;
+    const resetInboxBackoff = () => {
+        inboxBackoffIndex = 0;
+        inboxWaitGeneration += 1;
+        activeInboxWait?.abort();
+    };
+    const waitForInbox = async (delayMs, adaptive) => {
+        if (!adaptive) {
+            await sleep(delayMs);
+            return;
+        }
+        let remainingMs = delayMs;
+        let observedGeneration = inboxWaitGeneration;
+        while (remainingMs > 0 && !stopping && state === "running") {
+            const controller = new AbortController();
+            activeInboxWait = controller;
+            const chunkMs = Math.min(inboxIntervalMs, remainingMs);
+            await sleep(chunkMs, controller.signal);
+            if (activeInboxWait === controller)
+                activeInboxWait = null;
+            if (stopping || state !== "running")
+                break;
+            if (hasPromotionHold(dir))
+                break;
+            if (observedGeneration !== inboxWaitGeneration || controller.signal.aborted) {
+                observedGeneration = inboxWaitGeneration;
+                remainingMs = inboxIntervalMs;
+                continue;
+            }
+            remainingMs -= chunkMs;
+            // Keep the install watcher at its original two-second cadence even when
+            // the inbox itself is waiting longer between empty polls.
+            if (remainingMs > 0 && pollForCliUpdate())
+                break;
+        }
+    };
+    /** 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}]\n[HQ sender: ${item.fromPersonUid ?? "unknown"}; owner: ${config.ownerUid}; sender is ${item.fromPersonUid === config.ownerUid ? "the owner" : "not the owner"}.]`;
+        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 ?? "someone"} (${m.fromPersonUid ?? "unknown"}): ${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();
+        const env = turnEnv(process.env, kind, config.agentUid, config.companySlug);
+        let bind = { env };
+        if (config.companySlug) {
+            try {
+                ensureBotSessionMeta(config.hqRoot, sid, config.companySlug, undefined, now);
+                bind = { newSessionId: sid, env: { ...env, HQ_SESSION_ID: sid } };
+            }
+            catch (err) {
+                log("warn", `company bind failed for ${config.companySlug}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Only a personal bot, and only in 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. A company bot acts as itself and never gets it.
+        // Owner context also goes on the owner's scheduled jobs: `turnEnv` strips
+        // the machine credentials on EVERY personal-bot turn, so a job turn runs
+        // `hq` as the owner too and needs the same block saying whose account it
+        // is on. Rooms stay excluded (see above).
+        const actsPurelyForOwner = sessionScope === "dm" || sessionScope.startsWith("job:");
+        if (deps.ownerContext && actsPurelyForOwner && kind === "personal") {
+            try {
+                const owner = await deps.ownerContext();
+                if (owner.status === "unavailable") {
+                    log("warn", `owner context unavailable: ${owner.reason}${owner.detail ? ` (${owner.detail})` : ""}`);
+                }
+                else if (owner.status === "mismatch") {
+                    log("warn", `owner context mismatch: signed in as ${owner.signedInAs}`);
+                }
+                prompt = `${ownerContextBlock(owner, 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";
+        markSignInWorks();
+        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;
+        const silenceable = args.silenceable === true;
+        writeInflight(dir, {
+            v: 1,
+            ...args.marker,
+            startedAt: now().toISOString(),
+            ...(silenceable ? { silenceable: true } : {}),
+        });
+        let running = true;
+        let posted = 0;
+        const makeSendFn = (fn) => async (body) => {
+            try {
+                await fn(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 poster = new ProgressPoster({
+            // The setup bot talks to someone new to HQ: its notes to itself never
+            // reach them, and it posts no "still working" notice either — the
+            // desktop app shows that the bot is working.
+            ...(isSetupBot ? { dropPreToolMessages: true } : {}),
+            ...deps.progress,
+            ...(args.workingNotice === false || silenceable || isSetupBot ? { workingNoticeMs: 0 } : {}),
+            ...(silenceable || args.suppressOutput ? { buffer: true } : {}),
+            send: makeSendFn(args.send),
+            ...(args.sendFinal ? { sendFinal: makeSendFn(args.sendFinal) } : {}),
+        });
+        const controller = new AbortController();
+        currentTurns.add(controller);
+        poster.start();
+        try {
+            const turn = await executeTurn(args.prompt, args.sessionScope, args.tReceived, {
+                onEvent: (event) => {
+                    if (event.kind === "message")
+                        poster.message(event.text);
+                    else if (event.kind === "tool")
+                        poster.tool();
+                },
+                signal: controller.signal,
+                ...(args.readDirs?.length ? { readDirs: args.readDirs } : {}),
+            });
+            running = false;
+            // Control tokens were already stripped from turn.text in runRuntimeTurn, so
+            // a `<|eos|>`-only reply arrives here as empty. On an unmentioned room turn
+            // a stay-quiet phrase ("No response requested." etc.) is also silence — the
+            // meta chatter that let two bots loop on 2026-09-25.
+            const stayQuiet = silenceable && isMetaNonReply(turn.text);
+            const sentinelOrEmpty = containsNoReplySentinel(turn.text) || !turn.text.trim() || stayQuiet;
+            if (args.suppressOutput) {
+                await poster.abandon();
+                const finalText = sentinelOrEmpty ? "" : turn.text;
+                return { outcome: { ok: true, reply: finalText.trim(), ...(sentinelOrEmpty ? { silent: true } : {}) }, poster };
+            }
+            // Unmentioned room turn: a no_reply sentinel (bare, fenced, or with
+            // preamble), an empty/whitespace reply, or a stay-quiet phrase means stay
+            // quiet. Abandon the poster (it posts nothing) and return a silent outcome;
+            // the caller acks without posting anything.
+            if (silenceable && sentinelOrEmpty) {
+                await poster.abandon();
+                return { outcome: { ok: true, reply: "", silent: true }, poster };
+            }
+            // DM or @-mentioned room: the person asked directly and must get a reply.
+            // Strip the silence sentinel so its raw JSON never posts, then let the
+            // poster produce its "(no reply)" fallback when there is nothing else.
+            const finalText = sentinelOrEmpty ? "" : turn.text;
+            await poster.finish(finalText);
+            return { outcome: { ok: true, reply: finalText.trim() }, 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 {
+            currentTurns.delete(controller);
+        }
+    };
+    const failureReason = (outcome) => outcome.aborted ? STOPPED_BY_OWNER_REASON : `${runtime.id} stopped with an error: ${outcome.excerpt.slice(0, 160)}`;
+    const postOne = (target, body, rootEventId, audience) => {
+        const root = rootEventId ? { rootEventId } : {};
+        return target.kind === "dm"
+            ? api.sendDm({ toPersonUid: target.peerUid, body, ...root, ...(audience ? { audience } : {}) })
+            : 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, audience) => {
+        for (let i = Math.max(0, from); i < parts.length; i += 1) {
+            try {
+                await postOne(target, parts[i], rootEventId, audience);
+            }
+            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, audience) => sendParts(target, splitBody(body), 0, rootEventId, undefined, audience);
+    /**
+     * 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 makeSend = (audience) => async (body) => {
+            try {
+                await sendToTarget(target, body, rootEventId, audience);
+                last.value = null;
+            }
+            catch (err) {
+                last.value = err instanceof PartialPostError && err.delivered > 0 ? { parts: err.parts, delivered: err.delivered } : null;
+                throw err;
+            }
+        };
+        const send = makeSend(target.kind === "dm" ? "agent" : undefined);
+        const sendFinal = makeSend(target.kind === "dm" ? "human" : undefined);
+        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, sendFinal, saved };
+    };
+    // ── Scheduled jobs ────────────────────────────────────────────────────────
+    /** Newest pending run key already picked up, per jobId (one catch-up per wake). */
+    const handledJobFires = new Map();
+    /** Runs an older fire of a job that a newer pending run supersedes. */
+    const supersededJobRuns = new Set();
+    /**
+     * Report one fired run as finished. This is the ONLY thing that clears the
+     * job's in-progress flag in the cloud, so a failure is logged loudly and the
+     * completion is kept for the next poll — the caller still acks, because the
+     * work is done and must never run twice.
+     */
+    const completeJobRun = async (jobId, messageId, completion) => {
+        try {
+            await api.completeJobRun(config.agentUid, jobId, messageId, completion);
+            clearPendingJobCompletion(dir, messageId);
+            log("info", `reported run ${messageId} of job ${jobId} as ${completion.status}`);
+            return true;
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            const pending = recordPendingJobCompletion(dir, { agentUid: config.agentUid, jobId, messageId, status: completion.status, ...(completion.output !== undefined ? { output: completion.output } : {}), ...(completion.disposition !== undefined ? { disposition: completion.disposition } : {}) }, now());
+            log("error", `COULD NOT report run ${messageId} of job ${jobId} as ${completion.status}: ${reason}. ` +
+                `Until this is reported the cloud keeps the job marked in progress and skips its next fires. ` +
+                `Retry ${pending.attempts} in ${Math.round((pending.nextAttemptAt - now().getTime()) / 1000)}s.`);
+            return false;
+        }
+    };
+    /**
+     * Re-send completions the cloud has not accepted yet. Never re-runs work.
+     * Backed off per entry and given up on by age, so a minute-long network drop
+     * recovers instead of burning a fixed attempt budget in twenty seconds.
+     */
+    const retryPendingJobCompletions = async () => {
+        const nowMs = now().getTime();
+        for (const pending of readPendingJobCompletions(dir)) {
+            // A folder that outlived a deleted, same-named bot: never report another
+            // identity's run as this one's (see job-completions.ts, "After a reinstall").
+            if (isCompletionForOtherAgent(pending, config.agentUid)) {
+                clearPendingJobCompletion(dir, pending.messageId);
+                log("warn", `dropped an unreported run ${pending.messageId} of job ${pending.jobId}: it belongs to ${pending.agentUid}, ` +
+                    `not this bot (${config.agentUid}) — left behind by an earlier bot with the same name`);
+                continue;
+            }
+            if (isCompletionExpired(pending, nowMs)) {
+                clearPendingJobCompletion(dir, pending.messageId);
+                log("error", `giving up on reporting run ${pending.messageId} of job ${pending.jobId} after ${pending.attempts} attempts ` +
+                    `over an hour; the cloud has released the job's in-progress slot by itself by now`);
+                continue;
+            }
+            if (!isCompletionDue(pending, nowMs))
+                continue;
+            await completeJobRun(pending.jobId, pending.messageId, {
+                status: pending.status,
+                ...(pending.output !== undefined ? { output: pending.output } : {}),
+                ...(pending.disposition !== undefined ? { disposition: pending.disposition } : {}),
+            });
+        }
+    };
+    /**
+     * Kick the completion retries WITHOUT blocking the poll. Awaiting them in the
+     * inbox loop meant one hanging completion POST stalled DM delivery behind it.
+     * One pass at a time; the tracked promise is drained on shutdown.
+     */
+    let completionRetryTask = Promise.resolve();
+    let completionRetryRunning = false;
+    const kickCompletionRetries = () => {
+        if (completionRetryRunning)
+            return;
+        completionRetryRunning = true;
+        completionRetryTask = retryPendingJobCompletions()
+            .catch((err) => {
+            log("warn", `retrying job completions failed: ${err instanceof Error ? err.message : String(err)}`);
+        })
+            .finally(() => {
+            completionRetryRunning = false;
+        });
+    };
+    /** 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 scheduled run's marker is about to be closed: report its REAL outcome to
+     * the cloud first, and record that it was reported, BEFORE the ack.
+     *
+     * - A saved reply means the work finished and only delivery failed: that is
+     *   `succeeded`, with the report as output — including when delivery was
+     *   given up on as impossible. The owner not getting the DM does not undo
+     *   the work, and not reporting would jam the job for an hour.
+     * - No saved reply means the turn was cut off: `failed`.
+     * - A marker that says it was already reported is never reported again: the
+     *   server's complete is last-write-wins, so a second report after a crash
+     *   between reporting and acking would overwrite the recorded outcome.
+     */
+    const reportRecoveredJobRun = async (marker) => {
+        if (!marker.jobId || marker.jobCompleted)
+            return;
+        const finished = typeof marker.reply === "string";
+        // A run that failed or was stopped carries its real reason; only a marker
+        // with none was genuinely cut off by a restart.
+        const failure = marker.jobFailure;
+        const completion = finished
+            ? { status: "succeeded", output: marker.jobOutput ?? jobRunOutput(stripJobHeader(marker.reply, marker.jobHeader)) }
+            : failure
+                ? {
+                    status: "failed",
+                    disposition: failure.reason.slice(0, 256),
+                    ...(failure.excerpt ? { output: jobRunOutput(failure.excerpt) } : {}),
+                }
+                : { status: "failed", disposition: "the run was cut off when the bot restarted" };
+        await completeJobRun(marker.jobId, marker.messageId, completion);
+        patchInflight(dir, marker.messageId, { jobCompleted: completion.status });
+    };
+    /**
+     * The body a recovery posts. A scheduled run's FIRST message carries its
+     * header, so a report delivered by this path still reads as a scheduled run
+     * and not as an unsolicited DM. A body saved in parts already has the header
+     * baked in (the job's own send put it there), so it is never added twice.
+     */
+    const recoveryBody = (marker) => {
+        // A job that failed on its own says why; "I was restarted" only when it was.
+        const reason = marker.jobFailure?.reason ?? RESTARTED_REASON;
+        const body = marker.reply ?? didNotFinishText(reason, (marker.progressPosted ?? 0) > 0);
+        const headerAlreadyOut = (marker.progressPosted ?? 0) > 0 || body.startsWith(marker.jobHeader ?? "\u0000");
+        return marker.jobHeader && !headerAlreadyOut ? `${marker.jobHeader}${body}` : body;
+    };
+    /**
+     * 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;
+        // A scheduled run left in this folder by a DIFFERENT bot (adopt into a
+        // folder that survived without its bot.json). Posting its report would put
+        // another bot's work in this bot's DM, and completing it would be a write
+        // under the wrong identity — the thing job-completions.ts rules out. Drop
+        // it: no post, no completion, no ack (the item is not in this inbox). The
+        // cloud releases that job's slot by itself within the hour. A marker with
+        // no recorded agent predates the field and is recovered as before.
+        if (marker.jobId && marker.agentUid && marker.agentUid !== config.agentUid) {
+            clearInflight(dir, marker.messageId);
+            log("warn", `dropped an unfinished scheduled run ${marker.messageId} of job ${marker.jobId}: it belongs to ${marker.agentUid}, ` +
+                `not this bot (${config.agentUid}) — left behind by an earlier bot in this folder; not posted, not reported`);
+            return true;
+        }
+        if (!isKickoff && isProcessed(readInboxState(dir), marker.messageId)) {
+            clearInflight(dir, marker.messageId);
+            return true;
+        }
+        // An unmentioned room turn (silenceable) that never produced a saved
+        // reply: the person never asked the bot to answer. Posting "I didn't
+        // finish that — I was restarted…" into that room is noise (2026-09-25:
+        // two bots posted the notice in a channel where neither was mentioned).
+        // Ack and clear silently; a saved `reply` still posts below because a
+        // real answer that only failed delivery is worth keeping.
+        if (!isKickoff &&
+            marker.silenceable === true &&
+            !marker.jobId &&
+            (marker.reply === undefined || marker.reply.trim() === "")) {
+            log("info", `recovered unmentioned room turn ${marker.messageId} silently (no saved reply); not posting a restart notice`);
+            await closeMarker(marker, isKickoff);
+            return true;
+        }
+        const parts = marker.replyParts ?? splitBody(recoveryBody(marker));
+        const from = marker.replyParts ? Math.min(Math.max(0, marker.replyPartsDelivered ?? 0), parts.length) : 0;
+        try {
+            await sendParts(marker.target, parts, from, marker.rootEventId, (count) => patchInflight(dir, marker.messageId, { replyParts: parts, replyPartsDelivered: count }));
+        }
+        catch (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`);
+                if (marker.jobId) {
+                    // Nobody asked, so "ask me again" is wrong. The header goes on only if
+                    // no part of this run reached the chat yet.
+                    const headerOut = (marker.progressPosted ?? 0) > 0 || (err instanceof PartialPostError ? err.delivered : from) > 0;
+                    const text = marker.jobHeader && !headerOut ? `${marker.jobHeader}${UNDELIVERABLE_JOB_REPORT_TEXT}` : UNDELIVERABLE_JOB_REPORT_TEXT;
+                    await postOne(marker.target, text, marker.rootEventId).catch(() => undefined);
+                    // Giving up on DELIVERY is not giving up on the RUN: report it.
+                    await reportRecoveredJobRun(marker);
+                }
+                else {
+                    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;
+        }
+        await reportRecoveredJobRun(marker);
+        await closeMarker(marker, isKickoff);
+        log("info", marker.reply
+            ? `posted the saved reply for ${marker.messageId}`
+            : `told the owner ${marker.messageId} did not finish (${marker.jobFailure ? marker.jobFailure.reason : "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 { send, sendFinal, saved } = trackingSend(target);
+        const { outcome, poster } = await runTurnWithProgress({
+            marker: { messageId: KICKOFF_MESSAGE_ID, target, ...(thinking && introEventId ? { reactionEventId: introEventId } : {}) },
+            prompt,
+            sessionScope: "dm",
+            tReceived,
+            send,
+            sendFinal,
+            // The intro already said the bot is starting, and the app shows it thinking.
+            workingNotice: false,
+        });
+        await clearThinking();
+        if (outcome.ok) {
+            // The kickoff never runs silenceable, so outcome.silent is never set here.
+            if (poster.postedCount === 0) {
+                patchInflight(dir, KICKOFF_MESSAGE_ID, saved(outcome.reply));
+                log("warn", "kickoff reply failed to send; it is posted on the next start");
+                return;
+            }
+            clearInflight(dir, KICKOFF_MESSAGE_ID);
+            noteSetupReply(outcome.reply);
+            if (readBotConfig(dir)?.kickoffPendingSignIn)
+                patchBotConfig(dir, { kickoffPendingSignIn: false });
+            const st = readStatus();
+            setStatus({ repliesSent: (st?.repliesSent ?? 0) + 1, lastActivityAt: now().toISOString() });
+            log("info", `kickoff reply sent (${outcome.reply.length} chars)`);
+            return;
+        }
+        if (!outcome.aborted && poster.postedCount === 0 && isRuntimeSignInFailure(outcome.excerpt)) {
+            // Nothing ran: hold the kickoff until the tool can sign in, then run it.
+            clearInflight(dir, KICKOFF_MESSAGE_ID);
+            patchBotConfig(dir, { kickoffPendingSignIn: true });
+            markSignInBroken(outcome.excerpt);
+            await tellSignInNeeded("dm", send, true);
+            return;
+        }
+        if (readBotConfig(dir)?.kickoffPendingSignIn)
+            patchBotConfig(dir, { kickoffPendingSignIn: false });
+        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 send(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}`);
+        }
+    };
+    /**
+     * One fired job: a model turn on the job's own prompt, in the job's own
+     * session, reported in the owner's DM under a "scheduled job" header, and
+     * reported to the cloud exactly once.
+     */
+    const handleJobItem = async (item, target) => {
+        const id = item.messageId;
+        const { job, jobId } = target;
+        const peerUid = target.peerUid;
+        // An older pending run of this job: a newer one runs instead. Reported so
+        // the cloud releases the slot and the history says what happened.
+        if (supersededJobRuns.has(id)) {
+            await completeJobRun(jobId, id, { status: "skipped-precondition", disposition: SUPERSEDED_DISPOSITION });
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            supersededJobRuns.delete(id);
+            log("info", `skipped older run ${id} of job ${jobId}: a newer pending run of the same job runs instead`);
+            return;
+        }
+        const catchUp = isCatchUpRun(job, now());
+        const quietJob = target.job.quiet === true && await jobQuietOptionEnabled();
+        const attempt = (attempts.get(id) ?? 0) + 1;
+        attempts.set(id, attempt);
+        const tReceived = now().getTime();
+        log("info", `received scheduled run ${id} of job ${jobId}${catchUp ? " (catch-up)" : ""}`);
+        // The header goes on the first message of the turn, so the owner sees at a
+        // glance that this is a scheduled run and not a reply to something they
+        // said. It rides on the marker too, so a report posted by the recovery path
+        // after a restart carries it as well.
+        //
+        // Every post goes through the SAME split/track path as any other reply
+        // (trackingSend → splitBody), so a long report is delivered in parts rather
+        // than refused whole. The header is only counted as delivered once a part
+        // actually reached the chat, and `saved` records the body EXACTLY as it was
+        // attempted (header included), so the parts the recovery path resends line
+        // up with the parts already delivered and nothing is repeated or dropped.
+        const header = jobReportHeader(job, catchUp, timeZone);
+        const markerTarget = { kind: "dm", peerUid };
+        const tracking = trackingSend(markerTarget);
+        let headerOut = false;
+        // What actually reached the chat, kept apart from "was anything posted".
+        // `poster.postedCount` counts progress posts too, so a turn that said
+        // "Checking the dashboards…" and then failed to post its REPORT would look
+        // delivered — and for a scheduled run the report is the only thing the
+        // owner sees; nobody will ask again.
+        const deliveredBodies = [];
+        let anySendFailed = false;
+        /** The body of the LAST send, when that send failed (the resume point). */
+        let lastFailedBody = null;
+        const withHeader = (body) => (headerOut ? body : `${header}${body}`);
+        const makeSend = (fn) => async (body) => {
+            const full = withHeader(body);
+            try {
+                await fn(full);
+                headerOut = true;
+                deliveredBodies.push(body);
+                lastFailedBody = null;
+            }
+            catch (err) {
+                anySendFailed = true;
+                lastFailedBody = full;
+                if (err instanceof PartialPostError && err.delivered > 0)
+                    headerOut = true;
+                throw err;
+            }
+        };
+        const send = makeSend(tracking.send);
+        const sendFinal = makeSend(tracking.sendFinal);
+        const normalize = (text) => text.replace(/\s+/g, " ").trim();
+        /**
+         * True only when the final report itself reached the chat in full. With no
+         * failed post at all, the poster delivered everything it chose to (it skips
+         * a final that repeats a progress post, so "no failures" is the reliable
+         * signal). After any failure, the report must be inside a fully delivered
+         * post. Erring towards resending: a duplicate beats a report that vanished.
+         */
+        const reportDelivered = (reply) => poster.postedCount > 0 && (!anySendFailed || deliveredBodies.some((b) => normalize(b).includes(normalize(reply))));
+        /**
+         * The report, saved for resending. When the LAST post was the report and
+         * part of it already got through, resume that exact body at the parts
+         * delivered, so nothing is repeated. Otherwise resend the report whole,
+         * under its own header: the resend may come much later (after a restart)
+         * and must still read as a scheduled run.
+         */
+        const savedReport = (reply) => {
+            const jobOutput = jobRunOutput(reply);
+            const failed = lastFailedBody;
+            if (failed !== null && failed.trimEnd().endsWith(reply)) {
+                const resumed = tracking.saved(failed);
+                if ((resumed.replyPartsDelivered ?? 0) > 0)
+                    return { ...resumed, jobOutput };
+            }
+            return { ...tracking.saved(`${header}${reply}`), jobOutput };
+        };
+        /** Remember that this run's outcome is reported, before the ack. */
+        const markReported = (status) => {
+            patchInflight(dir, id, { jobCompleted: status });
+        };
+        const { outcome, poster } = await runTurnWithProgress({
+            marker: { messageId: id, target: markerTarget, jobId, jobHeader: header, agentUid: config.agentUid },
+            prompt: buildJobTurnPrompt(job, { now: now(), timeZone }),
+            sessionScope: target.sessionScope,
+            tReceived,
+            send,
+            sendFinal,
+            // A scheduled run has nobody waiting in a chat: no "working on it" filler.
+            workingNotice: false,
+            ...(quietJob ? { suppressOutput: true } : {}),
+        });
+        if (outcome.ok) {
+            if (!quietJob && !reportDelivered(outcome.reply)) {
+                // The work finished but the REPORT did not fully reach the DM — even if
+                // a progress post did. Keep it (and the run un-reported and un-acked)
+                // so the next poll delivers it, resuming at the parts already read,
+                // before the run is completed. Never re-run.
+                patchInflight(dir, id, savedReport(outcome.reply));
+                log("warn", `report for run ${id} of job ${jobId} was not fully delivered; it is resent on the next poll`);
+                return;
+            }
+            await completeJobRun(jobId, id, { status: "succeeded", output: jobRunOutput(outcome.reply) });
+            markReported("succeeded");
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            clearInflight(dir, id);
+            attempts.delete(id);
+            setStatus({
+                ...(!quietJob ? { repliesSent: (readStatus()?.repliesSent ?? 0) + 1 } : {}),
+                lastActivityAt: now().toISOString(),
+            });
+            log("info", `job ${jobId} run ${id} done (${outcome.reply.length} chars${catchUp ? ", catch-up" : ""})`);
+            return;
+        }
+        if (!outcome.aborted && poster.postedCount === 0 && isRuntimeSignInFailure(outcome.excerpt)) {
+            // Nothing ran: hold the run until the coding tool can sign in again. It
+            // is neither acked nor reported succeeded — the work is still owed.
+            clearInflight(dir, id);
+            attempts.delete(id);
+            markSignInBroken(outcome.excerpt);
+            await tellSignInNeeded(`job:${jobId}`, (body) => sendToTarget(markerTarget, body));
+            log("warn", `kept scheduled run ${id} of job ${jobId} until ${runtime.id} can sign in again`);
+            return; // un-acked, un-reported: run once the sign-in works
+        }
+        if (!outcome.started) {
+            // The model never ran, so nothing happened outside this Mac: retry.
+            clearInflight(dir, id);
+            const { excerpt } = recordTurnFailure(outcome.error, target.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) {
+                await send(`I couldn't run this one — ${runtime.id} kept failing: ${excerpt.slice(0, 160)}.`).catch(() => undefined);
+                await completeJobRun(jobId, id, { status: "failed", output: jobRunOutput(excerpt), disposition: `${runtime.id} could not be started` });
+                markReported("failed");
+                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; // 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, target.sessionScope);
+        const reason = failureReason(outcome);
+        // Saved BEFORE the post: if "did not finish" cannot be posted, recovery
+        // reports and says this real reason, not "the bot was restarted".
+        patchInflight(dir, id, { jobFailure: { reason, ...(outcome.excerpt ? { excerpt: outcome.excerpt } : {}) } });
+        try {
+            await send(didNotFinishText(reason, poster.postedCount > 0));
+        }
+        catch (err) {
+            // Leave it un-acked with the marker: the next poll reports it.
+            log("warn", `could not post "did not finish" for run ${id} of job ${jobId}: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        await completeJobRun(jobId, id, { status: "failed", output: jobRunOutput(outcome.excerpt), disposition: reason.slice(0, 256) });
+        markReported("failed");
+        markProcessed(dir, id, now().toISOString());
+        await api.ackInbox(config.agentUid, id);
+        clearInflight(dir, id);
+        attempts.delete(id);
+        log("error", `scheduled run ${id} of job ${jobId} ${outcome.aborted ? "stopped by the owner" : "failed"} after it started; 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 instant answer to "Explain HQ first" (setup-explain.ts). Returns true
+     * when it answered the message (sent, marked processed, acked); false sends
+     * the message down the normal model path, so nothing here can leave a
+     * message unanswered.
+     */
+    const sendSetupExplanation = async (item, text, attachments) => {
+        const id = item.messageId;
+        let reply;
+        try {
+            const due = setupExplainDue({
+                text,
+                attachments,
+                state: readSetupIntroState(dir),
+                progress: readSetupProgressIntro(resolveBotMemoryDir(config)),
+            });
+            if (!due)
+                return false;
+            const explainer = loadSetupExplainer(config.hqRoot, config.workerDir);
+            if (!explainer) {
+                log("warn", `no usable explain-hq.md in ${config.workerDir}; answering ${id} with a model turn`);
+                return false;
+            }
+            reply = explainer.reply;
+        }
+        catch (err) {
+            log("warn", `setup explanation check failed (${err instanceof Error ? err.message : String(err)}); answering ${id} with a model turn`);
+            return false;
+        }
+        try {
+            await sendToTarget({ kind: "dm", peerUid: config.ownerUid }, reply, item.rootEventId, "human");
+        }
+        catch (err) {
+            log("warn", `setup explanation for ${id} could not be sent (${err instanceof Error ? err.message : String(err)}); answering with a model turn`);
+            return false;
+        }
+        markProcessed(dir, id, now().toISOString());
+        try {
+            patchSetupIntroState(dir, { explainedAt: now().toISOString(), notePending: true, offeredAt: undefined });
+        }
+        catch (err) {
+            log("warn", `setup intro state not updated: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        await api.ackInbox(config.agentUid, id);
+        setStatus({ repliesSent: (readStatus()?.repliesSent ?? 0) + 1, lastActivityAt: now().toISOString() });
+        log("info", `answered ${id} with the setup explanation (no model turn)`);
+        return true;
+    };
+    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, id);
+        if (inflight) {
+            await recoverInflight(inflight);
+            return;
+        }
+        const target = resolveReplyTarget(item, config);
+        // A bot/agent sender that did not @mention this bot must never start a model
+        // turn: two bots each answering the other's plain room posts loop forever
+        // (observed 2026-09-25). An explicit @mention still gets answered below.
+        if (target && target.kind === "room" && !target.mentioned && isAgentSender(item.fromPersonUid)) {
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            log("info", `ignored inbox item ${id} (room ${target.channelId}, unmentioned message from bot ${item.fromPersonUid ?? "unknown"}; not starting a turn)`);
+            return;
+        }
+        if (!target) {
+            // A job item the bot cannot run. When it names a job, the cloud is still
+            // holding that job's in-progress slot: acking alone would jam every later
+            // fire of it for an hour, and the next fire would be just as unusable —
+            // the same jam, forever. Report it so the slot is released.
+            const unusableJobId = isJobItem(item) && typeof item.jobId === "string" ? item.jobId.trim() : "";
+            if (unusableJobId) {
+                await completeJobRun(unusableJobId, id, {
+                    status: "skipped-precondition",
+                    disposition: "the fired run carried no prompt, so there was nothing to run",
+                });
+            }
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            log("info", isJobItem(item)
+                ? `ignored job item ${id}: it carries no ${unusableJobId ? "prompt" : "job id"}`
+                : `ignored inbox item ${id} (${item.channel || "dm"}${item.channelScope ? ` ${item.channelScope}` : ""}, not addressed to me)`);
+            return;
+        }
+        if (target.kind === "job") {
+            await handleJobItem(item, target);
+            return;
+        }
+        const messageText = (item.text ?? "").trim();
+        // A message can be only a file (no text): that is still a message to answer.
+        const attachmentRefs = inboxEntryAttachments(item);
+        if (!messageText && attachmentRefs.length === 0) {
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            return;
+        }
+        // Setup bot: "Explain HQ first" clicked while that question is pending is
+        // answered with the fixed explanation, with no model turn.
+        const ownerDm = target.kind === "dm" && target.peerUid === config.ownerUid;
+        if (isSetupBot && ownerDm && (await sendSetupExplanation(item, messageText, attachmentRefs.length)))
+            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} (${messageText.length} chars${attachmentRefs.length ? `, ${attachmentRefs.length} attachment${attachmentRefs.length === 1 ? "" : "s"}` : ""}, ${where})`);
+        // Rooms: an UNMENTIONED responder (a plain room message)
+        // 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);
+            }
+        };
+        // Attachments are fetched here, in the runner, so every runtime sees them
+        // the same way: the turn text names each saved file (or why it is missing).
+        let text = messageText;
+        const readDirs = [];
+        if (attachmentRefs.length > 0) {
+            const attachmentsDir = botAttachmentsDir(dir);
+            const files = await downloadTurnAttachments({
+                attachments: attachmentRefs,
+                botEntityUid: config.agentUid,
+                attachmentsDir,
+                resolveBotCompanyUids: async () => (await api.getAgent(config.agentUid)).companyMemberships ?? [],
+                ...(deps.downloadAttachment ? { download: deps.downloadAttachment } : {}),
+            });
+            for (const f of files) {
+                if (f.error)
+                    log("warn", `attachment ${f.name} on ${id} not downloaded: ${f.error}`);
+                else
+                    log("info", `attachment ${f.name} on ${id} saved (${f.sizeBytes ?? 0} bytes)`);
+            }
+            if (files.some((f) => f.localPath))
+                readDirs.push(attachmentsDir);
+            const block = attachmentTurnBlock(files);
+            text = text ? `${text}\n\n${block}` : block;
+        }
+        const sessionScope = target.kind === "room" ? target.sessionScope : dmSessionScope(target.peerUid, config.ownerUid);
+        // The turn after the app sent the explanation: tell the model it went out.
+        const setupNote = isSetupBot && ownerDm && readSetupIntroState(dir).notePending === true;
+        const ownerText = setupNote ? `${SETUP_EXPLAINED_NOTE}\n\n${text}` : text;
+        const prompt = target.kind === "room" ? await buildRoomTurn(item, target, text) : target.peerUid === config.ownerUid ? ownerText :
+            `[HQ DM sender: ${target.peerUid}; owner: ${config.ownerUid}; sender is not the owner.]\n\n${text}`;
+        const markerTarget = target.kind === "dm" ? { kind: "dm", peerUid: target.peerUid } : { kind: "room", channelId: target.channelId };
+        const { send, sendFinal, saved } = trackingSend(markerTarget, item.rootEventId);
+        const { outcome, poster } = await runTurnWithProgress({
+            marker: {
+                messageId: id,
+                target: markerTarget,
+                ...(item.rootEventId ? { rootEventId: item.rootEventId } : {}),
+                ...(thinking ? { reactionEventId: reactionId } : {}),
+            },
+            prompt,
+            sessionScope,
+            tReceived,
+            send,
+            sendFinal,
+            silenceable: target.kind === "room" && !target.mentioned,
+            ...(readDirs.length ? { readDirs } : {}),
+            ...(target.kind === "room"
+                ? { afterProgressPost: () => api.postAgentStatus(target.channelId, ROOM_THINKING_STATUS, target.rootEventId) }
+                : {}),
+        });
+        // The model saw the note once its turn ran. A turn that never started, or
+        // one held for a coding-tool sign-in, runs again and keeps the note for it.
+        if (setupNote && (outcome.ok || (outcome.started && !isRuntimeSignInFailure(outcome.excerpt)))) {
+            try {
+                patchSetupIntroState(dir, { notePending: false });
+            }
+            catch (err) {
+                log("warn", `setup intro state not updated: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (outcome.ok && ownerDm)
+            noteSetupReply(outcome.reply);
+        if (outcome.ok) {
+            // A no_reply sentinel or intentionally empty reply: ack silently, post nothing.
+            if (outcome.silent) {
+                markProcessed(dir, id, now().toISOString());
+                await api.ackInbox(config.agentUid, id);
+                clearInflight(dir, id);
+                attempts.delete(id);
+                await clearThinking();
+                log("info", `no_reply sentinel or empty reply for ${id} (${where}); acked silently`);
+                return;
+            }
+            // Known gap (#614, not changed here): a progress post counts, so a final answer that fails after one is not resent.
+            if (poster.postedCount === 0) {
+                // 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;
+            }
+            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.aborted && poster.postedCount === 0 && isRuntimeSignInFailure(outcome.excerpt)) {
+            // The tool refused before doing anything: keep the message for when it
+            // can sign in again, and say so once in this conversation.
+            clearInflight(dir, id);
+            attempts.delete(id);
+            markSignInBroken(outcome.excerpt);
+            const conversation = markerTarget.kind === "dm" ? sessionScope : `room:${markerTarget.channelId}:${item.rootEventId ?? ""}`;
+            await tellSignInNeeded(conversation, send);
+            log("warn", `kept ${id} until ${runtime.id} can sign in again`);
+            return; // un-acked: answered once the sign-in works
+        }
+        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);
+        // reasoning_only means the model produced only reasoning tokens and no text.
+        const reasoningOnly = !outcome.aborted && isReasoningOnlyError(outcome.excerpt);
+        const silenceableTurn = target.kind === "room" && !target.mentioned;
+        // Unmentioned room turn that posted nothing and was not stopped by the
+        // owner: any model failure (reasoning_only or otherwise) is a silent
+        // no-reply. The failure is already recorded above via recordTurnFailure,
+        // so we just ack quietly and never leak the raw error into the room.
+        if (!outcome.aborted && poster.postedCount === 0 && silenceableTurn) {
+            markProcessed(dir, id, now().toISOString());
+            await api.ackInbox(config.agentUid, id);
+            clearInflight(dir, id);
+            attempts.delete(id);
+            await clearThinking();
+            log("info", `unmentioned room turn ${id} failed with no post (${where}); acked silently`);
+            if (failures.exceeded(now().getTime())) {
+                await finish("failed", 0, `${FAILURE_LIMIT} model failures in 10 minutes; last: ${outcome.excerpt}`);
+            }
+            return;
+        }
+        try {
+            // DM or @-mentioned room reasoning_only: the person asked directly, so
+            // still say we did not finish — but with a plain reason, never the raw
+            // internal error string.
+            const reason = reasoningOnly ? "the model returned no answer" : failureReason(outcome);
+            await send(didNotFinishText(reason, 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();
+    // ── Lanes: conversations side by side, each conversation in order ─────────
+    /** Messages waiting per lane, in arrival order. */
+    const lanes = new Map();
+    /** Lanes with a message being handled right now. */
+    const busyLanes = new Set();
+    /** Every message queued or being handled (the inbox re-delivers until acked). */
+    const pending = new Set();
+    const running = new Set();
+    const canStart = () => !stopping && state === "running" && !hasPromotionHold(dir);
+    /** Job turns yield to people: one at a time, and never the last free slot. */
+    const isJobLane = (lane) => lane.startsWith("job:");
+    const jobLaneBudget = Math.max(1, maxParallelTurns - 1);
+    const canStartJobLane = () => [...busyLanes].filter(isJobLane).length < MAX_PARALLEL_JOB_TURNS && busyLanes.size < jobLaneBudget;
+    const pump = () => {
+        for (const [lane, queue] of lanes) {
+            if (busyLanes.size >= maxParallelTurns || !canStart())
+                return;
+            // While the sign-in is broken, one message at a time tries it, on a timer.
+            if (signInIssue && (busyLanes.size > 0 || now().getTime() < nextSignInRetryAt))
+                return;
+            if (busyLanes.has(lane))
+                continue;
+            // `continue`, never `return`: a job that cannot start yet must not hold
+            // up the owner's DM sitting behind it in the map.
+            if (isJobLane(lane) && !canStartJobLane())
+                continue;
+            const item = queue.shift();
+            if (queue.length === 0)
+                lanes.delete(lane);
+            if (!item)
+                continue;
+            busyLanes.add(lane);
+            if (signInIssue)
+                nextSignInRetryAt = now().getTime() + signInRetryMs;
+            const task = handleItem(item)
+                .catch((err) => {
+                log("warn", `inbox item ${item.messageId} failed: ${err instanceof Error ? err.message : String(err)}`);
+            })
+                .finally(() => {
+                resetInboxBackoff();
+                busyLanes.delete(lane);
+                pending.delete(item.messageId);
+                running.delete(task);
+                pump();
+            });
+            running.add(task);
+        }
+    };
+    const enqueue = (item) => {
+        if (pending.has(item.messageId))
+            return;
+        pending.add(item.messageId);
+        const lane = inboxLaneKey(item, config);
+        const queue = lanes.get(lane);
+        if (queue)
+            queue.push(item);
+        else
+            lanes.set(lane, [item]);
+    };
+    const inboxLoop = (async () => {
+        // Turns cut off by the last restart are reported before anything new runs.
+        for (const leftover of leftovers) {
+            try {
+                await recoverInflight(leftover);
+            }
+            catch (err) {
+                log("warn", `recovering ${leftover.messageId} failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        await kickoff;
+        let inboxFails = 0;
+        while (!stopping && state === "running") {
+            if (hasPromotionHold(dir))
+                break;
+            // The install under this process was updated: take nothing new, let the
+            // turns already running finish, then exit so the supervisor loads it.
+            // Queued items were never started or acked; the next process gets them.
+            if (pollForCliUpdate())
+                break;
+            // A kickoff held for a sign-in retries on the same timer as messages.
+            if (busyLanes.size === 0 &&
+                (!signInIssue || now().getTime() >= nextSignInRetryAt) &&
+                readBotConfig(dir)?.kickoffPendingSignIn) {
+                if (signInIssue)
+                    nextSignInRetryAt = now().getTime() + signInRetryMs;
+                await runKickoff().catch((err) => {
+                    log("error", `kickoff retry crashed: ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
+            // Completions the cloud has not accepted yet: re-send the report (never
+            // the work), alongside the poll rather than in front of it.
+            kickCompletionRetries();
+            const useInboxBackoff = await inboxPollBackoffEnabled().catch((error) => {
+                log("warn", `inbox poll backoff flag lookup failed (${safeErrorClass(error)}); using default-off`);
+                return false;
+            });
+            let items;
+            try {
+                items = await api.pullInbox(config.agentUid);
+                inboxFails = 0;
+                setStatus({ lastInboxPollAt: now().toISOString(), lastInboxPollOk: true, lastInboxError: undefined });
+                // One catch-up per job per wake: when several runs of the same job are
+                // pending, the newest runs and the older ones are reported skipped.
+                for (const id of planJobRuns(items, handledJobFires).superseded)
+                    supersededJobRuns.add(id);
+                if (items.length > 0)
+                    resetInboxBackoff();
+                for (const item of items)
+                    enqueue(item);
+                pump();
+                if (stopping || state !== "running")
+                    break;
+            }
+            catch (err) {
+                inboxFails += 1;
+                const message = err instanceof Error ? err.message : String(err);
+                setStatus({ lastInboxPollOk: false, lastInboxError: message.slice(0, 400) });
+                log("warn", `inbox poll failed: ${message}`);
+                if (stopping || state !== "running")
+                    break;
+                await sleep(apiPollDelayMs({ err, attempt: inboxFails - 1, intervalMs: inboxIntervalMs, random }));
+                continue;
+            }
+            if (stopping || state !== "running")
+                break;
+            if (!useInboxBackoff) {
+                inboxBackoffIndex = 0;
+                await waitForInbox(inboxIntervalMs, false);
+                continue;
+            }
+            const delayMs = items.length > 0
+                ? inboxIntervalMs
+                : inboxBackoffSteps[Math.min(inboxBackoffIndex, inboxBackoffSteps.length - 1)];
+            if (items.length === 0)
+                inboxBackoffIndex = Math.min(inboxBackoffIndex + 1, inboxBackoffSteps.length - 1);
+            await waitForInbox(delayMs, true);
+        }
+        // Stop, drain and promotion wait for the turns already running. Queued
+        // messages were never started or acked, so the inbox delivers them again.
+        while (running.size > 0)
+            await Promise.allSettled([...running]);
+        await completionRetryTask;
+    })();
+    function readStatus() {
+        return readBotStatus(dir);
+    }
+    const stop = async (mode = "abort") => {
+        // An owner stop or a promotion while an update restart drains wins: the
+        // bot then exits 0 and stays down instead of being restarted.
+        cliUpdatePending = null;
+        if (stopping) {
+            if (mode === "abort")
+                for (const turn of currentTurns)
+                    turn.abort();
+            return;
+        }
+        stopping = true;
+        activeInboxWait?.abort();
+        // 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")
+            for (const turn of currentTurns)
+                turn.abort();
+        await Promise.allSettled([heartbeatLoop, inboxLoop]);
+        await finish("stopped", 0, mode === "drain" ? "drain completed (running turns finished)" : "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")
+            return;
+        const update = cliUpdatePending;
+        if (!update) {
+            void finish("stopped", 0, "loops ended");
+            return;
+        }
+        try {
+            deps.cliUpdate?.recordRestart(update);
+        }
+        catch (err) {
+            log("warn", `could not record the update restart: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        void finish("stopped", CLI_UPDATE_RESTART_EXIT_CODE, `hq-cli updated ${update.from} -> ${update.to}; restarting to load it`, () => deps.onCliUpdateRestart?.(update, log));
+    });
+    return { stop, done, status: readStatus, idle: () => pending.size === 0 };
+}
+//# sourceMappingURL=run.js.map