@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/session-cycles.d.ts

@@ -0,0 +1,45 @@
+import { type SessionEntry } from '@earendil-works/pi-coding-agent';
+import type { BrokerSnapshot } from './broker-protocol.js';
+/** customType of the persisted tree entry that ROOTS each post-yield cycle.
+ *  Data payload: `{ cycle, fromLeaf }` — `cycle` is the node's cycle counter at
+ *  relaunch, `fromLeaf` the previous cycle's leaf entry id. */
+export declare const CRTR_CYCLE_CUSTOM_TYPE = "crtr-cycle";
+/** customType of the SYNTHETIC divider message spliced between cycles in
+ *  snapshot rendering. Never persisted to the session file. */
+export declare const CRTR_CYCLE_DIVIDER_CUSTOM_TYPE = "crtr-cycle-divider";
+type SnapshotMessage = BrokerSnapshot['messages'][number];
+/** One reconstructed message and the durable session entry that produced it. */
+export type IdentifiedMessage = {
+    id: string;
+    message: SnapshotMessage;
+};
+/** The structural slice of pi's SessionManager cycle rendering needs. The
+ *  broker's fake-engine test fixture implements only `buildSessionContext`, so
+ *  the tree accessors are optional — absent ⇒ single-cycle behavior. */
+export interface CycleSessionManagerLike {
+    buildSessionContext(): {
+        messages: SnapshotMessage[];
+    };
+    getEntries?(): SessionEntry[];
+    /** Walk from `fromId` (default: the current leaf) to its root; returns the
+     *  path root-first. */
+    getBranch?(fromId?: string): SessionEntry[];
+}
+/** True when an assistant turn ended because its own abort fired — an ESC, a
+ *  critical-tier interrupt, or the self-abort a refresh-yield performs. */
+export declare function endedByAbort(message: {
+    stopReason?: string;
+    errorMessage?: string;
+}): boolean;
+/** A refresh-yield deliberately aborts its own turn before the next cycle is
+ * rooted. Preserve that assistant message (including tool calls and prose), but
+ * omit the failure annotation: the cycle divider is the truthful visible seam. */
+export declare function withoutYieldAbort(message: SnapshotMessage): SnapshotMessage;
+/** The full multi-cycle message history for display: prior cycles (oldest
+ *  first, each closed by a divider), then the live cycle's context. Falls back
+ *  to plain `buildSessionContext()` when the session has no cycle markers, when
+ *  the manager lacks tree accessors (fake engine), or when the current leaf was
+ *  tree-navigated back into a pre-yield branch (pi's active-branch semantics
+ *  then apply unchanged). */
+export declare function cycleAwareMessages(sm: CycleSessionManagerLike): IdentifiedMessage[] | undefined;
+export {};

package/dist/core/runtime/session-cycles.js

