@indigoai-us/hq-cli 5.190.0 → 5.192.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [5.192.0] — 2026-09-25
+
+### Added
+
+- `hq agents models` lists cloud-agent catalog entries by provider and supports JSON output.
+  Provision and update validate model IDs against the catalog. They use the cached
+  catalog when the endpoint is unavailable, and rely on server validation if no cache exists.
+
+### Fixed
+
+- `hq report adopt` checks whether scheduled jobs are enabled for the company before creating a cloud job, and explains when the server rejects a disabled job.
+
+## [5.191.0] — 2026-09-25
+
+### Fixed
+
+- `hq agents provision` now rejects an invalid `--slug` before sending the agent create request.
+
 ## [5.190.0] — 2026-09-25
 
 ### Added
@@ -19,6 +37,12 @@
 - `hq bot promote` accepts server-signed upload URLs without SSE headers when the bucket supplies encryption. SSE header names are checked case-insensitively, and any supplied encryption must be a complete SSE-KMS pair.
 - Company slug lookup errors now point to the supported `hq sources entities` command.
 
+### Added
+
+- QMD native-binding startup failures after sync can emit an actionable warning
+  when the `qmd.reindex-startup-warning` hq-flags canary is enabled. The flag
+  defaults off, and sync still succeeds when indexing cannot run.
+
 ## [5.189.0] — 2026-09-25
 
 ### Added

package/dist/command-catalog.generated.d.ts

