@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/lanes/types.js

@@ -0,0 +1,418 @@
+/**
+ * Lane record, question routing record, envelope, and config types (spec §3,
+ * §4, §5.5, §6.2). Finite sets are string-literal unions plus `const` arrays
+ * so the command layer can validate flags explicitly.
+ */
+import { LanesError, LaneSchemaError } from "./errors.js";
+export const LANE_SCHEMA_VERSION = "hq-lane.v1";
+export const QUESTION_SCHEMA_VERSION = "hq-lane-question.v1";
+export const ENVELOPE_SCHEMA_VERSION = "hq-lane-envelope.v1";
+export const CONFIG_SCHEMA_VERSION = "hq-lanes-config.v1";
+/** Lane terminal reason for an envelope still invalid after its one repair turn. */
+export const ENVELOPE_INVALID_REASON = "envelope_invalid";
+/**
+ * The envelope contract as a JSON schema. `parseLaneEnvelope` is the runtime
+ * check; this is the text handed to a worker on the repair turn (spec §4) so
+ * the two never drift apart in what they name.
+ */
+export const LANE_ENVELOPE_JSON_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "hq-lane-envelope.v1",
+    type: "object",
+    additionalProperties: false,
+    required: ["schema_version", "decision", "summary", "story_status", "artifacts"],
+    properties: {
+        schema_version: { const: "hq-lane-envelope.v1" },
+        decision: { enum: ["done", "ask", "blocked"] },
+        summary: { type: "string", minLength: 1 },
+        next_check_at: {
+            type: "string",
+            description: "Optional ISO date-time for a clock-based keep-alive check; invalid values are ignored.",
+        },
+        questions: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["question", "context", "options"],
+                properties: {
+                    id: { type: "string", minLength: 1, pattern: "\\S" },
+                    question: { type: "string" },
+                    context: { type: "string" },
+                    options: { type: "array", items: { type: "string" } },
+                    recommended: { type: "string" },
+                },
+            },
+        },
+        story_status: { enum: ["queued", "in_progress", "review", "done"] },
+        artifacts: { type: "array" },
+        blocked_reason: { type: "string" },
+        story_complete: { type: "boolean" },
+        story_complete_reason: { type: "string", minLength: 1 },
+    },
+    allOf: [
+        {
+            if: { properties: { decision: { const: "ask" } } },
+            then: { required: ["questions"], properties: { questions: { minItems: 1 } } },
+            else: { not: { required: ["questions"] } },
+        },
+        {
+            if: { properties: { decision: { const: "blocked" } } },
+            then: { required: ["blocked_reason"], properties: { blocked_reason: { minLength: 1 } } },
+            else: { not: { required: ["blocked_reason"] } },
+        },
+        {
+            if: { required: ["story_complete"], properties: { story_complete: { const: true } } },
+            then: {
+                required: ["story_complete_reason"],
+                properties: { story_status: { const: "done" }, story_complete_reason: { minLength: 1 } },
+            },
+            else: {
+                if: { required: ["story_complete"] },
+                then: {
+                    required: ["story_complete_reason"],
+                    properties: { story_status: { not: { const: "done" } }, story_complete_reason: { minLength: 1 } },
+                },
+                else: { not: { required: ["story_complete_reason"] } },
+            },
+        },
+    ],
+    description: "questions is present and non-empty exactly when decision is ask. " +
+        "blocked_reason is present exactly when decision is blocked. " +
+        "story_complete true requires story_status done; story_complete false requires story_status other than done; " +
+        "story_complete_reason is required whenever story_complete is present.",
+};
+export const LANE_STATES = [
+    "queued",
+    "running",
+    "awaiting_input",
+    "blocked",
+    "done",
+    "failed",
+    "interrupted",
+    "cancelled",
+    "killed",
+];
+/** Exact terminal set from spec §6.7. `awaiting_input` and `blocked` are not terminal. */
+export const TERMINAL_LANE_STATES = [
+    "done",
+    "failed",
+    "interrupted",
+    "cancelled",
+    "killed",
+];
+export const LANE_PROVIDERS = ["claude", "codex", "grok"];
+export const QUEUED_REASONS = [
+    "cap",
+    "provider_cap",
+    "account_cap",
+    "profile_cap",
+    "queue_position",
+    "throttle",
+    "provider_binary_missing",
+    "account_retry",
+    "worker_profile_changed",
+    "low_disk",
+];
+export function isQueuedReason(value) {
+    return typeof value === "string" && QUEUED_REASONS.includes(value);
+}
+export const HOST_KINDS = ["local", "outpost"];
+export const SENIOR_KINDS = ["session", "lane", "user"];
+export const ENVELOPE_DECISIONS = ["done", "ask", "blocked"];
+export const STORY_STATUSES = [
+    "queued",
+    "in_progress",
+    "review",
+    "done",
+];
+/** Durable Board status for a story carried by a lane. */
+export const LANE_STORY_STATUSES = [
+    "in_progress",
+    "blocked",
+    "review",
+    "done",
+];
+/**
+ * `expired` is accepted on read for records that already carry it. Spec §9
+ * ageing advances hop with `unanswered_timeout` and never expires a question,
+ * so reconcile (the only writer that may age without an operator) does not
+ * write this value. Kept in the enum so `--status expired` and old files parse.
+ */
+export const QUESTION_STATUSES = [
+    "pending",
+    "answered",
+    "cancelled",
+    "expired",
+];
+export const RAISED_VIA = ["cli", "envelope"];
+export const ROUTING_REASONS = [
+    "asked",
+    "escalated",
+    "audience_ended",
+    "reparented",
+    "unanswered_timeout",
+    "cancelled",
+];
+export const QUESTION_BODY_STORES = ["company", "personal"];
+export const LIVENESS_STATES = ["live", "idle", "ended", "lost"];
+export const HISTORY_CAP = 50;
+const TERMINAL_SET = new Set(TERMINAL_LANE_STATES);
+export function isLaneState(value) {
+    return typeof value === "string" && LANE_STATES.includes(value);
+}
+export function isTerminalLaneState(value) {
+    return typeof value === "string" && TERMINAL_SET.has(value);
+}
+export function isLaneProvider(value) {
+    return (typeof value === "string" &&
+        LANE_PROVIDERS.includes(value));
+}
+export function isSeniorKind(value) {
+    return (typeof value === "string" &&
+        SENIOR_KINDS.includes(value));
+}
+export function isHostKind(value) {
+    return (typeof value === "string" &&
+        HOST_KINDS.includes(value));
+}
+export function isEnvelopeDecision(value) {
+    return (typeof value === "string" &&
+        ENVELOPE_DECISIONS.includes(value));
+}
+export function isQuestionStatus(value) {
+    return (typeof value === "string" &&
+        QUESTION_STATUSES.includes(value));
+}
+export function isLivenessState(value) {
+    return (typeof value === "string" &&
+        LIVENESS_STATES.includes(value));
+}
+export function parseLaneProvider(value) {
+    if (isLaneProvider(value))
+        return value;
+    throw new LanesError("unknown_provider", `Unknown provider ${JSON.stringify(value)}. Accepted: ${LANE_PROVIDERS.join(", ")}`, { accepted: [...LANE_PROVIDERS], value });
+}
+export function parseLaneState(value) {
+    if (isLaneState(value))
+        return value;
+    throw new LanesError("unknown_state", `Unknown lane state ${JSON.stringify(value)}. Accepted: ${LANE_STATES.join(", ")}`, { accepted: [...LANE_STATES], value });
+}
+export function parseQuestionStatus(value) {
+    if (isQuestionStatus(value))
+        return value;
+    throw new LanesError("unknown_status", `Unknown question status ${JSON.stringify(value)}. Accepted: ${QUESTION_STATUSES.join(", ")}`, { accepted: [...QUESTION_STATUSES], value });
+}
+export function parseLivenessState(value) {
+    if (isLivenessState(value))
+        return value;
+    throw new LanesError("unknown_state", `Unknown session liveness state ${JSON.stringify(value)}. Accepted: ${LIVENESS_STATES.join(", ")}`, { accepted: [...LIVENESS_STATES], value });
+}
+export function parseSeniorKind(value) {
+    if (isSeniorKind(value))
+        return value;
+    throw new LanesError("unknown_senior_kind", `Unknown senior kind ${JSON.stringify(value)}. Accepted: ${SENIOR_KINDS.join(", ")}`, { accepted: [...SENIOR_KINDS], value });
+}
+/** The v1 fields that must exist on every durable lane record (spec §3). */
+export const REQUIRED_LANE_RECORD_FIELDS = [
+    "schema_version", "lane_id", "company", "project_id", "story_id", "depth",
+    "senior", "senior_history", "state", "priority", "provider", "host",
+    "version", "created_at", "updated_at", "attribution_history",
+];
+export const LANE_WRITERS = ["creator", "command", "watcher", "reconcile", "spawn", "story-ledger"];
+/** Field ownership at the durable-record mutation boundary (spec §10.1). */
+export const LANE_FIELD_WRITERS = {
+    schema_version: ["creator"], lane_id: ["creator"], written_by_version: [], owner_written_by_version: [], company: ["creator"],
+    project_id: ["command"], story_id: ["command"], no_story_reason: ["creator", "command"], ledger_sync_error: ["story-ledger"], pending_question_ids: ["story-ledger"], stories: ["creator", "command", "watcher", "reconcile", "spawn"], thread_id: ["creator", "command", "spawn"], mesh_company: ["creator", "command"],
+    depth: ["command"], senior: ["command"], senior_history: ["command"],
+    hire_grant: ["creator", "command"],
+    state: ["creator", "command", "watcher", "reconcile", "spawn"], queued_reason: ["creator", "command", "spawn", "watcher", "reconcile"], queued_details: ["command", "reconcile", "spawn", "watcher"], queued_at: ["creator", "command", "spawn", "watcher", "reconcile"], admission_reserved_at: ["creator", "command", "reconcile", "spawn", "watcher"],
+    pickup_validation_pending: ["creator", "command", "spawn", "reconcile"],
+    pickup_validation_pending_since: ["creator", "command", "spawn", "reconcile"],
+    priority: ["command"], worker: ["creator", "command"], worker_path: ["creator", "command"], worker_pack: ["creator", "command"], worker_profile: ["creator", "command"], worker_profile_hash: ["creator", "command", "spawn"], registry_worker: ["creator", "command", "spawn"], registry_worker_approval_history: ["command", "watcher", "reconcile"], worker_profile_repin_history: ["command"], worker_profile_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],
+    keep_alive: ["creator", "command"], keep_alive_standing: ["command"], keep_alive_opted_in_at: ["creator", "command"], keep_alive_blocked_reason: ["command", "reconcile"], keep_alive_resume_count: ["command", "reconcile"], keep_alive_history: ["reconcile"], keep_alive_blocked_resume_streak: ["reconcile", "spawn", "watcher"], keep_alive_last_resume_at: ["command", "reconcile"], keep_alive_next_eligible_at: ["command", "reconcile"], keep_alive_exhausted_at: ["command", "reconcile"],
+    provider: ["creator"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_selection: ["creator", "command"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], failed_resume_history: ["command"], fallback_question_cancellation_failures: ["command"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
+    version: ["creator"], created_at: ["creator"], updated_at: ["creator"], ended_at: ["reconcile"], envelope_summary: ["reconcile"], attribution_history: ["command", "watcher", "reconcile"], story_switch_pending: ["command", "watcher", "reconcile"], story_switch_unacknowledged: ["watcher", "reconcile"],
+    last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
+    last_message_at: ["command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher", "reconcile"], blocker_freshness_state: ["watcher"], kr_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
+    overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],
+    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command", "reconcile"], settings_history: ["command"], pending_settings: ["command", "spawn"], interrupted_at: ["command", "watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
+    quota_reset_at: ["watcher", "reconcile"], model_quota_marker: ["watcher", "reconcile"], outpost_command_id: ["command"],
+    provider_session_id: ["watcher", "command", "spawn"], provider_session_id_absent: ["watcher", "command"], provider_home_at_spawn: ["spawn"], last_resume: ["spawn"], resume_history: ["spawn", "watcher"], last_run_usage: ["watcher"], last_run_usage_at: ["watcher"], envelope_repair: ["watcher", "reconcile"], envelope_validation_errors: ["watcher"], last_progress_event_at: ["watcher"],
+};
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new LaneSchemaError(`Expected non-empty string for ${field}`, {
+            field,
+        });
+    }
+    return value;
+}
+export function isIsoDateTime(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(Z|[+-](\d{2}):(\d{2}))$/.exec(value);
+    if (!match)
+        return false;
+    const [, yearText, monthText, dayText, hourText, minuteText, secondText, , offsetHourText, offsetMinuteText] = match;
+    const year = Number(yearText);
+    const month = Number(monthText);
+    const day = Number(dayText);
+    const hour = Number(hourText);
+    const minute = Number(minuteText);
+    const second = Number(secondText);
+    const offsetHour = offsetHourText === undefined ? 0 : Number(offsetHourText);
+    const offsetMinute = offsetMinuteText === undefined ? 0 : Number(offsetMinuteText);
+    const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
+    return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth &&
+        hour <= 23 && minute <= 59 && second <= 59 && offsetHour <= 23 && offsetMinute <= 59 &&
+        Number.isFinite(Date.parse(value));
+}
+export function parseMajorSchema(schemaVersion, expectedPrefix, expectedMajor) {
+    const match = new RegExp(`^${expectedPrefix}\\.v(\\d+)$`).exec(schemaVersion);
+    if (!match) {
+        throw new LaneSchemaError(`Unknown schema_version ${JSON.stringify(schemaVersion)} (expected ${expectedPrefix}.v${expectedMajor})`, { schema_version: schemaVersion, expected: `${expectedPrefix}.v${expectedMajor}` });
+    }
+    const major = Number(match[1]);
+    if (major !== expectedMajor) {
+        throw new LaneSchemaError(`Unsupported ${expectedPrefix} major version ${major} (found ${schemaVersion})`, { schema_version: schemaVersion, major });
+    }
+}
+export function parseLaneEnvelope(raw) {
+    if (!isPlainObject(raw)) {
+        throw new LaneSchemaError("Lane envelope must be a JSON object");
+    }
+    const extra = Object.keys(raw).filter((key) => ![
+        "schema_version",
+        "decision",
+        "summary",
+        "next_check_at",
+        "questions",
+        "story_status",
+        "artifacts",
+        "blocked_reason",
+        "story_complete",
+        "story_complete_reason",
+    ].includes(key));
+    if (extra.length > 0) {
+        throw new LaneSchemaError(`Lane envelope rejects unknown properties: ${extra.join(", ")}`, { extra });
+    }
+    const schema_version = requireString(raw.schema_version, "schema_version");
+    parseMajorSchema(schema_version, "hq-lane-envelope", 1);
+    if (!isEnvelopeDecision(raw.decision)) {
+        throw new LaneSchemaError(`Unknown envelope decision ${JSON.stringify(raw.decision)}. Accepted: ${ENVELOPE_DECISIONS.join(", ")}`, { accepted: [...ENVELOPE_DECISIONS], value: raw.decision });
+    }
+    const summary = requireString(raw.summary, "summary");
+    let nextCheckAt;
+    if (raw.next_check_at !== undefined) {
+        if (typeof raw.next_check_at !== "string") {
+            throw new LaneSchemaError("next_check_at must be a string", { field: "next_check_at" });
+        }
+        nextCheckAt = raw.next_check_at;
+    }
+    if (typeof raw.story_status !== "string" ||
+        !STORY_STATUSES.includes(raw.story_status)) {
+        throw new LaneSchemaError(`Unknown story_status ${JSON.stringify(raw.story_status)}. Accepted: ${STORY_STATUSES.join(", ")}`, { accepted: [...STORY_STATUSES], value: raw.story_status });
+    }
+    if (!Array.isArray(raw.artifacts)) {
+        throw new LaneSchemaError("Envelope artifacts must be an array");
+    }
+    const questions = raw.questions;
+    if (raw.decision === "ask") {
+        if (!Array.isArray(questions) || questions.length === 0) {
+            throw new LaneSchemaError('questions must be non-empty when decision is "ask"');
+        }
+    }
+    else if (questions !== undefined) {
+        throw new LaneSchemaError('questions is present exactly when decision is "ask"');
+    }
+    if (raw.decision === "blocked") {
+        if (typeof raw.blocked_reason !== "string" || raw.blocked_reason.length === 0) {
+            throw new LaneSchemaError('blocked_reason is required when decision is "blocked"');
+        }
+    }
+    else if (raw.blocked_reason !== undefined) {
+        throw new LaneSchemaError('blocked_reason is present exactly when decision is "blocked"');
+    }
+    const storyStatus = raw.story_status;
+    let storyComplete;
+    let storyCompleteReason;
+    if (raw.story_complete !== undefined) {
+        if (typeof raw.story_complete !== "boolean") {
+            throw new LaneSchemaError("story_complete must be a boolean", {
+                field: "story_complete",
+            });
+        }
+        if (typeof raw.story_complete_reason !== "string" ||
+            raw.story_complete_reason.trim().length === 0) {
+            throw new LaneSchemaError("story_complete_reason is required when story_complete is present", { field: "story_complete_reason" });
+        }
+        if (raw.story_complete === true && storyStatus !== "done") {
+            throw new LaneSchemaError("story_complete true requires story_status done", {
+                error: "story_complete_status_mismatch",
+                story_complete: true,
+                story_status: storyStatus,
+            });
+        }
+        if (raw.story_complete === false && storyStatus === "done") {
+            throw new LaneSchemaError("story_complete false forbids story_status done", {
+                error: "story_complete_status_mismatch",
+                story_complete: false,
+                story_status: storyStatus,
+            });
+        }
+        storyComplete = raw.story_complete;
+        storyCompleteReason = raw.story_complete_reason.trim();
+    }
+    else if (raw.story_complete_reason !== undefined) {
+        throw new LaneSchemaError("story_complete_reason is present exactly when story_complete is present", { field: "story_complete_reason" });
+    }
+    const envelope = {
+        schema_version: ENVELOPE_SCHEMA_VERSION,
+        decision: raw.decision,
+        summary,
+        story_status: storyStatus,
+        artifacts: raw.artifacts,
+    };
+    if (nextCheckAt !== undefined)
+        envelope.next_check_at = nextCheckAt;
+    if (storyComplete !== undefined) {
+        envelope.story_complete = storyComplete;
+        envelope.story_complete_reason = storyCompleteReason;
+    }
+    if (Array.isArray(questions) && questions.length > 0) {
+        envelope.questions = questions.map((item, index) => {
+            if (!isPlainObject(item)) {
+                throw new LaneSchemaError(`questions[${index}] must be an object`);
+            }
+            const options = item.options;
+            if (!Array.isArray(options) ||
+                options.some((opt) => typeof opt !== "string")) {
+                throw new LaneSchemaError(`questions[${index}].options must be string[]`);
+            }
+            const parsed = {
+                question: requireString(item.question, `questions[${index}].question`),
+                context: requireString(item.context, `questions[${index}].context`),
+                options,
+            };
+            if (item.id !== undefined) {
+                if (typeof item.id !== "string" || item.id.trim().length === 0) {
+                    throw new LaneSchemaError(`Expected non-empty string for questions[${index}].id`, {
+                        field: `questions[${index}].id`,
+                    });
+                }
+                parsed.id = item.id;
+            }
+            if (item.recommended !== undefined) {
+                parsed.recommended = requireString(item.recommended, `questions[${index}].recommended`);
+            }
+            return parsed;
+        });
+    }
+    if (typeof raw.blocked_reason === "string") {
+        envelope.blocked_reason = raw.blocked_reason;
+    }
+    return envelope;
+}
+//# sourceMappingURL=types.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/dist/lib/lanes/watch.d.ts