@@ -0,0 +1,110 @@
+// Cycle-aware session history — one node, one `.jsonl`, many cycles.
+//
+// A refresh-yield does not start a new session file: reviveNode reuses the
+// node's existing `.jsonl` (buildPiArgv's `--crtr-new-cycle`), and the broker
+// resets the session-tree leaf, appending a `crtr-cycle` custom entry as the
+// new cycle's ROOT. Custom entries never participate in LLM context, so the
+// refreshed window is exactly as clean as a brand-new session — but every
+// cycle lives in the same tree as a sibling root branch, so the /tree
+// navigator shows previous cycles natively.
+//
+// `cycleAwareMessages()` is the display-side counterpart: it rebuilds the FULL
+// node history — each prior cycle's messages (via pi's own `buildSessionContext`,
+// so a compacted prior cycle renders correctly), a synthetic divider message per
+// boundary, then the live cycle's context — so the broker welcome snapshot
+// (broker.ts) and the dormant snapshot (node-snapshot.ts) both render one
+// continuous conversation.
+import { buildContextEntries, sessionEntryToContextMessages, } from '@earendil-works/pi-coding-agent';
+/** customType of the persisted tree entry that ROOTS each post-yield cycle.
+ *  Data payload: `{ cycle, fromLeaf }` — `cycle` is the node's cycle counter at
+ *  relaunch, `fromLeaf` the previous cycle's leaf entry id. */
+export const CRTR_CYCLE_CUSTOM_TYPE = 'crtr-cycle';
+/** customType of the SYNTHETIC divider message spliced between cycles in
+ *  snapshot rendering. Never persisted to the session file. */
+export const CRTR_CYCLE_DIVIDER_CUSTOM_TYPE = 'crtr-cycle-divider';
+function cycleDivider(cycle, timestamp) {
+    const label = cycle !== undefined ? `cycle ${cycle}` : 'new cycle';
+    return {
+        role: 'custom',
+        customType: CRTR_CYCLE_DIVIDER_CUSTOM_TYPE,
+        content: `yielded — ${label} begins with a fresh context window`,
+        display: true,
+        timestamp: new Date(timestamp).getTime(),
+    };
+}
+/** Text a provider attaches when the request's own AbortSignal fired. Pi's
+ *  providers stamp `stopReason: 'aborted'` when they observe the signal
+ *  themselves, but an abort that lands while the next request is starting
+ *  reaches their catch as a bare AbortError instead, and is recorded as
+ *  `stopReason: 'error'` carrying this text. Both spellings are the same healthy
+ *  event — a turn that stopped because something asked it to stop. */
+const ABORT_ERROR_TEXT = /\b(?:request|operation) was aborted\b|\bthe user aborted\b/i;
+/** True when an assistant turn ended because its own abort fired — an ESC, a
+ *  critical-tier interrupt, or the self-abort a refresh-yield performs. */
+export function endedByAbort(message) {
+    if (message.stopReason === 'aborted')
+        return true;
+    return message.stopReason === 'error' && ABORT_ERROR_TEXT.test(message.errorMessage ?? '');
+}
+/** A refresh-yield deliberately aborts its own turn before the next cycle is
+ * rooted. Preserve that assistant message (including tool calls and prose), but
+ * omit the failure annotation: the cycle divider is the truthful visible seam. */
+export function withoutYieldAbort(message) {
+    if (message.role !== 'assistant' || !endedByAbort(message))
+        return message;
+    const { stopReason: _stopReason, errorMessage: _errorMessage, ...visible } = message;
+    return visible;
+}
+function identifiedContextMessages(entries, leafId, byId) {
+    return buildContextEntries(entries, leafId, byId).flatMap((entry) => sessionEntryToContextMessages(entry).map((message) => ({ id: entry.id, message: message })));
+}
+function priorCycleMessages(messages) {
+    const last = messages.at(-1);
+    return last === undefined
+        ? messages
+        : [...messages.slice(0, -1), { ...last, message: withoutYieldAbort(last.message) }];
+}
+/** The full multi-cycle message history for display: prior cycles (oldest
+ *  first, each closed by a divider), then the live cycle's context. Falls back
+ *  to plain `buildSessionContext()` when the session has no cycle markers, when
+ *  the manager lacks tree accessors (fake engine), or when the current leaf was
+ *  tree-navigated back into a pre-yield branch (pi's active-branch semantics
+ *  then apply unchanged). */
+export function cycleAwareMessages(sm) {
+    if (typeof sm.getEntries !== 'function' || typeof sm.getBranch !== 'function')
+        return undefined;
+    // File order = append order = chronological cycle order.
+    const entries = sm.getEntries();
+    const byId = new Map(entries.map((e) => [e.id, e]));
+    const currentBranch = sm.getBranch();
+    const current = identifiedContextMessages(entries, currentBranch.at(-1)?.id ?? null, byId);
+    const markers = entries.filter((e) => e.type === 'custom' && e.customType === CRTR_CYCLE_CUSTOM_TYPE);
+    if (markers.length === 0)
+        return current;
+    // The current cycle's root: first entry on the leaf→root path. When it is
+    // not a cycle marker, the leaf sits in the ORIGINAL (pre-yield) branch —
+    // render just that branch. Otherwise replay every cycle up to and including
+    // the one the marker closes.
+    const currentRootId = currentBranch[0]?.id;
+    const rootMarkerIndex = markers.findIndex((m) => m.id === currentRootId);
+    if (rootMarkerIndex === -1)
+        return current;
+    const out = [];
+    for (let i = 0; i <= rootMarkerIndex; i++) {
+        const marker = markers[i];
+        const fromLeaf = marker.data?.fromLeaf;
+        if (typeof fromLeaf === 'string' && fromLeaf !== '') {
+            // Replay this prior cycle's own branch through pi's canonical context
+            // builder — preserving compaction semantics (one compactionSummary +
+            // kept + post-compaction messages only) exactly like the live cycle
+            // below.
+            out.push(...priorCycleMessages(identifiedContextMessages(entries, fromLeaf, byId)));
+        }
+        out.push({
+            id: `${marker.id}~divider`,
+            message: cycleDivider(marker.data?.cycle, marker.timestamp),
+        });
+    }
+    out.push(...current);
+    return out;
+}

