@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -36,19 +36,21 @@ export declare const CHECKPOINT_REPLY_REMINDER: string;
  * demands the findings), so the conditional half still points there.
  */
 export declare const CHECKPOINT_IDLE_REPLY_REMINDER: string;
-/**
- * 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;
+export declare function renderSiblingPrompt(runDir: string, payloadPath: string, options?: {
+    company?: string | null;
+    hqRoot?: string;
+}): string;
 export type WriteStampsOptions = {
     /**
      * Filesystem seam (default the real `node:fs`); injected in tests to force a
      * permission errno so the HqStateWriteError conversion can be proven without a
      * real unwritable path.
      */
-    fs?: Pick<typeof fs, "mkdirSync" | "writeFileSync">;
+    fs?: Pick<typeof fs, "mkdirSync" | "writeFileSync" | "renameSync" | "unlinkSync">;
+    /** Runtime seam for proving the Windows-only atomic path without host assumptions. */
+    platform?: NodeJS.Platform;
+    /** Synchronous delay seam for the bounded Windows lock retry. */
+    waitForRetry?: (delayMs: number) => void;
 };
 export declare function writeStamps(liveRoot: string, sessionId: string | undefined, options?: WriteStampsOptions): string[];
 /**
@@ -56,9 +58,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(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 autoBackendPreference(): SpawnableBackend[];
+export declare function companyPrefersGrok(liveRoot: string, companySlug: string | null | undefined): boolean;
 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;

package/dist/commands/core-checkpoint.js

@@ -8,20 +8,26 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { randomUUID } from "node:crypto";
 import { execFileSync, spawn } from "node:child_process";
 import { homedir } from "node:os";
 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";
+import { markBorrowed, oldestQueuedCompany, recordQueuedTouches } from "../lib/checkpoint-ontology/queued-touches.js";
+import { describeCoreCommand } from "./core-command-catalog.js";
 const DEFAULT_TRIGGER = "stop-gate";
 const BACKENDS = new Set(["auto", "claude", "codex", "grok", "none"]);
-// Pinned by operator directive 2026-07-31; change defaults here deliberately.
+// Pinned by operator directive 2026-09-15; change defaults here deliberately.
 const CODEX_SIBLING_MODEL = "gpt-5.6-terra";
-const CODEX_SIBLING_REASONING_EFFORT = "high";
-const CLAUDE_SIBLING_MODEL = "claude-opus-5";
+const CODEX_SIBLING_REASONING_EFFORT = "medium";
+const CLAUDE_SIBLING_MODEL = "claude-sonnet-5";
 const CLAUDE_SIBLING_EFFORT = "medium";
-const GROK_SIBLING_MODEL = "grok-4.5";
-const GROK_SIBLING_EFFORT = "high";
+const GROK_SIBLING_MODEL = "grok-4.6";
+const GROK_SIBLING_EFFORT = "medium";
 /**
  * `grok -p` is single-turn by default: without a turn budget it answers with a
  * plan and exits, having done nothing. The maintenance flow needs many turns.
@@ -32,6 +38,31 @@ const GROK_SIBLING_MAX_TURNS = "100";
  * unavailable, unresponsive, out of credits (surfaces as a crashed run), or
  * simply unknown. First healthy candidate wins.
  */
+/**
+ * Durable opt-out for the maintenance sibling, read from the HQ root's
+ * `.claude/settings.json` (overlaid by `settings.local.json`, the same order
+ * Claude Code merges them):
+ *
+ *   { "env": { "HQ_CHECKPOINT_AGENT": "0" } }
+ *
+ * `--no-agent` and `--backend none` already turn the sibling off, but only for
+ * one invocation — no help when the checkpoint is fired by the Stop gate,
+ * where the user has no command line to edit. The sibling is the expensive
+ * half of a checkpoint (an unattended agent turn per Stop), so the off switch
+ * has to be somewhere a user can set it once. The `env` block is that place:
+ * Claude Code already exports it into hook processes, and reading the file
+ * directly means the setting also holds for the Codex and grok gates, whose
+ * hosts never read it.
+ */
+const SIBLING_SETTING = "HQ_CHECKPOINT_AGENT";
+/**
+ * The Stop gate's own switch. Resolved through the same settings file as the
+ * sibling switch so it reaches Codex and grok, whose hosts never export the
+ * `.claude/settings.json` `env` block into a hook process.
+ */
+const GATE_SETTING = "HQ_CHECKPOINT_GATE";
+const SIBLING_SETTING_OFF = new Set(["0", "false", "off", "no"]);
+const SIBLING_SETTING_ON = new Set(["1", "true", "on", "yes"]);
 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;
@@ -84,7 +115,7 @@ function printError(line) {
  * 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 const SIBLING_PROMPT_TEMPLATE = `You are the HQ checkpoint sibling — a background maintenance agent for this
+const SIBLING_PROMPT_TEMPLATE = `You are the HQ checkpoint sibling — a background maintenance agent for this
 HQ install. Your parent session's state is in <payloadPath>. Work
 quietly and do not ask questions; if something is ambiguous, record it in the
 report instead of guessing.
@@ -138,7 +169,7 @@ report instead of guessing.
    core/knowledge/public/hq-core/index-md-spec.md. Mechanical index generation
    is allowed for those companies, but knowledge/policy content writes remain
    restricted to the payload's named company.
-6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;
+<ontologyStep>6. Run .claude/skills/document-release/SKILL.md best-effort when it exists;
    skip silently on any failure. Hook or automation improvements go ONLY under
    personal/hooks/ as proposals.
 7. 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.
@@ -155,10 +186,33 @@ report instead of guessing.
    NEVER read the queue and truncate it in place: a payload appended between
    your read and the truncate is lost, and its checkpoint is never enriched.
 `;
-export function renderSiblingPrompt(runDir, payloadPath) {
+/**
+ * Rendered into the sibling prompt only when the payload names a company. The
+ * flag check happens inside `hq core ontology plan`, in the sibling, because
+ * the checkpoint parent performs no network I/O. Only this run's own payload
+ * gets the step. A queued payload's company files are recorded as queued
+ * touches when it is queued (CO-59), and a later plan for that company takes
+ * them while checkpoint.ontology.queued-touches is on; a run with no company
+ * of its own gets the step for the company whose touches waited longest.
+ */
+const SIBLING_ONTOLOGY_STEP = `5b. ONTOLOGY (this run's own payload only; skip it for claimed queue payloads).
+   Run: hq core ontology plan --run-dir "<runDir>" --hq-root "<hqRoot>"
+   If it prints "ontology: skipped", do nothing more for this step. Otherwise
+   read <runDir>/ontology-plan.json, follow its "instructions" exactly, and
+   write <runDir>/ontology-candidates.json. Read only the files and line
+   ranges the plan lists. Then run:
+   hq core ontology apply --run-dir "<runDir>" --hq-root "<hqRoot>"
+   Never write under the company's ontology/ folder yourself, and never edit
+   payload.json or ontology-plan.json. Copy the command's one-line output into
+   the report. If either command fails, record the error and continue.
+`;
+export function renderSiblingPrompt(runDir, payloadPath, options = {}) {
+    const ontologyStep = options.company && options.hqRoot ? SIBLING_ONTOLOGY_STEP : "";
     return SIBLING_PROMPT_TEMPLATE
+        .replaceAll("<ontologyStep>", () => ontologyStep)
         .replaceAll("<runDir>", () => runDir)
-        .replaceAll("<payloadPath>", () => payloadPath);
+        .replaceAll("<payloadPath>", () => payloadPath)
+        .replaceAll("<hqRoot>", () => options.hqRoot ?? "");
 }
 function collect(value, previous) {
     return [...previous, value];
@@ -383,14 +437,65 @@ function writeHqState(targetPath, operation, perform) {
         perform();
     }
     catch (error) {
+        if (isCheckpointStampWriteError(error))
+            throw error;
         const typed = toHqStateWriteError(error, targetPath, operation);
         if (typed)
             throw typed;
         throw error;
     }
 }
+const WINDOWS_CHECKPOINT_WRITE_RETRY_CODES = new Set(["EBUSY", "EPERM", "UNKNOWN"]);
+const WINDOWS_CHECKPOINT_WRITE_RETRY_DELAYS_MS = [25, 50, 100];
+function waitForCheckpointWriteRetry(delayMs) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT)), 0, 0, delayMs);
+}
+function removeCheckpointStampTemp(tempPath, fsImpl, waitForRetry) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            fsImpl.unlinkSync(tempPath);
+            return;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === "ENOENT")
+                return;
+            if (typeof code === "string" &&
+                WINDOWS_CHECKPOINT_WRITE_RETRY_CODES.has(code) &&
+                attempt < WINDOWS_CHECKPOINT_WRITE_RETRY_DELAYS_MS.length) {
+                waitForRetry(WINDOWS_CHECKPOINT_WRITE_RETRY_DELAYS_MS[attempt]);
+                continue;
+            }
+            throw checkpointStampWriteErrorFor(error, "unlink") ?? error;
+        }
+    }
+}
+function writeCheckpointStampAtomically(targetPath, contents, fsImpl, waitForRetry) {
+    for (let attempt = 0;; attempt += 1) {
+        const tempPath = path.join(path.dirname(targetPath), `.hq-checkpoint-stamp.tmp.${process.pid}.${randomUUID()}`);
+        let failedOperation = "open";
+        try {
+            fsImpl.writeFileSync(tempPath, contents, { flag: "wx" });
+            failedOperation = "rename";
+            fsImpl.renameSync(tempPath, targetPath);
+            return;
+        }
+        catch (error) {
+            removeCheckpointStampTemp(tempPath, fsImpl, waitForRetry);
+            const code = error?.code;
+            if (typeof code !== "string" ||
+                !WINDOWS_CHECKPOINT_WRITE_RETRY_CODES.has(code) ||
+                attempt >= WINDOWS_CHECKPOINT_WRITE_RETRY_DELAYS_MS.length) {
+                throw checkpointStampWriteErrorFor(error, failedOperation) ?? error;
+            }
+            waitForRetry(WINDOWS_CHECKPOINT_WRITE_RETRY_DELAYS_MS[attempt]);
+        }
+    }
+}
 export function writeStamps(liveRoot, sessionId, options = {}) {
     const fsImpl = options.fs ?? fs;
+    const platform = options.platform ?? process.platform;
+    const waitForRetry = options.waitForRetry ?? waitForCheckpointWriteRetry;
     const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
     writeHqState(stateDir, "create the checkpoint state directory", () => fsImpl.mkdirSync(stateDir, { recursive: true }));
     const sessionKey = sessionId
@@ -402,7 +507,9 @@ export function writeStamps(liveRoot, sessionId, options = {}) {
         path.join(stateDir, `checkpoint-cli-last-${sessionKey}`),
     ];
     for (const stampPath of stampPaths) {
-        writeHqState(stampPath, "write its checkpoint state file", () => fsImpl.writeFileSync(stampPath, timestamp));
+        writeHqState(stampPath, "write its checkpoint state file", () => platform === "win32"
+            ? writeCheckpointStampAtomically(stampPath, timestamp, fsImpl, waitForRetry)
+            : fsImpl.writeFileSync(stampPath, timestamp));
     }
     return stampPaths;
 }
@@ -426,12 +533,13 @@ function checkpointGateRuntime() {
         return runtime;
     return "other";
 }
-function gateEligibility(runtime) {
-    const forced = process.env.HQ_CHECKPOINT_GATE;
-    if (forced === "0")
-        return false;
-    if (forced === "1")
-        return true;
+function gateEligibility(runtime, liveRoot) {
+    // An operator switch precedes runtime and identity eligibility, and is read
+    // from the settings file as well as the environment: under Codex and grok the
+    // environment is the one place the operator cannot reach.
+    const forced = resolveSwitchSetting(liveRoot, GATE_SETTING);
+    if (forced !== undefined)
+        return forced;
     if (runtime === "claude")
         return true;
     if (runtime !== "codex")
@@ -453,7 +561,7 @@ function writeGateVerdict(liveRoot) {
     const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
     fs.mkdirSync(stateDir, { recursive: true });
     const runtime = checkpointGateRuntime();
-    const eligible = gateEligibility(runtime);
+    const eligible = gateEligibility(runtime, liveRoot);
     fs.writeFileSync(path.join(stateDir, `checkpoint-gate-eligible-${runtime}`), eligible ? "1" : "0");
     printResult(eligible ? "eligible" : "ineligible");
 }
@@ -570,22 +678,128 @@ 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.
+    for (const file of ["settings.local.json", "settings.json"]) {
+        const settingsPath = path.join(liveRoot, ".claude", file);
+        let contents;
+        try {
+            contents = fs.readFileSync(settingsPath, "utf8");
+        }
+        catch {
+            continue; // absent overlay or no .claude directory at all
+        }
+        let env;
+        try {
+            env = JSON.parse(contents)?.env;
+        }
+        catch {
+            printError(`checkpoint: ignoring ${settingsPath} (not valid JSON)`);
+            continue;
+        }
+        if (!env || typeof env !== "object" || !(key in env))
+            continue;
+        const raw = env[key];
+        if (typeof raw === "string") {
+            const trimmed = raw.trim();
+            // An empty string is not a deferral to the next file: the key is here and
+            // says nothing, which is a mistake worth naming.
+            return trimmed
+                ? { kind: "value", value: trimmed, source: settingsPath }
+                : { kind: "invalid", source: settingsPath, raw };
+        }
+        // Claude Code's env block takes strings, but JSON's own `false`/`0` is what
+        // a user reaches for first. Honour it rather than ignoring the intent.
+        if (typeof raw === "boolean" || typeof raw === "number") {
+            return { kind: "value", value: String(raw), source: settingsPath };
+        }
+        return { kind: "invalid", source: settingsPath, raw };
+    }
+    return { kind: "absent" };
+}
+/** Maps one resolved value onto the switch, reporting a vocabulary it cannot read. */
+function parseSwitchSetting(key, raw, source) {
+    const value = raw.toLowerCase();
+    if (SIBLING_SETTING_OFF.has(value))
+        return false;
+    if (SIBLING_SETTING_ON.has(value))
+        return true;
+    printError(`checkpoint: ignoring ${key}=${raw} from ${source} ` +
+        "(expected 0/1, false/true, off/on or no/yes)");
+    return undefined;
+}
+/**
+ * One operator switch: the process environment first, then the HQ root's
+ * Claude settings. `undefined` means nobody set it — distinct from a setting
+ * that says "off", and distinct from one this cannot read (reported, then
+ * treated as unset so a typo never silently flips a default).
+ */
+function resolveSwitchSetting(liveRoot, key) {
+    const fromEnv = process.env[key]?.trim();
+    if (fromEnv)
+        return parseSwitchSetting(key, fromEnv, "the environment");
+    const lookup = settingsEnvValue(liveRoot, key);
+    if (lookup.kind === "absent")
+        return undefined;
+    if (lookup.kind === "invalid") {
+        printError(`checkpoint: ignoring ${key} in ${lookup.source}: ` +
+            `${JSON.stringify(lookup.raw) ?? String(lookup.raw)} is not a value it can read ` +
+            '(expected a string such as "0" or "1")');
+        return undefined;
+    }
+    return parseSwitchSetting(key, lookup.value, lookup.source);
+}
+/**
+ * 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
+ * checkpoint …` still works and a host that exports the settings `env` block
+ * (Claude Code does) agrees with a host that does not.
+ */
+function siblingEnabledBySetting(liveRoot) {
+    return resolveSwitchSetting(liveRoot, SIBLING_SETTING) ?? true;
 }
-function resolveBackend(requested, liveRoot) {
+/** Rejects an unknown `--backend` without paying for the probe that resolves one. */
+function assertKnownBackend(requested) {
     const value = requested ?? "auto";
     if (!BACKENDS.has(value))
         usage(`checkpoint: unknown backend: ${value}`);
+    return value;
+}
+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"));
@@ -593,6 +807,24 @@ 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];
 }
+/**
+ * Lane identity a checkpoint caller may carry. The sibling is HQ maintenance,
+ * not the lane: with HQ_LANE_ID set, the lane drop-box hook hands the lane's
+ * operator messages to the sibling, and the lane never sees them.
+ */
+const LANE_ENV_KEYS = ["HQ_LANE_ID", "HQ_PROJECT_ID", "HQ_STORY_ID", "HQ_POLICY_WORKER_DIR"];
+/** The sibling's environment: the caller's, minus lane identity. */
+function siblingEnv(base, backend) {
+    const vars = { ...base };
+    for (const name of LANE_ENV_KEYS)
+        delete vars[name];
+    // This prevents the scaffold Stop hook from recursively launching a
+    // sibling when the background agent itself finishes a turn.
+    vars.HQ_CHECKPOINT_SIBLING = "1";
+    if (backend === "claude")
+        vars.CLAUDE_EFFORT = CLAUDE_SIBLING_EFFORT;
+    return vars;
+}
 export function siblingArgs(backend, prompt) {
     switch (backend) {
         case "claude":
@@ -772,15 +1004,43 @@ function startSibling(liveRoot, input, threadPath, backend) {
     fs.mkdirSync(siblingRoot, { recursive: true });
     if (activePid !== null) {
         const depth = appendPending(pendingPath, payload);
+        try {
+            recordQueuedTouches(liveRoot, payload.company, payload.files, new Date());
+        }
+        catch {
+            // Queued touches only help a later ontology plan; they must never fail
+            // the checkpoint itself.
+        }
         printResult(`checkpoint: sibling busy — payload queued (${depth} pending)`);
         return;
     }
     const runDir = path.join(siblingRoot, `${formatTimestamp(new Date())}-${summarySlug(input.summary ?? "checkpoint")}`);
     fs.mkdirSync(runDir, { recursive: true });
     payload.pending_payloads = claimPending(pendingPath, path.join(runDir, "pending-claimed.jsonl"));
+    if (!payload.company) {
+        let queued;
+        try {
+            queued = oldestQueuedCompany(liveRoot);
+        }
+        catch {
+            queued = null;
+        }
+        if (queued) {
+            payload.ontology_company = queued;
+            try {
+                markBorrowed(liveRoot, queued, new Date());
+            }
+            catch {
+                // A borrowed-company marker must never fail the checkpoint.
+            }
+        }
+    }
     const payloadPath = path.join(runDir, "payload.json");
     fs.writeFileSync(payloadPath, `${JSON.stringify(payload, null, 2)}\n`);
-    const prompt = renderSiblingPrompt(runDir, payloadPath);
+    const prompt = renderSiblingPrompt(runDir, payloadPath, {
+        company: payload.company ?? payload.ontology_company ?? null,
+        hqRoot: liveRoot,
+    });
     fs.writeFileSync(path.join(runDir, "prompt.md"), prompt);
     const logPath = path.join(runDir, "run.log");
     const logFd = fs.openSync(logPath, "a");
@@ -789,15 +1049,10 @@ function startSibling(liveRoot, input, threadPath, backend) {
     try {
         child = spawn(backend, args, {
             detached: true,
+            windowsHide: true,
             cwd: liveRoot,
             stdio: ["ignore", logFd, logFd],
-            // This prevents the scaffold Stop hook from recursively launching a
-            // sibling when the background agent itself finishes a turn.
-            env: {
-                ...process.env,
-                HQ_CHECKPOINT_SIBLING: "1",
-                ...(backend === "claude" ? { CLAUDE_EFFORT: CLAUDE_SIBLING_EFFORT } : {}),
-            },
+            env: siblingEnv(process.env, backend),
         });
     }
     finally {
@@ -869,7 +1124,12 @@ function runCheckpoint(options, command, group) {
     if (!input.summary?.trim()) {
         usage("checkpoint: --summary is required unless --idle or --gate-probe is used");
     }
-    const backend = resolveBackend(options.backend, liveRoot);
+    // Resolved before resolveBackend so an opted-out run pays for no backend
+    // probe: `--backend auto` shells out to every installed CLI for a version.
+    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, input.company);
     const now = new Date();
     const threadId = `T-${formatTimestamp(now)}-auto-${summarySlug(input.summary)}`;
     const threadPath = path.join(liveRoot, "workspace", "threads", `${threadId}.json`);
@@ -890,7 +1150,7 @@ function runCheckpoint(options, command, group) {
                 worker: input.worker,
             },
             stamps: stampPaths.map((stampPath) => path.relative(liveRoot, stampPath)),
-            sibling: options.agent === false ? null : { backend },
+            sibling: siblingOptOut ? null : { backend },
         });
         return;
     }
@@ -926,7 +1186,10 @@ function runCheckpoint(options, command, group) {
     // requested backend that is not installed).
     try {
         if (options.agent !== false) {
-            if (backend === "none") {
+            if (siblingOptOut) {
+                printResult(`checkpoint: sibling disabled (${SIBLING_SETTING})`);
+            }
+            else if (backend === "none") {
                 printResult("checkpoint: sibling disabled (backend none)");
             }
             else {
@@ -945,7 +1208,7 @@ function reportUsage(error) {
 }
 /** Attach the native checkpoint command to the hidden `hq core` group. */
 export function registerCoreCheckpointCommand(core) {
-    core
+    const checkpoint = core
         .command("checkpoint")
         .description("Record an end-of-turn checkpoint and start HQ maintenance")
         .option("--summary <text>", "1–2 sentence outcome summary")
@@ -966,7 +1229,7 @@ export function registerCoreCheckpointCommand(core) {
         .option("--transcript <path>", "session transcript path")
         .option("--payload <file|->", "JSON payload file, or - for stdin")
         .option("--idle", "touch stamps without a checkpoint")
-        .option("--no-agent", "do not spawn the maintenance sibling")
+        .option("--no-agent", `do not spawn the maintenance sibling (set it off for good with "env": {"${SIBLING_SETTING}": "0"} in .claude/settings.json)`)
         .option("--backend <auto|claude|codex|grok|none>", "sibling backend", "auto")
         .option("--gate-probe", "write the local Stop-hook eligibility verdict")
         .option("--hq-root <path>", "HQ installation to operate on")
@@ -981,5 +1244,6 @@ export function registerCoreCheckpointCommand(core) {
             throw error;
         }
     });
+    describeCoreCommand(checkpoint, { execution: "native", root: "live" });
 }
 //# sourceMappingURL=core-checkpoint.js.map

package/dist/commands/core-command-catalog.d.ts

@@ -0,0 +1,34 @@
+import type { Command } from "commander";
+export type CoreCommandExecution = "native" | "bundled-shell" | "bundled-node";
+export type CoreCommandRoot = "live" | "source" | "cwd";
+export type CoreCommandListingEntry = {
+    name: string;
+    execution: CoreCommandExecution;
+    asset?: string;
+    root: CoreCommandRoot;
+};
+type CoreCommandMetadata = (Omit<CoreCommandListingEntry, "name"> & {
+    entries?: never;
+}) | {
+    entries: readonly CoreCommandListingEntry[];
+};
+/** Mark the exact Commander registration that supplies a catalog row. */
+export declare function describeCoreCommand(command: Command, metadata: CoreCommandMetadata): Command;
+/**
+ * Reflect executable leaf commands from the Commander tree. Asset-backed rows
+ * are attached at the point where core.ts registers each table entry, so the
+ * JSON output cannot drift into a second, hand-maintained command list.
+ */
+export declare function registeredCoreCommandListing(core: Command): CoreCommandListingEntry[];
+export declare function fastScaffoldListingMismatches(listing: readonly CoreCommandListingEntry[], fastScripts: readonly {
+    name: string;
+    kind: "shell" | "native";
+    asset?: string;
+}[]): string[];
+export declare function assertFastScaffoldListingParity(listing: readonly CoreCommandListingEntry[], fastScripts: readonly {
+    name: string;
+    kind: "shell" | "native";
+    asset?: string;
+}[]): void;
+export {};
+//# sourceMappingURL=core-command-catalog.d.ts.map

package/dist/commands/core-command-catalog.js

@@ -0,0 +1,62 @@
+const metadataByCommand = new WeakMap();
+/** Mark the exact Commander registration that supplies a catalog row. */
+export function describeCoreCommand(command, metadata) {
+    metadataByCommand.set(command, metadata);
+    return command;
+}
+/**
+ * Reflect executable leaf commands from the Commander tree. Asset-backed rows
+ * are attached at the point where core.ts registers each table entry, so the
+ * JSON output cannot drift into a second, hand-maintained command list.
+ */
+export function registeredCoreCommandListing(core) {
+    const entries = [];
+    const visit = (parent, parents) => {
+        for (const command of parent.commands) {
+            const path = [...parents, command.name()].join(" ");
+            if (command.commands.length > 0) {
+                visit(command, [...parents, command.name()]);
+                continue;
+            }
+            const metadata = metadataByCommand.get(command);
+            if (!metadata) {
+                throw new Error(`hq core command ${path} has no listing metadata`);
+            }
+            const described = metadata.entries
+                ? metadata.entries
+                : [{
+                        name: path,
+                        execution: metadata.execution,
+                        ...(metadata.asset ? { asset: metadata.asset } : {}),
+                        root: metadata.root,
+                    }];
+            entries.push(...described);
+        }
+    };
+    visit(core, []);
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function fastScaffoldListingMismatches(listing, fastScripts) {
+    const mismatches = [];
+    for (const fast of fastScripts) {
+        const listed = listing.find((entry) => entry.name === fast.name);
+        if (!listed) {
+            mismatches.push(`${fast.name} is missing from hq core commands`);
+        }
+        else if (fast.kind === "shell" && listed.asset !== fast.asset) {
+            mismatches.push(`${fast.name} lists ${listed.asset ?? "no asset"}, fast path uses ${fast.asset ?? "no asset"}`);
+        }
+        else if (fast.kind === "native" && ((listed.execution !== "native" && listed.execution !== "bundled-shell") ||
+            (fast.asset === undefined ? listed.asset !== undefined : listed.asset !== fast.asset))) {
+            mismatches.push(`${fast.name} has fast-route metadata that differs from the native command catalog`);
+        }
+    }
+    return mismatches;
+}
+export function assertFastScaffoldListingParity(listing, fastScripts) {
+    const mismatches = fastScaffoldListingMismatches(listing, fastScripts);
+    if (mismatches.length > 0) {
+        throw new Error(mismatches.join("\n"));
+    }
+}
+//# sourceMappingURL=core-command-catalog.js.map

package/dist/commands/core-company-index-scope-flag.d.ts

@@ -0,0 +1,3 @@
+export declare const CORE_COMPANY_INDEX_SCOPE_FLAG = "cli.rebuild-index-company-scope";
+export declare function coreCompanyIndexScopeEnabled(): boolean;
+//# sourceMappingURL=core-company-index-scope-flag.d.ts.map