@indigoai-us/hq-cli 5.288.0 → 5.290.0

package/dist/commands/core-ontology.d.ts

@@ -33,6 +33,8 @@ export interface MergeCopiesCommandOptions {
     variants?: boolean;
     limit?: number;
     only?: string;
+    /** Also re-point refs and links held today (flag merge-rewrite-refs). */
+    rewriteRefs?: boolean;
     json?: boolean;
 }
 /** Reads a `--only` file: a JSON array of `{ copy, original }` company-relative paths. */
@@ -44,7 +46,10 @@ export declare function readListedPairs(file: string): ListedPair[];
  * `checkpoint.ontology.merge-copies` and `checkpoint.ontology.multi-writer`.
  * With `--variants`, merges two-file duplicate groups whose names differ only
  * in case, spacing or punctuation instead, gated by
- * `checkpoint.ontology.merge-variants`.
+ * `checkpoint.ontology.merge-variants`. `--rewrite-refs` (flag
+ * `checkpoint.ontology.merge-rewrite-refs`) also re-points signal refs,
+ * invoice and bill links, source and knowledge links, and carries external
+ * ids and web domains.
  */
 export declare function runOntologyMergeCopies(hqRoot: string, slug: string | undefined, options: MergeCopiesCommandOptions, deps?: OntologyCommandDeps): Promise<string>;
 export declare function registerCoreOntologyCommand(core: Command): void;

package/dist/commands/core-ontology.js

@@ -17,7 +17,7 @@ import { applyOntologyRun, ApplyError } from "../lib/checkpoint-ontology/apply.j
 import { resolveOntologyCompany, WriteBoundsError } from "../lib/checkpoint-ontology/company.js";
 import { findDuplicateGroups, summarizeMergeBack, } from "../lib/checkpoint-ontology/multi-writer.js";
 import { buildEntityIndex } from "../lib/checkpoint-ontology/tree.js";
-import { MERGE_COPIES_FLAG, MERGE_VARIANTS_FLAG, mergeCopies, } from "../lib/checkpoint-ontology/merge-copies.js";
+import { MERGE_COPIES_FLAG, MERGE_REWRITE_REFS_FLAG, MERGE_VARIANTS_FLAG, mergeCopies, } from "../lib/checkpoint-ontology/merge-copies.js";
 import { callDeleteEndpoint } from "./files.js";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { registerCoreOntologyNativeCommands } from "./core-ontology-native.js";
@@ -146,11 +146,12 @@ function mergeCopiesSummary(report) {
     const held = report.plans.filter((plan) => plan.held).length;
     const lines = [
         `ontology merge-copies (${report.mode.replace("_", " ")}) in ${report.company} (${report.pair_kind}): ${report.plans.length} of ${report.copies_found} copies, ${held} held, ${report.skipped.length} skipped`,
-        `  merged ${report.merged.length}, relinked ${report.relinked.length}, deleted ${report.deleted.length}, not ready ${report.not_ready.length}, errors ${report.errors.length}`,
+        `  merged ${report.merged.length}, relinked ${report.relinked.length}${report.rewritten !== undefined ? `, rewritten ${report.rewritten.length}` : ""}, deleted ${report.deleted.length}, not ready ${report.not_ready.length}, errors ${report.errors.length}`,
         `  duplicate groups ${report.duplicate_groups_before} -> ${report.duplicate_groups_after}; broken entity links ${report.broken_links_before} -> ${report.broken_links_after}`,
     ];
-    for (const plan of report.plans.filter((entry) => entry.held))
-        lines.push(`  held ${plan.copy}: ${plan.held}`);
+    for (const plan of report.plans.filter((entry) => entry.held)) {
+        lines.push(`  held ${plan.copy}: ${plan.held}${plan.held === "external_id_conflict" ? ` (${plan.detail})` : ""}`);
+    }
     for (const error of report.errors)
         lines.push(`  error ${error.path}: ${error.error}`);
     for (const entry of report.only_unmatched ?? [])
@@ -176,7 +177,36 @@ export function readListedPairs(file) {
         })) {
         throw new OntologyUsageError("ontology: --only must be a non-empty JSON array of { copy, original } paths");
     }
