@north-light/crouter 0.3.263 → 0.3.269

package/dist/core/canvas/canvas.js

@@ -83,14 +83,15 @@ function writeMeta(meta) {
  *  state. A fresh insert takes the schema defaults for runtime. */
 function upsertRow(meta) {
     openDb()
-        .prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created, pi_session_file)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        .prepare(`INSERT INTO nodes (node_id, name, description, cycles, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created, pi_session_file)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(node_id) DO UPDATE SET
-         name=excluded.name, kind=excluded.kind, mode=excluded.mode,
+         name=excluded.name, description=excluded.description, cycles=excluded.cycles,
+         kind=excluded.kind, mode=excluded.mode,
          lifecycle=excluded.lifecycle, cwd=excluded.cwd, host_kind=excluded.host_kind,
          profile_id=excluded.profile_id, parent=excluded.parent,
          pi_session_file=excluded.pi_session_file`)
-        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, typeof meta.pi_session_file === 'string' ? canonicalSessionFile(meta.pi_session_file) : null);
+        .run(meta.node_id, meta.name, meta.description ?? null, meta.cycles ?? null, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, typeof meta.pi_session_file === 'string' ? canonicalSessionFile(meta.pi_session_file) : null);
 }
 /** Seed a node's row at BIRTH: identity columns + runtime columns taken from the
  *  incoming meta (defaults: status='active', the rest null). The only writer
@@ -99,11 +100,12 @@ function upsertRow(meta) {
 function seedRow(meta) {
     openDb()
         .prepare(`INSERT INTO nodes
-         (node_id, name, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created, pi_session_file,
+         (node_id, name, description, cycles, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created, pi_session_file,
           status, intent, waiting_for, final_report, finalized_at, pi_pid, "window", tmux_session, pane)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(node_id) DO UPDATE SET
-         name=excluded.name, kind=excluded.kind, mode=excluded.mode,
+         name=excluded.name, description=excluded.description, cycles=excluded.cycles,
+         kind=excluded.kind, mode=excluded.mode,
          lifecycle=excluded.lifecycle, cwd=excluded.cwd, host_kind=excluded.host_kind,
          profile_id=excluded.profile_id, parent=excluded.parent,
          pi_session_file=excluded.pi_session_file,
@@ -111,12 +113,14 @@ function seedRow(meta) {
          final_report=excluded.final_report, finalized_at=excluded.finalized_at,
          pi_pid=excluded.pi_pid, "window"=excluded."window", tmux_session=excluded.tmux_session,
          pane=excluded.pane`)
-        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, typeof meta.pi_session_file === 'string' ? canonicalSessionFile(meta.pi_session_file) : null, meta.status ?? 'active', meta.intent ?? null, meta.waiting_for ?? null, meta.final_report ?? null, meta.finalized_at ?? null, meta.pi_pid ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null);
+        .run(meta.node_id, meta.name, meta.description ?? null, meta.cycles ?? null, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, typeof meta.pi_session_file === 'string' ? canonicalSessionFile(meta.pi_session_file) : null, meta.status ?? 'active', meta.intent ?? null, meta.waiting_for ?? null, meta.final_report ?? null, meta.finalized_at ?? null, meta.pi_pid ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null);
 }
 function rowFrom(r) {
     return {
         node_id: r['node_id'],
         name: r['name'],
+        description: r['description'] ?? undefined,
+        cycles: r['cycles'] ?? undefined,
         kind: r['kind'],
         mode: r['mode'],
         lifecycle: r['lifecycle'],

package/dist/core/canvas/extensions.d.ts

@@ -1,4 +1,4 @@
-export declare const CANVAS_EXTENSION_NAMES: readonly ["canvas-inbox-watcher", "canvas-review-boundary", "canvas-stophook", "canvas-recap", "canvas-goal-capture", "canvas-passive-context", "canvas-context-intro", "canvas-tool-guide", "canvas-doc-substrate", "canvas-structured-output", "canvas-bash-valve", "canvas-preview-result", "canvas-prompt-scrub"];
+export declare const CANVAS_EXTENSION_NAMES: readonly ["canvas-inbox-watcher", "canvas-review-boundary", "canvas-stophook", "canvas-recap", "canvas-goal-capture", "canvas-passive-context", "canvas-context-intro", "canvas-tool-guide", "canvas-doc-substrate", "canvas-structured-output", "canvas-bash-valve", "canvas-preview-result", "canvas-prompt-scrub", "canvas-stamp"];
 /** Structural shipped-hook identity: a canvas-hook stem directly under a
  * `pi-extensions` directory. A user's own extension elsewhere may share the
  * stem and is not shipped. */