package/dist/core/runtime/session-list-cache.d.ts

@@ -0,0 +1,37 @@
+import type { WireSessionInfo } from './broker-protocol.js';
+export declare function compactSessionSearchText(text: string): string;
+/** In-memory + file-backed cache keyed by absolute `.jsonl` path. One instance
+ *  per broker; the file is shared across brokers (last-writer-wins via atomic
+ *  rename — a lost update just costs one file's rebuild next open, never
+ *  corruption). */
+export declare class SessionListCache {
+    private readonly cacheFile;
+    private cache;
+    /** Share concurrent scans for the same cwd. */
+    private inflightDir;
+    private loadPromise;
+    private buildChain;
+    private persisting;
+    private persistAgain;
+    private persistTimer;
+    constructor(cacheFile: string);
+    /** Sessions in the picker's current cwd. */
+    listDir(cwd: string): Promise<WireSessionInfo[]>;
+    private buildDir;
+    /** Sessions across every cwd (`all` scope). */
+    listAll(): Promise<WireSessionInfo[]>;
+    /** Serialize cwd and all-scope cache mutations. */
+    private build;
+    private buildLocked;
+    /** Load the persisted cache exactly once, single-flight. Returns a shared
+     *  promise so a build that starts while the read is still in flight awaits the
+     *  same load rather than proceeding against a not-yet-populated map. */
+    private ensureLoaded;
+    private loadFromDisk;
+    /** Coalesce persists onto a single trailing timer so the tens-of-MB
+     *  `JSON.stringify` never runs on the reply path and rapid opens write once. */
+    private schedulePersist;
+    /** Atomic write (temp + rename) so a concurrent reader never sees a partial
+     *  file. Coalesces overlapping writes into one trailing flush. */
+    private persist;
+}

package/dist/core/runtime/session-list-cache.js

