@north-light/api 0.3.561 → 0.3.562

package/dist/core/conversation-store/client.js

@@ -0,0 +1,111 @@
+import { MessageChannel, Worker, receiveMessageOnPort } from 'node:worker_threads';
+import { ConversationNotFoundError } from './index.js';
+export function createStoreClient(address, token) {
+    const worker = new Worker(new URL(import.meta.url.endsWith('.ts') ? './client-worker.ts' : './client-worker.js', import.meta.url), { workerData: { address, token } });
+    worker.unref();
+    let workerFailure;
+    worker.on('error', (error) => { workerFailure = error; });
+    worker.on('exit', (code) => { workerFailure = new Error(`conversation store worker exited with ${code}`); });
+    function settle(method, path, reply) {
+        if (!reply)
+            throw new Error('conversation store worker returned no reply');
+        if (reply.error)
+            throw new Error(reply.error);
+        if (reply.status === 404)
+            throw new ConversationNotFoundError(path.split('/')[2] ?? path);
+        if (!reply.status || reply.status >= 400)
+            throw new Error(`conversation store ${method} ${path} failed (${reply.status}): ${reply.body}`);
+        return { body: reply.body ?? '', ...(reply.path ? { path: reply.path } : {}), ...(reply.tail ? { tail: Number(reply.tail) } : {}) };
+    }
+    function call(method, path, data) {
+        if (workerFailure)
+            throw workerFailure;
+        const signal = new SharedArrayBuffer(4);
+        const { port1, port2 } = new MessageChannel();
+        try {
+            worker.postMessage({ method, path, data, signal, reply: port2 }, [port2]);
+            const result = Atomics.wait(new Int32Array(signal), 0, 0, 30_000);
+            if (result === 'timed-out') {
+                port1.postMessage('cancel');
+                throw new Error(`conversation store request timed out: ${method} ${path}`);
+            }
+            return settle(method, path, receiveMessageOnPort(port1)?.message);
+        }
+        finally {
+            port1.close();
+        }
+    }
+    /** The same request without parking the calling thread: an interactive surface keeps
+     *  handling input while the worker waits on the store. */
+    function callAsync(method, path) {
+        if (workerFailure)
+            return Promise.reject(workerFailure);
+        const { port1, port2 } = new MessageChannel();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { port1.postMessage('cancel'); port1.close(); reject(new Error(`conversation store request timed out: ${method} ${path}`)); }, 30_000);
+            timer.unref();
+            port1.once('message', (reply) => {
+                clearTimeout(timer);
+                port1.close();
+                try {
+                    resolve(settle(method, path, reply));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            worker.postMessage({ method, path, reply: port2 }, [port2]);
+        });
+    }
+    const url = (id) => `/conversations/${encodeURIComponent(id)}`;
+    function enqueueAppend(id, entries) {
+        if (workerFailure)
+            throw workerFailure;
+        worker.postMessage({ kind: 'append', method: 'POST', path: `${url(id)}/entries`, data: { entries } });
+    }
+    function flush() {
+        if (workerFailure)
+            return Promise.reject(workerFailure);
+        const { port1, port2 } = new MessageChannel();
+        return new Promise((resolve, reject) => {
+            port1.once('message', (reply) => {
+                port1.close();
+                try {
+                    settle('POST', '/commit', reply);
+                    resolve();
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            worker.postMessage({ kind: 'flush', method: 'POST', path: '/commit', reply: port2 }, [port2]);
+        });
+    }
+    const parseRead = (reply) => {
+        const [header, ...rest] = reply.body.trimEnd().split('\n').map((line) => JSON.parse(line));
+        const entries = rest;
+        if (reply.tail === undefined)
+            return { header: header, entries, path: reply.path ?? '' };
+        return { header: header, entries: entries.slice(0, reply.tail - 1), tail: entries.slice(reply.tail - 1), path: reply.path ?? '' };
+    };
+    const readPath = (id, window) => window ? `${url(id)}?head=${window.head}&tail=${window.tail}` : url(id);
+    return {
+        create(nodeId, header, entries, path) {
+            return JSON.parse(call('POST', '/conversations', { node_id: nodeId, header, entries, path }).body).conversation_id;
+        },
+        append(id, entries) { enqueueAppend(id, entries); },
+        flush,
+        replace(id, header, entries) { call('PUT', url(id), { header, entries }); },
+        read(id, window) { return parseRead(call('GET', readPath(id, window))); },
+        async readAsync(id, window) { return parseRead(await callAsync('GET', readPath(id, window))); },
+        header(id) { return JSON.parse(call('GET', `${url(id)}/header`).body); },
+        fork(id, nodeId, leafId, cwd) {
+            return JSON.parse(call('POST', `${url(id)}/fork`, { node_id: nodeId, leaf_id: leafId, cwd }).body).conversation_id;
+        },
+        list(nodeId) {
+            const query = nodeId === undefined ? '' : `?node_id=${encodeURIComponent(nodeId)}`;
+            return JSON.parse(call('GET', `/conversations${query}`).body).conversations;
+        },
+        delete(id) { call('DELETE', url(id)); },
+    };
+}

package/dist/core/conversation-store/index.d.ts

@@ -0,0 +1,96 @@
+import type { SessionEntry, SessionHeader } from '@earendil-works/pi-coding-agent';
+export type { SessionEntry, SessionHeader };
+export declare class ConversationNotFoundError extends Error {
+    readonly code = "not_found";
+    constructor(id: string);
+}
+export declare function isConversationNotFound(error: unknown): boolean;
+export interface ConversationInfo {
+    conversation_id: string;
+    node_id?: string;
+    header: SessionHeader;
+    mtime: number;
+    size: number;
+    path: string;
+}
+/** Byte budgets for a bounded read of a conversation's two ends. */
+export interface ConversationWindow {
+    head: number;
+    tail: number;
+}
+/** The synchronous shape pi's `SessionManager` statics need (`patch.ts`). The broker's client
+ *  (`client.ts`: an `Atomics.wait` worker, no db) implements it. It is declared apart from
+ *  `ConversationStore` so a change to the daemon's store never changes pi's contract. */
+export interface ConversationStoreClient {
+    create(nodeId: string, header: SessionHeader, entries: SessionEntry[], path?: string): string;
+    /** Enqueue entries in order without blocking the broker's event loop. */
+    append(id: string, entries: SessionEntry[]): void;
+    /** Wait for pending appends and seal each dirty conversation. */
+    flush(): Promise<void>;
+    replace(id: string, header: SessionHeader, entries: SessionEntry[]): void;
+    /** Given a window and a file larger than head + tail bytes, `entries` holds the entries wholly
+     *  inside the first `head` bytes and `tail` those wholly inside the last `tail` bytes.
+     *  Otherwise `entries` is the whole conversation and `tail` is absent. */
+    read(id: string, window?: ConversationWindow): {
+        header: SessionHeader;
+        entries: SessionEntry[];
+        tail?: SessionEntry[];
+        path: string;
+    };
+    /** `read` without blocking the calling thread. Stores that read in-process may omit it;
+     *  use `readConversationAsync`, which falls back to `read`. */
+    readAsync?(id: string, window?: ConversationWindow): Promise<ReturnType<ConversationStoreClient['read']>>;
+    header(id: string): {
+        header: SessionHeader;
+        mtime: number;
+        size: number;
+        path: string;
+    };
+    fork(id: string, nodeId?: string, leafId?: string, cwd?: string): string;
+    list(nodeId?: string): ConversationInfo[];
+    delete(id: string): void;
+}
+/** The daemon's file store (`createFileStore`, installed by `sessions.ts`). */
+export interface ConversationStore {
+    create(nodeId: string, header: SessionHeader, entries: SessionEntry[], path?: string): Promise<string>;
+    append(id: string, entries: SessionEntry[]): Promise<void>;
+    replace(id: string, header: SessionHeader, entries: SessionEntry[]): Promise<void>;
+    read(id: string, window?: ConversationWindow): Promise<{
+        header: SessionHeader;
+        entries: SessionEntry[];
+        tail?: SessionEntry[];
+        path: string;
+    }>;
+    /** Stream a complete conversation without blocking the daemon on a full-file read. */
+    readLines?(id: string): Promise<{
+        path: string;
+        lines: AsyncIterable<string>;
+    }>;
+    header(id: string): Promise<{
+        header: SessionHeader;
+        mtime: number;
+        size: number;
+        path: string;
+    }>;
+    fork(id: string, nodeId?: string, leafId?: string, cwd?: string): Promise<string>;
+    list(nodeId?: string): Promise<ConversationInfo[]>;
+    /** `path` names the transcript when its sessions row is already gone (the in-process store only;
+     *  the socket client resolves from the row and ignores it). A file already missing there is not an error. */
+    delete(id: string, path?: string): Promise<void>;
+}
+export declare function conversationIdFromPath(path: string): string | null;
+export declare function defaultConversationRoot(): string;
+/** Where the client reaches the daemon's /v1 API: `CRTR_API_URL` (an http(s) URL) or the API socket path. */
+export declare function conversationApiAddress(): string;
+export declare function installConversationStore(store: ConversationStore | undefined): void;
+/** The installed store, else the client over the store socket with each call awaited. */
+export declare function conversationStore(): ConversationStore;
+/** The synchronous store pi's `SessionManager` statics call: always the client over the store socket (the installed
+ *  store is async, so it cannot serve a synchronous caller). */
+export declare function conversationClient(): ConversationStoreClient;
+/** The broker settles mail only after its queued entries and part object are durable. */
+export declare function flushConversation(): Promise<void>;
+/** Read a conversation without parking the event loop on the store worker. */
+export declare function readConversationAsync(id: string, window?: ConversationWindow): Promise<Awaited<ReturnType<ConversationStore['read']>>>;
+export { installSessionManagerStorePatch } from './patch.js';
+export { findOrphanedParents, relinkOrphanedParents, repairConversationFile, type FileRepair, type OrphanRelink } from './repair.js';

package/dist/core/conversation-store/index.js

@@ -0,0 +1,62 @@
+import { appsRoot } from '../layout.js';
+import { apiSocketPath } from '../canvas/paths.js';
+import { createStoreClient } from './client.js';
+import { currentNodeToken } from '../runtime/broker/node-token.js';
+export class ConversationNotFoundError extends Error {
+    code = 'not_found';
+    constructor(id) { super(`conversation not found: ${id}`); }
+}
+export function isConversationNotFound(error) {
+    return error instanceof ConversationNotFoundError;
+}
+export function conversationIdFromPath(path) {
+    const match = /(?:^|\/)[^/]+_([0-9a-f-]{36})\.jsonl$/i.exec(path);
+    return match?.[1] ?? null;
+}
+export function defaultConversationRoot() { return appsRoot(); }
+/** Where the client reaches the daemon's /v1 API: `CRTR_API_URL` (an http(s) URL) or the API socket path. */
+export function conversationApiAddress() {
+    return process.env['CRTR_API_URL'] || apiSocketPath();
+}
+let local;
+let remote;
+export function installConversationStore(store) { local = store; }
+/** The installed store, else the client over the store socket with each call awaited. */
+export function conversationStore() {
+    if (local)
+        return local;
+    const client = conversationClient();
+    return {
+        create: async (...args) => client.create(...args),
+        append: async (id, entries) => client.append(id, entries),
+        replace: async (...args) => client.replace(...args),
+        read: async (...args) => client.read(...args),
+        header: async (...args) => client.header(...args),
+        fork: async (...args) => client.fork(...args),
+        list: async (...args) => client.list(...args),
+        delete: async (id) => client.delete(id),
+    };
+}
+/** The synchronous store pi's `SessionManager` statics call: always the client over the store socket (the installed
+ *  store is async, so it cannot serve a synchronous caller). */
+export function conversationClient() {
+    const address = conversationApiAddress();
+    if (remote?.address !== address)
+        remote = { address, store: createStoreClient(address, currentNodeToken()) };
+    return remote.store;
+}
+/** The broker settles mail only after its queued entries and part object are durable. */
+export async function flushConversation() {
+    if (local)
+        return;
+    await conversationClient().flush();
+}
+/** Read a conversation without parking the event loop on the store worker. */
+export async function readConversationAsync(id, window) {
+    if (local)
+        return local.read(id, window);
+    const store = conversationClient();
+    return store.readAsync ? store.readAsync(id, window) : store.read(id, window);
+}
+export { installSessionManagerStorePatch } from './patch.js';
+export { findOrphanedParents, relinkOrphanedParents, repairConversationFile } from './repair.js';

package/dist/core/conversation-store/patch.d.ts

@@ -0,0 +1,3 @@
+import { type ConversationStoreClient } from './index.js';
+/** `store` is the synchronous client pi's `SessionManager` needs: the broker's client over the store socket unless a caller supplies one. */
+export declare function installSessionManagerStorePatch(nodeId: string, store?: ConversationStoreClient): void;

package/dist/core/conversation-store/patch.js

@@ -0,0 +1,192 @@
+import { dirname, resolve } from 'node:path';
+import { SessionManager } from '@earendil-works/pi-coding-agent';
+import { conversationClient, conversationIdFromPath } from './index.js';
+import { findOrphanedParents } from './repair.js';
+import { emitEvent } from '../events/emit.js';
+let installed = false;
+/** `store` is the synchronous client pi's `SessionManager` needs: the broker's client over the store socket unless a caller supplies one. */
+export function installSessionManagerStorePatch(nodeId, store = conversationClient()) {
+    if (installed)
+        return;
+    const prototype = SessionManager.prototype;
+    const statics = SessionManager;
+    for (const name of ['_setSessionFile', '_rewriteFile', '_persist', 'createBranchedSession', 'newSession']) {
+        if (typeof prototype[name] !== 'function')
+            throw new Error(`pi SessionManager.${name} changed; store patch cannot start`);
+    }
+    for (const name of ['create', 'open', 'continueRecent', 'forkFrom', 'findById', 'list', 'listAll']) {
+        if (typeof statics[name] !== 'function')
+            throw new Error(`pi SessionManager.${name} changed; store patch cannot start`);
+    }
+    const originalBranch = prototype.createBranchedSession;
+    const originalNew = prototype.newSession;
+    /** A reload that finds a parent missing from the file would otherwise truncate the branch silently. */
+    function reportOrphans(id, entries) {
+        const orphans = findOrphanedParents(entries);
+        if (orphans.length === 0)
+            return;
+        emitEvent({
+            level: 'error',
+            event: 'conversation.orphaned_parent',
+            fields: { conversation_id: id, orphan_count: orphans.length, orphans: orphans.slice(0, 20).map((o) => ({ entry_id: o.entryId, missing_parent_id: o.missingParentId })) },
+        });
+    }
+    function fromStore(id, cwdOverride) {
+        const { header, entries, path } = store.read(id);
+        reportOrphans(header.id, entries);
+        const manager = SessionManager.inMemory(cwdOverride ?? header.cwd);
+        manager.sessionFile = path;
+        manager.sessionDir = dirname(path);
+        manager._loadEntries([header, ...entries]);
+        manager.persist = true;
+        manager.flushed = true;
+        const loaded = manager.fileEntries[0];
+        if (loaded?.type === 'session' && loaded.version !== header.version)
+            manager._rewriteFile();
+        return manager;
+    }
+    function persistNew(manager) {
+        const [header, ...entries] = manager.fileEntries;
+        if (!header || header.type !== 'session')
+            throw new Error('conversation has no session header');
+        store.create(nodeId, header, entries);
+        manager.sessionFile = store.header(header.id).path;
+        manager.sessionDir = dirname(manager.sessionFile);
+        manager.flushed = true;
+    }
+    function appendInOrder(manager, entry) {
+        store.append(manager.sessionId, [entry]);
+    }
+    function idOf(path) {
+        const id = conversationIdFromPath(path);
+        if (!id)
+            throw new Error(`invalid conversation path: ${path}`);
+        return id;
+    }
+    prototype._setSessionFile = function (path) {
+        const { header, entries } = store.read(idOf(path));
+        this.sessionFile = store.header(header.id).path;
+        this.sessionDir = dirname(this.sessionFile);
+        reportOrphans(header.id, entries);
+        this._loadEntries([header, ...entries]);
+        this.flushed = true;
+    };
+    prototype._rewriteFile = function () {
+        if (!this.persist || !this.sessionFile)
+            return;
+        const [header, ...entries] = this.fileEntries;
+        if (!header || header.type !== 'session')
+            throw new Error('conversation has no session header');
+        store.replace(header.id, header, entries);
+    };
+    prototype._persist = function (entry) {
+        if (!this.persist || !this.sessionFile)
+            return;
+        if (!this.flushed)
+            persistNew(this);
+        else
+            appendInOrder(this, entry);
+    };
+    // Every persisted session exists in the store from creation. pi's runtime creates a
+    // session and immediately starts another (`newSession({ parentSession })` for /new and
+    // root fork), so a still-empty conversation takes the new header under its own id
+    // rather than being left behind; a session with entries stays and a new one is created.
+    prototype.newSession = function (options) {
+        if (!this.persist)
+            return originalNew.call(this, options);
+        const empty = this.flushed && this.fileEntries.length === 1 && this.sessionFile !== undefined ? this.sessionId : undefined;
+        if (empty !== undefined && (options?.id === undefined || options.id === empty)) {
+            const path = this.sessionFile;
+            originalNew.call(this, { ...options, id: empty });
+            const header = this.fileEntries[0];
+            if (!header || header.type !== 'session')
+                throw new Error('conversation has no session header');
+            store.replace(empty, header, []);
+            this.sessionFile = path;
+            this.flushed = true;
+            return path;
+        }
+        originalNew.call(this, options);
+        persistNew(this);
+        return this.sessionFile;
+    };
+    prototype.createBranchedSession = function (leafId) {
+        if (!this.persist)
+            return originalBranch.call(this, leafId);
+        const prior = this.sessionFile;
+        this.persist = false;
+        try {
+            originalBranch.call(this, leafId);
+        }
+        finally {
+            this.persist = true;
+        }
+        const header = this.fileEntries[0];
+        if (!header || header.type !== 'session')
+            throw new Error('branch has no header');
+        this.fileEntries[0] = { ...header, parentSession: prior };
+        persistNew(this);
+        return this.sessionFile;
+    };
+    statics['create'] = (cwd, _sessionDir, options) => {
+        const manager = SessionManager.inMemory(cwd, options);
+        manager.persist = true;
+        persistNew(manager);
+        return manager;
+    };
+    statics['open'] = (path, _sessionDir, cwdOverride) => fromStore(idOf(path), cwdOverride);
+    statics['continueRecent'] = (cwd) => {
+        const latest = store.list().find((info) => info.header.cwd === resolve(cwd));
+        return latest ? fromStore(latest.conversation_id, cwd) : statics['create'](cwd);
+    };
+    statics['forkFrom'] = (path, targetCwd) => fromStore(store.fork(idOf(path), nodeId, undefined, targetCwd));
+    statics['findById'] = (cwd, id) => store.list().find((info) => info.conversation_id === id && info.header.cwd === resolve(cwd))?.path;
+    function sessionInfos(cwd) {
+        return store.list().filter((info) => cwd === undefined || info.header.cwd === resolve(cwd)).map((info) => {
+            let name;
+            let messageCount = 0;
+            let firstMessage = '';
+            let lastActivity;
+            const texts = [];
+            for (const entry of store.read(info.conversation_id).entries) {
+                if (entry.type === 'session_info')
+                    name = entry.name?.trim() || undefined;
+                if (entry.type !== 'message')
+                    continue;
+                messageCount++;
+                const message = entry.message;
+                if (message.role !== 'user' && message.role !== 'assistant')
+                    continue;
+                const at = typeof message.timestamp === 'number' ? message.timestamp : Date.parse(entry.timestamp);
+                if (!Number.isNaN(at))
+                    lastActivity = Math.max(lastActivity ?? 0, at);
+                const text = typeof message.content === 'string' ? message.content
+                    : Array.isArray(message.content) ? message.content.filter((block) => block.type === 'text').map((block) => block.text ?? '').join(' ') : '';
+                if (!text)
+                    continue;
+                texts.push(text);
+                if (!firstMessage && message.role === 'user')
+                    firstMessage = text;
+            }
+            const created = new Date(info.header.timestamp);
+            return {
+                path: info.path, id: info.conversation_id, cwd: info.header.cwd, ...(name ? { name } : {}),
+                ...(info.header.parentSession ? { parentSessionPath: info.header.parentSession } : {}),
+                created, modified: lastActivity && lastActivity > 0 ? new Date(lastActivity) : Number.isNaN(created.getTime()) ? new Date(info.mtime) : created,
+                messageCount, firstMessage: firstMessage || '(no messages)', allMessagesText: texts.join(' '),
+            };
+        });
+    }
+    statics['list'] = async (cwd, _sessionDir, onProgress, signal) => {
+        signal?.throwIfAborted();
+        const sessions = sessionInfos(cwd);
+        onProgress?.(sessions.length, sessions.length, sessions);
+        return sessions;
+    };
+    statics['listAll'] = async (...args) => {
+        const signal = args.find((arg) => arg instanceof AbortSignal);
+        signal?.throwIfAborted();
+        return sessionInfos();
+    };
+    installed = true;
+}

package/dist/core/conversation-store/repair.d.ts

@@ -0,0 +1,45 @@
+/** Pure helpers for conversations whose entries name a `parentId` that is not in the file.
+ *  That shape comes from an append that failed after pi had already advanced its in-memory leaf:
+ *  later entries were written chained onto the entry that never reached the file, and every
+ *  reload then stops walking the parent chain at the gap. */
+import type { SessionEntry, SessionHeader } from '@earendil-works/pi-coding-agent';
+export interface OrphanedParent {
+    /** Index into the entries array (header excluded) of the entry whose parent is missing. */
+    index: number;
+    entryId: string;
+    missingParentId: string;
+}
+/** Entries whose non-null `parentId` is absent from `entries`. */
+export declare function findOrphanedParents(entries: readonly SessionEntry[]): OrphanedParent[];
+export interface OrphanRelink extends OrphanedParent {
+    /** The entry it was relinked to: the one before it in file order, or null at the head. */
+    relinkedTo: string | null;
+    /** What the lost entry's absence leaves behind for the provider transcript. */
+    note?: string;
+}
+/** Relink each orphan onto the entry before it in file order — the leaf pi held when the lost
+ *  entry was appended. A lost toolResult leaves a tool call without a result, which pi-ai's
+ *  message transform answers with a synthetic "No result provided" result; a lost toolCall
+ *  would leave a toolResult with no call, which the transform does not fix, so that case is
+ *  reported in `note` for the caller to resolve. Returns new entry objects; the input is untouched. */
+export declare function relinkOrphanedParents(entries: readonly SessionEntry[]): {
+    entries: SessionEntry[];
+    relinks: OrphanRelink[];
+};
+/** Serialize a conversation file: header first, one JSON line per entry. */
+export declare function conversationLines(header: SessionHeader, entries: readonly SessionEntry[]): string;
+export interface FileRepair {
+    path: string;
+    entries: number;
+    /** Branch length walked from the last entry, before and after the relink. */
+    branchBefore: number;
+    branchAfter: number;
+    relinks: OrphanRelink[];
+    backup?: string;
+}
+/** Relink one conversation file's orphaned entries in place, after copying it to `<path>.bak-orphans`.
+ *  The caller must have stopped the owning node's broker: a running broker holds the conversation in
+ *  memory and appends to the file. `write: false` reports what would change and touches nothing. */
+export declare function repairConversationFile(path: string, options: {
+    write: boolean;
+}): FileRepair;

package/dist/core/conversation-store/repair.js

@@ -0,0 +1,84 @@
+import { copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+/** Entries whose non-null `parentId` is absent from `entries`. */
+export function findOrphanedParents(entries) {
+    const ids = new Set(entries.map((entry) => entry.id));
+    const found = [];
+    entries.forEach((entry, index) => {
+        if (entry.parentId && !ids.has(entry.parentId))
+            found.push({ index, entryId: entry.id, missingParentId: entry.parentId });
+    });
+    return found;
+}
+function toolCallIds(entry) {
+    if (entry?.type !== 'message')
+        return [];
+    const message = entry.message;
+    if (message.role !== 'assistant' || !Array.isArray(message.content))
+        return [];
+    return message.content.filter((block) => block.type === 'toolCall' && block.id).map((block) => block.id);
+}
+/** Relink each orphan onto the entry before it in file order — the leaf pi held when the lost
+ *  entry was appended. A lost toolResult leaves a tool call without a result, which pi-ai's
+ *  message transform answers with a synthetic "No result provided" result; a lost toolCall
+ *  would leave a toolResult with no call, which the transform does not fix, so that case is
+ *  reported in `note` for the caller to resolve. Returns new entry objects; the input is untouched. */
+export function relinkOrphanedParents(entries) {
+    const orphans = new Map(findOrphanedParents(entries).map((orphan) => [orphan.index, orphan]));
+    const relinks = [];
+    const next = entries.map((entry, index) => {
+        const orphan = orphans.get(index);
+        if (!orphan)
+            return entry;
+        const prior = entries[index - 1];
+        const relink = { ...orphan, relinkedTo: prior?.id ?? null };
+        if (entry.type === 'message' && entry.message.role === 'toolResult') {
+            const callId = entry.message.toolCallId;
+            if (!callId || !toolCallIds(prior).includes(callId))
+                relink.note = `toolResult ${callId ?? '?'} has no tool call on the entry before it`;
+        }
+        relinks.push(relink);
+        return { ...entry, parentId: prior?.id ?? null };
+    });
+    return { entries: next, relinks };
+}
+/** Serialize a conversation file: header first, one JSON line per entry. */
+export function conversationLines(header, entries) {
+    return [header, ...entries].map((line) => `${JSON.stringify(line)}\n`).join('');
+}
+function branchLength(entries) {
+    const byId = new Map(entries.map((entry) => [entry.id, entry]));
+    let length = 0;
+    for (let current = entries.at(-1); current; current = current.parentId ? byId.get(current.parentId) : undefined)
+        length++;
+    return length;
+}
+/** Relink one conversation file's orphaned entries in place, after copying it to `<path>.bak-orphans`.
+ *  The caller must have stopped the owning node's broker: a running broker holds the conversation in
+ *  memory and appends to the file. `write: false` reports what would change and touches nothing. */
+export function repairConversationFile(path, options) {
+    const lines = [];
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            lines.push(JSON.parse(line));
+        }
+        catch { /* an interrupted tail line */ }
+    }
+    const header = lines.shift();
+    if (header?.type !== 'session')
+        throw new Error(`no session header: ${path}`);
+    const entries = lines;
+    const { entries: relinked, relinks } = relinkOrphanedParents(entries);
+    const result = { path, entries: entries.length, branchBefore: branchLength(entries), branchAfter: branchLength(relinked), relinks };
+    if (relinks.length === 0 || !options.write)
+        return result;
+    const backup = `${path}.bak-orphans`;
+    if (existsSync(backup))
+        throw new Error(`backup already exists: ${backup}`);
+    copyFileSync(path, backup);
+    const temp = `${path}.${process.pid}.repair.tmp`;
+    writeFileSync(temp, conversationLines(header, relinked), { mode: 0o600 });
+    renameSync(temp, path);
+    return { ...result, backup };
+}

package/dist/core/env-name.d.ts

@@ -4,3 +4,4 @@ export interface EnvNameValidation {
 }
 /** Validate an environment variable identifier without reading its value. */
 export declare function validateEnvVarName(name: unknown): EnvNameValidation;
+export declare function isReservedEnvName(name: string): boolean;

package/dist/core/env-name.js

@@ -7,3 +7,19 @@ export function validateEnvVarName(name) {
         errors.push('env var name must start with letter/underscore, followed by alphanumeric/underscore');
     return { isValid: errors.length === 0, errors };
 }
+/** crtr's own identity/routing env names — reserved so a stored profile value
+ *  can never redirect a broker to a different canvas home/db/socket dir or
+ *  masquerade as its own process identity. `HOME` is reserved alongside the
+ *  `CRTR_*` family because crtr has no independent authoritative scope root
+ *  yet; every path in `core/canvas/paths.ts` ultimately derives from it.
+ *  Enforced at write (`setProfileEnvVar` throws below) AND defensively at
+ *  read (`readProfileEnvVars`), so even a reserved name that reached a row some
+ *  other way is uniformly invisible rather than trusted.
+ *
+ *  The deployment-wide feedback names are the only `CRTR_*` values stored
+ *  anywhere; they live in their own store (`profiles/app-env-store.ts`). */
+const RESERVED_ENV_PREFIX = 'CRTR_';
+const RESERVED_ENV_EXACT_NAMES = new Set(['HOME']);
+export function isReservedEnvName(name) {
+    return name.startsWith(RESERVED_ENV_PREFIX) || RESERVED_ENV_EXACT_NAMES.has(name);
+}

package/dist/core/events/emit.js

@@ -2,11 +2,13 @@ import { appendBufferedDaemonRecord, appendRotatingRecord } from '../log.js';
 import { buildEnvelope } from './envelope.js';
 import { serializeEventRecord } from './serialize.js';
 import { eventSource } from './source.js';
-import { envExecutionId } from '../../shared/env.js';
+import { isSandboxedNode } from '../../shared/env.js';
 import { appendBrokerLog } from '../runtime/broker/daemon-ops.js';
-// A launched broker cannot open its node's records, so its events append through
-// the daemon in emit order. A record the daemon did not append goes to stderr,
-// which the daemon-opened broker.log fd captures.
+// A broker confined by the hosted VMs' Linux launcher cannot open its node's records (spaces/mounts.ts refuses to
+// mount them), so its events append through the daemon in emit order. Every other broker, a Mac's or a cloud
+// sandbox's, appends its own log.jsonl on its own disk. A record the daemon did not append goes to stderr, which
+// the daemon-opened broker.log fd captures. Cycle 6 deletes the launcher and with it this route.
+let launcherConfined;
 let brokerLogTail = Promise.resolve();
 /** Resolves after every broker event emitted so far has been appended or written to stderr. */
 export function flushBrokerLog() { return brokerLogTail; }
@@ -34,7 +36,7 @@ export function emitEvent(input) {
         return false;
     const envelope = buildEnvelope({ ...input, component: source.component, ...(source.node_id === undefined ? {} : { node_id: source.node_id }), ...(source.stream_id === undefined ? {} : { stream_id: source.stream_id }) });
     const record = serializeEventRecord(envelope);
-    if (source.component === 'broker' && source.node_id !== undefined && envExecutionId() !== undefined) {
+    if (source.component === 'broker' && source.node_id !== undefined && (launcherConfined ??= isSandboxedNode())) {
         queueBrokerRecord(source.node_id, record);
         return true;
     }