@indigoai-us/hq-cli 5.126.0 → 5.128.0

package/dist/lib/lanes/liveness.js

@@ -12,6 +12,8 @@ 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;
@@ -64,8 +66,9 @@ export function classifySessionLiveness(entry, nowMs, presenceConnected = false,
     const kind = entry.lastKind;
     if (kind === "session_end")
         return "ended";
-    if (presenceConnected)
-        return "live";
+    // 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)
@@ -219,7 +222,7 @@ export function readLivenessIndex(hqRoot, deps = defaultLivenessDeps()) {
  * Return the compact index, rebuilding from the spool when missing or stale.
  * Never walks workspace/sessions/.
  */
-export function loadLivenessIndex(hqRoot, spoolPath, deps = defaultLivenessDeps()) {
+export function loadLivenessIndex(hqRoot, spoolPath, deps = defaultLivenessDeps(), persist = true) {
     const spool = spoolPath ?? defaultSpoolPath(deps);
     const existing = (() => {
         try {
@@ -247,8 +250,62 @@ export function loadLivenessIndex(hqRoot, spoolPath, deps = defaultLivenessDeps(
                 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);
@@ -256,16 +313,18 @@ export function sessionLiveness(hqRoot, sessionId, opts = {}) {
     if (!entry)
         return null;
     const windows = opts.windows ?? loadLanesConfig(hqRoot).liveness;
-    return classifySessionLiveness(entry, opts.nowMs ?? deps.now(), opts.presenceConnected ?? false, windows);
+    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, opts.presenceConnected ?? false, windows),
+        state: classifySessionLiveness(entry, nowMs, presenceConnected, windows),
         lastKind: entry.lastKind,
         lastAt: entry.lastAt,
     }));

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

package/dist/lib/lanes/mesh-events.js

@@ -0,0 +1,275 @@
+/**
+ * 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 { appendThreadEvent, clamp, ensureProjectThread, patchStoryStatus, requireToken, resolveMeshCompany, } from "../mesh/api.js";
+import { LanesError } from "./errors.js";
+export const LANE_MESH_EVENTS = [
+    "lane_started",
+    "lane_progress",
+    "lane_question",
+    "lane_question_at_user",
+    "lane_ask",
+    "lane_blocked",
+    "lane_done",
+];
+/** Roster kinds this module emits. Subset of the server's `validKinds`. */
+export const WIRE_EVENT_KINDS = [
+    "run_started",
+    "run_progress",
+    "run_complete",
+    "question",
+    "note",
+];
+/** Server caps: activity title/summary 2000, question text 500, note text 500. */
+export const WIRE_ACTIVITY_TEXT_MAX = 2000;
+export const WIRE_QUESTION_TEXT_MAX = 500;
+export const WIRE_NOTE_TEXT_MAX = 500;
+export function parseLaneMeshEvent(value) {
+    if (typeof value === "string" &&
+        LANE_MESH_EVENTS.includes(value)) {
+        return value;
+    }
+    throw new LanesError("unknown_lane_mesh_event", `Unknown lane mesh event ${JSON.stringify(value)}. Accepted: ${LANE_MESH_EVENTS.join(", ")}`, { accepted: [...LANE_MESH_EVENTS], value });
+}
+function str(value) {
+    if (value === undefined || value === null)
+        return "";
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+function identity(payload) {
+    const lane = str(payload.lane_id) || "unknown-lane";
+    const project = str(payload.project_id);
+    const story = str(payload.story_id);
+    return project || story ? `${lane} ${project}/${story}` : lane;
+}
+function nonEmpty(text, fallback) {
+    return text.trim().length > 0 ? text : fallback;
+}
+/**
+ * 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 function toWireThreadEvent(event, payload) {
+    const kind = parseLaneMeshEvent(event);
+    const id = identity(payload);
+    switch (kind) {
+        case "lane_started":
+            return {
+                eventKind: "run_started",
+                payload: {
+                    title: clamp(`lane_started ${str(payload.lane_id) || "unknown-lane"}`, WIRE_ACTIVITY_TEXT_MAX),
+                    summary: clamp(`Lane ${id} started`, WIRE_ACTIVITY_TEXT_MAX),
+                },
+            };
+        case "lane_progress": {
+            const detail = str(payload.detail);
+            return {
+                eventKind: "run_progress",
+                payload: {
+                    summary: clamp(nonEmpty(`lane_progress ${id}${detail ? `: ${detail}` : ""}`, "lane_progress"), WIRE_ACTIVITY_TEXT_MAX),
+                },
+            };
+        }
+        case "lane_done": {
+            const summary = str(payload.summary);
+            return {
+                eventKind: "run_complete",
+                payload: {
+                    title: clamp(`lane_done ${str(payload.lane_id) || "unknown-lane"}`, WIRE_ACTIVITY_TEXT_MAX),
+                    summary: clamp(nonEmpty(`${id}: ${summary}`.replace(/:\s*$/, ""), `lane_done ${id}`), WIRE_ACTIVITY_TEXT_MAX),
+                },
+            };
+        }
+        case "lane_blocked": {
+            const reason = str(payload.blocked_reason);
+            // The roster's `blocked` event kind would flip the shared project
+            // thread, which spec §8 keeps lane events away from. Use the accepted
+            // audit note kind to preserve a filterable blocked marker.
+            return {
+                eventKind: "note",
+                payload: {
+                    text: clamp(`lane_blocked ${id}${reason ? `: ${reason}` : ""}`, WIRE_NOTE_TEXT_MAX),
+                    noteKind: "audit",
+                },
+            };
+        }
+        case "lane_question":
+        case "lane_question_at_user": {
+            const questionId = str(payload.question_id);
+            const hop = payload.hop === undefined ? "" : ` hop ${str(payload.hop)}`;
+            const out = {
+                text: clamp(`${kind} ${id}${hop}`, WIRE_QUESTION_TEXT_MAX),
+            };
+            if (questionId)
+                out.questionId = questionId;
+            return { eventKind: "question", payload: out };
+        }
+        case "lane_ask": {
+            const ids = Array.isArray(payload.question_ids)
+                ? payload.question_ids.map((item) => str(item)).filter(Boolean)
+                : [];
+            const out = {
+                text: clamp(`lane_ask ${id}: ${ids.length} question${ids.length === 1 ? "" : "s"}${ids.length ? ` ${ids.join(" ")}` : ""}`, WIRE_QUESTION_TEXT_MAX),
+            };
+            if (ids[0])
+                out.questionId = ids[0];
+            return { eventKind: "question", payload: out };
+        }
+        default: {
+            const _exhaustive = kind;
+            return _exhaustive;
+        }
+    }
+}
+export function createLaneMesh(opts = {}) {
+    const interactive = opts.interactive ?? true;
+    const token = opts.token ?? (() => requireToken({ interactive }));
+    return {
+        async ensureProjectThread(company, projectId) {
+            const tok = await token();
+            const resolved = await resolveMeshCompany(tok, company.slug);
+            const ensured = await ensureProjectThread(tok, resolved, projectId, {
+                summary: `HQ lane ${projectId}`,
+            });
+            return ensured.threadId;
+        },
+        async appendThreadEvent(company, threadId, event, payload, signal) {
+            const wire = toWireThreadEvent(event, payload);
+            const tok = await token();
+            await appendThreadEvent(tok, company.uid, threadId, wire.eventKind, wire.payload, signal);
+        },
+        async patchStoryStatus(company, projectId, storyId, status) {
+            const tok = await token();
+            await patchStoryStatus(tok, company.uid, projectId, storyId, status);
+        },
+    };
+}
+/** Company + thread present. A core/personal lane (company null) emits nothing. */
+export function laneCanEmit(lane) {
+    return lane.company !== null && lane.company !== undefined && !!lane.thread_id;
+}
+function baseIdentity(lane) {
+    return {
+        lane_id: lane.lane_id,
+        project_id: lane.project_id,
+        story_id: lane.story_id,
+    };
+}
+/**
+ * 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 async function emitLaneDecisionEvents(mesh, lane, envelope, opts = {}) {
+    if (!laneCanEmit(lane))
+        return;
+    const company = lane.company;
+    const threadId = lane.thread_id;
+    switch (envelope.decision) {
+        case "done": {
+            const outcomes = await Promise.allSettled([
+                mesh.appendThreadEvent(company, threadId, "lane_done", {
+                    ...baseIdentity(lane),
+                    summary: envelope.summary,
+                }, opts.signal),
+                mesh.patchStoryStatus(company, lane.project_id, lane.story_id, "review"),
+            ]);
+            const failure = outcomes.find((outcome) => outcome.status === "rejected");
+            if (failure?.status === "rejected")
+                throw failure.reason;
+            return;
+        }
+        case "blocked":
+            await mesh.appendThreadEvent(company, threadId, "lane_blocked", {
+                ...baseIdentity(lane),
+                blocked_reason: envelope.blocked_reason ?? "",
+            });
+            return;
+        case "ask":
+            // A mesh question event has one `questionId`; sending one event per id
+            // avoids silently losing ids when the display text reaches its wire cap.
+            {
+                const failures = [];
+                for (const questionId of opts.questionIds ?? []) {
+                    try {
+                        await mesh.appendThreadEvent(company, threadId, "lane_ask", {
+                            ...baseIdentity(lane),
+                            question_ids: [questionId],
+                        }, opts.signal);
+                    }
+                    catch (err) {
+                        failures.push(err);
+                    }
+                }
+                if (failures.length > 0)
+                    throw failures[0];
+            }
+            return;
+        default: {
+            const _exhaustive = envelope.decision;
+            return _exhaustive;
+        }
+    }
+}
+export async function emitLaneProgressEvent(mesh, lane, detail, signal) {
+    if (!laneCanEmit(lane))
+        return;
+    await mesh.appendThreadEvent(lane.company, lane.thread_id, "lane_progress", {
+        ...baseIdentity(lane),
+        detail,
+    }, signal);
+}
+/**
+ * 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 function progressEventDue(input) {
+    if (input.lastEmitMs === null)
+        return true;
+    return input.nowMs - input.lastEmitMs >= input.minIntervalMs;
+}
+//# sourceMappingURL=mesh-events.js.map