@celestea/studio 2.7.1

package/dist/replay/report.js

@@ -0,0 +1,103 @@
+/**
+ * Markdown / console rendering of the P5 double-run report.
+ *
+ * The markdown is the deliverable of the replay: it states, per finding, WHICH
+ * evidence class backs the claim (byte-exact / frozen golden / spec-derived /
+ * self-check) so a reader can tell a proven byte-level match from a
+ * self-consistency check, and it lists the P6 gaps next to the verdict.
+ */
+const KIND_LABEL = {
+    "byte-exact": "逐字节",
+    golden: "冻结黄金",
+    "spec-derived": "独立重推导",
+    "self-check": "自洽校验",
+    info: "信息",
+};
+const VERDICT_LABEL = { match: "一致", diff: "差异", skip: "跳过" };
+function escape(text) {
+    return text.replace(/\|/g, "\\|");
+}
+function verdictTable(report) {
+    const s = report.summary;
+    return [
+        "| 指标 | 值 |",
+        "|---|---|",
+        `| 回放会话数 | ${s.sessions} |`,
+        `| 比对项（findings） | ${s.findings} |`,
+        `| 一致 | ${s.matched}（其中逐字节 ${s.byteExact} / 冻结黄金 ${s.golden}） |`,
+        `| **差异** | **${s.diffed}** |`,
+        `| 跳过（结构性说明） | ${s.skipped} |`,
+        `| harness 错误 | ${s.errors} |`,
+        `| 结论 | ${s.verdict} |`,
+        "",
+    ];
+}
+function findingsTable(title, findings, predicate) {
+    const rows = findings.filter(predicate);
+    const out = [`### ${title}（${rows.length}）`, ""];
+    if (rows.length === 0)
+        return [...out, "_无_", ""];
+    out.push("| scope | 证据类别 | 说明 |", "|---|---|---|");
+    for (const f of rows)
+        out.push(`| ${escape(f.scope)} | ${KIND_LABEL[f.kind]} | ${escape(f.detail)} |`);
+    out.push("");
+    return out;
+}
+function sessionTable(report) {
+    const out = ["| 会话 | roles | events | turns | 比对项 | 差异 | 结论 |", "|---|---|---|---|---|---|---|"];
+    for (const s of report.sessions) {
+        const diffed = s.findings.filter((f) => f.verdict === "diff").length;
+        out.push(`| ${s.id} | ${s.roles.join(", ")} | ${s.events} | ${s.turns} | ${s.findings.length} | ${diffed} | ${s.verdict} |`);
+    }
+    out.push("");
+    return out;
+}
+function diffSection(report) {
+    const diffs = report.findings.filter((f) => f.verdict === "diff");
+    const out = ["## 差异清单与原因", ""];
+    if (diffs.length === 0)
+        return [...out, "**无差异**：所有比对项一致。", ""];
+    out.push("| scope | 证据类别 | 差异 | 首个分歧 |", "|---|---|---|---|");
+    for (const f of diffs)
+        out.push(`| ${escape(f.scope)} | ${KIND_LABEL[f.kind]} | ${escape(f.detail)} | ${escape(f.diffs?.[0] ?? "-")} |`);
+    out.push("");
+    return out;
+}
+/** The full markdown report. */
+export function renderReplayMarkdown(report) {
+    const lines = [];
+    lines.push("# P5 双跑对拍报告（replay:e2e）", "");
+    lines.push(`- 生成时间：${report.generatedAt}`);
+    lines.push(`- fixtures：\`${report.fixtures}\`（导出时间 ${report.fixturesGeneratedAt}）`);
+    lines.push(`- 探针输入：\`${report.probeInput}\`（真实 agent-loop + 离线 mock LLM，禁真网）`);
+    lines.push("");
+    lines.push("## 结论", "");
+    lines.push(...verdictTable(report));
+    if (report.errors.length > 0) {
+        lines.push("### harness 错误", "");
+        for (const e of report.errors)
+            lines.push(`- ${e}`);
+        lines.push("");
+    }
+    lines.push("## 会话总览", "");
+    lines.push(...sessionTable(report));
+    lines.push(...findingsTable("已逐字节一致项", report.findings, (f) => f.verdict === "match" && f.kind === "byte-exact"));
+    lines.push(...findingsTable("冻结黄金一致项", report.findings, (f) => f.verdict === "match" && f.kind === "golden"));
+    lines.push(...findingsTable("独立重推导 / 自洽校验一致项", report.findings, (f) => f.verdict === "match" && (f.kind === "spec-derived" || f.kind === "self-check")));
+    lines.push(...diffSection(report));
+    lines.push("## P6 前还差什么", "");
+    for (const gap of report.gaps)
+        lines.push(`- ${gap}`);
+    lines.push("");
+    lines.push("## 全部比对项", "");
+    lines.push("| scope | 证据类别 | 结论 | 说明 |", "|---|---|---|---|");
+    for (const f of report.findings)
+        lines.push(`| ${escape(f.scope)} | ${KIND_LABEL[f.kind]} | ${VERDICT_LABEL[f.verdict]} | ${escape(f.detail)} |`);
+    lines.push("");
+    return lines.join("\n");
+}
+/** One-line console summary (the CLI prints this plus the session rows). */
+export function renderReplayConsole(report) {
+    const s = report.summary;
+    return `[replay:e2e] sessions=${s.sessions} findings=${s.findings} matched=${s.matched} (byte-exact=${s.byteExact}, golden=${s.golden}) diffed=${s.diffed} skipped=${s.skipped} errors=${s.errors} verdict=${s.verdict}`;
+}

