@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/dist/lib/lanes/liveness.js

@@ -0,0 +1,332 @@
+/**
+ * Session liveness from the work-mesh spool (spec §9).
+ *
+ * Source: ~/.hq/work-mesh/spool.jsonl, events session_start / turn_start /
+ * turn_end / session_end keyed by session id. Nothing latches, including
+ * `ended` — a later event for a reused id supersedes session_end.
+ *
+ * An index is a single compact file (workspace/lanes/sessions/index.json).
+ * This module never stats workspace/sessions/.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { workMeshSpoolPath, workMeshRoot } from "../mesh/live/paths.js";
+import { daemonDir, daemonStatePath } from "../mesh/live/daemon/paths.js";
+import { LanesError } from "./errors.js";
+import { DEFAULT_LIVE_WITHIN_MS, DEFAULT_SILENT_LOST_MS, DEFAULT_TURN_START_LOST_MS, loadLanesConfig, } from "./config.js";
+import { lanesStoreRoot } from "./store.js";
+export const LIVE_WITHIN_MS = DEFAULT_LIVE_WITHIN_MS;
+export const TURN_START_LOST_MS = DEFAULT_TURN_START_LOST_MS;
+export const SILENT_LOST_MS = DEFAULT_SILENT_LOST_MS;
+export const LIVENESS_EVENT_KINDS = [
+    "session_start",
+    "turn_start",
+    "turn_end",
+    "session_end",
+];
+export function defaultLivenessDeps() {
+    return {
+        now: () => Date.now(),
+        homedir: () => os.homedir(),
+        env: process.env,
+        readFileSync: (file, encoding) => fs.readFileSync(file, encoding),
+        writeFileSync: fs.writeFileSync.bind(fs),
+        renameSync: fs.renameSync.bind(fs),
+        unlinkSync: fs.unlinkSync.bind(fs),
+        existsSync: (file) => fs.existsSync(file),
+        mkdirSync: fs.mkdirSync.bind(fs),
+        statSync: (file) => fs.statSync(file),
+    };
+}
+export function defaultSpoolPath(deps = defaultLivenessDeps()) {
+    return workMeshSpoolPath(workMeshRoot(deps.homedir(), deps.env));
+}
+export function livenessIndexPath(hqRoot) {
+    return path.join(lanesStoreRoot(hqRoot), "sessions", "index.json");
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Classify one session from its last spool event. `ended` is not latched:
+ * a later event for the same id is classified from that later event.
+ *
+ * Mid-turn (`turn_start` younger than 2h) stays `live` even after the 10
+ * minute recency window — spec §9's prose treats that as working, not idle.
+ * `session_end` as the last event is `ended` even when recent (fast path).
+ */
+export function classifySessionLiveness(entry, nowMs, presenceConnected = false, windows = {
+    live_within_ms: LIVE_WITHIN_MS,
+    turn_start_lost_ms: TURN_START_LOST_MS,
+    silent_lost_ms: SILENT_LOST_MS,
+}) {
+    const at = Date.parse(entry.lastAt);
+    const age = Number.isFinite(at) ? nowMs - at : Number.POSITIVE_INFINITY;
+    const kind = entry.lastKind;
+    if (kind === "session_end")
+        return "ended";
+    // Box-wide MQTT connected is not per-session presence. A crashed
+    // mid-turn session must still become `lost` so §6.8 can advance.
+    void presenceConnected;
+    if (kind === "turn_start" && age < windows.turn_start_lost_ms)
+        return "live";
+    if (age <= windows.live_within_ms)
+        return "live";
+    if (kind === "turn_start" && age >= windows.turn_start_lost_ms)
+        return "lost";
+    if (age >= windows.silent_lost_ms)
+        return "lost";
+    if (kind === "turn_end")
+        return "idle";
+    return "idle";
+}
+export function ingestSpoolLine(line, sessions, lineNo) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (err) {
+        process.stderr.write(`lanes liveness: skipping malformed spool line ${lineNo}: ${err instanceof Error ? err.message : String(err)}\n`);
+        return;
+    }
+    if (!isPlainObject(parsed))
+        return;
+    const sessionId = typeof parsed.sessionId === "string" ? parsed.sessionId : "";
+    const kind = typeof parsed.kind === "string" ? parsed.kind : "";
+    const at = typeof parsed.at === "string" ? parsed.at : "";
+    if (!sessionId || !kind || !at)
+        return;
+    if (!Number.isFinite(Date.parse(at))) {
+        process.stderr.write(`lanes liveness: skipping spool line ${lineNo} with unparseable at\n`);
+        return;
+    }
+    const existing = sessions[sessionId];
+    const seq = typeof parsed.seq === "number" ? parsed.seq : undefined;
+    if (existing) {
+        const existingAt = Date.parse(existing.lastAt);
+        const nextAt = Date.parse(at);
+        if (nextAt < existingAt)
+            return;
+        if (nextAt === existingAt &&
+            seq !== undefined &&
+            existing.lastSeq !== undefined &&
+            seq < existing.lastSeq) {
+            return;
+        }
+    }
+    const entry = { sessionId, lastKind: kind, lastAt: at };
+    if (seq !== undefined)
+        entry.lastSeq = seq;
+    sessions[sessionId] = entry;
+}
+export function buildLivenessIndexFromSpool(spoolContents, meta) {
+    const sessions = {};
+    const lines = spoolContents.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        ingestSpoolLine(lines[i] ?? "", sessions, i + 1);
+    }
+    return {
+        schema_version: "hq-lane-liveness-index.v1",
+        built_at: meta.built_at,
+        spool_path: meta.spool_path,
+        spool_bytes: meta.spool_bytes,
+        spool_mtime_ms: meta.spool_mtime_ms,
+        sessions,
+    };
+}
+function atomicWriteJson(target, value, deps) {
+    const dir = path.dirname(target);
+    deps.mkdirSync(dir, { recursive: true });
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        deps.writeFileSync(tmp, `${JSON.stringify(value)}\n`, { encoding: "utf8" });
+        deps.renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            deps.unlinkSync(tmp);
+        }
+        catch (unlinkErr) {
+            const code = unlinkErr.code;
+            if (code !== "ENOENT") {
+                process.stderr.write(`lanes liveness: unlink tmp failed for ${tmp}: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}\n`);
+            }
+        }
+        throw err;
+    }
+}
+export function rebuildLivenessIndex(hqRoot, spoolPath, deps = defaultLivenessDeps()) {
+    let contents;
+    let st;
+    try {
+        st = deps.statSync(spoolPath);
+        contents = deps.readFileSync(spoolPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            const empty = {
+                schema_version: "hq-lane-liveness-index.v1",
+                built_at: new Date(deps.now()).toISOString(),
+                spool_path: spoolPath,
+                spool_bytes: 0,
+                spool_mtime_ms: 0,
+                sessions: {},
+            };
+            atomicWriteJson(livenessIndexPath(hqRoot), empty, deps);
+            return empty;
+        }
+        throw err;
+    }
+    const index = buildLivenessIndexFromSpool(contents, {
+        spool_path: spoolPath,
+        spool_bytes: st.size,
+        spool_mtime_ms: Math.floor(st.mtimeMs),
+        built_at: new Date(deps.now()).toISOString(),
+    });
+    atomicWriteJson(livenessIndexPath(hqRoot), index, deps);
+    return index;
+}
+export function readLivenessIndex(hqRoot, deps = defaultLivenessDeps()) {
+    const filePath = livenessIndexPath(hqRoot);
+    if (!deps.existsSync(filePath))
+        return null;
+    let raw;
+    try {
+        raw = deps.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        process.stderr.write(`lanes liveness: failed to read index ${filePath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        throw err;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isPlainObject(parsed) || parsed.schema_version !== "hq-lane-liveness-index.v1") {
+            throw new Error(`unexpected liveness index schema in ${filePath}`);
+        }
+        if (!isPlainObject(parsed.sessions)) {
+            throw new Error(`liveness index sessions map missing in ${filePath}`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        process.stderr.write(`lanes liveness: invalid index ${filePath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        throw err;
+    }
+}
+/**
+ * Return the compact index, rebuilding from the spool when missing or stale.
+ * Never walks workspace/sessions/.
+ */
+export function loadLivenessIndex(hqRoot, spoolPath, deps = defaultLivenessDeps(), persist = true) {
+    const spool = spoolPath ?? defaultSpoolPath(deps);
+    const existing = (() => {
+        try {
+            return readLivenessIndex(hqRoot, deps);
+        }
+        catch (err) {
+            process.stderr.write(`lanes liveness: rebuilding after invalid index: ${err instanceof Error ? err.message : String(err)}\n`);
+            return null;
+        }
+    })();
+    if (existing) {
+        try {
+            const st = deps.statSync(spool);
+            if (existing.spool_path === spool &&
+                existing.spool_bytes === st.size &&
+                existing.spool_mtime_ms === Math.floor(st.mtimeMs)) {
+                return existing;
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT")
+                throw err;
+            if (existing.spool_bytes === 0)
+                return existing;
+        }
+    }
+    if (!persist) {
+        let contents = "";
+        let stSize = 0;
+        let stMtime = 0;
+        try {
+            const st = deps.statSync(spool);
+            stSize = st.size;
+            stMtime = Math.floor(st.mtimeMs);
+            contents = deps.readFileSync(spool, "utf8");
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT")
+                throw err;
+        }
+        return buildLivenessIndexFromSpool(contents, {
+            spool_path: spool,
+            spool_bytes: stSize,
+            spool_mtime_ms: stMtime,
+            built_at: new Date(deps.now()).toISOString(),
+        });
+    }
+    return rebuildLivenessIndex(hqRoot, spool, deps);
+}
+/**
+ * Spec §9: a session is also `live` when the mesh daemon reports presence
+ * connected, not only from the spool. Missing state file → not connected.
+ * Unreadable or corrupt state is an error (unknown must not resolve to healthy).
+ */
+export function readDaemonPresenceConnected(deps = defaultLivenessDeps()) {
+    const statePath = daemonStatePath(daemonDir(undefined, deps.homedir(), deps.env));
+    if (!deps.existsSync(statePath))
+        return false;
+    let raw;
+    try {
+        raw = deps.readFileSync(statePath, "utf8");
+    }
+    catch (err) {
+        process.stderr.write(`lanes liveness: failed to read daemon state ${statePath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new LanesError("daemon_presence_unreadable", `Mesh daemon state ${statePath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`, { path: statePath });
+    }
+    if (!isPlainObject(parsed)) {
+        throw new LanesError("daemon_presence_unreadable", `Mesh daemon state ${statePath} is not an object`, { path: statePath });
+    }
+    if (parsed.v !== 1) {
+        throw new LanesError("daemon_presence_unreadable", `Mesh daemon state ${statePath} has unexpected v ${JSON.stringify(parsed.v)}`, { path: statePath, v: parsed.v });
+    }
+    return parsed.mqttState === "connected";
+}
+export function sessionLiveness(hqRoot, sessionId, opts = {}) {
+    const deps = opts.deps ?? defaultLivenessDeps();
+    const index = loadLivenessIndex(hqRoot, opts.spoolPath, deps);
+    const entry = index.sessions[sessionId];
+    if (!entry)
+        return null;
+    const windows = opts.windows ?? loadLanesConfig(hqRoot).liveness;
+    const presenceConnected = opts.presenceConnected ?? readDaemonPresenceConnected(deps);
+    return classifySessionLiveness(entry, opts.nowMs ?? deps.now(), presenceConnected, windows);
+}
+export function listSessionLiveness(hqRoot, opts = {}) {
+    const deps = opts.deps ?? defaultLivenessDeps();
+    const index = loadLivenessIndex(hqRoot, opts.spoolPath, deps);
+    const nowMs = opts.nowMs ?? deps.now();
+    const windows = opts.windows ?? loadLanesConfig(hqRoot).liveness;
+    const presenceConnected = opts.presenceConnected ?? readDaemonPresenceConnected(deps);
+    return Object.values(index.sessions).map((entry) => ({
+        sessionId: entry.sessionId,
+        state: classifySessionLiveness(entry, nowMs, presenceConnected, windows),
+        lastKind: entry.lastKind,
+        lastAt: entry.lastAt,
+    }));
+}
+//# sourceMappingURL=liveness.js.map

package/dist/lib/lanes/machine-identity.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared machine identity for Outpost self-target refusal (spec §5.2).
+ *
+ * One function, one fallback order, used by both the creating side
+ * (`origin_host` stamp) and the executing side (setup-time compare).
+ * EC2 instance id from IMDS, then hostname. Unresolvable is a status,
+ * never a guessed id.
+ *
+ * Only Outpost lane create and Outpost lane setup may call this. A local
+ * lane must not touch IMDS / the network.
+ */
+export declare const IMDS_HOST = "169.254.169.254";
+export declare const IMDS_TOKEN_URL = "http://169.254.169.254/latest/api/token";
+export declare const IMDS_INSTANCE_ID_URL = "http://169.254.169.254/latest/meta-data/instance-id";
+export declare const IMDS_TIMEOUT_MS = 250;
+export type MachineIdentity = {
+    status: "ok";
+    id: string;
+    source: "imds" | "hostname";
+    imds?: string | null;
+    hostname?: string | null;
+} | {
+    status: "unresolvable";
+    reason: string;
+};
+export interface MachineIdentityDeps {
+    /** Returns the IMDS instance id, or null when IMDS is unavailable. */
+    readImdsInstanceId?: () => string | null;
+    hostname?: () => string;
+}
+/** IMDSv2 token then instance-id. Any failure is null, not a thrown guess. */
+export declare function defaultReadImdsInstanceId(): string | null;
+export declare function resolveMachineIdentity(deps?: MachineIdentityDeps): MachineIdentity;
+//# sourceMappingURL=machine-identity.d.ts.map

package/dist/lib/lanes/machine-identity.js

@@ -0,0 +1,92 @@
+/**
+ * Shared machine identity for Outpost self-target refusal (spec §5.2).
+ *
+ * One function, one fallback order, used by both the creating side
+ * (`origin_host` stamp) and the executing side (setup-time compare).
+ * EC2 instance id from IMDS, then hostname. Unresolvable is a status,
+ * never a guessed id.
+ *
+ * Only Outpost lane create and Outpost lane setup may call this. A local
+ * lane must not touch IMDS / the network.
+ */
+import { spawnSync } from "node:child_process";
+import * as os from "node:os";
+export const IMDS_HOST = "169.254.169.254";
+export const IMDS_TOKEN_URL = `http://${IMDS_HOST}/latest/api/token`;
+export const IMDS_INSTANCE_ID_URL = `http://${IMDS_HOST}/latest/meta-data/instance-id`;
+export const IMDS_TIMEOUT_MS = 250;
+function curlImds(method, url, headers) {
+    const args = ["-sS", "-f", "-m", "1", "-X", method];
+    for (const [key, value] of Object.entries(headers)) {
+        args.push("-H", `${key}: ${value}`);
+    }
+    args.push(url);
+    try {
+        const result = spawnSync("curl", args, {
+            encoding: "utf8",
+            timeout: IMDS_TIMEOUT_MS,
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        const body = (result.stdout ?? "").trim();
+        return body.length > 0 ? body : null;
+    }
+    catch (err) {
+        process.stderr.write(`hq lanes: IMDS request failed for ${url}: ${err instanceof Error ? err.message : String(err)}\n`);
+        return null;
+    }
+}
+/** IMDSv2 token then instance-id. Any failure is null, not a thrown guess. */
+export function defaultReadImdsInstanceId() {
+    const token = curlImds("PUT", IMDS_TOKEN_URL, {
+        "X-aws-ec2-metadata-token-ttl-seconds": "60",
+    });
+    if (!token)
+        return null;
+    return curlImds("GET", IMDS_INSTANCE_ID_URL, {
+        "X-aws-ec2-metadata-token": token,
+    });
+}
+export function resolveMachineIdentity(deps = {}) {
+    const readImds = deps.readImdsInstanceId ?? defaultReadImdsInstanceId;
+    let imdsId = null;
+    try {
+        const raw = readImds();
+        imdsId = typeof raw === "string" && raw.trim() !== "" ? raw.trim() : null;
+    }
+    catch (err) {
+        process.stderr.write(`hq lanes: IMDS identity lookup failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    let hostname = null;
+    try {
+        const hostnameFn = deps.hostname ?? (() => os.hostname());
+        const host = hostnameFn();
+        hostname = typeof host === "string" && host.trim() !== "" ? host.trim() : null;
+    }
+    catch (err) {
+        process.stderr.write(`hq lanes: hostname identity lookup failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        if (!imdsId) {
+            return {
+                status: "unresolvable",
+                reason: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    if (imdsId) {
+        return { status: "ok", id: imdsId, source: "imds", imds: imdsId, hostname };
+    }
+    if (hostname) {
+        return {
+            status: "ok",
+            id: hostname,
+            source: "hostname",
+            imds: null,
+            hostname,
+        };
+    }
+    return {
+        status: "unresolvable",
+        reason: "IMDS unavailable and hostname empty",
+    };
+}
+//# sourceMappingURL=machine-identity.js.map

package/dist/lib/lanes/mesh-events.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Lane → work mesh events (spec §8).
+ *
+ * The lane side speaks the spec's vocabulary: lane_started, lane_progress,
+ * lane_question, lane_question_at_user, lane_ask, lane_blocked, lane_done.
+ * The work-mesh append endpoint accepts a closed roster of event kinds
+ * (hq-pro `src/vault-service/handlers/work-mesh.ts`, `validKinds`) and
+ * strips every payload field its per-kind validator does not name
+ * (hq-pro `src/vault-service/work-mesh/events.ts`). A `lane_*` kind on the
+ * wire is a 400. `toWireThreadEvent` is therefore the single place that
+ * turns a lane event into a roster kind whose payload carries the lane
+ * identity in the text fields the server keeps.
+ *
+ * Mapping, and why each kind:
+ *
+ * | lane event             | wire kind      | server effect                    |
+ * |------------------------|----------------|----------------------------------|
+ * | lane_started           | run_started    | status-neutral activity          |
+ * | lane_progress          | run_progress   | status-neutral activity          |
+ * | lane_done              | run_complete   | status-neutral; story → review   |
+ * | lane_blocked           | note (system)  | status-neutral; the project      |
+ * |                        |                | thread is shared by every lane,  |
+ * |                        |                | so one lane must not flip it to  |
+ * |                        |                | `blocked` (spec §8 keeps thread  |
+ * |                        |                | status out of lane events). The  |
+ * |                        |                | payload carries `blocked: true`  |
+ * |                        |                | and `blocked_reason` for filters |
+ * | lane_question          | question       | status-neutral, carries the id   |
+ * | lane_question_at_user  | question       | same                             |
+ * | lane_ask               | question       | same; ids of the ask envelope    |
+ *
+ * Token source for detached emitters (the per-lane watcher): the same
+ * `requireToken()` every `hq mesh session … --enqueue` hook call uses,
+ * which is `ensureCognitoToken()` over the person cache at
+ * `~/.hq/cognito-tokens.json`, or a machine mint when
+ * `HQ_MACHINE_CREDS_FILE` / the default agent creds file is readable
+ * (`src/utils/cognito-session.ts`). The watcher inherits the creator's
+ * `HOME` (spawn.ts `armLaneWatcher` copies the caller env and only adds
+ * `HQ_ROOT` / `HQ_LANE_ID`; the provider account home rides its own
+ * variable, never `HOME`), so it reads the same cache the hooks read. It
+ * passes `interactive: false`: a cache that cannot refresh throws instead
+ * of opening a browser nobody is watching, and the watcher records
+ * `mesh_event_failed` and moves on. No credential file is read here.
+ */
+import type { LaneCompanyRef, LaneEnvelope, LaneRecord } from "./types.js";
+export declare const LANE_MESH_EVENTS: readonly ["lane_started", "lane_progress", "lane_question", "lane_question_at_user", "lane_ask", "lane_blocked", "lane_done"];
+export type LaneMeshEvent = (typeof LANE_MESH_EVENTS)[number];
+/** Roster kinds this module emits. Subset of the server's `validKinds`. */
+export declare const WIRE_EVENT_KINDS: readonly ["run_started", "run_progress", "run_complete", "question", "note"];
+export type WireEventKind = (typeof WIRE_EVENT_KINDS)[number];
+/** Server caps: activity title/summary 2000, question text 500, note text 500. */
+export declare const WIRE_ACTIVITY_TEXT_MAX = 2000;
+export declare const WIRE_QUESTION_TEXT_MAX = 500;
+export declare const WIRE_NOTE_TEXT_MAX = 500;
+export interface WireThreadEvent {
+    eventKind: WireEventKind;
+    payload: Record<string, unknown>;
+}
+export declare function parseLaneMeshEvent(value: unknown): LaneMeshEvent;
+/**
+ * Lane event → roster kind + validator-shaped payload. Pure. Every text
+ * field is pre-clamped to the server cap so a long summary is truncated
+ * here rather than rejected there.
+ */
+export declare function toWireThreadEvent(event: LaneMeshEvent, payload: Record<string, unknown>): WireThreadEvent;
+/**
+ * The seam every lane emitter goes through. `appendThreadEvent` takes the
+ * spec's lane event name; the default implementation maps it to the wire
+ * kind. Tests substitute a recording implementation and see lane names.
+ */
+export interface LaneMesh {
+    ensureProjectThread: (company: LaneCompanyRef, projectId: string) => Promise<string>;
+    appendThreadEvent: (company: LaneCompanyRef, threadId: string, event: LaneMeshEvent, payload: Record<string, unknown>, signal?: AbortSignal) => Promise<void>;
+    patchStoryStatus: (company: LaneCompanyRef, projectId: string, storyId: string, status: string) => Promise<void>;
+}
+export interface CreateLaneMeshOptions {
+    /** False for detached callers (the watcher). See the token note above. */
+    interactive?: boolean;
+    /** Test seam. Defaults to the shared `requireToken`. */
+    token?: () => Promise<string>;
+}
+export declare function createLaneMesh(opts?: CreateLaneMeshOptions): LaneMesh;
+/** Company + thread present. A core/personal lane (company null) emits nothing. */
+export declare function laneCanEmit(lane: Pick<LaneRecord, "company" | "thread_id">): lane is Pick<LaneRecord, "company" | "thread_id"> & {
+    company: LaneCompanyRef;
+    thread_id: string;
+};
+/**
+ * Spec §8 terminal-envelope events. `done` → lane_done and story → review;
+ * `blocked` → lane_blocked; `ask` → lane_ask with the queue ids. The story is
+ * never set to `done` here: promotion belongs to the senior.
+ */
+export declare function emitLaneDecisionEvents(mesh: LaneMesh, lane: LaneRecord, envelope: Pick<LaneEnvelope, "decision" | "summary" | "blocked_reason">, opts?: {
+    questionIds?: string[];
+    signal?: AbortSignal;
+}): Promise<void>;
+export declare function emitLaneProgressEvent(mesh: LaneMesh, lane: LaneRecord, detail: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Throttle for lane_progress (spec §8 progress row). True when no progress
+ * event has been sent yet, or the last one is at least `minIntervalMs` old.
+ * The caller only asks on a tick that saw new activity; a silent tick never
+ * reaches this function.
+ */
+export declare function progressEventDue(input: {
+    lastEmitMs: number | null;
+    nowMs: number;
+    minIntervalMs: number;
+}): boolean;
+//# sourceMappingURL=mesh-events.d.ts.map