@indigoai-us/hq-cli 5.345.160 → 5.345.162

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

@@ -20,6 +20,8 @@ export interface LinkOptions {
     timeout?: number;
     event?: string;
     input?: string;
+    ackMode?: string;
+    claims?: string;
     now?: () => Date;
     sleep?: (milliseconds: number) => Promise<void>;
 }
@@ -31,7 +33,6 @@ export declare function resolveLinkSessionId(root: string, explicit: string | un
 /** Cheap hook guard used before remote flag lookup or queue access. */
 export declare function linkedSessionIdFromHookInput(input: string): string;
 export declare function isLinkedSession(root: string, sid: string): boolean;
-/** Claims pending files by renaming the whole queue, matching conduct-inbox's no-loss drain. */
 export declare function drainLinkQueue(inbox: string): string;
 export declare function runLaneLink(subcommand: string, options: LinkOptions): Promise<LinkResult>;
 /** Apply the default-on feature gate contract at the command boundary. */

package/dist/lib/lanes/links.js

@@ -2,6 +2,8 @@ import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { appendDropboxMessageAtPath } from "./dropbox.js";
+import { withLaneRecordFileLock } from "./store.js";
+import { LanesError } from "./errors.js";
 export const LANE_SESSION_LINKS_FLAG = "lanes.session-links";
 const ID_PATTERN = /^[A-Za-z0-9._-]+$/;
 export class LaneLinkError extends Error {
@@ -132,6 +134,17 @@ function resolvePointer(root, sid, role, options) {
 function queueDir(root, link, child) {
     return path.join(rootDir(root), link, child ? "children" : "up", ...(child ? [child] : []), "inbox");
 }
+function withLinkQueueLock(inbox, fn) {
+    try {
+        return withLaneRecordFileLock(path.join(inbox, "queue"), fn, { reclaimByAge: false });
+    }
+    catch (error) {
+        if (error instanceof LanesError && error.error === "store_lock_timeout") {
+            throw new LaneLinkError("queue_busy", "Conductor queue busy; instructions retained");
+        }
+        throw error;
+    }
+}
 function sendQueue(root, link, child, text) {
     const inbox = queueDir(root, link, child);
     const pending = path.join(inbox, "pending");
@@ -139,10 +152,12 @@ function sendQueue(root, link, child, text) {
     // Reuse hq monitor's session-inbox append primitive; the pending directory is
     // still claimed as a whole below, keeping conduct-inbox's no-loss handoff.
     const cleanText = text.replaceAll("\0", "").replaceAll("\u000b", "").replaceAll("\u000c", "").replaceAll("\r", "");
-    appendDropboxMessageAtPath(pending, { at: new Date().toISOString(), text: cleanText });
+    withLinkQueueLock(inbox, () => {
+        appendDropboxMessageAtPath(pending, { at: new Date().toISOString(), text: cleanText });
+    });
 }
 /** Claims pending files by renaming the whole queue, matching conduct-inbox's no-loss drain. */
-export function drainLinkQueue(inbox) {
+function drainLinkQueueUnlocked(inbox) {
     const pending = path.join(inbox, "pending");
     const claimedRoot = path.join(inbox, "claimed");
     // Recover claims interrupted before the delivery result was committed. This is
@@ -190,16 +205,197 @@ export function drainLinkQueue(inbox) {
     fs.writeFileSync(path.join(claim, ".consumed"), "delivered\n", { mode: 0o600 });
     return messages;
 }
+export function drainLinkQueue(inbox) {
+    return withLinkQueueLock(inbox, () => drainLinkQueueUnlocked(inbox));
+}
+/** Claims remain replayable until the recipient explicitly accepts instructions.
+ * This is at-least-once transport, not proof of a native turn or execution.
+ */
+function claimLinkQueueUnlocked(inbox) {
+    const pending = path.join(inbox, "pending");
+    const claimed = path.join(inbox, "unaccepted");
+    fs.mkdirSync(claimed, { recursive: true });
+    if (fs.existsSync(path.join(pending, "inbox.jsonl"))) {
+        // Allocate while holding the queue lock. Wall time alone can repeat or
+        // move backward, and pid/random suffixes do not preserve claim order.
+        let serial = 0n;
+        for (const previous of fs.readdirSync(claimed)) {
+            const prefix = /^(\d{1,16})-/.exec(previous)?.[1];
+            if (prefix && BigInt(prefix) > serial)
+                serial = BigInt(prefix);
+        }
+        const wall = Date.now();
+        if (!Number.isSafeInteger(wall) || wall < 0)
+            throw new LaneLinkError("claim_clock_invalid", "Cannot allocate a safe receipt serial");
+        serial = BigInt(wall) > serial ? BigInt(wall) : serial + 1n;
+        if (serial > 9999999999999999n)
+            throw new LaneLinkError("claim_serial_exhausted", "Receipt serial exhausted; instructions retained");
+        const id = `${serial.toString().padStart(16, "0")}-${process.pid}-${randomBytes(8).toString("hex")}`;
+        const dir = path.join(claimed, id);
+        fs.mkdirSync(dir);
+        // The shared queue lock joins the producer's open/write/close before this
+        // immutable snapshot is read. Keep the producer directory stable too.
+        try {
+            fs.renameSync(path.join(pending, "inbox.jsonl"), path.join(dir, "inbox.jsonl"));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    const claims = [];
+    const messages = [];
+    const ordered = fs.readdirSync(claimed).sort((a, b) => {
+        const left = /^(\d{1,16})-/.exec(a)?.[1];
+        const right = /^(\d{1,16})-/.exec(b)?.[1];
+        if (left && right && BigInt(left) !== BigInt(right))
+            return BigInt(left) < BigInt(right) ? -1 : 1;
+        return a.localeCompare(b);
+    });
+    for (const id of ordered) {
+        if (!safeId(id))
+            continue;
+        const dir = path.join(claimed, id);
+        if (fs.existsSync(path.join(dir, ".consumed")))
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, "inbox.jsonl"), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        const rows = [];
+        const invalidRows = [];
+        text.split(/\r?\n/).forEach((line, index) => {
+            if (!line)
+                return;
+            try {
+                const row = JSON.parse(line);
+                if (!row || typeof row !== "object" || typeof row.text !== "string")
+                    throw new Error("invalid row");
+                rows.push(row.text);
+            }
+            catch {
+                invalidRows.push(index + 1);
+            }
+        });
+        if (invalidRows.length) {
+            // The immutable original is the quarantine evidence. Record positions,
+            // never malformed contents, and retain both even after valid rows' ACK.
+            const audit = path.join(dir, "invalid-rows.json");
+            const expectedAudit = JSON.stringify({ version: 1, rows: invalidRows }) + "\n";
+            let previousAudit;
+            try {
+                previousAudit = fs.readFileSync(audit, "utf8");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            if (previousAudit !== expectedAudit) {
+                const temporary = `${audit}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+                try {
+                    const fd = fs.openSync(temporary, "wx", 0o600);
+                    try {
+                        fs.writeFileSync(fd, expectedAudit);
+                        fs.fsyncSync(fd);
+                    }
+                    finally {
+                        fs.closeSync(fd);
+                    }
+                    fs.renameSync(temporary, audit);
+                }
+                finally {
+                    fs.rmSync(temporary, { force: true });
+                }
+            }
+            // Retry all durability barriers even if a previous attempt wrote the
+            // audit but failed before publishing its directory entry durably.
+            for (const file of [path.join(dir, "inbox.jsonl"), audit]) {
+                const fd = fs.openSync(file, "r");
+                try {
+                    fs.fsyncSync(fd);
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+            }
+            for (const directory of [dir, claimed]) {
+                try {
+                    const fd = fs.openSync(directory, "r");
+                    try {
+                        fs.fsyncSync(fd);
+                    }
+                    finally {
+                        fs.closeSync(fd);
+                    }
+                }
+                catch (error) {
+                    // Same known unsupported directory-flush codes as lanes store.
+                    // File flush errors and unknown directory errors remain fatal.
+                    if (!["EISDIR", "EINVAL", "ENOTSUP"].includes(error.code ?? ""))
+                        throw error;
+                }
+            }
+        }
+        if (!rows.length)
+            continue;
+        claims.push(id);
+        messages.push(...rows);
+    }
+    return { messages: messages.join("\n"), claims };
+}
+function claimLinkQueue(inbox) {
+    return withLinkQueueLock(inbox, () => claimLinkQueueUnlocked(inbox));
+}
+function acknowledgeLinkClaims(inbox, claims) {
+    return withLinkQueueLock(inbox, () => acknowledgeLinkClaimsUnlocked(inbox, claims));
+}
+function acknowledgeLinkClaimsUnlocked(inbox, claims) {
+    if (!Array.isArray(claims) || !claims.length || claims.some(id => typeof id !== "string" || !safeId(id))) {
+        throw new LaneLinkError("claim_invalid", "An exact nonempty claim receipt is required");
+    }
+    // Validate the entire receipt before changing any claim. Never resolve paths
+    // outside the current session's authoritative queue.
+    for (const id of claims) {
+        if (!fs.existsSync(path.join(inbox, "unaccepted", id, "inbox.jsonl"))) {
+            throw new LaneLinkError("claim_not_found", "Claim does not belong to this queue");
+        }
+    }
+    for (const id of claims) {
+        fs.writeFileSync(path.join(inbox, "unaccepted", id, ".consumed"), "recipient-accepted\n", { mode: 0o600 });
+    }
+}
+function countQuarantined(inbox) {
+    const claims = path.join(inbox, "unaccepted");
+    if (!fs.existsSync(claims))
+        return 0;
+    return fs.readdirSync(claims).filter(id => safeId(id) && fs.existsSync(path.join(claims, id, "invalid-rows.json"))).length;
+}
 function countPending(inbox) {
-    const payload = path.join(inbox, "pending", "inbox.jsonl");
-    try {
-        return fs.readFileSync(payload, "utf8").split(/\r?\n/).filter(Boolean).length;
+    const paths = [path.join(inbox, "pending", "inbox.jsonl")];
+    for (const name of ["claimed", "unaccepted"]) {
+        const claimed = path.join(inbox, name);
+        if (fs.existsSync(claimed))
+            for (const id of fs.readdirSync(claimed)) {
+                if (!fs.existsSync(path.join(claimed, id, ".consumed")))
+                    paths.push(path.join(claimed, id, "inbox.jsonl"));
+            }
     }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return 0;
-        throw error;
+    let count = 0;
+    for (const file of paths) {
+        try {
+            count += fs.readFileSync(file, "utf8").split(/\r?\n/).filter(Boolean).length;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
     }
+    return count;
 }
 function readText(options) {
     if (options.textFile) {
@@ -244,7 +440,7 @@ function listChildren(root, dir) {
         if (!fs.existsSync(metaPath))
             return [];
         const unread = countPending(path.join(cdir, "inbox"));
-        return [{ ...readJson(metaPath), undelivered: unread }];
+        return [{ ...readJson(metaPath), undelivered: unread, quarantined_claims: countQuarantined(path.join(cdir, "inbox")) }];
     });
 }
 async function waitForReport(dir, timeoutSeconds, sleep) {
@@ -288,6 +484,7 @@ export async function runLaneLink(subcommand, options) {
     const root = options.hqRoot;
     let sid = "";
     let childContext = false;
+    let stopHookActive = false;
     if (subcommand === "_deliver") {
         let payload = {};
         try {
@@ -299,6 +496,7 @@ export async function runLaneLink(subcommand, options) {
         const value = payload.session_id ?? payload.sessionId;
         sid = typeof value === "string" && safeId(value) ? value : "";
         childContext = isChildHookPayload(payload);
+        stopHookActive = payload.stop_hook_active === true || payload.stopHookActive === true;
     }
     const requireSid = () => sid || (sid = resolveLinkSessionId(root, options.sessionId, env));
     const links = rootDir(root);
@@ -307,21 +505,41 @@ export async function runLaneLink(subcommand, options) {
         // drain the root's queue into the subagent, so leave the message queued.
         if (!sid || childContext || !["PostToolUse", "Stop"].includes(options.event ?? ""))
             return {};
-        if (options.event === "Stop" && env.HQ_STOP_DECISION_DELIVERABLE === "0")
+        if (options.event === "Stop" && (stopHookActive || env.HQ_STOP_DECISION_DELIVERABLE === "0"))
             return {};
         const pointer = readPointer(root, sid);
         if (!pointer)
             return {};
         const target = hookMessage(root, pointer);
-        const messages = drainLinkQueue(target.inbox);
+        if (options.ackMode !== undefined && options.ackMode !== "explicit")
+            throw new LaneLinkError("ack_mode_invalid", "Unsupported acknowledgement mode");
+        const claim = options.ackMode === "explicit" ? claimLinkQueue(target.inbox) : undefined;
+        const messages = claim ? claim.messages : drainLinkQueue(target.inbox);
         if (!messages)
             return {};
-        const body = target.role === "conductor"
+        const receipt = claim ? { _hqLinkDelivery: { version: 1, sessionId: sid, link: pointer.link, child: pointer.name ?? null, claims: claim.claims } } : {};
+        const acceptance = claim ? `\n\n[conduct receipt] Stable instruction receipt IDs: ${claim.claims.join(",")}. Treat replayed IDs as the same instruction, not new execution authority. After accepting these instructions, acknowledge receipt once with: hq lanes link ack --session-id ${sid} --link ${pointer.link}${pointer.name ? ` --child ${pointer.name}` : ""} --claims ${claim.claims.join(",")}. Receipt acceptance does not approve actions, answer owner pickers, or mean work is completed.` : "";
+        const body = (target.role === "conductor"
             ? `[conduct] Sessions you are conducting reported while you were working.\nEach report names the session it came from. Relay what the operator needs to know, and answer a session with: hq lanes link send --child <name> --text '...'\n\n${messages}`
-            : `[conduct] The session conducting you sent this while you were working.\nTreat it as a new instruction from the operator, taking precedence over your current task where the two conflict. When you have something to tell the conductor - a result, a blocker, a question - send it with: hq lanes link report --state <working|blocked|idle|done> --text '...'\n\n${messages}`;
+            : `[conduct] The session conducting you sent this while you were working.\nTreat it as a new instruction from the operator, taking precedence over your current task where the two conflict. When you have something to tell the conductor - a result, a blocker, a question - send it with: hq lanes link report --state <working|blocked|idle|done> --text '...'\n\n${messages}`) + acceptance;
         return options.event === "PostToolUse"
-            ? { output: { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: body } } }
-            : { output: { decision: "block", reason: body } };
+            ? { output: { ...receipt, hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: body } } }
+            : { output: { ...receipt, decision: "block", reason: body } };
+    }
+    if (subcommand === "capabilities") {
+        return { output: { protocol: "conduct-recipient-acceptance/1", explicitClaim: true, recipientAck: true, idleWake: false } };
+    }
+    if (subcommand === "ack") {
+        const currentSid = requireSid();
+        const pointer = readPointer(root, currentSid);
+        if (!pointer)
+            throw new LaneLinkError("session_unlinked", "Session is not linked");
+        if (!options.link || options.link !== pointer.link || (options.child ?? null) !== (pointer.name ?? null)) {
+            throw new LaneLinkError("claim_owner_invalid", "Receipt does not match the current link/child binding");
+        }
+        const claims = options.claims?.split(",");
+        acknowledgeLinkClaims(hookMessage(root, pointer).inbox, claims);
+        return { output: { acknowledged: true, acceptance: "recipient_instruction_only" } };
     }
     if (subcommand === "open") {
         const sessionId = requireSid();
@@ -438,7 +656,7 @@ export async function runLaneLink(subcommand, options) {
         const dir = linkPath(root, link);
         const meta = readJson(path.join(dir, "meta.json"));
         const unread = countPending(path.join(dir, "up", "inbox"));
-        return { output: { ...meta, unread_reports: unread, children: listChildren(root, dir) } };
+        return { output: { ...meta, unread_reports: unread, quarantined_reports: countQuarantined(path.join(dir, "up", "inbox")), children: listChildren(root, dir) } };
     }
     if (subcommand === "leave") {
         const sessionId = requireSid();

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;