@indigoai-us/hq-cli 5.79.0 → 5.81.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [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/cloud.d.ts

@@ -22,6 +22,11 @@ import { type BannerLevel } from "../lib/narrow-hint-banner.js";
  * succeed when files were dropped" guarantee unit-testable.
  */
 export declare function scopeExcludedWarning(count: number): string | null;
+/**
+ * Optional detail line listing the effective write prefixes when a push
+ * dropped files — helps debug ACL vs scope-excluded mismatches (feedback_7e9c535e).
+ */
+export declare function scopeExcludedPrefixDetail(prefixSet: readonly string[] | undefined): string | null;
 /**
  * Bound foreground waits for a watcher/manual sync that currently owns the
  * per-root operation lock. The cloud engine reads this environment value on
@@ -159,6 +164,8 @@ export interface ShareCallOptions {
     skipUnchanged?: boolean;
     propagateDeletes?: boolean;
     propagateDeletePolicy?: "owned-only" | "currency-gated" | "all";
+    /** DEV-1768 push parity: filter upload plan to granted ACL prefixes. */
+    prefixSet?: PullScope["prefixSet"];
 }
 export interface ShareCallResult {
     filesUploaded: number;
@@ -172,6 +179,8 @@ export interface ShareCallResult {
 export interface PushAllDeps {
     vaultClient: PullAllVaultClient;
     share: (options: ShareCallOptions) => Promise<ShareCallResult>;
+    /** DEV-1768: resolve membership push scope (same as pull). */
+    resolveScope?: (companyUid: string, slug: string) => Promise<PullScope>;
 }
 export interface PushAllOptions {
     hqRoot: string;

package/dist/commands/cloud.js

@@ -32,6 +32,16 @@ export function scopeExcludedWarning(count) {
         `They were skipped, not synced. Re-run with --json to list them, or ` +
         `ask an admin to grant you write on those paths.`);
 }
+/**
+ * Optional detail line listing the effective write prefixes when a push
+ * dropped files — helps debug ACL vs scope-excluded mismatches (feedback_7e9c535e).
+ */
+export function scopeExcludedPrefixDetail(prefixSet) {
+    if (!prefixSet || prefixSet.length === 0) {
+        return "  Granted write prefixes: (none — shared-mode membership with no explicit grants)";
+    }
+    return `  Granted write prefixes: ${prefixSet.join(", ")}`;
+}
 /**
  * Resolve the `propagateDeletePolicy` for share() calls.
  *
@@ -268,6 +278,7 @@ export async function pushAll(options, deps) {
         }
         plan.push({
             slug,
+            companyUid: m.companyUid,
             shareOptions: {
                 company: m.companyUid,
                 hqRoot: options.hqRoot,
@@ -284,6 +295,7 @@ export async function pushAll(options, deps) {
     if (personal) {
         plan.push({
             slug: "personal",
+            companyUid: personal.uid,
             shareOptions: {
                 company: personal.uid,
                 hqRoot: options.hqRoot,
@@ -309,6 +321,17 @@ export async function pushAll(options, deps) {
     };
     for (const entry of plan) {
         result.attempted += 1;
+        if (entry.slug !== "personal" && deps.resolveScope) {
+            try {
+                const scope = await deps.resolveScope(entry.companyUid, entry.slug);
+                if (scope.prefixSet !== undefined) {
+                    entry.shareOptions.prefixSet = scope.prefixSet;
+                }
+            }
+            catch {
+                // Degrade to no explicit scope filter — share() treats undefined as full access.
+            }
+        }
         try {
             const r = await deps.share(entry.shareOptions);
             result.filesUploaded += r.filesUploaded;
@@ -582,6 +605,8 @@ export function registerCloudCommands(program) {
             //   2. default: vend via cached Cognito session (the human CLI path).
             let entityContext;
             let vaultConfig;
+            /** Vault API config for membership/grant scope lookups. Set even on the pre-vended `--creds-from-stdin` path — share() accepts entityContext OR vaultConfig, not both. */
+            let scopeVaultConfig;
             if (options.credsFromStdin) {
                 if (process.stdin.isTTY) {
                     throw new Error("--creds-from-stdin requires JSON on stdin, but stdin is a " +
@@ -595,17 +620,22 @@ export function registerCloudCommands(program) {
                 catch (e) {
                     throw new Error(`--creds-from-stdin: failed to parse stdin as JSON: ${e instanceof Error ? e.message : String(e)}`);
                 }
+                // Upload creds are pre-vended in entityContext, but prefix filtering
+                // still needs vault-service membership/grant resolution.
+                const accessToken = await ensureCognitoToken();
+                scopeVaultConfig = buildVaultConfig(accessToken);
             }
             else {
                 const accessToken = await ensureCognitoToken();
                 vaultConfig = buildVaultConfig(accessToken);
+                scopeVaultConfig = vaultConfig;
             }
             // Resolve the target. For `--personal`, look up the caller's
             // canonical person entity and force personalMode + journalSlug so
             // share() lands files at hqRoot directly (no companies/<slug>/
             // prefix). For everything else, the company is whatever the user
             // passed or the active company from .hq/config.json.
-            let targetCompany = options.company;
+            let targetCompany = options.company ?? entityContext?.uid;
             let personalMode = false;
             let journalSlug;
             if (options.personal) {
@@ -646,6 +676,12 @@ export function registerCloudCommands(program) {
             // idToken — pre-vended `--creds-from-stdin` paths still get author
             // attribution as long as the caller is logged in locally.
             const author = resolveUploadAuthorFromCache();
+            let pushPrefixSet;
+            if (!personalMode && scopeVaultConfig) {
+                const scopeClient = new VaultClient(scopeVaultConfig);
+                const scope = await resolveCliPullScope(scopeClient, targetCompany, options.hqRoot);
+                pushPrefixSet = scope?.prefixSet;
+            }
             const result = await share({
                 paths: targetPaths,
                 company: targetCompany,
@@ -658,6 +694,7 @@ export function registerCloudCommands(program) {
                 ...(personalMode ? { personalMode: true } : {}),
                 ...(journalSlug !== undefined ? { journalSlug } : {}),
                 ...(author ? { author } : {}),
+                ...(pushPrefixSet !== undefined ? { prefixSet: pushPrefixSet } : {}),
             });
             if (jsonMode) {
                 // Synthetic terminal event so subprocess consumers can read final
@@ -681,6 +718,9 @@ export function registerCloudCommands(program) {
                 log(chalk.yellow(`\n⚠ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ` +
                     `${result.filesSkipped} skipped, ${result.filesExcludedByScope} scope-excluded)`));
                 log(chalk.yellow(scopeExcludedWarning(result.filesExcludedByScope)));
+                const prefixDetail = scopeExcludedPrefixDetail(pushPrefixSet);
+                if (prefixDetail)
+                    log(chalk.yellow(prefixDetail));
             }
             else {
                 log(chalk.green(`\n✓ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ${result.filesSkipped} skipped)`));
@@ -1091,6 +1131,7 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
             ...(skipPersonal ? { skipPersonal: true } : {}),
         }, {
             vaultClient: adapter,
+            resolveScope: (companyUid, slug) => resolvePullScope(realClient, companyUid, slug, hqRoot),
             share: (opts) => share({
                 paths: opts.paths,
                 company: opts.company,
@@ -1113,6 +1154,7 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
                 ...(opts.propagateDeletePolicy !== undefined
                     ? { propagateDeletePolicy: opts.propagateDeletePolicy }
                     : {}),
+                ...(opts.prefixSet !== undefined ? { prefixSet: opts.prefixSet } : {}),
                 ...(author ? { author } : {}),
             }),
         });
@@ -1195,6 +1237,12 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         // Push first so the subsequent pull doesn't redownload files we were
         // about to broadcast (matches hq-sync-runner ordering).
         console.log(chalk.dim("  → push leg"));
+        let nowPushPrefixSet;
+        if (!personalMode) {
+            const scopeClient = new VaultClient(vaultConfig);
+            const pushScope = await resolveCliPullScope(scopeClient, targetCompany, hqRoot);
+            nowPushPrefixSet = pushScope?.prefixSet;
+        }
         const pushResult = await share({
             paths: pushPaths,
             company: targetCompany,
@@ -1208,6 +1256,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             ...(personalMode ? { personalMode: true } : {}),
             ...(journalSlug !== undefined ? { journalSlug } : {}),
             ...(author ? { author } : {}),
+            ...(nowPushPrefixSet !== undefined ? { prefixSet: nowPushPrefixSet } : {}),
         });
         const pushStatus = pushResult.aborted || pushResult.filesExcludedByScope > 0
             ? chalk.yellow("⚠")
@@ -1218,6 +1267,9 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             (pushResult.aborted ? " — aborted" : ""));
         if (pushResult.filesExcludedByScope > 0) {
             console.log(chalk.yellow(scopeExcludedWarning(pushResult.filesExcludedByScope)));
+            const prefixDetail = scopeExcludedPrefixDetail(nowPushPrefixSet);
+            if (prefixDetail)
+                console.log(chalk.yellow(prefixDetail));
         }
         if (pushResult.aborted) {
             console.log(chalk.yellow("\n⚠ Sync now aborted on push leg; pull skipped."));

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, you may read\n   its tail for context (last ~200 lines); never quote secrets from it.\n2. Verify the checkpoint thread file named in the payload exists and is valid\n   JSON; repair or enrich it if needed (keep its shape).\n3. For each entry in \"learnings\": if it is a reusable rule, distill it into a\n   policy file under personal/policies/ (or companies/<company>/policies/ when\n   the payload names a company and the lesson is company-specific), following\n   core/knowledge/public/hq-core/policies-spec.md. Skip duplicates \u2014 search\n   existing policies first.\n4. For durable facts (not rules), update knowledge under personal/knowledge/\n   or companies/<company>/knowledge/.\n5. Hook or automation improvements go ONLY under personal/hooks/ as proposals.\n   You must never write into .claude/, core/, .agents/, .codex/, or repos/.\n6. Write <runDir>/report.md \u2014 full prose: what you read, what you changed\n   (paths), what you skipped and why.\n7. If workspace/checkpoints/sibling/pending.jsonl is non-empty when you\n   finish, process those payloads the same way, 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,544 @@
+/**
+ * `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, you may read
+   its tail for context (last ~200 lines); never quote secrets from it.
+2. Verify the checkpoint thread file named in the payload exists and is valid
+   JSON; repair or enrich it if needed (keep its shape).
+3. For each entry in "learnings": if it is a reusable rule, distill it into a
+   policy file under personal/policies/ (or companies/<company>/policies/ when
+   the payload names a company and the lesson is company-specific), following
+   core/knowledge/public/hq-core/policies-spec.md. Skip duplicates — search
+   existing policies first.
+4. For durable facts (not rules), update knowledge under personal/knowledge/
+   or companies/<company>/knowledge/.
+5. Hook or automation improvements go ONLY under personal/hooks/ as proposals.
+   You must never write into .claude/, core/, .agents/, .codex/, or repos/.
+6. Write <runDir>/report.md — full prose: what you read, what you changed
+   (paths), what you skipped and why.
+7. If workspace/checkpoints/sibling/pending.jsonl is non-empty when you
+   finish, process those payloads the same way, 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 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 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 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,
+        decisions,
+        nextSteps,
+        tags,
+        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"]) !== "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function gitStateFor(cwd, liveRoot) {
+    return (readGitState(cwd) ??
+        readGitState(liveRoot) ?? {
+        branch: "unknown",
+        current_commit: "unknown",
+        dirty: false,
+    });
+}
+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,
+        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,
+        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",
+        "decision",
+        "next",
+        "tag",
+        "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 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,
+            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: gitStateFor(process.cwd(), liveRoot),
+        conversation_summary: input.summary,
+        files_touched: input.files,
+        next_steps: input.nextSteps,
+        learnings: input.learnings,
+        decisions: input.decisions,
+        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("--decision <text>", "decision made", collect, [])
+        .option("--next <text>", "remaining next step", collect, [])
+        .option("--tag <tag>", "checkpoint tag", collect, [])
+        .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/packs.js

@@ -78,7 +78,7 @@ export function buildInstalledView(hqRoot, hqVersion, pack, installedSources, ch
     const counts = { live: 0, broken: 0, missing: 0, foreign: 0 };
     const brokenLinks = [];
     for (const link of links) {
-        const st = linkStatus(link);
+        const st = linkStatus(link, pack.dir);
         counts[st]++;
         if (st === 'broken')
             brokenLinks.push({ key: link.key, item: link.item, dst: link.dst });

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/index.js

@@ -11,8 +11,12 @@ if (isVersionRequest(process.argv)) {
     process.stdout.write(`${CLI_VERSION}\n`);
 }
 else {
-    const { runCli } = await import("./main.js");
-    await runCli();
+    // Keep the command lifecycle detached from module evaluation, as it was
+    // before the fast --version split. Some best-effort teardown work uses
+    // unref'd handles; top-level-awaiting runCli() makes Node turn an otherwise
+    // successful command into exit 13 when that teardown promise remains pending.
+    // Rejections still become unhandled and preserve a genuine non-zero failure.
+    void import("./main.js").then(({ runCli }) => runCli());
 }
 export const __test__ = { isVersionRequest };
 //# sourceMappingURL=index.js.map

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.d.ts

@@ -75,8 +75,13 @@ export type LinkStatus = 'live' | 'broken' | 'missing' | 'foreign';
  * effect (a config merge) is handled separately (US-004/US-005).
  */
 export declare function contributionLinks(hqRoot: string, packDir: string, contributes: Partial<Record<PackContributeKey, string[]>>): WiredLink[];
+/**
+ * Canonical absolute path — resolves symlinks and platform aliases such as
+ * macOS `/var` ↔ `/private/var` so equivalent paths compare equal.
+ */
+export declare function canonicalPath(p: string): string;
 /** Classify a host path against the link that should own it. */
-export declare function linkStatus(link: WiredLink): LinkStatus;
+export declare function linkStatus(link: WiredLink, packDir?: string): LinkStatus;
 /** A content pack's manifest plus the install-time stamped source. */
 export interface InstalledPackManifest extends PackManifest {
     source?: string;

package/dist/utils/pack-contributions.js

@@ -132,8 +132,56 @@ export function contributionLinks(hqRoot, packDir, contributes) {
     }
     return links;
 }
+/**
+ * Canonical absolute path — resolves symlinks and platform aliases such as
+ * macOS `/var` ↔ `/private/var` so equivalent paths compare equal.
+ */
+export function canonicalPath(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** True when `candidate` resolves under `packDir` (pack directory containment). */
+function targetUnderPackDir(packDir, candidate) {
+    const root = canonicalPath(packDir);
+    const resolved = canonicalPath(candidate);
+    const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+    return resolved === root || resolved.startsWith(prefix);
+}
+/** True when `a` and `b` resolve to the same on-disk file (canonical path or inode). */
+function samePayloadFile(a, b) {
+    const canonA = canonicalPath(a);
+    const canonB = canonicalPath(b);
+    if (canonA === canonB)
+        return true;
+    try {
+        const stA = fs.statSync(a);
+        const stB = fs.statSync(b);
+        return stA.dev === stB.dev && stA.ino === stB.ino;
+    }
+    catch {
+        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) {
+export function linkStatus(link, packDir) {
     let st;
     try {
         st = fs.lstatSync(link.dst);
@@ -151,13 +199,21 @@ export function linkStatus(link) {
     catch {
         return 'foreign';
     }
-    // scan-packages.sh writes the symlink target as the absolute `src` path, so a
-    // direct compare is correct. Resolve both to be robust to trailing slashes.
+    // scan-packages.sh writes the symlink target as the absolute `src` path.
+    // Canonicalize both sides so `/var` vs `/private/var` (macOS) and symlink
+    // 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 (path.resolve(link.src) !== resolvedTarget) {
-        return 'foreign'; // points at another pack / somewhere else
+    if (pointsAtDeclaredPayload(link, resolvedTarget)) {
+        return fs.existsSync(link.src) ? 'live' : 'broken';
+    }
+    if (packDir !== undefined && targetUnderPackDir(packDir, resolvedTarget)) {
+        // Stale or corrupted: symlink resolves inside this pack but not to the
+        // declared payload. Treat as broken (never live) so list does not report a
+        // healthy link; unwirePack still removes it on uninstall.
+        return 'broken';
     }
-    return fs.existsSync(link.src) ? 'live' : 'broken';
+    return 'foreign'; // points at another pack / somewhere else
 }
 /** Absolute path to `<hqRoot>/core/packages`. */
 export function packagesDir(hqRoot) {
@@ -230,7 +286,7 @@ export function findDependentPacks(installed, name) {
 export function unwirePack(hqRoot, packDir, contributes) {
     const result = { unlinked: [], skipped: [] };
     for (const link of contributionLinks(hqRoot, packDir, contributes)) {
-        const status = linkStatus(link);
+        const status = linkStatus(link, packDir);
         if (status === 'live' || status === 'broken') {
             try {
                 fs.unlinkSync(link.dst);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.79.0",
+  "version": "5.81.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -29,7 +29,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "^6.14.27",
+    "@indigoai-us/hq-cloud": "^6.14.37",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "better-sqlite3": "^12.11.1",