@indigoai-us/hq-cli 5.80.0 → 5.82.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [5.82.0]
+
+### Added
+
+- `hq core checkpoint` reaches full `/checkpoint`-skill parity: new
+  `--insight`, `--commit`, `--initial-commit`, and `--worker*` options
+  (payload equivalents included), automatic caller-repo `remote_url`
+  capture, `commits_made` derivation from `--initial-commit`, and a
+  sibling prompt that executes the complete checkpoint flow — in-place
+  thread upgrade/rename, knowledge-repo scan, journal close, legacy
+  checkpoint, thread index refresh, document-release best-effort,
+  transcript-derived learnings — under explicit allow-list write
+  bounds. (#289)
+
+## [5.81.0]
+
+### Added
+
+- Hidden `hq core checkpoint`: end-of-turn checkpoint + detached background
+  maintenance sibling (codex-first, pinned `gpt-5.6-terra` @ high effort;
+  claude fallback pinned `claude-opus-5` @ medium). Sibling distills
+  learnings into policies/knowledge under a single-flight lock;
+  `--gate-probe` caches Stop-gate eligibility (operator rollout domain,
+  `HQ_CHECKPOINT_GATE`/`HQ_CHECKPOINT_GATE_DOMAINS` overrides); session id
+  inferred from `CLAUDE_CODE_SESSION_ID` when omitted. (#286)
+
 ## [5.79.0]
 
 ### Added

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

@@ -0,0 +1,18 @@
+/**
+ * `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 { Command } from "commander";
+/**
+ * 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   distill a non-duplicate policy file under personal/policies/ or, only when\n   the payload names a company and the rule is company-specific,\n   companies/<company>/policies/, following\n   core/knowledge/public/hq-core/policies-spec.md. Store up to two explicit or\n   transcript-derived insights per core/knowledge/public/hq-core/insights-spec.md\n   when present, otherwise workspace/insights/. Durable facts (not rules) may\n   go under personal/knowledge/ or companies/<company>/knowledge/ only.\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. If\n   workspace/checkpoints/sibling/pending.jsonl is non-empty when you finish,\n   process those payloads with this same flow, then truncate the file.\n";
+export declare function renderSiblingPrompt(runDir: string, payloadPath: string): string;
+/** Attach the native checkpoint command to the hidden `hq core` group. */
+export declare function registerCoreCheckpointCommand(core: Command): void;
+//# sourceMappingURL=core-checkpoint.d.ts.map

package/dist/commands/core-checkpoint.js

@@ -0,0 +1,654 @@
+/**
+ * `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 { 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";
+const DEFAULT_TRIGGER = "stop-gate";
+const BACKENDS = new Set(["auto", "claude", "codex", "none"]);
+// Pinned by operator directive 2026-07-31; 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 CLAUDE_SIBLING_EFFORT = "medium";
+class CheckpointUsageError extends Error {
+}
+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.
+ */
+export 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,
+   distill a non-duplicate policy file under personal/policies/ or, only when
+   the payload names a company and the rule is company-specific,
+   companies/<company>/policies/, following
+   core/knowledge/public/hq-core/policies-spec.md. Store up to two explicit or
+   transcript-derived insights per core/knowledge/public/hq-core/insights-spec.md
+   when present, otherwise workspace/insights/. Durable facts (not rules) may
+   go under personal/knowledge/ or companies/<company>/knowledge/ only.
+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.
+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. If
+   workspace/checkpoints/sibling/pending.jsonl is non-empty when you finish,
+   process those payloads with this same flow, then truncate the file.
+`;
+export function renderSiblingPrompt(runDir, payloadPath) {
+    return SIBLING_PROMPT_TEMPLATE
+        .replaceAll("<runDir>", () => runDir)
+        .replaceAll("<payloadPath>", () => payloadPath);
+}
+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)
+                : [],
+    };
+}
+function writeStamps(liveRoot, sessionId) {
+    const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
+    fs.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)
+        fs.writeFileSync(stampPath, timestamp);
+    return stampPaths;
+}
+function gateEligibility() {
+    const forced = process.env.HQ_CHECKPOINT_GATE;
+    if (forced === "0")
+        return false;
+    if (forced === "1")
+        return true;
+    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 email = peekIdToken(tokens.idToken).email;
+        if (typeof email !== "string")
+            return false;
+        const domain = email.split("@").at(-1)?.toLowerCase();
+        if (!domain)
+            return false;
+        const configured = (process.env.HQ_CHECKPOINT_GATE_DOMAINS ?? "")
+            .split(",")
+            .map((candidate) => candidate.trim().toLowerCase())
+            .filter(Boolean);
+        return domain === "getindigo.ai" || configured.includes(domain);
+    }
+    catch {
+        return false;
+    }
+}
+function writeGateVerdict(liveRoot) {
+    const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
+    fs.mkdirSync(stateDir, { recursive: true });
+    const eligible = gateEligibility();
+    fs.writeFileSync(path.join(stateDir, "checkpoint-gate-eligible"), 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;
+        }
+    });
+}
+function resolveBackend(requested) {
+    const value = requested ?? "auto";
+    if (!BACKENDS.has(value))
+        usage(`checkpoint: unknown backend: ${value}`);
+    if (value === "auto") {
+        if (backendOnPath("codex"))
+            return "codex";
+        if (backendOnPath("claude"))
+            return "claude";
+        return "none";
+    }
+    return value;
+}
+function siblingPayload(input, threadPath) {
+    return {
+        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: [],
+    };
+}
+function existingSiblingPid(lockPath) {
+    try {
+        const pid = Number.parseInt(fs.readFileSync(lockPath, "utf8").trim(), 10);
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            return null;
+        process.kill(pid, 0);
+        return pid;
+    }
+    catch (error) {
+        if (error?.code === "EPERM") {
+            try {
+                return Number.parseInt(fs.readFileSync(lockPath, "utf8").trim(), 10);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+}
+function drainPending(pendingPath) {
+    if (!fs.existsSync(pendingPath))
+        return [];
+    const entries = [];
+    for (const line of fs.readFileSync(pendingPath, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            // A partial line must not prevent a future sibling from processing the
+            // valid queued payloads around it.
+        }
+    }
+    fs.writeFileSync(pendingPath, "");
+    return entries;
+}
+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);
+    const activePid = existingSiblingPid(lockPath);
+    fs.mkdirSync(siblingRoot, { recursive: true });
+    if (activePid !== null) {
+        fs.appendFileSync(pendingPath, `${JSON.stringify(payload)}\n`);
+        printResult("checkpoint: sibling busy — payload queued");
+        return;
+    }
+    const runDir = path.join(siblingRoot, `${formatTimestamp(new Date())}-${summarySlug(input.summary ?? "checkpoint")}`);
+    fs.mkdirSync(runDir, { recursive: true });
+    payload.pending_payloads = drainPending(pendingPath);
+    const payloadPath = path.join(runDir, "payload.json");
+    fs.writeFileSync(payloadPath, `${JSON.stringify(payload, null, 2)}\n`);
+    const prompt = renderSiblingPrompt(runDir, payloadPath);
+    fs.writeFileSync(path.join(runDir, "prompt.md"), prompt);
+    const logPath = path.join(runDir, "run.log");
+    const logFd = fs.openSync(logPath, "a");
+    const args = backend === "claude"
+        ? [
+            "-p",
+            prompt,
+            "--model",
+            CLAUDE_SIBLING_MODEL,
+            "--effort",
+            CLAUDE_SIBLING_EFFORT,
+            "--permission-mode",
+            "acceptEdits",
+        ]
+        : [
+            "exec",
+            "--skip-git-repo-check",
+            "-s",
+            "workspace-write",
+            "--dangerously-bypass-hook-trust",
+            "-m",
+            CODEX_SIBLING_MODEL,
+            "-c",
+            `model_reasoning_effort=${CODEX_SIBLING_REASONING_EFFORT}`,
+            prompt,
+        ];
+    let child;
+    try {
+        child = spawn(backend, args, {
+            detached: 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 } : {}),
+            },
+        });
+    }
+    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));
+    printResult(`checkpoint: sibling started (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));
+}
+function runCheckpoint(options, command, group) {
+    const hqRoot = options.hqRoot ?? group.opts().hqRoot;
+    const liveRoot = resolveLiveRoot({ hqRoot });
+    if (options.gateProbe) {
+        if (hasGateProbeConflict(options, command)) {
+            usage("checkpoint: --gate-probe cannot be combined with checkpoint options");
+        }
+        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)");
+        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");
+    }
+    const backend = resolveBackend(options.backend);
+    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: options.agent === false ? 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,
+        },
+    };
+    fs.mkdirSync(path.dirname(threadPath), { recursive: true });
+    fs.writeFileSync(threadPath, `${JSON.stringify(thread, null, 2)}\n`);
+    writeStamps(liveRoot, input.sessionId);
+    printResult(`checkpoint: ${relativeThreadPath}`);
+    if (options.agent === false)
+        return;
+    if (backend === "none") {
+        printResult("checkpoint: sibling disabled (backend none)");
+        return;
+    }
+    startSibling(liveRoot, input, threadPath, backend);
+}
+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) {
+    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")
+        .option("--backend <auto|claude|codex|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((options, command) => {
+        try {
+            runCheckpoint(options, command, core);
+        }
+        catch (error) {
+            if (error instanceof CheckpointUsageError)
+                reportUsage(error);
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=core-checkpoint.js.map

package/dist/commands/core.js

@@ -29,6 +29,7 @@
  * `ScaffoldRoot`.
  */
 import { Option } from "commander";
+import { registerCoreCheckpointCommand } from "./core-checkpoint.js";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { runBundledScript } from "../utils/run-bundled-script.js";
 /**
@@ -233,6 +234,9 @@ export function registerCoreCommands(program) {
         // collide with a wrapped script's own flags — everything after the
         // subcommand name is passed through untouched.
         .addOption(new Option("--hq-root <path>", "HQ installation to operate on (live-root commands)").hideHelp());
+    // This group primarily hosts manifest-driven bundled assets, but it also
+    // hosts native TypeScript plumbing when a scaffold contract needs it.
+    registerCoreCheckpointCommand(core);
     const runCommand = (entry, args = [], cmd, target) => {
         const scope = core.opts();
         // `cmd.args` is the authoritative operand list: with

package/dist/commands/whoami.js

@@ -3,24 +3,19 @@
  */
 import chalk from 'chalk';
 import { loadCachedTokens, isExpiring, isMachineIdentity, loadMachineCreds, } from '@indigoai-us/hq-cloud';
+import { peekIdToken as decodeIdToken } from "../utils/id-token.js";
 function peekIdToken(idToken) {
-    try {
-        const payload = idToken.split('.')[1];
-        if (!payload)
-            return {};
-        const pad = payload.length % 4 === 0 ? '' : '='.repeat(4 - (payload.length % 4));
-        const normalized = payload.replace(/-/g, '+').replace(/_/g, '/') + pad;
-        const decoded = JSON.parse(Buffer.from(normalized, 'base64').toString('utf-8'));
-        return {
-            email: decoded.email,
-            sub: decoded.sub,
-            entityType: decoded['custom:entityType'],
-            entityUid: decoded['custom:entityUid'],
-        };
-    }
-    catch {
-        return {};
-    }
+    const decoded = decodeIdToken(idToken);
+    return {
+        email: typeof decoded.email === "string" ? decoded.email : undefined,
+        sub: typeof decoded.sub === "string" ? decoded.sub : undefined,
+        entityType: typeof decoded["custom:entityType"] === "string"
+            ? decoded["custom:entityType"]
+            : undefined,
+        entityUid: typeof decoded["custom:entityUid"] === "string"
+            ? decoded["custom:entityUid"]
+            : undefined,
+    };
 }
 export function registerWhoamiCommand(program) {
     program

package/dist/utils/id-token.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Decode the payload of a locally cached JWT without verifying its signature.
+ *
+ * Callers use this only for data already trusted locally (display labels and
+ * local eligibility checks), never to authorize a remote request.
+ */
+export declare function peekIdToken(idToken: string): Record<string, unknown>;
+//# sourceMappingURL=id-token.d.ts.map

package/dist/utils/id-token.js

@@ -0,0 +1,23 @@
+/**
+ * Decode the payload of a locally cached JWT without verifying its signature.
+ *
+ * Callers use this only for data already trusted locally (display labels and
+ * local eligibility checks), never to authorize a remote request.
+ */
+export function peekIdToken(idToken) {
+    try {
+        const payload = idToken.split(".")[1];
+        if (!payload)
+            return {};
+        const pad = payload.length % 4 === 0 ? "" : "=".repeat(4 - (payload.length % 4));
+        const normalized = payload.replace(/-/g, "+").replace(/_/g, "/") + pad;
+        const decoded = JSON.parse(Buffer.from(normalized, "base64").toString("utf-8"));
+        return decoded && typeof decoded === "object" && !Array.isArray(decoded)
+            ? decoded
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=id-token.js.map

package/dist/utils/pack-contributions.js

@@ -166,6 +166,20 @@ function samePayloadFile(a, b) {
         return false;
     }
 }
+/** True when the symlink target resolves to the declared payload (dir or file inside it). */
+function pointsAtDeclaredPayload(link, resolvedTarget) {
+    if (samePayloadFile(link.src, resolvedTarget))
+        return true;
+    try {
+        const root = canonicalPath(link.src);
+        const resolved = canonicalPath(resolvedTarget);
+        const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+        return resolved === root || resolved.startsWith(prefix);
+    }
+    catch {
+        return false;
+    }
+}
 /** Classify a host path against the link that should own it. */
 export function linkStatus(link, packDir) {
     let st;
@@ -190,7 +204,7 @@ export function linkStatus(link, packDir) {
     // aliases classify as ours; optionally accept stale targets that still resolve
     // inside this pack's directory.
     const resolvedTarget = path.resolve(path.dirname(link.dst), target);
-    if (samePayloadFile(link.src, resolvedTarget)) {
+    if (pointsAtDeclaredPayload(link, resolvedTarget)) {
         return fs.existsSync(link.src) ? 'live' : 'broken';
     }
     if (packDir !== undefined && targetUnderPackDir(packDir, resolvedTarget)) {

package/package.json

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