@@ -3845,6 +3845,21 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly description: "Company slug (resolves to companyUid)";
     }];
     readonly subcommands: readonly [{
+        readonly name: "models";
+        readonly description: "List the model catalog available to cloud agents";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--provider <provider>";
+            readonly description: "Filter to one provider: codex, grok, or claude";
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print the stable catalog JSON shape";
+        }];
+        readonly subcommands: readonly [];
+    }, {
         readonly name: "message";
         readonly description: "Send a message to an agent and wait for its reply";
         readonly aliases: readonly ["msg"];
@@ -3939,7 +3954,7 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Runtime: agents-v2 (recommended) | codex | grok | claude (accepted for script compatibility; use agents-v2 for new Claude agents)";
         }, {
             readonly flags: "--model <model>";
-            readonly description: "Brain model, for example claude-opus-5-5, gpt-5.5, or grok-4.6";
+            readonly description: "Brain model from `hq agents models`";
         }, {
             readonly flags: "--auth-mode <mode>";
             readonly description: "Auth: subscription | apiKey (default subscription)";
@@ -4074,7 +4089,7 @@ export declare const COMMAND_CATALOG: readonly [{
     }, {
         readonly name: "config";
         readonly description: "Update an agent's runtime config (model / reasoning effort / service tier), or migrate its brain/runtime provider with --provider (DESTRUCTIVE: terminates + reprovisions the box)";
-        readonly aliases: readonly [];
+        readonly aliases: readonly ["update"];
         readonly hidden: false;
         readonly usage: "[options] <agentUid>";
         readonly arguments: readonly [{
@@ -4087,7 +4102,7 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Company slug (resolves to companyUid)";
         }, {
             readonly flags: "--model <model>";
-            readonly description: "Codex model id";
+            readonly description: "Model id from `hq agents models`";
         }, {
             readonly flags: "--effort <effort>";
             readonly description: "Reasoning effort: minimal | low | medium | high | xhigh";

package/dist/command-catalog.generated.js

@@ -4961,6 +4961,25 @@ export const COMMAND_CATALOG = [
             }
         ],
         "subcommands": [
+            {
+                "name": "models",
+                "description": "List the model catalog available to cloud agents",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--provider <provider>",
+                        "description": "Filter to one provider: codex, grok, or claude"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print the stable catalog JSON shape"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "message",
                 "description": "Send a message to an agent and wait for its reply",
@@ -5092,7 +5111,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--model <model>",
-                        "description": "Brain model, for example claude-opus-5-5, gpt-5.5, or grok-4.6"
+                        "description": "Brain model from `hq agents models`"
                     },
                     {
                         "flags": "--auth-mode <mode>",
@@ -5268,7 +5287,9 @@ export const COMMAND_CATALOG = [
             {
                 "name": "config",
                 "description": "Update an agent's runtime config (model / reasoning effort / service tier), or migrate its brain/runtime provider with --provider (DESTRUCTIVE: terminates + reprovisions the box)",
-                "aliases": [],
+                "aliases": [
+                    "update"
+                ],
                 "hidden": false,
                 "usage": "[options] <agentUid>",
                 "arguments": [
@@ -5285,7 +5306,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "flags": "--model <model>",
-                        "description": "Codex model id"
+                        "description": "Model id from `hq agents models`"
                     },
                     {
                         "flags": "--effort <effort>",

package/dist/commands/agents.d.ts

@@ -28,6 +28,7 @@
  */
 import { Command } from "commander";
 import { type TerminalSessionPayload } from "@indigoai-us/hq-cloud/outposts/node";
+import { type AgentModelProvider, type AgentModelCatalog } from "../lib/agents/model-catalog.js";
 import { type BillingErrorPayload } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export declare const VALID_EFFORTS: Set<string>;
@@ -341,6 +342,8 @@ export declare function formatJobsTable(jobs: AgentJobView[]): string;
 export declare function formatPauseResult(result: PauseJobResult): string;
 /** Human-readable "hot-applied to the running box" vs "saved for next launch". */
 export declare function appliedHint(applied: boolean): string;
+/** Stable human table shared by the all-provider and provider-filtered forms. */
+export declare function formatAgentModelsTable(catalog: AgentModelCatalog, selectedProvider?: AgentModelProvider): string;
 /** Agent uid shape (`agt_…`). */
 /** One message in a DM thread, as returned by `GET /v1/notify/thread`. */
 export interface DmThreadMessage {

package/dist/commands/agents.js

@@ -38,6 +38,7 @@ import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSe
 import { peekIdToken } from "../utils/id-token.js";
 import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, } from "../utils/plan-gate-error.js";
 import { AGENT_UID_PATTERN, isAgentUid } from "../lib/notify-recipient.js";
+import { AGENT_MODEL_PROVIDERS, modelSelectionErrorMessage, readAgentModelCatalog, validateAgentModelSelection, } from "../lib/agents/model-catalog.js";
 import { confirmChargeOrExit, formatUsd, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
@@ -55,11 +56,14 @@ export const VALID_PROVIDERS = new Set(["codex", "grok", "claude", "agents-v2"])
 export const VALID_AUTH_MODES = new Set(["subscription", "apiKey"]);
 /** Customer-facing agent size keys served by hq-pro's authoritative catalog. */
 export const VALID_AGENT_SIZE_KEYS = new Set(["basic", "power", "dev"]);
-const CLAUDE_PROVISION_COMMAND = "hq agents provision <name> --provider agents-v2 --model claude-opus-5-5";
+// Keep cloud agent create slugs aligned with hq-pro-agents POST /v1/agents.
+const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const CLAUDE_PROVISION_COMMAND = "hq agents provision <name> --provider agents-v2 --model <model-id>";
 const CLAUDE_API_KEY_ARGS = "--auth-mode apiKey --api-key-env <VAR>";
 function claudeProvisionGuidance() {
     return [
         "The account must be enabled for Claude. Subscription auth is the default.",
+        "Use `hq agents models` to see the current model ids.",
         `Create an agent with: ${CLAUDE_PROVISION_COMMAND}`,
         `For API-key auth, add: ${CLAUDE_API_KEY_ARGS}`,
         "The CLI accepts --provider claude for script compatibility, but the server rejects new agents that use it.",
@@ -861,6 +865,50 @@ export function appliedHint(applied) {
         ? "applied to the running box now"
         : "saved — takes effect on the agent's next launch";
 }
+async function validateAgentModelOption(token, chosenProvider, modelId) {
+    const result = await readAgentModelCatalog(token);
+    if (!result.ok) {
+        if (result.reason === "unavailable") {
+            console.error(chalk.yellow("model validation skipped: catalog unavailable (the server still validates)."));
+            return;
+        }
+        throw new Error(`Could not read the model catalog (HTTP ${result.status}). Check your hq login and try again.`);
+    }
+    if (result.source === "cache") {
+        console.error(chalk.yellow(`Model catalog unavailable; validating against the cached catalog from ${new Date(result.fetchedAt).toISOString()}.`));
+    }
+    const selection = validateAgentModelSelection(result.catalog, modelId, chosenProvider);
+    if (!selection.ok) {
+        throw new Error(modelSelectionErrorMessage(modelId, selection));
+    }
+}
+/** Stable human table shared by the all-provider and provider-filtered forms. */
+export function formatAgentModelsTable(catalog, selectedProvider) {
+    const providers = selectedProvider ? [selectedProvider] : AGENT_MODEL_PROVIDERS;
+    const sections = providers.map((provider) => {
+        const view = catalog.providers[provider];
+        const columns = ["ID", "LABEL", "DEFAULT", "NEW", "AVAILABILITY"];
+        const rows = view.models.map((model) => [
+            model.id,
+            model.label,
+            model.id === view.defaultModel ? "yes" : "",
+            model.isNew ? "yes" : "",
+            model.selectable ? "available" : "not yet on agents",
+        ]);
+        const widths = columns.map((column, index) => Math.max(column.length, ...rows.map((row) => row[index].length)));
+        const render = (cells) => cells.map((cell, index) => cell.padEnd(widths[index])).join("  ").trimEnd();
+        return [
+            chalk.bold(provider.toUpperCase()),
+            render(columns),
+            ...rows.map(render),
+        ].join("\n");
+    });
+    return sections.join("\n\n");
+}
+function catalogUnavailableMessage() {
+    return ("Model catalog is unavailable and no cached copy exists. " +
+        "Check your connection and try again after model-catalog.serve is enabled.");
+}
 /**
  * Resolve an agent reference to its `agt_` uid. An `agt_…` value is used
  * directly; anything else is treated as a slug or display name and resolved
@@ -1095,6 +1143,8 @@ export function registerAgentsCommand(program) {
         bySubcommand: {
             message: { capability: "agents:use", routeAvailable: false },
             thread: { capability: "agents:use", routeAvailable: false },
+            // The catalog read endpoint is JWT-only; hq-pro has no keyed parallel.
+            models: { capability: "agents:use", routeAvailable: false },
             // Interactive terminals are for humans: hq-pro serves no keyed
             // `/v1/keys/agents/{uid}/terminal` route, so machine keys fail closed.
             terminal: { capability: "agents:use", routeAvailable: false },
@@ -1110,6 +1160,43 @@ export function registerAgentsCommand(program) {
     // `hq agents --company acme list`.
     const companyOf = (sub) => sub.opts().company ??
         agents.opts().company;
+    agents
+        .command("models")
+        .description("List the model catalog available to cloud agents")
+        .option("--provider <provider>", "Filter to one provider: codex, grok, or claude")
+        .option("--json", "Print the stable catalog JSON shape")
+        .action(async (opts) => {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await readAgentModelCatalog(token);
+            if (!result.ok) {
+                if (result.reason === "request_failed") {
+                    throw new Error(`Could not read the model catalog (HTTP ${result.status}). Check your hq login and try again.`);
+                }
+                console.error(chalk.red(catalogUnavailableMessage()));
+                process.exit(1);
+            }
+            if (result.source === "cache") {
+                console.error(chalk.yellow(`Model catalog unavailable; showing cached catalog from ${new Date(result.fetchedAt).toISOString()}.`));
+            }
+            const providers = opts.provider
+                ? { [opts.provider]: result.catalog.providers[opts.provider] }
+                : result.catalog.providers;
+            if (opts.json) {
+                // Stable shape: { generatedAt, providers }. A provider filter selects
+                // one key but never changes or flattens the response envelope.
+                process.stdout.write(JSON.stringify({ generatedAt: result.catalog.generatedAt, providers }, null, 2) + "\n");
+                return;
+            }
+            console.log(formatAgentModelsTable(result.catalog, opts.provider));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    agents.commands.find((command) => command.name() === "models")
+        ?.options.find((option) => option.long === "--provider")
+        ?.choices(AGENT_MODEL_PROVIDERS);
     agents
         .command("message <agent> <message...>")
         .alias("msg")
@@ -1267,7 +1354,7 @@ export function registerAgentsCommand(program) {
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--slug <slug>", "Agent slug (defaults to a slug of <name>)")
         .option("--provider <provider>", "Runtime: agents-v2 (recommended) | codex | grok | claude (accepted for script compatibility; use agents-v2 for new Claude agents)")
-        .option("--model <model>", "Brain model, for example claude-opus-5-5, gpt-5.5, or grok-4.6")
+        .option("--model <model>", "Brain model from `hq agents models`")
         .option("--auth-mode <mode>", "Auth: subscription | apiKey (default subscription)", "subscription")
         .option("--api-key-env <VAR>", "Env var holding the API key for --auth-mode apiKey (never pass the key as a flag)")
         .option("--slack-bot-token <xoxb-token>", "Reuse an existing Slack bot token; HQ_SLACK_BOT_TOKEN or --slack-tokens-stdin avoid shell history")
@@ -1281,6 +1368,12 @@ export function registerAgentsCommand(program) {
         .addHelpText("after", `\n${claudeProvisionGuidance()}\n`)
         .action(async function (name, opts) {
         try {
+            const slug = opts.slug ?? slugifyAgentName(name);
+            if (!AGENT_SLUG_PATTERN.test(slug)) {
+                console.error(chalk.red("Agent slug must start with a lowercase letter or digit, contain only lowercase letters, digits, and hyphens, and be at most 63 characters. " +
+                    "Update --slug or the agent name."));
+                process.exit(1);
+            }
             // Both of these previously fell back to their default on an
             // unrecognised value, silently provisioning a billable box the operator
             // did not ask for. They now exit(1) instead — see parseEnumOption.
@@ -1326,6 +1419,9 @@ export function registerAgentsCommand(program) {
             }
             const token = (await resolveVaultCredential()).token;
             const companyUid = await getCompanyUid(token, companyOf(this));
+            if (opts.model !== undefined) {
+                await validateAgentModelOption(token, provider, opts.model);
+            }
             const idempotencyKey = `hq-cli-${randomUUID()}`;
             const sizeKey = parseEnumOption(opts.size, VALID_AGENT_SIZE_KEYS, "--size");
             const shouldChooseInteractively = !sizeKey && process.stdin.isTTY === true;
@@ -1341,7 +1437,6 @@ export function registerAgentsCommand(program) {
             // Every path confirms hq-pro's company-specific quote. Omission still
             // leaves the POST size implicit, preserving the server-side default.
             confirmAgentCreateQuoteOrExit(quotedSize, opts.yes, opts.json);
-            const slug = opts.slug ?? slugifyAgentName(name);
             try {
                 const result = await provisionAgent(token, {
                     companyUid,
@@ -1629,9 +1724,10 @@ export function registerAgentsCommand(program) {
     });
     agents
         .command("config <agentUid>")
+        .alias("update")
         .description("Update an agent's runtime config (model / reasoning effort / service tier), or migrate its brain/runtime provider with --provider (DESTRUCTIVE: terminates + reprovisions the box)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
-        .option("--model <model>", "Codex model id")
+        .option("--model <model>", "Model id from `hq agents models`")
         .option("--effort <effort>", "Reasoning effort: minimal | low | medium | high | xhigh")
         .option("--tier <tier>", "Service tier (speed): default | priority")
         .option("--provider <provider>", "Migrate brain/runtime provider (codex | grok | claude | agents-v2). DESTRUCTIVE: terminates and reprovisions the box; requires --model and --yes.")
@@ -1700,6 +1796,9 @@ export function registerAgentsCommand(program) {
                 process.exit(1);
             }
             const token = (await resolveVaultCredential()).token;
+            if (opts.model !== undefined) {
+                await validateAgentModelOption(token, opts.provider?.trim().toLowerCase(), opts.model);
+            }
             const result = await patchAgentRuntimeConfig(token, agentUid, patch);
             if (opts.json) {
                 process.stdout.write(JSON.stringify(result, null, 2) + "\n");

package/dist/commands/report.js

@@ -9,6 +9,7 @@ import { adoptReport, buildReportTarball, conventionReportDir, deployOrgContext,
 const DEPLOY_API_URL = process.env.HQ_DEPLOY_API_URL ?? "https://api.indigo-hq.com";
 const REPORT_CHANNEL_STATE_FILE = "report-channels.json";
 const MAX_REPORT_DISCOVERY_CHANNELS = 50;
+const JOB_EXECUTION_DISABLED_MESSAGE = "Scheduled jobs are turned off for this company. A company owner can turn them back on.";
 function reportPath(channelId, reportId) {
     return `/v1/notify/channels/${encodeURIComponent(channelId)}/reports/${encodeURIComponent(reportId)}`;
 }
@@ -414,10 +415,39 @@ async function cancelOwnedJob(token, agentUid, jobId) {
     if (!res.ok && res.status !== 404)
         throw new ReportPublishError("Could not remove the report job.");
 }
+async function requireScheduledJobsEnabled(token, agentUid) {
+    let executionEnabled;
+    try {
+        const res = await vaultApiFetch({
+            token,
+            path: `/v1/agents/${encodeURIComponent(agentUid)}/jobs`,
+            method: "GET",
+        });
+        if (!res.ok) {
+            console.debug("Scheduled job preflight was unavailable; proceeding with job creation.", { status: res.status });
+            return;
+        }
+        const body = await res.json();
+        if (body && typeof body === "object" && !Array.isArray(body)) {
+            executionEnabled = body.executionEnabled;
+        }
+    }
+    catch (error) {
+        console.debug("Scheduled job preflight failed; proceeding with job creation.", error);
+        return;
+    }
+    if (executionEnabled === false) {
+        throw new ReportPublishError(JOB_EXECUTION_DISABLED_MESSAGE, "job-execution-disabled");
+    }
+    if (executionEnabled !== true) {
+        console.debug("Scheduled job preflight did not return a boolean executionEnabled; proceeding with job creation.");
+    }
+}
 async function adoptAction(reportId, options) {
     const token = await ensureCognitoToken();
     const report = await resolveReport(token, reportId, options.channel);
     const updated = await adoptReport(report, {
+        preflightJobCreation: () => requireScheduledJobsEnabled(token, report.ownerAgentUid),
         cancelJob: (jobId) => cancelOwnedJob(token, report.ownerAgentUid, jobId),
         createJob: async (input) => {
             const res = await vaultApiFetch({
@@ -426,8 +456,21 @@ async function adoptAction(reportId, options) {
                 method: "POST",
                 body: input,
             });
-            if (!res.ok)
+            if (!res.ok) {
+                if (res.status === 409) {
+                    let rejection;
+                    try {
+                        rejection = await res.json();
+                    }
+                    catch {
+                        // A non-JSON conflict response is still the generic install failure.
+                    }
+                    if (rejection?.code === "JOB_EXECUTION_DISABLED") {
+                        throw new ReportPublishError(JOB_EXECUTION_DISABLED_MESSAGE, "job-execution-disabled");
+                    }
+                }
                 throw new ReportPublishError("Could not install the report job.");
+            }
             const body = await res.json();
             const jobId = body.job?.jobId ?? body.jobId;
             if (!jobId)

package/dist/lib/agents/model-catalog.d.ts

@@ -0,0 +1,61 @@
+export declare const AGENT_MODEL_PROVIDERS: readonly ["codex", "grok", "claude"];
+export type AgentModelProvider = (typeof AGENT_MODEL_PROVIDERS)[number];
+export interface AgentCatalogModel {
+    id: string;
+    label: string;
+    visibility: string;
+    isNew: boolean;
+    authModes: string[];
+    efforts: string[];
+    selectable: boolean;
+    unavailableReason?: string | null;
+}
+export interface AgentCatalogProvider {
+    models: AgentCatalogModel[];
+    defaultModel: string;
+}
+export interface AgentModelCatalog {
+    providers: Record<AgentModelProvider, AgentCatalogProvider>;
+    generatedAt: string;
+}
+export type AgentModelCatalogResult = {
+    ok: true;
+    catalog: AgentModelCatalog;
+    etag: string;
+    fetchedAt: number;
+    source: "network" | "cache";
+} | {
+    ok: false;
+    reason: "unavailable";
+} | {
+    ok: false;
+    reason: "request_failed";
+    status: number;
+};
+export interface ReadAgentModelCatalogOptions {
+    baseUrl?: string;
+    cacheFile?: string;
+    now?: () => number;
+    request?: (headers: Record<string, string>, signal: AbortSignal) => Promise<Response>;
+    timeoutMs?: number;
+}
+/** Use the same effective state directory as the CLI's person-token cache. */
+export declare function agentModelCatalogCacheFile(baseUrl?: string, home?: string, env?: NodeJS.ProcessEnv): string;
+/** Parse the documented response without constraining forward-compatible string values. */
+export declare function parseAgentModelCatalog(value: unknown): AgentModelCatalog | null;
+/** Read the live endpoint, conditionally refresh it, and fall back to the last good cache. */
+export declare function readAgentModelCatalog(token: string, options?: ReadAgentModelCatalogOptions): Promise<AgentModelCatalogResult>;
+export type ModelSelectionResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "unknown" | "not_selectable";
+    provider?: AgentModelProvider;
+    suggestions: string[];
+};
+/** Check an explicit model against the selected provider or inferred agents-v2 brain. */
+export declare function validateAgentModelSelection(catalog: AgentModelCatalog, modelId: string, chosenProvider?: string): ModelSelectionResult;
+export declare function modelSelectionErrorMessage(modelId: string, result: Extract<ModelSelectionResult, {
+    ok: false;
+}>): string;
+//# sourceMappingURL=model-catalog.d.ts.map

package/dist/lib/agents/model-catalog.js

@@ -0,0 +1,275 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { DEFAULT_VAULT_API_URL, personTokenCacheFile } from "../../utils/cognito-session.js";
+import { vaultApiFetch } from "../../utils/vault-api.js";
+export const AGENT_MODEL_PROVIDERS = ["codex", "grok", "claude"];
+const MODEL_CATALOG_REQUEST_TIMEOUT_MS = 15_000;
+/** Use the same effective state directory as the CLI's person-token cache. */
+export function agentModelCatalogCacheFile(baseUrl = DEFAULT_VAULT_API_URL, home = os.homedir(), env = process.env) {
+    const scope = createHash("sha256").update(baseUrl).digest("hex").slice(0, 16);
+    return path.join(path.dirname(personTokenCacheFile(home, env)), `agent-model-catalog-${scope}.json`);
+}
+/** Parse the documented response without constraining forward-compatible string values. */
+export function parseAgentModelCatalog(value) {
+    if (!isRecord(value) || !isRecord(value.providers))
+        return null;
+    if (typeof value.generatedAt !== "string" || !Number.isFinite(Date.parse(value.generatedAt))) {
+        return null;
+    }
+    const providers = {};
+    for (const provider of AGENT_MODEL_PROVIDERS) {
+        const rawProvider = value.providers[provider];
+        if (!isRecord(rawProvider) ||
+            !Array.isArray(rawProvider.models) ||
+            typeof rawProvider.defaultModel !== "string") {
+            return null;
+        }
+        const models = [];
+        for (const rawModel of rawProvider.models) {
+            if (!isRecord(rawModel) ||
+                typeof rawModel.id !== "string" ||
+                !/^[A-Za-z0-9._-]{1,128}$/.test(rawModel.id) ||
+                typeof rawModel.label !== "string" ||
+                typeof rawModel.visibility !== "string" ||
+                typeof rawModel.isNew !== "boolean" ||
+                !isStringArray(rawModel.authModes) ||
+                !isStringArray(rawModel.efforts) ||
+                typeof rawModel.selectable !== "boolean" ||
+                (rawModel.unavailableReason !== undefined &&
+                    rawModel.unavailableReason !== null &&
+                    typeof rawModel.unavailableReason !== "string")) {
+                return null;
+            }
+            models.push({
+                id: rawModel.id,
+                label: rawModel.label,
+                visibility: rawModel.visibility,
+                isNew: rawModel.isNew,
+                authModes: rawModel.authModes,
+                efforts: rawModel.efforts,
+                selectable: rawModel.selectable,
+                ...(rawModel.unavailableReason !== undefined
+                    ? { unavailableReason: rawModel.unavailableReason }
+                    : {}),
+            });
+        }
+        if (!models.some((model) => model.id === rawProvider.defaultModel && model.selectable)) {
+            return null;
+        }
+        providers[provider] = { models, defaultModel: rawProvider.defaultModel };
+    }
+    return { providers, generatedAt: value.generatedAt };
+}
+/** Read the live endpoint, conditionally refresh it, and fall back to the last good cache. */
+export async function readAgentModelCatalog(token, options = {}) {
+    const baseUrl = options.baseUrl ?? DEFAULT_VAULT_API_URL;
+    const cacheFile = options.cacheFile ?? agentModelCatalogCacheFile(baseUrl);
+    const now = options.now ?? Date.now;
+    const signal = AbortSignal.timeout(options.timeoutMs ?? MODEL_CATALOG_REQUEST_TIMEOUT_MS);
+    const cached = readCache(cacheFile);
+    const headers = cached
+        ? { "If-None-Match": cached.etag }
+        : {};
+    let response;
+    try {
+        response = options.request
+            ? await options.request(headers, signal)
+            : await vaultApiFetch({ token, baseUrl, path: "/v1/agents/models", headers, signal });
+    }
+    catch {
+        return cached ? fromCache(cached) : { ok: false, reason: "unavailable" };
+    }
+    if (response.status === 304) {
+        if (!cached)
+            return { ok: false, reason: "unavailable" };
+        const refreshed = {
+            ...cached,
+            etag: response.headers.get("etag") ?? cached.etag,
+            fetchedAt: now(),
+        };
+        if (isStrongEtag(refreshed.etag))
+            writeCache(cacheFile, refreshed);
+        return fromCache(refreshed, "network");
+    }
+    if (response.status === 404 || response.status === 429 || response.status >= 500) {
+        return cached ? fromCache(cached) : { ok: false, reason: "unavailable" };
+    }
+    if (!response.ok) {
+        return { ok: false, reason: "request_failed", status: response.status };
+    }
+    try {
+        const catalog = parseAgentModelCatalog(await response.json());
+        const etag = response.headers.get("etag");
+        if (!catalog || !etag || !isStrongEtag(etag)) {
+            return cached ? fromCache(cached) : { ok: false, reason: "unavailable" };
+        }
+        const entry = {
+            version: 1,
+            catalog,
+            etag,
+            fetchedAt: now(),
+        };
+        writeCache(cacheFile, entry);
+        return { ok: true, ...entry, source: "network" };
+    }
+    catch {
+        return cached ? fromCache(cached) : { ok: false, reason: "unavailable" };
+    }
+}
+/** Check an explicit model against the selected provider or inferred agents-v2 brain. */
+export function validateAgentModelSelection(catalog, modelId, chosenProvider) {
+    const provider = isCatalogProvider(chosenProvider) ? chosenProvider : undefined;
+    const inferred = providerFromModelId(modelId);
+    const providers = provider
+        ? [provider]
+        : inferred
+            ? [inferred]
+            : [...AGENT_MODEL_PROVIDERS];
+    const rows = providers.flatMap((name) => catalog.providers[name].models.map((model) => ({ provider: name, model })));
+    const exact = rows.find(({ model }) => model.id.toLowerCase() === modelId.toLowerCase());
+    if (exact?.model.selectable)
+        return { ok: true };
+    const suggestions = closestSelectableModels(modelId, rows.filter(({ model }) => model.selectable).map(({ model }) => model.id));
+    return {
+        ok: false,
+        reason: exact ? "not_selectable" : "unknown",
+        ...(providers.length === 1 ? { provider: providers[0] } : {}),
+        suggestions,
+    };
+}
+export function modelSelectionErrorMessage(modelId, result) {
+    const scope = result.provider ? `the ${result.provider} catalog` : "the model catalog";
+    const problem = result.reason === "not_selectable" ? "not selectable in" : "not listed in";
+    const suggestion = result.suggestions.length
+        ? ` Close matches: ${result.suggestions.join(", ")}.`
+        : "";
+    const command = result.provider
+        ? ` Run \`hq agents models --provider ${result.provider}\` to see available models.`
+        : " Run `hq agents models` to see available models.";
+    return `Model '${modelId}' is ${problem} ${scope}.${suggestion}${command}`;
+}
+function providerFromModelId(modelId) {
+    const normalized = modelId.toLowerCase();
+    if (normalized.startsWith("gpt-"))
+        return "codex";
+    if (normalized.startsWith("grok-"))
+        return "grok";
+    if (normalized.startsWith("claude-"))
+        return "claude";
+    return undefined;
+}
+function closestSelectableModels(modelId, candidates) {
+    const needle = modelId.toLowerCase();
+    return candidates
+        .map((id) => ({
+        id,
+        distance: editDistance(needle, id.toLowerCase()),
+        prefix: commonPrefixLength(needle, id.toLowerCase()),
+    }))
+        .filter(({ distance, id }) => distance <= Math.max(2, Math.floor(needle.length / 4)) ||
+        id.toLowerCase().startsWith(needle))
+        .sort((a, b) => a.distance - b.distance || b.prefix - a.prefix || a.id.localeCompare(b.id))
+        .slice(0, 3)
+        .map(({ id }) => id);
+}
+function editDistance(left, right) {
+    let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= left.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= right.length; j += 1) {
+            current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + (left[i - 1] === right[j - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    return previous[right.length];
+}
+function commonPrefixLength(left, right) {
+    let index = 0;
+    while (index < left.length && index < right.length && left[index] === right[index])
+        index += 1;
+    return index;
+}
+function readCache(file) {
+    let serialized;
+    try {
+        serialized = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return null;
+        console.warn("Unable to read the model catalog cache; continuing without cached data.");
+        return null;
+    }
+    let value;
+    try {
+        value = JSON.parse(serialized);
+    }
+    catch {
+        console.warn("Ignoring an invalid model catalog cache file.");
+        return null;
+    }
+    if (!isRecord(value) || value.version !== 1 || !isStrongEtag(value.etag)) {
+        console.warn("Ignoring an invalid model catalog cache file.");
+        return null;
+    }
+    if (typeof value.fetchedAt !== "number" || !Number.isFinite(value.fetchedAt)) {
+        console.warn("Ignoring an invalid model catalog cache file.");
+        return null;
+    }
+    const catalog = parseAgentModelCatalog(value.catalog);
+    if (!catalog) {
+        console.warn("Ignoring an invalid model catalog cache file.");
+        return null;
+    }
+    return { version: 1, catalog, etag: value.etag, fetchedAt: value.fetchedAt };
+}
+function writeCache(file, cache) {
+    const temporary = `${file}.${process.pid}.${cache.fetchedAt}.tmp`;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(temporary, JSON.stringify(cache), { encoding: "utf8", mode: 0o600 });
+        fs.renameSync(temporary, file);
+    }
+    catch {
+        console.warn("Unable to save the model catalog cache; offline use may be unavailable.");
+        try {
+            fs.rmSync(temporary, { force: true });
+        }
+        catch (error) {
+            if (!isMissingFile(error)) {
+                console.warn("Unable to remove a temporary model catalog cache file.");
+            }
+        }
+    }
+}
+function fromCache(cache, source = "cache") {
+    return {
+        ok: true,
+        catalog: cache.catalog,
+        etag: cache.etag,
+        fetchedAt: cache.fetchedAt,
+        source,
+    };
+}
+function isStrongEtag(value) {
+    return typeof value === "string" &&
+        value.length >= 2 &&
+        value.startsWith('"') &&
+        value.endsWith('"') &&
+        !/[\r\n]/.test(value);
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isCatalogProvider(value) {
+    return value !== undefined && AGENT_MODEL_PROVIDERS.includes(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=model-catalog.js.map

package/dist/lib/core-utils/qmd-reindex-after-sync.d.ts

@@ -1,6 +1,8 @@
 import { type EmbedLockDependencies } from "../search-index/embed-lock.js";
 import { type LoadGateDependencies } from "../search-index/load-gate.js";
 import { type UtilityIo } from "./common.js";
+export declare const QMD_REINDEX_STARTUP_WARNING_FLAG = "qmd.reindex-startup-warning";
+export declare const QMD_REINDEX_STARTUP_WARNING_FLAG_FALLBACK = false;
 export type QmdReindexOptions = UtilityIo & {
     cwd?: string;
     /** Test seams; default to the real search-index implementations. */
@@ -17,6 +19,8 @@ export type QmdReindexOptions = UtilityIo & {
     embedLockDependencies?: EmbedLockDependencies;
     /** Test seams for the host load gate consulted while the embed lock is held. */
     loadGateDependencies?: LoadGateDependencies;
+    /** Test seam for the hq-flags-gated warning on qmd native startup failures. */
+    startupFailureWarningsEnabled?: () => boolean;
 };
 export declare function qmdReindexAfterSync(args?: string[], options?: QmdReindexOptions): number;
 //# sourceMappingURL=qmd-reindex-after-sync.d.ts.map

package/dist/lib/core-utils/qmd-reindex-after-sync.js

@@ -15,7 +15,14 @@ import { reconcileCollections, resolveQmdBin, resolveQmdHome, runQmd } from "../
 import { applyIndexSizeLimit } from "../search-index/max-doc-bytes.js";
 import { defaultEmbedLockDependencies, runWithEmbedLock, } from "../search-index/embed-lock.js";
 import { LoadGateConfigurationError, checkEmbedLoad, defaultLoadGateDependencies, recordSuccessfulEmbed, } from "../search-index/load-gate.js";
+import { resolveProcessFlagGate } from "../flag-registry.js";
+import { isQmdNativeBindingError, QMD_NATIVE_BINDING_REMEDY, } from "../../utils/qmd-native-binding-error.js";
 import { ioFor, line } from "./common.js";
+export const QMD_REINDEX_STARTUP_WARNING_FLAG = "qmd.reindex-startup-warning";
+export const QMD_REINDEX_STARTUP_WARNING_FLAG_FALLBACK = false;
+function qmdStartupFailureWarningsEnabled() {
+    return resolveProcessFlagGate(QMD_REINDEX_STARTUP_WARNING_FLAG, { fallback: QMD_REINDEX_STARTUP_WARNING_FLAG_FALLBACK }, () => QMD_REINDEX_STARTUP_WARNING_FLAG_FALLBACK);
+}
 export function qmdReindexAfterSync(args = [], options = {}) {
     let hqRoot = "";
     let embed = false;
@@ -42,6 +49,15 @@ export function qmdReindexAfterSync(args = [], options = {}) {
     const run = options.run ?? ((argv, opts) => runQmd(argv, opts));
     const sizeLimit = options.sizeLimit ?? ((root) => applyIndexSizeLimit(root));
     const { stderr } = ioFor(options);
+    let startupFailureWarningShown = false;
+    const warnOnNativeStartupFailure = (error) => {
+        if (startupFailureWarningShown ||
+            !isQmdNativeBindingError(error) ||
+            !(options.startupFailureWarningsEnabled ?? qmdStartupFailureWarningsEnabled)())
+            return;
+        startupFailureWarningShown = true;
+        line(stderr, `hq: search index was not updated after sync; ${QMD_NATIVE_BINDING_REMEDY}`);
+    };
     // Every qmd interaction is best-effort: the shell suffixed each with `|| true`.
     try {
         reconcile(hqRoot, { bin });
@@ -62,7 +78,8 @@ export function qmdReindexAfterSync(args = [], options = {}) {
     try {
         run(["update"], { bin, cwd: hqRoot });
     }
-    catch {
+    catch (error) {
+        warnOnNativeStartupFailure(error);
         /* never fail a sync on index freshness */
     }
     if (embed) {
@@ -91,6 +108,7 @@ export function qmdReindexAfterSync(args = [], options = {}) {
         catch (error) {
             if (error instanceof LoadGateConfigurationError)
                 line(stderr, `hq: ${error.message}`);
+            warnOnNativeStartupFailure(error);
             /* embeddings are deferred-cost and optional */
         }
     }

package/dist/lib/report-publish.d.ts

@@ -106,6 +106,7 @@ export declare function ownerFailureNotice(input: {
     body: string;
 } | null;
 export interface ReportAdoptDependencies {
+    preflightJobCreation(): Promise<void>;
     createJob(input: {
         prompt: string;
         schedule: {
@@ -124,8 +125,8 @@ export interface ReportAdoptDependencies {
     patch(report: ChannelReport, patch: ReportPatch): Promise<ChannelReport>;
 }
 export declare class ReportPublishError extends Error {
-    readonly code: "already-running" | "source-invalid" | "deploy-failed" | "job-failed" | "revision-conflict";
-    constructor(message: string, code?: "already-running" | "source-invalid" | "deploy-failed" | "job-failed" | "revision-conflict");
+    readonly code: "already-running" | "source-invalid" | "deploy-failed" | "job-failed" | "job-execution-disabled" | "revision-conflict";
+    constructor(message: string, code?: "already-running" | "source-invalid" | "deploy-failed" | "job-failed" | "job-execution-disabled" | "revision-conflict");
 }
 /** A deliberately boring, token-safe failure reason stored on the report. */
 export declare function plainFailureReason(error: unknown): string;

package/dist/lib/report-publish.js

@@ -41,7 +41,7 @@ export class ReportPublishError extends Error {
 /** A deliberately boring, token-safe failure reason stored on the report. */
 export function plainFailureReason(error) {
     if (error instanceof ReportPublishError) {
-        if (error.code === "source-invalid" || error.code === "job-failed" || error.code === "revision-conflict")
+        if (error.code === "source-invalid" || error.code === "job-failed" || error.code === "job-execution-disabled" || error.code === "revision-conflict")
             return error.message.slice(0, 240);
         if (error.code === "already-running")
             return "already running";
@@ -231,9 +231,11 @@ export async function adoptReport(report, deps) {
         throw new ReportPublishError("Report schedule is missing.", "source-invalid");
     }
     try {
+        const cron = reportJobCron(schedule);
+        if (cron)
+            await deps.preflightJobCreation();
         if (report.jobId)
             await deps.cancelJob(report.jobId);
-        const cron = reportJobCron(schedule);
         if (!cron) {
             return deps.patch(report, { jobId: null, jobState: "adopted", jobStateReason: null });
         }

package/package.json

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