@indigoai-us/hq-cli 5.97.3-rc.0 → 5.97.3

package/CHANGELOG.md

@@ -2,7 +2,9 @@
 
 ## [Unreleased]
 
-## [5.97.3-rc.0] — 2026-08-10
+## [5.97.3] — 2026-08-10
+
+## [5.97.3-rc.1] — 2026-08-10
 
 ## [5.97.2]
 

package/dist/commands/agents.d.ts

@@ -27,6 +27,44 @@ import { type BillingErrorPayload } from "../utils/billing-gate.js";
 export declare const VALID_EFFORTS: Set<string>;
 /** Service-tier (speed) values hq-pro accepts on `runtime-config`. */
 export declare const VALID_TIERS: Set<string>;
+/** Agent runtimes hq-pro accepts on `POST /v1/agents` (`AgentProvider`). */
+export declare const VALID_PROVIDERS: Set<string>;
+/** Auth modes hq-pro accepts on `POST /v1/agents` (`CodexAuthMode`). */
+export declare const VALID_AUTH_MODES: Set<string>;
+/**
+ * Resolve a closed-set option value, or exit(1) with a message naming the
+ * offending input and the legal set.
+ *
+ * WHY THIS EXISTS. `--effort` and `--tier` were already validated this way, but
+ * `--provider` and `--auth-mode` were resolved with a ternary that FELL BACK to
+ * the default on anything unrecognised:
+ *
+ *     opts.provider === "grok" ? "grok" : opts.provider ? "codex" : undefined
+ *     opts.authMode === "apiKey" ? "apiKey" : "subscription"
+ *
+ * So `--provider claude` (before claude was supported) silently provisioned a
+ * CODEX box, and `--auth-mode typo` silently provisioned in SUBSCRIPTION mode.
+ * Both paths are behind a `--yes` charge gate, so the operator paid $100/month
+ * for a runtime they did not ask for, with nothing in the output to say a
+ * substitution had happened. A wrong flag must fail loudly, never resolve to a
+ * plausible default.
+ *
+ * `undefined` in ⇒ `undefined` out: an OMITTED option is not an invalid one, and
+ * keeps the server-side default authoritative.
+ *
+ * Matching is trim + lowercase to be forgiving of shell padding and casing,
+ * EXCEPT that the returned value is the canonical member of the set — so the
+ * wire value is always exactly what hq-pro's validators expect. Note `apiKey`
+ * is camelCase on the wire, so the comparison set is keyed on the lowercased
+ * form and mapped back (see {@link canonicalizeOptionValue}).
+ */
+export declare function parseEnumOption(raw: string | undefined, allowed: Set<string>, flagName: string): string | undefined;
+/**
+ * Case-insensitively map `raw` onto its canonical member of `allowed`, or
+ * `undefined` when it is not a member. Split out from {@link parseEnumOption}
+ * so the mapping is unit-testable without a process exit.
+ */
+export declare function canonicalizeOptionValue(raw: string, allowed: Set<string>): string | undefined;
 /**
  * A non-2xx from the `/v1/agents` control plane. Carries the HTTP status and
  * the registry error `code` (when present) so callers can branch — notably a
@@ -89,7 +127,7 @@ export interface ProvisionAgentInput {
     name: string;
     slug: string;
     codexAuthMode: "subscription" | "apiKey";
-    provider?: "codex" | "grok";
+    provider?: "codex" | "grok" | "claude";
     codexApiKey?: string;
     idempotencyKey: string;
     title?: string;

package/dist/commands/agents.js

@@ -37,6 +37,61 @@ export const VALID_EFFORTS = new Set([
 ]);
 /** Service-tier (speed) values hq-pro accepts on `runtime-config`. */
 export const VALID_TIERS = new Set(["default", "priority"]);
