@indigoai-us/hq-cli 5.345.161 → 5.345.162

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

@@ -48,6 +48,10 @@ export interface LoopStatus {
     stall_counts: Record<string, number>;
     pid?: number;
     updated_at: string;
+    handoff_hold?: {
+        envelope_id: string;
+        question_id: string;
+    };
 }
 export interface LoopResult {
     schema_version: typeof LOOP_SCHEMA;
@@ -61,6 +65,7 @@ export interface LoopResult {
     resumed?: boolean;
     fresh_fallback?: boolean;
     question_id?: string;
+    hold_reason?: "handoff_needs_repair";
     decision?: {
         question_id: string;
         choice: string;
@@ -112,6 +117,7 @@ export interface LoopRunnerOptions {
         attempt: number;
         error: string;
         questionId: string;
+        reason?: "handoff_needs_repair";
     }): Promise<void> | void;
     defaultDeadlineSeconds?: number;
     now?: () => Date;
@@ -131,8 +137,19 @@ interface StoredEnvelope {
     queued_at: string;
     deadline_budget_seconds?: number;
     stall_attempts?: number;
+    accepted_handoff?: {
+        output: string;
+        sha256: string;
+    };
+    handoff_retry?: boolean;
     envelope: LoopEnvelope;
 }
+export declare const HANDOFF_HOLD_CHOICES: readonly ["Use the repaired handoff without running the phase again", "Retry the phase; I understand external effects may repeat", "Keep this phase held"];
+export declare function loopHandoffHoldIdentity(runDir: string): {
+    envelope_id: string;
+    question_id: string;
+    unresolved: boolean;
+} | undefined;
 /** Validate both hq-cli phase envelopes and the conduct protocol §8 shape. */
 export declare function validateLoopEnvelope(value: unknown): LoopEnvelope;
 export declare function validateSection8Handoff(value: unknown, envelope: Section8PhaseEnvelope): Section8Handoff;

package/dist/lib/lanes/loop.js

@@ -1,5 +1,5 @@
 /** Durable envelope queue and runtime primitives for conduct worker lanes. */
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { providerSupportsSessionResume } from "./delivery.js";
@@ -14,6 +14,174 @@ export function loopAdmissionPath(state, hasPendingResume, initialAdmission) {
         return "deferred";
     return "resume";
 }
+export const HANDOFF_HOLD_CHOICES = [
+    "Use the repaired handoff without running the phase again",
+    "Retry the phase; I understand external effects may repeat",
+    "Keep this phase held",
+];
+function handoffHoldPath(runDir) { return path.join(runDir, "loop", "handoff-hold.json"); }
+function readHandoffHold(runDir) {
+    const file = handoffHoldPath(runDir);
+    if (!fs.existsSync(file))
+        return undefined;
+    const hold = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readHandoffBytes(file, LOOP_ENVELOPE_LIMIT * 8)));
+    if (!isRecord(hold) || hold.schema !== "hq-loop-handoff-hold.v1" || !nonEmpty(hold.envelope_id) || !nonEmpty(hold.question_id)) {
+        throw new Error("Invalid durable handoff hold; operator investigation required");
+    }
+    return hold;
+}
+async function notifyHandoffHold(options, hold, envelope) {
+    if (hold.notified || hold.resolution || !options.raiseQuestion)
+        return;
+    const record = envelope ? undefined : ["stalled", "active"].flatMap((dir) => envelopeFiles(path.join(options.runDir, "loop", dir)))
+        .map(fileEnvelope).find((entry) => entry.envelope_id === hold.envelope_id);
+    const heldEnvelope = envelope ?? record?.envelope;
+    if (!heldEnvelope)
+        throw new Error("Held handoff envelope is missing; cannot deliver its repair question");
+    await options.raiseQuestion({ envelope: heldEnvelope, envelopeId: hold.envelope_id, attempt: 1, error: hold.error, questionId: hold.question_id, reason: "handoff_needs_repair" });
+    const current = readHandoffHold(options.runDir);
+    if (current?.question_id === hold.question_id)
+        atomicJson(handoffHoldPath(options.runDir), { ...current, notified: true });
+}
+export function loopHandoffHoldIdentity(runDir) {
+    const hold = readHandoffHold(runDir);
+    return hold ? { envelope_id: hold.envelope_id, question_id: hold.question_id, unresolved: !hold.resolution } : undefined;
+}
+function readHandoffBytes(file, limit = LOOP_ENVELOPE_LIMIT) {
+    const before = fs.lstatSync(file);
+    if (!before.isFile())
+        throw new Error("Repaired handoff must be a bounded regular file");
+    if (!Number.isSafeInteger(before.ino) || before.ino <= 0 || !Number.isSafeInteger(before.dev))
+        throw new Error("Cannot establish handoff file identity on this filesystem");
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = fs.fstatSync(fd);
+        const current = fs.lstatSync(file);
+        if (!current.isFile() || stat.dev !== before.dev || stat.ino !== before.ino || current.dev !== stat.dev || current.ino !== stat.ino)
+            throw new Error("Handoff file identity changed while opening it");
+        if (!stat.isFile() || stat.size > limit)
+            throw new Error("Repaired handoff must be a bounded regular file");
+        const bytes = Buffer.alloc(limit + 1);
+        let count = 0;
+        while (count < bytes.length) {
+            const read = fs.readSync(fd, bytes, count, bytes.length - count, null);
+            if (read === 0)
+                break;
+            count += read;
+        }
+        if (count > limit)
+            throw new Error("Repaired handoff exceeds the 1 MiB limit");
+        return bytes.subarray(0, count);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function validateAcceptedHandoff(output, envelope) {
+    if (Buffer.byteLength(output, "utf8") > LOOP_ENVELOPE_LIMIT)
+        throw new Error("Repaired handoff exceeds the 1 MiB limit");
+    if (envelope.schema !== PHASE_ENVELOPE_SCHEMA)
+        throw new Error("Repair hold requires a section 8 phase");
+    const phase = envelope;
+    const handoff = validateSection8Handoff(JSON.parse(output), phase);
+    if (handoff.worker_id !== phase.worker_id || handoff.status !== "passed") {
+        throw new Error("Repaired handoff must match the worker and have passed status");
+    }
+    const criteria = phase.acceptance_criteria;
+    if (!Array.isArray(criteria) || !criteria.every((item) => typeof item === "string"))
+        throw new Error("Held phase requires string acceptance criteria");
+    if (!Array.isArray(handoff.ac_evidence))
+        throw new Error("Repaired handoff requires acceptance-criterion evidence");
+    for (let index = 0; index < criteria.length; index += 1) {
+        const evidence = handoff.ac_evidence.filter((item) => isRecord(item) && item.index === index);
+        if (evidence.length !== 1)
+            throw new Error(`Repaired handoff requires exactly one evidence entry for criterion ${index}`);
+        const item = evidence[0];
+        if (item.criterion !== criteria[index] || item.met !== true || !nonEmpty(item.evidence)) {
+            throw new Error(`Repaired handoff must copy criterion ${index} verbatim with met=true and string evidence`);
+        }
+    }
+    for (const item of handoff.ac_evidence) {
+        if (!isRecord(item) || !Number.isInteger(item.index) || Number(item.index) < 0 || Number(item.index) >= criteria.length) {
+            throw new Error("Repaired handoff contains an unknown criterion index");
+        }
+    }
+    return handoff;
+}
+function applyHandoffHoldAnswer(input) {
+    const release = acquireEnqueueLock(input.runDir);
+    try {
+        const hold = readHandoffHold(input.runDir);
+        if (!hold || hold.question_id !== input.questionId)
+            throw new Error("Handoff hold identity changed");
+        if (!HANDOFF_HOLD_CHOICES.includes(input.choice))
+            throw new Error("Choose an explicit handoff repair disposition");
+        if (loopStatus(input.runDir, path.basename(input.runDir)).state === "stopped")
+            throw new Error("An intentionally stopped loop cannot resume from a handoff answer");
+        if (fs.existsSync(path.join(input.runDir, "loop", "runner.lock")))
+            throw new Error("Handoff controller has not released its lease yet; retry the same answer after it exits");
+        const resultPath = path.join(resultsDir(input.runDir), resultName(hold.envelope_id));
+        const result = fs.existsSync(resultPath) ? readJson(resultPath) : undefined;
+        if (input.choice === HANDOFF_HOLD_CHOICES[2]) {
+            if (hold.resolution)
+                throw new Error("A handoff disposition is already being committed");
+            if (isRecord(result))
+                atomicJson(resultPath, { ...result, decision: { question_id: input.questionId, choice: input.choice, at: input.at, ...(input.notes ? { notes: input.notes } : {}) } });
+            return { lane_id: path.basename(input.runDir), envelope_id: hold.envelope_id, action: "parked" };
+        }
+        if (hold.resolution && hold.resolution.choice !== input.choice)
+            throw new Error("A different handoff disposition is already recorded");
+        if (!hold.resolution) {
+            if (!isRecord(result) || result.hold_reason !== "handoff_needs_repair" || result.question_id !== input.questionId || result.envelope_id !== hold.envelope_id)
+                throw new Error("Handoff result identity changed");
+            const held = envelopeFiles(path.join(input.runDir, "loop", "stalled")).find((file) => fileEnvelope(file).envelope_id === hold.envelope_id);
+            if (!held)
+                throw new Error("Held handoff envelope is missing");
+            const record = fileEnvelope(held);
+            if (input.choice === HANDOFF_HOLD_CHOICES[0]) {
+                const externalPath = record.envelope.result_path;
+                if (typeof externalPath !== "string" || !externalPath.trim())
+                    throw new Error("Held phase has no handoff path");
+                const output = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readHandoffBytes(externalPath));
+                validateAcceptedHandoff(output, record.envelope);
+                delete record.handoff_retry;
+                record.accepted_handoff = { output, sha256: createHash("sha256").update(output).digest("hex") };
+            }
+            else {
+                delete record.accepted_handoff;
+                record.handoff_retry = true;
+            }
+            record.stall_attempts = 0;
+            hold.resolution = { choice: input.choice, at: input.at, ...(input.notes ? { notes: input.notes } : {}), pending_name: `0000000000000-answer-${path.basename(held)}`, record };
+            // Durable authorization precedes every queue/result move. The hold gates
+            // raw controllers until all those moves have completed, including retries.
+            atomicJson(handoffHoldPath(input.runDir), hold);
+        }
+        const resolution = hold.resolution;
+        const pending = path.join(pendingDir(input.runDir), resolution.pending_name);
+        if (path.basename(resolution.pending_name) !== resolution.pending_name || resolution.record.envelope_id !== hold.envelope_id)
+            throw new Error("Invalid handoff disposition record");
+        const held = envelopeFiles(path.join(input.runDir, "loop", "stalled")).find((file) => fileEnvelope(file).envelope_id === hold.envelope_id);
+        if (held) {
+            atomicJson(held, resolution.record);
+            fs.mkdirSync(pendingDir(input.runDir), { recursive: true });
+            fs.renameSync(held, pending);
+        }
+        else if (!fs.existsSync(pending) || JSON.stringify(fileEnvelope(pending)) !== JSON.stringify(resolution.record)) {
+            throw new Error("Disposition envelope changed before it could be resumed");
+        }
+        if (fs.existsSync(resultPath)) {
+            atomicJson(resultPath, { ...readJson(resultPath), decision: { question_id: input.questionId, choice: resolution.choice, at: resolution.at, ...(resolution.notes ? { notes: resolution.notes } : {}) } });
+            fs.renameSync(resultPath, asidePath(resultPath, "stalled"));
+        }
+        persistStatus(input.runDir, path.basename(input.runDir), { state: "waiting" });
+        fs.unlinkSync(handoffHoldPath(input.runDir));
+        return { lane_id: path.basename(input.runDir), envelope_id: hold.envelope_id, action: "requeued" };
+    }
+    finally {
+        release();
+    }
+}
 function asidePath(file, marker) {
     const parsed = path.parse(file);
     let suffix = 1;
@@ -520,6 +688,11 @@ export function findLoopStallResult(runDir, questionId) {
     return resultPath ? readJson(resultPath) : undefined;
 }
 export function applyLoopStallAnswer(input) {
+    const hold = readHandoffHold(input.runDir);
+    if (hold?.question_id === input.questionId)
+        return applyHandoffHoldAnswer(input);
+    if (hold)
+        throw new Error("A different handoff hold must be resolved first");
     const result = findLoopStallResult(input.runDir, input.questionId);
     if (!result) {
         for (const name of stalledResultArchives(input.runDir)) {
@@ -586,12 +759,14 @@ export function loopStatus(runDir, laneId) {
     const stallCounts = isRecord(loop.stall_counts)
         ? Object.fromEntries(Object.entries(loop.stall_counts).filter((entry) => typeof entry[1] === "number"))
         : {};
+    const hold = readHandoffHold(runDir);
     const processState = loop.state === "running" || loop.state === "parked" || loop.state === "stopped" || loop.state === "failed" ? loop.state : "waiting";
     return {
-        mode: "loop", lane_id: laneId, state: processState, queue_depth: queueDepth,
+        mode: "loop", lane_id: laneId, state: hold && processState !== "stopped" ? "parked" : processState, queue_depth: queueDepth,
         active_envelope_id: active?.envelope_id ?? null,
         active_phase: active ? phaseName(active.envelope, active.envelope_id) : null,
         stall_counts: stallCounts,
+        ...(hold ? { handoff_hold: { envelope_id: hold.envelope_id, question_id: hold.question_id } } : {}),
         ...(typeof loop.pid === "number" ? { pid: loop.pid } : {}),
         updated_at: typeof loop.updated_at === "string" ? loop.updated_at : new Date(0).toISOString(),
     };
@@ -746,6 +921,13 @@ function abortAfter(ms, parent) {
 /** Run queued phases serially. Sessions are isolated by story and provider. */
 export async function runLoopLane(options) {
     const now = options.now ?? (() => new Date());
+    const held = readHandoffHold(options.runDir);
+    if (held) {
+        if (loopStatus(options.runDir, options.lane.lane_id).state === "stopped")
+            return { state: "stopped", completed: 0 };
+        await notifyHandoffHold(options, held);
+        return { state: "parked", completed: 0 };
+    }
     const defaultDeadlineSeconds = options.defaultDeadlineSeconds ?? 3600;
     const sessions = new Map();
     try {
@@ -766,6 +948,10 @@ export async function runLoopLane(options) {
     let completed = 0;
     fs.mkdirSync(options.runDir, { recursive: true });
     let releaseRunner = acquireRunnerLease(options.runDir);
+    if (readHandoffHold(options.runDir)) {
+        releaseRunner();
+        return { state: loopStatus(options.runDir, options.lane.lane_id).state === "stopped" ? "stopped" : "parked", completed: 0 };
+    }
     persistStatus(options.runDir, options.lane.lane_id, { pid: process.pid });
     try {
         const previous = readJson(loopPath(options.runDir));
@@ -821,7 +1007,7 @@ export async function runLoopLane(options) {
         const provider = envelopeProvider(envelope, options.lane.provider);
         const story = envelopeStory(envelope);
         const sessionKey = `${story}\0${provider}`;
-        const fresh = envelope.fresh === true || envelope.fresh_call === true;
+        const fresh = record.handoff_retry === true || envelope.fresh === true || envelope.fresh_call === true;
         const previousSession = sessions.get(sessionKey);
         const startedAt = now().toISOString();
         const startedAtMs = Date.parse(startedAt);
@@ -835,14 +1021,29 @@ export async function runLoopLane(options) {
         atomicJson(file, record);
         persistStatus(options.runDir, options.lane.lane_id, { state: "running", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: record.envelope_id, active_phase: phaseName(envelope, record.envelope_id) });
         const timer = abortAfter(budget * 1000, options.signal);
+        let malformedHandoff;
         try {
             let result;
             let fallback = false;
             try {
                 const resumable = options.canResume?.(provider) ?? providerSupportsSessionResume(provider);
-                result = await options.execute({ lane: options.lane, envelope, envelopeId: record.envelope_id, signal: timer.signal, fresh: fresh || previousSession === undefined || !resumable, ...(fresh || previousSession === undefined || !resumable ? {} : { sessionId: previousSession }) });
+                if (record.accepted_handoff) {
+                    malformedHandoff = "Accepted handoff changed before continuation";
+                    const externalPath = envelope.result_path;
+                    if (typeof externalPath !== "string" || createHash("sha256").update(readHandoffBytes(externalPath)).digest("hex") !== record.accepted_handoff.sha256)
+                        throw new Error(malformedHandoff);
+                    if (createHash("sha256").update(record.accepted_handoff.output).digest("hex") !== record.accepted_handoff.sha256)
+                        throw new Error("Accepted handoff hash changed");
+                    validateAcceptedHandoff(record.accepted_handoff.output, envelope);
+                    result = { output: record.accepted_handoff.output };
+                    malformedHandoff = undefined;
+                }
+                else
+                    result = await options.execute({ lane: options.lane, envelope, envelopeId: record.envelope_id, signal: timer.signal, fresh: fresh || previousSession === undefined || !resumable, ...(fresh || previousSession === undefined || !resumable ? {} : { sessionId: previousSession }) });
             }
             catch (error) {
+                if (record.accepted_handoff)
+                    throw error;
                 const resumable = options.canResume?.(provider) ?? providerSupportsSessionResume(provider);
                 if (!fresh && previousSession && resumable && !timer.signal.aborted) {
                     fallback = true;
@@ -875,6 +1076,7 @@ export async function runLoopLane(options) {
                     }
                 }
                 catch (validationError) {
+                    malformedHandoff = validationError instanceof Error ? validationError.message : String(validationError);
                     if (options.repairInvalidHandoff !== false && !timer.signal.aborted) {
                         const repairError = validationError instanceof Error ? validationError.message : String(validationError);
                         const repaired = await options.execute({
@@ -899,6 +1101,7 @@ export async function runLoopLane(options) {
                         if (repairedValidated.worker_id !== envelope.worker_id) {
                             throw new Error(`handoff worker_id must match the queued phase envelope: ${repairError}`);
                         }
+                        malformedHandoff = undefined;
                         result = repaired;
                         success = {
                             ...success,
@@ -932,6 +1135,33 @@ export async function runLoopLane(options) {
                 persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
                 return { state: "aborted", completed };
             }
+            if (malformedHandoff !== undefined) {
+                const message = error instanceof Error ? error.message : String(error);
+                const questionId = randomUUID();
+                const hold = { schema: "hq-loop-handoff-hold.v1", envelope_id: record.envelope_id, question_id: questionId, error: `${malformedHandoff}; repair failed: ${message}` };
+                try {
+                    atomicJson(handoffHoldPath(options.runDir), hold);
+                    const externalPath = envelope.result_path;
+                    if (typeof externalPath === "string" && fs.existsSync(externalPath)) {
+                        const stat = fs.lstatSync(externalPath);
+                        if (stat.isFile() && stat.size <= LOOP_ENVELOPE_LIMIT) {
+                            const backup = path.join(options.runDir, "loop", "handoff-original", `${resultName(record.envelope_id)}.${questionId}`);
+                            fs.mkdirSync(path.dirname(backup), { recursive: true });
+                            fs.writeFileSync(backup, readHandoffBytes(externalPath), { flag: "wx", mode: 0o600 });
+                            hold.original_copy = backup;
+                            atomicJson(handoffHoldPath(options.runDir), hold);
+                        }
+                    }
+                    writeResultAt(options.runDir, file, record, { schema_version: LOOP_SCHEMA, envelope_id: record.envelope_id, status: "stalled", hold_reason: "handoff_needs_repair", question_id: questionId, started_at: startedAt, finished_at: now().toISOString(), error: hold.error }, 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 });
+                }
+                finally {
+                    releaseRunner();
+                    clearLoopControllerPid(options.runDir, options.lane.lane_id, process.pid);
+                }
+                await notifyHandoffHold(options, hold, envelope);
+                return { state: "parked", completed };
+            }
             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 }, options.repairInvalidHandoff !== false);
@@ -1035,7 +1265,7 @@ function writeResultAt(runDir, activeFile, record, result, includeHandoffValidat
                         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." : includeHandoffValidationError ? `Phase execution failed: ${result.error ?? "unknown error"}` : "Phase execution failed.",
+                        summary: result.hold_reason === "handoff_needs_repair" ? `Handoff needs repair: ${result.error ?? "invalid handoff"}` : 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/questions.d.ts

@@ -9,6 +9,7 @@ export interface QuestionBody {
         lane_id: string;
         envelope_id: string;
         attempt: number;
+        reason?: "handoff_needs_repair";
     };
 }
 export declare function assertQuestionBodySecretSafe(body: QuestionBody): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.161",
+  "version": "5.345.162",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -52,7 +52,7 @@
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
     "@aws-sdk/dsql-signer": "^3.1146.0",
-    "@indigoai-us/hq-cloud": "6.18.99",
+    "@indigoai-us/hq-cloud": "6.18.100",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@sentry/node": "^10.49.0",
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.161",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.161",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.161",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.161",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.161",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.161"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.162",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.162",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.162",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.162",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.162",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.162"
   }
 }