@indigoai-us/hq-cli 5.345.73 → 5.345.74

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.345.74] — 2026-10-10
+
+- Lane envelope repair prompts now identify parser locations and schema fields,
+  include a minimal valid envelope, and keep `next_check_at` optional. Section 8
+  loop workers receive explicit handoff enums and one same-session repair turn;
+  failed handoff summaries retain the validation error. Both behaviors have
+  default-on hq-flags kill switches.
+
 ## [5.345.73] — 2026-10-10
 - Fixed company resolution so a minimal entity liveness response is not treated as a full company record.
 

package/dist/commands/lanes-loop.js

@@ -9,6 +9,8 @@ import { raiseLaneQuestion } from "../lib/lanes/questions.js";
 import { isTerminalLaneState } from "../lib/lanes/types.js";
 import { clearLoopControllerPid, loopAdmissionPath, runLoopLane, setLoopControllerPid } from "../lib/lanes/loop.js";
 import { laneStories } from "../lib/lanes/stories.js";
+import { readLanesRegistryFlagFailOpen } from "../lib/lanes/registry-flag.js";
+import { LANE_LOOP_HANDOFF_REPAIR_FLAG } from "../lib/lanes/flag-keys.js";
 const LOOP_RUNS_REL = path.join("workspace", "lanes-runs");
 function loopRunDir(hqRoot, laneId) {
     return path.join(hqRoot, LOOP_RUNS_REL, laneId);
@@ -34,6 +36,11 @@ export async function runLaneLoopController(ctx, laneId, deps) {
     if (lane.loop_mode !== true)
         throw new LanesError("lane_not_loop_mode", `Lane ${laneId} is not a loop lane`, { lane_id: laneId });
     const runDir = loopRunDir(hqRoot, laneId);
+    const handoffRepairEnabled = await readLanesRegistryFlagFailOpen(LANE_LOOP_HANDOFF_REPAIR_FLAG, {
+        company: lane.company ?? lane.mesh_company,
+        defaultValue: true,
+        env: ctx.env,
+    });
     let initialAdmission = ctx.env.HQ_LANE_LOOP_INITIAL === "1";
     const stop = new AbortController();
     const onSignal = () => stop.abort();
@@ -43,9 +50,10 @@ export async function runLaneLoopController(ctx, laneId, deps) {
         const result = await runLoopLane({
             lane,
             runDir,
+            repairInvalidHandoff: handoffRepairEnabled,
             signal: stop.signal,
             idlePollMs: 250,
-            execute: async ({ envelope, signal, fresh, sessionId }) => {
+            execute: async ({ envelope, signal, fresh, sessionId, repairError }) => {
                 let current = readLane(hqRoot, laneId);
                 const data = envelope;
                 const storyId = typeof data.story_id === "string" && data.story_id.trim() ? data.story_id.trim() : current.story_id;
@@ -88,9 +96,21 @@ export async function runLaneLoopController(ctx, laneId, deps) {
                 const prompt = typeof data.prompt === "string" ? data.prompt :
                     `${phaseContext}\n\nPhase envelope:\n${JSON.stringify(envelope, null, 2)}`;
                 const briefPath = path.join(runDir, "brief.md");
+                const repairInstructions = repairError && data.schema === "hq-phase-envelope/v1"
+                    ? [
+                        "HANDOFF REPAIR TURN: the previous handoff failed validation.",
+                        `Exact validation error: ${repairError}`,
+                        "Return a corrected hq-phase-handoff/v1 object. Preserve every valid supplied value and extension field.",
+                        "Allowed status values: passed, failed, blocked. Allowed back_pressure values for tests, lint, typecheck, and build: pass, fail, skip.",
+                        `Minimal valid shape: ${JSON.stringify({ schema: "hq-phase-handoff/v1", story_id: String(data.story_id), phase: String(data.phase), worker_id: String(data.worker_id), status: "passed", summary: "...", files_changed: [], commits: [], back_pressure: { tests: "skip", lint: "skip", typecheck: "skip", build: "skip" }, context_for_next: "..." }, null, 2)}`,
+                    ].join("\n")
+                    : "";
                 fs.writeFileSync(briefPath, [
                     "Follow the lane worker instructions and complete this single bounded phase.",
-                    "Return the standard hq-lane-envelope.v1 envelope when the phase is complete. For a section 8 phase envelope, put a complete hq-phase-handoff/v1 object in artifacts; it must identify the requested story_id and phase and include worker_id, status, summary, files_changed, commits, back_pressure (tests/lint/typecheck/build), and context_for_next.",
+                    handoffRepairEnabled
+                        ? "Return the standard hq-lane-envelope.v1 envelope when the phase is complete. For a section 8 phase envelope, put a complete hq-phase-handoff/v1 object in artifacts. The lane envelope decision uses done/ask/blocked; handoff status uses passed/failed/blocked. Allowed handoff status values are passed, failed, blocked. Allowed back_pressure values for tests, lint, typecheck, and build are pass, fail, skip. Include story_id, phase, worker_id, summary, files_changed, commits, back_pressure, and context_for_next."
+                        : "Return the standard hq-lane-envelope.v1 envelope when the phase is complete. For a section 8 phase envelope, put a complete hq-phase-handoff/v1 object in artifacts; it must identify the requested story_id and phase and include worker_id, status, summary, files_changed, commits, back_pressure (tests/lint/typecheck/build), and context_for_next.",
+                    repairInstructions,
                     "",
                     prompt,
                 ].join("\n"));
@@ -137,6 +157,7 @@ export async function runLaneLoopController(ctx, laneId, deps) {
                         story: storyId,
                         freshThread: fresh,
                         ...(sessionId ? { loopSessionId: sessionId } : {}),
+                        ...(repairError !== undefined ? { loopHandoffRepair: true } : {}),
                         workingDirectory: worktree,
                     });
                 }

package/dist/commands/lanes-resume.d.ts

@@ -1,4 +1,5 @@
-import { type Ctx, type LaneBalanceMoveTargetOptions, type LaneResumeHandlerDeps, type LaneResumeOptions } from "./lanes-shared.js";
+import { type Ctx, type LaneBalanceMoveTargetOptions, type LaneRecord, type LaneResumeHandlerDeps, type LaneResumeOptions } from "./lanes-shared.js";
+export declare function isLoopHandoffRepairResume(lane: Pick<LaneRecord, "loop_mode" | "state" | "provider_session_id">, opts: Pick<LaneResumeOptions, "loopHandoffRepair" | "loopSessionId">): boolean;
 export declare function createLaneResumeHandlers(deps: LaneResumeHandlerDeps): {
     runClaudeBalanceMoveTarget: (ctx: Ctx, laneId: string, opts: LaneBalanceMoveTargetOptions) => Promise<void>;
     runResume: (ctx: Ctx, laneId: string, opts: LaneResumeOptions) => Promise<void>;

package/dist/commands/lanes-resume.js

@@ -10,6 +10,13 @@ import { markSpawnFailure, spawnLaneWorker } from "../lib/lanes/spawn.js";
 import { appendProjectFocusOverride, removeProjectFocusOverride } from "../lib/lanes/story-ledger.js";
 import { appendLaneFocusOverride, makeFocusOverride } from "../lib/lanes/focus-guard.js";
 import { accountMoveSummary, accountRequestKeepsCurrentLane, assertCurrentResumeAccountAvailable, hasKeepAliveProgress, recordedResumeEffort, resetKeepAliveProgress, resolveResumeEffort } from "./lanes-shared.js";
+export function isLoopHandoffRepairResume(lane, opts) {
+    return opts.loopHandoffRepair === true &&
+        lane.loop_mode === true &&
+        lane.state === "awaiting_input" &&
+        opts.loopSessionId !== undefined &&
+        opts.loopSessionId === lane.provider_session_id;
+}
 export function createLaneResumeHandlers(deps) {
     const { archiveResumeMessage, assertLaneRunsHereForAdmission, assertLaneRunsHereForOperatorMutation, assessLaneAdmission, automaticBalanceMoveHistoryReason, authorizeFailedResume, authorizeResumeProfileRepin, casUpdateLane, dispatchOutpostLaneCommand, laneIsHostedHere, laneWithRecoveredProviderSession, mintMessageId, persistClaudeAccountSelection, prepareAccountMove, printJson, recordResumeSetup, resolveResumeProfile, selectAutomaticClaudeResumeAccount, validateResumeProfileModel, withResumeHireAdmission } = deps;
     async function runClaudeBalanceMoveTarget(ctx, laneId, opts) {
@@ -156,6 +163,10 @@ export function createLaneResumeHandlers(deps) {
             throw new LanesError("effort_resume_unsupported", `Provider ${lane.provider} cannot change effort on a resumed session`, { lane_id: laneId, provider: lane.provider });
         }
         lane = laneWithRecoveredProviderSession(hqRoot, lane);
+        const loopHandoffRepair = isLoopHandoffRepairResume(lane, opts);
+        if (opts.loopHandoffRepair === true && !loopHandoffRepair) {
+            throw new LanesError("loop_handoff_repair_session_mismatch", "Loop handoff repair requires the awaiting-input loop lane's current provider session", { lane_id: laneId, state: lane.state });
+        }
         if (opts.loopSessionId !== undefined && opts.loopSessionId !== lane.provider_session_id) {
             lane = casUpdateLane(hqRoot, laneId, (current) => ({ ...current, provider_session_id: opts.loopSessionId }));
         }
@@ -192,7 +203,7 @@ export function createLaneResumeHandlers(deps) {
         const pendingQuestions = lane.state === "awaiting_input"
             ? await deps.pendingQuestionsForLane(ctx, lane)
             : [];
-        if (pendingQuestions.length > 0) {
+        if (pendingQuestions.length > 0 && !loopHandoffRepair) {
             const companySlug = lane.company?.slug ?? lane.mesh_company ?? "<company-slug>";
             const instructions = pendingQuestions.map(({ question_id, audience }) => `question ${question_id} awaits ${audience.kind}:${audience.id}; answer it with hq lanes questions answer ${question_id} --company ${companySlug} --freeform <answer>`);
             const message = `Lane ${laneId} is awaiting input. ${instructions.join("; ")}`;
@@ -632,7 +643,7 @@ export function createLaneResumeHandlers(deps) {
                                 kind: "resume",
                                 from: resumedFrom,
                                 ...(opts.freshThread === true ? { fresh: true } : {}),
-                                ...(resumedFrom === "awaiting_input" && pendingQuestions.length === 0 ? { allowAwaitingInput: true } : {}),
+                                ...(resumedFrom === "awaiting_input" && (pendingQuestions.length === 0 || loopHandoffRepair) ? { allowAwaitingInput: true } : {}),
                                 ...(opts.fromFailed === true ? { fromFailed: true } : {}),
                                 ...(failedResumeExpectedSenior !== undefined
                                     ? { expectedSenior: failedResumeExpectedSenior }

package/dist/commands/lanes-shared.d.ts

@@ -81,6 +81,8 @@ export interface LaneResumeOptions {
     workingDirectory?: string;
     /** Internal loop runner session; selects this story's saved provider session. */
     loopSessionId?: string;
+    /** Allows only a section 8 handoff repair to continue a loop lane with a pending question. */
+    loopHandoffRepair?: boolean;
     meshCompany?: string;
     profileRepinContext?: string;
     grantContext?: string;

package/dist/commands/lanes.js

@@ -42,7 +42,7 @@ import { readLanesFlagLocalOverride, readLanesRegistryFlag, readLanesRegistryFla
 import { readLaneStatusRowFields } from "../lib/lanes/status-fields.js";
 import { appendProjectFocusOverride, readProjectStoryFocusData, removeProjectFocusOverride } from "../lib/lanes/story-ledger.js";
 import { appendLaneFocusOverride, assertFocusGuardAllows, makeFocusOverride } from "../lib/lanes/focus-guard.js";
-import { LANE_FOCUS_GUARD_FLAG, LANE_FOCUS_DASHBOARD_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, LANE_PROFILE_PIN_EXHAUSTED_FALLBACK_FLAG, LANE_STATUS_ROW_FIELDS_FLAG, LANE_REAP_STOP_FLAG, LANE_REUSE_REFRESHES_PROFILE_FLAG, LANE_WORKER_CONTINUITY_FLAG, LANE_CONDUCT_LOOP_FLAG, } from "../lib/lanes/flag-keys.js";
+import { LANE_FOCUS_GUARD_FLAG, LANE_FOCUS_DASHBOARD_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, LANE_PROFILE_PIN_EXHAUSTED_FALLBACK_FLAG, LANE_STATUS_ROW_FIELDS_FLAG, LANE_REAP_STOP_FLAG, LANE_REUSE_REFRESHES_PROFILE_FLAG, LANE_WORKER_CONTINUITY_FLAG, LANE_CONDUCT_LOOP_FLAG, LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG, } from "../lib/lanes/flag-keys.js";
 import { findWorkerContinuityLane, sameLaneHost, workerContinuityPrompt } from "../lib/lanes/worker-continuity.js";
 import { enqueueLoopEnvelope, interruptLoopQueue, interruptLoopQueueForStory, loopControllerIsAlive, loopStatus, validateLoopEnvelope } from "../lib/lanes/loop.js";
 import { runLaneLoopController, startLaneLoopController } from "./lanes-loop.js";
@@ -10021,8 +10021,24 @@ export function registerLanesCommand(parent, deps = {}) {
         catch (err) {
             throw new LanesError("repair_request_invalid", `Envelope repair request is invalid JSON: ${err instanceof Error ? err.message : String(err)}`, {});
         }
+        const laneId = payload && typeof payload === "object" && !Array.isArray(payload) && typeof payload.lane_id === "string"
+            ? payload.lane_id
+            : undefined;
+        const company = laneId ? (() => { try {
+            const lane = readLane(ctx.hqRoot(), laneId);
+            return lane.company ?? lane.mesh_company;
+        }
+        catch {
+            return undefined;
+        } })() : undefined;
+        const envelopeRepairGuidanceEnabled = await readLanesRegistryFlagFailOpen(LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG, {
+            company,
+            defaultValue: true,
+            env: ctx.env,
+        });
         printJson(spawnEnvelopeRepairRequest(ctx.hqRoot(), payload, {
             env: ctx.env,
+            envelopeRepairGuidanceEnabled,
             hostname: ctx.hostname(),
             existsSync: ctx.existsSync,
             spawnProcess: ctx.spawnProcess,

package/dist/lib/lanes/flag-keys.d.ts

@@ -44,4 +44,6 @@ export declare const LANE_REAP_STOP_FLAG = "lanes.reap-stop";
 export declare const LANE_WORKER_CONTINUITY_FLAG = "lanes.worker-continuity";
 /** Kill switch for conduct loop lanes; absence or read failure keeps it enabled. */
 export declare const LANE_CONDUCT_LOOP_FLAG = "lanes.conduct-loop";
+export declare const LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG = "lanes.envelope-repair-guidance";
+export declare const LANE_LOOP_HANDOFF_REPAIR_FLAG = "lanes.loop-handoff-repair";
 //# sourceMappingURL=flag-keys.d.ts.map

package/dist/lib/lanes/flag-keys.js

@@ -44,4 +44,6 @@ export const LANE_REAP_STOP_FLAG = "lanes.reap-stop";
 export const LANE_WORKER_CONTINUITY_FLAG = "lanes.worker-continuity";
 /** Kill switch for conduct loop lanes; absence or read failure keeps it enabled. */
 export const LANE_CONDUCT_LOOP_FLAG = "lanes.conduct-loop";
+export const LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG = "lanes.envelope-repair-guidance";
+export const LANE_LOOP_HANDOFF_REPAIR_FLAG = "lanes.loop-handoff-repair";
 //# sourceMappingURL=flag-keys.js.map

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

@@ -95,6 +95,7 @@ export interface LoopExecutionContext {
     signal: AbortSignal;
     sessionId?: string;
     fresh: boolean;
+    repairError?: string;
 }
 export interface LoopExecutionResult {
     output: string;
@@ -116,6 +117,7 @@ export interface LoopRunnerOptions {
     now?: () => Date;
     idlePollMs?: number;
     signal?: AbortSignal;
+    repairInvalidHandoff?: boolean;
 }
 export interface LoopRunSummary {
     state: "stopped" | "parked" | "aborted";

package/dist/lib/lanes/loop.js

@@ -750,7 +750,7 @@ export async function runLoopLane(options) {
         if (envelope.kind === "stop") {
             const stopped = { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "stopped", started_at: record.queued_at, finished_at: now().toISOString() };
             try {
-                writeResultAt(options.runDir, file, record, stopped);
+                writeResultAt(options.runDir, file, record, stopped, options.repairInvalidHandoff !== false);
                 persistStatus(options.runDir, options.lane.lane_id, { state: "stopped", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
             }
             catch (error) {
@@ -811,7 +811,7 @@ export async function runLoopLane(options) {
             if (timer.signal.aborted)
                 throw timer.signal.reason;
             const finishedAt = now().toISOString();
-            const success = {
+            let success = {
                 schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "done", started_at: startedAt, finished_at: finishedAt,
                 output: result.output, ...(result.sessionId ? { session_id: result.sessionId } : {}),
                 ...(previousSession && !fresh && !fallback ? { resumed: true } : { resumed: false }),
@@ -820,17 +820,55 @@ export async function runLoopLane(options) {
             if (envelope.schema === PHASE_ENVELOPE_SCHEMA) {
                 let handoff;
                 try {
-                    handoff = JSON.parse(result.output);
-                }
-                catch {
-                    throw new Error("section 8 phase result is not valid JSON");
+                    try {
+                        handoff = JSON.parse(result.output);
+                    }
+                    catch {
+                        throw new Error("section 8 phase result is not valid JSON");
+                    }
+                    const validated = validateSection8Handoff(handoff, envelope);
+                    if (validated.worker_id !== envelope.worker_id) {
+                        throw new Error("handoff worker_id must match the queued phase envelope");
+                    }
                 }
-                const validated = validateSection8Handoff(handoff, envelope);
-                if (validated.worker_id !== envelope.worker_id) {
-                    throw new Error("handoff worker_id must match the queued phase envelope");
+                catch (validationError) {
+                    if (options.repairInvalidHandoff !== false && !timer.signal.aborted) {
+                        const repairError = validationError instanceof Error ? validationError.message : String(validationError);
+                        const repaired = await options.execute({
+                            lane: options.lane,
+                            envelope,
+                            envelopeId: record.envelope_id,
+                            signal: timer.signal,
+                            fresh: false,
+                            ...(result.sessionId ? { sessionId: result.sessionId } : {}),
+                            repairError,
+                        });
+                        if (timer.signal.aborted)
+                            throw timer.signal.reason;
+                        let repairedHandoff;
+                        try {
+                            repairedHandoff = JSON.parse(repaired.output);
+                        }
+                        catch {
+                            throw new Error(`handoff repair returned invalid JSON: ${repairError}`);
+                        }
+                        const repairedValidated = validateSection8Handoff(repairedHandoff, envelope);
+                        if (repairedValidated.worker_id !== envelope.worker_id) {
+                            throw new Error(`handoff worker_id must match the queued phase envelope: ${repairError}`);
+                        }
+                        result = repaired;
+                        success = {
+                            ...success,
+                            output: repaired.output,
+                            ...(repaired.sessionId ? { session_id: repaired.sessionId } : {}),
+                        };
+                    }
+                    else {
+                        throw validationError;
+                    }
                 }
             }
-            writeResultAt(options.runDir, file, record, success);
+            writeResultAt(options.runDir, file, record, success, options.repairInvalidHandoff !== false);
             if (result.sessionId) {
                 sessions.set(sessionKey, result.sessionId);
                 atomicJson(sessionsPath(options.runDir), Object.fromEntries(sessions));
@@ -853,7 +891,7 @@ export async function runLoopLane(options) {
             }
             if (!timer.signal.aborted) {
                 const failure = error instanceof Error ? error.message : String(error);
-                writeResultAt(options.runDir, file, record, { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "failed", started_at: startedAt, finished_at: now().toISOString(), error: failure });
+                writeResultAt(options.runDir, file, record, { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "failed", started_at: startedAt, finished_at: now().toISOString(), error: failure }, options.repairInvalidHandoff !== false);
                 completed += 1;
                 persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
                 continue;
@@ -880,7 +918,7 @@ export async function runLoopLane(options) {
             const message = error instanceof Error ? error.message : String(error);
             const questionId = options.raiseQuestion ? randomUUID() : undefined;
             const result = { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "stalled", started_at: startedAt, finished_at: now().toISOString(), error: message, ...(questionId ? { question_id: questionId } : {}) };
-            writeResultAt(options.runDir, file, record, result);
+            writeResultAt(options.runDir, file, record, result, options.repairInvalidHandoff !== false);
             persistStatus(options.runDir, options.lane.lane_id, { state: "parked", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
             completed += 1;
             try {
@@ -921,7 +959,7 @@ function appendJournal(runDir, value) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.appendFileSync(file, `${JSON.stringify(value)}\n`, { mode: 0o600 });
 }
-function writeResultAt(runDir, activeFile, record, result) {
+function writeResultAt(runDir, activeFile, record, result, includeHandoffValidationError = true) {
     const localPath = path.join(resultsDir(runDir), resultName(record.envelope_id));
     atomicJson(localPath, result);
     const envelope = record.envelope;
@@ -939,7 +977,7 @@ function writeResultAt(runDir, activeFile, record, result) {
                         schema: PHASE_HANDOFF_SCHEMA,
                         story_id: String(envelope.story_id), phase: String(envelope.phase),
                         worker_id: String(envelope.worker_id), status: stalled ? "blocked" : "failed",
-                        summary: stalled ? "Phase stalled twice and needs operator direction." : "Phase execution failed.",
+                        summary: stalled ? "Phase stalled twice and needs operator direction." : includeHandoffValidationError ? `Phase execution failed: ${result.error ?? "unknown error"}` : "Phase execution failed.",
                         files_changed: [], commits: [],
                         back_pressure: { tests: "skip", lint: "skip", typecheck: "skip", build: "skip" },
                         context_for_next: [result.error ?? result.status, ...(result.question_id ? [`Decision question: ${result.question_id}`] : [])].join("\n"),

package/dist/lib/lanes/reconcile.js

@@ -24,7 +24,7 @@ import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecor
 import { appendCappedHistory, lanesStoreRoot, parseLaneRecord, parseQuestionRecord, readLane, retryUpdateLane, readQuestion, listQuestionIds, updateLane, updateQuestion, } from "./store.js";
 import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyObservation, recordCpuBusyObservation, throttleStatePath, writeThrottleState, } from "./throttle.js";
 import { readLanesRegistryFlag, readLanesRegistryFlagFailOff, readLanesRegistryFlagFailOpen } from "./registry-flag.js";
-import { LANE_BLOCKED_ESCALATION_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_KEEP_ALIVE_DUE_WAKE_PRECISE_FLAG, LANE_LEAD_ADMISSION_PRIORITY_FLAG, LANE_QUOTA_ACCOUNT_FAILOVER_FLAG, } from "./flag-keys.js";
+import { LANE_BLOCKED_ESCALATION_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_KEEP_ALIVE_DUE_WAKE_PRECISE_FLAG, LANE_LEAD_ADMISSION_PRIORITY_FLAG, LANE_QUOTA_ACCOUNT_FAILOVER_FLAG, LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG, } from "./flag-keys.js";
 import { checkLaneDiskSpace, configuredCodexRolloutHomes, laneDiskAccount, retainCodexRollouts } from "./disk-guard.js";
 import { laneCompanyUidSource, resolveLaneCompany } from "./lane-company.js";
 import { appendDropboxMessageOnce, appendDropboxMessageOnceAtPath } from "./dropbox.js";
@@ -1700,7 +1700,13 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                     }
                     const spawnRepair = deps.spawnRepair ??
                         ((root, repairLane, input) => spawnEnvelopeRepair(root, repairLane, input, spawnDepsForHost(deps)));
-                    const repair = decideEnvelopeRepair(hqRoot, lane.lane_id, repairCandidate, nowMs, spawnRepair, () => undefined);
+                    const repairGuidanceFlagReader = deps.readRegistryFlag ?? readLanesRegistryFlagFailOpen;
+                    const repairGuidanceEnabled = await repairGuidanceFlagReader(LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG, {
+                        company: resolveLaneCompany(hqRoot, classified).company,
+                        defaultValue: true,
+                        env: deps.spawnLaneDeps?.env ?? deps.env ?? process.env,
+                    });
+                    const repair = decideEnvelopeRepair(hqRoot, lane.lane_id, repairCandidate, nowMs, spawnRepair, () => undefined, repairGuidanceEnabled);
                     if (repair.action === "spawned") {
                         armLaneWatcher(hqRoot, lane.lane_id, spawnDepsForHost(deps));
                         summary.heartbeats.push(`${lane.lane_id}:envelope-repair`);

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

@@ -94,6 +94,7 @@ export interface SpawnLaneDeps {
     locateTranscript?: (home: string, sessionId: string) => string | null;
     /** Internal loop-lane override for the single provider turn's working directory. */
     workingDirectory?: string;
+    envelopeRepairGuidanceEnabled?: boolean;
 }
 export interface ProviderLaunch {
     command: string;
@@ -210,12 +211,12 @@ export declare function resumePrompt(input: {
         second_error?: string;
     };
 }): string;
-/** Spec §4: the one repair turn. Schema, parser error, raw text, JSON only. */
 export declare function envelopeRepairPrompt(input: {
     envelopePath: string;
     error: string;
     rawText: string;
     missing?: boolean;
+    detailedGuidance?: boolean;
 }): string;
 export interface ProviderResumeInput {
     session_id: string;
@@ -319,6 +320,7 @@ export interface EnvelopeRepairSpawnInput {
     rawText: string;
     /** True when this run never wrote its expected envelope file. */
     missing?: boolean;
+    detailedGuidance?: boolean;
     /** Repair-only warning hook for profile metadata ignored during recovery. */
     onProfileWarning?: (fields: readonly string[]) => void;
 }

package/dist/lib/lanes/spawn.js

@@ -1375,6 +1375,42 @@ export function resumePrompt(input) {
     return parts.join("\n\n");
 }
 /** Spec §4: the one repair turn. Schema, parser error, raw text, JSON only. */
+function recoverRawJsonArrayField(rawText, field) {
+    const match = new RegExp(`"${field}"\\s*:\\s*\\[`).exec(rawText);
+    if (!match)
+        return undefined;
+    const start = match.index + match[0].lastIndexOf("[");
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < rawText.length; index += 1) {
+        const char = rawText[index];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"')
+            inString = true;
+        else if (char === "[")
+            depth += 1;
+        else if (char === "]" && --depth === 0) {
+            try {
+                const parsed = JSON.parse(rawText.slice(start, index + 1));
+                return Array.isArray(parsed) ? parsed : undefined;
+            }
+            catch {
+                process.stderr.write("hq lanes: envelope repair could not recover the supplied JSON array\n");
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+}
 export function envelopeRepairPrompt(input) {
     const maxRawTextChars = 24_000;
     const rawText = input.rawText.length <= maxRawTextChars
@@ -1393,11 +1429,94 @@ export function envelopeRepairPrompt(input) {
                 `Output only that JSON. Do not add keys the schema does not name, and do not resume the task.`,
         ].join("\n\n");
     }
+    if (input.detailedGuidance === false) {
+        return [
+            `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:", rawText,
+            `Write the corrected JSON object to ${input.envelopePath}, overwriting it. Output only that JSON. Do not add keys the schema does not name, and do not resume the task.`,
+        ].join("\n\n");
+    }
+    const location = input.error.match(/position (\d+) \(line (\d+) column (\d+)\)/i);
+    const lineColumn = input.error.match(/line (\d+) column (\d+)/i);
+    const offendingToken = location
+        ? input.rawText[Number(location[1])] ?? "<end of file>"
+        : undefined;
+    const preciseError = location || lineColumn
+        ? `${input.error}\nFault location: line ${location?.[2] ?? lineColumn?.[1]}, column ${location?.[3] ?? lineColumn?.[2]}.${offendingToken === undefined ? "" : ` Offending token: ${JSON.stringify(offendingToken)}.`}`
+        : input.error;
+    const syntaxFault = /unexpected (?:token|end)|property name.*in JSON at position|JSON at position \d+|position \d+/i.test(input.error);
+    const originalDecision = input.rawText.match(/"decision"\s*:\s*"(done|ask|blocked)"/)?.[1] ?? "done";
+    const originalCompleteMatch = input.rawText.match(/"story_complete"\s*:\s*(true|false)/)?.[1];
+    const originalComplete = originalCompleteMatch === undefined ? undefined : originalCompleteMatch === "true";
+    const originalStatus = input.rawText.match(/"story_status"\s*:\s*"(queued|in_progress|review|done)"/)?.[1];
+    let originalObject = {};
+    try {
+        const parsed = JSON.parse(input.rawText);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed))
+            originalObject = parsed;
+    }
+    catch {
+        process.stderr.write("hq lanes: envelope repair is recovering values from invalid JSON\n");
+    }
+    const rawStringField = (field) => {
+        const token = input.rawText.match(new RegExp(`"${field}"\\s*:\\s*("(?:\\\\.|[^"\\\\])*")`))?.[1];
+        if (!token)
+            return undefined;
+        try {
+            return JSON.parse(token);
+        }
+        catch {
+            process.stderr.write(`hq lanes: envelope repair could not recover the supplied ${field} string\n`);
+            return undefined;
+        }
+    };
+    const minimalEnvelope = {
+        schema_version: "hq-lane-envelope.v1",
+        decision: originalDecision,
+        summary: rawStringField("summary") || "Describe the completed work or remaining issue.",
+        story_status: originalComplete === true ? "done" : originalComplete === false && originalStatus === "done" ? "review" : originalStatus ?? "review",
+        artifacts: [],
+    };
+    const originalCompleteReason = rawStringField("story_complete_reason");
+    if (originalComplete !== undefined)
+        minimalEnvelope.story_complete = originalComplete;
+    if (originalComplete !== undefined || originalCompleteReason !== undefined) {
+        minimalEnvelope.story_complete_reason = originalCompleteReason || (originalComplete === true ? "State what was delivered and how it was verified." : "State what remains missing.");
+    }
+    const originalArtifacts = Array.isArray(originalObject.artifacts)
+        ? originalObject.artifacts
+        : recoverRawJsonArrayField(input.rawText, "artifacts");
+    if (originalArtifacts)
+        minimalEnvelope.artifacts = originalArtifacts;
+    if (originalDecision === "ask") {
+        const originalQuestion = Array.isArray(originalObject.questions) && originalObject.questions[0] && typeof originalObject.questions[0] === "object"
+            ? originalObject.questions[0]
+            : {};
+        const options = Array.isArray(originalQuestion.options) && originalQuestion.options.every((item) => typeof item === "string")
+            ? originalQuestion.options
+            : ["Option A", "Option B"];
+        minimalEnvelope.questions = [{
+                id: typeof originalQuestion.id === "string" && originalQuestion.id.trim() ? originalQuestion.id : "repair-question",
+                question: typeof originalQuestion.question === "string" && originalQuestion.question.trim() ? originalQuestion.question : rawStringField("question") || "What decision is needed?",
+                context: typeof originalQuestion.context === "string" && originalQuestion.context.trim() ? originalQuestion.context : rawStringField("context") || "State the unresolved choice.",
+                options,
+            }];
+    }
+    if (originalDecision === "blocked")
+        minimalEnvelope.blocked_reason = rawStringField("blocked_reason") || "State the external blocker.";
     return [
         `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.",
+        `Exact validation error: ${preciseError}`,
+        syntaxFault
+            ? "This is a JSON syntax error. Fix the exact reported line and column and remove the offending token or delimiter. Do not add trailing commas."
+            : "This is a schema validation error. Correct the named field path and use only the allowed value(s) stated in the error.",
+        "Keep every supplied value that is already valid. Do not invent next_check_at; it is optional. For decision=ask include non-empty id, question, and context fields; for decision=blocked include blocked_reason.",
+        "Minimal valid envelope shape (retain your original decision and values when valid):",
+        JSON.stringify(minimalEnvelope, null, 2),
         "Schema:",
         JSON.stringify(LANE_ENVELOPE_JSON_SCHEMA, null, 2),
         "Your previous output was:",
@@ -2894,6 +3013,7 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
         error: input.error,
         rawText: input.rawText,
         missing: input.missing,
+        detailedGuidance: input.detailedGuidance ?? deps.envelopeRepairGuidanceEnabled,
     });
     const command = buildProviderCommand(lane.provider, {
         hqRoot,

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

@@ -800,6 +800,10 @@ export interface LaneEnvelopeRepair {
     skipped_reason?: string;
     /** Envelope slot the repair was asked to rewrite. */
     envelope_ref?: string;
+    /** Absolute raw envelope retained when the repair output also fails JSON parsing. */
+    raw_envelope_path?: string;
+    /** Recoverable artifacts from malformed raw JSON, surfaced by lanes show --json. */
+    artifacts?: unknown[];
     at: string;
 }
 export interface AccountHistoryEntry {

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

@@ -247,18 +247,7 @@ export type EnvelopeRepairDecision = {
     action: "give_up";
     errors: string[];
 };
-/**
- * Spec §4 repair decision for an exited worker whose expected envelope is
- * invalid or missing. First failure on a resumable provider with a recorded
- * session id: record `envelope_repair` on the lane and spawn the repair turn.
- * A provider with no session resume gets the same single attempt as a fresh
- * turn for invalid files. Anything else (already attempted, no session id on a
- * resumable provider, non-running lane, spawn failure): give up with every
- * error collected. The caller preserves the normal interrupted classification
- * for a missing file and uses `envelope_invalid` only for an existing invalid
- * file.
- */
-export declare function decideEnvelopeRepair(hqRoot: string, laneId: string, latest: LatestEnvelopeFile, nowMs: number, spawnRepair: NonNullable<WatcherLoopDeps["spawnRepair"]>, logDecision: (record: Record<string, unknown>) => void): EnvelopeRepairDecision;
+export declare function decideEnvelopeRepair(hqRoot: string, laneId: string, latest: LatestEnvelopeFile, nowMs: number, spawnRepair: NonNullable<WatcherLoopDeps["spawnRepair"]>, logDecision: (record: Record<string, unknown>) => void, repairGuidanceEnabled?: boolean): EnvelopeRepairDecision;
 /** Exported so tests can prove the watcher reads the live record, not spawn env. */
 export declare function laneIdentityFromRecord(hqRoot: string, laneId: string): {
     lane_id: string;

package/dist/lib/lanes/watcher.js

@@ -49,13 +49,13 @@ import { loadLanesConfig, providerProgressEventMinIntervalMs, providerQuotaDefau
 import { resolveAdmissionHost as resolveProcessAdmissionHost } from "./admission-host.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneProgressEvent, emitLaneTerminalStateEvent, laneStoryStatusSuppressionKey, progressEventDue, } from "./mesh-events.js";
 import { envelopeQuestionId } from "./questions.js";
-import { readLanesRegistryFlag } from "./registry-flag.js";
+import { readLanesRegistryFlag, readLanesRegistryFlagFailOpen } from "./registry-flag.js";
 import { laneCompanyUidSource, resolveLaneCompany } from "./lane-company.js";
 import { blockerFreshnessFingerprint, resolveBlockerFreshnessForLane, } from "./blocker-freshness.js";
 import { krFreshnessFingerprint, resolveKrFreshnessForLane, } from "./kr-freshness.js";
 import { managerStatusWasWritten, readStatusSnapshot, resolveManagerStatusTarget, } from "./manager-status-gate.js";
 import { LEAD_LANE_KEEP_ALIVE_FIRST_RESUME_SETTLE_MS, LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG, LEAD_LANE_KEEP_ALIVE_TERMINAL_TRIGGER_FLAG, queueLaneTerminalResume, queueManagerStatusGateResume, } from "./keep-alive.js";
-import { LANE_ENVELOPE_REPAIR_CONTINUE_FLAG } from "./flag-keys.js";
+import { LANE_ENVELOPE_REPAIR_CONTINUE_FLAG, LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG } from "./flag-keys.js";
 import { monitorSessionDir } from "../monitor.js";
 import { laneRunDir, missingPidProbe, probePidRecord, readPidRecord, readProcStarttime, readSpawnManifest, envelopeRepairMode, spawnEnvelopeRepair, writePidRecord, retryLaneOnAlternateAccount, } from "./spawn.js";
 /** Spec §5.7: no signal for 20 minutes while the process is still alive. */
@@ -1574,7 +1574,13 @@ async function runWatcherLoopOwned(hqRoot, laneId, deps) {
             const missingRepairAllowed = !repairCandidate.missing ||
                 (lane !== null && envelopeRepairMode(lane.provider) === "resume");
             if (missingRepairAllowed) {
-                const repair = decideEnvelopeRepair(hqRoot, laneId, repairCandidate, now(), spawnRepair, logDecision);
+                const repairLane = readLaneSoft(hqRoot, laneId);
+                const repairGuidanceEnabled = await readLanesRegistryFlagFailOpen(LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG, {
+                    company: repairLane?.company ?? repairLane?.mesh_company,
+                    defaultValue: true,
+                    env: process.env,
+                });
+                const repair = decideEnvelopeRepair(hqRoot, laneId, repairCandidate, now(), spawnRepair, logDecision, repairGuidanceEnabled);
                 if (repair.action === "spawned") {
                     lastSignalMs = now();
                     lastAlive = null;
@@ -1941,7 +1947,43 @@ async function runWatcherLoopOwned(hqRoot, laneId, deps) {
  * for a missing file and uses `envelope_invalid` only for an existing invalid
  * file.
  */
-export function decideEnvelopeRepair(hqRoot, laneId, latest, nowMs, spawnRepair, logDecision) {
+function recoverRawEnvelopeArtifacts(rawText) {
+    const match = /"artifacts"\s*:\s*\[/.exec(rawText);
+    if (!match)
+        return undefined;
+    const start = match.index + match[0].lastIndexOf("[");
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < rawText.length; index += 1) {
+        const char = rawText[index];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"')
+            inString = true;
+        else if (char === "[")
+            depth += 1;
+        else if (char === "]" && --depth === 0) {
+            try {
+                const parsed = JSON.parse(rawText.slice(start, index + 1));
+                return Array.isArray(parsed) ? parsed : undefined;
+            }
+            catch {
+                process.stderr.write("hq lanes watcher: could not recover artifacts from the invalid envelope\n");
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+}
+export function decideEnvelopeRepair(hqRoot, laneId, latest, nowMs, spawnRepair, logDecision, repairGuidanceEnabled = true) {
     const at = new Date(nowMs).toISOString();
     const error = latest.error ?? "unparseable envelope";
     const lane = readLaneSoft(hqRoot, laneId);
@@ -1964,10 +2006,14 @@ export function decideEnvelopeRepair(hqRoot, laneId, latest, nowMs, spawnRepair,
         // The repair turn ran and its output does not parse either.
         if (prior.attempted) {
             const errors = [prior.first_error, error];
+            let artifacts;
+            if (repairGuidanceEnabled) {
+                artifacts = recoverRawEnvelopeArtifacts(latest.text);
+            }
             try {
                 retryUpdateLane(hqRoot, laneId, "watcher", (current) => ({
                     ...current,
-                    envelope_repair: { ...prior, succeeded: false, second_error: error },
+                    envelope_repair: { ...prior, succeeded: false, second_error: error, ...(repairGuidanceEnabled ? { raw_envelope_path: latest.path } : {}), ...(artifacts ? { artifacts } : {}) },
                 }));
             }
             catch (err) {
@@ -1993,6 +2039,7 @@ export function decideEnvelopeRepair(hqRoot, laneId, latest, nowMs, spawnRepair,
     const base = {
         first_error: error,
         envelope_ref: repairRef,
+        ...(repairGuidanceEnabled ? { raw_envelope_path: latest.path } : {}),
         at,
     };
     if (skipped !== undefined) {
@@ -2008,6 +2055,7 @@ export function decideEnvelopeRepair(hqRoot, laneId, latest, nowMs, spawnRepair,
             error,
             rawText: latest.text,
             missing: latest.missing,
+            detailedGuidance: repairGuidanceEnabled,
             onProfileWarning: (fields) => {
                 logDecision({
                     event: "envelope_repair",

package/package.json

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