@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -0,0 +1,564 @@
+/**
+ * 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, ensureLaneMeshThread, ensureProjectThread, getProjectView, patchStoryStatus, putProjectView, requireToken, registerMeshProject, resolveMeshCompany, } from "../mesh/api.js";
+import { LanesError } from "./errors.js";
+import { terminalEnvelopeStoryStatus } from "./stories.js";
+export const LANE_MESH_EVENTS = [
+    "lane_started",
+    "lane_progress",
+    "lane_question",
+    "lane_question_at_user",
+    "lane_ask",
+    "lane_blocked",
+    "lane_done",
+    "lane_failed",
+    "lane_interrupted",
+    "lane_cancelled",
+    "lane_killed",
+];
+/** Roster kinds this module emits. Subset of the server's `validKinds`. */
+export const WIRE_EVENT_KINDS = [
+    "run_started",
+    "run_progress",
+    "run_complete",
+    "blocked",
+    "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);
+    const laneId = str(payload.lane_id ?? payload.laneId).trim();
+    const senior = payload.senior && typeof payload.senior === "object" && !Array.isArray(payload.senior)
+        ? payload.senior
+        : undefined;
+    const lane = laneId
+        ? {
+            laneId,
+            ...(str(payload.story_id ?? payload.storyId) ? { storyId: str(payload.story_id ?? payload.storyId) } : {}),
+            ...(str(payload.worker_profile ?? payload.workerProfile) ? { workerProfile: str(payload.worker_profile ?? payload.workerProfile) } : {}),
+            ...(str(payload.model) ? { model: str(payload.model) } : {}),
+            ...(str(payload.account) ? { account: str(payload.account) } : {}),
+            ...(str(payload.parent_lane_id ?? payload.parentLaneId) ? { parentLaneId: str(payload.parent_lane_id ?? payload.parentLaneId) } : {}),
+            ...(senior && ["user", "session", "lane"].includes(String(senior.kind))
+                ? { senior: { kind: senior.kind, ...(typeof senior.id === "string" ? { id: senior.id } : {}) } }
+                : {}),
+            laneVersion: Number.isSafeInteger(Number(payload.lane_version ?? payload.laneVersion)) && Number(payload.lane_version ?? payload.laneVersion) > 0
+                ? Number(payload.lane_version ?? payload.laneVersion)
+                : 1,
+        }
+        : undefined;
+    const laneFields = (laneStatus) => ({
+        ...(lane ? { lane } : {}),
+        ...(laneStatus ? { laneStatus } : {}),
+    });
+    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),
+                    ...laneFields("running"),
+                },
+            };
+        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),
+                    ...laneFields("running"),
+                },
+            };
+        }
+        case "lane_done": {
+            const summary = str(payload.summary);
+            const suppliedStatus = str(payload.lane_status ?? payload.laneStatus);
+            const laneStatus = isMeshLaneStatus(suppliedStatus) ? suppliedStatus : "done";
+            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),
+                    ...laneFields(laneStatus),
+                },
+            };
+        }
+        case "lane_blocked": {
+            const reason = str(payload.blocked_reason ?? payload.reason);
+            const suppliedStatus = str(payload.lane_status ?? payload.laneStatus);
+            const laneStatus = isMeshLaneStatus(suppliedStatus) ? suppliedStatus : "blocked";
+            return {
+                eventKind: "blocked",
+                payload: {
+                    reason: clamp(`lane_blocked ${id}${reason ? `: ${reason}` : ""}`, WIRE_NOTE_TEXT_MAX),
+                    ...laneFields(laneStatus),
+                },
+            };
+        }
+        case "lane_failed":
+        case "lane_interrupted":
+        case "lane_cancelled":
+        case "lane_killed": {
+            const laneStatus = kind.slice("lane_".length);
+            const summary = str(payload.summary ?? payload.reason ?? payload.blocked_reason);
+            return {
+                eventKind: "run_complete",
+                payload: {
+                    title: clamp(`${kind} ${str(payload.lane_id) || "unknown-lane"}`, WIRE_ACTIVITY_TEXT_MAX),
+                    summary: clamp(nonEmpty(`${id}: ${summary}`.replace(/:\s*$/, ""), `${kind} ${id}`), WIRE_ACTIVITY_TEXT_MAX),
+                    ...laneFields(laneStatus),
+                },
+            };
+        }
+        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;
+            Object.assign(out, laneFields());
+            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];
+            Object.assign(out, laneFields("awaiting_input"));
+            return { eventKind: "question", payload: out };
+        }
+        default: {
+            const _exhaustive = kind;
+            return _exhaustive;
+        }
+    }
+}
+function isProjectViewNotFound(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return (candidate.code === "PROJECT_VIEW_NOT_FOUND" ||
+        (typeof candidate.message === "string" && candidate.message.includes("PROJECT_VIEW_NOT_FOUND")));
+}
+function isUnknownProjectStory(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return (candidate.status === 400 &&
+        candidate.code === "PROJECT_VIEW_INVALID" &&
+        typeof candidate.message === "string" &&
+        candidate.message.includes("Unknown story"));
+}
+function isUncodedStoryPatchNotFound(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    // The story-absent route response is exactly `404 Not found` without a code.
+    // Keep coded 404s, especially PROJECT_VIEW_NOT_FOUND, on their own paths.
+    return (candidate.status === 404 &&
+        candidate.code === undefined &&
+        typeof candidate.message === "string" &&
+        /^404 not found$/i.test(candidate.message));
+}
+function shellQuote(value) {
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+export function storyNotOnBoardError(company, projectId, storyId) {
+    const command = "hq mesh project ensure " + shellQuote(projectId) +
+        " --company " + shellQuote(company.slug) +
+        " --stories-file '<prd.json>'";
+    const message = "Story " + JSON.stringify(storyId) + " is not on the Work Mesh Board for project " +
+        JSON.stringify(projectId) + ". Add it to the project PRD, then run: " + command;
+    return new LanesError("story_not_on_board", message, {
+        message,
+        project_id: projectId,
+        story_id: storyId,
+        command,
+    });
+}
+export function laneStoryStatusSuppressionKey(company, projectId, storyId) {
+    return JSON.stringify([company.uid, projectId, storyId]);
+}
+function isAlreadyRegistered(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return (candidate.code === "PROJECT_ALREADY_REGISTERED" ||
+        (typeof candidate.message === "string" && candidate.message.includes("PROJECT_ALREADY_REGISTERED")));
+}
+async function repairProjectView(input) {
+    const company = { companyUid: input.company.uid, companySlug: input.company.slug };
+    await ensureProjectThread(input.token, company, input.projectId, {
+        summary: `HQ lane ${input.projectId}`,
+    });
+    let current;
+    try {
+        current = await getProjectView(input.token, input.company.uid, input.projectId);
+    }
+    catch (error) {
+        if (!isProjectViewNotFound(error))
+            throw error;
+    }
+    const stories = [...(current?.stories ?? [])];
+    const index = stories.findIndex((story) => story.id === input.storyId);
+    const nextStory = {
+        ...(index >= 0 ? stories[index] : {}),
+        id: input.storyId,
+        title: index >= 0 ? stories[index]?.title || input.storyId : input.storyId,
+        status: input.status,
+    };
+    if (index >= 0)
+        stories[index] = nextStory;
+    else
+        stories.push(nextStory);
+    await putProjectView(input.token, input.company.uid, input.projectId, {
+        name: current?.name || input.projectId,
+        description: current?.description || "HQ lane project",
+        stories,
+        repos: current?.repos ?? [],
+        ...(current?.version !== undefined ? { expectedVersion: current.version } : {}),
+    });
+    try {
+        await registerMeshProject(input.token, input.company.uid, input.projectId);
+    }
+    catch (error) {
+        if (!isAlreadyRegistered(error))
+            throw error;
+    }
+}
+export function createLaneMesh(opts = {}) {
+    const interactive = opts.interactive ?? true;
+    const token = opts.token ?? (() => requireToken({ interactive }));
+    const repair = opts.repairProjectView ?? repairProjectView;
+    return {
+        async ensureProjectThread(company, projectId) {
+            const tok = await token();
+            const resolved = await resolveMeshCompany(tok, company.uid);
+            const ensured = await ensureProjectThread(tok, resolved, projectId, {
+                summary: `HQ lane ${projectId}`,
+            });
+            return ensured.threadId;
+        },
+        async ensureLaneThread(company, lane, laneStatus = lane.state, signal) {
+            const tok = await token();
+            const resolved = await resolveMeshCompany(tok, company.uid);
+            const descriptor = {
+                laneId: lane.lane_id,
+                ...(lane.story_id ? { storyId: lane.story_id } : {}),
+                ...(lane.worker_profile ? { workerProfile: lane.worker_profile } : {}),
+                ...(lane.model ? { model: lane.model } : {}),
+                ...(lane.account ? { account: lane.account } : {}),
+                ...(lane.senior.kind === "lane" ? { parentLaneId: lane.senior.id } : {}),
+                senior: { kind: lane.senior.kind, id: lane.senior.id },
+                laneVersion: lane.version,
+            };
+            try {
+                const ensured = await ensureLaneMeshThread(tok, resolved, lane.project_id, descriptor, isMeshLaneStatus(laneStatus) ? laneStatus : "running", signal);
+                return ensured.threadId;
+            }
+            catch (error) {
+                if (lane.story_id && isUnknownProjectStory(error)) {
+                    throw storyNotOnBoardError(company, lane.project_id, lane.story_id);
+                }
+                throw error;
+            }
+        },
+        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 assertProjectStoriesOnBoard(company, projectId, storyIds) {
+            if (storyIds.length === 0)
+                return;
+            const tok = await token();
+            let view;
+            try {
+                view = await getProjectView(tok, company.uid, projectId);
+            }
+            catch (error) {
+                // A missing Board has a separate, established repair path in
+                // patchStoryStatus. Keep it available; an existing Board is strict.
+                if (isProjectViewNotFound(error))
+                    return;
+                throw error;
+            }
+            if (view.companyUid !== company.uid || view.projectId !== projectId) {
+                throw new LanesError("project_board_scope_mismatch", "Work Mesh returned a Board for a different company or project", { project_id: projectId });
+            }
+            for (const storyId of storyIds) {
+                if (!view.stories.some((story) => story.id === storyId)) {
+                    throw storyNotOnBoardError(company, projectId, storyId);
+                }
+            }
+        },
+        async patchStoryStatus(company, projectId, storyId, status) {
+            const tok = await token();
+            const patch = async () => {
+                try {
+                    await patchStoryStatus(tok, company.uid, projectId, storyId, status);
+                }
+                catch (error) {
+                    if (isUnknownProjectStory(error) || isUncodedStoryPatchNotFound(error)) {
+                        throw storyNotOnBoardError(company, projectId, storyId);
+                    }
+                    throw error;
+                }
+            };
+            try {
+                await patch();
+            }
+            catch (error) {
+                if (!isProjectViewNotFound(error))
+                    throw error;
+                await repair({
+                    token: tok,
+                    company,
+                    projectId,
+                    storyId,
+                    status,
+                });
+                await patch();
+            }
+        },
+    };
+}
+/** Resolve the explicit mesh attribution before falling back to the lane tenant. */
+export function laneMeshCompany(lane) {
+    return lane.mesh_company ?? lane.company ?? undefined;
+}
+/** Company attribution + thread present. Unscoped personal lanes emit nothing. */
+export function laneCanEmit(lane) {
+    return laneMeshCompany(lane) !== undefined && !!lane.thread_id;
+}
+export function laneMeshEventIdentity(lane) {
+    const lastMove = lane.account_history?.[lane.account_history.length - 1];
+    return {
+        lane_id: lane.lane_id,
+        project_id: lane.project_id,
+        story_id: lane.story_id,
+        worker_profile: lane.worker_profile,
+        model: lane.model,
+        lane_version: lane.version,
+        senior: { kind: lane.senior.kind, id: lane.senior.id },
+        ...(lane.senior.kind === "lane" ? { parent_lane_id: lane.senior.id } : {}),
+        ...(lane.account !== undefined ? { account: lane.account } : {}),
+        // A moved lane names the move on every event its run emits (US-023 §8).
+        ...(lastMove !== undefined ? { account_move: { from: lastMove.from, to: lastMove.to, at: lastMove.at } } : {}),
+    };
+}
+function isMeshLaneStatus(value) {
+    return ["queued", "running", "awaiting_input", "blocked", "done", "failed", "interrupted", "cancelled", "killed"].includes(value);
+}
+// hq-pro derives lane thread ids from company + lane identity; opaque ids may
+// be legacy shared project threads and must be migrated before a lane closes.
+const STABLE_LANE_THREAD_ID = /^lane-[0-9a-f]{32}$/;
+async function ensureLaneEventThread(mesh, company, lane, laneStatus, signal) {
+    if (mesh.ensureLaneThread && !STABLE_LANE_THREAD_ID.test(lane.thread_id ?? "")) {
+        return mesh.ensureLaneThread(company, lane, laneStatus, signal);
+    }
+    return lane.thread_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 = {}) {
+    const company = laneMeshCompany(lane);
+    if (!company)
+        return;
+    const threadId = await ensureLaneEventThread(mesh, company, lane, lane.state, opts.signal);
+    if (!company || !threadId)
+        return;
+    const patchStoryStatus = async (status) => {
+        if (!lane.project_id?.trim() || !lane.story_id?.trim())
+            return;
+        if (terminalEnvelopeStoryStatus(lane, envelope.decision) === undefined)
+            return;
+        const suppressions = opts.storyStatusSuppressions;
+        const key = laneStoryStatusSuppressionKey(company, lane.project_id, lane.story_id);
+        if (suppressions?.has(key))
+            return;
+        try {
+            await mesh.patchStoryStatus(company, lane.project_id, lane.story_id, status);
+        }
+        catch (err) {
+            if (suppressions && err instanceof LanesError && err.error === "story_not_on_board") {
+                suppressions.add(key);
+            }
+            throw err;
+        }
+    };
+    switch (envelope.decision) {
+        case "done": {
+            const outcomes = await Promise.allSettled([
+                mesh.appendThreadEvent(company, threadId, "lane_done", {
+                    ...laneMeshEventIdentity(lane),
+                    summary: envelope.summary,
+                }, opts.signal),
+                patchStoryStatus("review"),
+            ]);
+            const failure = outcomes.find((outcome) => outcome.status === "rejected");
+            if (failure?.status === "rejected")
+                throw failure.reason;
+            return;
+        }
+        case "blocked":
+            {
+                const outcomes = await Promise.allSettled([
+                    mesh.appendThreadEvent(company, threadId, "lane_blocked", {
+                        ...laneMeshEventIdentity(lane),
+                        blocked_reason: envelope.blocked_reason ?? "",
+                    }),
+                    patchStoryStatus("in_progress"),
+                ]);
+                const failure = outcomes.find((outcome) => outcome.status === "rejected");
+                if (failure?.status === "rejected")
+                    throw failure.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", {
+                            ...laneMeshEventIdentity(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;
+        }
+    }
+}
+/** Emit an abnormal terminal state even when the worker produced no envelope. */
+export async function emitLaneTerminalStateEvent(mesh, lane, state, summary, signal) {
+    const company = laneMeshCompany(lane);
+    if (!company)
+        return;
+    const threadId = await ensureLaneEventThread(mesh, company, lane, state, signal);
+    if (!company || !threadId)
+        return;
+    await mesh.appendThreadEvent(company, threadId, `lane_${state}`, {
+        ...laneMeshEventIdentity(lane),
+        ...(summary ? { summary } : {}),
+    }, signal);
+}
+export async function emitLaneProgressEvent(mesh, lane, detail, signal) {
+    const company = laneMeshCompany(lane);
+    if (!company)
+        return;
+    const threadId = await ensureLaneEventThread(mesh, company, lane, lane.state, signal);
+    if (!company || !threadId)
+        return;
+    await mesh.appendThreadEvent(company, threadId, "lane_progress", {
+        ...laneMeshEventIdentity(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

package/dist/lib/lanes/message-replay.d.ts

@@ -0,0 +1,21 @@
+import { probeProviderCompactionsSince } from "./compaction.js";
+import type { LaneProvider } from "./types.js";
+export declare const MESSAGE_REPLAY_STATE_NAME = "message-compaction-replay.json";
+export declare const MESSAGE_COMPACTION_REPLAY_NOTE = "These messages were delivered before a context compaction and still apply.";
+export interface MessageReplayState {
+    schema_version: 1;
+    turn_id: string;
+    /** Null until the provider transcript is first observed in this turn. */
+    last_compaction_marker: number | null;
+    /** Last complete JSONL byte offset scanned in the provider transcript. */
+    transcript_offset?: number;
+    /** Canonical transcript path for this provider turn. */
+    transcript_path?: string;
+    /** Provider needed to inspect appended transcript records without loading the lane store. */
+    provider?: LaneProvider;
+}
+export type ReplayTranscriptUpdate = "baseline" | "unchanged" | "replaced" | "compacted";
+export declare function readMessageReplayState(filePath: string, turnId: string, onLegacyFlag?: () => void): MessageReplayState;
+export declare function writeMessageReplayState(filePath: string, state: MessageReplayState): void;
+export declare function updateMessageReplayTranscript(state: MessageReplayState, transcriptPath: string, provider: LaneProvider, env: NodeJS.ProcessEnv, probe?: typeof probeProviderCompactionsSince): ReplayTranscriptUpdate;
+//# sourceMappingURL=message-replay.d.ts.map