@indigoai-us/hq-cli 5.313.0 → 5.314.0

package/dist/lib/lanes/types.js

@@ -1,418 +0,0 @@
-/**
- * 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

@@ -1,39 +0,0 @@
-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

@@ -1,159 +0,0 @@
-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

@@ -1,39 +0,0 @@
-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