@indigoai-us/hq-cli 5.160.0 → 5.162.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [5.162.0] — 2026-09-24
+
+### Fixed
+
+- An invalid envelope that remains after its repair turn no longer leaves a
+  lane inaccessible. Operators can resume or message a failed lane with a
+  recorded provider session, and the next envelope slot gets one new repair
+  attempt with the validation errors in the prompt.
+
+## [5.161.0] — 2026-09-24
+
+### Fixed
+
+- No-reader flag gates now honor only `true` and `false` in `HQ_FLAG_<KEY>`
+  overrides when the registry endpoint is unset or its reader is unavailable.
+
 ## [5.160.0] — 2026-09-24
 
 ### Added

package/dist/commands/lanes.js

@@ -3830,7 +3830,9 @@ function laneWithRecoveredProviderSession(hqRoot, lane) {
 }
 /**
  * `hq lanes resume <lane-id> [--text <msg>]`: the explicit opt-in that
- * continues a lane in `interrupted`, `done` or `blocked` on its recorded
+ * continues a lane in `interrupted`, `done` or `blocked`, or a failed lane
+ * whose only terminal reason is an invalid envelope after its repair turn,
+ * on its recorded
  * provider session. `hq lanes message` keeps refusing `interrupted`; this
  * command is the path its refusal names. The launch is the same
  * `spawnLaneWorker` a message resume uses, so the resume-time compaction

package/dist/lib/flag-registry.js

@@ -6,11 +6,17 @@
  * keep a short-lived, offline CLI alive until the client's network deadline.
  */
 import { Worker } from "node:worker_threads";
-import { isFlagSnapshot, resolveFlag, } from "@indigoai-us/hq-flags-client";
+import { isFlagSnapshot, readLocalOverride, resolveFlag, } from "@indigoai-us/hq-flags-client";
 /** Dedicated endpoint configuration; this is intentionally not HQ_PRO_API_URL. */
 export const FLAG_REGISTRY_ENDPOINT_ENV = "HQ_FLAGS_API_URL";
 let heldSnapshot = null;
 let processReader = null;
