@north-light/crouter 0.3.200 → 0.3.202

package/dist/core/memory/history.js

@@ -0,0 +1,202 @@
+// Per-document revision history for the memory substrate: one append-only
+// JSONL sidecar per doc at `<store>/memory/.history/<name>.jsonl`, mirroring
+// the doc tree segment for segment. Every record carries the COMPLETE document
+// text before and after the mutation, so a reader never reconstructs a chain,
+// an interleaved concurrent append stays fully valid, and an out-of-band direct
+// file edit is visible as a record whose `before` differs from the prior
+// record's `after`. Diffs and revision numbers are derived at read time, never
+// stored.
+//
+// The raw file is the consumer contract: an external reader (a product surface
+// reading a store off disk) parses one JSON object per line and computes its
+// own diffs. Nothing here shells out to git.
+import { appendFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { ensureDir, pathExists, readText } from '../fs-utils.js';
+import { general } from '../errors.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+/** Sidecar tree name under a store's `memory/` dir. Dot-prefixed and holding
+ *  only `.jsonl`, so every substrate scan (which filters to `*.md`, and in
+ *  `lint`'s case skips dot-dirs outright) passes it over without an exclusion
+ *  rule of its own. */
+export const HISTORY_DIR = '.history';
+/** The log path for a document, derived from its PHYSICAL path so the history
+ *  tree mirrors the doc tree exactly (`memory/area/topic.md` →
+ *  `memory/.history/area/topic.jsonl`). `memoryRoot` is the store's `memory/`
+ *  dir the doc lives under. */
+export function historyLogPathFor(memoryRoot, docPath) {
+    const rel = relative(memoryRoot, docPath);
+    if (rel === '' || rel.startsWith('..')) {
+        throw general(`memory document ${docPath} is not inside its store root ${memoryRoot}`);
+    }
+    return join(memoryRoot, HISTORY_DIR, rel.replace(/\.md$/i, '') + '.jsonl');
+}
+/** Stamp the runtime-owned fields of a record. Field insertion order IS the
+ *  serialized key order — the on-disk shape consumers read. */
+export function buildHistoryRecord(input) {
+    const env = process.env;
+    const record = {
+        op: input.op,
+        at: new Date().toISOString(),
+        ...(env['CRTR_NODE_ID'] ? { node: env['CRTR_NODE_ID'] } : {}),
+        cwd: env['CRTR_NODE_CWD'] ?? process.cwd(),
+        ...(input.rationale !== undefined ? { rationale: input.rationale } : {}),
+        ...(input.verbatim === true ? { verbatim: true } : {}),
+        before: input.before,
+        after: input.after,
+    };
+    return record;
+}
+/** Append one record. Single write of one line — concurrent appends interleave
+ *  whole records, and every record stands alone, so no lock is needed. */
+export function appendHistoryRecord(logPath, record) {
+    ensureDir(dirname(logPath));
+    appendFileSync(logPath, JSON.stringify(record) + '\n', 'utf8');
+}
+/** Every record in a log, oldest first (append order). Revision numbers are
+ *  1-based positions in this array. */
+export function readHistoryRecords(logPath) {
+    if (!pathExists(logPath))
+        return [];
+    const lines = readText(logPath).split('\n');
+    const records = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.trim() === '')
+            continue;
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch {
+            throw general(`corrupt history record at ${logPath}:${i + 1} — the line is not valid JSON`, {
+                next: 'Inspect that line directly; the surrounding records are self-contained and still readable.',
+            });
+        }
+    }
+    return records;
+}
+/** What one record changed, derived from its own two texts. `last-updated` is
+ *  excluded: the runtime stamps it on every edit, so listing it says nothing. */
+export function summarizeChange(before, after) {
+    const b = parseFrontmatterGeneric(before);
+    const a = parseFrontmatterGeneric(after);
+    const bData = b.data ?? {};
+    const aData = a.data ?? {};
+    const keys = new Set([...Object.keys(bData), ...Object.keys(aData)]);
+    keys.delete('last-updated');
+    const changed = [...keys]
+        .filter((k) => JSON.stringify(bData[k]) !== JSON.stringify(aData[k]))
+        .sort((x, y) => x.localeCompare(y));
+    return { body_changed: b.body !== a.body, frontmatter_changed: changed };
+}
+/** Unified diff between two document texts, computed at read time. Dependency
+ *  free (an LCS over lines) — memory docs are lint-capped small, so the
+ *  quadratic table is never a cost. */
+export function unifiedDiff(before, after, context = 3) {
+    const { lines: a, terminated: aTerm } = toLines(before);
+    const { lines: b, terminated: bTerm } = toLines(after);
+    // Diff on keys, not raw text: an unterminated final line is a DIFFERENT line
+    // from the same text terminated, so dropping a trailing newline is a real
+    // change rather than an empty diff.
+    const ops = diffOps(diffKeys(a, aTerm), diffKeys(b, bTerm));
+    // Each changed op claims `context` ops on either side; overlapping claims
+    // merge into one hunk.
+    const ranges = [];
+    for (let i = 0; i < ops.length; i += 1) {
+        if (ops[i].tag === ' ')
+            continue;
+        const from = Math.max(0, i - context);
+        const to = Math.min(ops.length, i + context + 1);
+        const last = ranges[ranges.length - 1];
+        if (last !== undefined && from <= last.to)
+            last.to = Math.max(last.to, to);
+        else
+            ranges.push({ from, to });
+    }
+    if (ranges.length === 0)
+        return '';
+    // Line numbers each op sits at, in the before and after texts.
+    const aAt = [];
+    const bAt = [];
+    let aLine = 0;
+    let bLine = 0;
+    for (const op of ops) {
+        aAt.push(aLine);
+        bAt.push(bLine);
+        if (op.tag !== '+')
+            aLine += 1;
+        if (op.tag !== '-')
+            bLine += 1;
+    }
+    const out = [];
+    for (const { from, to } of ranges) {
+        const slice = ops.slice(from, to);
+        const aCount = slice.filter((op) => op.tag !== '+').length;
+        const bCount = slice.filter((op) => op.tag !== '-').length;
+        // A side contributing no lines is `0,0` — an empty file has no line 1.
+        out.push(`@@ -${aCount === 0 ? 0 : aAt[from] + 1},${aCount} +${bCount === 0 ? 0 : bAt[from] + 1},${bCount} @@`);
+        for (let i = from; i < to; i += 1) {
+            const op = ops[i];
+            out.push(op.tag + (op.tag === '+' ? b[op.index] : a[op.index]));
+            const endsA = op.tag !== '+' && !aTerm && aAt[i] === a.length - 1;
+            const endsB = op.tag !== '-' && !bTerm && bAt[i] === b.length - 1;
+            if (endsA || endsB)
+                out.push(NO_NEWLINE_MARKER);
+        }
+    }
+    return out.join('\n');
+}
+const NO_NEWLINE_MARKER = '\';
+// U+0000 cannot occur in a memory document, so it can never collide with text.
+const NO_NEWLINE_KEY = '\u0000no-newline-at-eof';
+function diffKeys(lines, terminated) {
+    if (terminated || lines.length === 0)
+        return lines;
+    return lines.map((line, i) => (i === lines.length - 1 ? line + NO_NEWLINE_KEY : line));
+}
+/** Split into diffable lines. A final `\n` TERMINATES the last line rather than
+ *  opening an empty one, so `foo\n` is one line; a text without it is flagged so
+ *  the diff can mark it, the way a unified patch must. */
+function toLines(text) {
+    if (text === '')
+        return { lines: [], terminated: true };
+    const terminated = text.endsWith('\n');
+    const lines = text.split('\n');
+    if (terminated)
+        lines.pop();
+    return { lines, terminated };
+}
+function diffOps(a, b) {
+    const n = a.length;
+    const m = b.length;
+    // lcs[i][j] = length of the longest common subsequence of a[i..] and b[j..].
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            ops.push({ tag: ' ', index: i });
+            i += 1;
+            j += 1;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            ops.push({ tag: '-', index: i });
+            i += 1;
+        }
+        else {
+            ops.push({ tag: '+', index: j });
+            j += 1;
+        }
+    }
+    for (; i < n; i += 1)
+        ops.push({ tag: '-', index: i });
+    for (; j < m; j += 1)
+        ops.push({ tag: '+', index: j });
+    return ops;
+}

