@indigoai-us/hq-cli 5.97.3-rc.1 → 5.98.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.98.0] — 2026-08-10
+
+## [5.97.3] — 2026-08-10
+
 ## [5.97.3-rc.1] — 2026-08-10
 
 ## [5.97.2]

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

@@ -7,12 +7,24 @@
  * I/O itself.
  */
 import { Command } from "commander";
+type Backend = "claude" | "codex" | "grok" | "none";
+type SpawnableBackend = Exclude<Backend, "none">;
 /**
  * Kept in TypeScript rather than in a bundled asset: it is an instruction to
  * a locally-installed agent, not a scaffold script that should be packaged.
  */
 export declare const SIBLING_PROMPT_TEMPLATE = "You are the HQ checkpoint sibling \u2014 a background maintenance agent for this\nHQ install. Your parent session's state is in <payloadPath>. Work\nquietly and do not ask questions; if something is ambiguous, record it in the\nreport instead of guessing.\n\n1. Read the payload. If it lists a transcript path that exists, read its tail (~400 lines)\n   both for session context and to extract additional reusable learnings/insights\n   the parent did not pass explicitly. Never quote secrets\n   or tokens from the transcript. If .claude/skills/checkpoint/SKILL.md exists\n   under this HQ root, read it and follow it wherever it goes beyond these instructions;\n   the write bounds below always win over the skill text.\n2. Upgrade the thread file named in the payload IN PLACE: verify/repair its\n   JSON; fill git.remote_url, git.initial_commit, git.commits_made, and\n   git.knowledge_repos by scanning core/knowledge/public/*,\n   core/knowledge/private/*, personal/knowledge/*, and companies/*/knowledge\n   for symlinks or directories containing .git, recording dirty repositories\n   as {\"<name>\": {\"commit\": \"<short>\", \"dirty\": true}}. Fill worker,\n   next_steps, and insights; set type to \"checkpoint\"; then rename the file to\n   drop -auto- from its filename. Use the renamed path in every reference you\n   write afterwards.\n3. For every explicit or transcript-derived learning that is a reusable rule,\n   FIRST search the existing policies for one the learning refines, contradicts\n   or duplicates. Then take exactly one of these actions and name it in the\n   report \u2014 the policy set is curated, not append-only:\n   - AMEND an existing policy in place when the learning sharpens it, narrows\n     its scope, or adds a case, and the rule as written is still correct.\n   - SUPERSEDE it when the learning contradicts it: rewrite the rule to what is\n     now true and record inside the file what changed and why.\n   - MERGE near-duplicates into the single best-named file, then delete the\n     files you merged away.\n   - CREATE a new policy only when no existing policy covers the rule.\n   Follow core/knowledge/public/hq-core/policies-spec.md. Write under\n   personal/policies/ or, only when the payload names a company and the rule is\n   company-specific, companies/<company>/policies/.\n   DELETION BOUNDS: delete a policy only as the MERGE or SUPERSEDE step above,\n   only inside those two directories, and never one whose body marks it HARD \u2014\n   if a hard policy now looks wrong, leave it untouched and flag it in the\n   report for a human to decide. Never delete a file you have not read.\n   Apply the same curation to durable facts (not rules) under\n   personal/knowledge/ or companies/<company>/knowledge/: correct a stale fact\n   in place rather than appending a second, contradictory copy of it.\n   Store up to two explicit or transcript-derived insights per\n   core/knowledge/public/hq-core/insights-spec.md when present, otherwise\n   workspace/insights/.\n4. Close an active session journal fail-soft with\n   bash .claude/skills/_shared/journal.sh close \"<project_dir>\" \"<one-line synthesis>\".\n   Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with\n   id, created_at, summary, files, and next_steps for backward compatibility.\n5. Update workspace/threads/recent.md and regenerate\n   workspace/threads/INDEX.md. For each company whose knowledge path appears\n   in files_touched, regenerate companies/<company>/knowledge/INDEX.md under\n   core/knowledge/public/hq-core/index-md-spec.md. Mechanical index generation\n   is allowed for those companies, but knowledge/policy content writes remain\n   restricted to the payload's named company.\n6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;\n   skip silently on any failure. Hook or automation improvements go ONLY under\n   personal/hooks/ as proposals.\n7. WRITE BOUNDS: you may write only under personal/, workspace/, and companies/<company>/ as constrained above. You must NEVER write into .claude/, core/, .agents/, .codex/, repos/, or anywhere outside the HQ root.\n8. Write <runDir>/report.md \u2014 full prose: what you read, what you changed\n   (paths), and what you skipped and why. List every policy or knowledge file\n   you amended, superseded, merged or deleted with the reason, so a human can\n   audit and reverse it; a deletion you do not name in the report is a defect.\n   Then drain the queue: while\n   workspace/checkpoints/sibling/pending.jsonl exists and is non-empty, claim\n   it atomically by renaming it aside \u2014\n   mv workspace/checkpoints/sibling/pending.jsonl <runDir>/pending-claimed-N.jsonl\n   (N counting up from 2) \u2014 and process the claimed payloads with this same\n   flow. Repeat until a claim finds nothing left, then update the report.\n   NEVER read the queue and truncate it in place: a payload appended between\n   your read and the truncate is lost, and its checkpoint is never enriched.\n";
 export declare function renderSiblingPrompt(runDir: string, payloadPath: string): string;
