@indigoai-us/hq-cli 5.89.1 → 5.89.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [5.89.2]
+
+### Fixed
+
+- The `hq core checkpoint` maintenance sibling no longer loses queued payloads.
+  Both drain paths read `pending.jsonl` and then truncated it, so a checkpoint
+  queued between the read and the truncate was discarded unread and never
+  enriched. The queue is now claimed atomically by renaming it into the run
+  directory, leaving producers a fresh queue and keeping the claimed file as an
+  audit and crash-recovery trail; the sibling prompt claims by `mv` in a loop
+  rather than truncating in place. (#317)
+
 ## [5.89.1]
 
 ### Fixed

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

@@ -11,7 +11,7 @@ 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 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. Then drain the queue: while\n   workspace/checkpoints/sibling/pending.jsonl exists and is non-empty, claim\n   it atomically by renaming it aside \u2014\n   mv workspace/checkpoints/sibling/pending.jsonl <runDir>/pending-claimed-N.jsonl\n   (N counting up from 2) \u2014 and process the claimed payloads with this same\n   flow. Repeat until a claim finds nothing left, then update the report.\n   NEVER read the queue and truncate it in place: a payload appended between\n   your read and the truncate is lost, and its checkpoint is never enriched.\n";
 export declare function renderSiblingPrompt(runDir: string, payloadPath: string): string;
 /** Attach the native checkpoint command to the hidden `hq core` group. */
 export declare function registerCoreCheckpointCommand(core: Command): void;

package/dist/commands/core-checkpoint.js

@@ -78,9 +78,14 @@ report instead of guessing.
    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.
+   (paths), and what you skipped and why. 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.
 `;
 export function renderSiblingPrompt(runDir, payloadPath) {
     return SIBLING_PROMPT_TEMPLATE
@@ -457,26 +462,43 @@ function appendPending(pendingPath, payload) {
         .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;
 }
-function drainPending(pendingPath) {
-    if (!fs.existsSync(pendingPath))
-        return [];
+/**
+ * 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(pendingPath, "utf8").split("\n")) {
+    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 a future sibling from processing the
-            // valid queued payloads around it.
+            // A partial line must not prevent this run from processing the valid
+            // queued payloads around it.
         }
     }
-    fs.writeFileSync(pendingPath, "");
     return entries;
 }
 function startSibling(liveRoot, input, threadPath, backend) {
@@ -494,7 +516,7 @@ function startSibling(liveRoot, input, threadPath, backend) {
     }
     const runDir = path.join(siblingRoot, `${formatTimestamp(new Date())}-${summarySlug(input.summary ?? "checkpoint")}`);
     fs.mkdirSync(runDir, { recursive: true });
-    payload.pending_payloads = drainPending(pendingPath);
+    payload.pending_payloads = claimPending(pendingPath, path.join(runDir, "pending-claimed.jsonl"));
     const payloadPath = path.join(runDir, "payload.json");
     fs.writeFileSync(payloadPath, `${JSON.stringify(payload, null, 2)}\n`);
     const prompt = renderSiblingPrompt(runDir, payloadPath);

package/package.json

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