+/** Agent runtimes hq-pro accepts on `POST /v1/agents` (`AgentProvider`). */
+export const VALID_PROVIDERS = new Set(["codex", "grok", "claude"]);
+/** Auth modes hq-pro accepts on `POST /v1/agents` (`CodexAuthMode`). */
+export const VALID_AUTH_MODES = new Set(["subscription", "apiKey"]);
+/**
+ * Resolve a closed-set option value, or exit(1) with a message naming the
+ * offending input and the legal set.
+ *
+ * WHY THIS EXISTS. `--effort` and `--tier` were already validated this way, but
+ * `--provider` and `--auth-mode` were resolved with a ternary that FELL BACK to
+ * the default on anything unrecognised:
+ *
+ *     opts.provider === "grok" ? "grok" : opts.provider ? "codex" : undefined
+ *     opts.authMode === "apiKey" ? "apiKey" : "subscription"
+ *
+ * So `--provider claude` (before claude was supported) silently provisioned a
+ * CODEX box, and `--auth-mode typo` silently provisioned in SUBSCRIPTION mode.
+ * Both paths are behind a `--yes` charge gate, so the operator paid $100/month
+ * for a runtime they did not ask for, with nothing in the output to say a
+ * substitution had happened. A wrong flag must fail loudly, never resolve to a
+ * plausible default.
+ *
+ * `undefined` in ⇒ `undefined` out: an OMITTED option is not an invalid one, and
+ * keeps the server-side default authoritative.
+ *
+ * Matching is trim + lowercase to be forgiving of shell padding and casing,
+ * EXCEPT that the returned value is the canonical member of the set — so the
+ * wire value is always exactly what hq-pro's validators expect. Note `apiKey`
+ * is camelCase on the wire, so the comparison set is keyed on the lowercased
+ * form and mapped back (see {@link canonicalizeOptionValue}).
+ */
+export function parseEnumOption(raw, allowed, flagName) {
+    if (raw === undefined)
+        return undefined;
+    const canonical = canonicalizeOptionValue(raw, allowed);
+    if (canonical === undefined) {
+        const legal = [...allowed].join(", ");
+        console.error(chalk.red(`Invalid ${flagName} '${raw}': must be one of ${legal}`));
+        process.exit(1);
+    }
+    return canonical;
+}
+/**
+ * Case-insensitively map `raw` onto its canonical member of `allowed`, or
+ * `undefined` when it is not a member. Split out from {@link parseEnumOption}
+ * so the mapping is unit-testable without a process exit.
+ */
+export function canonicalizeOptionValue(raw, allowed) {
+    const needle = raw.trim().toLowerCase();
+    for (const candidate of allowed) {
+        if (candidate.toLowerCase() === needle)
+            return candidate;
+    }
+    return undefined;
+}
 /**
  * A non-2xx from the `/v1/agents` control plane. Carries the HTTP status and
  * the registry error `code` (when present) so callers can branch — notably a
@@ -335,16 +390,28 @@ export function registerAgentsCommand(program) {
         .description("Provision a new cloud agent ($100/month — requires --yes)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--slug <slug>", "Agent slug (defaults to a slug of <name>)")
-        .option("--provider <provider>", "Runtime: codex | grok (default codex)")
-        .option("--auth-mode <mode>", "Codex auth: subscription | apiKey (default subscription)", "subscription")
+        .option("--provider <provider>", "Runtime: codex | grok | claude (default codex). claude is subscription-only")
+        .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("--title <title>", "Org-chart job title")
         .option("--description <text>", "Short description / bio")
         .option("--yes", "Confirm the $100/month charge (required to provision)")
         .action(async function (name, opts) {
         try {
-            const authMode = opts.authMode === "apiKey" ? "apiKey" : "subscription";
-            const provider = opts.provider === "grok" ? "grok" : opts.provider ? "codex" : undefined;
+            // 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.
+            const authMode = parseEnumOption(opts.authMode, VALID_AUTH_MODES, "--auth-mode") ?? "subscription";
+            const provider = parseEnumOption(opts.provider, VALID_PROVIDERS, "--provider");
+            // claude is subscription-only on hq-pro (rejectIncompatibleProviderAuthMode
+            // returns AGENT_PROVIDER_INCOMPATIBLE_WITH_AUTH_MODE). Catch it here so the
+            // operator gets a direct message instead of a 400 from the control plane
+            // AFTER clearing the charge gate. The server stays authoritative; this is
+            // only a friendlier, earlier copy of the same rule.
+            if (provider === "claude" && authMode === "apiKey") {
+                console.error(chalk.red("The claude provider is subscription-only — drop --auth-mode apiKey."));
+                process.exit(1);
+            }
             // Resolve the API key from the environment (never from a flag value) when
             // apiKey mode is requested — validated BEFORE the paid gate so we don't
             // charge and then fail.

package/dist/lib/search-index/background.d.ts

@@ -1,3 +1,4 @@
+import { type StdioOptions } from 'node:child_process';
 import { type QmdProcessResult, type RunQmdOptions } from './index.js';
 export type BackgroundResult = {
     state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed' | 'terminated';
@@ -17,6 +18,7 @@ export type BackgroundDependencies = {
     runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
     spawnWorker: (options: {
         logPath: string;
+        fallbackLogPath?: string;
     }) => number;
     /** Test seam for simulating a competing owner replacing the atomic record. */
     afterOwnerPublish?: (ownerFile: string) => void;
@@ -28,6 +30,60 @@ export type BackgroundStatus = {
     lock: 'held' | 'stale' | 'free';
     completedAt?: number;
 };
