@indigoai-us/hq-cli 5.288.0 → 5.289.0

package/CHANGELOG.md

@@ -2,12 +2,13 @@
 
 ## [Unreleased]
 
-## [5.288.0] — 2026-09-29
+## [5.289.0] — 2026-09-29
 
 ## [5.287.0] — 2026-09-29
 - Group hook-timeout events by script while preserving triage diagnostics.
 - Preserve safe slow-child script basenames in hook-timeout diagnostics.
 - Cloud provisioning and retirement now stop after 15 seconds when a Vault API request stalls, with a clear timeout error.
+- In the HQ desktop app, clicking "Explain HQ first" in the setup bot now shows the fixed explanation of HQ at once, with no model turn. The setup worker ships that text in `skills/explain-hq.md`, and the bot reads the same file when someone asks in their own words.
 - Add native TypeScript implementations for four `hq core` worktree and
   handoff scripts behind the default-off `core-native-handoff` flag. The
   original shell assets remain bundled as the rollback path.
@@ -17,6 +18,10 @@
 - `hq team-sync` keeps its successful no-team result, reports which company
   directories are cloud-backed, and points to `hq sync pull --all` and
   `hq sync status` for cloud-backed companies.
+- An unconfirmed Outpost pickup acknowledgement keeps its mirror queued with
+  `outcome_unknown` and its command id. Reconcile uses a strict owner snapshot;
+  it marks the mirror `remote_lost` only after the 15-minute grace when the
+  owner confirms the lane is missing. Unreachable owners remain counted.
 
 ### Fixed
 

package/assets/bot-workers/setup/skills/explain-hq.md

@@ -0,0 +1,35 @@
+---
+name: explain-hq
+description: The fixed explanation of HQ, sent when the person asks for it at the start of setup. It is sent word for word, by you or by the HQ app.
+---
+
+# Explaining HQ at the start
+
+This is the one explanation of HQ that setup gives. It is sent word for word
+and never reworded, shortened or added to.
+
+- **When you send it** (they asked for the explanation in their own words, or
+  they clicked "Explain HQ first" and your turn does not start with a note
+  from the HQ app saying it already went out): send the text under "The
+  explanation" as written. Then, in the same message, one line saying you are
+  starting, and the first unfinished step's one question.
+- **When the HQ app sends it** (they clicked "Explain HQ first"): the app
+  sends the text under "The explanation" at once, followed by the text under
+  "After the explanation, when the app sends it". Your next turn starts with
+  a note saying so. Do not send the explanation again.
+
+## The explanation
+
+**One shared brain for your company's AI.** Your clients, decisions, meeting notes, connected apps, keys and skills live in one place, and every AI that works for you reads from it and adds to it.
+
+**It works with the agents you already use.** Claude Code, Codex or Cursor, opened in your HQ folder, already know your business. You can put agents in Slack so your team can ask them things where they already talk, and connect other agents from the HQ console under Agents. Messaging bots in this app is one more way in, not the main one.
+
+**It's built for your team.** Invite someone and their AI knows the business on day one. Connected apps and keys can be shared with them without passing passwords around, and each company stays separate.
+
+## After the explanation, when the app sends it
+
+Ready to start the setup?
+
+```hq-block
+{"v":1,"blocks":[{"kind":"suggestions","items":["Let's start","How is this different from Claude?"]}]}
+```

package/assets/bot-workers/setup/worker.yaml

@@ -42,6 +42,9 @@ skills:
   - name: standing-help
     description: "How to behave once setup is finished: the always-there helper who does the thing rather than describing it."
     doc: skills/standing-help.md
+  - name: explain-hq
+    description: "The fixed explanation of HQ for someone who asks for it at the start of setup. Sent word for word, by you or by the HQ app."
+    doc: skills/explain-hq.md
 
 instructions: |
   # Setup
@@ -256,28 +259,26 @@ instructions: |
 
   ## Explaining HQ at the start
 