+/**
+ * Preference order for `--backend auto`: the caller's own backend first, so a
+ * claude session keeps using claude and a codex session keeps using codex
+ * (same-engine continuity), then the fallback priority claude -> codex -> grok
+ * for whatever the caller is not. Deterministic and env-only, so it is unit
+ * tested directly.
+ */
+export declare function autoBackendPreference(): SpawnableBackend[];
+export declare function siblingArgs(backend: SpawnableBackend, prompt: string): string[];
 /** Attach the native checkpoint command to the hidden `hq core` group. */
 export declare function registerCoreCheckpointCommand(core: Command): void;
+export {};
 //# sourceMappingURL=core-checkpoint.d.ts.map

package/dist/commands/core-checkpoint.js

@@ -26,8 +26,12 @@ const GROK_SIBLING_EFFORT = "high";
  * plan and exits, having done nothing. The maintenance flow needs many turns.
  */
 const GROK_SIBLING_MAX_TURNS = "100";
-/** Preference order for `--backend auto`, first healthy candidate wins. */
-const AUTO_BACKEND_ORDER = ["codex", "grok", "claude"];
+/**
+ * Fallback priority for `--backend auto` once the caller's own backend is
+ * unavailable, unresponsive, out of credits (surfaces as a crashed run), or
+ * simply unknown. First healthy candidate wins.
+ */
+const FALLBACK_BACKEND_ORDER = ["claude", "codex", "grok"];
 /** A backend that cannot answer `--version` this fast is treated as broken. */
 const BACKEND_PROBE_TIMEOUT_MS = 10_000;
 /** A sibling still holding the lock after this long is treated as abandoned. */
@@ -492,6 +496,32 @@ function crashedBackends(siblingRoot) {
     }
     return crashed;
 }
+/**
+ * The backend of the agent that invoked this checkpoint, when known.
+ *
+ * Reuses the same runtime signal the Stop gate reads (`HQ_CHECKPOINT_RUNTIME`,
+ * set to `codex` by the codex hook adapter and defaulted to `claude` by the
+ * claude Stop hook). Grok runs no HQ hooks, so it never auto-invokes a
+ * checkpoint and has no reliable caller signal — an `other`/unknown runtime
+ * returns null and falls through to the fallback order.
+ */
+function callerBackend() {
+    const runtime = checkpointGateRuntime();
+    return runtime === "claude" || runtime === "codex" ? runtime : null;
+}
+/**
+ * Preference order for `--backend auto`: the caller's own backend first, so a
+ * claude session keeps using claude and a codex session keeps using codex
+ * (same-engine continuity), then the fallback priority claude -> codex -> grok
+ * for whatever the caller is not. Deterministic and env-only, so it is unit
+ * tested directly.
+ */
+export function autoBackendPreference() {
+    const caller = callerBackend();
+    if (!caller)
+        return [...FALLBACK_BACKEND_ORDER];
+    return [caller, ...FALLBACK_BACKEND_ORDER.filter((name) => name !== caller)];
+}
 function resolveBackend(requested, liveRoot) {
     const value = requested ?? "auto";
     if (!BACKENDS.has(value))
@@ -499,7 +529,7 @@ function resolveBackend(requested, liveRoot) {
     // An explicitly named backend is honoured as given; only `auto` shops around.
     if (value !== "auto")
         return value;
-    const available = AUTO_BACKEND_ORDER.filter((name) => backendOnPath(name) && backendResponds(name));
+    const available = autoBackendPreference().filter((name) => backendOnPath(name) && backendResponds(name));
     if (available.length === 0)
         return "none";
     const crashed = crashedBackends(path.join(liveRoot, "workspace", "checkpoints", "sibling"));
@@ -507,7 +537,7 @@ function resolveBackend(requested, liveRoot) {
     // failure is a weaker signal than running no maintenance sibling at all.
     return available.find((name) => !crashed.has(name)) ?? available[0];
 }
-function siblingArgs(backend, prompt) {
+export function siblingArgs(backend, prompt) {
     switch (backend) {
         case "claude":
             return [
@@ -517,8 +547,16 @@ function siblingArgs(backend, prompt) {
                 CLAUDE_SIBLING_MODEL,
                 "--effort",
                 CLAUDE_SIBLING_EFFORT,
+                // `acceptEdits` auto-approves edits only. At the HQ root the scaffold
+                // settings make Bash "ask", so a terminal command — the git scan, the
+                // journal helper, the queue-draining `mv` — hits an approval gate with
+                // no human attached; headless `claude -p` then denies it and the run
+                // stalls having written no report. `bypassPermissions` is the same
+                // unattended posture codex gets from `-s workspace-write` and grok from
+                // `--always-approve --sandbox workspace`. Hooks still fire natively —
+                // this only removes the interactive approval gate, not the hook chain.
                 "--permission-mode",
-                "acceptEdits",
+                "bypassPermissions",
             ];
         case "grok":
             return [

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.1",
+  "version": "5.98.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {