@indigoai-us/hq-cli 5.208.0 → 5.209.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.209.0] — 2026-09-26
+
+### Added
+
+- Behind the off-by-default `checkpoint.ontology.grok-backend` flag, `hq core checkpoint --backend auto` tries grok first for the payload company and falls back to the usual order when grok is missing or crashed last time. The detached ontology plan reads the flag and records it in the company state directory, so the foreground checkpoint makes no network call; a flag change applies from the checkpoint after the next plan.
+- Behind the off-by-default `checkpoint.ontology.ignore-annotations` flag, the checkpoint ontology plan gives the model a copy of each knowledge input without the old cloud annotator's `entities:` front-matter list and entity links, which were mostly wrong and which the model copied.
+
 ## [5.208.0] — 2026-09-26
 
 ### Fixed

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

@@ -71,9 +71,17 @@ export declare function writeStamps(liveRoot: string, sessionId: string | undefi
  * 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.
+ * tested directly. `preferGrok` (the company's grok-backend flag) puts grok
+ * ahead of that order and leaves the rest as the fallback.
  */
-export declare function autoBackendPreference(): SpawnableBackend[];
+export declare function autoBackendPreference(preferGrok?: boolean): SpawnableBackend[];
+/**
+ * Whether the payload company's last ontology plan recorded
+ * checkpoint.ontology.grok-backend as on. Reads only the local state file the
+ * detached sibling writes, so a foreground checkpoint never waits on the flag
+ * registry; a flag change takes effect from the checkpoint after the next plan.
+ */
+export declare function companyPrefersGrok(liveRoot: string, companySlug: string | null | undefined): boolean;
 /**
  * Whether the maintenance sibling may run at all. The process environment wins
  * over the settings file, so a one-off `HQ_CHECKPOINT_AGENT=0 hq core

package/dist/commands/core-checkpoint.js

@@ -15,6 +15,8 @@ import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { peekIdToken } from "../utils/id-token.js";
 import { toHqStateWriteError } from "../utils/hq-state-write-error.js";
 import { checkpointStampWriteErrorFor, isCheckpointStampWriteError, } from "../utils/checkpoint-stamp-write-error.js";
+import { readBackendPreference } from "../lib/checkpoint-ontology/plan.js";
+import { resolveOntologyCompany } from "../lib/checkpoint-ontology/company.js";
 const DEFAULT_TRIGGER = "stop-gate";
 const BACKENDS = new Set(["auto", "claude", "codex", "grok", "none"]);
 // Pinned by operator directive 2026-09-15; change defaults here deliberately.
@@ -672,13 +674,34 @@ function callerBackend() {
  * 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.
+ * tested directly. `preferGrok` (the company's grok-backend flag) puts grok
+ * ahead of that order and leaves the rest as the fallback.
  */
-export function autoBackendPreference() {
+export function autoBackendPreference(preferGrok = false) {
     const caller = callerBackend();
-    if (!caller)
-        return [...FALLBACK_BACKEND_ORDER];
-    return [caller, ...FALLBACK_BACKEND_ORDER.filter((name) => name !== caller)];
+    const order = caller
+        ? [caller, ...FALLBACK_BACKEND_ORDER.filter((name) => name !== caller)]
+        : [...FALLBACK_BACKEND_ORDER];
+    return preferGrok ? ["grok", ...order.filter((name) => name !== "grok")] : order;
+}
+/**
+ * Whether the payload company's last ontology plan recorded
+ * checkpoint.ontology.grok-backend as on. Reads only the local state file the
+ * detached sibling writes, so a foreground checkpoint never waits on the flag
+ * registry; a flag change takes effect from the checkpoint after the next plan.
+ */
+export function companyPrefersGrok(liveRoot, companySlug) {
+    const resolved = resolveOntologyCompany(liveRoot, companySlug);
+    if (!resolved.ok)
+        return false;
+    try {
+        return readBackendPreference(liveRoot, resolved.company);
+    }
+    catch (error) {
+        // A damaged state file must not stop the checkpoint; the usual order applies.
+        printError(`checkpoint: ignoring unreadable backend preference for ${resolved.company.slug}: ${error.message}`);
+        return false;
+    }
 }
 function settingsEnvValue(liveRoot, key) {
     // settings.local.json wins, matching Claude Code's own merge order.
@@ -767,12 +790,12 @@ function assertKnownBackend(requested) {
         usage(`checkpoint: unknown backend: ${value}`);
     return value;
 }
-function resolveBackend(requested, liveRoot) {
+function resolveBackend(requested, liveRoot, company) {
     const value = assertKnownBackend(requested);
     // An explicitly named backend is honoured as given; only `auto` shops around.
     if (value !== "auto")
         return value;
-    const available = autoBackendPreference().filter((name) => backendOnPath(name) && backendResponds(name));
+    const available = autoBackendPreference(companyPrefersGrok(liveRoot, company)).filter((name) => backendOnPath(name) && backendResponds(name));
     if (available.length === 0)
         return "none";
     const crashed = crashedBackends(path.join(liveRoot, "workspace", "checkpoints", "sibling"));
@@ -1073,7 +1096,7 @@ function runCheckpoint(options, command, group) {
     const siblingOptOut = options.agent === false || !siblingEnabledBySetting(liveRoot);
     // Validated even when nothing will spawn, so `--backend bogus` is still an error.
     const requestedBackend = assertKnownBackend(options.backend);
-    const backend = siblingOptOut ? "none" : resolveBackend(requestedBackend, liveRoot);
+    const backend = siblingOptOut ? "none" : resolveBackend(requestedBackend, liveRoot, input.company);
     const now = new Date();
     const threadId = `T-${formatTimestamp(now)}-auto-${summarySlug(input.summary)}`;
     const threadPath = path.join(liveRoot, "workspace", "threads", `${threadId}.json`);

package/dist/lib/checkpoint-ontology/plan.d.ts

@@ -12,6 +12,13 @@ import { type OntologyCompany } from "./company.js";
 export declare const ONTOLOGY_FLAG = "checkpoint.ontology";
 export declare const SHARED_INPUTS_FLAG = "checkpoint.ontology.shared-inputs";
 export declare const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
+export declare const IGNORE_ANNOTATIONS_FLAG = "checkpoint.ontology.ignore-annotations";
+/**
+ * With `--backend auto`, `hq core checkpoint` tries grok first for this
+ * company. Read here, in the detached sibling, and recorded in the company's
+ * state directory, so the foreground checkpoint makes no network call.
+ */
+export declare const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
 export declare const PLAN_FILE = "ontology-plan.json";
 export declare const CANDIDATES_FILE = "ontology-candidates.json";
 export declare const REPORT_FILE = "ontology-report.json";
@@ -59,6 +66,8 @@ export interface PlanInput {
     } | null;
     /** For signals: `entity_refs` items with no entity file yet. */
     missing_refs?: string[];
+    /** Run-directory-relative copy of `path` with annotator entity lists removed; same line numbers. */
+    read_path?: string;
 }
 export interface OntologyPlan {
     schema: typeof PLAN_SCHEMA;
@@ -112,9 +121,13 @@ export type PlanOutcome = {
     planPath: string;
     companyBrief?: CompanyBriefResult;
 };
+export declare const READ_PATH_INSTRUCTION = "When an input has read_path, read that file (relative to the run directory) instead of path, with the same line range. It is the same text with an older annotator's entity lists and entity links removed.";
 export declare function ledgerPath(hqRoot: string, company: OntologyCompany): string;
 export declare function readLedger(hqRoot: string, company: OntologyCompany): Ledger | null;
 export declare function writeLedger(hqRoot: string, company: OntologyCompany, ledger: Ledger): void;
+export declare function backendPreferencePath(hqRoot: string, company: OntologyCompany): string;
+/** The grok-backend flag value the last plan recorded; false when no plan has recorded one. */
+export declare function readBackendPreference(hqRoot: string, company: OntologyCompany): boolean;
 /** Company-relative paths of the payload's touched files that are inside this company. */
 export declare function sessionTouched(hqRoot: string, company: OntologyCompany, files: unknown): Set<string>;
 /** 1-based line ranges, each at most `chunkTokens` tokens (bytes / 4). */
@@ -130,4 +143,13 @@ export declare function refreshLedger(company: OntologyCompany, existing: Ledger
 };
 /** Plan this run. Never throws for a skip; returns the reason instead. */
 export declare function planOntologyRun(options: PlanOptions): Promise<PlanOutcome>;
+/**
+ * The cloud annotator wrote an `entities:` list into knowledge front matter and
+ * `[[ontology/entities/...]]` links into the text. Most are wrong, and a model
+ * told to ignore them still copies them (design section 18), so the model reads
+ * a copy without them. The list's lines are blanked rather than removed so the
+ * plan's line ranges still hold; a link becomes its label, or its last path
+ * segment. Returns null when the text has neither.
+ */
+export declare function stripAnnotations(text: string): string | null;
 //# sourceMappingURL=plan.d.ts.map

package/dist/lib/checkpoint-ontology/plan.js

@@ -16,6 +16,13 @@ import { buildEntityIndex, listKnowledgeFiles, listSignalFiles, readSignal } fro
 export const ONTOLOGY_FLAG = "checkpoint.ontology";
 export const SHARED_INPUTS_FLAG = "checkpoint.ontology.shared-inputs";
 export const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
+export const IGNORE_ANNOTATIONS_FLAG = "checkpoint.ontology.ignore-annotations";
+/**
+ * With `--backend auto`, `hq core checkpoint` tries grok first for this
+ * company. Read here, in the detached sibling, and recorded in the company's
+ * state directory, so the foreground checkpoint makes no network call.
+ */
+export const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
 export const PLAN_FILE = "ontology-plan.json";
 export const CANDIDATES_FILE = "ontology-candidates.json";
 export const REPORT_FILE = "ontology-report.json";
@@ -27,6 +34,7 @@ export const BUDGET = {
     maxTokens: 60_000,
     chunkTokens: 12_000,
 };
+export const READ_PATH_INSTRUCTION = "When an input has read_path, read that file (relative to the run directory) instead of path, with the same line range. It is the same text with an older annotator's entity lists and entity links removed.";
 const CANDIDATE_INSTRUCTIONS = [
     `Write ${CANDIDATES_FILE} in the run directory as {"schema":"${CANDIDATES_SCHEMA}","candidates":[...]} and nothing else.`,
     "Each candidate: {input, type, name, aliases, confidence, evidence}. input is one of this plan's input ids; type is person, project, company or concept; name is the entity's full proper name; aliases are other names the input uses for it (at most 5); confidence is 0 to 1; evidence is a short quote from the input.",
@@ -61,6 +69,26 @@ export function writeLedger(hqRoot, company, ledger) {
     const target = ledgerPath(hqRoot, company);
     safeWriteFile(hqRoot, [stateRoot(hqRoot, company)], target, `${JSON.stringify(ledger, null, 2)}\n`);
 }
+export function backendPreferencePath(hqRoot, company) {
+    return path.join(stateRoot(hqRoot, company), "backend.json");
+}
+/** The grok-backend flag value the last plan recorded; false when no plan has recorded one. */
+export function readBackendPreference(hqRoot, company) {
+    let raw;
+    try {
+        raw = fs.readFileSync(backendPreferencePath(hqRoot, company), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    return JSON.parse(raw)?.prefer_grok === true;
+}
+function recordBackendPreference(hqRoot, company, preferGrok) {
+    const target = backendPreferencePath(hqRoot, company);
+    safeWriteFile(hqRoot, [stateRoot(hqRoot, company)], target, `${JSON.stringify({ prefer_grok: preferGrok })}\n`);
+}
 /** Company-relative paths of the payload's touched files that are inside this company. */
 export function sessionTouched(hqRoot, company, files) {
     const out = new Set();
@@ -172,13 +200,18 @@ export async function planOntologyRun(options) {
     if (!resolution.ok)
         return { status: "skipped", reason: resolution.reason };
     const company = resolution.company;
-    if (!(await options.readFlag(ONTOLOGY_FLAG, company)))
+    if (!(await options.readFlag(ONTOLOGY_FLAG, company))) {
+        // A preference recorded while the ontology was on must not outlive it.
+        fs.rmSync(backendPreferencePath(hqRoot, company), { force: true });
         return { status: "skipped", reason: "flag off" };
+    }
     const sharedInputs = await options.readFlag(SHARED_INPUTS_FLAG, company);
     // Before the ledger, so a nothing-changed plan still records the brief.
     const companyBrief = (await options.readFlag(COMPANY_BRIEF_FLAG, company))
         ? writeCompanyBrief(hqRoot, company, options.now ?? new Date())
         : undefined;
+    const ignoreAnnotations = await options.readFlag(IGNORE_ANNOTATIONS_FLAG, company);
+    recordBackendPreference(hqRoot, company, await options.readFlag(GROK_BACKEND_FLAG, company));
     const touched = sessionTouched(hqRoot, company, payload.files);
     const { ledger, firstRun } = refreshLedger(company, readLedger(hqRoot, company), touched, sharedInputs);
     const pending = Object.entries(ledger.entries)
@@ -192,9 +225,16 @@ export async function planOntologyRun(options) {
             remaining += 1;
             continue;
         }
-        const lines = fs.readFileSync(path.join(company.dir, rel), "utf8").split("\n");
+        const text = fs.readFileSync(path.join(company.dir, rel), "utf8");
+        const lines = text.split("\n");
         const chunks = chunkLines(lines.join("\n"), BUDGET.chunkTokens);
         const kind = rel.startsWith("signals/") ? "signal" : "knowledge";
+        const cleaned = ignoreAnnotations && kind === "knowledge" ? stripAnnotations(text) : null;
+        const readPath = cleaned === null ? null : path.join(READ_COPY_DIR, rel);
+        if (readPath !== null) {
+            fs.mkdirSync(path.dirname(path.join(runDir, readPath)), { recursive: true });
+            fs.writeFileSync(path.join(runDir, readPath), cleaned);
+        }
         let index = entry.next_chunk ?? 0;
         for (; index < chunks.length; index += 1) {
             const [start, end] = chunks[index];
@@ -212,6 +252,7 @@ export async function planOntologyRun(options) {
                 lines: chunks.length > 1 ? [start, end] : null,
                 chunk: chunks.length > 1 ? { index, count: chunks.length } : null,
                 ...(kind === "signal" ? { missing_refs: missingRefs(company.dir, rel) } : {}),
+                ...(readPath !== null ? { read_path: readPath } : {}),
             });
             tokens += cost;
         }
@@ -267,13 +308,47 @@ export async function planOntologyRun(options) {
             planned_tokens: tokens,
         },
         candidates_file: CANDIDATES_FILE,
-        instructions: CANDIDATE_INSTRUCTIONS,
+        instructions: inputs.some((input) => input.read_path)
+            ? [...CANDIDATE_INSTRUCTIONS.slice(0, 3), READ_PATH_INSTRUCTION, ...CANDIDATE_INSTRUCTIONS.slice(3)]
+            : CANDIDATE_INSTRUCTIONS,
     };
     fs.mkdirSync(runDir, { recursive: true });
     const planPath = path.join(runDir, PLAN_FILE);
     fs.writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
     return companyBrief ? { status: "planned", plan, planPath, companyBrief } : { status: "planned", plan, planPath };
 }
+const READ_COPY_DIR = "ontology-inputs";
+/**
+ * The cloud annotator wrote an `entities:` list into knowledge front matter and
+ * `[[ontology/entities/...]]` links into the text. Most are wrong, and a model
+ * told to ignore them still copies them (design section 18), so the model reads
+ * a copy without them. The list's lines are blanked rather than removed so the
+ * plan's line ranges still hold; a link becomes its label, or its last path
+ * segment. Returns null when the text has neither.
+ */
+export function stripAnnotations(text) {
+    let out = text;
+    const front = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (front && /^entities:/m.test(front[1])) {
+        let inList = false;
+        const body = front[1]
+            .split("\n")
+            .map((line) => {
+            if (/^entities:/.test(line))
+                inList = true;
+            else if (inList && /^\S/.test(line))
+                inList = false;
+            return inList ? "" : line;
+        })
+            .join("\n");
+        const start = text.indexOf("\n") + 1;
+        out = text.slice(0, start) + body + text.slice(start + front[1].length);
+    }
+    out = out
+        .replace(/\[\[ontology\/entities\/[^\]|\n]*\|([^\]\n]*)\]\]/g, "$1")
+        .replace(/\[\[ontology\/entities\/(?:[^\]\n]*\/)?([^\]/\n]*)\]\]/g, "$1");
+    return out === text ? null : out;
+}
 const SESSION_TEXT_MAX_BYTES = 8_000;
 /** The session summary, decisions and learnings from the payload, capped. */
 function sessionContent(payload) {

package/package.json

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