@indigoai-us/hq-cli 5.99.3 → 5.100.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [5.100.0] — 2026-08-13
+
+### Added
+
+- `hq core checkpoint` now ends every non-dry-run checkpoint — real writes and
+  `--idle` alike — with a REMINDER line telling the calling agent that the
+  checkpoint is invisible bookkeeping, not the user-facing reply, and that any
+  substance not yet reported to the user must be delivered before the turn ends
+  (#374). The reminder is emitted even when sibling startup fails, and the
+  bundled Stop-gate prompt was reworded to prescribe the same reply-first
+  ordering. Machine-parsed outputs (`--dry-run` JSON, `--gate-probe`) are
+  unchanged.
+
 ## [5.99.3] — 2026-08-13
 
 ### Fixed

package/assets/scaffold/core/scripts/checkpoint-stop-gate.sh

@@ -327,7 +327,7 @@ set -uo pipefail
 
   # Built with printf rather than concatenation so the session id can appear in
   # both commands without re-splitting the message into fragments.
-  reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. If you owe them anything — a result, a link, an answer, a status — say it in the reply as usual. The checkpoint is invisible to them and is NOT a message to them; running it does not count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nSo: finish whatever you owe the user in the reply first, then run the checkpoint as the FINAL action of the turn and end the turn immediately after it — no further commentary once the command has run.\n\n  hq core checkpoint --session-id %s --trigger stop-gate --summary "<what changed, in one line>" [--file <path>] [--decision "<choice and why>"] [--learning "<reusable rule>"] [--next "<outstanding step>"]\n\nOnly --summary is required, and the repeatable flags are what the sibling uses to enrich the record, distil policies and update the indexes — a bare summary gives it almost nothing to work with. Write them as machine record, not prose for the user, and pass each one that genuinely applies:\n  --file      every path you created or modified this turn\n  --decision  a choice you made that a reader would otherwise have to reverse-engineer\n  --learning  a rule that changes how someone acts next time, not a restatement of what just happened\n  --next      work that is genuinely still outstanding\nOmit a flag rather than padding it: an empty or invented learning is worse than none.\n\nIf this turn only read or inspected things and changed no state, the correct call instead is:\n\n  hq core checkpoint --session-id %s --idle' "$session_id" "$session_id")"
+  reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. If you owe them anything — a result, a link, an answer, a status — say it in the reply as usual. The checkpoint is invisible to them and is NOT a message to them; running it does not count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nSo: finish whatever you owe the user in the reply first, then run the checkpoint as the FINAL action of the turn and end the turn immediately after it. The checkpoint output ends with a REMINDER restating this contract: if it catches you having skipped the user-facing reply, deliver that overdue reply — nothing else — and then end the turn; otherwise add no commentary after the command.\n\n  hq core checkpoint --session-id %s --trigger stop-gate --summary "<what changed, in one line>" [--file <path>] [--decision "<choice and why>"] [--learning "<reusable rule>"] [--next "<outstanding step>"]\n\nOnly --summary is required, and the repeatable flags are what the sibling uses to enrich the record, distil policies and update the indexes — a bare summary gives it almost nothing to work with. Write them as machine record, not prose for the user, and pass each one that genuinely applies:\n  --file      every path you created or modified this turn\n  --decision  a choice you made that a reader would otherwise have to reverse-engineer\n  --learning  a rule that changes how someone acts next time, not a restatement of what just happened\n  --next      work that is genuinely still outstanding\nOmit a flag rather than padding it: an empty or invented learning is worse than none.\n\nIf this turn only read or inspected things and changed no state, the correct call instead is:\n\n  hq core checkpoint --session-id %s --idle' "$session_id" "$session_id")"
 
   # Codex surfaces a blocked Stop reason as a synthetic user prompt. Preserve
   # the actionable instruction out-of-band, then use the stable marker covered

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

@@ -9,6 +9,19 @@
 import { Command } from "commander";
 type Backend = "claude" | "codex" | "grok" | "none";
 type SpawnableBackend = Exclude<Backend, "none">;
+/**
+ * Printed after every non-dry-run checkpoint, real or --idle. Agents were
+ * treating the checkpoint call as the end of the turn, leaving their actual
+ * findings only in the checkpoint payload — which the user never sees. This
+ * line rides the command output (the one channel guaranteed to reach the
+ * calling agent) to force the user-facing reply. Deliberately conditional so
+ * it composes with the Stop-gate prompt's "reply first, checkpoint last, then
+ * end the turn" ordering: an agent that already replied is told to end the
+ * turn, not to add commentary. Mirrors the hq-core policies
+ * `checkpoint-is-bookkeeping-not-user-communication` and
+ * `checkpoint-is-not-the-user-report`.
+ */
+export declare const CHECKPOINT_REPLY_REMINDER: string;
 /**
  * Kept in TypeScript rather than in a bundled asset: it is an instruction to
  * a locally-installed agent, not a scaffold script that should be packaged.

package/dist/commands/core-checkpoint.js

@@ -40,6 +40,23 @@ const SIBLING_LOCK_TTL_MS = 60 * 60 * 1000;
 const MAX_PENDING_PAYLOADS = 50;
 class CheckpointUsageError extends Error {
 }
+/**
+ * Printed after every non-dry-run checkpoint, real or --idle. Agents were
+ * treating the checkpoint call as the end of the turn, leaving their actual
+ * findings only in the checkpoint payload — which the user never sees. This
+ * line rides the command output (the one channel guaranteed to reach the
+ * calling agent) to force the user-facing reply. Deliberately conditional so
+ * it composes with the Stop-gate prompt's "reply first, checkpoint last, then
+ * end the turn" ordering: an agent that already replied is told to end the
+ * turn, not to add commentary. Mirrors the hq-core policies
+ * `checkpoint-is-bookkeeping-not-user-communication` and
+ * `checkpoint-is-not-the-user-report`.
+ */
+export const CHECKPOINT_REPLY_REMINDER = "checkpoint: REMINDER — this checkpoint is invisible bookkeeping; the user never sees it " +
+    "and it does NOT count as your reply. If your reply to the user already contains " +
+    "everything of substance from this turn, end the turn now. If anything — results, " +
+    "findings, decisions, state changes, anything awaiting their input — exists only in this " +
+    "checkpoint or your head, deliver it to the user in plain language before ending the turn.";
 function printResult(line) {
     process.stdout.write(`${line}\n`);
 }
@@ -801,6 +818,9 @@ function runCheckpoint(options, command, group) {
         }
         writeStamps(liveRoot, resolveSessionId(options, command, readPayload(options.payload)));
         printResult("checkpoint: idle (nothing to record)");
+        // An idle turn persisted nothing, but a read-only turn can still have
+        // produced substantive findings the user has not been told about.
+        printResult(CHECKPOINT_REPLY_REMINDER);
         return;
     }
     const payload = readPayload(options.payload);
@@ -860,13 +880,22 @@ function runCheckpoint(options, command, group) {
     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;
+    // finally: the thread is already written at this point, so the agent must
+    // get the reminder even when sibling startup throws (e.g. an explicitly
+    // requested backend that is not installed).
+    try {
+        if (options.agent !== false) {
+            if (backend === "none") {
+                printResult("checkpoint: sibling disabled (backend none)");
+            }
+            else {
+                startSibling(liveRoot, input, threadPath, backend);
+            }
+        }
+    }
+    finally {
+        printResult(CHECKPOINT_REPLY_REMINDER);
     }
-    startSibling(liveRoot, input, threadPath, backend);
 }
 function reportUsage(error) {
     printError("Usage: hq core checkpoint --summary <text> [options]");

package/package.json

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