@indigoai-us/hq-cli 5.313.0 → 5.314.0

package/dist/lib/bot/run.js

@@ -1,1869 +0,0 @@
-/**
- * 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 { 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 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 ? { 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;
-            // 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 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,
-        });
-        if (outcome.ok) {
-            if (!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({ 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