package/dist/replay/session-e2e.d.ts

@@ -0,0 +1,44 @@
+/**
+ * One replayed session: the four comparison families of the P5 double run.
+ *
+ *   1. **session log JSONL** — replay the golden log through the TS engine's own
+ *      persistent log and re-serialize it: the bytes must come back identical
+ *      (codec + replay fidelity), and the file itself must stay untouched;
+ *   2. **messages projection** — `GET /api/sessions/{id}/messages` over the REAL
+ *      host vs the frozen capture (`messages-expected.json`) + the engine's own
+ *      `derive_messages` vs its stored derivation;
+ *   3. **SSE sequence** — the derived transcript vs the stored golden, and the
+ *      same frames pushed through the real `GET /api/events` endpoint;
+ *   4. **real turn + compaction** — a probe turn appended by the engine (byte
+ *      level), then compaction over HTTP with an independently re-derived plan.
+ */
+import type { SessionEvent } from "@celestea/core";
+import { type Finding } from "./compare.js";
+import { type FixtureSession } from "./fixtures.js";
+import type { ReplayHost } from "./host.js";
+export interface SessionE2E {
+    id: string;
+    slug: string;
+    roles: string[];
+    events: number;
+    turns: number;
+    findings: Finding[];
+    verdict: "match" | "diff";
+}
+export interface ReplaySessionOptions {
+    host: ReplayHost;
+    fixturesDir: string;
+    entry: FixtureSession;
+    /** Input of the probe turn appended to the session copy. */
+    probeInput?: string;
+}
+/** Replay one fixture session end to end and collect its findings. */
+export declare function replaySession(opts: ReplaySessionOptions): Promise<SessionE2E>;
+/** Family 1: the golden log replayed and re-serialized, byte for byte. */
+export declare function logFindings(id: string, goldenText: string): Finding[];
+/** Family 2: the Studio projection (golden) + the engine projection (self-check). */
+export declare function messagesFindings(host: ReplayHost, id: string, messagesFile: string, derivedFile: string, events: readonly SessionEvent[]): Promise<Finding[]>;
+/** Family 3: derived transcript vs the stored golden, then the SSE transport. */
+export declare function sseChecks(host: ReplayHost, id: string, sseFile: string | null, events: readonly SessionEvent[]): Promise<Finding[]>;
+/** Where a planted session copy lives (report / debugging aid). */
+export declare function plantedDir(host: ReplayHost, id: string): string;

package/dist/replay/session-e2e.js