package/dist/core/memory-resolver.d.ts

@@ -26,6 +26,11 @@ export interface MemoryDoc {
     scope: MemoryScope;
     /** Absolute path to the resolved .md file. */
     path: string;
+    /** Absolute path of the `memory/` dir this doc loaded from — the store root
+     *  its identity is relative to. Sidecar trees that mirror the doc tree (the
+     *  revision-history log) are derived from `path` relative to this. For a
+     *  plugin doc it is that plugin's own memory dir. */
+    root: string;
     /** Raw, uncoerced frontmatter record (null when the doc has no frontmatter). */
     frontmatter: Record<string, unknown> | null;
     /** Document body, with the frontmatter block stripped. */
@@ -64,6 +69,15 @@ export interface MemoryResolutionOpts {
      *  persona resolution, which stay on the flat ancestor+profile stack. */
     includeDescendants?: boolean;
 }
+/** The native (non-plugin) store dirs in resolution precedence — node >
+ *  project stack > profile > user, builtin excluded as a read-only corpus.
+ *  Addresses a store directly when the document itself may be absent, which is
+ *  how a DELETED doc's revision log is still found: history outlives the doc,
+ *  so its lookup cannot go through document resolution. */
+export declare function nativeMemoryStoresInPrecedence(scope?: MemoryScope, includeDescendants?: boolean): {
+    scope: MemoryScope;
+    memoryDir: string;
+}[];
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export declare function memoryDocId(doc: MemoryDoc): string;
 /** Whose memory view is being resolved: the workspace dir, profile, and node
@@ -105,6 +119,13 @@ export declare function listProjectMemoryDocs(startDir?: string, profileId?: str
  *  native docs are emitted before enabled-plugin docs, so native wins on the
  *  caller's first-wins dedup. */
 export declare function listAllMemoryDocs(scope?: MemoryScope, quiet?: boolean, includeDescendants?: boolean): MemoryDoc[];
+/** Resolve a document NAME against a `.history` tree, which mirrors the doc
+ *  tree segment for segment with `.jsonl` in place of `.md`. Reuses the doc
+ *  resolution rules so a log outlives its doc under the same name the doc had:
+ *  numeric prefixes stay prefix-blind (`00-topic.md` logged at
+ *  `.history/00-topic.jsonl` still answers to `topic`) and a bare directory
+ *  name falls back to its INDEX log. Returns null when nothing resolves. */
+export declare function resolveHistoryLogPath(historyDir: string, segments: string[]): string | null;
 export interface MemoryDocSnapshot {
     /** Every document in default scope precedence order, loaded once. */
     docs: readonly MemoryDoc[];

package/dist/core/memory-resolver.js

@@ -11,6 +11,20 @@ import { effectiveDocKind, normalizeDocName, normalizeNameSegment, resolveDocNam
 import { loadProfileManifest, profileMemoryDir } from './profiles/manifest.js';
 import { memoryDir as nodeMemoryDir } from './runtime/memory.js';
 import { descendantStoreRoots } from './nested-stores.js';
+/** The native (non-plugin) store dirs in resolution precedence — node >
+ *  project stack > profile > user, builtin excluded as a read-only corpus.
+ *  Addresses a store directly when the document itself may be absent, which is
+ *  how a DELETED doc's revision log is still found: history outlives the doc,
+ *  so its lookup cannot go through document resolution. */
+export function nativeMemoryStoresInPrecedence(scope, includeDescendants = false) {
+    const out = [];
+    for (const source of memorySourcesInPrecedence(ambientTarget(), scope, includeDescendants)) {
+        if (source.scope === 'builtin' || source.memoryDir === null)
+            continue;
+        out.push({ scope: source.scope, memoryDir: source.memoryDir });
+    }
+    return out;
+}
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export function memoryDocId(doc) {
     return `${doc.scope}/${doc.name}`;
@@ -109,9 +123,9 @@ function memorySourcesInPrecedence(target, scope, includeDescendants = false) {
     }
     return out;
 }
-function loadMemoryDoc(scope, path, fallbackName) {
+function loadMemoryDoc(scope, root, path, fallbackName) {
     const { data, body } = parseFrontmatterGeneric(readText(path));
-    return { name: resolveDocName(data, fallbackName), scope, path, frontmatter: data, body };
+    return { name: resolveDocName(data, fallbackName), scope, path, root, frontmatter: data, body };
 }
 /** All memory docs in one memory/ dir, scanned recursively for *.md (topical
  *  subdirs supported), sorted by resolver identity (explicit frontmatter name
@@ -157,7 +171,7 @@ function listMemoryDocsInDir(scope, dir, quiet = false) {
         // `quiet` suppresses the notice for a targeted resolve (a leaf-name read),
         // where another doc's health is irrelevant noise before the result.
         try {
-            docs.push(loadMemoryDoc(scope, path, name));
+            docs.push(loadMemoryDoc(scope, dir, path, name));
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
@@ -211,7 +225,7 @@ export function listPluginMemoryDocs(plugin, scope, quiet = false) {
             continue;
         const name = `${plugin.name}/${derived}`;
         try {
-            docs.push({ ...loadMemoryDoc(scope, file, name), plugin: plugin.name });
+            docs.push({ ...loadMemoryDoc(scope, dir, file, name), plugin: plugin.name });
         }
         catch (e) {
             const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
@@ -250,13 +264,13 @@ export function listProjectMemoryDocs(startDir = process.cwd(), profileId = sele
 export function listAllMemoryDocs(scope, quiet = false, includeDescendants = false) {
     return memorySourcesInPrecedence(ambientTarget(), scope, includeDescendants).flatMap((source) => sourceMemoryDocs(source, quiet));
 }
-/** Find the direct child of `dir` — a `.md` file (matched on name minus
+/** Find the direct child of `dir` — an `ext` file (matched on name minus
  *  extension) or a directory — whose NORMALIZED display name equals
  *  `segment`. An exact literal match (no prefix to strip) wins over a
  *  normalized match, so a `spine` dir sitting beside a `01-spine` dir (a
  *  malformed corpus) never masks the literal one; a well-formed corpus has at
  *  most one candidate either way. Returns the absolute child path, or null. */
-function matchNormalizedChild(dir, segment, want) {
+function matchNormalizedChild(dir, segment, want, ext = '.md') {
     let entries;
     try {
         entries = readdirSync(dir, { withFileTypes: true });
@@ -276,9 +290,9 @@ function matchNormalizedChild(dir, segment, want) {
             }
         }
         else {
-            if (!(e.isFile() && e.name.endsWith('.md')))
+            if (!(e.isFile() && e.name.endsWith(ext)))
                 continue;
-            const base = e.name.slice(0, -3);
+            const base = e.name.slice(0, -ext.length);
             if (base === segment)
                 return join(dir, e.name);
             if (normalizedHit === null && normalizeNameSegment(base) === segment) {
@@ -297,20 +311,37 @@ function matchNormalizedChild(dir, segment, want) {
  *  `00-runtime-base.md` findable as `runtime-base` and `01-spine/00-has-manager`
  *  findable as `spine/has-manager` — the physical path keeps its pins, only
  *  lookup is prefix-blind. */
-function resolveNormalizedPath(baseDir, segments) {
+function resolveNormalizedPath(baseDir, segments, ext = '.md') {
     let curDir = baseDir;
     for (let i = 0; i < segments.length - 1; i++) {
-        const next = matchNormalizedChild(curDir, segments[i], 'dir');
+        const next = matchNormalizedChild(curDir, segments[i], 'dir', ext);
         if (!next)
             return { filePath: null, dirPath: null };
         curDir = next;
     }
     const last = segments[segments.length - 1];
     return {
-        filePath: matchNormalizedChild(curDir, last, 'file'),
-        dirPath: matchNormalizedChild(curDir, last, 'dir'),
+        filePath: matchNormalizedChild(curDir, last, 'file', ext),
+        dirPath: matchNormalizedChild(curDir, last, 'dir', ext),
     };
 }
+/** Resolve a document NAME against a `.history` tree, which mirrors the doc
+ *  tree segment for segment with `.jsonl` in place of `.md`. Reuses the doc
+ *  resolution rules so a log outlives its doc under the same name the doc had:
+ *  numeric prefixes stay prefix-blind (`00-topic.md` logged at
+ *  `.history/00-topic.jsonl` still answers to `topic`) and a bare directory
+ *  name falls back to its INDEX log. Returns null when nothing resolves. */
+export function resolveHistoryLogPath(historyDir, segments) {
+    const { filePath, dirPath } = resolveNormalizedPath(historyDir, segments, '.jsonl');
+    if (filePath)
+        return filePath;
+    if (dirPath) {
+        const index = matchNormalizedChild(dirPath, 'INDEX', 'file', '.jsonl');
+        if (index)
+            return index;
+    }
+    return null;
+}
 /** Direct full-path lookup of memory/<name>.md within ONE source. Returns that
  *  source's single hit, or undefined — a source can produce at most one direct
  *  match (native wins over plugin within the source, and at most one plugin's
@@ -333,11 +364,11 @@ function findMemoryMatchInSource(name, segments, source) {
     if (dir) {
         const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
         if (!isLegacySkillDoc && filePath !== null)
-            return loadMemoryDoc(source.scope, filePath, name);
+            return loadMemoryDoc(source.scope, dir, filePath, name);
         if (dirPath !== null) {
             const indexPath = join(dirPath, 'INDEX.md');
             if (pathExists(indexPath))
-                return loadMemoryDoc(source.scope, indexPath, name);
+                return loadMemoryDoc(source.scope, dir, indexPath, name);
         }
     }
     // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
@@ -356,14 +387,14 @@ function findMemoryMatchInSource(name, segments, source) {
         if (rest) {
             const { filePath } = resolveNormalizedPath(pdir, restSegments);
             if (restSegments.at(-1) !== 'SKILL' && filePath !== null)
-                return loadMemoryDoc(source.scope, filePath, name);
+                return loadMemoryDoc(source.scope, pdir, filePath, name);
         }
         // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
         const pIndexDir = rest ? resolveNormalizedPath(pdir, restSegments).dirPath : pdir;
         if (pIndexDir !== null) {
             const pindex = join(pIndexDir, 'INDEX.md');
             if (pathExists(pindex))
-                return loadMemoryDoc(source.scope, pindex, name);
+                return loadMemoryDoc(source.scope, pdir, pindex, name);
         }
     }
     return undefined;

package/dist/core/preview-registry.js

@@ -114,6 +114,8 @@ const LEAF_ICON_CP = {
     'memory read': 0xf02d,
     'memory find': 0xf002,
     'memory write': 0xf040,
+    'memory edit': 0xf044,
+    'memory history': 0xf1da,
     'memory origin': 0xf1bb,
     'memory lint': 0xf14a,
     'node new': 0xf067,

package/dist/core/runtime/node-read.d.ts

@@ -28,9 +28,20 @@ export interface NodeSnapshotRead {
         source: 'builtin';
     }>;
 }
+export interface NodeMessagesPageRead {
+    messages: unknown[];
+    nextCursor: string | null;
+}
+export interface NodeMessagesPageOptions {
+    cursor?: string;
+    limit?: number;
+}
 /** Reconstruct a persisted session without launching its broker. Backs the
  * machine-readable snapshot endpoint and the human transcript render. */
 export declare function readNodeSnapshot(nodeId: string): Promise<NodeSnapshotRead>;
+/** A backward-paged, chronological window over the same visible history as a
+ * snapshot. `nextCursor` walks toward older messages. */
+export declare function readNodeMessagesPage(nodeId: string, { cursor, limit }: NodeMessagesPageOptions): Promise<NodeMessagesPageRead>;
 /** Human-readable history only: text messages plus terse tool records, never
  * private model reasoning. */
 export declare function transcriptMarkdown(nodeId: string): Promise<string>;

package/dist/core/runtime/node-read.js

@@ -135,9 +135,10 @@ function readToolGroupSummaries(nodeId) {
         return {};
     }
 }
-/** Reconstruct a persisted session without launching its broker. Backs the
- * machine-readable snapshot endpoint and the human transcript render. */
-export async function readNodeSnapshot(nodeId) {
+/** Reconstruct the visible message history from a stable at-rest session copy.
+ * Both snapshot and paged reads use this one path so their histories cannot
+ * diverge. */
+async function reconstructVisibleMessages(nodeId) {
     const node = getNode(nodeId);
     if (node === null) {
         throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, field: 'id', next: 'List nodes with `crtr node inspect list`.' });
@@ -146,57 +147,122 @@ export async function readNodeSnapshot(nodeId) {
     if (sessionFile === null) {
         throw new InputError({ error: 'no_session', message: `node has no readable session file: ${nodeId}`, field: 'id', next: 'Choose a node with captured conversation history.' });
     }
-    const tempDir = mkdtempSync(join(tmpdir(), 'crtr-node-snapshot-'));
+    const tempDir = mkdtempSync(join(tmpdir(), 'crtr-node-session-'));
     try {
         const copy = join(tempDir, basename(sessionFile));
         copyFileSync(sessionFile, copy);
         const manager = SessionManager.open(copy);
         const context = manager.buildSessionContext();
         const messages = visibleMessages(cycleAwareMessages(manager), { boundaryReviewId: node.review_binding?.review_id });
-        const sessionId = manager.getSessionId();
-        const sessionName = manager.getSessionName();
-        const snapshot = {
-            messages,
-            stats: statsFromMessages(messages, sessionId, sessionFile),
-            // pi's `get_state` shape (RpcSessionState), reconstructed offline: the
-            // live-only fields report their at-rest values (nothing is streaming or
-            // queued for a node with no broker).
-            state: {
-                model: await resolveRecordedModel(context.model),
-                thinkingLevel: context.thinkingLevel,
-                isStreaming: false,
-                isCompacting: false,
-                steeringMode: 'one-at-a-time',
-                followUpMode: 'one-at-a-time',
-                sessionFile,
-                sessionId,
-                sessionName,
-                autoCompactionEnabled: true,
-                messageCount: messages.length,
-                pendingMessageCount: 0,
-            },
-            // A snapshot reconstructed from the .jsonl alone: display state is broker
-            // process state (last setStatus/setWidget/setTitle) and is not persisted,
-            // so an offline read has none.
-            display: { statuses: {}, widgets: {}, title: undefined },
-            // The unrun queue lives in the engine's memory; a dormant node has no
-            // engine, so nothing is waiting to run.
-            queued: { steering: [], followUp: [] },
-            // Sidecar summaries survive broker exit so a dormant transcript receives
-            // the same completed-group data as a live welcome snapshot. Malformed or
-            // absent sidecars are deliberately ignored: tool calls remain visible.
-            toolGroupSummaries: readToolGroupSummaries(nodeId),
-        };
         return {
-            nodeId,
-            snapshot,
-            commands: BUILTIN_SLASH_COMMANDS.map((c) => ({ ...c, source: 'builtin' })),
+            sessionFile,
+            messages,
+            model: context.model,
+            thinkingLevel: context.thinkingLevel,
+            sessionId: manager.getSessionId(),
+            sessionName: manager.getSessionName(),
         };
     }
     finally {
         rmSync(tempDir, { recursive: true, force: true });
     }
 }
+function invalidCursor() {
+    throw new InputError({
+        error: 'invalid_cursor',
+        message: 'cursor must be a base64url-encoded messages cursor.',
+        field: 'cursor',
+        next: 'Omit cursor to start from the newest messages.',
+    });
+}
+function decodeMessagesCursor(cursor, messagesLength) {
+    if (!/^[A-Za-z0-9_-]+$/u.test(cursor))
+        invalidCursor();
+    let parsed;
+    try {
+        const json = Buffer.from(cursor, 'base64url').toString('utf8');
+        if (Buffer.from(json, 'utf8').toString('base64url') !== cursor)
+            invalidCursor();
+        parsed = JSON.parse(json);
+    }
+    catch {
+        invalidCursor();
+    }
+    if (typeof parsed !== 'object'
+        || parsed === null
+        || parsed.v !== 1
+        || !Number.isSafeInteger(parsed.before)) {
+        invalidCursor();
+    }
+    const before = parsed.before;
+    if (before < 0 || before > messagesLength)
+        invalidCursor();
+    return before;
+}
+function encodeMessagesCursor(before) {
+    return Buffer.from(JSON.stringify({ v: 1, before }), 'utf8').toString('base64url');
+}
+/** Reconstruct a persisted session without launching its broker. Backs the
+ * machine-readable snapshot endpoint and the human transcript render. */
+export async function readNodeSnapshot(nodeId) {
+    const read = await reconstructVisibleMessages(nodeId);
+    const snapshot = {
+        messages: read.messages,
+        stats: statsFromMessages(read.messages, read.sessionId, read.sessionFile),
+        // pi's `get_state` shape (RpcSessionState), reconstructed offline: the
+        // live-only fields report their at-rest values (nothing is streaming or
+        // queued for a node with no broker).
+        state: {
+            model: await resolveRecordedModel(read.model),
+            thinkingLevel: read.thinkingLevel,
+            isStreaming: false,
+            isCompacting: false,
+            steeringMode: 'one-at-a-time',
+            followUpMode: 'one-at-a-time',
+            sessionFile: read.sessionFile,
+            sessionId: read.sessionId,
+            sessionName: read.sessionName,
+            autoCompactionEnabled: true,
+            messageCount: read.messages.length,
+            pendingMessageCount: 0,
+        },
+        // A snapshot reconstructed from the .jsonl alone: display state is broker
+        // process state (last setStatus/setWidget/setTitle) and is not persisted,
+        // so an offline read has none.
+        display: { statuses: {}, widgets: {}, title: undefined },
+        // The unrun queue lives in the engine's memory; a dormant node has no
+        // engine, so nothing is waiting to run.
+        queued: { steering: [], followUp: [] },
+        // Sidecar summaries survive broker exit so a dormant transcript receives
+        // the same completed-group data as a live welcome snapshot. Malformed or
+        // absent sidecars are deliberately ignored: tool calls remain visible.
+        toolGroupSummaries: readToolGroupSummaries(nodeId),
+    };
+    return {
+        nodeId,
+        snapshot,
+        commands: BUILTIN_SLASH_COMMANDS.map((c) => ({ ...c, source: 'builtin' })),
+    };
+}
+/** A backward-paged, chronological window over the same visible history as a
+ * snapshot. `nextCursor` walks toward older messages. */
+export async function readNodeMessagesPage(nodeId, { cursor, limit = 200 }) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500) {
+        throw new InputError({
+            error: 'invalid_limit',
+            message: 'limit must be an integer from 1 through 500.',
+            field: 'limit',
+            next: 'Use a limit from 1 through 500.',
+        });
+    }
+    const { messages } = await reconstructVisibleMessages(nodeId);
+    const before = cursor === undefined ? messages.length : decodeMessagesCursor(cursor, messages.length);
+    const start = Math.max(0, before - limit);
+    return {
+        messages: messages.slice(start, before),
+        nextCursor: start === 0 ? null : encodeMessagesCursor(start),
+    };
+}
 function textFromContent(content) {
     if (typeof content === 'string')
         return content;

package/dist/daemon/api/handlers/inbox.js

@@ -187,6 +187,7 @@ function handleList() {
                 slot_kinds: item.slotKinds,
                 inbox: item.inbox,
                 awaits_response: item.awaitsResponse,
+                state: item.state,
             };
             if (item.subtitle !== '')
                 dto.subtitle = item.subtitle;

package/dist/daemon/api/handlers/nodes.js

@@ -14,7 +14,7 @@ import { childrenOf, subscribersOf, subscriptionsOf, setMessageWait, updateNode
 import { subtreeIds } from '../../../core/canvas/nav-model.js';
 import { contextDir, reportsDir } from '../../../core/canvas/paths.js';
 import { nodeArtifacts } from '../../../core/canvas/history.js';
-import { readNodeSession, readNodeSnapshot, transcriptMarkdown } from '../../../core/runtime/node-read.js';
+import { readNodeMessagesPage, readNodeSession, readNodeSnapshot, transcriptMarkdown } from '../../../core/runtime/node-read.js';
 import { reviveAll } from '../../../core/runtime/revive-all.js';
 import { promote, requestYield, reshapeNode } from '../../../core/runtime/promote.js';
 import { recycleNode } from '../../../core/runtime/recycle.js';
@@ -301,6 +301,38 @@ async function handleSnapshot(ctx) {
     };
     return { status: 200, body };
 }
+function parseMessagesQuery(ctx) {
+    for (const [field] of ctx.query) {
+        if (field !== 'cursor' && field !== 'limit')
+            throw usage(`unknown messages query parameter: ${field}`);
+    }
+    const cursors = ctx.query.getAll('cursor');
+    const limits = ctx.query.getAll('limit');
+    if (cursors.length > 1)
+        throw usage('cursor must appear at most once');
+    if (limits.length > 1)
+        throw usage('limit must appear at most once');
+    if (limits.length === 0)
+        return cursors.length === 0 ? {} : { cursor: cursors[0] };
+    const rawLimit = limits[0];
+    const limit = Number(rawLimit);
+    if (!Number.isSafeInteger(limit) || rawLimit === '') {
+        throw usage('limit must be an integer from 1 through 500');
+    }
+    return cursors.length === 0 ? { limit } : { cursor: cursors[0], limit };
+}
+/** Offline, backward-paged read of the cycle-flattened visible history. */
+async function handleMessages(ctx) {
+    const id = ctx.params['id'];
+    const read = await readNodeMessagesPage(id, parseMessagesQuery(ctx));
+    const body = {
+        node_id: id,
+        messages: read.messages,
+        next_cursor: read.nextCursor,
+        captured_at: nowIso(),
+    };
+    return { status: 200, body };
+}
 /** The faithful export read: raw `.jsonl` bytes + assembled system prompt.
  *  `/snapshot` reconstructs a cycle-flattened `AgentMessage[]` for renderers and
  *  drops what a renderer cannot show; this drops nothing. */
@@ -598,6 +630,7 @@ export const nodeRoutes = [
     { method: 'POST', pattern: '/v1/nodes/revive-all', handler: () => handleReviveAll() },
     { method: 'GET', pattern: '/v1/nodes/:id', handler: handleDetail },
     { method: 'GET', pattern: '/v1/nodes/:id/snapshot', handler: handleSnapshot },
+    { method: 'GET', pattern: '/v1/nodes/:id/messages', handler: handleMessages },
     { method: 'GET', pattern: '/v1/nodes/:id/session', handler: handleSession },
     { method: 'GET', pattern: '/v1/nodes/:id/transcript', handler: handleTranscript },
     { method: 'GET', pattern: '/v1/nodes/:id/context', handler: handleContext },