+/**
+ * Injectable seams for the launcher's worker-log open and detached spawn. Split
+ * out purely as a test seam so a synthetic open failure can be forced without
+ * touching real files or the invoking uid.
+ */
+export type SpawnWorkerIo = {
+    mkdirSync: (directory: string) => void;
+    openSync: (file: string) => number;
+    closeSync: (fd: number) => void;
+    spawn: (command: string, args: string[], options: {
+        detached: boolean;
+        stdio: StdioOptions;
+    }) => {
+        pid?: number;
+        unref: () => void;
+    };
+    /** Report a degraded open without swallowing it (stderr notice + breadcrumb). */
+    report: (info: WorkerLogDegradation) => void;
+};
+export type WorkerLogDegradation = {
+    requested: string;
+    used: string | null;
+    usedFallback: boolean;
+    code?: string;
+    syscall?: string;
+};
+type WorkerLogOpen = {
+    fd: number | null;
+    logPath: string | null;
+    usedFallback: boolean;
+    error?: {
+        code?: string;
+        syscall?: string;
+    };
+};
+/**
+ * Open the detached worker's log, degrading instead of crashing. Try the
+ * requested path; on ANY open failure retry once against a per-user fallback
+ * under the caller's own $HOME; if that also fails, return a no-log result so
+ * the launcher still spawns the worker.
+ *
+ * This is the fix for Sentry indigo-d0/hq-cli 7663380187: HQ's /handoff always
+ * points --log at the fixed, shared, world-writable /tmp/qmd-handoff.log, and an
+ * unguarded fs.openSync(logPath, 'a') here threw EACCES whenever that file
+ * already existed owned by another uid, so the reindex worker never spawned and
+ * the raw errno reached Sentry. A diagnostic side-channel must not take down the
+ * feature it exists to observe — every other worker-log writer in this module
+ * (appendWorkerLog, capWorkerLog) already swallows I/O failures the same way.
+ */
+export declare function openWorkerLog(logPath: string, fallbackLogPath: string | undefined, io: Pick<SpawnWorkerIo, 'mkdirSync' | 'openSync'>): WorkerLogOpen;
+export declare function defaultSpawnWorker({ logPath, fallbackLogPath }: {
+    logPath: string;
+    fallbackLogPath?: string;
+}, io?: SpawnWorkerIo): number;
 /** Defaults used by the CLI; tests supply every nondeterministic dependency. */
 export declare function defaultBackgroundDependencies(hqRoot: string): BackgroundDependencies;
 /** Match the shell forwarder's hosted-agent markers before looking up qmd. */