-  When they answer the first question by asking for the explanation, give it
-  in three short paragraphs, in this order, each one opening with a short
-  bold lead (the only bold in the message), in your own words but keeping
-  every point:
-
-  1. **One shared brain for your company's AI.** Their clients, decisions,
-     meeting notes, connected apps, keys and skills live in one place, and
-     every AI that works for them reads from it and adds to it.
-  2. **It works with the agents you already use.** Claude Code, Codex or
-     Cursor opened in their HQ folder already know their business. They can
-     put agents in Slack so their team can ask them things where they already
-     talk, and connect other agents from the HQ console under Agents.
-     Messaging bots in this app is one more way in, not the main one.
-  3. **It's built for your team.** Invite someone and their AI knows the
-     business on day one. Connected apps and keys can be shared with them
-     without passing passwords around, and each company stays separate.
-
-  Then one line that you are starting, and the first unfinished step's one
-  question, in the same message. Do not ask whether the explanation made
-  sense, and do not offer a tour. If they ask how to do one of those things
-  (a Slack agent, an outside agent, inviting someone, sharing an app or a
-  key), walk them through it using `skills/agents-and-team.md`.
+  The explanation is fixed, and it lives in `skills/explain-hq.md`. The same
+  text goes out whether you send it or the HQ app does, so never write your
+  own version.
+
+  When they click "Explain HQ first", the HQ app sends the explanation for
+  you straight away, and your next turn starts with a note from the app
+  saying it went out. The question is then answered: write `Intro: explained`
+  in your progress note, do not explain HQ again, and carry on with the first
+  unfinished step's one question.
+
+  When they ask for the explanation any other way (in their own words, or by
+  clicking "Explain HQ first" with no note from the app at the start of your
+  turn), read `skills/explain-hq.md` and send the text under its "The
+  explanation" heading word for word. Then one line that you are starting,
+  and the first unfinished step's one question, in the same message.
+
+  Do not ask whether the explanation made sense, and do not offer a tour. If
+  they ask how to do one of those things (a Slack agent, an outside agent,
+  inviting someone, sharing an app or a key), walk them through it using
+  `skills/agents-and-team.md`.
 
   ## How you make them feel it
 
@@ -407,7 +408,8 @@ instructions: |
     company", "Just for me". Put the answer you would recommend first.
   - **You offered a choice or a yes/no:** "Want me to invite them now?" gets
     "Yes, invite them", "Not yet".
-  - **The explain-or-jump question:** "Explain HQ first", "Jump straight in".
+  - **The explain-or-jump question:** "Explain HQ first", "Jump straight in",
+    in exactly those words. The HQ app answers "Explain HQ first" by itself.
   - **You finished something and did not ask anything:** the one or two next
     steps most people would take ("Connect my calls", "How do I add my team?").
 

package/dist/commands/lanes.js

@@ -79,6 +79,7 @@ export { MAX_LANE_DEPTH };
 export const LANES_RUNS_REL = path.join("workspace", "lanes-runs");
 export const LANE_REMOTE_MIRROR_SYNC_FLAG = "lanes.remote-done-mirror";
 const REMOTE_MIRROR_REFRESH_BATCH_SIZE = 100;
+const REMOTE_LANE_NOT_FOUND_GRACE_MS = 15 * 60_000;
 /** The lane → mesh seam. Defined in lib/lanes/mesh-events.ts; the watcher shares it. */
 export { emitLaneDecisionEvents };
 export { LANE_OUTPOST_SNAPSHOT_CACHE_FLAG };
