@indigoai-us/hq-cli 5.217.0 → 5.218.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.218.0] — 2026-09-26
+
+### Fixed
+
+- The reconcile summary now lists opted-in lanes it could not resume and why.
+  Stderr provides reason-specific guidance and recommends reapplying opt-in only
+  when that can help.
+
 ## [5.217.0] — 2026-09-26
 
 ### Fixed

package/dist/lib/lanes/reconcile.d.ts

@@ -9,6 +9,7 @@ import { type LivenessDeps } from "./liveness.js";
 import { type EnvelopeRepairSpawnInput, type SpawnLaneDeps } from "./spawn.js";
 import { type ThrottleDeps } from "./throttle.js";
 import { readLanesRegistryFlag } from "./registry-flag.js";
+import { type KeepAliveBlockedReason } from "./keep-alive.js";
 import type { LaneRecord, LivenessState, QueuedReason, QuestionRecord, SeniorRef } from "./types.js";
 import { type LaneMesh } from "./mesh-events.js";
 /** Spec §9: unanswered at the current hop for 60 minutes → one hop. */
@@ -49,6 +50,10 @@ export interface ReconcileSummary {
     dead_host: ReconcileChange[];
     heartbeats: string[];
     skipped: ReconcileSkip[];
+    keep_alive_blocked: Array<{
+        id: string;
+        reason: KeepAliveBlockedReason;
+    }>;
     errors: Array<{
         message: string;
         code?: string;

package/dist/lib/lanes/reconcile.js

@@ -66,6 +66,7 @@ function emptySummary(dryRun) {
         dead_host: [],
         heartbeats: [],
         skipped: [],
+        keep_alive_blocked: [],
         errors: [],
         heartbeat_at: null,
     };
@@ -1417,12 +1418,38 @@ function recordKeepAliveEvent(hqRoot, laneId, summary, event) {
         });
     }
 }
+function keepAliveSkipGuidance(laneId, reason) {
+    switch (reason) {
+        case "missing_opt_in_time":
+            return `if appropriate, run hq lanes keep-alive ${laneId} --on`;
+        case "not_opted_in":
+            return "explicit opt-in is required before keep-alive can resume this lane";
+        case "envelope_before_opt_in":
+            return `the latest envelope predates opt-in; review the lane with hq lanes show ${laneId}`;
+        case "interruption_before_opt_in":
+            return `the interruption predates opt-in; review the lane with hq lanes show ${laneId}`;
+        case "missing_interruption_time":
+            return "the interruption time is unavailable; inspect the watcher classification before resuming";
+        case "retired":
+            return "the lane is retired; resolve its retired status before resuming";
+        case "superseded":
+            return "a newer lead exists for this project; continue on that lane";
+        case "retired_list_invalid":
+            return "the retired lane list is invalid; repair workspace/lane-briefs/juniors.json before retrying";
+        case "terminal_state":
+            return `the lane is in a terminal state; review it with hq lanes show ${laneId} before starting replacement work`;
+    }
+}
 function recordKeepAliveSkip(hqRoot, lane, reason, summary, deps, detail) {
     summary.skipped.push({
         kind: "lane",
         id: lane.lane_id,
         why: `keep_alive_${reason}${detail ? `: ${detail}` : ""}`,
     });
+    if (lane.keep_alive === true) {
+        summary.keep_alive_blocked.push({ id: lane.lane_id, reason });
+        process.stderr.write(`hq lanes reconcile: keep-alive blocked for lane ${lane.lane_id} (${reason}); ${keepAliveSkipGuidance(lane.lane_id, reason)}\n`);
+    }
     if (deps.dryRun || lane.keep_alive_blocked_reason === reason)
         return;
     try {

package/package.json

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