@indigoai-us/hq-cli 5.345.104 → 5.345.106

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

@@ -0,0 +1,62 @@
+/**
+ * A bot whose worker belongs to an installed pack with a `setup:` block gets
+ * an auto-generated "Pack setup" section in its system prompt, and, when the
+ * pack asks for it and HQ's own setup is unfinished, a takeover section with
+ * HQ's setup worker skills (build contract section 3).
+ *
+ * scan-packages links a pack worker at `core/workers/public/<id>` ->
+ * `core/packages/<pack>/workers/<id>`, so the pack is found by resolving the
+ * worker folder's real path and checking whether it sits under
+ * `<hqRoot>/core/packages/<pack>/`.
+ */
+import type { PackSetup } from "../../types.js";
+import { type WorkerSkillSource } from "./prompt.js";
+export interface PackSetupResolveFs {
+    realpathSync: (p: string) => string;
+    existsSync: (p: string) => boolean;
+}
+/** The installed pack (name + root) a worker folder belongs to, or null. */
+export declare function findPackForWorker(hqRoot: string, workerDir: string, io?: PackSetupResolveFs): {
+    packName: string;
+    packRoot: string;
+} | null;
+export interface PackSetupPromptSections {
+    packName: string;
+    /** Absolute installed pack root. */
+    packRoot: string;
+    /** The validated `setup:` block. */
+    setup: PackSetup;
+    /** "## Finish HQ setup first", present only when the bot takes over HQ setup. */
+    takeover?: string;
+    /** "## Pack setup (...)". */
+    packSetup: string;
+}
+export interface ResolvePackSetupPromptInput {
+    hqRoot: string;
+    /** hqRoot-relative worker folder (bot.json `workerDir`). */
+    workerDir: string;
+    /** Only worker-sourced bots can belong to a pack. */
+    workerSource?: "scaffold" | "worker";
+    /** Seams for tests. */
+    io?: PackSetupResolveFs;
+    readProgressNote?: () => {
+        path: string | null;
+        note: string | null;
+    };
+    setupWorkerSkills?: (hqRoot: string) => {
+        workerDir: string;
+        skills: WorkerSkillSource[];
+    } | null;
+    log?: (level: "info" | "warn", message: string) => void;
+}
+/** HQ's setup worker folder and skills, resolved like `hq bot create --worker setup`. */
+export declare function loadSetupWorkerSkills(hqRoot: string): {
+    workerDir: string;
+    skills: WorkerSkillSource[];
+} | null;
+/**
+ * The prompt sections for a pack bot, or null when the bot's worker is not a
+ * pack worker or its pack has no valid `setup:` block.
+ */
+export declare function resolvePackSetupPrompt(input: ResolvePackSetupPromptInput): PackSetupPromptSections | null;
+//# sourceMappingURL=pack-setup.d.ts.map

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

@@ -0,0 +1,103 @@
+/**
+ * A bot whose worker belongs to an installed pack with a `setup:` block gets
+ * an auto-generated "Pack setup" section in its system prompt, and, when the
+ * pack asks for it and HQ's own setup is unfinished, a takeover section with
+ * HQ's setup worker skills (build contract section 3).
+ *
+ * scan-packages links a pack worker at `core/workers/public/<id>` ->
+ * `core/packages/<pack>/workers/<id>`, so the pack is found by resolving the
+ * worker folder's real path and checking whether it sits under
+ * `<hqRoot>/core/packages/<pack>/`.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readInstalledPackSetup } from "../packages/setup-block.js";
+import { renderPackSetupSection } from "../packages/setup-prompt.js";
+import { decideTakeover, readHqSetupProgressNote, renderTakeoverSection } from "../packages/setup-takeover.js";
+import { readPackManifest } from "../../utils/pack-contributions.js";
+import { readPromptSources } from "./prompt.js";
+import { resolveBotWorker } from "./worker-source.js";
+import { SETUP_BOT_WORKER_ID } from "./config.js";
+const defaultFs = {
+    realpathSync: (p) => fs.realpathSync(p),
+    existsSync: (p) => fs.existsSync(p),
+};
+/** The installed pack (name + root) a worker folder belongs to, or null. */
+export function findPackForWorker(hqRoot, workerDir, io = defaultFs) {
+    let packagesRoot;
+    let workerReal;
+    try {
+        packagesRoot = io.realpathSync(path.join(hqRoot, "core", "packages"));
+        workerReal = io.realpathSync(path.isAbsolute(workerDir) ? workerDir : path.join(hqRoot, workerDir));
+    }
+    catch {
+        return null;
+    }
+    const rel = path.relative(packagesRoot, workerReal);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
+        return null;
+    const packName = rel.split(path.sep)[0];
+    if (!packName || packName.startsWith("."))
+        return null;
+    return { packName, packRoot: path.join(packagesRoot, packName) };
+}
+/** HQ's setup worker folder and skills, resolved like `hq bot create --worker setup`. */
+export function loadSetupWorkerSkills(hqRoot) {
+    try {
+        const worker = resolveBotWorker(hqRoot, SETUP_BOT_WORKER_ID);
+        const sources = readPromptSources(hqRoot, worker.path, undefined, { workerSource: "worker" });
+        return { workerDir: worker.path, skills: sources.worker?.skills ?? [] };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The prompt sections for a pack bot, or null when the bot's worker is not a
+ * pack worker or its pack has no valid `setup:` block.
+ */
+export function resolvePackSetupPrompt(input) {
+    if (input.workerSource !== "worker")
+        return null;
+    const log = input.log ?? (() => { });
+    const found = findPackForWorker(input.hqRoot, input.workerDir, input.io);
+    if (!found)
+        return null;
+    const { manifest, error } = readPackManifest(found.packRoot);
+    if (!manifest) {
+        log("warn", `worker ${input.workerDir} belongs to pack ${found.packName} but its package.yaml is unreadable (${error ?? "unknown"}); no pack setup section`);
+        return null;
+    }
+    if (manifest.setup === undefined)
+        return null;
+    const setup = readInstalledPackSetup(manifest, found.packRoot, input.io?.existsSync);
+    if (!setup) {
+        log("warn", `pack ${found.packName} has a setup: block that does not validate; no pack setup section`);
+        return null;
+    }
+    const promptInput = { packName: found.packName, packRoot: found.packRoot, setup };
+    const sections = {
+        packName: found.packName,
+        packRoot: found.packRoot,
+        setup,
+        packSetup: renderPackSetupSection(promptInput),
+    };
+    if (setup.takeover_setup) {
+        const progress = (input.readProgressNote ?? readHqSetupProgressNote)();
+        if (decideTakeover({ takeoverSetup: true, progressNote: progress.note })) {
+            const setupWorker = (input.setupWorkerSkills ?? loadSetupWorkerSkills)(input.hqRoot);
+            sections.takeover = renderTakeoverSection({
+                packName: found.packName,
+                setupWorkerDir: setupWorker?.workerDir ?? path.join("core", "workers", SETUP_BOT_WORKER_ID),
+                skills: setupWorker?.skills ?? [],
+                progressNotePath: progress.path,
+            });
+            log("info", `pack ${found.packName}: HQ setup is not finished; this bot finishes it before the pack setup`);
+        }
+        else {
+            log("info", `pack ${found.packName}: HQ setup is finished; going straight to the pack setup`);
+        }
+    }
+    return sections;
+}
+//# sourceMappingURL=pack-setup.js.map

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

@@ -93,6 +93,14 @@ export interface BuildSystemPromptInput {
     kind?: BotKind;
     /** Company bots: the slugs of the companies the bot is a member of. */
     companies?: string[];
+    /**
+     * Pack bot: the auto-generated "Pack setup" section (and the HQ setup
+     * takeover section when it applies), rendered by lib/bot/pack-setup.ts.
+     */
+    packSetup?: {
+        takeover?: string;
+        packSetup: string;
+    } | null;
     /** hqRoot-relative (default `${workerDir}/memory`) or absolute. */
     memoryDir?: string;
 }

package/dist/lib/bot/prompt.js

@@ -373,6 +373,11 @@ export function buildSystemPrompt(input) {
             parts.push(`## Persona (${path.join(input.workerDir, "persona.md")})\n\n${input.sources.persona.trim()}`);
         }
     }
+    if (input.packSetup) {
+        if (input.packSetup.takeover)
+            parts.push(input.packSetup.takeover);
+        parts.push(input.packSetup.packSetup);
+    }
     if (input.sources.memory.length > 0) {
         const blocks = input.sources.memory.map((m) => `### ${m.name}\n\n${m.body.trim()}`);
         parts.push(`## Memory (${memoryDir}/)\n\n${blocks.join("\n\n")}`);

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

@@ -201,13 +201,25 @@ export declare const KICKOFF_MESSAGE_ID = "kickoff";
 export declare function turnEnv(base: NodeJS.ProcessEnv, kind: BotKind, agentUid?: string, companySlug?: string): NodeJS.ProcessEnv;
 /** The core worker HQ's setup bot runs. */
 export declare const SETUP_WORKER_ID = "setup";
+/**
+ * The executable a bot's turns will spawn, for the start-up log: an absolute
+ * path when the runtime found one (the HQ app toolchain, a system prefix, the
+ * Claude desktop app), the bare name when it relies on PATH, or "not found"
+ * when the bare name is on no PATH entry either.
+ */
+export declare function describeRuntimeBinary(runtime: BotRuntime, env: NodeJS.ProcessEnv, cwd: string): string;
 /** The one message a person gets when a turn on their message did not finish. */
 export declare function didNotFinishText(reason: string, progressPosted: boolean): string;
 export { containsNoReplySentinel };
 /** Grok emits is_error with this message when the model produces only reasoning tokens. */
 export declare function isReasoningOnlyError(excerpt: string): boolean;
-/** The one note a person gets when the bot pauses after repeated failures. */
-export declare function holdNoticeText(holdMs: number, messagePending: boolean): string;
+/**
+ * The one note a person gets when the bot pauses after repeated failures. With
+ * `reason` (the plain failure text of the last turn) it is the summary that
+ * replaces the fifth per-turn line: one message for the run of failures, with
+ * what went wrong and the one next step.
+ */
+export declare function holdNoticeText(holdMs: number, messagePending: boolean, reason?: string): string;
 /** Owner stop, `hq bot stop` or `hq bot restart`: all arrive as the same signal. */
 export declare const STOPPED_BY_OWNER_REASON = "I was stopped before I was done";
 export declare const RESTARTED_REASON = "I was restarted while I was working on it";
@@ -229,4 +241,8 @@ export interface BotHandle {
 export declare function inboxLaneKey(item: InboxItem, config: Pick<BotConfig, "ownerUid" | "agentUid" | "name">): string;
 export declare function preflightCreds(dir: string, config: BotConfig): string | null;
 export declare function runBot(deps: BotRunDeps): Promise<BotHandle>;
+/** True for a setup note the desktop app sent, not words the person typed. */
+export declare function isAppSetupNote(text: string): boolean;
+/** Put ahead of an app setup note: fold it in, and stay quiet unless it changes what to say. */
+export declare const APP_SETUP_NOTE_TURN_NOTE: string;
 //# sourceMappingURL=run.d.ts.map

package/dist/lib/bot/run.js

@@ -63,10 +63,13 @@ import { containsNoReplySentinel, ProgressPoster, } from "./progress.js";
 import { splitBody } from "./split.js";
 import { createBotLogger } from "./log.js";
 import { buildSystemPrompt, introDmText, readPromptSources } from "./prompt.js";
+import { resolvePackSetupPrompt } from "./pack-setup.js";
+import { writeLeanClaudeSettings } from "./lean-settings.js";
+import { companyDisplayName, firstQuestionNote, questionDefault, questionMessage, readPackSetupState, writePackSetupState, } from "./pack-setup-driver.js";
 import { loadSetupExplainer, patchSetupIntroState, readSetupIntroState, readSetupProgressIntro, replyOffersExplain, SETUP_EXPLAINED_NOTE, setupExplainDue, } from "./setup-explain.js";
 import { detectCodingToolActivity, SIGNIFICANT_CODING_TOOL_ACTIVITY, } from "./coding-tool-activity.js";
 import { setupKeptHereNote, setupOfferAnsweredInWordsNote, setupToolOfferAnswer, setupToolOfferText, setupWelcomeOpening, } from "./setup-tool-offer.js";
-import { FALLBACK_CLAUDE_PERMISSION_MODE, isClaudeBypassDisabled } from "./runtime/claude.js";
+import { FALLBACK_CLAUDE_PERMISSION_MODE, isClaudeBypassDisabled, onPath } from "./runtime/claude.js";
 import { runRuntimeTurn, RuntimeError } from "./runtime/index.js";
 import { botAttachmentsDir, dmSessionScope, isDmSessionScope } from "./paths.js";
 import { appendDmHistory, dmHistoryHasModelThread, markDmHistoryModelTurn, readDmHistory, withRecentDmHistory } from "./dm-history.js";
@@ -78,7 +81,7 @@ import { buildJobTurnPrompt, isCatchUpRun, isJobItem, jobReportHeader, jobRunOut
 import { botJobQuietOptionEnabled } from "./job-quiet-flag.js";
 import { clearPendingJobCompletion, isCompletionDue, isCompletionExpired, isCompletionForOtherAgent, readPendingJobCompletions, recordPendingJobCompletion } from "./job-completions.js";
 import { SIGN_IN_RETRY_MS, signInNeededText } from "./runtime-sign-in.js";
-import { classifyRuntimeError, classifyRuntimeFailure, runtimeDidNotFinishText, runtimeFailureReason, runtimeFailureText, runtimeRepairNotice, } from "./runtime-failure.js";
+import { classifyRuntimeError, classifyRuntimeFailure, runtimeDidNotFinishText, runtimeFailureReason, runtimeFailureText, runtimeRepairNotice, withRetrySuggestion, } from "./runtime-failure.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";
@@ -183,6 +186,24 @@ export function turnEnv(base, kind, agentUid, companySlug) {
 }
 /** The core worker HQ's setup bot runs. */
 export const SETUP_WORKER_ID = SETUP_BOT_WORKER_ID;
+/**
+ * The executable a bot's turns will spawn, for the start-up log: an absolute
+ * path when the runtime found one (the HQ app toolchain, a system prefix, the
+ * Claude desktop app), the bare name when it relies on PATH, or "not found"
+ * when the bare name is on no PATH entry either.
+ */
+export function describeRuntimeBinary(runtime, env, cwd) {
+    let binary;
+    try {
+        binary = runtime.resolveBinary?.(env, cwd, process.platform) ?? runtime.binary;
+    }
+    catch {
+        binary = runtime.binary;
+    }
+    if (path.isAbsolute(binary))
+        return binary;
+    return onPath(binary, env) ? `${binary} (on PATH)` : `${binary} (not found on PATH; turns will fail as not-installed)`;
+}
 /** 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]+$/, "");
@@ -194,10 +215,16 @@ export { containsNoReplySentinel };
 export function isReasoningOnlyError(excerpt) {
     return excerpt.includes("reasoning_only");
 }
-/** The one note a person gets when the bot pauses after repeated failures. */
-export function holdNoticeText(holdMs, messagePending) {
+/**
+ * The one note a person gets when the bot pauses after repeated failures. With
+ * `reason` (the plain failure text of the last turn) it is the summary that
+ * replaces the fifth per-turn line: one message for the run of failures, with
+ * what went wrong and the one next step.
+ */
+export function holdNoticeText(holdMs, messagePending, reason) {
     const minutes = Math.max(1, Math.round(holdMs / 60_000));
-    return `I'm pausing for ${minutes} minute${minutes === 1 ? "" : "s"} after a few failed tries, then I'll ${messagePending ? "pick your message up" : "pick up from your next message"}.`;
+    const base = `I'm pausing for ${minutes} minute${minutes === 1 ? "" : "s"} after ${reason ? `${FAILURE_LIMIT} failed tries` : "a few failed tries"}, then I'll ${messagePending ? "pick your message up" : "pick up from your next message"}.`;
+    return reason ? `${base} ${reason}` : base;
 }
 /** 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";
@@ -459,6 +486,7 @@ export async function runBot(deps) {
     // 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}`);
+    log("info", `${runtime.id} binary: ${describeRuntimeBinary(runtime, turnEnv(process.env, kind, config.agentUid, config.companySlug), turnCwd)}`);
     deps.cliUpdate?.startup(log);
     try {
         const record = await api.getAgent(config.agentUid);
@@ -479,8 +507,19 @@ export async function runBot(deps) {
         return { stop: async () => { }, done, status: () => null, idle: () => true };
     }
     // ── System prompt ──────────────────────────────────────────────────────────
+    // A pack worker's bot gets the pack's "Pack setup" section (and the HQ setup
+    // takeover when the pack asks for it and setup is unfinished).
+    // Resolved even under a prompt override: the instant pack setup reads it too.
+    let packSetup = null;
+    try {
+        packSetup = resolvePackSetupPrompt({ hqRoot: config.hqRoot, workerDir: config.workerDir, workerSource: config.workerSource, log });
+    }
+    catch (err) {
+        log("warn", `pack setup section skipped: ${err instanceof Error ? err.message : String(err)}`);
+    }
     const systemPrompt = deps.systemPromptOverride ??
         buildSystemPrompt({
+            packSetup,
             botName: config.name,
             ...(config.displayName ? { displayName: config.displayName } : {}),
             agentUid: config.agentUid,
@@ -502,6 +541,16 @@ export async function runBot(deps) {
     const systemPromptFile = path.join(dir, "system-prompt.md");
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     fs.writeFileSync(systemPromptFile, systemPrompt, { mode: 0o600 });
+    // A lean bot's Claude Code turns load only HQ's tool hooks (lean-settings.ts).
+    let leanSettingsFile = null;
+    if (config.lean && config.runtime === "claude") {
+        try {
+            leanSettingsFile = writeLeanClaudeSettings(dir, config.hqRoot);
+        }
+        catch (err) {
+            log("warn", `lean settings not written; turns load the full settings: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     if (hasPromotionHold(dir)) {
         await finish("stopped", 0, "local bot held for cloud promotion");
         return { stop: async () => { }, done, status: () => null, idle: () => true };
@@ -580,7 +629,7 @@ export async function runBot(deps) {
      */
     const modelHoldMs = Math.max(0, deps.modelHoldMs ?? FAILURE_WINDOW_MS);
     let modelHoldUntil = 0;
-    const holdAfterFailures = async (excerpt, tell, messagePending = false) => {
+    const holdAfterFailures = async (excerpt, tell, messagePending = false, cls) => {
         const until = now().getTime() + modelHoldMs;
         modelHoldUntil = until;
         failures.clear();
@@ -592,7 +641,7 @@ export async function runBot(deps) {
         // nothing while their next messages wait out the hold.
         if (tell) {
             try {
-                await tell(holdNoticeText(modelHoldMs, messagePending));
+                await tell(holdNoticeText(modelHoldMs, messagePending, cls ? runtimeFailureText(cls, runtime.id) : undefined));
             }
             catch (err) {
                 log("warn", `could not say that turns are on hold: ${err instanceof Error ? err.message : String(err)}`);
@@ -863,6 +912,7 @@ export async function runBot(deps) {
                 sessionId: session?.sessionId,
                 ...(live.model ? { model: live.model } : {}),
                 ...(live.effort ? { effort: live.effort } : {}),
+                ...(leanSettingsFile ? { leanSettingsFile } : {}),
                 ...bind,
                 ...stream,
             });
@@ -1046,6 +1096,12 @@ export async function runBot(deps) {
      * A server that refuses the block (400) still gets the plain body.
      */
     const postRepair = async (target, notice, rootEventId) => {
+        if (target.kind === "dm" && !notice.richContent) {
+            // No repair card for this class: a tap-to-answer Retry so the failure is
+            // never a dead end in the person's DM (rooms get the plain line).
+            await api.sendDm({ toPersonUid: target.peerUid, body: withRetrySuggestion(notice.text), audience: "human", ...(rootEventId ? { rootEventId } : {}) });
+            return;
+        }
         if (target.kind === "dm" && notice.richContent) {
             const base = { toPersonUid: target.peerUid, body: notice.text, audience: "human", ...(rootEventId ? { rootEventId } : {}) };
             try {
@@ -1400,12 +1456,56 @@ export async function runBot(deps) {
         recordToolOffer(tool);
         return true;
     };
+    // ── Instant first question (pack-setup-driver.ts) ─────────────────────────
+    /** The one company this pack is set up in: the owner's only company with a folder here. */
+    const resolvePackFirm = async () => {
+        if (!deps.ownerContext)
+            return null;
+        const owner = await deps.ownerContext();
+        if (owner.status !== "ok")
+            return null;
+        const local = owner.companies
+            .map((c) => (c.companySlug ?? "").trim())
+            .filter((slug, i, all) => slug && all.indexOf(slug) === i && fs.existsSync(path.join(config.hqRoot, "companies", slug)));
+        return local.length === 1 ? local[0] : null;
+    };
+    /**
+     * First start of a pack bot: send the first setup question from code. False
+     * (run the kickoff model turn) when there is no pack setup, it already
+     * started, or the owner has no single company here to set the pack up in.
+     */
+    const startPackSetup = async () => {
+        if (!packSetup || readPackSetupState(dir))
+            return false;
+        try {
+            const firm = await resolvePackFirm();
+            if (!firm) {
+                log("info", "pack setup: no single company on this computer to set up in; the kickoff turn handles it");
+                return false;
+            }
+            const q = packSetup.setup.questions[0];
+            const firmName = companyDisplayName(config.hqRoot, firm);
+            await sendToTarget({ kind: "dm", peerUid: config.ownerUid }, questionMessage(q, questionDefault(q, { firmName })), undefined, "human");
+            writePackSetupState(dir, { v: 1, pack: packSetup.packName, firm, askedFirst: q.id, modelNotePending: true, updatedAt: now().toISOString() });
+            log("info", `pack setup for ${firm}: asked ${q.id} from code (no kickoff turn)`);
+            return true;
+        }
+        catch (err) {
+            log("warn", `first pack setup question not sent from code (${err instanceof Error ? err.message : String(err)}); running the kickoff`);
+            return false;
+        }
+    };
     const runKickoff = async (introEventId) => {
         const prompt = (config.kickoff ?? "").trim();
         if (!prompt || stopping || state !== "running")
             return;
         if (isSetupBot && (await offerCodingTool()))
             return;
+        if (packSetup && (await startPackSetup())) {
+            if (readBotConfig(dir)?.kickoffPendingSignIn)
+                patchBotConfig(dir, { kickoffPendingSignIn: false });
+            return;
+        }
         const peerUid = config.ownerUid;
         const tReceived = now().getTime();
         log("info", `kickoff turn starting (${prompt.length} chars)`);
@@ -1462,6 +1562,13 @@ export async function runBot(deps) {
         // The person sees one plain sentence and one next step; the raw runtime
         // text is in the log (recordTurnFailure) and status.json only.
         const cls = failureClass(outcome);
+        if (!outcome.aborted && failures.exceeded(now().getTime())) {
+            // The failure that hit the limit: one summary carries the reason and the pause.
+            clearInflight(dir, KICKOFF_MESSAGE_ID);
+            log("error", `kickoff turn failed (${count}/${FAILURE_LIMIT} in window); not retried`);
+            await holdAfterFailures(outcome.excerpt, sendToPerson, false, cls);
+            return;
+        }
         const notice = outcome.aborted
             ? { cls, text: `${didNotFinishText(failureReason(outcome), poster.postedCount > 0)} Send me any message and I'll pick up from there.` }
             : runtimeRepairNotice({
@@ -1479,9 +1586,6 @@ export async function runBot(deps) {
             /* 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 holdAfterFailures(outcome.excerpt, sendToPerson);
-        }
     };
     /**
      * One fired job: a model turn on the job's own prompt, in the job's own
@@ -1629,12 +1733,14 @@ export async function runBot(deps) {
             // The model never ran, so nothing happened outside this Mac: retry.
             clearInflight(dir, id);
             const { excerpt } = recordTurnFailure(outcome.error, target.sessionScope);
+            const cls = classifyRuntimeError(outcome.error);
             if (failures.exceeded(now().getTime())) {
-                await holdAfterFailures(excerpt, sendToPerson, true);
+                await holdAfterFailures(excerpt, sendToPerson, true, cls);
                 return;
             }
-            if (attempt >= MAX_ATTEMPTS_PER_MESSAGE) {
-                const plain = runtimeFailureText(classifyRuntimeError(outcome.error), runtime.id);
+            // A missing tool does not come back between retries: say so now.
+            if (attempt >= MAX_ATTEMPTS_PER_MESSAGE || cls === "not-installed") {
+                const plain = runtimeFailureText(cls, runtime.id);
                 await sendToPerson(`I couldn't run this one. ${plain}`).catch(() => undefined);
                 await completeJobRun(jobId, id, { status: "failed", output: jobRunOutput(plain), disposition: `${runtime.id} could not be started` });
                 markReported("failed");
@@ -1674,7 +1780,7 @@ export async function runBot(deps) {
         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 holdAfterFailures(outcome.excerpt, sendToPerson);
+            await holdAfterFailures(outcome.excerpt, sendToPerson, false, failureClass(outcome));
         }
     };
     /**
@@ -1865,14 +1971,24 @@ export async function runBot(deps) {
         const toolOffer = isSetupBot && ownerDm ? pendingToolOffer() : null;
         const toolAnswer = toolOffer ? setupToolOfferAnswer(messageText, attachmentRefs.length) : null;
         const kickoffPrompt = (config.kickoff ?? "").trim();
+        // While (or right after) the app runs the pack setup, the model is told where it stands.
+        const packState = packSetup && ownerDm ? readPackSetupState(dir) : null;
+        const packTurnNote = packSetup && packState?.modelNotePending ? firstQuestionNote(packSetup.setup, packState, companyDisplayName(config.hqRoot, packState.firm)) : null;
         const ownerText = toolOffer && toolAnswer === "kept_here" && kickoffPrompt
             ? `${setupKeptHereNote(toolOffer)}\n\n${kickoffPrompt}`
             : toolOffer
                 ? `${setupOfferAnsweredInWordsNote(toolOffer)}\n\n${text}`
                 : setupNote
                     ? `${SETUP_EXPLAINED_NOTE}\n\n${text}`
-                    : text;
-        const prompt = target.kind === "room" ? await buildRoomTurn(item, target, text) : target.peerUid === config.ownerUid ? ownerText :
+                    : packTurnNote
+                        ? `${packTurnNote}\n\n${text}`
+                        : text;
+        // A note the desktop app sends the setup bot as it finishes visual setup
+        // steps. It often lands while the bot's previous question is still open;
+        // answering every note re-posted that question (three times in a row on
+        // 2026-10-12). Such a turn may stay quiet.
+        const appSetupNote = isSetupBot && ownerDm && isAppSetupNote(messageText);
+        const prompt = target.kind === "room" ? await buildRoomTurn(item, target, text) : target.peerUid === config.ownerUid ? (appSetupNote ? `${APP_SETUP_NOTE_TURN_NOTE}\n\n${ownerText}` : 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 { sendProgress, sendToPerson, saved } = trackingSend(markerTarget, item.rootEventId);
@@ -1888,7 +2004,7 @@ export async function runBot(deps) {
             tReceived,
             sendProgress,
             sendToPerson,
-            silenceable: target.kind === "room" && !target.mentioned,
+            silenceable: (target.kind === "room" && !target.mentioned) || appSetupNote,
             ...(readDirs.length ? { readDirs } : {}),
             ...(target.kind === "dm" ? { historyEventId: item.eventId ?? id } : {}),
             ...(target.kind === "room"
@@ -1917,6 +2033,11 @@ export async function runBot(deps) {
         }
         if (outcome.ok && ownerDm)
             noteSetupReply(outcome.reply);
+        if (outcome.ok && packState?.modelNotePending) {
+            const latest = readPackSetupState(dir);
+            if (latest)
+                writePackSetupState(dir, { ...latest, modelNotePending: false, updatedAt: now().toISOString() });
+        }
         if (outcome.ok) {
             // A no_reply sentinel or intentionally empty reply: ack silently, post nothing.
             if (outcome.silent) {
@@ -1966,14 +2087,17 @@ export async function runBot(deps) {
             // outside this Mac, so retrying is safe.
             clearInflight(dir, id);
             const { excerpt } = recordTurnFailure(outcome.error, sessionScope);
+            const cls = classifyRuntimeError(outcome.error);
             if (failures.exceeded(now().getTime())) {
-                await holdAfterFailures(excerpt, sendToPerson, true);
+                await holdAfterFailures(excerpt, sendToPerson, true, cls);
                 return;
             }
-            if (attempt >= MAX_ATTEMPTS_PER_MESSAGE) {
+            // A missing tool does not come back between retries: tell the person on
+            // the first attempt (with Retry) instead of after a silent minute.
+            if (attempt >= MAX_ATTEMPTS_PER_MESSAGE || cls === "not-installed") {
                 try {
                     await postRepair(markerTarget, runtimeRepairNotice({
-                        cls: classifyRuntimeError(outcome.error),
+                        cls,
                         runtime: runtime.id,
                         botName: config.name,
                         context: "message",
@@ -2010,15 +2134,21 @@ export async function runBot(deps) {
             log("info", `unmentioned room turn ${id} failed with no post (${where}); acked silently`);
             // Nobody asked the bot here, so the hold note goes to the owner's DM, not the room.
             if (failures.exceeded(now().getTime())) {
-                await holdAfterFailures(outcome.excerpt, (body) => sendToTarget({ kind: "dm", peerUid: config.ownerUid }, body, undefined, "human"));
+                await holdAfterFailures(outcome.excerpt, (body) => sendToTarget({ kind: "dm", peerUid: config.ownerUid }, body, undefined, "human"), false, failureClass(outcome));
             }
             return;
         }
+        const holdNow = !outcome.aborted && failures.exceeded(now().getTime());
         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.
-            if (reasoningOnly || outcome.aborted) {
+            if (holdNow) {
+                // The failure that hit the limit: one summary (reason, next step, the
+                // pause) instead of a per-turn line followed by a pause note.
+                await holdAfterFailures(outcome.excerpt, (body) => sendToPerson(body), false, failureClass(outcome));
+            }
+            else if (reasoningOnly || outcome.aborted) {
                 const reason = reasoningOnly ? "the model returned no answer" : failureReason(outcome);
                 await sendToPerson(didNotFinishText(reason, poster.postedCount > 0));
             }
@@ -2044,9 +2174,6 @@ export async function runBot(deps) {
         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 holdAfterFailures(outcome.excerpt, sendToPerson);
-        }
     };
     // 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.
@@ -2259,4 +2386,15 @@ export async function runBot(deps) {
     });
     return { stop, done, status: readStatus, idle: () => pending.size === 0 };
 }
+/** The prefix the HQ desktop app puts on the setup notes it sends the setup bot. */
+const APP_SETUP_NOTE_PREFIX = "Setup note from the HQ desktop app:";
+/** True for a setup note the desktop app sent, not words the person typed. */
+export function isAppSetupNote(text) {
+    return text.trimStart().startsWith(APP_SETUP_NOTE_PREFIX);
+}
+/** Put ahead of an app setup note: fold it in, and stay quiet unless it changes what to say. */
+export const APP_SETUP_NOTE_TURN_NOTE = "[This message is a setup note from the HQ desktop app, not words from the person. Record what it settles. " +
+    "If you already asked the person something that is still unanswered and this note does not change it, reply with exactly " +
+    '{"action":"no_reply"} and nothing else, so nothing is posted. Never repeat a question you already asked. ' +
+    "Write to the person only when the note changes what they need to know or answer next, in one or two sentences.]";
 //# sourceMappingURL=run.js.map

package/dist/lib/bot/runtime/claude.d.ts

@@ -45,6 +45,31 @@ export declare function onPath(name: string, env: NodeJS.ProcessEnv): boolean;
  * skipped), matching the HQ desktop app's own lookup.
  */
 export declare function bundledClaudeBin(homeDir?: string): string | null;
-export declare function resolveClaudeBinary(env: NodeJS.ProcessEnv, homeDir?: string, platform?: NodeJS.Platform, cwd?: string): string;
-export declare function createClaudeRuntime(env?: NodeJS.ProcessEnv): BotRuntime;
+/**
+ * Where a bot looks for `claude`, in order, outside the PATH walk. The HQ
+ * desktop app's toolchain comes first: on a clean Mac it is the only copy, and
+ * it is the one the app keeps updated. Then the usual install prefixes, so a
+ * bot under launchd (no shell profile) still finds a Homebrew or npm global
+ * install even when its PATH is thin.
+ */
+export declare const CLAUDE_SYSTEM_BIN_DIRS: readonly ["/usr/local/bin", "/opt/homebrew/bin", "/usr/bin"];
+/**
+ * The `claude` a bot spawns. Order (contract "Claude resolution for bots"):
+ *
+ *   1. `~/Library/Application Support/Indigo HQ/toolchain/npm-global/bin/claude`
+ *      (the HQ app's own install; macOS only)
+ *   2. /usr/local/bin, /opt/homebrew/bin, /usr/bin
+ *   3. PATH (returned as the bare name, so the spawn uses the same lookup)
+ *   4. the Claude desktop app's bundled Claude Code
+ *   5. the bare name, so the failure reads "claude is not installed".
+ *
+ * Absolute paths come back for 1, 2 and 4 so the bot log can say which one
+ * ran.
+ */
+export declare function resolveClaudeBinary(env: NodeJS.ProcessEnv, homeDir?: string, platform?: NodeJS.Platform, cwd?: string, systemBinDirs?: readonly string[]): string;
+export interface ClaudeRuntimeOptions {
+    /** Install prefixes checked after the HQ app toolchain (test seam; default CLAUDE_SYSTEM_BIN_DIRS). */
+    systemBinDirs?: readonly string[];
+}
+export declare function createClaudeRuntime(env?: NodeJS.ProcessEnv, opts?: ClaudeRuntimeOptions): BotRuntime;
 //# sourceMappingURL=claude.d.ts.map