@indigoai-us/hq-cli 5.345.73 → 5.345.75

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [5.345.75] — 2026-10-10
+
+- Native delegate manifest updates now use mode 0600 on POSIX, matching the
+  shell commands and preventing the manifest from becoming readable by other
+  local users.
+- Lane lifecycle delivery, worker continuity, status-row fields, and operator-requested orphan stopping now stay enabled when their hq-flags registry rows are missing or unavailable.
+- `hq uninstall --global --runtime codex` is now idempotent: on a machine with
+  no global Codex installation it reports that there is nothing to remove and
+  exits successfully.
+- Delegate send now stops before DM delivery and reports the shell-compatible
+  error when saving the `sending` state fails.
+
+## [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/assets/scaffold/core/scripts/hq-delegate-pickup.sh

@@ -59,9 +59,13 @@ case "$STATUS" in
 esac
 
 record_pickup() { # <kind> <detail>
-  jq --arg now "$NOW" --arg k "$1" --arg d "$2" \
+  local TMP_MANIFEST
+  TMP_MANIFEST="$(mktemp "${MANIFEST}.tmp.XXXXXX")" || exit 1
+  if ! jq --arg now "$NOW" --arg k "$1" --arg d "$2" \
     '.status = "picked-up" | .pickedUpAt = $now | .pickup = {kind: $k, detail: $d, recordedAt: $now}' \
-    "$MANIFEST" > "$MANIFEST.tmp" && mv "$MANIFEST.tmp" "$MANIFEST"
+    "$MANIFEST" > "$TMP_MANIFEST" || ! mv "$TMP_MANIFEST" "$MANIFEST"; then
+    rm -f "$TMP_MANIFEST"
+  fi
   echo "hq-delegate-pickup: $NAME picked up the delegation ($1) — status advanced to 'picked-up'"
   exit 0
 }
@@ -93,7 +97,10 @@ if [ "$age_h" -lt "$WINDOW" ]; then
   exit 6
 fi
 reason="no pickup evidence from $NAME within ${WINDOW}h of send (${SENT_AT:-unknown}): no acknowledgement, no commit by $TO on ${BRANCH:-the branch}"
-jq --arg now "$NOW" --arg r "$reason" '.status = "failed" | .failedAt = $now | .failure = {reason: $r, recordedAt: $now}' \
-  "$MANIFEST" > "$MANIFEST.tmp" && mv "$MANIFEST.tmp" "$MANIFEST"
+TMP_MANIFEST="$(mktemp "${MANIFEST}.tmp.XXXXXX")" || exit 1
+if ! jq --arg now "$NOW" --arg r "$reason" '.status = "failed" | .failedAt = $now | .failure = {reason: $r, recordedAt: $now}' \
+  "$MANIFEST" > "$TMP_MANIFEST" || ! mv "$TMP_MANIFEST" "$MANIFEST"; then
+  rm -f "$TMP_MANIFEST"
+fi
 echo "hq-delegate-pickup: FAILED — $reason. Re-send with a direct ask, or hand it to someone else." >&2
 exit 5

package/dist/commands/core-delegate-w1b.js

@@ -174,6 +174,23 @@ function parseFlags(args, allowed) {
 }
 function usage(name) { return USAGE[name] ?? ""; }
 function usageFailure(name) { err(usage(name)); return 1; }
