@indigoai-us/hq-cli 5.232.0 → 5.233.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.233.0] — 2026-09-27
+
+### Added
+
+- `hq lanes wait` exits on the first selected envelope, pending-question, or
+  state change across the requested lanes. It uses a startup baseline and a
+  bounded two-second poll interval.
+
 ## [5.232.0] — 2026-09-27
 
 ### Added

package/dist/command-catalog.generated.d.ts

@@ -7773,6 +7773,27 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "JSON on stdout (always)";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "wait";
+        readonly description: "Wait for the first requested change across lanes";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--any <lane-id...>";
+            readonly description: "Lane ids to monitor";
+        }, {
+            readonly flags: "--for <change-type>";
+            readonly description: "envelope | question | state";
+        }, {
+            readonly flags: "--timeout <seconds>";
+            readonly description: "Positive timeout in seconds";
+        }, {
+            readonly flags: "--json";
+            readonly description: "JSON output";
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "watch";
         readonly description: "Watch lane state and question changes until all lanes are terminal";

package/dist/command-catalog.generated.js

@@ -10051,6 +10051,33 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "wait",
+                "description": "Wait for the first requested change across lanes",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--any <lane-id...>",
+                        "description": "Lane ids to monitor"
+                    },
+                    {
+                        "flags": "--for <change-type>",
+                        "description": "envelope | question | state"
+                    },
+                    {
+                        "flags": "--timeout <seconds>",
+                        "description": "Positive timeout in seconds"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "JSON output"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "watch",
                 "description": "Watch lane state and question changes until all lanes are terminal",

package/dist/commands/lanes.js

@@ -52,6 +52,7 @@ import { compactionAfterUsage, } from "../lib/lanes/compaction.js";
 import { assertUniqueAccountHomes, providerCompactAfterMs } from "../lib/lanes/config.js";
 import { parseCliEffort, resolveLaneEffort, } from "../lib/lanes/effort.js";
 import { LanesError } from "../lib/lanes/errors.js";
+import { LANE_WAIT_INVALID_INPUT_EXIT_CODE, LANE_WAIT_TIMEOUT_EXIT_CODE, runLaneWait, } from "../lib/lanes/wait.js";
 import { dispatchLaneDelivery } from "../lib/lanes/delivery-core.js";
 import { dropboxInboxHasMessages, drainDropbox, formatDropboxMessages, formatMonitorEvent, requeueDropboxMessages, } from "../lib/lanes/dropbox.js";
 import { isPidAlive, runWatcherLoop, WATCHER_OUT_MAX_BYTES, watcherOutLogPath, writeWatcherDecision, } from "../lib/lanes/watcher.js";
@@ -2127,6 +2128,37 @@ function yieldEventLoop() {
         setImmediate(resolve);
     });
 }
+function laneWaitHumanLine(result) {
+    const details = Object.entries(result.change)
+        .filter(([key]) => key !== "type")
+        .map(([key, value]) => `${key}=${String(value)}`)
+        .join(" ");
+    return `lane=${result.lane_id} change=${result.change.type}${details ? ` ${details}` : ""} at=${result.at}`;
+}
+async function runWait(ctx, opts) {
+    const timeoutSeconds = opts.timeout === undefined ? Number.NaN : Number(opts.timeout);
+    try {
+        const result = await runLaneWait(ctx.hqRoot(), opts.any ?? [], opts.for ?? [], timeoutSeconds * 1000, { now: ctx.now, sleep: ctx.sleep });
+        if (result) {
+            console.log(opts.json ? JSON.stringify(result) : laneWaitHumanLine(result));
+            return 0;
+        }
+        console.log(opts.json
+            ? JSON.stringify({ ok: false, error: "wait_timeout" })
+            : "wait_timeout");
+        return LANE_WAIT_TIMEOUT_EXIT_CODE;
+    }
+    catch (err) {
+        if (!isLanesError(err) || err.error !== "wait_invalid_input")
+            throw err;
+        const output = { ok: false, error: err.error, message: err.message };
+        if (opts.json)
+            console.log(JSON.stringify(output));
+        else
+            process.stderr.write(`${err.message}\n`);
+        return LANE_WAIT_INVALID_INPUT_EXIT_CODE;
+    }
+}
 function withCasRetry(fn, attempts = 5) {
     let last;
     for (let i = 0; i < attempts; i += 1) {
@@ -9492,6 +9524,14 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (laneId, opts) => {
         await runAdmit(ctx, laneId, opts);
     }));
+    lanes
+        .command("wait")
+        .description("Wait for the first requested change across lanes")
+        .option("--any <lane-id...>", "Lane ids to monitor")
+        .option("--for <change-type>", "envelope | question | state", collectRepeatable, [])
+        .option("--timeout <seconds>", "Positive timeout in seconds")
+        .option("--json", "JSON output")
+        .action(wrapText(async (opts) => runWait(ctx, opts)));
     lanes
         .command("watch")
         .description("Watch lane state and question changes until all lanes are terminal")

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