-    return parsed.map((entry) => ({ copy: entry.copy, original: entry.original }));
+    return parsed.map((entry) => {
+        if (entry.resolve_external_ids === undefined)
+            return { copy: entry.copy, original: entry.original };
+        return { copy: entry.copy, original: entry.original, resolve_external_ids: readResolution(entry.copy, entry.resolve_external_ids) };
+    });
+}
+/** `{ provider: { primary, namespace, object_type? } }`, every value a non-empty string. */
+function readResolution(copy, raw) {
+    const usage = `ontology: --only entry ${copy}: resolve_external_ids must map each provider to { primary, namespace, object_type? } strings`;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw) || Object.keys(raw).length === 0)
+        throw new OntologyUsageError(usage);
+    const out = {};
+    for (const [provider, value] of Object.entries(raw)) {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            throw new OntologyUsageError(usage);
+        const record = value;
+        const nonEmpty = (field) => typeof field === "string" && field.length > 0;
+        if (!Object.keys(record).every((key) => key === "primary" || key === "namespace" || key === "object_type") ||
+            !nonEmpty(record.primary) ||
+            !nonEmpty(record.namespace) ||
+            (record.object_type !== undefined && !nonEmpty(record.object_type))) {
+            throw new OntologyUsageError(usage);
+        }
+        out[provider] = {
+            primary: record.primary,
+            namespace: record.namespace,
+            ...(record.object_type !== undefined ? { object_type: record.object_type } : {}),
+        };
+    }
+    return out;
 }
 /**
  * `hq core ontology merge-copies`: merge `<slug> <n>.md` copies into their
@@ -185,7 +215,10 @@ export function readListedPairs(file) {
  * `checkpoint.ontology.merge-copies` and `checkpoint.ontology.multi-writer`.
  * With `--variants`, merges two-file duplicate groups whose names differ only
  * in case, spacing or punctuation instead, gated by
- * `checkpoint.ontology.merge-variants`.
+ * `checkpoint.ontology.merge-variants`. `--rewrite-refs` (flag
+ * `checkpoint.ontology.merge-rewrite-refs`) also re-points signal refs,
+ * invoice and bill links, source and knowledge links, and carries external
+ * ids and web domains.
  */
 export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
     if (options.apply && options.delete) {
@@ -200,7 +233,7 @@ export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
         throw new OntologyUsageError(`ontology: company rejected: ${resolution.reason}`);
     const company = resolution.company;
     const readFlag = deps.readFlag ?? registryFlagReader;
-    for (const flag of [options.variants ? MERGE_VARIANTS_FLAG : MERGE_COPIES_FLAG, MULTI_WRITER_FLAG]) {
+    for (const flag of [options.variants ? MERGE_VARIANTS_FLAG : MERGE_COPIES_FLAG, MULTI_WRITER_FLAG, ...(options.rewriteRefs ? [MERGE_REWRITE_REFS_FLAG] : [])]) {
         if (!(await readFlag(flag, company))) {
             return options.json ? JSON.stringify({ company: company.slug, skipped: `${flag} off` }) : `ontology merge-copies: skipped (${flag} is off)`;
         }
@@ -220,6 +253,7 @@ export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
         ...(options.variants ? { pairKind: "variants" } : {}),
         ...(options.limit !== undefined ? { limit: options.limit } : {}),
         ...(only ? { only } : {}),
+        ...(options.rewriteRefs ? { rewriteRefs: true } : {}),
         ...(deleteVaultKey ? { deleteVaultKey } : {}),
     });
     return options.json ? JSON.stringify(report, null, 2) : mergeCopiesSummary(report);
@@ -274,6 +308,7 @@ export function registerCoreOntologyCommand(core) {
         .option("--variants", "merge two-file duplicate groups whose names differ only in case, spacing or punctuation (checkpoint.ontology.merge-variants)")
         .option("--limit <n>", "handle at most this many copies", (value) => Number(value))
         .option("--only <file>", "handle only the copy -> original pairs listed in this JSON file")
+        .option("--rewrite-refs", "also re-point signal refs, invoice, source and knowledge links to the survivor and carry external ids and web domains (checkpoint.ontology.merge-rewrite-refs)")
         .option("--json", "print JSON")
         .option("--hq-root <path>", "HQ installation to operate on")
         .action(async (options) => {

package/dist/commands/core.js

@@ -31,6 +31,7 @@
 import { Option } from "commander";
 import { registerCoreCheckpointCommand } from "./core-checkpoint.js";
 import { registerCoreDelegateCommand } from "./core-delegate.js";
+import { registerCoreHandoffCommand } from "./core-handoff.js";
 import { registerCoreOntologyCommand } from "./core-ontology.js";
 import { registerCoreKnowledgePrefsCommand } from "./core-knowledge-prefs.js";
 import { registerCorePolicyCommand } from "./core-policy.js";
@@ -241,7 +242,7 @@ export const SCAFFOLD_ONLY_ASSETS = [
     { asset: "core/scripts/ontology-source-worklist.sh", root: "live", summary: "Rollback companion for native ontology source worklist" },
     { asset: "core/scripts/source-yaml-validate.sh", root: "cwd", summary: "Rollback companion for native source YAML validation" },
     // Shared by native knowledge-prefs and the ontology candidate shell fallback.
-    { asset: "core/scripts/knowledge-prefs.sh", root: "live", summary: "Rollback companion for native knowledge-prefs and ontology candidate" },
+    { asset: "core/scripts/knowledge-prefs.sh", root: "live", summary: "Sibling dependency for ontology candidate rollback companion" },
     // Rollback companions for the default-off native knowledge and policy routes.
     // policy-retire also runs the scaffold validator in-process when native, but
     // its bundled shell fallback needs both helper assets at these exact paths.
@@ -250,6 +251,11 @@ export const SCAFFOLD_ONLY_ASSETS = [
     { asset: "core/scripts/read-policy-frontmatter.sh", root: "cwd", summary: "Rollback companion for native policy frontmatter" },
     { asset: "core/scripts/eval-trigger.sh", root: "live", summary: "Trigger grammar helper used by the policy validator companion" },
     { asset: ".claude/hooks/validate-policy-frontmatter.sh", root: "live", summary: "Policy validator companion used by policy-retire rollback" },
+    // Wave 2a handoff shells remain bundled as the default-off rollback path.
+    { asset: "core/scripts/handoff-finalize.sh", root: "live", summary: "Rollback shell for native handoff finalize" },
+    { asset: "core/scripts/handoff-post.sh", root: "live", summary: "Rollback shell for native handoff post" },
+    { asset: "core/scripts/handoff-open-steps.sh", root: "live", summary: "Rollback shell for native handoff open-steps" },
+    { asset: "core/scripts/qmd-reindex-bg.sh", root: "live", summary: "Rollback handoff reindex forwarder" },
     ...NATIVE_UTILITY_COMMANDS.map(({ asset, root, summary }) => ({
         asset,
         root,
@@ -326,6 +332,7 @@ export function registerCoreCommands(program) {
     registerCoreOntologyCommand(core);
     registerCoreCheckpointGateSettingCommand(core);
     registerCoreDelegateCommand(core);
+    registerCoreHandoffCommand(core);
     registerCoreKnowledgePrefsCommand(core);
     registerCorePolicyCommand(core);
     // Wave 2 handoff/worktree commands retain their byte-identical shell assets

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