@@ -0,0 +1,39 @@
+import { type LaneHost, type LaneProvider, type LaneRecord, type QuestionRecord } from "./types.js";
+export declare const DEFAULT_LANE_WATCH_INTERVAL_MS = 5000;
+export declare const MAX_LANE_WATCH_INTERVAL_MS = 30000;
+export declare const MAX_WATCHED_LANES = 64;
+export declare const MAX_WATCH_OUTPUT_LINES = 512;
+export interface LaneWatchAccountStatus {
+    lane_id: string;
+    provider: LaneProvider;
+    account: string;
+    host: LaneHost;
+    logged_in: boolean | null;
+}
+export interface LaneAccountLoggedOutEvent {
+    event: "account_logged_out";
+    provider: LaneProvider;
+    account: string;
+    host: LaneHost;
+    lane_ids: string[];
+}
+export interface LaneWatchDeps {
+    readLane?: (hqRoot: string, laneId: string) => LaneRecord | null;
+    listQuestionIds?: (hqRoot: string) => string[];
+    readQuestion?: (hqRoot: string, questionId: string) => QuestionRecord | null;
+    readAccountStatuses?: (lanes: readonly LaneRecord[]) => Promise<readonly LaneWatchAccountStatus[]>;
+    keepAliveEnabled?: (lane: LaneRecord) => boolean | Promise<boolean>;
+    sleep?: (ms: number) => Promise<void>;
+    intervalMs?: number;
+    maxOutputLines?: number;
+    writeLine?: (line: string) => void;
+    writeAccountEvent?: (event: LaneAccountLoggedOutEvent) => void;
+    writeError?: (line: string) => void;
+}
+export interface LaneWatchResult {
+    polls: number;
+    lines: number;
+    suppressed: boolean;
+}
+export declare function runLaneWatch(hqRoot: string, laneIds: readonly string[], deps?: LaneWatchDeps): Promise<LaneWatchResult>;
+//# sourceMappingURL=watch.d.ts.map