@@ -39,4 +95,5 @@ export declare function runBackgroundLauncher(dependencies: BackgroundDependenci
 export declare function runBackgroundWorker(dependencies: BackgroundDependencies): Promise<BackgroundResult>;
 /** Report the background lock and latest successful completion for `hq index status`. */
 export declare function backgroundStatus(dependencies: BackgroundDependencies): BackgroundStatus;
+export {};
 //# sourceMappingURL=background.d.ts.map

package/dist/lib/search-index/background.js

@@ -1,20 +1,99 @@
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { Sentry } from '../../sentry.js';
 import { reconcileCollections as defaultReconcileCollections, resolveQmdBin as defaultResolveQmdBin, runQmd as defaultRunQmd, } from './index.js';
 const LOCK_NAME = 'qmd-reindex-bg.lock';
 const COMPLETE_NAME = 'qmd-reindex-bg.completed';
-function defaultSpawnWorker({ logPath }) {
-    fs.mkdirSync(path.dirname(logPath), { recursive: true });
-    const log = fs.openSync(logPath, 'a');
+function errnoInfo(error) {
+    const e = error;
+    return { code: e?.code, syscall: e?.syscall };
+}
+/**
+ * Open the detached worker's log, degrading instead of crashing. Try the
+ * requested path; on ANY open failure retry once against a per-user fallback
+ * under the caller's own $HOME; if that also fails, return a no-log result so
+ * the launcher still spawns the worker.
+ *
+ * This is the fix for Sentry indigo-d0/hq-cli 7663380187: HQ's /handoff always
+ * points --log at the fixed, shared, world-writable /tmp/qmd-handoff.log, and an
+ * unguarded fs.openSync(logPath, 'a') here threw EACCES whenever that file
+ * already existed owned by another uid, so the reindex worker never spawned and
+ * the raw errno reached Sentry. A diagnostic side-channel must not take down the
+ * feature it exists to observe — every other worker-log writer in this module
+ * (appendWorkerLog, capWorkerLog) already swallows I/O failures the same way.
+ */
+export function openWorkerLog(logPath, fallbackLogPath, io) {
+    try {
+        io.mkdirSync(path.dirname(logPath));
+        return { fd: io.openSync(logPath), logPath, usedFallback: false };
+    }
+    catch (primaryError) {
+        const error = errnoInfo(primaryError);
+        if (fallbackLogPath && fallbackLogPath !== logPath) {
+            try {
+                io.mkdirSync(path.dirname(fallbackLogPath));
+                return { fd: io.openSync(fallbackLogPath), logPath: fallbackLogPath, usedFallback: true, error };
+            }
+            catch { /* fall through to the no-log result below */ }
+        }
+        return { fd: null, logPath: null, usedFallback: false, error };
+    }
+}
+/**
+ * Surface a degraded worker-log open without swallowing it: one best-effort
+ * stderr line naming the rejected path and where output went, plus a Sentry
+ * breadcrumb carrying only the errno — never the fallback path, which lives
+ * under $HOME. The condition is now handled and degraded, so it is deliberately
+ * NOT captured as an exception; the breadcrumb just gives the next genuine
+ * failure at this site the errno evidence this event lacked.
+ */
+function reportWorkerLogDegradation(info) {
+    const reason = info.code ? ` (${info.code}${info.syscall ? ` on ${info.syscall}` : ''})` : '';
+    const destination = info.used ? `writing worker output to ${info.used} instead` : 'disabling worker output';
+    try {
+        process.stderr.write(`hq: cannot open background reindex log ${info.requested}${reason}; ${destination}.\n`);
+    }
+    catch { /* the notice itself is best-effort and must never crash the launcher */ }
+    try {
+        Sentry.addBreadcrumb({
+            category: 'qmd.background',
+            level: 'warning',
+            message: 'worker log open degraded',
+            data: { code: info.code, syscall: info.syscall, usedFallback: info.usedFallback },
+        });
+    }
+    catch { /* breadcrumb is best-effort; no Sentry client is active in tests */ }
+}
+const defaultSpawnWorkerIo = {
+    mkdirSync: (directory) => { fs.mkdirSync(directory, { recursive: true }); },
+    openSync: (file) => fs.openSync(file, 'a'),
+    closeSync: (fd) => { fs.closeSync(fd); },
+    spawn: (command, args, options) => spawn(command, args, options),
+    report: reportWorkerLogDegradation,
+};
+export function defaultSpawnWorker({ logPath, fallbackLogPath }, io = defaultSpawnWorkerIo) {
+    const opened = openWorkerLog(logPath, fallbackLogPath, io);
+    if (opened.error) {
+        io.report({ requested: logPath, used: opened.logPath, usedFallback: opened.usedFallback, ...opened.error });
+    }
     const entry = process.argv[1];
     if (!entry)
         throw new Error('Cannot determine hq CLI entrypoint for background worker');
-    const child = spawn(process.execPath, [entry, 'index', 'background', '--worker', '--log', logPath], {
+    // Hand the child the log path we actually opened so its own appendWorkerLog /
+    // capWorkerLog write to the same file. When nothing could be opened, omit
+    // --log entirely so the child resolves its own default rather than re-failing
+    // on the path we already rejected — the reindex itself must still run.
+    const logArgs = opened.logPath ? ['--log', opened.logPath] : [];
+    const stdio = opened.fd === null
+        ? ['ignore', 'ignore', 'ignore']
+        : ['ignore', opened.fd, opened.fd];
+    const child = io.spawn(process.execPath, [entry, 'index', 'background', '--worker', ...logArgs], {
         detached: true,
-        stdio: ['ignore', log, log],
+        stdio,
     });
-    fs.closeSync(log);
+    if (opened.fd !== null)
+        io.closeSync(opened.fd);
     child.unref();
     if (!child.pid)
         throw new Error('Unable to start qmd background worker');
@@ -358,7 +437,15 @@ export function runBackgroundLauncher(dependencies) {
     catch {
         return { state: 'skipped' };
     }
-    return { state: 'launched', pid: dependencies.spawnWorker({ logPath: workerLogPath(dependencies.env) }) };
+    // Fall back to a per-user log under the caller's own $HOME when the requested
+    // (often the shared, world-writable /tmp) log cannot be opened — see
+    // openWorkerLog. `home` is validated non-empty above, so the fallback is
+    // always inside a directory this user owns.
+    const fallbackLogPath = path.join(home, '.hq', 'logs', 'qmd-handoff.log');
+    return {
+        state: 'launched',
+        pid: dependencies.spawnWorker({ logPath: workerLogPath(dependencies.env), fallbackLogPath }),
+    };
 }
 /** Run the single-flight cleanup → update → embed pipeline in a worker only. */
 export async function runBackgroundWorker(dependencies) {

package/package.json

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