package/dist/core/canvas/extensions.js

@@ -7,9 +7,15 @@ export const CANVAS_EXTENSION_NAMES = [
     'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
     'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
     'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
-    'canvas-bash-valve', 'canvas-preview-result', 'canvas-prompt-scrub',
+    'canvas-bash-valve', 'canvas-preview-result', 'canvas-prompt-scrub', 'canvas-stamp',
 ];
 const HISTORICAL_CANVAS_EXTENSION_PREFIXES = [
+    [
+        'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
+        'canvas-bash-valve', 'canvas-preview-result', 'canvas-prompt-scrub',
+    ],
     [
         'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
         'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',

package/dist/core/canvas/history.d.ts

@@ -1,5 +1,13 @@
 import type { NodeStatus } from './types.js';
-export type HistorySource = 'report' | 'doc' | 'roadmap' | 'meta' | 'inbox';
+export type HistorySource = 'report' | 'doc' | 'roadmap' | 'meta' | 'inbox' | 'transcript';
+/** Every origin token `--origin` accepts. `human` is a person at a front door;
+ *  the rest mirror the runtime origin kinds; `unknown` is a message that
+ *  carries no stamp at all — its own bucket, never folded into another, since
+ *  a rising unknown rate is how a delivery seam that stopped announcing shows
+ *  itself. */
+export declare const ORIGIN_TOKENS: readonly ["human", "inbox", "wake", "revive", "restart-continuation", "stop-guard", "park", "recovery", "context-nudge", "kickoff", "unknown"];
+/** Message roles carried by a transcript artifact. */
+export declare const MESSAGE_ROLES: readonly ["user", "assistant", "toolResult"];
 /** One searchable unit of the episodic record: a report, a context doc, a
  *  node's roadmap, or a node's meta (name/description/kind). */
 export interface HistoryArtifact {
@@ -26,6 +34,16 @@ export interface HistoryArtifact {
     path: string | null;
     /** Frontmatter-stripped body, loaded once and cached. Empty on read error. */
     loadBody: () => string;
+    /** What drove this message to arrive. Set ONLY on inbound artifacts — a
+     *  user-role transcript message or an inbox entry — because origin is a
+     *  property of arrival. An assistant turn leaves it undefined, so `--origin`
+     *  excludes generated turns without needing a role filter beside it. */
+    origin?: string;
+    /** Transcript only: user | assistant | toolResult. */
+    role?: string;
+    /** Sender attribution: an inbox stamp's delivered entries, or an inbox
+     *  entry's own sender. Comma-joined when a delivery carried several. */
+    from?: string;
 }
 export interface ScopeFilter {
     /** A specific cwd. Default (all flags absent) = the caller's cwd. */
@@ -48,6 +66,12 @@ export interface CorpusFilter {
     /** Inclusive lower / upper bound on artifact ts, epoch ms. */
     sinceMs?: number;
     untilMs?: number;
+    /** Message-attribute narrowing — meaningful for transcript + inbox only.
+     *  An artifact without the field never survives the corresponding filter. */
+    origins?: string[];
+    roles?: string[];
+    /** Case-insensitive substring against the artifact's sender attribution. */
+    from?: string;
 }
 /** The cwd the caller means by default: the calling node's cwd (resolved from
  *  CRTR_NODE_ID via the canvas data layer), falling back to the process cwd
@@ -62,6 +86,17 @@ export declare function newestReportRef(nodeId: string): string | null;
  *  are applied against the db rows first (cheap); only surviving nodes' files
  *  are read. */
 export declare function buildCorpus(scope: ScopeFilter, corpus: CorpusFilter): HistoryArtifact[];
+export type GroupKey = 'origin' | 'node' | 'kind' | 'day' | 'type' | 'role';
+export interface CorpusGroup {
+    key: string;
+    count: number;
+}
+/** Collapse a built corpus into counts by one dimension, descending by count.
+ *  Artifacts that do not carry the grouped dimension are omitted rather than
+ *  bucketed as empty — grouping by origin answers "what drove arrivals", and a
+ *  generated turn is not an arrival. `unknown` is a real origin value here, not
+ *  a missing one. */
+export declare function groupCorpus(arts: HistoryArtifact[], by: GroupKey): CorpusGroup[];
 export interface ResolvedRef {
     nodeId: string;
     relpath: string;

package/dist/core/canvas/history.js

@@ -13,10 +13,31 @@ import { envNodeId } from '../../shared/env.js';
 import { statSync, readdirSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { getNode, listNodes, view } from './canvas.js';
-import { contextDir, reportsDir, nodeDir, inboxPath } from './paths.js';
+import { contextDir, reportsDir, nodeDir, inboxPath, sessionPtrPath } from './paths.js';
 import { readTextIfExists, walkFiles, pathExists } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { warn } from '../output.js';
+import { readStamps } from '../runtime/stamp/protocol.js';
+/** Every origin token `--origin` accepts. `human` is a person at a front door;
+ *  the rest mirror the runtime origin kinds; `unknown` is a message that
+ *  carries no stamp at all — its own bucket, never folded into another, since
+ *  a rising unknown rate is how a delivery seam that stopped announcing shows
+ *  itself. */
+export const ORIGIN_TOKENS = [
+    'human',
+    'inbox',
+    'wake',
+    'revive',
+    'restart-continuation',
+    'stop-guard',
+    'park',
+    'recovery',
+    'context-nudge',
+    'kickoff',
+    'unknown',
+];
+/** Message roles carried by a transcript artifact. */
+export const MESSAGE_ROLES = ['user', 'assistant', 'toolResult'];
 /** The cwd the caller means by default: the calling node's cwd (resolved from
  *  CRTR_NODE_ID via the canvas data layer), falling back to the process cwd
  *  when not run as a node. */
@@ -184,7 +205,10 @@ function inboxEntryBody(e) {
 function inboxArtifact(row, desc, entry, index) {
     const relpath = `inbox/${String(index).padStart(6, '0')}`;
     const body = inboxEntryBody(entry);
-    return {
+    // An inbox entry IS an arrival, so it carries the same two inbound
+    // dimensions a stamped user message does — which is what lets `--origin` and
+    // `--from` span the transcript and inbox corpora with one vocabulary.
+    const a = {
         ref: `${row.node_id}:${relpath}`,
         nodeId: row.node_id,
         relpath,
@@ -199,7 +223,201 @@ function inboxArtifact(row, desc, entry, index) {
         nodeDesc: desc,
         path: null,
         loadBody: () => body,
+        origin: 'inbox',
+    };
+    if (typeof entry.from === 'string' && entry.from !== '')
+        a.from = entry.from;
+    return a;
+}
+/** The node's session `.jsonl`, or null when nothing has been written yet. pi
+ *  binds the path at session creation but writes the file on the FIRST appended
+ *  entry, so a fresh node has a bound path that is not yet on disk. Mirrors
+ *  `runtime/node-read.ts`'s resolution: the recorded path first, then the
+ *  `session.ptr` the node dir carries. */
+function resolveSessionFile(nodeId) {
+    const node = getNode(nodeId);
+    const recorded = node?.pi_session_file;
+    if (typeof recorded === 'string' && recorded !== '' && pathExists(recorded))
+        return recorded;
+    const raw = readTextIfExists(sessionPtrPath(nodeId));
+    if (raw === null)
+        return null;
+    const target = raw.trim();
+    return target !== '' && pathExists(target) ? target : null;
+}
+/** The searchable text of a message's content blocks. `thinking` blocks are
+ *  deliberately dropped: private model reasoning is excluded from every human
+ *  transcript surface, and putting it in the search corpus would leak it back
+ *  in through grep. */
+function textFromBlocks(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (block === null || typeof block !== 'object')
+            continue;
+        const b = block;
+        if (b['type'] === 'text' && typeof b['text'] === 'string')
+            parts.push(b['text']);
+        else if (b['type'] === 'toolCall')
+            parts.push(`Tool: ${typeof b['name'] === 'string' ? b['name'] : 'call'}`);
+    }
+    return parts.join('\n');
+}
+/** The single token `--origin` matches against. */
+function originToken(origin) {
+    if (origin === null || origin === undefined)
+        return 'unknown';
+    return origin.type === 'human' ? 'human' : origin.kind;
+}
+/** Who a delivery came from, comma-joined when it carried several entries. */
+function sendersOf(origin) {
+    if (origin === null || origin === undefined || origin.type !== 'runtime')
+        return undefined;
+    const entries = origin.entries;
+    if (entries === undefined || entries.length === 0)
+        return undefined;
+    const names = new Set();
+    for (const e of entries) {
+        const who = e.fromName ?? e.from;
+        if (typeof who === 'string' && who !== '')
+            names.add(who);
+    }
+    return names.size === 0 ? undefined : [...names].join(', ');
+}
+/** Parse a node's session file into its messages, each carrying the origin its
+ *  stamp recorded. Deliberately a direct line parse rather than pi's
+ *  SessionManager: reconstruction copies the file to a temp dir and rebuilds
+ *  cycles, which is far too heavy to run across every node in a scan.
+ *
+ *  Stamps are correlated by the target message's own `timestamp` (epoch ms) —
+ *  never by tree position, because a stamp is physically written BEFORE the
+ *  message it describes. */
+function sessionMessages(nodeId) {
+    const file = resolveSessionFile(nodeId);
+    if (file === null)
+        return [];
+    const raw = readTextIfExists(file);
+    if (raw === null)
+        return [];
+    const entries = [];
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            // A truncated final line is normal while a broker is mid-append.
+        }
+    }
+    const origins = new Map();
+    for (const stamp of readStamps(entries)) {
+        if (stamp.kind !== 'message')
+            continue;
+        const payload = stamp.payload;
+        if (typeof payload.msgTs !== 'number')
+            continue;
+        origins.set(payload.msgTs, payload.origin);
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const e = entry;
+        if (e['type'] !== 'message')
+            continue;
+        const message = e['message'];
+        if (message === null || typeof message !== 'object')
+            continue;
+        const m = message;
+        const role = typeof m['role'] === 'string' ? m['role'] : '';
+        if (role === '')
+            continue;
+        const msgTs = typeof m['timestamp'] === 'number' ? m['timestamp'] : undefined;
+        const iso = typeof e['timestamp'] === 'string'
+            ? e['timestamp']
+            : msgTs !== undefined ? new Date(msgTs).toISOString() : '';
+        const text = textFromBlocks(m['content']);
+        const msg = {
+            index: out.length,
+            role,
+            text,
+            ts: iso,
+            tsMs: msgTs ?? toMs(iso),
+        };
+        // Origin is a property of ARRIVAL, so only an inbound turn carries one.
+        if (role === 'user') {
+            const origin = msgTs !== undefined && origins.has(msgTs) ? origins.get(msgTs) : null;
+            msg.origin = originToken(origin);
+            const from = sendersOf(origin);
+            if (from !== undefined)
+                msg.from = from;
+        }
+        out.push(msg);
+    }
+    return out;
+}
+/** The verbatim jsonl line that persisted the Nth MESSAGE. Message ordinals
+ *  and line numbers differ — stamps, model changes, and session headers occupy
+ *  lines of their own — so this re-walks the file counting message entries
+ *  rather than indexing lines directly. */
+function rawSessionLine(file, index) {
+    const raw = readTextIfExists(file);
+    if (raw === null)
+        return null;
+    let seen = 0;
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (parsed === null || typeof parsed !== 'object')
+            continue;
+        const e = parsed;
+        if (e['type'] !== 'message')
+            continue;
+        const m = e['message'];
+        if (m === null || typeof m !== 'object' || typeof m['role'] !== 'string')
+            continue;
+        if (seen === index)
+            return line;
+        seen++;
+    }
+    return null;
+}
+function transcriptArtifact(row, desc, msg) {
+    const relpath = `session/${String(msg.index).padStart(6, '0')}`;
+    const lead = msg.text.split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
+    const a = {
+        ref: `${row.node_id}:${relpath}`,
+        nodeId: row.node_id,
+        relpath,
+        source: 'transcript',
+        ts: msg.ts,
+        tsMs: msg.tsMs,
+        title: `[${msg.role}] ${lead.length > 80 ? `${lead.slice(0, 80)}…` : lead}`,
+        nodeName: row.name,
+        nodeKind: row.kind,
+        nodeStatus: row.status,
+        nodeCwd: row.cwd,
+        nodeDesc: desc,
+        path: null,
+        loadBody: () => msg.text,
+        role: msg.role,
     };
+    if (msg.origin !== undefined)
+        a.origin = msg.origin;
+    if (msg.from !== undefined)
+        a.from = msg.from;
+    return a;
 }
 function metaArtifact(row, desc) {
     const body = `${row.name}\n${desc}\n${row.kind}`;
@@ -280,9 +498,10 @@ export function buildCorpus(scope, corpus) {
             return false;
         return true;
     });
-    // --report-kind implies type=report. `inbox` is opt-in only — never part of
-    // the default set — since a node's raw inbox history is unbounded diagnostic
-    // detail, not curated past work.
+    // --report-kind implies type=report. `inbox` and `transcript` are opt-in
+    // only — never part of the default set — since a node's raw inbox history and
+    // its full conversation are unbounded diagnostic detail, not curated past
+    // work.
     const wantReportKind = corpus.reportKind;
     const types = corpus.types !== undefined && corpus.types.length > 0
         ? corpus.types
@@ -335,16 +554,76 @@ export function buildCorpus(scope, corpus) {
         if (want.has('inbox')) {
             allInboxEntries(row.node_id).forEach((entry, i) => out.push(inboxArtifact(row, desc, entry, i)));
         }
+        if (want.has('transcript')) {
+            for (const msg of sessionMessages(row.node_id))
+                out.push(transcriptArtifact(row, desc, msg));
+        }
     }
-    // Time window on artifact ts.
+    // Time window on artifact ts, then the message-attribute narrowing. An
+    // artifact that does not carry a dimension never survives that dimension's
+    // filter — asking for an origin excludes every generated turn by itself.
     return out.filter((a) => {
         if (corpus.sinceMs !== undefined && a.tsMs < corpus.sinceMs)
             return false;
         if (corpus.untilMs !== undefined && a.tsMs > corpus.untilMs)
             return false;
-        return true;
+        return matchesMessageFilters(a, corpus);
     });
 }
+/** The transcript/inbox dimensions: origin, role, sender. */
+function matchesMessageFilters(a, corpus) {
+    const { origins, roles, from } = corpus;
+    if (origins !== undefined && origins.length > 0) {
+        if (a.origin === undefined || !origins.includes(a.origin))
+            return false;
+    }
+    if (roles !== undefined && roles.length > 0) {
+        if (a.role === undefined || !roles.includes(a.role))
+            return false;
+    }
+    if (from !== undefined && from !== '') {
+        if (a.from === undefined || !a.from.toLowerCase().includes(from.toLowerCase()))
+            return false;
+    }
+    return true;
+}
+/** Collapse a built corpus into counts by one dimension, descending by count.
+ *  Artifacts that do not carry the grouped dimension are omitted rather than
+ *  bucketed as empty — grouping by origin answers "what drove arrivals", and a
+ *  generated turn is not an arrival. `unknown` is a real origin value here, not
+ *  a missing one. */
+export function groupCorpus(arts, by) {
+    const counts = new Map();
+    for (const a of arts) {
+        let key;
+        switch (by) {
+            case 'origin':
+                key = a.origin;
+                break;
+            case 'role':
+                key = a.role;
+                break;
+            case 'node':
+                key = `${a.nodeName} (${a.nodeId})`;
+                break;
+            case 'kind':
+                key = a.nodeKind;
+                break;
+            case 'type':
+                key = a.source;
+                break;
+            case 'day':
+                key = a.ts.slice(0, 10) || undefined;
+                break;
+        }
+        if (key === undefined || key === '')
+            continue;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([key, count]) => ({ key, count }))
+        .sort((x, y) => y.count - x.count || x.key.localeCompare(y.key));
+}
 /** Resolve the scope to the node rows in play. */
 function scopedRows(scope) {
     const all = listNodes();
@@ -401,6 +680,44 @@ export function resolveRef(ref) {
             path: null,
         };
     }
+    // `session` addresses the whole conversation; `session/<index>` one message.
+    // `raw` is the verbatim record in both cases — the session file's bytes, or
+    // the one jsonl line that persisted that message.
+    if (relpath === 'session' || relpath.startsWith('session/')) {
+        const file = resolveSessionFile(nodeId);
+        if (file === null)
+            return null;
+        const messages = sessionMessages(nodeId);
+        if (relpath === 'session') {
+            const rendered = messages
+                .map((m) => `## ${m.role}${m.origin !== undefined ? ` (origin: ${m.origin})` : ''}\n\n${m.text}`)
+                .join('\n\n');
+            return {
+                nodeId,
+                relpath,
+                source: 'transcript',
+                ts: messages[messages.length - 1]?.ts ?? node.created,
+                nodeName: node.name,
+                body: rendered,
+                raw: readTextIfExists(file),
+                path: file,
+            };
+        }
+        const index = Number(relpath.slice('session/'.length));
+        const msg = messages[index];
+        if (msg === undefined)
+            return null;
+        return {
+            nodeId,
+            relpath,
+            source: 'transcript',
+            ts: msg.ts,
+            nodeName: node.name,
+            body: msg.text,
+            raw: rawSessionLine(file, index),
+            path: file,
+        };
+    }
     if (relpath.includes('..') || relpath.startsWith('/')) {
         throw new Error(`illegal relpath in ref: ${relpath}`);
     }
@@ -501,6 +818,10 @@ export function nodeArtifacts(nodeId, types) {
     if (want.has('inbox')) {
         allInboxEntries(nodeId).forEach((entry, i) => out.push(inboxArtifact(row, desc, entry, i)));
     }
+    if (want.has('transcript')) {
+        for (const msg of sessionMessages(nodeId))
+            out.push(transcriptArtifact(row, desc, msg));
+    }
     return out;
 }
 /** Bounded per-cwd aggregate for the branch `-h` `<corpus>` block. Counts files

package/dist/core/canvas/labels.d.ts

@@ -3,8 +3,8 @@ import type { Mode, NodeMeta } from './types.js';
  *  as a single figure (nf-fa-user, U+F007); an orchestrator reads as a fan-out
  *  hierarchy (nf-fa-sitemap, U+F0E8). */
 export declare function modeIcon(mode: Mode): string;
-/** The minimal shape `fullName` needs — satisfied by NodeMeta and by anything
- *  else carrying name + kind (description optional). */
+/** The minimal shape `fullName` needs — satisfied by NodeMeta, by NodeRow, and
+ *  by anything else carrying name + kind (description optional). */
 export interface NamedNode {
     name: string;
     kind: string;

package/dist/core/canvas/migrations.js

@@ -1329,6 +1329,37 @@ END
 WHERE status IN ('done','canceled','dead') AND terminal_reason IS NULL;
 `);
 }
+/** v38 — mirror the two display-identity fields (`description`, `cycles`) that
+ *  lived ONLY in meta.json onto the row, completing the identity projection the
+ *  row index already is. Before this, every roster read that wanted a node's full
+ *  label had to open and parse each node's meta.json (a per-node disk read on a
+ *  path that already had all the other columns in one query). The backfill reads
+ *  each meta once; from here `upsertRow`/`seedRow` maintain them like any other
+ *  identity column, and `rebuildIndex` re-derives them. */
+function addNodeLabelColumns(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'description', 'ALTER TABLE nodes ADD COLUMN description TEXT;');
+    addNodeColumnIfMissing(db, columns, 'cycles', 'ALTER TABLE nodes ADD COLUMN cycles INTEGER;');
+    const root = nodesRoot();
+    if (!existsSync(root))
+        return;
+    const upd = db.prepare('UPDATE nodes SET description = ?, cycles = ? WHERE node_id = ?');
+    for (const id of readdirSync(root)) {
+        const p = nodeMetaPath(id);
+        if (!existsSync(p))
+            continue;
+        let meta;
+        try {
+            meta = JSON.parse(readFileSync(p, 'utf8'));
+        }
+        catch {
+            continue; // a single unreadable meta never aborts the migration
+        }
+        const description = typeof meta['description'] === 'string' ? meta['description'] : null;
+        const cycles = typeof meta['cycles'] === 'number' ? meta['cycles'] : null;
+        upd.run(description, cycles, id);
+    }
+}
 /** The journaled lane of the state-migration registry, adapted to this chain's
  *  step shape. Registry order is preserved, so these versions stay stable as
  *  long as the registry is append-only (same contract as the local list). */
@@ -1379,6 +1410,7 @@ export const MIGRATIONS = [
     /* v35 */ addNodeLifecycleColumns,
     /* v36 */ makeNodeSessionFileUnique,
     /* v37 */ repairNodeSessionFileUniqueIndex,
+    /* v38 */ addNodeLabelColumns,
     ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not

package/dist/core/canvas/node-recap.d.ts

@@ -0,0 +1,23 @@
+export interface NodeRecap {
+    /** What this conversation is for — the recap's `Goal:` line. */
+    goal: string;
+    /** Where it actually stands — the recap's `State:` line. */
+    state: string;
+    /** ISO 8601 stamp of when the briefing was generated. */
+    at: string;
+}
+/** Split the model's two-line briefing into its labelled halves. Returns null for
+ *  anything that doesn't yield at least one non-empty line — a garbled recap is
+ *  worse than none, so it is never stored. Missing labels fall back to line order
+ *  (the prompt asks for Goal first, State second). */
+export declare function parseRecapBriefing(briefing: string): {
+    goal: string;
+    state: string;
+} | null;
+/** Persist a freshly generated briefing. Best-effort — a write failure only costs
+ *  the browse preview one stale panel, so it must never disturb the broker. */
+export declare function writeNodeRecap(nodeId: string, briefing: string): void;
+/** The node's stored briefing, or undefined when it never generated one (a node
+ *  that finished before its first idle window, or one last run before this file
+ *  existed). Never throws. */
+export declare function readNodeRecap(nodeId: string): NodeRecap | undefined;