@indigoai-us/hq-cli 5.231.1 → 5.233.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [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
+
+- `checkpoint.ontology.sync-gated` (off by default) turns the checkpoint
+  ontology step on like `checkpoint.ontology`. Older CLI builds do not read it,
+  so it can be turned on widely without them. With either flag on, the step runs
+  only when the hq-cloud bundled with this CLI and the one the hq daemon runs
+  are both 6.18.7 or later; otherwise it skips and says which copy is older.
+  It also skips while the daemon's sync still runs from before its hq-cloud
+  copy was installed. `hq core ontology apply` checks again before it writes and
+  reports `sync_client_old` with the reason. Earlier hq-cloud releases pushed
+  stale copies of deleted entities.
+
 ## [5.231.1] — 2026-09-27
 
 ### Fixed

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/core-ontology.js

@@ -86,6 +86,8 @@ export function runOntologyApply(hqRoot, runDirOption, deps = {}) {
         throw new OntologyUsageError("ontology: the run payload names no company");
     }
     const report = applyOntologyRun({ hqRoot, runDir, company, now: deps.now?.() });
+    if (report.status === "sync_client_old")
+        return `ontology: skipped (${report.skip_reason}); nothing written`;
     if (report.status !== "applied")
         return `ontology: ${report.status.replaceAll("_", " ")}; nothing written`;
     return (`ontology: ${report.created.length} created, ${report.updated.length} updated, ` +

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/checkpoint-ontology/apply.d.ts

@@ -7,6 +7,7 @@
  */
 import { type DuplicateReport, type MergeBackOutcome } from "./multi-writer.js";
 import { type CompanyBriefResult } from "./company-brief.js";
+import { type SyncClientVersions } from "./sync-client.js";
 import { type WritableEntityType } from "./identity.js";
 import { type EntityIndex } from "./tree.js";
 export declare const CAPS: {
@@ -30,7 +31,9 @@ export interface ApplyReport {
     schema: "hq-checkpoint-ontology-report.v1";
     company: string;
     run_id: string;
-    status: "applied" | "no_candidates" | "invalid_candidates";
+    status: "applied" | "no_candidates" | "invalid_candidates" | "sync_client_old";
+    /** Present only with status `sync_client_old`: which sync client copy is older or unknown. */
+    skip_reason?: string;
     planned_inputs: number;
     planned_tokens: number;
     candidates: number;
@@ -94,6 +97,8 @@ export interface ApplyOptions {
     /** The payload company. Must equal the plan's company. */
     company: string;
     now?: Date;
+    /** Test seam for the sync client check; defaults to reading this machine's hq-cloud copies. */
+    syncClientVersions?: () => SyncClientVersions;
 }
 export declare class ApplyError extends Error {
     constructor(message: string);

package/dist/lib/checkpoint-ontology/apply.js

@@ -12,6 +12,7 @@ import { entityKey, freshAliases, MAX_NAME_LENGTH, ownNames } from "./aliases.js
 import { recordOutbox, scanDuplicates } from "./multi-writer.js";
 import { writeCompanyBrief } from "./company-brief.js";
 import { entitiesRoot, resolveOntologyCompany, safeWriteFile } from "./company.js";
+import { checkSyncClient, readSyncClientVersions } from "./sync-client.js";
 import { appendBackRefs, parseEntityFile, patchEntityFile, previewSignalContent, renderNewEntity, validateEntityFrontmatter, } from "./entity-file.js";
 import { canonicalizeName, entityId, isRejectedName, isWritableEntityType, normalizeEntityName, squash, toSlug, } from "./identity.js";
 import { CANDIDATES_FILE, CANDIDATES_SCHEMA, PLAN_FILE, PLAN_SCHEMA, REPORT_FILE, readLedger, writeLedger, } from "./plan.js";
@@ -232,6 +233,15 @@ export function applyOntologyRun(options) {
         fs.writeFileSync(path.join(options.runDir, REPORT_FILE), `${JSON.stringify(report, null, 2)}\n`);
         return report;
     };
+    // CO-45: the sync client can change between plan and apply, so check it
+    // again before anything is written.
+    const syncClient = checkSyncClient((options.syncClientVersions ?? readSyncClientVersions)());
+    if (!syncClient.ok) {
+        report.status = "sync_client_old";
+        report.skip_reason = syncClient.reason;
+        report.inputs_pending = plan.inputs.filter((i) => i.kind !== "session").map((i) => i.id);
+        return finish();
+    }
     const candidatesPath = path.join(options.runDir, CANDIDATES_FILE);
     if (!fs.existsSync(candidatesPath)) {
         report.status = "no_candidates";

package/dist/lib/checkpoint-ontology/plan.d.ts

@@ -11,7 +11,16 @@ import { type CompanyBriefResult } from "./company-brief.js";
 import { type OntologyCompany } from "./company.js";
 import { type MultiWriterStart } from "./multi-writer.js";
 import { type EntityHint } from "./hints.js";
+import { type SyncClientVersions } from "./sync-client.js";
 export declare const ONTOLOGY_FLAG = "checkpoint.ontology";
+/**
+ * Turns the step on like `checkpoint.ontology`, but only builds that check the
+ * sync client read it (CO-45, owner decision CO-D-005). Older CLI builds read
+ * only `checkpoint.ontology`, so this key can default on without starting the
+ * step next to an hq-cloud older than 6.18.7. Either key needs a sync client of
+ * 6.18.7 or later; see ./sync-client.ts.
+ */
+export declare const ONTOLOGY_SYNC_GATED_FLAG = "checkpoint.ontology.sync-gated";
 export declare const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
 /**
  * Applies only when the payload's sibling backend is grok. On gold-v2, Claude
@@ -159,6 +168,8 @@ export interface PlanOptions {
     payload: CheckpointPayloadLike;
     readFlag: FlagReader;
     now?: Date;
+    /** This machine's hq-cloud versions; defaults to reading them. */
+    syncClientVersions?: () => SyncClientVersions;
 }
 export type PlanOutcome = {
     status: "skipped";

package/dist/lib/checkpoint-ontology/plan.js

@@ -14,8 +14,17 @@ import { writeCompanyBrief } from "./company-brief.js";
 import { resolveOntologyCompany, safeWriteFile, stateRoot } from "./company.js";
 import { startMultiWriterRun } from "./multi-writer.js";
 import { entityHints, wordWeights } from "./hints.js";
+import { checkSyncClient, readSyncClientVersions } from "./sync-client.js";
 import { buildEntityIndex, listKnowledgeFiles, listSignalFiles, readSignal } from "./tree.js";
 export const ONTOLOGY_FLAG = "checkpoint.ontology";
+/**
+ * Turns the step on like `checkpoint.ontology`, but only builds that check the
+ * sync client read it (CO-45, owner decision CO-D-005). Older CLI builds read
+ * only `checkpoint.ontology`, so this key can default on without starting the
+ * step next to an hq-cloud older than 6.18.7. Either key needs a sync client of
+ * 6.18.7 or later; see ./sync-client.ts.
+ */
+export const ONTOLOGY_SYNC_GATED_FLAG = "checkpoint.ontology.sync-gated";
 export const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
 /**
  * Applies only when the payload's sibling backend is grok. On gold-v2, Claude
@@ -231,10 +240,12 @@ export async function planOntologyRun(options) {
     if (!resolution.ok)
         return { status: "skipped", reason: resolution.reason };
     const company = resolution.company;
-    if (!(await options.readFlag(ONTOLOGY_FLAG, company))) {
+    const ontologyOn = (await options.readFlag(ONTOLOGY_FLAG, company)) || (await options.readFlag(ONTOLOGY_SYNC_GATED_FLAG, company));
+    const syncClient = ontologyOn ? checkSyncClient((options.syncClientVersions ?? readSyncClientVersions)()) : null;
+    if (!ontologyOn || !syncClient?.ok) {
         // A preference recorded while the ontology was on must not outlive it.
         fs.rmSync(backendPreferencePath(hqRoot, company), { force: true });
-        return { status: "skipped", reason: "flag off" };
+        return { status: "skipped", reason: syncClient && !syncClient.ok ? syncClient.reason : "flag off" };
     }
     const briefOn = await options.readFlag(COMPANY_BRIEF_FLAG, company);
     const ignoreAnnotations = (await options.readFlag(IGNORE_ANNOTATIONS_FLAG, company)) && payload.backend === "grok";

package/dist/lib/checkpoint-ontology/sync-client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The sync client check for the checkpoint ontology step (CO-45, owner
+ * decision CO-D-005).
+ *
+ * The step writes entity files locally and a sync client pushes them. hq-cloud
+ * before 6.18.7 pushed stale local copies of deleted entities as new objects
+ * and overwrote newer entities with older ones (INC-CO-RESURRECT). hq-flags
+ * cannot target by client version, so the step checks this machine's hq-cloud
+ * copies itself: the one bundled with this CLI (`hq sync`) and the one the hq
+ * daemon runs. If either is older than 6.18.7, or the bundled copy cannot be
+ * read, the step does not run. The daemon picks up a new hq-cloud only when
+ * its sync unit restarts, so a sync unit that started before its copy was
+ * installed may still run older code; the step does not run then either.
+ *
+ * The desktop app's sync runner is not visible from here. The vault's
+ * `vault.refuse-stale-entity-recreate` guard refuses those two writes from any
+ * client.
+ */
+export declare const MIN_SYNC_CLIENT_VERSION = "6.18.7";
+export interface SyncClientVersions {
+    /** hq-cloud bundled with this CLI, or null when it cannot be read. */
+    bundled: string | null;
+    /** hq-cloud the hq daemon runs, or null when it cannot be read. */
+    daemon: string | null;
+    /** True when the daemon's running sync unit started before that copy was installed. */
+    daemonRestartPending?: boolean;
+}
+export type SyncClientCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Read this machine's hq-cloud versions. Never throws. */
+export declare function readSyncClientVersions(): SyncClientVersions;
+/** Every readable copy must be at least 6.18.7, and the bundled copy must be readable. */
+export declare function checkSyncClient(versions: SyncClientVersions): SyncClientCheck;
+//# sourceMappingURL=sync-client.d.ts.map

package/dist/lib/checkpoint-ontology/sync-client.js

@@ -0,0 +1,84 @@
+/**
+ * The sync client check for the checkpoint ontology step (CO-45, owner
+ * decision CO-D-005).
+ *
+ * The step writes entity files locally and a sync client pushes them. hq-cloud
+ * before 6.18.7 pushed stale local copies of deleted entities as new objects
+ * and overwrote newer entities with older ones (INC-CO-RESURRECT). hq-flags
+ * cannot target by client version, so the step checks this machine's hq-cloud
+ * copies itself: the one bundled with this CLI (`hq sync`) and the one the hq
+ * daemon runs. If either is older than 6.18.7, or the bundled copy cannot be
+ * read, the step does not run. The daemon picks up a new hq-cloud only when
+ * its sync unit restarts, so a sync unit that started before its copy was
+ * installed may still run older code; the step does not run then either.
+ *
+ * The desktop app's sync runner is not visible from here. The vault's
+ * `vault.refuse-stale-entity-recreate` guard refuses those two writes from any
+ * client.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import semver from "semver";
+import { bundledHqCloud, currentHqCloud } from "../daemon/hq-cloud.js";
+import { daemonPaths } from "../daemon/paths.js";
+export const MIN_SYNC_CLIENT_VERSION = "6.18.7";
+/** Read this machine's hq-cloud versions. Never throws. */
+export function readSyncClientVersions() {
+    const bundled = bundledHqCloud()?.version ?? null;
+    let daemon = null;
+    let daemonRestartPending = false;
+    try {
+        const paths = daemonPaths();
+        const picked = currentHqCloud(paths.root);
+        daemon = picked?.version ?? null;
+        if (picked) {
+            try {
+                daemonRestartPending = syncStartedBefore(paths.statePath, path.join(picked.root, "package.json"));
+            }
+            catch (err) {
+                // Unknown start time: assume the running sync may be older.
+                daemonRestartPending = true;
+                console.warn(`ontology: could not read the hq daemon's sync start time: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`ontology: could not read the hq daemon's hq-cloud version: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { bundled, daemon, daemonRestartPending };
+}
+/** Whether the daemon's running sync unit started before `copyPackageJson` was written. No state file: no running unit. */
+function syncStartedBefore(statePath, copyPackageJson) {
+    let state;
+    try {
+        state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    const sync = state.units?.find((u) => u.id === "sync" && u.status === "running");
+    if (!sync || typeof sync.startedAt !== "number")
+        return false;
+    return fs.statSync(copyPackageJson).mtimeMs > sync.startedAt;
+}
+/** Every readable copy must be at least 6.18.7, and the bundled copy must be readable. */
+export function checkSyncClient(versions) {
+    if (versions.bundled === null) {
+        return { ok: false, reason: `sync client version unknown; needs hq-cloud ${MIN_SYNC_CLIENT_VERSION} or later` };
+    }
+    for (const [name, version] of [["bundled", versions.bundled], ["daemon", versions.daemon]]) {
+        if (version === null)
+            continue;
+        const parsed = semver.valid(version);
+        if (parsed === null || semver.lt(parsed, MIN_SYNC_CLIENT_VERSION)) {
+            return { ok: false, reason: `sync client hq-cloud ${version} (${name}) is older than ${MIN_SYNC_CLIENT_VERSION}` };
+        }
+    }
+    if (versions.daemonRestartPending) {
+        return { ok: false, reason: `the hq daemon's sync has not restarted onto hq-cloud ${versions.daemon ?? "(unknown)"} yet` };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=sync-client.js.map

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