+function processLocalOverride(flagKey) {
+    return readLocalOverride(flagKey, process.env);
+}
+function localOverrideOrFallback(flagKey, legacyFallback) {
+    return processLocalOverride(flagKey) ?? legacyFallback();
+}
 function processSnapshotReader() {
     return {
         isEnabled(flagKey, lookup = {}) {
@@ -65,12 +71,12 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
  */
 export function resolveFlagGate(reader, flagKey, lookup, legacyFallback) {
     if (!reader)
-        return legacyFallback();
+        return localOverrideOrFallback(flagKey, legacyFallback);
     try {
         return reader.isEnabled(flagKey, lookup);
     }
     catch {
-        return legacyFallback();
+        return localOverrideOrFallback(flagKey, legacyFallback);
     }
 }
 /** Resolve a process gate against the shared snapshot reader, when configured. */

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

@@ -57,7 +57,9 @@ export type ResumeCommandState = (typeof RESUME_COMMAND_STATES)[number];
 export declare function isResumeCommandState(state: LaneState): state is ResumeCommandState;
 export declare const LANE_DELIVERY_MECHANISMS: readonly ["dropbox", "resume", "none"];
 export type LaneDeliveryMechanism = (typeof LANE_DELIVERY_MECHANISMS)[number];
-export type DeliveryLane = Pick<LaneRecord, "state" | "provider" | "provider_session_id">;
+export type DeliveryLane = Pick<LaneRecord, "state" | "provider" | "provider_session_id" | "terminal_reason" | "envelope_repair">;
+/** Only the terminal result of a failed automatic envelope repair is recoverable. */
+export declare function isFailedEnvelopeRepairLane(lane: DeliveryLane): boolean;
 /**
  * `dropbox`: a process is (or is about to be) alive to drain the inbox.
  * `resume`: the process has exited, the provider can resume, the state allows
@@ -120,7 +122,7 @@ export type LaunchTrigger = {
     /** `hq lanes resume`: the operator's explicit opt-in to continue an exited lane. */
     kind: "resume";
     /** Lane state at the moment of the command; recorded as `last_resume.resumed_from`. */
-    from: ResumeCommandState;
+    from: ResumeCommandState | "failed";
     text?: string;
     message_id?: string;
 };
@@ -147,5 +149,5 @@ export declare function resumeCommandRefusal(lane: DeliveryLane): {
  */
 export declare function planLaneLaunch(lane: DeliveryLane, trigger: LaunchTrigger): LaunchPlan;
 /** Lane states a launch may claim `running` from, per trigger. */
-export declare function claimableStatesFor(trigger: LaunchTrigger): readonly LaneState[];
+export declare function claimableStatesFor(trigger: LaunchTrigger, lane?: DeliveryLane): readonly LaneState[];
 //# sourceMappingURL=delivery.d.ts.map

package/dist/lib/lanes/delivery.js

@@ -20,7 +20,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { LanesError } from "./errors.js";
-import { parseLaneProvider, } from "./types.js";
+import { parseLaneProvider, ENVELOPE_INVALID_REASON, } from "./types.js";
 /** Which providers can continue an exited worker from a recorded session id. */
 export const PROVIDER_SESSION_RESUME = {
     claude: true,
@@ -67,6 +67,13 @@ export function isResumeCommandState(state) {
     return RESUME_COMMAND_STATES.includes(state);
 }
 export const LANE_DELIVERY_MECHANISMS = ["dropbox", "resume", "none"];
+/** Only the terminal result of a failed automatic envelope repair is recoverable. */
+export function isFailedEnvelopeRepairLane(lane) {
+    return (lane.state === "failed" &&
+        lane.terminal_reason === ENVELOPE_INVALID_REASON &&
+        lane.envelope_repair?.attempted === true &&
+        lane.envelope_repair.succeeded === false);
+}
 /**
  * `dropbox`: a process is (or is about to be) alive to drain the inbox.
  * `resume`: the process has exited, the provider can resume, the state allows
@@ -77,7 +84,7 @@ export function laneDeliveryMechanism(lane) {
     if (lane.state === "queued" || lane.state === "running")
         return "dropbox";
     if (providerSupportsSessionResume(lane.provider) &&
-        isResumableLaneState(lane.state) &&
+        (isResumableLaneState(lane.state) || isFailedEnvelopeRepairLane(lane)) &&
         hasRecordedSessionId(lane)) {
         return "resume";
     }
@@ -275,7 +282,7 @@ export const LAUNCH_TRIGGERS = ["admit", "answered_questions", "message", "resum
  * without a resume path, no recorded session. Null when the resume can go.
  */
 export function resumeCommandRefusal(lane) {
-    if (!isResumeCommandState(lane.state)) {
+    if (!isResumeCommandState(lane.state) && !isFailedEnvelopeRepairLane(lane)) {
         return {
             error: "lane_not_resumable",
             message: `Lane is ${lane.state}. hq lanes resume continues a lane in ${RESUME_COMMAND_STATES.join(", ")}; ${lane.state === "awaiting_input"
@@ -337,16 +344,17 @@ export function planLaneLaunch(lane, trigger) {
     }
 }
 /** Lane states a launch may claim `running` from, per trigger. */
-export function claimableStatesFor(trigger) {
+export function claimableStatesFor(trigger, lane) {
+    const envelopeRepairFailed = lane !== undefined && isFailedEnvelopeRepairLane(lane) && hasRecordedSessionId(lane);
     switch (trigger.kind) {
         case "admit":
             return ["queued"];
         case "answered_questions":
             return ["awaiting_input"];
         case "message":
-            return RESUMABLE_LANE_STATES;
+            return envelopeRepairFailed ? [...RESUMABLE_LANE_STATES, "failed"] : RESUMABLE_LANE_STATES;
         case "resume":
-            return RESUME_COMMAND_STATES;
+            return envelopeRepairFailed ? [...RESUME_COMMAND_STATES, "failed"] : RESUME_COMMAND_STATES;
         default: {
             const _exhaustive = trigger;
             return _exhaustive;

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

@@ -192,6 +192,11 @@ export declare function resumePrompt(input: {
     answers?: AnsweredQuestionLine[];
     /** `hq lanes resume`: the state the operator resumed the lane from. */
     resumedFrom?: string;
+    /** Exact validator errors recorded after the prior envelope repair failed. */
+    envelopeRepairErrors?: {
+        first_error: string;
+        second_error?: string;
+    };
 }): string;
 /** Spec §4: the one repair turn. Schema, parser error, raw text, JSON only. */
 export declare function envelopeRepairPrompt(input: {

package/dist/lib/lanes/spawn.js

@@ -26,7 +26,7 @@ import { copySessionFiles, planSessionCopy } from "./move-account.js";
 import { ensureSessionHome } from "./session-relink.js";
 import { hasEarlierEligibleQueuedLane, laneAdmissionCapReason, withLaneAdmissionLock, } from "./admission.js";
 import { resolveAdmissionHost } from "./admission-host.js";
-import { LANE_ENVELOPE_JSON_SCHEMA, parseLaneProvider, } from "./types.js";
+import { LANE_ENVELOPE_JSON_SCHEMA, ENVELOPE_INVALID_REASON, parseLaneProvider, } from "./types.js";
 export const LANES_RUNS_REL = path.join("workspace", "lanes-runs");
 /** Written by reconcile before a resume spawn; the worker prompt names this path. */
 export const ANSWERED_QUESTIONS_FILE = "answered-questions.json";
@@ -996,6 +996,16 @@ export function resumePrompt(input) {
             ...(lines.length > 0 ? ["Answers:", ...lines] : []),
         ].join("\n"));
     }
+    if (input.envelopeRepairErrors !== undefined) {
+        const errors = [input.envelopeRepairErrors.first_error, input.envelopeRepairErrors.second_error]
+            .filter((error) => typeof error === "string" && error.length > 0);
+        parts.push([
+            `The previous envelope repair failed validation. The next envelope slot is ${input.envelopePath}; write a new valid envelope there.`,
+            "Exact validation errors recorded in envelope_repair:",
+            ...errors.map((error, index) => `- envelope_repair.${index === 0 ? "first_error" : "second_error"}: ${JSON.stringify(error)}`),
+            "For an ask question, include non-empty id, question, and context fields.",
+        ].join("\n"));
+    }
     // Every resume turn carries the authorization, including a textless
     // `hq lanes resume`: a pre-upgrade session's brief never had the paragraph.
     if (input.operatorMessage !== undefined ||
@@ -1028,6 +1038,7 @@ export function envelopeRepairPrompt(input) {
         `The file you wrote at ${input.envelopePath} is not a valid hq-lane-envelope.v1. ` +
             `This is the single repair turn: rewrite that file so it validates, and do nothing else.`,
         `Parser error: ${input.error}`,
+        "For an ask question, include non-empty id, question, and context fields.",
         "Schema:",
         JSON.stringify(LANE_ENVELOPE_JSON_SCHEMA, null, 2),
         "Your previous output was:",
@@ -1723,6 +1734,16 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 answers: (trigger.kind === "answered_questions" || pendingResume?.trigger === "answered_questions") && existsSync(answersPath)
                     ? readAnsweredQuestionLines(answersPath)
                     : undefined,
+                envelopeRepairErrors: lane.terminal_reason === ENVELOPE_INVALID_REASON &&
+                    lane.envelope_repair?.attempted === true &&
+                    lane.envelope_repair.succeeded === false
+                    ? {
+                        first_error: lane.envelope_repair.first_error,
+                        ...(lane.envelope_repair.second_error !== undefined
+                            ? { second_error: lane.envelope_repair.second_error }
+                            : {}),
+                    }
+                    : undefined,
             }),
         }
         : undefined;
@@ -1805,7 +1826,6 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     }
     // Claim running before spawning. Two callers that both observe queued must
     // not both start processes; the CAS loser returns without spawn.
-    const claimable = claimableStatesFor(trigger);
     const nowIso = (deps.now ?? (() => new Date()))().toISOString();
     let claimed = false;
     const claimedRecord = retryUpdateLane(hqRoot, lane.lane_id, "spawn", (current) => {
@@ -1816,7 +1836,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             }
             return current;
         }
-        if (!claimable.includes(current.state)) {
+        if (!claimableStatesFor(trigger, current).includes(current.state)) {
             throw new LanesError("spawn_state_mismatch", `Cannot mark ${current.lane_id} running from ${current.state}`, { lane_id: current.lane_id, state: current.state, trigger: trigger.kind });
         }
         claimed = true;
@@ -1826,6 +1846,8 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             queued_reason: undefined,
             queued_at: undefined,
             admission_reserved_at: undefined,
+            terminal_reason: undefined,
+            terminal_details: undefined,
             // An account move's reservation ends with the claim.
             pending_resume: undefined,
             account: resolved.id,

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

@@ -7,6 +7,8 @@ export declare const LANE_SCHEMA_VERSION: "hq-lane.v1";
 export declare const QUESTION_SCHEMA_VERSION: "hq-lane-question.v1";
 export declare const ENVELOPE_SCHEMA_VERSION: "hq-lane-envelope.v1";
 export declare const CONFIG_SCHEMA_VERSION: "hq-lanes-config.v1";
+/** Lane terminal reason for an envelope still invalid after its one repair turn. */
+export declare const ENVELOPE_INVALID_REASON: "envelope_invalid";
 /**
  * The envelope contract as a JSON schema. `parseLaneEnvelope` is the runtime
  * check; this is the text handed to a worker on the repair turn (spec §4) so
@@ -36,6 +38,11 @@ export declare const LANE_ENVELOPE_JSON_SCHEMA: {
                 readonly additionalProperties: false;
                 readonly required: readonly ["question", "context", "options"];
                 readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly pattern: "\\S";
+                    };
                     readonly question: {
                         readonly type: "string";
                     };
@@ -444,7 +451,7 @@ export interface AccountHistoryEntry {
 export interface PendingResume {
     session_id: string;
     trigger: "answered_questions" | "message" | "resume";
-    resumed_from?: "interrupted" | "done" | "blocked";
+    resumed_from?: "interrupted" | "done" | "blocked" | "failed";
     text?: string;
     message_id?: string;
     /** False when the command passed --no-compact; the deferred spawn honours it. */
@@ -471,7 +478,7 @@ export interface LaneResumeRecord {
      * `hq lanes resume` only: the state the lane was in when the operator
      * resumed it (`interrupted`, `done` or `blocked`) and the text they sent.
      */
-    resumed_from?: "interrupted" | "done" | "blocked";
+    resumed_from?: "interrupted" | "done" | "blocked" | "failed";
     text?: string;
     /** False when the continued turn explicitly skipped compaction. */
     compact?: boolean;
@@ -555,6 +562,8 @@ export interface QuestionRecord {
     answer_history?: QuestionAnswer[];
 }
 export interface EnvelopeQuestion {
+    /** Optional for compatibility with existing v1 envelopes; repair prompts request it. */
+    id?: string;
     question: string;
     context: string;
     options: string[];

package/dist/lib/lanes/types.js

@@ -8,6 +8,8 @@ export const LANE_SCHEMA_VERSION = "hq-lane.v1";
 export const QUESTION_SCHEMA_VERSION = "hq-lane-question.v1";
 export const ENVELOPE_SCHEMA_VERSION = "hq-lane-envelope.v1";
 export const CONFIG_SCHEMA_VERSION = "hq-lanes-config.v1";
+/** Lane terminal reason for an envelope still invalid after its one repair turn. */
+export const ENVELOPE_INVALID_REASON = "envelope_invalid";
 /**
  * The envelope contract as a JSON schema. `parseLaneEnvelope` is the runtime
  * check; this is the text handed to a worker on the repair turn (spec §4) so
@@ -30,6 +32,7 @@ export const LANE_ENVELOPE_JSON_SCHEMA = {
                 additionalProperties: false,
                 required: ["question", "context", "options"],
                 properties: {
+                    id: { type: "string", minLength: 1, pattern: "\\S" },
                     question: { type: "string" },
                     context: { type: "string" },
                     options: { type: "array", items: { type: "string" } },
@@ -357,6 +360,14 @@ export function parseLaneEnvelope(raw) {
                 context: requireString(item.context, `questions[${index}].context`),
                 options,
             };
+            if (item.id !== undefined) {
+                if (typeof item.id !== "string" || item.id.trim().length === 0) {
+                    throw new LaneSchemaError(`Expected non-empty string for questions[${index}].id`, {
+                        field: `questions[${index}].id`,
+                    });
+                }
+                parsed.id = item.id;
+            }
             if (item.recommended !== undefined) {
                 parsed.recommended = requireString(item.recommended, `questions[${index}].recommended`);
             }

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

@@ -31,7 +31,7 @@
  * Queue admission of the next lane when a slot frees is owned by the
  * periodic reconcile pass and is out of scope here.
  */
-import { type LaneEnvelope, type LaneRecord, type LaneState } from "./types.js";
+import { ENVELOPE_INVALID_REASON, type LaneEnvelope, type LaneRecord, type LaneState } from "./types.js";
 import { type QuotaSignal } from "./quota.js";
 import { type ProviderRejection } from "./provider-rejection.js";
 import type { AdmissionHost } from "./admission.js";
@@ -50,7 +50,7 @@ export declare const WATCHER_HEARTBEAT_MS: number;
 export declare const WATCHER_OUT_MAX_BYTES: number;
 export declare const WATCHER_DECISION_EVENTS: readonly ["liveness_transition", "silence_deadline", "envelope_observed", "envelope_invalid", "envelope_repair", "classification", "terminal_write", "mesh_event", "mesh_event_failed"];
 /** Terminal reason when the envelope failed to parse after the repair turn (spec §4). */
-export declare const ENVELOPE_INVALID_REASON: "envelope_invalid";
+export { ENVELOPE_INVALID_REASON };
 export type WatcherDecisionEvent = (typeof WATCHER_DECISION_EVENTS)[number];
 export declare const WATCHER_SIGNAL_KINDS: readonly ["progress", "terminal", "silence"];
 export type WatcherSignalKind = (typeof WATCHER_SIGNAL_KINDS)[number];

package/dist/lib/lanes/watcher.js

@@ -35,7 +35,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { LanesError } from "./errors.js";
 import { raiseEnvelopeQuestions } from "./questions.js";
-import { isTerminalLaneState, parseLaneEnvelope, } from "./types.js";
+import { isTerminalLaneState, ENVELOPE_INVALID_REASON, parseLaneEnvelope, } from "./types.js";
 import { laneStories, storyStatusForEnvelope } from "./stories.js";
 import { readLane, retryUpdateLane } from "./store.js";
 import { readWorkerRunResult } from "./delivery.js";
@@ -70,7 +70,7 @@ export const WATCHER_DECISION_EVENTS = [
     "mesh_event_failed",
 ];
 /** Terminal reason when the envelope failed to parse after the repair turn (spec §4). */
-export const ENVELOPE_INVALID_REASON = "envelope_invalid";
+export { ENVELOPE_INVALID_REASON };
 export const WATCHER_SIGNAL_KINDS = ["progress", "terminal", "silence"];
 export function parseWatcherSignalKind(value) {
     if (typeof value === "string" &&

package/package.json

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