@@ -0,0 +1,39 @@
+import type { LaneRecord, QuestionRecord } from "./types.js";
+export declare const LANE_WAIT_POLL_INTERVAL_MS = 2000;
+export declare const LANE_WAIT_MAX_LANES = 64;
+export declare const LANE_WAIT_TIMEOUT_EXIT_CODE = 4;
+export declare const LANE_WAIT_INVALID_INPUT_EXIT_CODE = 2;
+export declare const LANE_WAIT_CHANGE_TYPES: readonly ["envelope", "question", "state"];
+export type LaneWaitChangeType = (typeof LANE_WAIT_CHANGE_TYPES)[number];
+export type LaneWaitChange = {
+    type: "envelope";
+    ref: string;
+    decision: "done" | "ask" | "blocked";
+} | {
+    type: "question";
+    question_id: string;
+} | {
+    type: "state";
+    from: string;
+    to: string;
+};
+export interface LaneWaitResult {
+    ok: true;
+    lane_id: string;
+    change: LaneWaitChange;
+    at: string;
+}
+export interface LaneWaitDeps {
+    readLane?: (hqRoot: string, laneId: string) => LaneRecord | null;
+    listQuestionIds?: (hqRoot: string) => string[];
+    readQuestion?: (hqRoot: string, questionId: string) => QuestionRecord | null;
+    now?: () => Date;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Wait for the first requested change after taking a read-only baseline.
+ * Each poll reads every selected lane once and runs no lane-store mutation or
+ * lock. Question records are scanned in one pass when question changes matter.
+ */
+export declare function runLaneWait(hqRoot: string, laneIds: readonly string[], changeTypes: readonly string[], timeoutMs: number, deps?: LaneWaitDeps): Promise<LaneWaitResult | null>;
+//# sourceMappingURL=wait.d.ts.map

package/dist/lib/lanes/wait.js

@@ -0,0 +1,159 @@
+import { listQuestionIds, readLane, readQuestion } from "./store.js";
+import { LanesError } from "./errors.js";
+export const LANE_WAIT_POLL_INTERVAL_MS = 2_000;
+export const LANE_WAIT_MAX_LANES = 64;
+export const LANE_WAIT_TIMEOUT_EXIT_CODE = 4;
+export const LANE_WAIT_INVALID_INPUT_EXIT_CODE = 2;
+export const LANE_WAIT_CHANGE_TYPES = ["envelope", "question", "state"];
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function invalidInput(message, details = {}) {
+    throw new LanesError("wait_invalid_input", message, details);
+}
+function validateInput(laneIds, changeTypes, timeoutMs) {
+    const normalizedLaneIds = laneIds.map((laneId) => laneId.trim());
+    if (normalizedLaneIds.length === 0 || normalizedLaneIds.some((laneId) => laneId.length === 0)) {
+        invalidInput("hq lanes wait requires at least one non-empty lane id", { lane_ids: laneIds });
+    }
+    if (normalizedLaneIds.some((laneId) => laneId === "." || laneId === ".." || /[\\/]/.test(laneId))) {
+        invalidInput("Lane ids must not contain path separators", { lane_ids: laneIds });
+    }
+    const uniqueLaneIds = [...new Set(normalizedLaneIds)];
+    if (uniqueLaneIds.length > LANE_WAIT_MAX_LANES) {
+        invalidInput(`hq lanes wait accepts at most ${LANE_WAIT_MAX_LANES} lane ids`, {
+            max: LANE_WAIT_MAX_LANES,
+        });
+    }
+    if (changeTypes.length === 0 || changeTypes.some((kind) => !LANE_WAIT_CHANGE_TYPES.includes(kind))) {
+        invalidInput(`hq lanes wait requires one or more --for values: ${LANE_WAIT_CHANGE_TYPES.join(", ")}`, { accepted: [...LANE_WAIT_CHANGE_TYPES], values: changeTypes });
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || !Number.isSafeInteger(Math.ceil(timeoutMs))) {
+        invalidInput("hq lanes wait requires a positive finite timeout", { timeout_ms: timeoutMs });
+    }
+    return {
+        laneIds: uniqueLaneIds,
+        changeTypes: [...new Set(changeTypes)],
+    };
+}
+function snapshotLanes(hqRoot, laneIds, changeTypes, deps) {
+    const readLaneRecord = deps.readLane ?? readLane;
+    const lanes = new Map();
+    for (const laneId of laneIds) {
+        const lane = readLaneRecord(hqRoot, laneId);
+        if (!lane) {
+            throw new LanesError("wait_lane_unreadable", `Lane ${laneId} could not be read while waiting`, { lane_id: laneId });
+        }
+        lanes.set(laneId, lane);
+    }
+    const pendingQuestions = new Map();
+    if (changeTypes.includes("question")) {
+        const listIds = deps.listQuestionIds ?? listQuestionIds;
+        const readQuestionRecord = deps.readQuestion ?? readQuestion;
+        for (const questionId of new Set(listIds(hqRoot))) {
+            const question = readQuestionRecord(hqRoot, questionId);
+            if (!question) {
+                throw new LanesError("wait_question_unreadable", `Question ${questionId} disappeared while waiting`, { question_id: questionId });
+            }
+            if (question.status === "pending" && lanes.has(question.lane_id)) {
+                pendingQuestions.set(questionId, question);
+            }
+        }
+    }
+    return { lanes, pendingQuestions };
+}
+function timestamp(value, fallbackMs) {
+    const parsed = value === undefined ? Number.NaN : Date.parse(value);
+    const atMs = Number.isFinite(parsed) ? parsed : fallbackMs;
+    return { at: new Date(atMs).toISOString(), atMs };
+}
+function envelopeSignature(lane) {
+    const envelope = lane.last_envelope;
+    return envelope === undefined
+        ? undefined
+        : `${envelope.ref}\0${envelope.decision}\0${envelope.at}`;
+}
+function candidatesForSnapshot(previous, current, laneIds, changeTypes, observedAtMs) {
+    const candidates = [];
+    laneIds.forEach((laneId, laneOrder) => {
+        const before = previous.lanes.get(laneId);
+        const after = current.lanes.get(laneId);
+        if (!before || !after)
+            return;
+        changeTypes.forEach((type, typeOrder) => {
+            if (type === "envelope" && envelopeSignature(before) !== envelopeSignature(after)) {
+                const envelope = after.last_envelope;
+                if (envelope) {
+                    const when = timestamp(envelope.at, observedAtMs);
+                    candidates.push({
+                        laneId,
+                        change: { type, ref: envelope.ref, decision: envelope.decision },
+                        ...when,
+                        laneOrder,
+                        typeOrder,
+                    });
+                }
+            }
+            if (type === "state" && before.state !== after.state) {
+                const when = timestamp(after.updated_at, observedAtMs);
+                candidates.push({
+                    laneId,
+                    change: { type, from: before.state, to: after.state },
+                    ...when,
+                    laneOrder,
+                    typeOrder,
+                });
+            }
+            if (type === "question") {
+                for (const [questionId, question] of current.pendingQuestions) {
+                    if (question.lane_id !== laneId || previous.pendingQuestions.has(questionId))
+                        continue;
+                    const when = timestamp(question.asked_at, observedAtMs);
+                    candidates.push({
+                        laneId,
+                        change: { type, question_id: questionId },
+                        ...when,
+                        laneOrder,
+                        typeOrder,
+                    });
+                }
+            }
+        });
+    });
+    return candidates.sort((a, b) => a.atMs - b.atMs || a.laneOrder - b.laneOrder || a.typeOrder - b.typeOrder);
+}
+/**
+ * Wait for the first requested change after taking a read-only baseline.
+ * Each poll reads every selected lane once and runs no lane-store mutation or
+ * lock. Question records are scanned in one pass when question changes matter.
+ */
+export async function runLaneWait(hqRoot, laneIds, changeTypes, timeoutMs, deps = {}) {
+    const input = validateInput(laneIds, changeTypes, timeoutMs);
+    const now = deps.now ?? (() => new Date());
+    const sleep = deps.sleep ?? defaultSleep;
+    const startedAtMs = now().getTime();
+    const deadlineMs = startedAtMs + timeoutMs;
+    let previous = snapshotLanes(hqRoot, input.laneIds, input.changeTypes, deps);
+    while (true) {
+        const remainingMs = deadlineMs - now().getTime();
+        if (remainingMs <= 0)
+            return null;
+        await sleep(Math.min(LANE_WAIT_POLL_INTERVAL_MS, remainingMs));
+        const observedAtMs = now().getTime();
+        const current = snapshotLanes(hqRoot, input.laneIds, input.changeTypes, deps);
+        const candidates = candidatesForSnapshot(previous, current, input.laneIds, input.changeTypes, observedAtMs);
+        const first = candidates.find((candidate) => candidate.atMs <= deadlineMs);
+        if (first) {
+            return {
+                ok: true,
+                lane_id: first.laneId,
+                change: first.change,
+                at: first.at,
+            };
+        }
+        if (observedAtMs >= deadlineMs)
+            return null;
+        previous = current;
+    }
+}
+//# sourceMappingURL=wait.js.map

package/package.json

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