@indigoai-us/hq-cli 5.287.0 → 5.289.0

package/CHANGELOG.md

@@ -2,10 +2,13 @@
 
 ## [Unreleased]
 
+## [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.
@@ -15,6 +18,44 @@
 - `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
+
+- Confirm primary-dispatched Outpost profile recovery when it is queued for
+  reconcile, and sync the cleared recovery state to the primary lane mirror.
+- Cache-first `hq lanes list` now allows one detached Outpost summary refresh
+  per HQ root at a time, avoiding duplicate work from overlapping list calls.
+
+### Fixed
+
+- The lanes hook reads only transcript bytes appended since its last check.
+  It still replays compaction messages and resets the offset when a transcript
+  is replaced or truncated.
+
+### Added
+
+- `hq core ontology merge-copies --only <file>` handles only the copy -> original pairs listed in a JSON file and reports every other found pair as skipped (`not_listed`).
+
+### Changed
+
+- The checkpoint ontology step always applies its ten quality rules (company
+  brief, annotation stripping on grok, grok-first backend, no link aliases,
+  first-name people, ambiguous concept links, dominant sibling link, hub
+  mention floor, concept-project link, named evidence). Their
+  `checkpoint.ontology.*` flags, on for everyone since 2026-09-29, are no
+  longer read.
+
+### Added
+
+- Record company-scoped exposure for printed CLI plan-limit notices when the default-off `billing.limit-at-action-prompt` flag is enabled; count an upgrade engagement only after the user confirms opening the link.
+
+### Fixed
+
+- `hq secrets` and other noninteractive person-token callers reuse a fresh same-principal session written by another process while a stale refresh is rejected.
 
 ## [5.286.0] — 2026-09-29
 
@@ -27,11 +68,6 @@
   it, and output the old daemon had not read reaches the new one. Other
   platforms keep the anonymous pipe.
 
-### Fixed
-
-- Cache-first `hq lanes list` now allows one detached Outpost summary refresh
-  per HQ root at a time, avoiding duplicate work from overlapping list calls.
-
 ## [5.285.0] — 2026-09-29
 
 - Route eligible Linux CI jobs onto ARM runners while retaining existing test and platform gates.
@@ -42,6 +78,13 @@
 
 ### Fixed
 
+- Recover a queued Outpost lane held for `worker_profile_changed` with its
+  printed `hq lanes resume <id> --worker <profile>` command. The lane owner's
+  profile copy is authoritative: the command records an authorized re-pin in
+  history, leaves the lane queued for normal reconcile admission, and syncs the
+  cleared recovery state back to the primary mirror. Other queued lanes still
+  require `hq lanes admit`.
+
 - A remote `hq lanes list` read no longer dispatches owner hire summaries,
   capacity probes, or mirror snapshots to other Outposts. Two Outposts that
   each held a lane placed on the other ran `hq lanes list --json` on each other

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/command-catalog.generated.d.ts

@@ -5205,6 +5205,9 @@ export declare const COMMAND_CATALOG: readonly [{
             }, {
                 readonly flags: "--limit <n>";
                 readonly description: "handle at most this many copies";
+            }, {
+                readonly flags: "--only <file>";
+                readonly description: "handle only the copy -> original pairs listed in this JSON file";
             }, {
                 readonly flags: "--json";
                 readonly description: "print JSON";

package/dist/command-catalog.generated.js

@@ -6730,6 +6730,10 @@ export const COMMAND_CATALOG = [
                                 "flags": "--limit <n>",
                                 "description": "handle at most this many copies"
                             },
+                            {
+                                "flags": "--only <file>",
+                                "description": "handle only the copy -> original pairs listed in this JSON file"
+                            },
                             {
                                 "flags": "--json",
                                 "description": "print JSON"

package/dist/commands/agent-enroll.js

@@ -20,6 +20,7 @@ import * as os from "node:os";
 import { CLI_VERSION } from "../cli-version.js";
 import { DEFAULT_VAULT_API_URL, personTokenCacheFile, } from "../utils/cognito-session.js";
 import { HQ_CLIENT_NAME } from "../utils/vault-api.js";
+import { queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
 import { networkTransportErrorCode } from "../utils/network-transport-error.js";
 import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, planGateErrorFromPayload, } from "../utils/plan-gate-error.js";
 import { generateHostKeyPair, machineCredsFileExists, readExternalMachineCreds, writeHostKeyPair, writeMachineCreds, } from "../lib/agent-kit/creds.js";
@@ -373,9 +374,14 @@ export function registerAgentEnrollCommand(agent) {
             else if (err instanceof EnrollError && err.upgradeUrl) {
                 const interactive = canOfferTeamUpgrade();
                 console.error(chalk.red(formatEnrollFailureMessage(err, { urlOnly: !interactive })));
+                const exposure = err.code === "billing_required"
+                    ? queueCliLimitNoticeExposure("agents", "refusal")
+                    : null;
                 if (interactive) {
                     try {
-                        await offerUpgradeLink(err.upgradeUrl, { interactive: true });
+                        const opened = await offerUpgradeLink(err.upgradeUrl, { interactive: true });
+                        if (opened)
+                            queueCliLimitNoticeEngagement(exposure);
                     }
                     catch (openErr) {
                         const message = openErr instanceof Error ? openErr.message : String(openErr);
@@ -386,7 +392,9 @@ export function registerAgentEnrollCommand(agent) {
             else {
                 console.error(chalk.red(err instanceof Error ? err.message : String(err)));
             }
-            process.exit(1);
+            // Let the CLI's bounded finalization flush the best-effort prompt
+            // telemetry before the process exits with the same failure status.
+            process.exitCode = 1;
         }
     });
 }

package/dist/commands/agents.d.ts

@@ -62,6 +62,7 @@ export declare function agentCreatePlanLimitFromPayload(status: number, body: un
 /** Print a server-priced plan block without minting or rewriting its URL. */
 export declare function surfaceAgentCreatePlanLimit(planLimit: AgentCreatePlanLimit, opts?: {
     json?: boolean;
+    companyUid?: string;
 }): Promise<void>;
 /**
  * Resolve a closed-set option value, or exit(1) with a message naming the

package/dist/commands/agents.js

@@ -34,6 +34,7 @@ import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { maxLength } from "../utils/table-width.js";
 import { DEFAULT_VAULT_API_URL } from "../utils/cognito-session.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
+import { queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 import { consoleOrigin } from "./integrations-connect.js";
 import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSessionTimeoutError, waitForTerminalSession, } from "@indigoai-us/hq-cloud/outposts/node";
@@ -128,13 +129,14 @@ function formatServerPrice(amountMinor, currency) {
 async function offerAgentCheckout(url) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
     try {
-        await offerUpgradeLink(url, {
+        return await offerUpgradeLink(url, {
             interactive: true,
             ask: (question) => new Promise((resolve) => rl.question(question, resolve)),
         });
     }
     catch {
         console.error("Could not open the upgrade page automatically. Use the URL above.");
+        return false;
     }
     finally {
         rl.close();
@@ -149,11 +151,14 @@ export async function surfaceAgentCreatePlanLimit(planLimit, opts = {}) {
     if (!planLimit.checkoutUrl) {
         console.error(reason);
         console.error("Ask a company owner to upgrade before creating an agent.");
+        queueCliLimitNoticeExposure("agents", "refusal", opts.companyUid);
         return;
     }
     console.error(formatUpgradeRefusal(reason, planLimit.checkoutUrl, { urlOnly: !interactive }));
-    if (interactive)
-        await offerAgentCheckout(planLimit.checkoutUrl);
+    const exposure = queueCliLimitNoticeExposure("agents", "refusal", opts.companyUid);
+    if (interactive && await offerAgentCheckout(planLimit.checkoutUrl)) {
+        queueCliLimitNoticeEngagement(exposure);
+    }
 }
 /**
  * Resolve a closed-set option value, or exit(1) with a message naming the
@@ -1548,7 +1553,10 @@ export function registerAgentsCommand(program) {
                     if (!err.agentCreatePlanLimit) {
                         throw new Error("HQ Pro returned an unrecognized agent payment-required response.");
                     }
-                    await surfaceAgentCreatePlanLimit(err.agentCreatePlanLimit, opts);
+                    await surfaceAgentCreatePlanLimit(err.agentCreatePlanLimit, {
+                        ...opts,
+                        companyUid,
+                    });
                     // Keep the payment-required status through normal CLI teardown.
                     // Unlike process.exit(), this is testable and cannot be caught by
                     // this action's outer error boundary as a generic failure.

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

@@ -9,7 +9,7 @@
  */
 import { Command } from "commander";
 import { type FlagReader } from "../lib/checkpoint-ontology/plan.js";
-import { type DeleteVaultKey } from "../lib/checkpoint-ontology/merge-copies.js";
+import { type DeleteVaultKey, type ListedPair } from "../lib/checkpoint-ontology/merge-copies.js";
 export declare const ONTOLOGY_PAYLOAD_FILE = "payload.json";
 /** The hq-flags read, scoped to the payload company. */
 export declare const registryFlagReader: FlagReader;
@@ -32,8 +32,11 @@ export interface MergeCopiesCommandOptions {
     delete?: boolean;
     variants?: boolean;
     limit?: number;
+    only?: string;
     json?: boolean;
 }
+/** Reads a `--only` file: a JSON array of `{ copy, original }` company-relative paths. */
+export declare function readListedPairs(file: string): ListedPair[];
 /**
  * `hq core ontology merge-copies`: merge `<slug> <n>.md` copies into their
  * original (`--apply`), then delete merged copies from the vault

package/dist/commands/core-ontology.js

@@ -153,8 +153,31 @@ function mergeCopiesSummary(report) {
         lines.push(`  held ${plan.copy}: ${plan.held}`);
     for (const error of report.errors)
         lines.push(`  error ${error.path}: ${error.error}`);
+    for (const entry of report.only_unmatched ?? [])
+        lines.push(`  not found ${entry.copy} -> ${entry.original}`);
     return lines.join("\n");
 }
+/** Reads a `--only` file: a JSON array of `{ copy, original }` company-relative paths. */
+export function readListedPairs(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new OntologyUsageError(`ontology: --only file ${file} is not readable JSON: ${error.message}`);
+    }
+    if (!Array.isArray(parsed) ||
+        parsed.length === 0 ||
+        !parsed.every((entry) => {
+            if (!entry || typeof entry !== "object")
+                return false;
+            const record = entry;
+            return typeof record.copy === "string" && typeof record.original === "string";
+        })) {
+        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 }));
+}
 /**
  * `hq core ontology merge-copies`: merge `<slug> <n>.md` copies into their
  * original (`--apply`), then delete merged copies from the vault
@@ -171,6 +194,7 @@ export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
     if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1)) {
         throw new OntologyUsageError("ontology: --limit must be a positive whole number");
     }
+    const only = options.only !== undefined ? readListedPairs(options.only) : undefined;
     const resolution = resolveOntologyCompany(hqRoot, slug);
     if (!resolution.ok)
         throw new OntologyUsageError(`ontology: company rejected: ${resolution.reason}`);
@@ -195,6 +219,7 @@ export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
         now: deps.now?.() ?? new Date(),
         ...(options.variants ? { pairKind: "variants" } : {}),
         ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        ...(only ? { only } : {}),
         ...(deleteVaultKey ? { deleteVaultKey } : {}),
     });
     return options.json ? JSON.stringify(report, null, 2) : mergeCopiesSummary(report);
@@ -248,6 +273,7 @@ export function registerCoreOntologyCommand(core) {
         .option("--delete", "delete fully merged copies from the vault by exact key (after sync pushed the merge)")
         .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("--json", "print JSON")
         .option("--hq-root <path>", "HQ installation to operate on")
         .action(async (options) => {

package/dist/commands/lanes-resume.js

@@ -153,10 +153,27 @@ export function createLaneResumeHandlers(deps) {
         if (opts.account !== undefined && !providerSessionPortable(lane.provider)) {
             throw new LanesError("provider_session_not_portable", sessionNotPortableMessage(lane.provider), { lane_id: laneId, provider: lane.provider });
         }
-        if (lane.state === "queued") {
+        if (lane.state === "queued" &&
+            (lane.queued_reason !== "worker_profile_changed" || opts.worker === undefined)) {
             throw new LanesError("lane_not_resumable", `Lane ${laneId} is queued; use hq lanes admit ${laneId} to request admission`, { lane_id: laneId, state: lane.state, admission_command: `hq lanes admit ${laneId}` });
         }
-        const refusal = resumeCommandRefusal(lane, { allowFailed: opts.fromFailed === true });
+        const queuedProfileRecovery = lane.state === "queued" &&
+            lane.queued_reason === "worker_profile_changed" &&
+            opts.worker !== undefined;
+        if (queuedProfileRecovery && (opts.text !== undefined ||
+            opts.project !== undefined ||
+            opts.story !== undefined ||
+            opts.account !== undefined ||
+            opts.model !== undefined ||
+            opts.effort !== undefined ||
+            opts.keepAlive !== undefined ||
+            opts.meshCompany !== undefined ||
+            opts.compact === false)) {
+            throw new LanesError("worker_profile_recovery_options_invalid", "Queued worker-profile recovery accepts only --worker; rerun hq lanes resume after reconcile admits the lane", { lane_id: laneId });
+        }
+        const refusal = queuedProfileRecovery
+            ? null
+            : resumeCommandRefusal(lane, { allowFailed: opts.fromFailed === true });
         if (refusal !== null) {
             throw new LanesError(refusal.error, refusal.message, {
                 lane_id: laneId,
@@ -206,6 +223,28 @@ export function createLaneResumeHandlers(deps) {
         if (resumeProfile !== undefined && (opts.account === undefined || keepCurrentAccount)) {
             validateResumeProfileModel(ctx, lane, resumeProfile.profile);
         }
+        if (lane.state === "queued" && lane.queued_reason === "worker_profile_changed") {
+            if (resumeProfile === undefined) {
+                throw new LanesError("worker_profile_required", `Lane ${laneId} needs --worker ${lane.worker_profile ?? "<profile>"} to recover its queued profile`, { lane_id: laneId, worker: lane.worker_profile ?? null });
+            }
+            const recovered = recordResumeSetup(ctx, lane, {
+                profile: resumeProfile,
+                ...(profileRepin !== undefined ? { profileRepin } : {}),
+                clearWorkerProfileChangedQueue: true,
+            });
+            printJson({
+                ok: true,
+                action: "resume",
+                lane_id: laneId,
+                delivery: "profile_repin",
+                delivery_status: "queued_for_reconcile",
+                profile_repin: profileRepin !== undefined
+                    ? recovered.worker_profile_repin_history?.at(-1) ?? null
+                    : null,
+                lane: recovered,
+            });
+            return;
+        }
         const automaticAccountSelection = opts.account === undefined
             ? await selectAutomaticClaudeResumeAccount(ctx, lane, resumeProfile, { repairUnavailableAccount: true })
             : undefined;

package/dist/commands/lanes-shared.d.ts

@@ -113,6 +113,8 @@ export interface RecordResumeSetupInput {
     meshCompany?: LaneCompanyRef;
     threadId?: string;
     profileRepin?: ResumeProfileRepinAuthorization;
+    /** Clear only the recoverable worker_profile_changed queue after its profile is revalidated. */
+    clearWorkerProfileChangedQueue?: boolean;
 }
 export declare function accountRequestKeepsCurrentLane(lane: LaneRecord, rawAccount: string): boolean;
 export declare function assertCurrentResumeAccountAvailable(ctx: Ctx, lane: LaneRecord): void;