@@ -0,0 +1,302 @@
+// Broker-side cache for the `/resume` session picker's `list_sessions` reply.
+//
+// Cache conversations by (mtime, size) so the picker rebuilds search text only
+// for conversations changed since its last open. The cache survives broker
+// restarts and stores bounded search text for the viewer.
+import { readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { conversationStore, ConversationNotFoundError } from '../conversation-store/index.js';
+/** Search-text bound: `allMessagesText` is searched on every query edit; pi's
+ *  unbounded value retains gigabytes in the viewer and turns key-repeat into GC
+ *  jitter. The opening and latest text keep search useful. */
+const SESSION_SEARCH_TEXT_CHARS = 1024;
+export function compactSessionSearchText(text) {
+    if (text.length <= SESSION_SEARCH_TEXT_CHARS)
+        return text;
+    const half = SESSION_SEARCH_TEXT_CHARS / 2;
+    return `${text.slice(0, half)} … ${text.slice(-half)}`;
+}
+/** Persisted-file schema version. Bump whenever `CacheEntry`'s shape (or
+ *  `WireSessionInfo`'s) changes: on a version mismatch the whole file is
+ *  discarded and rebuilt from disk — no per-entry migration, no lenient
+ *  recovery (the cache is fully derivable). */
+const CACHE_SCHEMA_VERSION = 1;
+/** The full map is tens of MB (~15 MB for one cwd, ~46 MB for `all`); a
+ *  synchronous `JSON.stringify` of it must never sit on the reply path. Persists
+ *  are coalesced onto this trailing timer so rapid opens write at most once per
+ *  window, off the hot path. */
+const PERSIST_DEBOUNCE_MS = 2000;
+function isFiniteNonNeg(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0;
+}
+/** An optional field is valid iff absent/undefined or a string. */
+function isOptionalString(v) {
+    return v === undefined || typeof v === 'string';
+}
+/** Validate the full persisted `WireSessionInfo` shape. A same-version file whose
+ *  entry drifts from the current wire schema (any required field missing or
+ *  mistyped, any optional field the wrong type, non-finite/negative metadata)
+ *  must discard the whole cache and rebuild rather than feed a malformed entry to
+ *  the viewer or the sort. */
+function isValidWireInfo(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const i = v;
+    return (typeof i['path'] === 'string' &&
+        typeof i['id'] === 'string' &&
+        typeof i['cwd'] === 'string' &&
+        typeof i['created'] === 'string' &&
+        typeof i['modified'] === 'string' &&
+        isFiniteNonNeg(i['messageCount']) &&
+        typeof i['firstMessage'] === 'string' &&
+        typeof i['allMessagesText'] === 'string' &&
+        isOptionalString(i['name']) &&
+        isOptionalString(i['parentSessionPath']));
+}
+/** Shape-check a loaded entry — a well-formed-JSON file with the right version
+ *  but a stale entry shape would otherwise feed a malformed `WireSessionInfo` to
+ *  the viewer/sort. Any failure discards the whole file (rebuild). */
+function isValidEntry(e) {
+    if (typeof e !== 'object' || e === null)
+        return false;
+    const c = e;
+    return isFiniteNonNeg(c['mtimeMs']) && isFiniteNonNeg(c['size']) && isValidWireInfo(c['info']);
+}
+// faithful mirror of pi's private buildSessionInfo
+function extractTextContent(message) {
+    const content = message['content'];
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join(' ');
+}
+function messageActivityTime(entry) {
+    const message = entry['message'];
+    if (!message || !('content' in message))
+        return undefined;
+    const role = message['role'];
+    if (role !== 'user' && role !== 'assistant')
+        return undefined;
+    const ts = message['timestamp'];
+    if (typeof ts === 'number')
+        return ts;
+    const t = new Date(entry['timestamp']).getTime();
+    return Number.isNaN(t) ? undefined : t;
+}
+/** Build one session's wire info. A conversation deleted after listing is omitted. */
+async function buildWireSessionInfo(info) {
+    try {
+        const header = info.header;
+        let messageCount = 0;
+        let firstMessage = '';
+        const allMessages = [];
+        let name;
+        let lastActivityTime;
+        for (const entry of (await conversationStore().read(info.conversation_id)).entries) {
+            if (entry['type'] === 'session_info') {
+                name = entry['name']?.trim() || undefined;
+            }
+            if (entry['type'] !== 'message')
+                continue;
+            messageCount++;
+            const activityTime = messageActivityTime(entry);
+            if (typeof activityTime === 'number') {
+                lastActivityTime = Math.max(lastActivityTime ?? 0, activityTime);
+            }
+            const message = entry['message'];
+            if (!message || !('content' in message))
+                continue;
+            const role = message['role'];
+            if (role !== 'user' && role !== 'assistant')
+                continue;
+            const textContent = extractTextContent(message);
+            if (!textContent)
+                continue;
+            allMessages.push(textContent);
+            if (!firstMessage && role === 'user')
+                firstMessage = textContent;
+        }
+        const cwd = typeof header['cwd'] === 'string' ? header['cwd'] : '';
+        const headerTime = typeof header['timestamp'] === 'string' ? new Date(header['timestamp']).getTime() : NaN;
+        const modified = typeof lastActivityTime === 'number' && lastActivityTime > 0
+            ? new Date(lastActivityTime)
+            : !Number.isNaN(headerTime)
+                ? new Date(headerTime)
+                : new Date(info.mtime);
+        return {
+            path: info.path,
+            id: header['id'],
+            cwd,
+            name,
+            parentSessionPath: header['parentSession'],
+            created: new Date(header['timestamp']).toISOString(),
+            modified: modified.toISOString(),
+            messageCount,
+            firstMessage: firstMessage || '(no messages)',
+            // Cache the already-bounded wire form (the selector searches this field).
+            allMessagesText: compactSessionSearchText(allMessages.join(' ')),
+        };
+    }
+    catch (error) {
+        if (error instanceof ConversationNotFoundError)
+            return null;
+        throw error;
+    }
+}
+// the cache
+/** In-memory + file-backed cache keyed by absolute `.jsonl` path. One instance
+ *  per broker; the file is shared across brokers (last-writer-wins via atomic
+ *  rename — a lost update just costs one file's rebuild next open, never
+ *  corruption). */
+export class SessionListCache {
+    cacheFile;
+    cache = new Map();
+    /** Share concurrent scans for the same cwd. */
+    inflightDir = new Map();
+    loadPromise = null;
+    buildChain = Promise.resolve();
+    persisting = false;
+    persistAgain = false;
+    persistTimer = null;
+    constructor(cacheFile) {
+        this.cacheFile = cacheFile;
+    }
+    /** Sessions in the picker's current cwd. */
+    listDir(cwd) {
+        const key = resolve(cwd);
+        const existing = this.inflightDir.get(key);
+        if (existing)
+            return existing;
+        const op = Promise.resolve().then(() => this.buildDir(key));
+        this.inflightDir.set(key, op);
+        // Clear on success or rejection so a failed scan cannot poison the next open.
+        const clear = () => {
+            if (this.inflightDir.get(key) === op)
+                this.inflightDir.delete(key);
+        };
+        op.then(clear, clear);
+        return op;
+    }
+    async buildDir(cwd) {
+        const conversations = (await conversationStore().list()).filter((info) => info.header.cwd === cwd);
+        return this.build(conversations, (key) => this.cache.get(key)?.info.cwd === cwd);
+    }
+    /** Sessions across every cwd (`all` scope). */
+    async listAll() {
+        return this.build(await conversationStore().list(), () => true);
+    }
+    /** Serialize cwd and all-scope cache mutations. */
+    build(conversations, shouldPrune) {
+        const run = this.buildChain.then(() => this.buildLocked(conversations, shouldPrune));
+        // Keep the chain alive past a rejected build without leaking the rejection.
+        this.buildChain = run.then(() => { }, () => { });
+        return run;
+    }
+    async buildLocked(conversations, shouldPrune) {
+        await this.ensureLoaded();
+        const present = new Set(conversations.map(({ path }) => path));
+        let changed = false;
+        for (const key of this.cache.keys()) {
+            if (!present.has(key) && shouldPrune(key)) {
+                this.cache.delete(key);
+                changed = true;
+            }
+        }
+        // Preserve the store list order when modified timestamps tie.
+        const infos = new Array(conversations.length);
+        for (const [i, conversation] of conversations.entries()) {
+            const cached = this.cache.get(conversation.path);
+            if (cached && cached.mtimeMs === conversation.mtime && cached.size === conversation.size) {
+                infos[i] = cached.info;
+                continue;
+            }
+            const info = await buildWireSessionInfo(conversation);
+            changed = true;
+            if (!info) {
+                this.cache.delete(conversation.path);
+                continue;
+            }
+            this.cache.set(conversation.path, { mtimeMs: conversation.mtime, size: conversation.size, info });
+            infos[i] = info;
+        }
+        if (changed)
+            this.schedulePersist();
+        const result = infos.filter((x) => x !== undefined);
+        result.sort((a, b) => new Date(b.modified).getTime() - new Date(a.modified).getTime());
+        return result;
+    }
+    /** Load the persisted cache exactly once, single-flight. Returns a shared
+     *  promise so a build that starts while the read is still in flight awaits the
+     *  same load rather than proceeding against a not-yet-populated map. */
+    ensureLoaded() {
+        if (!this.loadPromise)
+            this.loadPromise = this.loadFromDisk();
+        return this.loadPromise;
+    }
+    async loadFromDisk() {
+        try {
+            const raw = JSON.parse(await readFile(this.cacheFile, 'utf8'));
+            // Version mismatch or shape drift → discard and rebuild. No lenient
+            // multi-path recovery: the cache is derivable, so a bad file is just
+            // overwritten on the next persist.
+            if (raw?.version !== CACHE_SCHEMA_VERSION || typeof raw.entries !== 'object')
+                return;
+            for (const [path, entry] of Object.entries(raw.entries)) {
+                if (!isValidEntry(entry)) {
+                    this.cache.clear();
+                    return;
+                }
+                this.cache.set(path, entry);
+            }
+        }
+        catch {
+            // Missing or corrupt cache file → start empty and rebuild.
+            this.cache.clear();
+        }
+    }
+    /** Coalesce persists onto a single trailing timer so the tens-of-MB
+     *  `JSON.stringify` never runs on the reply path and rapid opens write once. */
+    schedulePersist() {
+        if (this.persistTimer)
+            return;
+        this.persistTimer = setTimeout(() => {
+            this.persistTimer = null;
+            void this.persist();
+        }, PERSIST_DEBOUNCE_MS);
+        this.persistTimer.unref?.();
+    }
+    /** Atomic write (temp + rename) so a concurrent reader never sees a partial
+     *  file. Coalesces overlapping writes into one trailing flush. */
+    async persist() {
+        if (this.persisting) {
+            this.persistAgain = true;
+            return;
+        }
+        this.persisting = true;
+        const tmp = `${this.cacheFile}.${process.pid}.tmp`;
+        try {
+            const entries = {};
+            for (const [path, entry] of this.cache)
+                entries[path] = entry;
+            const payload = { version: CACHE_SCHEMA_VERSION, entries };
+            await writeFile(tmp, JSON.stringify(payload));
+            await rename(tmp, this.cacheFile);
+        }
+        catch {
+            // Best-effort: a failed persist only costs a rebuild next open. Clean up
+            // the temp file so a failed write never leaks it.
+            await unlink(tmp).catch(() => { });
+        }
+        finally {
+            this.persisting = false;
+            if (this.persistAgain) {
+                this.persistAgain = false;
+                void this.persist();
+            }
+        }
+    }
+}

package/dist/core/runtime/session-visibility.d.ts

@@ -0,0 +1,37 @@
+import type { WireSessionTreeNode } from './broker-protocol.js';
+import type { IdentifiedMessage } from './session-cycles.js';
+import { type MessageVisibility } from './stamp/protocol.js';
+import { REVIEW_BOUNDARY_CUSTOM_TYPE } from '../../shared/generated-context.js';
+export { REVIEW_BOUNDARY_CUSTOM_TYPE };
+export type ProjectedMessage = IdentifiedMessage & {
+    visibility: MessageVisibility;
+};
+/** True when an entry is a durable review boundary, optionally for one review. */
+export declare function isReviewBoundary(entry: unknown, reviewId?: string): boolean;
+/**
+ * Project identified snapshot messages for transcript presentation.
+ *
+ * Every retained message carries its durable visibility classification. A
+ * companion then passes its binding's review id so its slice starts at ITS OWN
+ * boundary marker: a node forked from another companion inherits that
+ * companion's earlier marker, and slicing at the first marker of any review
+ * would reveal the origin companion's transcript.
+ */
+export declare function projectTranscript(messages: IdentifiedMessage[], opts: {
+    boundaryReviewId: string | undefined;
+    sessionEntries?: readonly unknown[];
+}): ProjectedMessage[];
+/**
+ * Project a session tree to the review companion's visible transcript boundary.
+ *
+ * Pre-boundary ancestors are omitted rather than retained as empty structural
+ * shells, making each durable boundary a root in the returned forest. Once a
+ * boundary is crossed, its complete descendant subtree remains navigable. An
+ * absent boundary produces an empty tree, so picker previews never disclose an
+ * inherited entry before a mutation guard can reject its selection.
+ *
+ * `boundaryReviewId` selects only this binding's marker as a root, so a
+ * companion forked from another companion never navigates into the inherited
+ * subtree rooted at the origin's earlier marker.
+ */
+export declare function boundaryRootedTree(tree: readonly WireSessionTreeNode[], boundaryReviewId?: string): WireSessionTreeNode[];

package/dist/core/runtime/session-visibility.js

@@ -0,0 +1,99 @@
+// session-visibility.ts — the transcript projection shared by live and dormant
+// reads. Raw session entries remain authoritative; durable stamps and review
+// boundaries select which reconstructed messages a person can see.
+import { readStamps, STAMP_SCHEMA_VERSION, } from './stamp/protocol.js';
+import { REVIEW_BOUNDARY_CUSTOM_TYPE } from '../../shared/generated-context.js';
+export { REVIEW_BOUNDARY_CUSTOM_TYPE };
+/** True when an entry is a durable review boundary, optionally for one review. */
+export function isReviewBoundary(entry, reviewId) {
+    if (entry === null || typeof entry !== 'object')
+        return false;
+    const candidate = entry;
+    return ((candidate.role === 'custom' || candidate.type === 'custom_message') &&
+        candidate.customType === REVIEW_BOUNDARY_CUSTOM_TYPE &&
+        (reviewId === undefined || candidate.details?.reviewId === reviewId));
+}
+function syntheticBoundary(timestamp) {
+    return {
+        role: 'custom',
+        customType: REVIEW_BOUNDARY_CUSTOM_TYPE,
+        content: 'Earlier conversation with the origin is not shown.',
+        display: true,
+        timestamp: timestamp ?? Date.now(),
+    };
+}
+function classifyMessages(messages, sessionEntries) {
+    const internalByTimestamp = new Map();
+    for (const stamp of readStamps(sessionEntries ?? [])) {
+        if (stamp.kind !== 'message' || stamp.v !== STAMP_SCHEMA_VERSION)
+            continue;
+        const payload = stamp.payload;
+        if (typeof payload.msgTs !== 'number')
+            continue;
+        // Last stamp wins, matching every other message-stamp reader.
+        internalByTimestamp.set(payload.msgTs, payload.visibility === 'internal');
+    }
+    let visibility = 'visible';
+    return messages.map((identified) => {
+        const { message } = identified;
+        if (message.role === 'user') {
+            visibility = typeof message.timestamp === 'number'
+                && internalByTimestamp.get(message.timestamp) === true
+                ? 'internal'
+                : 'visible';
+        }
+        return { ...identified, visibility };
+    });
+}
+/**
+ * Project identified snapshot messages for transcript presentation.
+ *
+ * Every retained message carries its durable visibility classification. A
+ * companion then passes its binding's review id so its slice starts at ITS OWN
+ * boundary marker: a node forked from another companion inherits that
+ * companion's earlier marker, and slicing at the first marker of any review
+ * would reveal the origin companion's transcript.
+ */
+export function projectTranscript(messages, opts) {
+    const projected = classifyMessages(messages, opts.sessionEntries);
+    const markerIndex = projected.findIndex(({ message }) => isReviewBoundary(message, opts.boundaryReviewId));
+    if (markerIndex !== -1)
+        return projected.slice(markerIndex);
+    if (opts.boundaryReviewId === undefined)
+        return projected;
+    const [first, ...retainedTail] = projected;
+    const boundary = {
+        id: '~boundary',
+        message: syntheticBoundary(first?.message.timestamp),
+        visibility: 'visible',
+    };
+    if (first?.message.role === 'compactionSummary') {
+        return [boundary, ...retainedTail];
+    }
+    return [boundary];
+}
+/**
+ * Project a session tree to the review companion's visible transcript boundary.
+ *
+ * Pre-boundary ancestors are omitted rather than retained as empty structural
+ * shells, making each durable boundary a root in the returned forest. Once a
+ * boundary is crossed, its complete descendant subtree remains navigable. An
+ * absent boundary produces an empty tree, so picker previews never disclose an
+ * inherited entry before a mutation guard can reject its selection.
+ *
+ * `boundaryReviewId` selects only this binding's marker as a root, so a
+ * companion forked from another companion never navigates into the inherited
+ * subtree rooted at the origin's earlier marker.
+ */
+export function boundaryRootedTree(tree, boundaryReviewId) {
+    const retainSubtree = (node) => ({
+        ...node,
+        children: node.children.map(retainSubtree),
+    });
+    const project = (node) => {
+        if (isReviewBoundary(node.entry, boundaryReviewId))
+            return [retainSubtree(node)];
+        return node.children.flatMap(project);
+    };
+    return tree.flatMap(project);
+}

package/dist/core/runtime/setup-marker.d.ts

@@ -0,0 +1,8 @@
+export declare function setupCompleted(): boolean;
+/** Record a finished setup run. A first setup leaves the tutorial offer
+ *  pending; a re-run keeps whatever the earlier marker said about it. */
+export declare function recordSetupCompleted(outcome: 'completed' | 'skipped'): Promise<void>;
+/** True while setup has run but no root has booted since. */
+export declare function tourOfferPending(): Promise<boolean>;
+/** The root that carries the offer is booting; never offer it again. */
+export declare function markTourOffered(): Promise<void>;