@@ -1129,6 +1130,7 @@ function normalizedLaneListQuery(query) {
         ...(hierarchy === undefined ? {} : { hierarchy }),
         ...(query.snapshot ? { snapshot: true } : {}),
         ...(query.strictSnapshot ? { strictSnapshot: true } : {}),
+        ...(query.includeForeignHostRows ? { includeForeignHostRows: true } : {}),
     };
 }
 async function readOutpostLaneRecordsUncached(ctx, outpostId, query, dispatchOptions = {}) {
@@ -1191,7 +1193,7 @@ async function readOutpostLaneRecordsUncached(ctx, outpostId, query, dispatchOpt
         // Outpost's own store, so preserve those local identities for accounting.
         const hasLocalHostIdentity = rowHost.kind === "local" &&
             typeof rowHost.id === "string" && rowHost.id.trim() !== "";
-        if (!belongsToOutpost && !hasLocalHostIdentity)
+        if (!belongsToOutpost && !hasLocalHostIdentity && !query.includeForeignHostRows)
             continue;
         try {
             lanes.push(parseLaneRecord(normalizeLaneRecordView(raw)));
@@ -1216,6 +1218,7 @@ async function refreshRemoteLaneMirrors(ctx, hqRoot, records, parentLaneIds) {
     const result = {
         updated: new Map(),
         unverifiedRemote: new Map(),
+        missingOnOwner: new Map(),
     };
     const host = reconcileHostFromCtx(ctx);
     if (ctx.env.HQ_LANES_REMOTE_READ === "1" || parentLaneIds?.size === 0)
@@ -1285,6 +1288,7 @@ async function refreshRemoteLaneMirrors(ctx, hqRoot, records, parentLaneIds) {
                 laneIds: batch.map((lane) => lane.lane_id),
                 snapshot: true,
                 strictSnapshot: true,
+                includeForeignHostRows: true,
             });
         }
         catch (error) {
@@ -1306,6 +1310,8 @@ async function refreshRemoteLaneMirrors(ctx, hqRoot, records, parentLaneIds) {
                 !ownerIsHostedByOutpost ||
                 (owner.company?.uid ?? null) !== (mirror.company?.uid ?? null) ||
                 (owner.company?.slug ?? null) !== (mirror.company?.slug ?? null)) {
+                if (matches.length === 0)
+                    result.missingOnOwner.set(mirror.lane_id, mirror);
                 const detail = matches.length === 0
                     ? "owner did not return the requested lane"
                     : matches.length > 1
@@ -1329,6 +1335,7 @@ async function refreshRemoteLaneMirrors(ctx, hqRoot, records, parentLaneIds) {
             }
             const needsUpdate = before.state !== owner.state ||
                 before.queued_reason !== (owner.state === "queued" ? owner.queued_reason : undefined) ||
+                JSON.stringify(before.queued_details) !== JSON.stringify(owner.state === "queued" ? owner.queued_details : undefined) ||
                 before.ended_at !== endedAt ||
                 before.envelope_summary !== envelopeSummary ||
                 (isTerminalLaneState(owner.state) && (JSON.stringify(before.last_envelope) !== JSON.stringify(owner.last_envelope) ||
@@ -1348,6 +1355,7 @@ async function refreshRemoteLaneMirrors(ctx, hqRoot, records, parentLaneIds) {
                     ...current,
                     state: owner.state,
                     queued_reason: owner.state === "queued" ? owner.queued_reason : undefined,
+                    queued_details: owner.state === "queued" ? owner.queued_details : undefined,
                     ended_at: endedAt,
                     envelope_summary: envelopeSummary,
                     ...(isTerminalLaneState(owner.state) ? {
@@ -2445,6 +2453,47 @@ function markDispatchFailure(hqRoot, laneId, details) {
         };
     });
 }
+function retainQueuedOutpostAfterUnknownDelivery(hqRoot, laneId, outpostId, commandId) {
+    return casUpdateLane(hqRoot, laneId, (current) => {
+        if (current.state !== "queued" ||
+            current.host.kind !== "outpost" ||
+            current.host.id !== outpostId)
+            return current;
+        return {
+            ...current,
+            queued_details: {
+                reason: "outpost_dispatch_unknown",
+                outcome_unknown: true,
+                command_id: commandId,
+            },
+        };
+    });
+}
+function markRemoteLaneLost(hqRoot, laneId, outpostId, at, writer, operatorReason, expectedVersion) {
+    return retryUpdateLane(hqRoot, laneId, writer, (current) => {
+        if (current.host.kind !== "outpost" ||
+            current.host.id !== outpostId ||
+            (expectedVersion !== undefined && current.version !== expectedVersion) ||
+            isTerminalLaneState(current.state))
+            return current;
+        return {
+            ...current,
+            state: "failed",
+            queued_reason: undefined,
+            queued_details: undefined,
+            terminal_reason: "remote_lost",
+            terminal_details: {
+                outpost_id: outpostId,
+                owner_error: "lane_not_found",
+                ...(operatorReason === undefined ? {} : { operator_reason: operatorReason }),
+            },
+            stop_history: [
+                ...(current.stop_history ?? []),
+                { at, reason: "remote_lost" },
+            ],
+        };
+    });
+}
 /**
  * The CAS updater a pickup failure applies. A lane that is already terminal
  * for any reason (a cancel that landed after the caller's last read, an
@@ -3528,6 +3577,22 @@ async function dispatchCreatedOutpostLane(ctx, input) {
                 exit_code: dispatched.exitCode,
             });
         }
+        const commandId = dispatched.commandId?.trim();
+        if (dispatched.done !== true || !commandId) {
+            const details = {
+                outpost_id: outpostId,
+                lane_id: lane.lane_id,
+                command_id: commandId || null,
+                status: dispatched.status,
+                done: dispatched.done ?? false,
+                exit_code: dispatched.exitCode,
+                outcome_unknown: true,
+            };
+            throw new LanesError("outpost_delivery_unconfirmed", `Outpost ${outpostId} did not confirm pickup for lane ${lane.lane_id}; the queued lane will be reconciled against its owner`, {
+                ...details,
+                state: retainQueuedOutpostAfterUnknownDelivery(hqRoot, lane.lane_id, outpostId, commandId || null).state,
+            });
+        }
         const stdoutTrimmed = dispatched.stdout.trim();
         if (remote === null && stdoutTrimmed !== "" && dispatched.status !== "Success") {
             if (preserveQueuedOnFailure) {
@@ -3606,6 +3671,9 @@ async function dispatchCreatedOutpostLane(ctx, input) {
     catch (err) {
         if (preserveQueuedOnFailure)
             throw err;
+        if (isLanesError(err) && err.error === "outpost_delivery_unconfirmed" && err.details.outcome_unknown === true) {
+            throw err;
+        }
         if (isLanesError(err) &&
             err.error === DISPATCH_TERMINAL_REASON &&
             readLane(hqRoot, lane.lane_id).state === "failed") {
@@ -4551,7 +4619,7 @@ async function runList(ctx, opts, fastRouteFlags) {
     }
     const remoteRead = ctx.env[REMOTE_LANE_READ_ENV] === "1";
     const remoteRefresh = remoteRead
-        ? { updated: new Map(), unverifiedRemote: new Map() }
+        ? { updated: new Map(), unverifiedRemote: new Map(), missingOnOwner: new Map() }
         : await refreshRemoteLaneMirrors(ctx, hqRoot, laneSource, new Set(selectedLanes
             .filter((lane) => !isTerminalLaneState(lane.state))
             .map((lane) => lane.lane_id)));
@@ -7035,11 +7103,21 @@ async function readOutpostTerminalLane(ctx, laneId, outpostId, stopCommandId, wa
         commandId,
     };
 }
+function isDefiniteOutpostLaneNotFound(dispatched, laneId, ownerError) {
+    return dispatched.done === true &&
+        Boolean(dispatched.commandId?.trim()) &&
+        dispatched.status === "Failed" &&
+        dispatched.exitCode !== null &&
+        dispatched.exitCode !== 0 &&
+        ownerError?.error === "lane_not_found" &&
+        ownerError.details.lane_id === laneId;
+}
 async function dispatchOutpostLaneStop(ctx, lane, reason, quiet = false) {
     if (lane.host.kind !== "outpost") {
         throw new LanesError("outpost_dispatch_failed", `Lane ${lane.lane_id} has no Outpost host to dispatch stop to`, { lane_id: lane.lane_id });
     }
     const outpostId = lane.host.id;
+    const hqRoot = ctx.hqRoot();
     const waitMs = outpostSingleLaneWaitMs(ctx.env);
     let dispatched;
     try {
@@ -7063,7 +7141,36 @@ async function dispatchOutpostLaneStop(ctx, lane, reason, quiet = false) {
             required_option: "--reason",
         });
     }
+    const commandId = dispatched.commandId?.trim();
     const ownerError = ownerErrorFromOutput(dispatched.stdout);
+    if (isDefiniteOutpostLaneNotFound(dispatched, lane.lane_id, ownerError)) {
+        const at = ctx.now().toISOString();
+        const updated = markRemoteLaneLost(ctx.hqRoot(), lane.lane_id, outpostId, at, "command", reason);
+        if (updated.terminal_reason !== "remote_lost") {
+            throw new LanesError("already_terminal", `Lane ${lane.lane_id} became terminal before its missing Outpost record could be marked remote_lost`, { lane_id: lane.lane_id, state: updated.state });
+        }
+        const cancelled = cancelPendingQuestionsForLane(hqRoot, lane.lane_id, at, "remote_lost");
+        await emitLaneTerminalStateSoft(ctx, updated);
+        if (!quiet)
+            printJson({
+                ok: true,
+                action: "stop",
+                reason: "remote_lost",
+                lane: updated,
+                terminal: true,
+                resumable: false,
+                cancelled_questions: cancelled.map((question) => question.question_id),
+                outpost_id: outpostId,
+                outpost_command_id: commandId,
+                outpost_result: {
+                    state: "failed",
+                    reason: "remote_lost",
+                    status: dispatched.status,
+                    exit_code: dispatched.exitCode,
+                },
+            });
+        return;
+    }
     if (ownerError) {
         throw new LanesError("outpost_dispatch_failed", `Outpost ${outpostId} rejected the stop command: ${ownerError.message}`, {
             lane_id: lane.lane_id,
@@ -7075,7 +7182,6 @@ async function dispatchOutpostLaneStop(ctx, lane, reason, quiet = false) {
             owner_error: ownerError,
         });
     }
-    const commandId = dispatched.commandId?.trim();
     if (dispatched.done !== true || !commandId) {
         throw new LanesError("outpost_delivery_unconfirmed", `Outpost ${outpostId} did not return a completed stop command for lane ${lane.lane_id}`, {
             lane_id: lane.lane_id,
@@ -7559,8 +7665,42 @@ async function runReconcile(ctx, opts, recoverQueuedMessages) {
     const fromEnv = ctx.env.HQ_ROOT?.trim();
     const hqRoot = fromEnv && ctx.existsSync(fromEnv) ? fromEnv : ctx.hqRoot();
     const mirrorRefresh = opts.dryRun
-        ? { updated: new Map(), unverifiedRemote: new Map() }
+        ? {
+            updated: new Map(),
+            unverifiedRemote: new Map(),
+            missingOnOwner: new Map(),
+        }
         : await refreshRemoteLaneMirrors(ctx, hqRoot, loadAllLanes(hqRoot));
+    const remoteLost = [];
+    const remoteLostErrors = [];
+    if (!opts.dryRun && mirrorRefresh.missingOnOwner.size > 0) {
+        const at = ctx.now().toISOString();
+        const nowMs = Date.parse(at);
+        for (const [laneId, mirror] of mirrorRefresh.missingOnOwner) {
+            const createdAtMs = Date.parse(mirror.created_at);
+            if (!Number.isFinite(createdAtMs) ||
+                nowMs - createdAtMs < REMOTE_LANE_NOT_FOUND_GRACE_MS)
+                continue;
+            try {
+                const updated = markRemoteLaneLost(hqRoot, laneId, mirror.host.id, at, "reconcile", undefined, mirror.version);
+                if (updated.terminal_reason !== "remote_lost") {
+                    if (updated.version !== mirror.version) {
+                        mirrorRefresh.unverifiedRemote.set(laneId, "mirror changed after the owner snapshot");
+                    }
+                    continue;
+                }
+                remoteLost.push({ id: laneId, reason: "remote_lost" });
+                cancelPendingQuestionsForLane(hqRoot, laneId, at, "remote_lost");
+                await emitLaneTerminalStateSoft(ctx, updated);
+            }
+            catch (err) {
+                remoteLostErrors.push({
+                    laneId,
+                    message: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
     const summary = await runReconcilePass(hqRoot, {
         now: ctx.now,
         host: reconcileHostFromCtx(ctx),
@@ -7676,10 +7816,22 @@ async function runReconcile(ctx, opts, recoverQueuedMessages) {
             }
         },
     });
+    for (const failure of remoteLostErrors) {
+        summary.errors.push({
+            code: "remote_lane_terminalize_failed",
+            message: `Could not mark remote lane ${failure.laneId} lost: ${failure.message}`,
+        });
+        summary.ok = false;
+    }
+    const terminalizedRemoteIds = new Set(remoteLost.map(({ id }) => id));
     printJson({
         ...summary,
+        ...(remoteLost.length > 0 ? { remote_lost: remoteLost } : {}),
         ...(mirrorRefresh.unverifiedRemote.size > 0
-            ? { unverified_remote_lanes: [...mirrorRefresh.unverifiedRemote.keys()] }
+            ? {
+                unverified_remote_lanes: [...mirrorRefresh.unverifiedRemote.keys()]
+                    .filter((id) => !terminalizedRemoteIds.has(id)),
+            }
             : {}),
     });
     if (!summary.ok) {

package/dist/lib/bot/run.js

@@ -52,7 +52,7 @@ 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, SETUP_BOT_WORKER_ID } from "./config.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";
@@ -61,6 +61,7 @@ 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";
@@ -296,6 +297,26 @@ export async function runBot(deps) {
     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();
@@ -1105,6 +1126,7 @@ export async function runBot(deps) {
                 return;
             }
             clearInflight(dir, KICKOFF_MESSAGE_ID);
+            noteSetupReply(outcome.reply);
             if (readBotConfig(dir)?.kickoffPendingSignIn)
                 patchBotConfig(dir, { kickoffPendingSignIn: false });
             const st = readStatus();
@@ -1323,6 +1345,54 @@ export async function runBot(deps) {
             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);
@@ -1381,6 +1451,11 @@ export async function runBot(deps) {
             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;
@@ -1441,7 +1516,10 @@ export async function runBot(deps) {
             text = text ? `${text}\n\n${block}` : block;
         }
         const sessionScope = target.kind === "room" ? target.sessionScope : dmSessionScope(target.peerUid, config.ownerUid);
-        const prompt = target.kind === "room" ? await buildRoomTurn(item, target, text) : target.peerUid === config.ownerUid ? text :
+        // 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);
@@ -1463,6 +1541,18 @@ export async function runBot(deps) {
                 ? { 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) {

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

@@ -0,0 +1,68 @@
+/**
+ * The setup bot's instant "Explain HQ first" answer.
+ *
+ * The setup bot's first question is whether to explain HQ or jump straight in,
+ * with "Explain HQ first" as a suggested reply. The explanation is fixed text,
+ * so a click on that button does not need a model turn: the runner sends the
+ * text from the setup worker's `skills/explain-hq.md` at once, and the bot's
+ * next turn starts with a note saying the explanation already went out.
+ *
+ * The text has one home, the worker file. The model reads the same file when
+ * someone asks for the explanation in their own words, so the two paths never
+ * drift. Anything unexpected (file missing or malformed, the question not
+ * pending, any other message) falls back to the normal model turn.
+ */
+/** The suggested reply that triggers the instant answer. Exact match only. */
+export declare const EXPLAIN_HQ_SUGGESTION = "Explain HQ first";
+/** Where the explanation lives, relative to the setup worker folder. */
+export declare const EXPLAIN_HQ_FILE: string;
+/** The setup bot's progress note in its memory folder (setup worker.yaml). */
+export declare const SETUP_PROGRESS_FILE = "setup-progress.md";
+/** Runner-owned state, in the bot's own folder (never the model's memory). */
+export declare const SETUP_INTRO_STATE_FILE = "setup-intro.json";
+/**
+ * Put in front of the next message from the person, so the model knows the
+ * explanation went out without it. It never reaches the person.
+ */
+export declare const SETUP_EXPLAINED_NOTE: string;
+export interface SetupExplainer {
+    /** The explanation, word for word (shared with the model path). */
+    explanation: string;
+    /** What the app adds after it: a line offering to continue, and suggestions. */
+    closing: string;
+    /** The whole message the app sends. */
+    reply: string;
+}
+/** Parse the worker file. Null when it is not the shape the app can send. */
+export declare function parseSetupExplainer(body: string): SetupExplainer | null;
+/** Read the explanation from the setup worker folder the bot runs. */
+export declare function loadSetupExplainer(hqRoot: string, workerDir: string): SetupExplainer | null;
+export type SetupProgressIntro = "asked" | "answered" | "finished" | null;
+/** What the model's progress note says about the opening question. */
+export declare function readSetupProgressIntro(memoryDir: string): SetupProgressIntro;
+export interface SetupIntroState {
+    v: 1;
+    /** The bot's latest owner-DM reply asked the explain-or-jump question. */
+    offeredAt?: string;
+    /** The app sent the explanation (never sent twice). */
+    explainedAt?: string;
+    /** The model has not yet been told that the explanation went out. */
+    notePending?: boolean;
+}
+export declare function readSetupIntroState(dir: string): SetupIntroState;
+export declare function patchSetupIntroState(dir: string, patch: Partial<Omit<SetupIntroState, "v">>): SetupIntroState;
+/** A bot reply that asks the explain-or-jump question (the words or the button). */
+export declare function replyOffersExplain(reply: string): boolean;
+/**
+ * The instant answer is due only when ALL of these hold: the message is exactly
+ * the button text with nothing attached, the question is pending (the bot's
+ * last reply offered it, or its note says it asked), and the explanation has
+ * not gone out yet (neither by the app nor, per the note, by the model).
+ */
+export declare function setupExplainDue(input: {
+    text: string;
+    attachments: number;
+    state: SetupIntroState;
+    progress: SetupProgressIntro;
+}): boolean;
+//# sourceMappingURL=setup-explain.d.ts.map

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

@@ -0,0 +1,141 @@
+/**
+ * The setup bot's instant "Explain HQ first" answer.
+ *
+ * The setup bot's first question is whether to explain HQ or jump straight in,
+ * with "Explain HQ first" as a suggested reply. The explanation is fixed text,
+ * so a click on that button does not need a model turn: the runner sends the
+ * text from the setup worker's `skills/explain-hq.md` at once, and the bot's
+ * next turn starts with a note saying the explanation already went out.
+ *
+ * The text has one home, the worker file. The model reads the same file when
+ * someone asks for the explanation in their own words, so the two paths never
+ * drift. Anything unexpected (file missing or malformed, the question not
+ * pending, any other message) falls back to the normal model turn.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** The suggested reply that triggers the instant answer. Exact match only. */
+export const EXPLAIN_HQ_SUGGESTION = "Explain HQ first";
+/** Where the explanation lives, relative to the setup worker folder. */
+export const EXPLAIN_HQ_FILE = path.join("skills", "explain-hq.md");
+/** The setup bot's progress note in its memory folder (setup worker.yaml). */
+export const SETUP_PROGRESS_FILE = "setup-progress.md";
+/** Runner-owned state, in the bot's own folder (never the model's memory). */
+export const SETUP_INTRO_STATE_FILE = "setup-intro.json";
+const EXPLANATION_HEADING = /^##[ \t]+The explanation[ \t]*$/m;
+const CLOSING_HEADING = /^##[ \t]+After the explanation, when the app sends it[ \t]*$/m;
+/**
+ * Put in front of the next message from the person, so the model knows the
+ * explanation went out without it. It never reaches the person.
+ */
+export const SETUP_EXPLAINED_NOTE = `[Note from the HQ app: the person clicked "${EXPLAIN_HQ_SUGGESTION}", and the app already sent them the explanation ` +
+    `from skills/explain-hq.md word for word, ending by asking whether to start the setup. The explain-or-jump question is answered. ` +
+    "Write `Intro: explained` in your progress note, do not explain HQ again, and carry on with the first unfinished setup step. " +
+    "Their reply to that message follows.]";
+/** The text between a heading and the next `## ` heading (or the end). */
+function sectionAfter(body, heading) {
+    const match = heading.exec(body);
+    if (!match)
+        return null;
+    const rest = body.slice(match.index + match[0].length);
+    const next = /^##[ \t]/m.exec(rest);
+    return (next ? rest.slice(0, next.index) : rest).trim();
+}
+/** True when the closing carries exactly one well-formed suggestions block. */
+function hasSuggestionsBlock(closing) {
+    const fence = /^```hq-block\n(.+)\n```$/m.exec(closing);
+    if (!fence)
+        return false;
+    try {
+        const parsed = JSON.parse(fence[1]);
+        const block = parsed.blocks?.[0];
+        return (parsed.v === 1 &&
+            block?.kind === "suggestions" &&
+            Array.isArray(block.items) &&
+            block.items.length >= 2 &&
+            block.items.every((item) => typeof item === "string" && item.trim().length > 0));
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse the worker file. Null when it is not the shape the app can send. */
+export function parseSetupExplainer(body) {
+    const text = body.replace(/\r\n/g, "\n");
+    const explanation = sectionAfter(text, EXPLANATION_HEADING);
+    const closing = sectionAfter(text, CLOSING_HEADING);
+    if (!explanation || !closing)
+        return null;
+    // The closing must end with the block (nothing after it) so the app shows the buttons.
+    if (!closing.endsWith("```") || !hasSuggestionsBlock(closing))
+        return null;
+    return { explanation, closing, reply: `${explanation}\n\n${closing}` };
+}
+/** Read the explanation from the setup worker folder the bot runs. */
+export function loadSetupExplainer(hqRoot, workerDir) {
+    try {
+        return parseSetupExplainer(fs.readFileSync(path.resolve(hqRoot, workerDir, EXPLAIN_HQ_FILE), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** What the model's progress note says about the opening question. */
+export function readSetupProgressIntro(memoryDir) {
+    let note;
+    try {
+        note = fs.readFileSync(path.join(memoryDir, SETUP_PROGRESS_FILE), "utf8");
+    }
+    catch {
+        return null;
+    }
+    if (/^Status:[ \t]*finished/im.test(note))
+        return "finished";
+    if (/^Intro:[ \t]*(explained|skipped)\b/im.test(note))
+        return "answered";
+    if (/^Intro:[ \t]*asked\b/im.test(note))
+        return "asked";
+    return null;
+}
+export function readSetupIntroState(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, SETUP_INTRO_STATE_FILE), "utf8"));
+        return parsed && parsed.v === 1 ? parsed : { v: 1 };
+    }
+    catch {
+        return { v: 1 };
+    }
+}
+export function patchSetupIntroState(dir, patch) {
+    const next = { ...readSetupIntroState(dir), ...patch, v: 1 };
+    for (const key of Object.keys(next)) {
+        if (next[key] === undefined)
+            delete next[key];
+    }
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = path.join(dir, SETUP_INTRO_STATE_FILE);
+    const tmp = `${dest}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+    return next;
+}
+/** A bot reply that asks the explain-or-jump question (the words or the button). */
+export function replyOffersExplain(reply) {
+    return reply.includes(`"${EXPLAIN_HQ_SUGGESTION}"`) || /explain HQ to you/i.test(reply);
+}
+/**
+ * The instant answer is due only when ALL of these hold: the message is exactly
+ * the button text with nothing attached, the question is pending (the bot's
+ * last reply offered it, or its note says it asked), and the explanation has
+ * not gone out yet (neither by the app nor, per the note, by the model).
+ */
+export function setupExplainDue(input) {
+    if (input.text !== EXPLAIN_HQ_SUGGESTION || input.attachments > 0)
+        return false;
+    if (input.state.explainedAt)
+        return false;
+    if (input.progress === "answered" || input.progress === "finished")
+        return false;
+    return Boolean(input.state.offeredAt) || input.progress === "asked";
+}
+//# sourceMappingURL=setup-explain.js.map

package/dist/lib/lanes/store.js

@@ -532,26 +532,44 @@ export function parseLaneRecord(raw, filePath) {
         const details = raw.queued_details;
         if (details === null || typeof details !== "object" || Array.isArray(details) ||
             typeof details.reason !== "string") {
-            throw new LaneSchemaError("queued_details must describe a worker_profile_changed queue reason", {
+            throw new LaneSchemaError("queued_details must describe a supported queue condition", {
                 path: filePath,
                 field: "queued_details",
             });
         }
         const detailsRecord = details;
-        if (detailsRecord.reason !== "worker_profile_changed" ||
-            (detailsRecord.expected_hash !== null && typeof detailsRecord.expected_hash !== "string") ||
-            typeof detailsRecord.actual_hash !== "string" || detailsRecord.actual_hash === "" ||
-            typeof detailsRecord.recovery_command !== "string" || detailsRecord.recovery_command.trim() === "") {
-            throw new LaneSchemaError("queued_details must describe a worker_profile_changed queue reason", {
-                path: filePath,
-                field: "queued_details",
-            });
+        if (detailsRecord.reason === "worker_profile_changed") {
+            if ((detailsRecord.expected_hash !== null && typeof detailsRecord.expected_hash !== "string") ||
+                typeof detailsRecord.actual_hash !== "string" || detailsRecord.actual_hash === "" ||
+                typeof detailsRecord.recovery_command !== "string" || detailsRecord.recovery_command.trim() === "") {
+                throw new LaneSchemaError("queued_details must describe a worker_profile_changed queue reason", {
+                    path: filePath,
+                    field: "queued_details",
+                });
+            }
+            if (raw.queued_reason !== "worker_profile_changed") {
+                throw new LaneSchemaError("queued_details requires queued_reason worker_profile_changed", {
+                    path: filePath,
+                    field: "queued_details",
+                    queued_reason: raw.queued_reason,
+                });
+            }
+        }
+        else if (detailsRecord.reason === "outpost_dispatch_unknown") {
+            if (raw.state !== "queued" ||
+                detailsRecord.outcome_unknown !== true ||
+                (detailsRecord.command_id !== null &&
+                    (typeof detailsRecord.command_id !== "string" || detailsRecord.command_id.trim() === ""))) {
+                throw new LaneSchemaError("queued_details must describe an unknown Outpost dispatch on a queued lane", {
+                    path: filePath,
+                    field: "queued_details",
+                });
+            }
         }
-        if (raw.queued_reason !== "worker_profile_changed") {
-            throw new LaneSchemaError("queued_details requires queued_reason worker_profile_changed", {
+        else {
+            throw new LaneSchemaError("queued_details must describe a supported queue condition", {
                 path: filePath,
                 field: "queued_details",
-                queued_reason: raw.queued_reason,
             });
         }
     }

package/dist/lib/lanes/types.d.ts

@@ -175,12 +175,16 @@ export declare const LANE_PROVIDERS: readonly ["claude", "codex", "grok"];
 export type LaneProvider = (typeof LANE_PROVIDERS)[number];
 export declare const QUEUED_REASONS: readonly ["cap", "provider_cap", "account_cap", "profile_cap", "queue_position", "throttle", "provider_binary_missing", "account_retry", "worker_profile_changed"];
 export type QueuedReason = (typeof QUEUED_REASONS)[number];
-export interface QueuedDetails {
+export type QueuedDetails = {
     reason: "worker_profile_changed";
     expected_hash: string | null;
     actual_hash: string;
     recovery_command: string;
-}
+} | {
+    reason: "outpost_dispatch_unknown";
+    outcome_unknown: true;
+    command_id: string | null;
+};
 export declare function isQueuedReason(value: unknown): value is QueuedReason;
 export declare const HOST_KINDS: readonly ["local", "outpost"];
 export type HostKind = (typeof HOST_KINDS)[number];

package/dist/lib/lanes/types.js

@@ -231,7 +231,7 @@ export const LANE_FIELD_WRITERS = {
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
     last_message_at: ["command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher"], blocker_freshness_state: ["watcher"], kr_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
     overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],
-    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command"], settings_history: ["command"], pending_settings: ["command", "spawn"], interrupted_at: ["command", "watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
+    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command", "reconcile"], settings_history: ["command"], pending_settings: ["command", "spawn"], interrupted_at: ["command", "watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
     quota_reset_at: ["watcher", "reconcile"], model_quota_marker: ["watcher", "reconcile"], outpost_command_id: ["command"],
     provider_session_id: ["watcher", "command", "spawn"], provider_session_id_absent: ["watcher", "command"], provider_home_at_spawn: ["spawn"], last_resume: ["spawn"], last_run_usage: ["watcher"], last_run_usage_at: ["watcher"], envelope_repair: ["watcher", "reconcile"], envelope_validation_errors: ["watcher"], last_progress_event_at: ["watcher"],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.288.0",
+  "version": "5.289.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {