@indigoai-us/hq-cli 5.345.28 → 5.345.29

package/dist/commands/core-checkpoint-native.js

@@ -0,0 +1,1252 @@
+/**
+ * `hq core checkpoint` — synchronous end-of-turn state capture plus an
+ * optional detached HQ-maintenance sibling.
+ *
+ * The foreground command intentionally performs only local filesystem and git
+ * reads/writes. It never waits for the sibling, and it never performs network
+ * I/O itself.
+ */
+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 { toHqStateWriteError } from "../utils/hq-state-write-error.js";
+import { checkpointStampWriteErrorFor, isCheckpointStampWriteError, } from "../utils/checkpoint-stamp-write-error.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-09-15; change defaults here deliberately.
+const CODEX_SIBLING_MODEL = "gpt-5.6-terra";
+const CODEX_SIBLING_REASONING_EFFORT = "medium";
+const CLAUDE_SIBLING_MODEL = "claude-sonnet-5";
+const CLAUDE_SIBLING_EFFORT = "medium";
+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.
+ */
+const GROK_SIBLING_MAX_TURNS = "100";
+/**
+ * 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.
+ */
+/**
+ * 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;
+/** A sibling still holding the lock after this long is treated as abandoned. */
+const SIBLING_LOCK_TTL_MS = 60 * 60 * 1000;
+/** Newest-wins cap so a wedged sibling cannot grow an unbounded queue. */
+const MAX_PENDING_PAYLOADS = 50;
+class CheckpointUsageError extends Error {
+}
+/**
+ * Printed after every non-dry-run checkpoint, real or --idle. Agents were
+ * treating the checkpoint call as the end of the turn, leaving their actual
+ * findings only in the checkpoint payload — which the user never sees. This
+ * line rides the command output (the one channel guaranteed to reach the
+ * calling agent) to force the user-facing reply. Deliberately conditional on
+ * whether the reply was already delivered this turn: an unconditional
+ * "restate in full" made agents repeat a reply the user had already seen
+ * (both the CLI and the desktop app render pre-tool-call text), while an
+ * unconditional "no commentary after" hid the reply from agents that had not
+ * yet written one. The Stop gate makes the same distinction from the
+ * transcript — and backstops this reminder mechanically: a satisfying
+ * checkpoint on a work turn whose genuine reply is still missing is blocked
+ * once with a dedicated reply demand. This line covers proactive checkpoints
+ * the gate never sees. Mirrors the hq-core policies
+ * `checkpoint-is-bookkeeping-not-user-communication` and
+ * `checkpoint-is-not-the-user-report`.
+ */
+export const CHECKPOINT_REPLY_REMINDER = "checkpoint: REMINDER — this checkpoint is invisible bookkeeping; the user never sees it " +
+    "and it does NOT count as your reply. If this turn's substance (results, findings, " +
+    "decisions, state changes, anything awaiting their input) has NOT yet been delivered to " +
+    "the user, write your user-facing reply now as the FINAL text of the turn. If you " +
+    "already delivered it earlier this turn, end the turn now WITHOUT repeating it — the " +
+    "user has already seen that message, and repeating it double-messages them.";
+/**
+ * The --idle variant: an idle-only turn (nothing ran, nothing to report) is
+ * exempt at the Stop gate, so this text must never order a reply into
+ * existence — but an --idle after read-only work is NOT exempt (the gate
+ * demands the findings), so the conditional half still points there.
+ */
+export const CHECKPOINT_IDLE_REPLY_REMINDER = "checkpoint: idle recorded — invisible bookkeeping; the user sees none of it. If this " +
+    "turn surfaced findings or answers the user has not been told, deliver them now as the " +
+    "turn's final text. If the turn genuinely produced nothing to report, end it.";
+function printResult(line) {
+    process.stdout.write(`${line}\n`);
+}
+function printError(line) {
+    process.stderr.write(`${line}\n`);
+}
+/**
+ * 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.
+ */
+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.
+
+1. Read the payload. If it lists a transcript path that exists, read its tail (~400 lines)
+   both for session context and to extract additional reusable learnings/insights
+   the parent did not pass explicitly. Never quote secrets
+   or tokens from the transcript. If .claude/skills/checkpoint/SKILL.md exists
+   under this HQ root, read it and follow it wherever it goes beyond these instructions;
+   the write bounds below always win over the skill text.
+2. Upgrade the thread file named in the payload IN PLACE: verify/repair its
+   JSON; fill git.remote_url, git.initial_commit, git.commits_made, and
+   git.knowledge_repos by scanning core/knowledge/public/*,
+   core/knowledge/private/*, personal/knowledge/*, and companies/*/knowledge
+   for symlinks or directories containing .git, recording dirty repositories
+   as {"<name>": {"commit": "<short>", "dirty": true}}. Fill worker,
+   next_steps, and insights; set type to "checkpoint"; then rename the file to
+   drop -auto- from its filename. Use the renamed path in every reference you
+   write afterwards.
+3. For every explicit or transcript-derived learning that is a reusable rule,
+   FIRST search the existing policies for one the learning refines, contradicts
+   or duplicates. Then take exactly one of these actions and name it in the
+   report — the policy set is curated, not append-only:
+   - AMEND an existing policy in place when the learning sharpens it, narrows
+     its scope, or adds a case, and the rule as written is still correct.
+   - SUPERSEDE it when the learning contradicts it: rewrite the rule to what is
+     now true and record inside the file what changed and why.
+   - MERGE near-duplicates into the single best-named file, then delete the
+     files you merged away.
+   - CREATE a new policy only when no existing policy covers the rule.
+   Follow core/knowledge/public/hq-core/policies-spec.md. Write under
+   personal/policies/ or, only when the payload names a company and the rule is
+   company-specific, companies/<company>/policies/.
+   DELETION BOUNDS: delete a policy only as the MERGE or SUPERSEDE step above,
+   only inside those two directories, and never one whose body marks it HARD —
+   if a hard policy now looks wrong, leave it untouched and flag it in the
+   report for a human to decide. Never delete a file you have not read.
+   Apply the same curation to durable facts (not rules) under
+   personal/knowledge/ or companies/<company>/knowledge/: correct a stale fact
+   in place rather than appending a second, contradictory copy of it.
+   Store up to two explicit or transcript-derived insights per
+   core/knowledge/public/hq-core/insights-spec.md when present, otherwise
+   workspace/insights/.
+4. Close an active session journal fail-soft with
+   bash .claude/skills/_shared/journal.sh close "<project_dir>" "<one-line synthesis>".
+   Write a legacy checkpoint JSON under workspace/checkpoints/<id>.json with
+   id, created_at, summary, files, and next_steps for backward compatibility.
+5. Update workspace/threads/recent.md and regenerate
+   workspace/threads/INDEX.md. For each company whose knowledge path appears
+   in files_touched, regenerate companies/<company>/knowledge/INDEX.md under
+   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.
+<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.
+8. Write <runDir>/report.md — full prose: what you read, what you changed
+   (paths), and what you skipped and why. List every policy or knowledge file
+   you amended, superseded, merged or deleted with the reason, so a human can
+   audit and reverse it; a deletion you do not name in the report is a defect.
+   Then drain the queue: while
+   workspace/checkpoints/sibling/pending.jsonl exists and is non-empty, claim
+   it atomically by renaming it aside —
+   mv workspace/checkpoints/sibling/pending.jsonl <runDir>/pending-claimed-N.jsonl
+   (N counting up from 2) — and process the claimed payloads with this same
+   flow. Repeat until a claim finds nothing left, then update the report.
+   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.
+`;
+/**
+ * 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("<hqRoot>", () => options.hqRoot ?? "");
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+function usage(message) {
+    throw new CheckpointUsageError(message);
+}
+function readPayload(payloadPath) {
+    if (!payloadPath)
+        return {};
+    let raw;
+    try {
+        raw = payloadPath === "-"
+            ? fs.readFileSync(0, "utf8")
+            : fs.readFileSync(payloadPath, "utf8");
+    }
+    catch {
+        usage(`checkpoint: could not read payload: ${payloadPath}`);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            usage("checkpoint: payload must be a JSON object");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof CheckpointUsageError)
+            throw error;
+        usage("checkpoint: payload is not valid JSON");
+    }
+}
+function asOptionalString(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        usage(`checkpoint: payload ${field} must be a string`);
+    return value;
+}
+function asStringList(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        usage(`checkpoint: payload ${field} must be an array of strings`);
+    }
+    return value;
+}
+function asWorker(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        usage("checkpoint: payload worker must be an object");
+    }
+    const worker = value;
+    return {
+        id: asOptionalString(worker.id, "worker.id"),
+        skill: asOptionalString(worker.skill, "worker.skill"),
+        state: asOptionalString(worker.state, "worker.state"),
+    };
+}
+function resolveWorker(options, command, payload) {
+    const payloadWorker = asWorker(payload.worker);
+    const id = wasPassed(command, "worker") ? options.worker : payloadWorker.id;
+    const skill = wasPassed(command, "workerSkill") ? options.workerSkill : payloadWorker.skill;
+    const suppliedState = wasPassed(command, "workerState") ? options.workerState : payloadWorker.state;
+    const state = suppliedState ?? (id ? "completed" : null);
+    return { id: id ?? null, skill: skill ?? null, state };
+}
+function wasPassed(command, option) {
+    return command.getOptionValueSource(option) === "cli";
+}
+function inferredSessionId() {
+    // Deliberately do not fall back to the newest transcript under
+    // ~/.claude/projects/<munged-cwd>: concurrent sessions make its mtime
+    // unreliable and can mis-attribute a checkpoint. Env var or nothing.
+    return process.env.CLAUDE_CODE_SESSION_ID?.trim() || undefined;
+}
+function resolveSessionId(options, command, payload) {
+    if (wasPassed(command, "sessionId"))
+        return options.sessionId;
+    return asOptionalString(payload.session_id, "session_id") ?? inferredSessionId();
+}
+function mergeInput(options, command, payload) {
+    const summary = wasPassed(command, "summary")
+        ? options.summary
+        : asOptionalString(payload.summary, "summary");
+    const files = wasPassed(command, "file")
+        ? options.file
+        : asStringList(payload.files, "files");
+    const learnings = wasPassed(command, "learning")
+        ? options.learning
+        : asStringList(payload.learnings, "learnings");
+    const insights = wasPassed(command, "insight")
+        ? options.insight
+        : asStringList(payload.insights, "insights");
+    const decisions = wasPassed(command, "decision")
+        ? options.decision
+        : asStringList(payload.decisions, "decisions");
+    const nextSteps = wasPassed(command, "next")
+        ? options.next
+        : asStringList(payload.next_steps, "next_steps");
+    const tags = wasPassed(command, "tag")
+        ? options.tag
+        : asStringList(payload.tags, "tags");
+    const commits = wasPassed(command, "commit")
+        ? options.commit
+        : asStringList(payload.commits, "commits");
+    const initialCommit = wasPassed(command, "initialCommit")
+        ? options.initialCommit
+        : asOptionalString(payload.initial_commit, "initial_commit");
+    const trigger = (wasPassed(command, "trigger")
+        ? options.trigger
+        : asOptionalString(payload.trigger, "trigger")) ?? DEFAULT_TRIGGER;
+    const company = wasPassed(command, "company")
+        ? options.company
+        : asOptionalString(payload.company, "company");
+    const sessionId = resolveSessionId(options, command, payload);
+    const transcript = wasPassed(command, "transcript")
+        ? options.transcript
+        : asOptionalString(payload.transcript, "transcript");
+    return {
+        summary,
+        files,
+        learnings,
+        insights,
+        decisions,
+        nextSteps,
+        tags,
+        commits,
+        initialCommit,
+        worker: resolveWorker(options, command, payload),
+        trigger,
+        company,
+        sessionId,
+        transcript,
+    };
+}
+function formatTimestamp(date) {
+    const part = (value) => value.toString().padStart(2, "0");
+    return `${date.getUTCFullYear()}${part(date.getUTCMonth() + 1)}${part(date.getUTCDate())}-${part(date.getUTCHours())}${part(date.getUTCMinutes())}${part(date.getUTCSeconds())}`;
+}
+function summarySlug(summary) {
+    const words = summary.toLowerCase().match(/[a-z0-9]+/g)?.slice(0, 4) ?? [];
+    if (words.length === 0)
+        return "checkpoint-update";
+    if (words.length === 1)
+        words.push("update");
+    const slug = words.join("-").slice(0, 40).replace(/-+$/, "");
+    return slug || "checkpoint-update";
+}
+function titleFor(summary) {
+    const truncated = summary.length > 60 ? `${summary.slice(0, 57).trimEnd()}...` : summary;
+    return `Auto: ${truncated}`;
+}
+function readGitState(repoDir) {
+    try {
+        const read = (args) => execFileSync("git", ["-C", repoDir, ...args], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (read(["rev-parse", "--is-inside-work-tree"]) !== "true")
+            return null;
+        return {
+            branch: read(["rev-parse", "--abbrev-ref", "HEAD"]),
+            current_commit: read(["rev-parse", "--short", "HEAD"]),
+            dirty: read(["status", "--porcelain"]) !== "",
+            remote_url: (() => {
+                try {
+                    return read(["remote", "get-url", "origin"]);
+                }
+                catch {
+                    return null;
+                }
+            })(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function commitsSince(repoDir, initialCommit) {
+    try {
+        const output = execFileSync("git", ["-C", repoDir, "log", "--no-decorate", "--pretty=format:%h: %s", `${initialCommit}..HEAD`], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return output ? output.split("\n") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function gitStateFor(cwd, liveRoot, initialCommit, explicitCommits) {
+    const callerState = readGitState(cwd);
+    const state = callerState ??
+        readGitState(liveRoot) ?? {
+        branch: "unknown",
+        current_commit: "unknown",
+        dirty: false,
+        remote_url: null,
+    };
+    return {
+        ...state,
+        // Remote URLs and derived history describe the caller's repository only.
+        remote_url: callerState?.remote_url ?? null,
+        initial_commit: initialCommit ?? null,
+        commits_made: explicitCommits.length > 0
+            ? explicitCommits
+            : initialCommit && callerState
+                ? commitsSince(cwd, initialCommit)
+                : [],
+    };
+}
+/**
+ * Perform a write into HQ's OWN state tree, converting a filesystem errno into a
+ * typed, path-naming {@link HqStateWriteError} (the boundary prints that and does
+ * NOT capture it — the fault is the user's machine, not an hq bug) while leaving
+ * any NON-errno failure — a genuine defect — to propagate unchanged and stay
+ * reportable. Scoped by the caller to the checkpoint state paths this command
+ * derives. The checkpoint still FAILS (exits non-zero) on such an error; only
+ * the classification and the message change (HQ-CLI-19, Sentry 7702730566).
+ */
+function writeHqState(targetPath, operation, perform) {
+    try {
+        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
+        ? sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "unknown"
+        : "unknown";
+    const timestamp = Math.floor(Date.now() / 1000).toString();
+    const stampPaths = [
+        path.join(stateDir, "checkpoint-cli-last"),
+        path.join(stateDir, `checkpoint-cli-last-${sessionKey}`),
+    ];
+    for (const stampPath of stampPaths) {
+        writeHqState(stampPath, "write its checkpoint state file", () => platform === "win32"
+            ? writeCheckpointStampAtomically(stampPath, timestamp, fsImpl, waitForRetry)
+            : fsImpl.writeFileSync(stampPath, timestamp));
+    }
+    return stampPaths;
+}
+/**
+ * Codex Stop-gate rollout scope: every HQ user on the operator domain, rather
+ * than the single account that dogfooded it first. Eligibility is decided on
+ * the email domain alone — a candidate must have exactly one `@` and the part
+ * after it must equal this domain, so lookalikes never pass (`xgetindigo.ai`,
+ * `getindigo.ai.evil.test`, `a@b@getindigo.ai`).
+ */
+const CODEX_CHECKPOINT_DOMAIN = "getindigo.ai";
+function hasCodexCheckpointDomain(candidate) {
+    if (typeof candidate !== "string")
+        return false;
+    const parts = candidate.trim().toLowerCase().split("@");
+    return parts.length === 2 && parts[0].length > 0 && parts[1] === CODEX_CHECKPOINT_DOMAIN;
+}
+function checkpointGateRuntime() {
+    const runtime = (process.env.HQ_CHECKPOINT_RUNTIME ?? "claude").trim().toLowerCase();
+    if (runtime === "claude" || runtime === "codex")
+        return runtime;
+    return "other";
+}
+async 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")
+        return false;
+    try {
+        const tokenPath = path.join(homedir(), ".hq", "cognito-tokens.json");
+        const tokens = JSON.parse(fs.readFileSync(tokenPath, "utf8"));
+        if (typeof tokens.idToken !== "string")
+            return false;
+        const { peekIdToken } = await import("../utils/id-token.js");
+        const claims = peekIdToken(tokens.idToken);
+        const candidateEmails = [claims.email, claims["custom:delegatedEmail"]];
+        return candidateEmails.some(hasCodexCheckpointDomain);
+    }
+    catch {
+        return false;
+    }
+}
+async function writeGateVerdict(liveRoot) {
+    const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
+    fs.mkdirSync(stateDir, { recursive: true });
+    const runtime = checkpointGateRuntime();
+    const eligible = await gateEligibility(runtime, liveRoot);
+    fs.writeFileSync(path.join(stateDir, `checkpoint-gate-eligible-${runtime}`), eligible ? "1" : "0");
+    printResult(eligible ? "eligible" : "ineligible");
+}
+function backendOnPath(name) {
+    const pathValue = process.env.PATH;
+    if (!pathValue)
+        return false;
+    return pathValue.split(path.delimiter).some((directory) => {
+        if (!directory)
+            return false;
+        try {
+            fs.accessSync(path.join(directory, name), fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * An installed binary is not necessarily a working one: a partial install, a
+ * broken wrapper or a missing runtime all leave an executable on PATH that
+ * fails the moment it is asked to do anything. Ask it for its version — cheap,
+ * bounded, and enough to reject a backend before handing it a checkpoint.
+ */
+function backendResponds(name) {
+    try {
+        execFileSync(name, ["--version"], {
+            timeout: BACKEND_PROBE_TIMEOUT_MS,
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Backends whose most recent run died without producing a report.
+ *
+ * A version probe cannot catch a backend that starts cleanly and then fails at
+ * runtime — an expired login, a sandbox it cannot write in, a model it is not
+ * entitled to. The evidence for that is a finished run directory with no
+ * report.md in it, so prefer a different backend for the next checkpoint. Only
+ * the newest run per backend counts: one that has since succeeded is healthy.
+ */
+function crashedBackends(siblingRoot) {
+    const crashed = new Set();
+    let runDirs;
+    try {
+        runDirs = fs
+            .readdirSync(siblingRoot)
+            .filter((entry) => entry !== "pending.jsonl")
+            .sort()
+            .reverse();
+    }
+    catch {
+        return crashed;
+    }
+    const seen = new Set();
+    for (const runDir of runDirs) {
+        const absolute = path.join(siblingRoot, runDir);
+        let backend;
+        try {
+            const payload = JSON.parse(fs.readFileSync(path.join(absolute, "payload.json"), "utf8"));
+            backend = payload.backend;
+        }
+        catch {
+            continue;
+        }
+        if (typeof backend !== "string" || !backend || seen.has(backend))
+            continue;
+        seen.add(backend);
+        if (fs.existsSync(path.join(absolute, "report.md")))
+            continue;
+        // A missing report only means a crash once the process itself is gone.
+        let pid = Number.NaN;
+        try {
+            pid = Number.parseInt(fs.readFileSync(path.join(absolute, "sibling.pid"), "utf8").trim(), 10);
+        }
+        catch {
+            // A run that never recorded a PID cannot still be running.
+        }
+        if (Number.isSafeInteger(pid) && pid > 0 && processAlive(pid))
+            continue;
+        crashed.add(backend);
+    }
+    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. `preferGrok` (the company's grok-backend flag) puts grok
+ * ahead of that order and leaves the rest as the fallback.
+ */
+export function autoBackendPreference(preferGrok = false) {
+    const caller = callerBackend();
+    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 async function companyPrefersGrok(liveRoot, companySlug) {
+    const [{ readBackendPreference }, { resolveOntologyCompany }] = await Promise.all([
+        import("../lib/checkpoint-ontology/plan.js"),
+        import("../lib/checkpoint-ontology/company.js"),
+    ]);
+    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;
+}
+/** 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;
+}
+async 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(await companyPrefersGrok(liveRoot, company)).filter((name) => backendOnPath(name) && backendResponds(name));
+    if (available.length === 0)
+        return "none";
+    const crashed = crashedBackends(path.join(liveRoot, "workspace", "checkpoints", "sibling"));
+    // If every candidate failed last time, still try the preferred one: a stale
+    // 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":
+            return [
+                "-p",
+                prompt,
+                "--model",
+                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 danger-full-access` and grok from
+                // `--always-approve --sandbox workspace`. Hooks still fire natively —
+                // this only removes the interactive approval gate, not the hook chain.
+                "--permission-mode",
+                "bypassPermissions",
+            ];
+        case "grok":
+            return [
+                "-p",
+                prompt,
+                "-m",
+                GROK_SIBLING_MODEL,
+                "--reasoning-effort",
+                GROK_SIBLING_EFFORT,
+                // `acceptEdits` auto-approves edits only. A terminal command — the git
+                // scan, the journal helper — then hits an approval gate with no human
+                // attached, and grok cancels the whole run: `stopReason: cancelled,
+                // cancellationCategory: PermissionCancelled`. Unattended approval plus
+                // a sandbox is the same posture codex gets from `-s danger-full-access`.
+                "--always-approve",
+                "--sandbox",
+                "workspace",
+                "--max-turns",
+                GROK_SIBLING_MAX_TURNS,
+            ];
+        case "codex":
+            return [
+                "exec",
+                "--skip-git-repo-check",
+                // danger-full-access, NOT workspace-write. `-s workspace-write` force-
+                // enables Codex's restrictive sandbox, which denies the temp/cache/socket
+                // writes the maintenance sibling needs on macOS (git/Xcode cache, zsh/asdf
+                // heredocs) and cannot even initialize bubblewrap on some Linux hosts
+                // (`bwrap: loopback: Failed RTM_NEWADDR`) — HQ harness finding 2.3, which
+                // wedged the sibling before it wrote any report. HQ's safety boundary is
+                // its hooks, which still fire here via --dangerously-bypass-hook-trust;
+                // the sandbox is not what guards the HQ root.
+                "-s",
+                "danger-full-access",
+                "--dangerously-bypass-hook-trust",
+                "-m",
+                CODEX_SIBLING_MODEL,
+                "-c",
+                `model_reasoning_effort=${CODEX_SIBLING_REASONING_EFFORT}`,
+                prompt,
+            ];
+    }
+}
+function siblingPayload(input, threadPath, backend) {
+    return {
+        backend,
+        summary: input.summary ?? "",
+        files: input.files,
+        learnings: input.learnings,
+        insights: input.insights,
+        decisions: input.decisions,
+        next_steps: input.nextSteps,
+        tags: input.tags,
+        trigger: input.trigger,
+        company: input.company ?? null,
+        session_id: input.sessionId ?? null,
+        transcript: input.transcript ?? null,
+        worker: input.worker,
+        thread_path: threadPath,
+        pending_payloads: [],
+    };
+}
+/**
+ * PID of a sibling that is genuinely still working, or null when the lock is
+ * stale and this process should take it over.
+ *
+ * A lock is stale when the PID is gone, when it cannot be signalled, or when
+ * the run has outlived {@link SIBLING_LOCK_TTL_MS}. Siblings are spawned as
+ * this user, so an EPERM means the PID was recycled by somebody else's
+ * process — not that our sibling is alive. Treating an unsignalable PID as
+ * alive wedges the queue permanently: on 2026-08-03 a lock landed on a
+ * root-owned kernel thread and every checkpoint for the next two days queued
+ * behind a sibling that had never existed.
+ */
+function existingSiblingPid(lockPath, now) {
+    let raw;
+    let writtenAtMs;
+    try {
+        raw = fs.readFileSync(lockPath, "utf8").trim();
+        writtenAtMs = fs.statSync(lockPath).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+    const pid = Number.parseInt(raw, 10);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    if (now - writtenAtMs >= SIBLING_LOCK_TTL_MS)
+        return null;
+    try {
+        process.kill(pid, 0);
+        return pid;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Queue a payload for the next sibling, keeping only the newest entries. An
+ * unbounded queue hides a wedged sibling instead of surfacing it. Returns the
+ * resulting queue depth so the caller can report it.
+ */
+function appendPending(pendingPath, payload) {
+    fs.appendFileSync(pendingPath, `${JSON.stringify(payload)}\n`);
+    const lines = fs
+        .readFileSync(pendingPath, "utf8")
+        .split("\n")
+        .filter((line) => line.trim());
+    if (lines.length <= MAX_PENDING_PAYLOADS)
+        return lines.length;
+    // Best-effort trim: this rewrite can race a concurrent append, but it only
+    // runs once the queue is already over cap, where newest-wins is the point.
+    const kept = lines.slice(-MAX_PENDING_PAYLOADS);
+    fs.writeFileSync(pendingPath, `${kept.join("\n")}\n`);
+    return kept.length;
+}
+/**
+ * Take ownership of the queued payloads by renaming the queue aside.
+ *
+ * The queue must never be claimed by read-then-truncate: a payload appended
+ * between the read and the truncate is discarded unread, and the checkpoint it
+ * describes is never enriched. Renaming is atomic, so this run receives exactly
+ * the file that existed at the moment of the claim while concurrent callers go
+ * on appending to a fresh queue. The claimed file is left in the run directory
+ * as an audit trail and as a recovery point if this sibling dies.
+ */
+function claimPending(pendingPath, claimPath) {
+    try {
+        fs.renameSync(pendingPath, claimPath);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const entries = [];
+    for (const line of fs.readFileSync(claimPath, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            // A partial line must not prevent this run from processing the valid
+            // queued payloads around it.
+        }
+    }
+    return entries;
+}
+async function startSibling(liveRoot, input, threadPath, backend) {
+    const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
+    const siblingRoot = path.join(liveRoot, "workspace", "checkpoints", "sibling");
+    const pendingPath = path.join(siblingRoot, "pending.jsonl");
+    const lockPath = path.join(stateDir, "checkpoint-sibling.lock");
+    const payload = siblingPayload(input, threadPath, backend);
+    const activePid = existingSiblingPid(lockPath, Date.now());
+    fs.mkdirSync(siblingRoot, { recursive: true });
+    if (activePid !== null) {
+        const depth = appendPending(pendingPath, payload);
+        try {
+            const { recordQueuedTouches } = await import("../lib/checkpoint-ontology/queued-touches.js");
+            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 {
+            const { oldestQueuedCompany } = await import("../lib/checkpoint-ontology/queued-touches.js");
+            queued = oldestQueuedCompany(liveRoot);
+        }
+        catch {
+            queued = null;
+        }
+        if (queued) {
+            payload.ontology_company = queued;
+            try {
+                const { markBorrowed } = await import("../lib/checkpoint-ontology/queued-touches.js");
+                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, {
+        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");
+    const args = siblingArgs(backend, prompt);
+    let child;
+    try {
+        child = spawn(backend, args, {
+            detached: true,
+            windowsHide: true,
+            cwd: liveRoot,
+            stdio: ["ignore", logFd, logFd],
+            env: siblingEnv(process.env, backend),
+        });
+    }
+    finally {
+        fs.closeSync(logFd);
+    }
+    child.unref();
+    if (!child.pid)
+        throw new Error("checkpoint: sibling did not return a PID");
+    fs.writeFileSync(lockPath, String(child.pid));
+    // Recorded per run so a later checkpoint can tell "died without a report"
+    // apart from "still working" without consulting the shared lock.
+    fs.writeFileSync(path.join(runDir, "sibling.pid"), String(child.pid));
+    printResult(`checkpoint: sibling started (${backend}, pid ${child.pid})`);
+}
+function hasGateProbeConflict(options, command) {
+    return [
+        "summary",
+        "file",
+        "learning",
+        "insight",
+        "decision",
+        "next",
+        "tag",
+        "commit",
+        "initialCommit",
+        "worker",
+        "workerSkill",
+        "workerState",
+        "trigger",
+        "company",
+        "sessionId",
+        "transcript",
+        "payload",
+        "idle",
+        "agent",
+        "backend",
+        "dryRun",
+    ].some((option) => wasPassed(command, option));
+}
+function printDryRun(plan) {
+    printResult(JSON.stringify(plan, null, 2));
+}
+async function runCheckpoint(options, command, group, preResolvedHqRoot) {
+    const hqRoot = options.hqRoot ?? group.opts().hqRoot;
+    const liveRoot = preResolvedHqRoot ?? (await import("../utils/hq-roots.js")).resolveLiveRoot({ hqRoot });
+    if (options.gateProbe) {
+        if (hasGateProbeConflict(options, command)) {
+            usage("checkpoint: --gate-probe cannot be combined with checkpoint options");
+        }
+        await writeGateVerdict(liveRoot);
+        return;
+    }
+    if (options.idle) {
+        if (options.dryRun) {
+            printDryRun({ live_root: liveRoot, idle: true, stamps: [], thread: null, sibling: null });
+            return;
+        }
+        writeStamps(liveRoot, resolveSessionId(options, command, readPayload(options.payload)));
+        printResult("checkpoint: idle (nothing to record)");
+        // An idle turn persisted nothing, but a read-only turn can still have
+        // produced substantive findings the user has not been told about. The
+        // conditional idle variant matches the Stop gate, which exempts an
+        // idle-only turn from the reply demand.
+        printResult(CHECKPOINT_IDLE_REPLY_REMINDER);
+        return;
+    }
+    const payload = readPayload(options.payload);
+    const input = mergeInput(options, command, payload);
+    if (!input.summary?.trim()) {
+        usage("checkpoint: --summary is required unless --idle or --gate-probe is used");
+    }
+    // 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" : await 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`);
+    const relativeThreadPath = path.relative(liveRoot, threadPath);
+    const git = gitStateFor(process.cwd(), liveRoot, input.initialCommit, input.commits);
+    const stampPaths = [
+        path.join(liveRoot, "workspace", "orchestrator", "hook-state", "checkpoint-cli-last"),
+        path.join(liveRoot, "workspace", "orchestrator", "hook-state", `checkpoint-cli-last-${input.sessionId ? input.sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "unknown" : "unknown"}`),
+    ];
+    if (options.dryRun) {
+        printDryRun({
+            live_root: liveRoot,
+            idle: false,
+            thread: relativeThreadPath,
+            checkpoint: {
+                git,
+                insights: input.insights,
+                worker: input.worker,
+            },
+            stamps: stampPaths.map((stampPath) => path.relative(liveRoot, stampPath)),
+            sibling: siblingOptOut ? null : { backend },
+        });
+        return;
+    }
+    const thread = {
+        thread_id: threadId,
+        version: 1,
+        type: "auto-checkpoint",
+        created_at: now.toISOString(),
+        updated_at: now.toISOString(),
+        workspace_root: liveRoot,
+        cwd: process.cwd(),
+        git,
+        conversation_summary: input.summary,
+        files_touched: input.files,
+        next_steps: input.nextSteps,
+        learnings: input.learnings,
+        insights: input.insights,
+        decisions: input.decisions,
+        worker: input.worker,
+        session_id: input.sessionId ?? null,
+        metadata: {
+            title: titleFor(input.summary),
+            tags: ["auto-checkpoint", ...input.tags],
+            trigger: input.trigger,
+        },
+    };
+    writeHqState(path.dirname(threadPath), "create the checkpoint thread directory", () => fs.mkdirSync(path.dirname(threadPath), { recursive: true }));
+    writeHqState(threadPath, "write the checkpoint thread file", () => fs.writeFileSync(threadPath, `${JSON.stringify(thread, null, 2)}\n`));
+    writeStamps(liveRoot, input.sessionId);
+    printResult(`checkpoint: ${relativeThreadPath}`);
+    // finally: the thread is already written at this point, so the agent must
+    // get the reminder even when sibling startup throws (e.g. an explicitly
+    // requested backend that is not installed).
+    try {
+        if (options.agent !== false) {
+            if (siblingOptOut) {
+                printResult(`checkpoint: sibling disabled (${SIBLING_SETTING})`);
+            }
+            else if (backend === "none") {
+                printResult("checkpoint: sibling disabled (backend none)");
+            }
+            else {
+                await startSibling(liveRoot, input, threadPath, backend);
+            }
+        }
+    }
+    finally {
+        printResult(CHECKPOINT_REPLY_REMINDER);
+    }
+}
+function reportUsage(error) {
+    printError("Usage: hq core checkpoint --summary <text> [options]");
+    printError(error.message);
+    process.exit(2);
+}
+/** Attach the native checkpoint command to the hidden `hq core` group. */
+export function registerCoreCheckpointCommand(core, preResolvedHqRoot) {
+    const checkpoint = core
+        .command("checkpoint")
+        .description("Record an end-of-turn checkpoint and start HQ maintenance")
+        .option("--summary <text>", "1–2 sentence outcome summary")
+        .option("--file <path>", "file touched this turn", collect, [])
+        .option("--learning <text>", "reusable lesson", collect, [])
+        .option("--insight <text>", "session insight", collect, [])
+        .option("--decision <text>", "decision made", collect, [])
+        .option("--next <text>", "remaining next step", collect, [])
+        .option("--tag <tag>", "checkpoint tag", collect, [])
+        .option("--commit <entry>", "session commit (<hash>: <message>)", collect, [])
+        .option("--initial-commit <sha>", "commit at the start of this session")
+        .option("--worker <id>", "active worker identifier")
+        .option("--worker-skill <name>", "active worker skill")
+        .option("--worker-state <state>", "active worker state")
+        .option("--trigger <name>", "checkpoint trigger", DEFAULT_TRIGGER)
+        .option("--company <slug>", "active company scope")
+        .option("--session-id <id>", "caller session id (default: $CLAUDE_CODE_SESSION_ID when set)")
+        .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 (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")
+        .option("--dry-run", "print the planned checkpoint without writing")
+        .action(async (options, command) => {
+        try {
+            await runCheckpoint(options, command, core, preResolvedHqRoot);
+        }
+        catch (error) {
+            if (error instanceof CheckpointUsageError)
+                reportUsage(error);
+            throw error;
+        }
+    });
+    describeCoreCommand(checkpoint, { execution: "native", root: "live" });
+}
+//# sourceMappingURL=core-checkpoint-native.js.map