+function grantHasDanglingManifestFlag(args) {
+    for (let i = 0; i < args.length;) {
+        const key = args[i] ?? "";
+        if (key === "--yes") {
+            i += 1;
+            continue;
+        }
+        if (key === "--manifest") {
+            if (i + 1 >= args.length)
+                return true;
+            i += 2;
+            continue;
+        }
+        return false;
+    }
+    return false;
+}
 function bashPath(value) {
     if (process.platform !== "win32")
         return value;
@@ -205,6 +222,10 @@ function runBundle(args, context, onMalformedWhoami) {
     const root = context.root ?? context.cwd;
     if (args[0] !== "build")
         return usageFailure("bundle");
+    // The shell uses `shift 2` for these options. With no value at end of argv,
+    // Bash exits nonzero before it reaches the required-field diagnostics.
+    if (["--company", "--project", "--to", "--to-kind", "--to-name", "--mode"].includes(args.at(-1) ?? ""))
+        return 1;
     const parsed = parseFlags(args.slice(1), ["--company", "--project", "--to", "--to-kind", "--to-name", "--mode", "--dry-run"]);
     if (parsed.help) {
         out(usage("bundle"));
@@ -326,7 +347,7 @@ function runBundle(args, context, onMalformedWhoami) {
     const next = stories.filter((story) => !isRecord(story) || story.passes !== true)
         .sort((a, b) => Number(getPath(a, "priority", 0)) - Number(getPath(b, "priority", 0))).slice(0, 3);
     const doneList = done.map((story) => `- ${text(getPath(story, "id"))}: ${text(getPath(story, "title"))}`).join("\n");
-    const nextList = next.map((story) => `### ${text(getPath(story, "id"))}: ${text(getPath(story, "title"))}\n\n${text(getPath(story, "description"))}\n`).join("\n");
+    const nextList = next.map((story) => `### ${text(getPath(story, "id"))}: ${text(getPath(story, "title"))}\n\n${text(getPath(story, "description"))}\n`).join("\n").replace(/\n+$/, "");
     const questions = list(getPath(prd, "metadata.openQuestions", [])).map((entry) => `- ${text(entry)}`).join("\n");
     const traps = [
         ...list(getPath(prd, "metadata.securityNotes", [])),
@@ -410,6 +431,10 @@ const ACL_FILTER = `
     (.direct | type == "array") and (.exists | type == "boolean")
   `;
 function runGrant(args, context) {
+    // The shell companion's `shift 2` runs under `set -e`; a final bare
+    // --manifest exits 1 without diagnostics. Preserve that observable contract.
+    if (grantHasDanglingManifestFlag(args))
+        return 1;
     const parsed = parseFlags(args, ["--manifest", "--yes"]);
     if (parsed.help) {
         out(usage("grant"));
@@ -618,10 +643,14 @@ function runGrant(args, context) {
     out(`hq-delegate-grant: all ${prefixes.length} grants verified — manifest status advanced to 'granted'\n`);
     return 0;
 }
-function atomicCopy(source, target) {
+function atomicCopy(source, target, mode) {
     const temporary = `${target}.tmp.${process.pid}.${Math.random().toString(16).slice(2)}`;
     try {
-        fs.copyFileSync(source, temporary);
+        const contents = fs.readFileSync(source);
+        if (mode === undefined)
+            fs.writeFileSync(temporary, contents, { flag: "wx" });
+        else
+            fs.writeFileSync(temporary, contents, { flag: "wx", mode });
         moveFile(temporary, target);
     }
     catch (error) {
@@ -745,9 +774,9 @@ function runPublish(args, context) {
         if (shareSession.test(fs.readFileSync(stagedManifest, "utf8")) || shareSession.test(fs.readFileSync(stagedBrief, "utf8")))
             return fail("publish", "share-session capability in dossier; nothing published");
         fs.mkdirSync(dest, { recursive: true });
-        atomicCopy(stagedBrief, path.join(dest, "BRIEF.md"));
-        atomicCopy(stagedManifest, path.join(dest, "manifest.json"));
-        atomicCopy(stagedManifest, manifestPath);
+        atomicCopy(stagedBrief, path.join(dest, "BRIEF.md"), 0o600);
+        atomicCopy(stagedManifest, path.join(dest, "manifest.json"), 0o600);
+        atomicCopy(stagedManifest, manifestPath, 0o600);
         const push = runHq(["sync", "push", `${relative}/`, "--company", company, "--on-conflict", "keep"], context, "inherit");
         if (push.code !== 0)
             return fail("publish", "final dossier push failed; resume publication");
@@ -775,7 +804,7 @@ function runPublish(args, context) {
         const publication = { verifiedAt: currentTime(), manifestPath: `${relative}/delegation/${id}/manifest.json`, files: receipts };
         const updated = { ...canonical, publication, recipientAccess: "unconfirmed" };
         fs.writeFileSync(stagedManifest, jsonText(updated));
-        atomicCopy(stagedManifest, manifestPath);
+        atomicCopy(stagedManifest, manifestPath, 0o600);
         out("hq-delegate-publish: canonical dossier bytes verified as sender; recipient access unconfirmed\n");
         return 0;
     }
@@ -794,6 +823,10 @@ function sortedJson(value) {
     return serializeJqJson(sort(value), "compact").replace(/\n+$/, "");
 }
 function runSend(args, context) {
+    // The shell shifts two arguments for value options. Under `set -e`, a
+    // trailing option without its value exits 1 before printing diagnostics.
+    if (["--manifest", "--headline", "--note"].includes(args.at(-1) ?? ""))
+        return 1;
     const parsed = parseFlags(args, ["--manifest", "--send", "--headline", "--note"]);
     if (parsed.help) {
         out(usage("send"));
@@ -884,7 +917,7 @@ function runSend(args, context) {
             const access = jqRawPath(manifest, "repo.accessNote");
             const branchCheck = branch ? subprocess("git", ["check-ref-format", "--branch", branch], context.cwd, { stdout: "ignore", stderr: "ignore" }) : { code: 1 };
             if (branch && branchCheck.code === 0 && sha) {
-                repoSection = `## Get the code\n\nThe work lives on branch \`${branch}\` (base: \`${base}\`) at \`${sha}\`.\n\n\`\`\`bash\n# From your HQ root; clone first if the repo is not present${remote ? ` (remote: ${remote})` : ""}:\ngit -C ${quoteBash(repoPath)} fetch origin\ngit -C ${quoteBash(repoPath)} switch -- ${quoteBash(branch)}\n\`\`\`${access ? `\n\n> ${access}` : ""}`;
+                repoSection = `## Get the code\n\nThe work lives on branch \`${branch}\` (base: \`${base}\`) at \`${sha}\`.\n\n\`\`\`bash\n# From your HQ root; clone first if the repo is not present${remote ? ` (remote: ${remote})` : ""}:\ngit -C ${quoteBash(repoPath)} fetch origin\ngit -C ${quoteBash(repoPath)} switch -- ${quoteBash(branch)}\n\`\`\`${access ? `\n\n> ${access}` : "\n"}`;
             }
         }
         const secretNames = list(getPath(manifest, "secrets", [])).map((entry) => text(entry)).join(",");
@@ -906,7 +939,7 @@ function runSend(args, context) {
         if (repoSection)
             body += `${repoSection}\n\n`;
         if (secretsSection)
-            body += `${secretsSection}\n`;
+            body += `${secretsSection}\n\n`;
         if (nextSteps)
             body += `## Your next three steps\n\n${nextSteps}\n\n`;
         body += `## If something is off\n\nThe manifest and BRIEF.md are published under \`delegation/${delegationId}/\` within \`companies/${company}/projects/${project}/\`. If a pull fails or a path looks empty, report it to ${from}.\n`;
@@ -956,7 +989,12 @@ function runSend(args, context) {
         if (checksum(brief) !== checksum(path.join(path.dirname(publishedManifestPath), "BRIEF.md")))
             return fail("send", "brief changed since publication; run verification again");
         manifest.status = "sending";
-        writeJsonAtomically(manifestPath, manifest, true);
+        try {
+            writeJsonAtomically(manifestPath, manifest, true, context.atomicWriteFileSystem);
+        }
+        catch {
+            return fail("send", "could not persist sending state; no DM attempted");
+        }
         const dm = runHq(["dm", principal, headline, "--prompt-file", prompt, "--details-file", brief], context);
         if (dm.code !== 0)
             return fail("send", "hq dm delivery outcome is uncertain; status is sending, inspect DM history before retrying");
@@ -994,6 +1032,10 @@ function captureRun(run) {
     }
 }
 function runVerify(args, context) {
+    // The shell shifts a value-taking option and its value under `set -e`.
+    // A trailing option therefore exits 1 before any diagnostic is printed.
+    if (["--manifest", "--company", "--project", "--to", "--mode"].includes(args.at(-1) ?? ""))
+        return 1;
     const parsed = parseFlags(args, ["--manifest", "--dry-run", "--company", "--project", "--to", "--mode"]);
     if (parsed.help) {
         out(usage("verify"));
@@ -1051,7 +1093,7 @@ function runVerify(args, context) {
         out(`  Recipient:  ${recipient}\n  Mode:       ${mode}\n  Company:    ${company}\n  Project:    ${project}\n\n`);
         out("  Vault grants that would be written:\n");
         for (const entry of list(getPath(manifest, "vaultPrefixes", [])))
-            out(`    ${jqRawPath(entry, "permission")}\t on ${jqRawPath(entry, "prefix")}\t(${jqRawPath(entry, "reason")})\n`);
+            out(`    ${jqRawPath(entry, "permission")}\ton ${jqRawPath(entry, "prefix")}\t(${jqRawPath(entry, "reason")})\n`);
         out(`\n  Secret names that would be granted (read): ${secretNames}\n\n`);
         const repoValue = getPath(manifest, "repo");
         if (repoValue !== null && repoValue !== undefined)

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

@@ -1,11 +1,14 @@
 /** Native implementations of the five `hq core delegate` shell companions. */
+import * as fs from "node:fs";
 import { Command } from "commander";
 import { type SpawnPlan } from "../utils/windows-spawn.js";
 export declare const CORE_NATIVE_DELEGATE_FLAG = "core-native-delegate";
 export type DelegateContext = {
     cwd: string;
     root?: string;
+    atomicWriteFileSystem?: DelegateAtomicWriteFileSystem;
 };
+export type DelegateAtomicWriteFileSystem = Pick<typeof fs, "openSync" | "writeFileSync" | "closeSync" | "renameSync" | "copyFileSync" | "unlinkSync" | "rmSync">;
 type CommandResult = {
     code: number;
     stdout?: string;
@@ -38,8 +41,8 @@ export declare function rawJsonValue(value: unknown): string;
 export declare function jqRawPath(value: unknown, dottedPath: string, fallback?: unknown): string;
 export declare function jqRawPaths(value: unknown, dottedPaths: string[], fallback?: unknown): string;
 export declare function requireRecord(value: unknown, property: string): JsonRecord;
-export declare function moveFile(source: string, target: string): void;
-export declare function writeJsonAtomically(target: string, value: unknown, siblingTemp?: boolean): void;
+export declare function moveFile(source: string, target: string, fileSystem?: Pick<DelegateAtomicWriteFileSystem, "renameSync" | "copyFileSync" | "unlinkSync">): void;
+export declare function writeJsonAtomically(target: string, value: unknown, siblingTemp?: boolean, fileSystem?: DelegateAtomicWriteFileSystem): void;
 export declare function delegateDiagnosticPath(argument: string): string;
 export declare function scanSecretFiles(file: string): string[] | undefined;
 /** Fast-entry adapter; family gating and shell fallback happen before import. */

package/dist/commands/core-delegate.js

@@ -1,5 +1,6 @@
 /** Native implementations of the five `hq core delegate` shell companions. */
 import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -174,25 +175,59 @@ export function requireRecord(value, property) {
         throw new TypeError(`Cannot update non-object field ${property}`);
     return result;
 }
-export function moveFile(source, target) {
+export function moveFile(source, target, fileSystem = fs) {
     try {
-        fs.renameSync(source, target);
+        fileSystem.renameSync(source, target);
     }
     catch (error) {
         if (error.code !== "EXDEV")
             throw error;
         // The shell companion uses `mv`, which copies across filesystem boundaries.
-        fs.copyFileSync(source, target);
-        fs.unlinkSync(source);
+        fileSystem.copyFileSync(source, target);
+        fileSystem.unlinkSync(source);
     }
 }
-export function writeJsonAtomically(target, value, siblingTemp = false) {
+export function writeJsonAtomically(target, value, siblingTemp = false, fileSystem = fs) {
     const serialized = serializeJqJson(value, "pretty");
     // Native delegate JSON writers use LF on every platform.
     if (siblingTemp) {
-        const temporary = `${target}.tmp`;
-        fs.writeFileSync(temporary, serialized);
-        moveFile(temporary, target);
+        const temporary = `${target}.tmp.${randomBytes(6).toString("hex")}`;
+        let fd;
+        let descriptorOpen = false;
+        let temporaryCreated = false;
+        try {
+            fd = fileSystem.openSync(temporary, "wx", 0o600);
+            descriptorOpen = true;
+            temporaryCreated = true;
+            fileSystem.writeFileSync(fd, serialized);
+            fileSystem.closeSync(fd);
+            descriptorOpen = false;
+            moveFile(temporary, target, fileSystem);
+        }
+        catch (error) {
+            const failures = [error];
+            if (descriptorOpen && fd !== undefined) {
+                try {
+                    fileSystem.closeSync(fd);
+                    descriptorOpen = false;
+                }
+                catch (closeError) {
+                    failures.push(closeError);
+                }
+            }
+            if (temporaryCreated) {
+                try {
+                    fileSystem.rmSync(temporary, { force: true });
+                }
+                catch (cleanupError) {
+                    failures.push(cleanupError);
+                }
+            }
+            if (failures.length > 1) {
+                throw new AggregateError(failures, "Failed to write and clean up delegate manifest temporary file");
+            }
+            throw error;
+        }
         return;
     }
     const temporaryDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-delegate-"));

package/dist/commands/install-global.js

@@ -919,8 +919,10 @@ export function uninstallGlobalCodex(opts = {}) {
     const hqPointer = claudeTargets(home).hqPointer;
     const state = readCodexState(t);
     const hqRoot = state?.hqRoot ?? opts.hqRoot ?? readOrNull(hqPointer)?.trim();
-    if (!hqRoot)
-        throw new Error('No HQ global install found (no install state and no ~/.hq/root).');
+    if (!hqRoot) {
+        log('No HQ global Codex install found; nothing to remove.');
+        return [];
+    }
     const regFile = opts.registryFile ?? registryFile(registryDir(home, env));
     const claudeStillInstalled = fs.existsSync(claudeTargets(home).stateFile);
     const providerBin = path.join(home, '.hq', 'bin');

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.d.ts

@@ -158,5 +158,6 @@ export declare function pickupFailureUpdater(reasonRaw: string, details: Record<
 export declare function applyOutpostAccountPickup(hqRoot: string, laneId: string, modelDeps?: KnownModelsDeps): LaneRecord;
 export declare function cancelPendingQuestionsForLane(hqRoot: string, laneId: string, nowIso: string, operatorReason?: string): QuestionRecord[];
 export declare function stopCommittedState(state: LaneRecord["state"]): "cancelled" | "killed";
+export declare function readLaneReapStopEnabled(hqRoot: string, lane: LaneRecord, env: NodeJS.ProcessEnv): Promise<boolean>;
 export declare function registerLanesCommand(parent: Command, deps?: LanesCommandDeps): Command;
 //# sourceMappingURL=lanes.d.ts.map

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";
@@ -3392,7 +3392,7 @@ async function runCreate(ctx, opts) {
     const provider = explicitProvider ??
         profile?.meta.provider ??
         parseLaneProvider("codex");
-    const continuityEnabled = opts.worker !== undefined && await readLanesRegistryFlagFailOpen(LANE_WORKER_CONTINUITY_FLAG, { company: company ?? meshCompany, env: ctx.env });
+    const continuityEnabled = opts.worker !== undefined && await readLanesRegistryFlagFailOpen(LANE_WORKER_CONTINUITY_FLAG, { company: company ?? meshCompany, env: ctx.env, defaultValue: true });
     let workerContinuity = continuityEnabled
         ? findWorkerContinuityLane(loadAllLanes(hqRoot), {
             senior,
@@ -5456,6 +5456,7 @@ async function laneStatusFieldsForCommand(ctx, hqRoot, lane, now) {
         enabled = await readLanesRegistryFlagFailOpen(LANE_STATUS_ROW_FIELDS_FLAG, {
             ...(resolved ? { company: resolved } : {}),
             env: ctx.env,
+            defaultValue: true,
         });
     }
     catch (err) {
@@ -9365,6 +9366,16 @@ function attachJsonNoop(cmd) {
     for (const child of cmd.commands)
         attachJsonNoop(child);
 }
+export async function readLaneReapStopEnabled(hqRoot, lane, env) {
+    const resolution = resolveLaneCompany(hqRoot, lane);
+    const company = resolution.company ?? undefined;
+    return readLanesRegistryFlagFailOpen(LANE_REAP_STOP_FLAG, {
+        company,
+        ...(company ? { companyUidSource: laneCompanyUidSource(resolution.source) } : {}),
+        env,
+        defaultValue: true,
+    });
+}
 export function registerLanesCommand(parent, deps = {}) {
     const ctx = resolveDeps(deps);
     const storyHandlers = createLaneStoryHandlers({
@@ -9566,15 +9577,7 @@ export function registerLanesCommand(parent, deps = {}) {
             presenceConnected: ctx.presenceConnected ?? false,
             deps: ctx.livenessDeps,
         }),
-        stopEnabled: (lane) => {
-            const resolution = resolveLaneCompany(ctx.hqRoot(), lane);
-            const company = resolution.company ?? undefined;
-            return readLanesRegistryFlag(LANE_REAP_STOP_FLAG, {
-                company,
-                ...(company ? { companyUidSource: laneCompanyUidSource(resolution.source) } : {}),
-                env: ctx.env,
-            });
-        },
+        stopEnabled: (lane) => readLaneReapStopEnabled(ctx.hqRoot(), lane, ctx.env),
     }, wrap);
     registerLaneDropboxRepairCommand(lanes, {
         hqRoot: ctx.hqRoot,
@@ -10021,8 +10024,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/dropbox.js

@@ -595,6 +595,7 @@ export async function runDrainHook(env, input = {}, deps = {}) {
                 : await readLanesRegistryFlagFailOpen(LANE_DROPBOX_LIFECYCLE_DELIVERY_FLAG, {
                     ...(company ? { company } : {}),
                     env,
+                    defaultValue: true,
                 });
         }
         catch (err) {

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.75",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {