@indigoai-us/hq-cli 5.345.61 → 5.345.63

package/dist/lib/lanes/loop.js

@@ -305,6 +305,9 @@ function fileEnvelope(file) {
     if (!isRecord(value) || value.schema_version !== LOOP_SCHEMA || !nonEmpty(value.envelope_id) || !nonEmpty(value.queued_at)) {
         throw new Error(`Invalid queued loop envelope record: ${file}`);
     }
+    if (value.stall_attempts !== undefined && (!Number.isSafeInteger(value.stall_attempts) || Number(value.stall_attempts) < 0)) {
+        throw new Error(`Invalid stall_attempts in queued loop envelope record: ${file}`);
+    }
     return { ...value, envelope: validateLoopEnvelope(value.envelope) };
 }
 /** Queue depth and FIFO ordering are based on the timestamp-prefixed filename. */
@@ -329,34 +332,41 @@ export function enqueueLoopEnvelope(input) {
     fs.mkdirSync(dir, { recursive: true });
     const release = acquireEnqueueLock(input.runDir);
     try {
-        const records = [pendingDir(input.runDir), activeDir(input.runDir), claimedDir(input.runDir), path.join(input.runDir, "loop", "stalled"), path.join(input.runDir, "loop", "withdrawn")]
-            .flatMap(envelopeFiles)
-            .map((file) => {
+        const withdrawnDir = path.join(input.runDir, "loop", "withdrawn");
+        const stalledDir = path.join(input.runDir, "loop", "stalled");
+        const records = [pendingDir(input.runDir), activeDir(input.runDir), claimedDir(input.runDir), stalledDir, withdrawnDir]
+            .flatMap((dir) => envelopeFiles(dir).map((file) => ({ file, dir })))
+            .map(({ file, dir }) => {
             try {
-                return fileEnvelope(file);
+                return { file, dir, record: fileEnvelope(file) };
             }
             catch (error) {
                 process.stderr.write(`hq lanes: ignored unreadable loop record ${file}: ${error instanceof Error ? error.message : String(error)}\n`);
                 return undefined;
             }
         })
-            .filter((record) => record !== undefined);
-        const withdrawnDir = path.join(input.runDir, "loop", "withdrawn");
-        const stalledDir = path.join(input.runDir, "loop", "stalled");
-        const reusableRecords = records.filter((record) => record.envelope_id === envelopeId);
+            .filter((entry) => entry !== undefined);
+        const reusableRecords = records.filter(({ record }) => record.envelope_id === envelopeId);
         const terminalResult = fs.existsSync(path.join(resultsDir(input.runDir), resultName(envelopeId)))
             ? readJson(path.join(resultsDir(input.runDir), resultName(envelopeId))) : undefined;
-        const reusable = reusableRecords.length > 0 && reusableRecords.every((record) => [stalledDir, withdrawnDir].some((dir) => envelopeFiles(dir).some((file) => {
+        const reusable = reusableRecords.length > 0 && reusableRecords.every(({ dir }) => dir === stalledDir || dir === withdrawnDir) &&
+            !reusableRecords.some(({ dir }) => dir === pendingDir(input.runDir) || dir === activeDir(input.runDir) || dir === claimedDir(input.runDir)) &&
+            (!isRecord(terminalResult) || terminalResult.status === "stalled");
+        if ((reusableRecords.length > 0 && !reusable) ||
+            (terminalResult !== undefined && (!reusable || !isRecord(terminalResult) || terminalResult.status !== "stalled"))) {
+            throw new Error(`envelope id ${envelopeId} was already used in this loop lane`);
+        }
+        const incomingStop = envelope.kind === "stop";
+        const blockingStop = [pendingDir(input.runDir), activeDir(input.runDir), claimedDir(input.runDir)].some((scanDir) => envelopeFiles(scanDir).some((file) => {
             try {
-                return fileEnvelope(file).envelope_id === record.envelope_id;
+                return fileEnvelope(file).envelope.kind === "stop";
             }
             catch {
                 return false;
             }
-        }))) && (!isRecord(terminalResult) || terminalResult.status === "stalled");
-        if ((records.some((record) => record.envelope_id === envelopeId) && !reusable) ||
-            (terminalResult !== undefined && (!reusable || !isRecord(terminalResult) || terminalResult.status !== "stalled"))) {
-            throw new Error(`envelope id ${envelopeId} was already used in this loop lane`);
+        }));
+        if (blockingStop) {
+            throw new Error(incomingStop ? "a stop envelope is already queued or active" : "cannot enqueue a phase after a stop envelope");
         }
         if (reusable) {
             for (const file of envelopeFiles(withdrawnDir).concat(envelopeFiles(stalledDir))) {
@@ -374,23 +384,11 @@ export function enqueueLoopEnvelope(input) {
                 fs.renameSync(resultFile, asidePath(resultFile, "stalled"));
             }
         }
-        const incomingStop = envelope.kind === "stop";
-        const blockingStop = [pendingDir(input.runDir), activeDir(input.runDir)].some((scanDir) => envelopeFiles(scanDir).some((file) => {
-            try {
-                return fileEnvelope(file).envelope.kind === "stop";
-            }
-            catch {
-                return false;
-            }
-        }));
-        if (blockingStop) {
-            throw new Error(incomingStop ? "a stop envelope is already queued or active" : "cannot enqueue a phase after a stop envelope");
-        }
         const sequence = nextQueueSequence(input.runDir);
         const prefix = `${String(sequence).padStart(16, "0")}-${String(now.getTime()).padStart(13, "0")}-${randomUUID()}`;
         const destination = path.join(dir, `${prefix}-${envelopeId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
         const temporary = `${destination}.${process.pid}.tmp`;
-        const record = { schema_version: LOOP_SCHEMA, envelope_id: envelopeId, queued_at: queuedAt, envelope };
+        const record = { schema_version: LOOP_SCHEMA, envelope_id: envelopeId, queued_at: queuedAt, stall_attempts: 0, envelope };
         try {
             fs.writeFileSync(temporary, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 });
             fs.renameSync(temporary, destination);
@@ -417,6 +415,12 @@ export function enqueueLoopEnvelope(input) {
 export function claimNextLoopEnvelope(runDir) {
     fs.mkdirSync(activeDir(runDir), { recursive: true });
     fs.mkdirSync(claimedDir(runDir), { recursive: true });
+    // A previous controller may have written a stop result but failed before moving the active record to claimed.
+    for (const active of envelopeFiles(activeDir(runDir))) {
+        const record = fileEnvelope(active);
+        if (record.envelope.kind === "stop")
+            return { file: active, record };
+    }
     for (const pending of envelopeFiles(pendingDir(runDir))) {
         const active = path.join(activeDir(runDir), path.basename(pending));
         try {
@@ -453,7 +457,7 @@ export function interruptLoopQueue(runDir) {
     }
     return { withdrawn, already_picked_up: alreadyPickedUp };
 }
-export function interruptLoopQueueForStory(runDir, storyId, phase) {
+export function interruptLoopQueueForStory(runDir, storyId, phase, hooks = {}) {
     const withdrawn = [];
     const alreadyPickedUp = [];
     const matches = (record) => {
@@ -461,28 +465,51 @@ export function interruptLoopQueueForStory(runDir, storyId, phase) {
         return envelope.story_id === storyId && (phase === undefined || envelope.phase === phase);
     };
     for (const file of envelopeFiles(pendingDir(runDir))) {
-        const record = fileEnvelope(file);
+        let record;
+        hooks.beforePendingRead?.(file);
+        try {
+            record = fileEnvelope(file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
         if (!matches(record))
             continue;
         const destination = path.join(runDir, "loop", "withdrawn", path.basename(file));
         fs.mkdirSync(path.dirname(destination), { recursive: true });
-        fs.renameSync(file, destination);
-        withdrawn.push(record.envelope_id);
+        hooks.beforePendingRename?.(file);
+        try {
+            fs.renameSync(file, destination);
+            withdrawn.push(record.envelope_id);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            alreadyPickedUp.push(record.envelope_id);
+        }
     }
     for (const file of envelopeFiles(activeDir(runDir))) {
         const record = fileEnvelope(file);
         if (matches(record))
             alreadyPickedUp.push(record.envelope_id);
     }
-    return { withdrawn, already_picked_up: alreadyPickedUp };
+    return { withdrawn, already_picked_up: [...new Set(alreadyPickedUp)] };
 }
-export function applyLoopStallAnswer(input) {
-    const results = fs.existsSync(resultsDir(input.runDir))
-        ? fs.readdirSync(resultsDir(input.runDir)).filter((name) => name.endsWith(".json")) : [];
-    const resultPath = results.map((name) => path.join(resultsDir(input.runDir), name)).find((file) => {
+function stalledResultArchives(runDir) {
+    return fs.existsSync(resultsDir(runDir))
+        ? fs.readdirSync(resultsDir(runDir)).filter((name) => /\.stalled\.\d+\.json$/.test(name))
+        : [];
+}
+export function findLoopStallResult(runDir, questionId) {
+    const archivedNames = new Set(stalledResultArchives(runDir));
+    const results = fs.existsSync(resultsDir(runDir))
+        ? fs.readdirSync(resultsDir(runDir)).filter((name) => name.endsWith(".json") && !archivedNames.has(name)) : [];
+    const resultPath = results.map((name) => path.join(resultsDir(runDir), name)).find((file) => {
         try {
             const result = readJson(file);
-            return isRecord(result) && result.status === "stalled" && result.question_id === input.questionId;
+            return isRecord(result) && result.status === "stalled" && result.question_id === questionId;
         }
         catch (error) {
             if (error instanceof SyntaxError)
@@ -490,9 +517,35 @@ export function applyLoopStallAnswer(input) {
             throw error;
         }
     });
-    if (!resultPath)
+    return resultPath ? readJson(resultPath) : undefined;
+}
+export function applyLoopStallAnswer(input) {
+    const result = findLoopStallResult(input.runDir, input.questionId);
+    if (!result) {
+        for (const name of stalledResultArchives(input.runDir)) {
+            try {
+                const archived = readJson(path.join(resultsDir(input.runDir), name));
+                if (!isRecord(archived) || archived.status !== "stalled" || archived.question_id !== input.questionId)
+                    continue;
+                const envelopeId = String(archived.envelope_id);
+                for (const dir of [pendingDir(input.runDir), activeDir(input.runDir), claimedDir(input.runDir)]) {
+                    const match = envelopeFiles(dir).find((file) => fileEnvelope(file).envelope_id === envelopeId);
+                    if (!match)
+                        continue;
+                    const isAnswer = path.basename(match).startsWith("0000000000000-answer-");
+                    return { lane_id: path.basename(input.runDir), envelope_id: envelopeId, action: isAnswer && dir === pendingDir(input.runDir) ? "requeued" : "already_applied" };
+                }
+                return { lane_id: path.basename(input.runDir), envelope_id: envelopeId, action: "already_applied" };
+            }
+            catch (error) {
+                if (error instanceof SyntaxError || error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+        }
         return undefined;
-    const result = readJson(resultPath);
+    }
+    const resultPath = path.join(resultsDir(input.runDir), resultName(result.envelope_id));
     const envelopeFile = envelopeFiles(path.join(input.runDir, "loop", "stalled")).find((file) => {
         try {
             return fileEnvelope(file).envelope_id === result.envelope_id;
@@ -506,15 +559,17 @@ export function applyLoopStallAnswer(input) {
     const record = fileEnvelope(envelopeFile);
     const action = input.choice === "Retry with a longer deadline" ? "requeued" : "parked";
     if (action === "requeued") {
-        record.deadline_budget_seconds = Math.max(1, record.deadline_budget_seconds ?? phaseDeadlineBudget(record.envelope, 3600)) * 2;
+        record.deadline_budget_seconds = (record.deadline_budget_seconds ?? phaseDeadlineBudget(record.envelope, 3600)) * 2;
+        record.stall_attempts = 0;
         const head = path.join(pendingDir(input.runDir), `0000000000000-answer-${path.basename(envelopeFile)}`);
         fs.mkdirSync(pendingDir(input.runDir), { recursive: true });
         fs.renameSync(envelopeFile, head);
         fs.renameSync(resultPath, asidePath(resultPath, "stalled"));
         const pending = fileEnvelope(head);
         pending.deadline_budget_seconds = record.deadline_budget_seconds;
+        pending.stall_attempts = 0;
         atomicJson(head, pending);
-        persistStatus(input.runDir, path.basename(input.runDir), { stall_counts: { [record.envelope_id]: 0 } });
+        persistStallCount(input.runDir, path.basename(input.runDir), record.envelope_id, 0);
     }
     else {
         atomicJson(resultPath, {
@@ -613,6 +668,15 @@ function phaseDeadlineBudget(envelope, defaultSeconds) {
     const configured = Number(process.env.HQ_LANE_LOOP_PHASE_DEADLINE_SECS);
     return Number.isFinite(configured) && configured > 0 ? configured : defaultSeconds;
 }
+function persistStallCount(runDir, laneId, envelopeId, count) {
+    const status = loopStatus(runDir, laneId);
+    persistStatus(runDir, laneId, { stall_counts: { ...status.stall_counts, [envelopeId]: count } });
+}
+function clearPersistedStallCount(runDir, laneId, envelopeId) {
+    const counts = loopStatus(runDir, laneId).stall_counts;
+    delete counts[envelopeId];
+    persistStatus(runDir, laneId, { stall_counts: counts });
+}
 function persistStatus(runDir, laneId, patch) {
     let current = {};
     try {
@@ -658,7 +722,7 @@ export async function runLoopLane(options) {
     const stalls = new Map();
     let completed = 0;
     fs.mkdirSync(options.runDir, { recursive: true });
-    const releaseRunner = acquireRunnerLease(options.runDir);
+    let releaseRunner = acquireRunnerLease(options.runDir);
     persistStatus(options.runDir, options.lane.lane_id, { pid: process.pid });
     try {
         const previous = readJson(loopPath(options.runDir));
@@ -673,7 +737,7 @@ export async function runLoopLane(options) {
         if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
             throw error;
     }
-    persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: {} });
+    persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
     while (!options.signal?.aborted) {
         const claimed = claimNextLoopEnvelope(options.runDir);
         if (!claimed) {
@@ -685,8 +749,29 @@ export async function runLoopLane(options) {
         const envelope = record.envelope;
         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() };
-            writeResultAt(options.runDir, file, record, stopped);
-            persistStatus(options.runDir, options.lane.lane_id, { state: "stopped", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+            try {
+                writeResultAt(options.runDir, file, record, stopped);
+                persistStatus(options.runDir, options.lane.lane_id, { state: "stopped", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
+            }
+            catch (error) {
+                const cleanupErrors = [];
+                try {
+                    releaseRunner();
+                }
+                catch (cleanupError) {
+                    cleanupErrors.push(cleanupError);
+                }
+                releaseRunner = () => { };
+                try {
+                    clearLoopControllerPid(options.runDir, options.lane.lane_id, process.pid);
+                }
+                catch (cleanupError) {
+                    cleanupErrors.push(cleanupError);
+                }
+                if (cleanupErrors.length)
+                    throw new AggregateError([error, ...cleanupErrors], "Could not recover after committing a stop envelope");
+                throw error;
+            }
             releaseRunner();
             return { state: "stopped", completed };
         }
@@ -700,12 +785,12 @@ export async function runLoopLane(options) {
         const absoluteDeadline = envelope.deadline;
         const budget = record.deadline_budget_seconds ?? firstDeadline.get(record.envelope_id) ??
             (typeof absoluteDeadline === "string"
-                ? Math.max(1, Math.round((Date.parse(absoluteDeadline) - startedAtMs) / 1000))
+                ? Math.max(1, Math.round((Date.parse(absoluteDeadline) - startedAtMs) / 1000)) // An absolute deadline already in the past still gets a 1 s execution window.
                 : phaseDeadlineBudget(envelope, defaultDeadlineSeconds));
         firstDeadline.set(record.envelope_id, budget);
         record.deadline_budget_seconds = budget;
         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), stall_counts: Object.fromEntries(stalls) });
+        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);
         try {
             let result;
@@ -751,6 +836,7 @@ export async function runLoopLane(options) {
                 atomicJson(sessionsPath(options.runDir), Object.fromEntries(sessions));
             }
             stalls.delete(record.envelope_id);
+            clearPersistedStallCount(options.runDir, options.lane.lane_id, record.envelope_id);
             completed += 1;
         }
         catch (error) {
@@ -759,49 +845,75 @@ export async function runLoopLane(options) {
                 const pending = path.join(pendingDir(options.runDir), path.basename(file));
                 fs.mkdirSync(pendingDir(options.runDir), { recursive: true });
                 fs.renameSync(file, pending);
-                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
                 releaseRunner();
+                releaseRunner = () => { };
+                clearLoopControllerPid(options.runDir, options.lane.lane_id, process.pid);
+                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 (!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 });
                 completed += 1;
-                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
                 continue;
             }
-            const attempt = (stalls.get(record.envelope_id) ?? 0) + 1;
+            const legacyCount = stalls.get(record.envelope_id) ?? 0;
+            const attempt = (record.stall_attempts ?? legacyCount) + 1;
             stalls.set(record.envelope_id, attempt);
-            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), stall_counts: Object.fromEntries(stalls) });
+            persistStallCount(options.runDir, options.lane.lane_id, record.envelope_id, attempt);
+            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) });
             appendJournal(options.runDir, { event: "phase_stalled", envelope_id: record.envelope_id, phase: phaseName(envelope, record.envelope_id), attempt, at: now().toISOString() });
             if (attempt === 1) {
                 timer.clear();
                 sessions.delete(sessionKey);
                 atomicJson(sessionsPath(options.runDir), Object.fromEntries(sessions));
                 // Restore the same envelope at the FIFO head. Rename preserves a single claim.
+                record.stall_attempts = 1;
+                atomicJson(file, record);
                 const head = path.join(pendingDir(options.runDir), `0000000000000-retry-${path.basename(file)}`);
                 fs.mkdirSync(pendingDir(options.runDir), { recursive: true });
                 fs.renameSync(file, head);
-                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+                persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
                 continue;
             }
             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);
-            if (questionId)
-                await options.raiseQuestion?.({ envelope, envelopeId: record.envelope_id, attempt, error: message, questionId });
+            persistStatus(options.runDir, options.lane.lane_id, { state: "parked", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
             completed += 1;
-            persistStatus(options.runDir, options.lane.lane_id, { state: "parked", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
-            releaseRunner();
+            try {
+                if (questionId)
+                    await options.raiseQuestion?.({ envelope, envelopeId: record.envelope_id, attempt, error: message, questionId });
+            }
+            finally {
+                releaseRunner();
+                releaseRunner = () => { };
+                clearLoopControllerPid(options.runDir, options.lane.lane_id, process.pid);
+            }
+            const answeredRetryIsPending = envelopeFiles(pendingDir(options.runDir)).some((pendingFile) => path.basename(pendingFile).startsWith("0000000000000-answer-") && fileEnvelope(pendingFile).envelope_id === record.envelope_id);
+            if (answeredRetryIsPending) {
+                try {
+                    releaseRunner = acquireRunnerLease(options.runDir);
+                    persistStatus(options.runDir, options.lane.lane_id, { pid: process.pid, state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
+                    continue;
+                }
+                catch (leaseError) {
+                    if (!(leaseError instanceof Error) || !(leaseError.message.includes("already active") || leaseError.message.includes("claimed by another controller")))
+                        throw leaseError;
+                }
+            }
             return { state: "parked", completed };
         }
         finally {
             timer.clear();
         }
-        persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null, stall_counts: Object.fromEntries(stalls) });
+        persistStatus(options.runDir, options.lane.lane_id, { state: "waiting", queue_depth: listLoopQueue(options.runDir).length, active_envelope_id: null, active_phase: null });
     }
     releaseRunner();
+    clearLoopControllerPid(options.runDir, options.lane.lane_id, process.pid);
+    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 };
 }
 function appendJournal(runDir, value) {

package/dist/utils/client-health-contract.d.ts

@@ -53,6 +53,13 @@ export type ClientHealthSyncState = (typeof CLIENT_HEALTH_SYNC_STATES)[number];
  */
 export declare const CLIENT_HEALTH_UPDATER_STATES: readonly ["unchecked", "up_to_date", "update_available", "update_downloading", "update_ready", "update_failed", "unsupported"];
 export type ClientHealthUpdaterState = (typeof CLIENT_HEALTH_UPDATER_STATES)[number];
+/** Origin of the runner currently used by desktop sync. */
+export declare const CLIENT_HEALTH_SYNC_RUNNER_SOURCES: readonly ["npx", "daemon_managed", "daemon_staged", "daemon_bundled", "unknown"];
+export type ClientHealthSyncRunnerSource = (typeof CLIENT_HEALTH_SYNC_RUNNER_SOURCES)[number];
+export declare const CLIENT_HEALTH_DAEMON_HQ_CLOUD_UPDATE_OUTCOMES: readonly ["updated", "up_to_date", "pinned", "failed"];
+export type ClientHealthDaemonHqCloudUpdateOutcome = (typeof CLIENT_HEALTH_DAEMON_HQ_CLOUD_UPDATE_OUTCOMES)[number];
+export declare const CLIENT_HEALTH_DAEMON_HQ_CLOUD_UPDATE_ERROR_CLASSES: readonly ["registry", "install", "convergence", "filesystem", "unknown"];
+export type ClientHealthDaemonHqCloudUpdateErrorClass = (typeof CLIENT_HEALTH_DAEMON_HQ_CLOUD_UPDATE_ERROR_CLASSES)[number];
 /** Closed failure/blocker reason codes — the ONLY reasons that cross the wire. */
 export declare const CLIENT_HEALTH_FAILURE_REASONS: readonly ["SYNC_PAUSED", "CONFLICT_BLOCKED", "DESKTOP_OUTDATED", "CLI_OUTDATED", "CORE_OUTDATED", "AUTH_EXPIRED", "UPDATE_FAILED", "RUNNER_FAILED", "PERMISSION_DENIED", "DISK_FULL", "HEARTBEAT_STALE"];
 export type ClientHealthFailureReason = (typeof CLIENT_HEALTH_FAILURE_REASONS)[number];
@@ -139,6 +146,11 @@ export interface ClientHealthHeartbeat {
     conflictCount?: number;
     updaterState?: ClientHealthUpdaterState;
     failureReason?: ClientHealthFailureReason;
+    syncRunnerSource?: ClientHealthSyncRunnerSource;
+    daemonHqCloudUpdateLastCheckAt?: string;
+    daemonHqCloudUpdateOutcome?: ClientHealthDaemonHqCloudUpdateOutcome;
+    daemonHqCloudUpdateTarget?: string;
+    daemonHqCloudUpdateErrorClass?: ClientHealthDaemonHqCloudUpdateErrorClass;
     /** Absent on older clients / non-sync-outcome events. See {@link ClientHealthLocalFilesOverview}. */
     localFilesOverview?: ClientHealthLocalFilesOverview;
 }

package/dist/utils/client-health-contract.js

@@ -65,6 +65,27 @@ export const CLIENT_HEALTH_UPDATER_STATES = [
     "update_failed",
     "unsupported",
 ];
+/** Origin of the runner currently used by desktop sync. */
+export const CLIENT_HEALTH_SYNC_RUNNER_SOURCES = [
+    "npx",
+    "daemon_managed",
+    "daemon_staged",
+    "daemon_bundled",
+    "unknown",
+];
+export const CLIENT_HEALTH_DAEMON_HQ_CLOUD_UPDATE_OUTCOMES = [
+    "updated",
+    "up_to_date",
+    "pinned",
+    "failed",
+];
+export const CLIENT_HEALTH_DAEMON_HQ_CLOUD_UPDATE_ERROR_CLASSES = [
+    "registry",
+    "install",
+    "convergence",
+    "filesystem",
+    "unknown",
+];
 /** Closed failure/blocker reason codes — the ONLY reasons that cross the wire. */
 export const CLIENT_HEALTH_FAILURE_REASONS = [
     "SYNC_PAUSED",
@@ -193,6 +214,23 @@ function assertEnum(field, value, allowed) {
     }
     return safe;
 }
+function copyValidOptionalDiagnostic(field, value, validate) {
+    try {
+        return validate(field, value);
+    }
+    catch (error) {
+        if (error instanceof ClientHealthContractError)
+            return undefined;
+        throw error;
+    }
+}
+function copyKnownOptionalEnum(target, field, value, allowed) {
+    if (value === undefined)
+        return;
+    const parsed = copyValidOptionalDiagnostic(field, value, (name, input) => assertEnum(name, input, allowed));
+    if (parsed !== undefined)
+        Object.assign(target, { [field]: parsed });
+}
 function assertBoundedInt(field, value, max) {
     if (value === undefined || value === null)
         throw new ClientHealthContractError("MISSING_FIELD", field);
@@ -264,6 +302,19 @@ export function parseClientHealthHeartbeat(input) {
     if (raw.failureReason !== undefined) {
         heartbeat.failureReason = assertEnum("failureReason", raw.failureReason, CLIENT_HEALTH_FAILURE_REASONS);
     }
+    copyKnownOptionalEnum(heartbeat, "syncRunnerSource", raw.syncRunnerSource, CLIENT_HEALTH_SYNC_RUNNER_SOURCES);
+    if (raw.daemonHqCloudUpdateLastCheckAt !== undefined) {
+        const lastCheckAt = copyValidOptionalDiagnostic("daemonHqCloudUpdateLastCheckAt", raw.daemonHqCloudUpdateLastCheckAt, assertIsoUtc);
+        if (lastCheckAt !== undefined)
+            heartbeat.daemonHqCloudUpdateLastCheckAt = lastCheckAt;
+    }
+    copyKnownOptionalEnum(heartbeat, "daemonHqCloudUpdateOutcome", raw.daemonHqCloudUpdateOutcome, CLIENT_HEALTH_DAEMON_HQ_CLOUD_UPDATE_OUTCOMES);
+    if (raw.daemonHqCloudUpdateTarget !== undefined) {
+        const target = copyValidOptionalDiagnostic("daemonHqCloudUpdateTarget", raw.daemonHqCloudUpdateTarget, assertVersion);
+        if (target !== undefined)
+            heartbeat.daemonHqCloudUpdateTarget = target;
+    }
+    copyKnownOptionalEnum(heartbeat, "daemonHqCloudUpdateErrorClass", raw.daemonHqCloudUpdateErrorClass, CLIENT_HEALTH_DAEMON_HQ_CLOUD_UPDATE_ERROR_CLASSES);
     if (raw.localFilesOverview !== undefined) {
         heartbeat.localFilesOverview = parseClientHealthLocalFilesOverview("localFilesOverview", raw.localFilesOverview);
     }

package/dist/utils/version-gate.js

@@ -1947,7 +1947,11 @@ export async function enforceVersionGate(onUpdateRecommended, options = {}) {
  * force-upgraded.
  */
 export function shouldSkipGate(argv) {
-    return isVersionRequest(argv) || argv.some((a) => a === "--version" ||
+    // Hook-time deliveries must finish inside the provider's timeout budget.
+    // process.argv slots 0 and 1 are the runtime and CLI entry point. Inspect
+    // command positions only; user arguments may legitimately contain these words.
+    const hookTimeLinkDelivery = argv[2] === "lanes" && argv[3] === "link" && argv[4] === "_deliver";
+    return hookTimeLinkDelivery || isVersionRequest(argv) || argv.some((a) => a === "--version" ||
         a === "-V" ||
         a === "-v" ||
         a === "--help" ||

package/package.json

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