@indigoai-us/hq-cli 5.345.103 → 5.345.105

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

package/dist/lib/bot/runtime/claude.js

@@ -19,6 +19,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { messagesStreamEvents, messagesStreamFailure, messagesStreamResult } from "./messages-stream.js";
+import { hqAppToolchainBin } from "../toolchain.js";
 import { resolveRuntimeBinary } from "./windows.js";
 export const CLAUDE_PERMISSION_MODE_ENV = "HQ_BOT_CLAUDE_PERMISSION_MODE";
 export const DEFAULT_CLAUDE_PERMISSION_MODE = "bypassPermissions";
@@ -104,18 +105,59 @@ export function bundledClaudeBin(homeDir = os.homedir()) {
     });
     return candidates.at(-1)?.bin ?? null;
 }
-export function resolveClaudeBinary(env, homeDir, platform = process.platform, cwd = process.cwd()) {
+/**
+ * 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 const CLAUDE_SYSTEM_BIN_DIRS = ["/usr/local/bin", "/opt/homebrew/bin", "/usr/bin"];
+function executableAt(file) {
+    try {
+        fs.accessSync(file, fs.constants.X_OK);
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function resolveClaudeBinary(env, homeDir, platform = process.platform, cwd = process.cwd(), systemBinDirs = CLAUDE_SYSTEM_BIN_DIRS) {
     if (platform === "win32")
         return resolveRuntimeBinary("claude", env, platform, fs.existsSync, cwd);
+    const home = homeDir ?? env.HOME ?? os.homedir();
+    if (platform === "darwin") {
+        const toolchain = hqAppToolchainBin("claude", home);
+        if (executableAt(toolchain))
+            return toolchain;
+    }
+    for (const dir of systemBinDirs) {
+        const candidate = path.join(dir, "claude");
+        if (executableAt(candidate))
+            return candidate;
+    }
     if (onPath("claude", env))
         return "claude";
-    return bundledClaudeBin(homeDir ?? env.HOME ?? os.homedir()) ?? "claude";
+    return bundledClaudeBin(home) ?? "claude";
 }
-export function createClaudeRuntime(env = process.env) {
+export function createClaudeRuntime(env = process.env, opts = {}) {
     return {
         id: "claude",
         binary: "claude",
-        resolveBinary: (turnEnv, cwd, platform) => resolveClaudeBinary(turnEnv, undefined, platform ?? process.platform, cwd),
+        resolveBinary: (turnEnv, cwd, platform) => resolveClaudeBinary(turnEnv, undefined, platform ?? process.platform, cwd, opts.systemBinDirs ?? CLAUDE_SYSTEM_BIN_DIRS),
         buildArgs(input, scratch) {
             const usesWindowsStdin = input.platform === "win32";
             const args = [
@@ -142,6 +184,9 @@ export function createClaudeRuntime(env = process.env) {
             }
             if (input.model)
                 args.push("--model", input.model);
+            if (input.leanSettingsFile) {
+                args.push("--strict-mcp-config", "--setting-sources", "", "--settings", input.leanSettingsFile);
+            }
             if (input.sessionId)
                 args.push("--resume", input.sessionId);
             else

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

@@ -33,6 +33,11 @@ export interface RuntimeTurnInput {
     sessionId?: string;
     /** Optional model override. */
     model?: string;
+    /**
+     * Claude only: a lean turn. The settings file holds HQ's tool hooks; the turn
+     * loads no other settings, plugins or MCP servers (BotConfig.lean).
+     */
+    leanSettingsFile?: string;
     /** Thinking level for the CLI (runtimes fall back to medium). */
     effort?: string;
     /**

package/dist/lib/bot/runtime-failure.d.ts

@@ -89,7 +89,7 @@ export interface RuntimeRepairNotice {
     cls: RuntimeFailureClass;
     /** The plain DM body. */
     text: string;
-    /** Absent for `not-installed` and `unknown`: those get the plain text only. */
+    /** Absent for `not-installed` and `unknown`: those get the plain text (plus a Retry suggestion in a DM). */
     richContent?: RuntimeRichContent;
 }
 export declare function runtimeRepairBlock(args: {
@@ -99,7 +99,23 @@ export declare function runtimeRepairBlock(args: {
     retryOf?: string;
     suggestedModel?: string;
 }): RuntimeRepairBlock;
-/** The plain body plus, for a repairable class, the repair block. */
+/** The tap-to-answer button under a failure that carries no repair card. */
+export declare const RETRY_SUGGESTION = "Retry";
+/**
+ * The `hq-block` suggestions envelope the desktop draws as buttons (the same
+ * one the setup bot uses for its questions). Tapping sends the text back as
+ * the person's next message, so a failed turn is never a dead end.
+ */
+export declare function suggestionsBlock(items: string[]): string;
+/** `text` followed by a one-button Retry envelope. */
+export declare function withRetrySuggestion(text: string): string;
+/**
+ * The plain body plus, for a repairable class, the repair block. Classes
+ * without a card (`not-installed`, `unknown`) get the plain text; the DM post
+ * path adds a Retry suggestion under it (see run.ts postRepair): on 2026-10-11
+ * a fresh bot whose Claude Code was missing left the person with nothing to
+ * press.
+ */
 export declare function runtimeRepairNotice(args: {
     cls: RuntimeFailureClass;
     runtime: BotRuntimeId | string;

package/dist/lib/bot/runtime-failure.js

@@ -155,7 +155,27 @@ export function runtimeRepairBlock(args) {
         ...(args.suggestedModel ? { suggestedModel: args.suggestedModel.slice(0, 128) } : {}),
     };
 }
-/** The plain body plus, for a repairable class, the repair block. */
+/** The tap-to-answer button under a failure that carries no repair card. */
+export const RETRY_SUGGESTION = "Retry";
+/**
+ * The `hq-block` suggestions envelope the desktop draws as buttons (the same
+ * one the setup bot uses for its questions). Tapping sends the text back as
+ * the person's next message, so a failed turn is never a dead end.
+ */
+export function suggestionsBlock(items) {
+    return "```hq-block\n" + JSON.stringify({ v: 1, blocks: [{ kind: "suggestions", items }] }) + "\n```";
+}
+/** `text` followed by a one-button Retry envelope. */
+export function withRetrySuggestion(text) {
+    return `${text}\n\n${suggestionsBlock([RETRY_SUGGESTION])}`;
+}
+/**
+ * The plain body plus, for a repairable class, the repair block. Classes
+ * without a card (`not-installed`, `unknown`) get the plain text; the DM post
+ * path adds a Retry suggestion under it (see run.ts postRepair): on 2026-10-11
+ * a fresh bot whose Claude Code was missing left the person with nothing to
+ * press.
+ */
 export function runtimeRepairNotice(args) {
     const text = args.text ?? runtimeFailureText(args.cls, args.runtime, args.context);
     if (!isRuntimeRepairClass(args.cls))

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

@@ -0,0 +1,25 @@
+/**
+ * The HQ desktop app's managed toolchain.
+ *
+ * The app installs node, hq-cli and @anthropic-ai/claude-code under one
+ * prefix so a clean Mac can run bots without the person installing anything:
+ *
+ *   ~/Library/Application Support/Indigo HQ/toolchain/
+ *     node/bin/node
+ *     npm-global/bin/hq
+ *     npm-global/bin/claude
+ *
+ * The bot daemon's PATH, the hq-cli update watcher and the Claude Code
+ * resolver all key on the same root, so it lives here once.
+ */
+/** Path segments under the home directory. macOS only; other platforms have no app toolchain. */
+export declare const HQ_APP_TOOLCHAIN_SEGMENTS: readonly ["Library", "Application Support", "Indigo HQ", "toolchain"];
+/** The npm prefix the app installs CLIs into, relative to the toolchain root. */
+export declare const HQ_APP_TOOLCHAIN_NPM_GLOBAL_BIN: string;
+/** `~/Library/Application Support/Indigo HQ/toolchain`. */
+export declare function hqAppToolchainRoot(homeDir?: string): string;
+/** `<toolchain>/npm-global/bin`, where `hq` and `claude` live. */
+export declare function hqAppToolchainBinDir(homeDir?: string): string;
+/** `<toolchain>/npm-global/bin/<name>`: where the app puts a CLI it manages. */
+export declare function hqAppToolchainBin(name: string, homeDir?: string): string;
+//# sourceMappingURL=toolchain.d.ts.map

package/dist/lib/bot/toolchain.js

@@ -0,0 +1,33 @@
+/**
+ * The HQ desktop app's managed toolchain.
+ *
+ * The app installs node, hq-cli and @anthropic-ai/claude-code under one
+ * prefix so a clean Mac can run bots without the person installing anything:
+ *
+ *   ~/Library/Application Support/Indigo HQ/toolchain/
+ *     node/bin/node
+ *     npm-global/bin/hq
+ *     npm-global/bin/claude
+ *
+ * The bot daemon's PATH, the hq-cli update watcher and the Claude Code
+ * resolver all key on the same root, so it lives here once.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+/** Path segments under the home directory. macOS only; other platforms have no app toolchain. */
+export const HQ_APP_TOOLCHAIN_SEGMENTS = ["Library", "Application Support", "Indigo HQ", "toolchain"];
+/** The npm prefix the app installs CLIs into, relative to the toolchain root. */
+export const HQ_APP_TOOLCHAIN_NPM_GLOBAL_BIN = path.join("npm-global", "bin");
+/** `~/Library/Application Support/Indigo HQ/toolchain`. */
+export function hqAppToolchainRoot(homeDir = os.homedir()) {
+    return path.join(homeDir, ...HQ_APP_TOOLCHAIN_SEGMENTS);
+}
+/** `<toolchain>/npm-global/bin`, where `hq` and `claude` live. */
+export function hqAppToolchainBinDir(homeDir = os.homedir()) {
+    return path.join(hqAppToolchainRoot(homeDir), HQ_APP_TOOLCHAIN_NPM_GLOBAL_BIN);
+}
+/** `<toolchain>/npm-global/bin/<name>`: where the app puts a CLI it manages. */
+export function hqAppToolchainBin(name, homeDir = os.homedir()) {
+    return path.join(hqAppToolchainBinDir(homeDir), name);
+}
+//# sourceMappingURL=toolchain.js.map

package/dist/lib/bot/worker-source.d.ts

@@ -48,6 +48,7 @@ export interface WorkerSourceFs {
     }) => Array<{
         name: string;
         isDirectory: () => boolean;
+        isSymbolicLink?: () => boolean;
     }>;
 }
 /** Collapse whitespace and take the first sentence, capped at `max` chars. */