@@ -0,0 +1,91 @@
+/**
+ * One replayed session: the four comparison families of the P5 double run.
+ *
+ *   1. **session log JSONL** — replay the golden log through the TS engine's own
+ *      persistent log and re-serialize it: the bytes must come back identical
+ *      (codec + replay fidelity), and the file itself must stay untouched;
+ *   2. **messages projection** — `GET /api/sessions/{id}/messages` over the REAL
+ *      host vs the frozen capture (`messages-expected.json`) + the engine's own
+ *      `derive_messages` vs its stored derivation;
+ *   3. **SSE sequence** — the derived transcript vs the stored golden, and the
+ *      same frames pushed through the real `GET /api/events` endpoint;
+ *   4. **real turn + compaction** — a probe turn appended by the engine (byte
+ *      level), then compaction over HTTP with an independently re-derived plan.
+ */
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deriveMessages, deriveSseTranscript, parseSessionJsonl, PersistentSessionLog } from "@celestea/session";
+import { serializeEventLog } from "@celestea/runtime";
+import { compareBytes, compareJson, note, tally } from "./compare.js";
+import { fixtureFiles, readJson, readJsonl, plantFixture, splitSessionId } from "./fixtures.js";
+import { SESSION_LOG_ID, SESSION_LOG_NAME } from "../runtime/engine-session.js";
+import { activate, captureSseWire, compactFindings, runTurn, sseFindings, turnFindings } from "./probes.js";
+/** Replay one fixture session end to end and collect its findings. */
+export async function replaySession(opts) {
+    const { host, entry } = opts;
+    const files = fixtureFiles(opts.fixturesDir, entry.slug);
+    const planted = plantFixture(host.root, files, entry.id);
+    const events = parseSessionJsonl(planted.logBytes).events;
+    const findings = [...logFindings(entry.id, planted.logBytes)];
+    findings.push(...(await messagesFindings(host, entry.id, files.messages, files.derivedMessages, events)));
+    findings.push(...(await sseChecks(host, entry.id, files.sse, events)));
+    const input = opts.probeInput ?? "P5 重放探针";
+    const status = await activate(host, entry.id);
+    const turn = await runTurn(host, input);
+    const after = readFileSync(join(planted.dir, SESSION_LOG_NAME), "utf8");
+    findings.push(...turnFindings(entry.id, planted.logBytes, after, input, turn.frames));
+    if (status !== 200)
+        findings.push(note(`${entry.id} :: activate`, "golden", `activate returned ${status}`, "diff"));
+    findings.push(...(await compactFindings(host, entry.id, planted.dir)));
+    const counts = tally(findings);
+    return { id: entry.id, slug: entry.slug, roles: entry.roles, events: events.length, turns: entry.turns, findings, verdict: counts.diffed === 0 ? "match" : "diff" };
+}
+/** Family 1: the golden log replayed and re-serialized, byte for byte. */
+export function logFindings(id, goldenText) {
+    const dir = mkdtempSync(join(tmpdir(), "replay-log-"));
+    try {
+        const path = join(dir, SESSION_LOG_NAME);
+        writeFileSync(path, goldenText, "utf8");
+        const log = PersistentSessionLog.open(dir, SESSION_LOG_ID);
+        const findings = [
+            compareBytes(`${id} :: session-log-jsonl`, goldenText, serializeEventLog(log.events()), "replay -> re-serialize"),
+            compareBytes(`${id} :: session-log-file`, goldenText, readFileSync(path, "utf8"), "replay kept the file untouched"),
+        ];
+        findings.push(log.tornTail === null
+            ? note(`${id} :: session-log-replay`, "byte-exact", `${log.events().length} event(s), no torn tail, next turn id turn-${log.peekTurnNumber()}`, "match")
+            : note(`${id} :: session-log-replay`, "golden", `torn tail at line ${log.tornTail.line}`, "diff"));
+        log.close();
+        return findings;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Family 2: the Studio projection (golden) + the engine projection (self-check). */
+export async function messagesFindings(host, id, messagesFile, derivedFile, events) {
+    const res = await host.app.request(`/api/sessions/${encodeURIComponent(id)}/messages`);
+    const body = (await res.json());
+    const golden = readJson(messagesFile).messages;
+    return [
+        compareJson(`${id} :: messages-projection`, "golden", golden, body.messages ?? [], `GET /api/sessions/{id}/messages (${res.status})`),
+        compareJson(`${id} :: engine-derive-messages`, "self-check", readJson(derivedFile).messages, deriveMessages(events), "engine model-visible history"),
+    ];
+}
+/** Family 3: derived transcript vs the stored golden, then the SSE transport. */
+export async function sseChecks(host, id, sseFile, events) {
+    const derived = deriveSseTranscript(events);
+    const golden = sseFile === null ? null : readJsonl(sseFile);
+    const expected = derived.map((f) => ({
+        event: f.event,
+        turn: f.data.turn,
+        payload: f.data.payload,
+    }));
+    const capture = await captureSseWire(host, expected, id);
+    return sseFindings(id, derived, golden, capture);
+}
+/** Where a planted session copy lives (report / debugging aid). */
+export function plantedDir(host, id) {
+    const { workspace, session } = splitSessionId(id);
+    return join(host.root, workspace, session);
+}

package/dist/routes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Route table derived from the frozen contract.
+ *
+ * 64 endpoints (68 method+path combos minus the 4 static routes).
+ * The contract path params use `{id}`; Hono uses `:id`, so paths are translated here
+ * once and the translation is asserted in tests.
+ *
+ * W516 added `GET|POST|DELETE /api/sessions/{id}/grants` and
+ * `GET /api/sessions/{id}/grants/confirm-token` (39 -> 43); W725 added
+ * `GET /api/sessions/{id}/context` (43 -> 44). W767 added Studio's own login
+ * cookie gate: `GET /login`, `POST /auth/login`, `GET /auth/check` (44 -> 47;
+ * the first two are deliberately NOT under `/api/`). W785 added
+ * `GET /api/usage/ledger` (49 -> 50). W791 added
+ * `POST /api/sessions/{id}/mode` (50 -> 51; the P1 session working mode). W9
+ * added the six permission endpoints (51 -> 57). W860 added
+ * `GET|PUT /api/sessions/{id}/tools` and `GET /api/plugins` (57 -> 60). W870
+ * added `PUT /api/sessions/{id}/model` (60 -> 61; the statusline picker's
+ * session-scoped model switch). G5 added `GET /api/fs/list` (61 -> 62; the
+ * Win-style file manager's directory+file listing). G2 added `POST /api/exec`
+ * (62 -> 63; immediate shell execution for the UI's /run and !, no model). All of
+ * them have NO counterpart in the legacy backend:
+ * `contracts/route-table.snapshot.json` keeps the frozen extraction intact and
+ * lists the TypeScript-only additions separately.
+ */
+import { type EndpointContract } from "@celestea/core";
+export interface RegisteredRoute {
+    id: string;
+    method: "GET" | "POST" | "DELETE" | "PUT";
+    /** Contract path, e.g. /api/sessions/{id}/messages */
+    contractPath: string;
+    /** Hono path, e.g. /api/sessions/:id/messages */
+    honoPath: string;
+    endpoint: EndpointContract;
+}
+export declare function toHonoPath(contractPath: string): string;
+/** Substitute placeholder values so a route can be exercised in tests. */
+export declare function concretePath(contractPath: string, sample?: string): string;
+export declare function studioRoutes(): RegisteredRoute[];
+export declare const API_ENDPOINT_COUNT = 64;
+export declare const STATIC_ROUTE_COUNT = 4;
+/** Id-keyed view of the contract routes: a handler asks for its id, never a path. */
+export interface RouteTable {
+    routes: RegisteredRoute[];
+    /** Throws when the id is not in the frozen contract (typo guard). */
+    get(id: string): RegisteredRoute;
+}
+export declare function routeTable(): RouteTable;

package/dist/routes.js

@@ -0,0 +1,59 @@
+/**
+ * Route table derived from the frozen contract.
+ *
+ * 64 endpoints (68 method+path combos minus the 4 static routes).
+ * The contract path params use `{id}`; Hono uses `:id`, so paths are translated here
+ * once and the translation is asserted in tests.
+ *
+ * W516 added `GET|POST|DELETE /api/sessions/{id}/grants` and
+ * `GET /api/sessions/{id}/grants/confirm-token` (39 -> 43); W725 added
+ * `GET /api/sessions/{id}/context` (43 -> 44). W767 added Studio's own login
+ * cookie gate: `GET /login`, `POST /auth/login`, `GET /auth/check` (44 -> 47;
+ * the first two are deliberately NOT under `/api/`). W785 added
+ * `GET /api/usage/ledger` (49 -> 50). W791 added
+ * `POST /api/sessions/{id}/mode` (50 -> 51; the P1 session working mode). W9
+ * added the six permission endpoints (51 -> 57). W860 added
+ * `GET|PUT /api/sessions/{id}/tools` and `GET /api/plugins` (57 -> 60). W870
+ * added `PUT /api/sessions/{id}/model` (60 -> 61; the statusline picker's
+ * session-scoped model switch). G5 added `GET /api/fs/list` (61 -> 62; the
+ * Win-style file manager's directory+file listing). G2 added `POST /api/exec`
+ * (62 -> 63; immediate shell execution for the UI's /run and !, no model). All of
+ * them have NO counterpart in the legacy backend:
+ * `contracts/route-table.snapshot.json` keeps the frozen extraction intact and
+ * lists the TypeScript-only additions separately.
+ */
+import { loadEndpoints } from "@celestea/core";
+export function toHonoPath(contractPath) {
+    return contractPath.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, ":$1").replace(/\{\*([A-Za-z_][A-Za-z0-9_]*)\}/g, "*");
+}
+/** Substitute placeholder values so a route can be exercised in tests. */
+export function concretePath(contractPath, sample = "sample-ws%2Fsample-session") {
+    return contractPath
+        .replace(/\{\*([A-Za-z_][A-Za-z0-9_]*)\}/g, "sample/asset.js")
+        .replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => (name === "id" ? sample : `sample-${name}`));
+}
+export function studioRoutes() {
+    const c = loadEndpoints();
+    return c.endpoints.map((e) => ({
+        id: e.id,
+        method: e.method,
+        contractPath: e.path,
+        honoPath: toHonoPath(e.path),
+        endpoint: e,
+    }));
+}
+export const API_ENDPOINT_COUNT = 64;
+export const STATIC_ROUTE_COUNT = 4;
+export function routeTable() {
+    const routes = studioRoutes();
+    const byId = new Map(routes.map((r) => [r.id, r]));
+    return {
+        routes,
+        get(id) {
+            const route = byId.get(id);
+            if (route === undefined)
+                throw new Error(`unknown contract endpoint id '${id}'`);
+            return route;
+        },
+    };
+}

package/dist/runtime/attachments-llm.d.ts

@@ -0,0 +1,13 @@
+/**
+ * W804 (multimodal P0 section 3.1): resolve content-addressed image references
+ * into a REQUEST-scoped `images` table (attachment_id -> data URL) before the
+ * wire layer runs.
+ *
+ * The bytes are read here, on the request path, and are NEVER persisted: the
+ * session log keeps only the reference. A reference whose object is missing is a
+ * HARD error — a silently dropped image is worse than a failed request.
+ */
+import type { Llm } from "@celestea/core";
+import type { AttachmentStore } from "@celestea/tools";
+/** Wrap one `Llm` so image references become a data-URL table on the request. */
+export declare function withAttachments(inner: Llm, store: AttachmentStore | null): Llm;

package/dist/runtime/attachments-llm.js

@@ -0,0 +1,37 @@
+/**
+ * W804 (multimodal P0 section 3.1): resolve content-addressed image references
+ * into a REQUEST-scoped `images` table (attachment_id -> data URL) before the
+ * wire layer runs.
+ *
+ * The bytes are read here, on the request path, and are NEVER persisted: the
+ * session log keeps only the reference. A reference whose object is missing is a
+ * HARD error — a silently dropped image is worse than a failed request.
+ */
+/** Wrap one `Llm` so image references become a data-URL table on the request. */
+export function withAttachments(inner, store) {
+    if (store === null)
+        return inner;
+    return {
+        async generate(req) {
+            const table = {};
+            for (const message of req.messages) {
+                for (const part of message.content) {
+                    if (part.type !== "image")
+                        continue;
+                    const id = part.content.attachment_id;
+                    if (table[id] !== undefined)
+                        continue;
+                    const url = await store.readDataUrl(id);
+                    if (url === null) {
+                        throw new Error(`W804: attachment ${id} is not present in ${store.dir}; the image cannot be delivered`);
+                    }
+                    table[id] = url;
+                }
+            }
+            if (Object.keys(table).length === 0)
+                return inner.generate(req);
+            const withImages = { ...req, images: table };
+            return inner.generate(withImages);
+        },
+    };
+}

package/dist/runtime/boot-recovery.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Boot recovery of the ACTIVE session (E §1.3 P0 ③, §1.6 apps/studio row).
+ *
+ * `workspaces.json.active_session` is the one session the host knows was in use
+ * when the process stopped, so that is the session it repairs at startup — before
+ * any instance exists for it, which matters because a composed instance replays
+ * the log and derives its turn counter from it (E §1.3 P0 ④).
+ *
+ * The heavy lifting (decision table, append-only repair) lives in the engine
+ * packages; this module only answers "WHICH directory" and reports the outcome on
+ * the P0 observation channel (stderr; the durable record is the sidecar's
+ * `repaired[]`). Recovery never throws and never fails the boot: a damaged
+ * sidecar or an unknown session id must not stop the studio from starting.
+ *
+ * W787 (§5.2③): the repair is an AUTOMATIC behaviour, so it now also reaches the
+ * audit channel (`recovery-audit.jsonl`) when one is wired — the P0 note that
+ * only two channels existed was a deliberate deferral, and P1 is when it closes.
+ */
+import { type BootRecoveryReport } from "@celestea/runtime";
+import type { SessionsStore } from "../store/sessions.js";
+import type { WorkspacesStore } from "../store/workspaces.js";
+import type { RecoveryAuditWriter } from "./recovery-audit.js";
+export interface BootRecoveryInput {
+    workspaces: Pick<WorkspacesStore, "activeSession">;
+    sessions: Pick<SessionsStore, "resolve">;
+    now?: () => number;
+    warn?: (message: string) => void;
+    /** W787: the durable audit channel (§5.2③); absent = stderr only. */
+    audit?: RecoveryAuditWriter | null;
+}
+/** Recover the previously active session; null when there is nothing to look at. */
+export declare function recoverActiveSessionOnBoot(input: BootRecoveryInput): BootRecoveryReport | null;

package/dist/runtime/boot-recovery.js

@@ -0,0 +1,71 @@
+/**
+ * Boot recovery of the ACTIVE session (E §1.3 P0 ③, §1.6 apps/studio row).
+ *
+ * `workspaces.json.active_session` is the one session the host knows was in use
+ * when the process stopped, so that is the session it repairs at startup — before
+ * any instance exists for it, which matters because a composed instance replays
+ * the log and derives its turn counter from it (E §1.3 P0 ④).
+ *
+ * The heavy lifting (decision table, append-only repair) lives in the engine
+ * packages; this module only answers "WHICH directory" and reports the outcome on
+ * the P0 observation channel (stderr; the durable record is the sidecar's
+ * `repaired[]`). Recovery never throws and never fails the boot: a damaged
+ * sidecar or an unknown session id must not stop the studio from starting.
+ *
+ * W787 (§5.2③): the repair is an AUTOMATIC behaviour, so it now also reaches the
+ * audit channel (`recovery-audit.jsonl`) when one is wired — the P0 note that
+ * only two channels existed was a deliberate deferral, and P1 is when it closes.
+ */
+import { recoverSessionOnBoot } from "@celestea/runtime";
+/** Recover the previously active session; null when there is nothing to look at. */
+export function recoverActiveSessionOnBoot(input) {
+    const warn = input.warn ?? defaultWarn;
+    const active = input.workspaces.activeSession();
+    if (active === null || active.trim() === "")
+        return null;
+    const resolved = input.sessions.resolve(active);
+    if (!resolved.ok) {
+        warn(`[celestea-recovery] active session '${active}' does not resolve — nothing to recover`);
+        return null;
+    }
+    // The sidecar's self-description must be the SAME string a live instance
+    // writes. W878: that is the host's TRUSTED `resolve()` id (the same one
+    // grants.json/permission.json/tools.json use), NOT a path inference — the
+    // inference breaks the moment a session directory sinks below the workspace
+    // root (`<ws>/.celestea/sessions/<dir>`), which would silently skip recovery.
+    const report = recoverSessionOnBoot({
+        dir: resolved.value.dir,
+        session: resolved.value.id,
+        ...(input.now === undefined ? {} : { now: input.now }),
+        warn,
+    });
+    announce(report, warn);
+    auditRepair(input.audit, report);
+    return report;
+}
+/** One audit line for the ONE automatic action of this capability (§5.2③). */
+function auditRepair(audit, report) {
+    if (audit == null || !report.appended)
+        return;
+    audit.write({
+        event: "session_repaired",
+        session: report.session,
+        turn_id: report.turn_id,
+        count: report.dangling_before.length,
+        detail: `appended turn_end{outcome:interrupted} after a crash (dangling before=${report.dangling_before.length})`,
+    });
+}
+/** The P0 visibility rule: a repair, a skip that hides a dangling turn, a warning. */
+function announce(report, warn) {
+    if (report.appended) {
+        warn(`[celestea-recovery] ${report.session}: closed interrupted ${String(report.turn_id)} (crash recovery, ${report.dangling_before.length} dangling turn(s) before)`);
+    }
+    else if (report.action === "skipped_no_checkpoint" && report.dangling_before.length > 0) {
+        warn(`[celestea-recovery] ${report.session}: ${report.dangling_before.length} dangling turn(s) left untouched — no checkpoint (fail-safe)`);
+    }
+    for (const message of report.warnings)
+        warn(`[celestea-recovery] ${message}`);
+}
+function defaultWarn(message) {
+    process.stderr.write(`${message}\n`);
+}

package/dist/runtime/context-snapshot.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Engine request -> host view (W725): the projection behind
+ * `GET /api/sessions/{id}/context`.
+ *
+ * The projection is deliberately thin and lossless in the direction that
+ * matters: everything the model sees comes from the agent loop's own
+ * `contextSnapshot()` (system prompt, post-trim derived history, tool schemas).
+ * This module never trims, filters or re-derives a single message — it only
+ * flattens the engine's `Message[]` into one display row per message, because
+ * the wire contract carries `content` as a string.
+ *
+ * Flattening rules (frozen; the frontend renders them verbatim):
+ *   - a message's content blocks are joined with "\n";
+ *   - a `tool_call` block contributes `[tool_call] <name> <compact JSON args>`;
+ *   - an assistant tool-call row carries the FIRST call's `tool_name` +
+ *     `tool_call_id` (`tool_name` = what it called, id = the call it made);
+ *   - a `tool` result row carries its own `tool_call_id`, resolved back to the
+ *     call's `tool_name` while the messages are walked in order.
+ */
+import type { Content, Message, ToolSpec } from "@celestea/core";
+import type { Runtime } from "@celestea/runtime";
+import type { ContextMessageView, ContextToolView, SessionContextView } from "../runtime-adapter.js";
+/** What to report when the mounted loop has no snapshot capability. */
+export interface ContextFallback {
+    model: string;
+    system: string;
+    tools: readonly ToolSpec[];
+}
+/** One message's content blocks as a single display string. */
+export declare function renderContent(content: readonly Content[]): string;
+/** W804: e.g. `[image] logo.png image/png 512x512 (attachment <sha>)`. */
+export declare function imageText(ref: {
+    attachment_id: string;
+    media_type: string;
+    width: number;
+    height: number;
+    name?: string;
+}): string;
+/** `Message[]` -> one view row each, resolving tool names in message order. */
+export declare function messageViews(messages: readonly Message[]): ContextMessageView[];
+/**
+ * The session's context as the engine assembled it. `runtime.contextSnapshot()`
+ * is the ONLY source; the fallback (a loop without the capability) reports the
+ * profile's system prompt and the composed tool schemas with no history.
+ */
+export declare function contextViewOf(runtime: Runtime, fallback: ContextFallback): SessionContextView;
+/**
+ * W769: the read-only view helpers the adapter's HTTP surface needs, so the
+ * adapter stays a router instead of an assembly site (it is at its size budget).
+ *
+ * `sessionContextOf` is `/api/sessions/{id}/context` for one already-composed
+ * runtime: the read-only view of a runtime the caller already resolved.
+ */
+export declare function sessionContextOf(runtime: Runtime, profile: {
+    model: string;
+    system_prompt: string;
+}): SessionContextView;
+/** Tool schemas pass through verbatim (name / description / parameters). */
+export declare function toolViews(specs: readonly ToolSpec[]): ContextToolView[];