@north-light/api 0.3.580 → 0.3.587

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

@@ -0,0 +1,14 @@
+import { type ConversationStore } from './index.js';
+/** Durable tail rows, with immutable JSONL parts. All broker-visible writes pass through this store. */
+export declare function createRowStore(): ConversationStore & {
+    commit(id: string): Promise<number>;
+    importLegacy(runId?: string): Promise<void>;
+    recover(rows: Array<{
+        session_id: string;
+        node_id: string;
+        transcript_path: string | null;
+    }>): void;
+};
+/** Rewrite part 0's header `cwd` under the conversation's row lock, leaving later parts and tail rows untouched.
+ *  Returns false when the header's cwd is not `oldCwd`. */
+export declare function relocateConversationHeader(id: string, oldCwd: string, newCwd: string): Promise<boolean>;

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

@@ -0,0 +1,337 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { SessionManager } from '@earendil-works/pi-coding-agent';
+import { blobStore } from '../blobs/index.js';
+import { openDb, withCanvasWrite } from '../canvas/db.js';
+import { appSpace } from '../layout.js';
+import { appendConversationEvents, rootRepromptPending } from '../../daemon/runs/append-section.js';
+import { ConversationNotFoundError } from './index.js';
+const OWNER_ORDER = 's.unbound_at IS NULL DESC, s.created_at DESC, s.seq DESC';
+const keyFor = (node, id, seq) => `conversations/${node}/${id}/${seq}.jsonl`;
+const encode = (values) => values.map(value => JSON.stringify(value) + '\n').join('');
+const decode = (text) => text.split('\n').filter(Boolean).map(line => JSON.parse(line));
+const at = () => new Date().toISOString();
+async function binding(db, id, lock = false) {
+    const row = await db.prepare(`SELECT s.binding_id, s.node_id, s.transcript_path, s.input_ids_json, s.source_session_id, n.run_id FROM sessions s JOIN nodes n ON n.node_id = s.node_id WHERE s.session_id = ? ORDER BY ${OWNER_ORDER} LIMIT 1${lock ? ' FOR UPDATE OF s' : ''}`).get(id);
+    if (!row)
+        throw new ConversationNotFoundError(id);
+    return row;
+}
+async function parts(db, id) {
+    return await db.prepare('SELECT seq, blob_key, bytes, entries, created FROM conversation_parts WHERE conversation_id = ? ORDER BY seq').all(id);
+}
+async function tail(db, id) {
+    return await db.prepare('SELECT seq, body, bytes, created FROM conversation_entries WHERE conversation_id = ? ORDER BY seq').all(id);
+}
+/** Parts and tail rows read by one statement, so a concurrent commit (new part, tail rows deleted, one transaction)
+ *  is seen whole or not at all. */
+async function snapshot(db, id) {
+    const rows = await db.prepare(`SELECT 'part' AS kind, seq, blob_key, NULL AS body, bytes, entries, created FROM conversation_parts WHERE conversation_id = ?
+    UNION ALL SELECT 'tail', seq, NULL, body, bytes, NULL, created FROM conversation_entries WHERE conversation_id = ? ORDER BY 1, 2`).all(id, id);
+    return {
+        parts: rows.filter(row => row.kind === 'part').map(({ seq, blob_key, bytes, entries, created }) => ({ seq: Number(seq), blob_key, bytes: Number(bytes), entries: Number(entries), created })),
+        tail: rows.filter(row => row.kind === 'tail').map(({ seq, body, bytes, created }) => ({ seq: Number(seq), body, bytes: Number(bytes), created })),
+    };
+}
+const CHUNK = 1024 * 1024;
+/** The bytes [start, end) of the logical JSONL (parts, then tail rows), reading only the objects and ranges that overlap. */
+async function bytesOf(snap, start, end) {
+    const out = [];
+    let offset = 0;
+    const blobs = await blobStore();
+    for (const part of snap.parts) {
+        const from = Math.max(start, offset), to = Math.min(end, offset + part.bytes);
+        if (from < to) {
+            const data = await blobs.get(part.blob_key, { start: from - offset, length: to - from });
+            if (!data)
+                throw new Error(`missing conversation object: ${part.blob_key}`);
+            out.push(data);
+        }
+        offset += part.bytes;
+    }
+    for (const row of snap.tail) {
+        const from = Math.max(start, offset), to = Math.min(end, offset + row.bytes);
+        if (from < to)
+            out.push(Buffer.from(row.body + '\n').subarray(from - offset, to - offset));
+        offset += row.bytes;
+    }
+    return Buffer.concat(out);
+}
+/** Files registered by `recover` (tests, first-boot repair): imported as part 0 on first use. */
+const legacy = new Map();
+async function importOne(id, node, path) {
+    const db = await openDb();
+    if (await db.prepare('SELECT 1 FROM conversation_parts WHERE conversation_id = ? AND seq = 0').get(id) || !existsSync(path))
+        return;
+    let data = readFileSync(path);
+    // A crash can leave a torn last line; only complete lines are recorded.
+    const lastNewline = data.lastIndexOf(10);
+    if (lastNewline < 0)
+        return;
+    data = data.subarray(0, lastNewline + 1);
+    // The file store indexed run events up to `event_offset`; the entries it wrote after that are projected now.
+    const row = await db.prepare('SELECT s.binding_id, s.node_id, s.event_offset, s.input_ids_json, s.source_session_id, n.run_id FROM sessions s JOIN nodes n ON n.node_id = s.node_id WHERE s.session_id = ? ORDER BY ' + OWNER_ORDER + ' LIMIT 1').get(id);
+    let unindexed = [];
+    if (row?.run_id && row.event_offset !== null) {
+        const offset = Number(row.event_offset);
+        if (data.length < offset)
+            throw new Error(`conversation shorter than indexed offset: ${id}`);
+        unindexed = decode(data.subarray(offset).toString('utf8')).filter((entry) => entry.type !== 'session');
+    }
+    const reprompt = row?.run_id ? await rootRepromptPending(row.run_id, row.node_id, unindexed) : false;
+    const key = keyFor(node, id, 0);
+    await (await blobStore()).put(key, data);
+    await withCanvasWrite(async (tx) => {
+        const inserted = await tx.prepare('INSERT INTO conversation_parts (conversation_id, seq, blob_key, bytes, entries, created) VALUES (?, 0, ?, ?, ?, ?) ON CONFLICT DO NOTHING RETURNING seq').get(id, key, data.length, Math.max(0, data.toString('utf8').split('\n').filter(Boolean).length - 1), at());
+        if (!inserted || !row?.run_id || row.event_offset === null)
+            return;
+        const pending = row.source_session_id ? [] : await appendConversationEvents(tx, row.run_id, row.node_id, unindexed, JSON.parse(row.input_ids_json), reprompt);
+        await tx.prepare('UPDATE sessions SET event_offset = ?, indexed_entry_id = ?, input_ids_json = ? WHERE binding_id = ?').run(data.length, unindexed.at(-1)?.id ?? null, JSON.stringify(pending), row.binding_id);
+    });
+}
+async function initial(id, db) {
+    const owner = await db.prepare(`SELECT s.binding_id, s.node_id, s.transcript_path, s.input_ids_json, s.source_session_id, n.run_id FROM sessions s JOIN nodes n ON n.node_id = s.node_id WHERE s.session_id = ? ORDER BY ${OWNER_ORDER} LIMIT 1`).get(id);
+    const known = legacy.get(id);
+    if (!owner && !known)
+        throw new ConversationNotFoundError(id);
+    let first = (await parts(db, id))[0];
+    if (!first) {
+        const path = known?.path ?? owner?.transcript_path ?? undefined;
+        if (path)
+            await importOne(id, known?.node ?? owner.node_id, path);
+        first = (await parts(db, id))[0];
+    }
+    if (!first || first.seq !== 0)
+        throw new ConversationNotFoundError(id);
+    const data = await (await blobStore()).get(first.blob_key, { start: 0, length: Math.min(first.bytes, 256 * 1024) });
+    if (!data)
+        throw new Error(`missing conversation object: ${first.blob_key}`);
+    const end = data.indexOf(10);
+    if (end < 0)
+        throw new Error(`invalid conversation header: ${id}`);
+    const header = JSON.parse(data.subarray(0, end).toString('utf8'));
+    if (header.type !== 'session' || header.id !== id)
+        throw new Error(`invalid conversation header: ${id}`);
+    return { header, path: owner?.transcript_path ?? known?.path ?? '', binding: owner };
+}
+/** Durable tail rows, with immutable JSONL parts. All broker-visible writes pass through this store. */
+export function createRowStore() {
+    const store = {
+        async create(nodeId, header, entries, _path) {
+            const db = await openDb();
+            const node = await db.prepare('SELECT grantee, run_id FROM node_rows WHERE node_id = ?').get(nodeId);
+            if (!node)
+                throw new Error(`missing conversation owner ${nodeId}`);
+            const id = header.id;
+            const path = join(appSpace(node.grantee).conversations, nodeId, `${header.timestamp.replace(/[:.]/g, '-')}_${id}.jsonl`);
+            const body = encode([header, ...entries]);
+            const key = keyFor(nodeId, id, 0);
+            const reprompt = node.run_id ? await rootRepromptPending(node.run_id, nodeId, entries) : false;
+            await (await blobStore()).put(key, body);
+            await withCanvasWrite(async (tx) => {
+                if (await tx.prepare('SELECT 1 FROM conversation_parts WHERE conversation_id = ?').get(id))
+                    throw new Error(`conversation already exists: ${id}`);
+                const created = at();
+                const source = header.parentSession ? await tx.prepare('SELECT session_id FROM sessions WHERE transcript_path = ? LIMIT 1').get(header.parentSession) : undefined;
+                await tx.prepare('INSERT INTO sessions (binding_id, session_id, node_id, transcript_path, source_session_id, fork_entry_id, created_at, bound_at, unbound_at) VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?)')
+                    .run(randomUUID(), id, nodeId, path, source ? source.session_id : null, created, created, created);
+                await tx.prepare('INSERT INTO conversation_parts (conversation_id, seq, blob_key, bytes, entries, created) VALUES (?, 0, ?, ?, ?, ?)').run(id, key, Buffer.byteLength(body), entries.length, created);
+                if (node.run_id && !source) {
+                    const pending = await appendConversationEvents(tx, node.run_id, nodeId, entries, [], reprompt);
+                    await tx.prepare('UPDATE sessions SET indexed_entry_id = ?, input_ids_json = ? WHERE session_id = ? AND node_id = ?').run(entries.at(-1)?.id ?? null, JSON.stringify(pending), id, nodeId);
+                }
+            });
+            return id;
+        },
+        async append(id, entries) {
+            if (!entries.length)
+                return;
+            // Run-status inputs that read files are computed before the transaction opens.
+            const first = await binding(await openDb(), id);
+            const reprompt = first.run_id ? await rootRepromptPending(first.run_id, first.node_id, entries) : false;
+            await withCanvasWrite(async (db) => {
+                const owner = await binding(db, id, true);
+                if (!(await parts(db, id)).length)
+                    throw new ConversationNotFoundError(id);
+                const inserted = [];
+                for (const entry of entries) {
+                    const body = JSON.stringify(entry);
+                    const row = await db.prepare('INSERT INTO conversation_entries (conversation_id, entry_id, body, bytes, execution_id, created) VALUES (?, ?, ?, ?, NULL, ?) ON CONFLICT (conversation_id, entry_id) DO NOTHING RETURNING entry_id').get(id, entry.id, body, Buffer.byteLength(body) + 1, at());
+                    if (row)
+                        inserted.push(entry);
+                }
+                if (owner.run_id && inserted.length) {
+                    const pending = await appendConversationEvents(db, owner.run_id, owner.node_id, inserted, JSON.parse(owner.input_ids_json ?? '[]'), reprompt);
+                    await db.prepare('UPDATE sessions SET indexed_entry_id = ?, input_ids_json = ? WHERE binding_id = ?').run(inserted.at(-1).id, JSON.stringify(pending), owner.binding_id);
+                }
+            });
+        },
+        async readLines(id) {
+            const db = await openDb();
+            const { path } = await initial(id, db);
+            const snap = await snapshot(db, id);
+            const size = snap.parts.reduce((n, p) => n + p.bytes, 0) + snap.tail.reduce((n, p) => n + p.bytes, 0);
+            async function* lines() {
+                let carry = '';
+                for (let at = 0; at < size; at += CHUNK) {
+                    const text = carry + (await bytesOf(snap, at, Math.min(size, at + CHUNK))).toString('latin1');
+                    const cut = text.lastIndexOf('\n');
+                    carry = text.slice(cut + 1);
+                    for (const line of text.slice(0, cut + 1).split('\n'))
+                        if (line)
+                            yield Buffer.from(line, 'latin1').toString('utf8');
+                }
+                if (carry)
+                    yield Buffer.from(carry, 'latin1').toString('utf8');
+            }
+            return { path, lines: lines() };
+        },
+        async read(id, window) {
+            const db = await openDb();
+            const { header, path } = await initial(id, db);
+            const snap = await snapshot(db, id);
+            const size = snap.parts.reduce((n, p) => n + p.bytes, 0) + snap.tail.reduce((n, p) => n + p.bytes, 0);
+            const entriesOf = (text) => decode(text).filter((entry) => entry.type !== 'session');
+            if (!window || size <= window.head + window.tail)
+                return { header, entries: entriesOf((await bytesOf(snap, 0, size)).toString('utf8')), path };
+            const front = (await bytesOf(snap, 0, Math.max(0, window.head))).toString('utf8').split('\n');
+            front.pop();
+            // One byte before the tail window says whether it begins on a line boundary.
+            const from = Math.max(0, size - window.tail);
+            const back = (await bytesOf(snap, from > 0 ? from - 1 : 0, size)).toString('utf8').split('\n');
+            if (from > 0)
+                back.shift();
+            return { header, entries: entriesOf(front.join('\n')), tail: entriesOf(back.join('\n')), path };
+        },
+        async header(id) {
+            const db = await openDb();
+            const { header, path } = await initial(id, db);
+            const snap = await snapshot(db, id);
+            return { header, path, mtime: Date.parse(snap.tail.at(-1)?.created ?? snap.parts.at(-1).created), size: snap.parts.reduce((n, p) => n + p.bytes, 0) + snap.tail.reduce((n, p) => n + p.bytes, 0) };
+        },
+        async list(nodeId) {
+            const db = await openDb();
+            const rows = await db.prepare(`SELECT DISTINCT ON (s.session_id) s.session_id, s.node_id FROM sessions s JOIN conversation_parts p ON p.conversation_id = s.session_id WHERE s.session_id IS NOT NULL ORDER BY s.session_id, ${OWNER_ORDER}`).all();
+            const result = [];
+            for (const row of rows) {
+                if (nodeId && row.node_id !== nodeId)
+                    continue;
+                const info = await store.header(row.session_id);
+                result.push({ conversation_id: row.session_id, node_id: row.node_id, ...info });
+            }
+            return result.sort((a, b) => b.mtime - a.mtime);
+        },
+        async replace(id, header, entries) {
+            if (header.id !== id)
+                throw new Error('replacement header id differs from conversation id');
+            const db = await openDb();
+            const owner = await binding(db, id);
+            if (owner.run_id)
+                throw new Error(`run conversation ${id} is append-only; replace refused`);
+            const key = `conversations/${owner.node_id}/${id}/0-${randomUUID()}.jsonl`;
+            const text = encode([header, ...entries]);
+            await (await blobStore()).put(key, text);
+            // The parts displaced are the ones current under the lock, so a concurrent header relocation leaves no orphan object.
+            const old = await withCanvasWrite(async (tx) => {
+                const current = await binding(tx, id, true);
+                if (current.run_id)
+                    throw new Error(`run conversation ${id} is append-only; replace refused`);
+                const displaced = await parts(tx, id);
+                await tx.prepare('DELETE FROM conversation_parts WHERE conversation_id = ?').run(id);
+                await tx.prepare('DELETE FROM conversation_entries WHERE conversation_id = ?').run(id);
+                await tx.prepare('INSERT INTO conversation_parts (conversation_id, seq, blob_key, bytes, entries, created) VALUES (?, 0, ?, ?, ?, ?)').run(id, key, Buffer.byteLength(text), entries.length, at());
+                return displaced;
+            });
+            for (const part of old)
+                await (await blobStore()).delete(part.blob_key);
+        },
+        async fork(id, nodeId, leafId, cwd) {
+            const source = await store.read(id);
+            let entries = source.entries;
+            if (leafId !== undefined) {
+                const manager = SessionManager.inMemory(source.header.cwd, undefined, [source.header, ...entries]);
+                manager.createBranchedSession(leafId);
+                entries = manager.getEntries();
+            }
+            return await store.create(nodeId ?? (await initial(id, await openDb())).binding?.node_id ?? legacy.get(id).node, { ...source.header, id: randomUUID(), timestamp: at(), cwd: cwd ?? source.header.cwd, parentSession: source.path }, entries);
+        },
+        async delete(id, knownPath) {
+            const db = await openDb();
+            const old = await parts(db, id);
+            await withCanvasWrite(async (tx) => {
+                await tx.prepare('DELETE FROM conversation_entries WHERE conversation_id = ?').run(id);
+                await tx.prepare('DELETE FROM conversation_parts WHERE conversation_id = ?').run(id);
+                await tx.prepare('DELETE FROM sessions WHERE session_id = ?').run(id);
+            });
+            for (const part of old)
+                await (await blobStore()).delete(part.blob_key);
+            // The legacy transcript file the conversation was imported from goes with it.
+            if (knownPath)
+                rmSync(knownPath, { force: true });
+        },
+        async commit(id) {
+            return await withCanvasWrite(async (tx) => {
+                const owner = await binding(tx, id, true);
+                const pending = await tail(tx, id);
+                const existing = await parts(tx, id);
+                if (!pending.length)
+                    return existing.at(-1)?.seq ?? 0;
+                const seq = (existing.at(-1)?.seq ?? 0) + 1;
+                const key = keyFor(owner.node_id, id, seq);
+                const body = pending.map(row => row.body + '\n').join('');
+                // Keep the owner row locked through the put so concurrent commits cannot overwrite this key.
+                await (await blobStore()).put(key, body);
+                if (process.env['CRTR_FAULT_CONVERSATION'] === 'commit_exit_after_put')
+                    process.exit(1);
+                await tx.prepare('INSERT INTO conversation_parts (conversation_id, seq, blob_key, bytes, entries, created) VALUES (?, ?, ?, ?, ?, ?)').run(id, seq, key, Buffer.byteLength(body), pending.length, at());
+                await tx.prepare('DELETE FROM conversation_entries WHERE conversation_id = ? AND seq <= ?').run(id, pending.at(-1).seq);
+                return seq;
+            });
+        },
+        async importLegacy(runId) {
+            const db = await openDb();
+            const rows = await db.prepare(`SELECT DISTINCT ON (s.session_id) s.session_id, s.node_id, s.transcript_path FROM sessions s JOIN nodes n ON n.node_id = s.node_id WHERE s.session_id IS NOT NULL AND s.transcript_path IS NOT NULL ${runId ? 'AND n.run_id = ?' : ''} ORDER BY s.session_id, ${OWNER_ORDER}`).all(...(runId ? [runId] : []));
+            for (const row of rows)
+                await importOne(row.session_id, row.node_id, row.transcript_path);
+        },
+        recover(rows) {
+            for (const row of rows)
+                if (row.transcript_path)
+                    legacy.set(row.session_id, { node: row.node_id, path: row.transcript_path });
+        },
+    };
+    return store;
+}
+/** Rewrite part 0's header `cwd` under the conversation's row lock, leaving later parts and tail rows untouched.
+ *  Returns false when the header's cwd is not `oldCwd`. */
+export async function relocateConversationHeader(id, oldCwd, newCwd) {
+    const db = await openDb();
+    const owner = await binding(db, id);
+    const first = (await parts(db, id))[0];
+    if (!first || first.seq !== 0)
+        return false;
+    const data = await (await blobStore()).get(first.blob_key);
+    if (!data)
+        throw new Error(`missing conversation object: ${first.blob_key}`);
+    const end = data.indexOf(10);
+    if (end < 0)
+        throw new Error(`invalid conversation header: ${id}`);
+    const header = JSON.parse(data.subarray(0, end).toString('utf8'));
+    if (header.type !== 'session' || header.id !== id)
+        throw new Error(`invalid conversation header: ${id}`);
+    if (header.cwd !== oldCwd)
+        return false;
+    const body = Buffer.concat([Buffer.from(JSON.stringify({ ...header, cwd: newCwd })), data.subarray(end)]);
+    const key = `conversations/${owner.node_id}/${id}/0-${randomUUID()}.jsonl`;
+    // Blob I/O stays outside the write transaction; the swap only commits if part 0 is still the object we read.
+    await (await blobStore()).put(key, body);
+    const swapped = await withCanvasWrite(async (tx) => {
+        const done = await tx.prepare('UPDATE conversation_parts SET blob_key = ?, bytes = ? WHERE conversation_id = ? AND seq = 0 AND blob_key = ? RETURNING seq').get(key, body.length, id, first.blob_key);
+        return done !== undefined;
+    });
+    await (await blobStore()).delete(swapped ? first.blob_key : key).catch(() => undefined);
+    if (!swapped)
+        throw new Error(`conversation header changed during relocation: ${id}`);
+    return true;
+}

package/dist/core/directory/issuer.d.ts

@@ -0,0 +1,8 @@
+/** The directory this process mints tokens against and reads provider bundles and sign-in pages from, without a trailing slash; null
+ *  when it has none. A cloud role (`crtrd --role api|reconcile`) has no person outside a request, so it takes the issuer from the
+ *  deployment's `CRTR_DIRECTORY_URL` (the daemon refuses to boot without it), never from one person's settings. Anything else (a
+ *  Mac or a legacy single-person install) reads the user config's `runtime.issuer`, null while the runtime has not joined. */
+export declare function directoryIssuer(): string | null;
+/** Northlight's directory: where a person signs in or creates an account, and the default for `crtr sys signin` and
+ *  `crtr sys import start` when nothing names another (`--directory-url`, `runtime/machine.json`, the stored sign-in). */
+export declare const NORTHLIGHT_DIRECTORY_URL = "https://account.northlight.ai";

package/dist/core/directory/issuer.js

@@ -0,0 +1,15 @@
+import { isCloudRole } from '../canvas/person-state.js';
+import { readConfig } from '../config.js';
+// A leaf on purpose: `daemon/cron/authority.ts` reads the issuer, and `core/peer/directory.ts` (which builds the peer token cache at load) reaches it
+// through `grants/sync.ts`, so importing that module from there is an import cycle.
+/** The directory this process mints tokens against and reads provider bundles and sign-in pages from, without a trailing slash; null
+ *  when it has none. A cloud role (`crtrd --role api|reconcile`) has no person outside a request, so it takes the issuer from the
+ *  deployment's `CRTR_DIRECTORY_URL` (the daemon refuses to boot without it), never from one person's settings. Anything else (a
+ *  Mac or a legacy single-person install) reads the user config's `runtime.issuer`, null while the runtime has not joined. */
+export function directoryIssuer() {
+    const url = isCloudRole() ? process.env['CRTR_DIRECTORY_URL'] : readConfig('user').runtime?.issuer;
+    return url ? url.replace(/\/+$/, '') : null;
+}
+/** Northlight's directory: where a person signs in or creates an account, and the default for `crtr sys signin` and
+ *  `crtr sys import start` when nothing names another (`--directory-url`, `runtime/machine.json`, the stored sign-in). */
+export const NORTHLIGHT_DIRECTORY_URL = 'https://account.northlight.ai';

package/dist/core/directory/join.d.ts

@@ -0,0 +1,57 @@
+import { type JsonWebKey } from 'node:crypto';
+/** The runtime-client key file grant sync reads, plus the accepted
+ *  enrollment's metadata. Written only after a successful registration. */
+interface JoinedClient {
+    jwk: JsonWebKey & {
+        kid: string;
+    };
+    kid: string;
+    alg: 'ES256';
+    client_id: string;
+    runtime: string;
+    issuer: string;
+    owner: string;
+    url: string;
+    token_sha256: string;
+    machine_id?: string;
+    is_default?: boolean;
+}
+type Registration = Pick<JoinedClient, 'runtime' | 'client_id' | 'issuer' | 'owner' | 'url' | 'machine_id' | 'is_default'>;
+export interface JoinResult extends Registration {
+    /** False when the token matched the stored successful registration and no directory call was made. */
+    registered: boolean;
+    /** `restarted`: a daemon was running, join stopped it and started a new one on the joined config. `started`: none was running and join started one, whose first grant sync installs the account's provider plugins (`crtr cloud …`). `not_running`: none was started (a hosted container's launcher owns its daemon). `restart_failed`: the join is committed but the new daemon did not start (see `daemon_error`). */
+    daemon: 'restarted' | 'started' | 'not_running' | 'restart_failed';
+    daemon_error?: string;
+}
+/** How join takes a running daemon down and brings it back. Absent, join keeps
+ *  the offline contract and refuses `daemon_running` while a daemon answers. */
+export interface JoinDaemonControl {
+    /** Whether a daemon is running or answering on this runtime's socket. */
+    running(): Promise<boolean>;
+    /** Stop the daemon and every stray; resolves once none remains. */
+    stop(): Promise<void>;
+    /** Start a daemon on the settings now on disk and wait until it serves. */
+    start(): Promise<void>;
+    /** Waits, bounded, for a daemon that join started with none running to finish its first grant sync, which installs the account's provider plugins. Best effort: the join is committed either way. */
+    firstSync?(): Promise<void>;
+    /** Whether this process runs inside a node, whose broker the stop kills. */
+    insideNode(): boolean;
+}
+/** Provider plugin ids installed on this machine (reported for display only). */
+export declare function installedPluginIds(): string[];
+/** The owner a successful join recorded, or null when `crtr sys join` never wrote the client file. */
+export declare function joinedOwner(): string | null;
+/** The issuer a successful join recorded, or null. */
+export declare function joinedIssuer(): string | null;
+/** The whole registration a successful join recorded, or null; a damaged file throws. */
+export declare function joinedClient(): Registration | null;
+/** Join this runtime to a directory.
+ *
+ *  With `daemon` control, a running daemon is no obstacle: the join holds the
+ *  join lock (so no viewer's redial can autostart a daemon while it is down),
+ *  registers with the directory while the daemon still serves, stops the
+ *  daemon, writes the identity, and starts the daemon again so its start
+ *  applies the person change to canvas.db. Without it, a running daemon refuses. */
+export declare function joinDirectory(directory: string, token: string, name?: string, daemon?: JoinDaemonControl): Promise<JoinResult>;
+export {};

package/dist/core/directory/join.js

@@ -0,0 +1,218 @@
+// Runtime join: exchange a directory enrollment token for a registration of a
+// new runtime client key, then record the returned identity in the runtime-client file. Runs
+// offline, before the daemon starts, as the daemon's OS user; it writes no settings (the daemon applies them at its start).
+import { createHash, generateKeyPairSync, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { InputError } from '../io.js';
+import { network } from '../errors.js';
+import { secretsDir } from '../layout.js';
+import { apiSocketPath } from '../canvas/paths.js';
+import { daemonAnswers } from '../layout-migrate/index.js';
+import { atomicWriteJson, readJsonIfExists } from '../fs-utils.js';
+import { launcherPresent } from '../grants/sandboxes.js';
+import { crtrVersion } from '../../shared/crtr-version.js';
+import { pluginsDir } from '../scope.js';
+import { withJoinLock } from './join-lock.js';
+function clientPath() {
+    return join(secretsDir(), 'runtime-client.json');
+}
+function isUrl(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        const { protocol } = new URL(value);
+        return protocol === 'http:' || protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+function registration(value) {
+    const body = (value ?? {});
+    const { runtime, client_id, issuer, owner, url } = body;
+    if (typeof runtime !== 'string' || !/^runtime:.+/.test(runtime) || typeof client_id !== 'string' || client_id === ''
+        || !isUrl(issuer) || typeof owner !== 'string' || !/^user:.+/.test(owner) || !isUrl(url)) {
+        throw network('directory registration answer is missing runtime, client_id, issuer, owner, or url');
+    }
+    const { machine_id, is_default } = body;
+    return { runtime, client_id, issuer, owner, url,
+        ...(typeof machine_id === 'string' ? { machine_id } : {}), ...(typeof is_default === 'boolean' ? { is_default } : {}) };
+}
+function pendingPath() {
+    return join(secretsDir(), 'runtime-client.pending.json');
+}
+/** Provider plugin ids installed on this machine (reported for display only). */
+export function installedPluginIds() {
+    try {
+        const dir = pluginsDir('user');
+        if (!dir || !existsSync(dir))
+            return [];
+        return readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith('.')).map((entry) => entry.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function register(directory, token, publicJwk, name) {
+    const endpoint = `${directory.replace(/\/$/, '')}/v1/runtimes/registration`;
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: 'PUT',
+            headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ jwk: publicJwk, name, platform: `${process.platform}-${process.arch}`, crtr_version: crtrVersion(), plugins: installedPluginIds(), sandboxed: launcherPresent() }),
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (error) {
+        throw network(`directory registration request to ${endpoint} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const text = await response.text();
+    if (!response.ok) {
+        // A refusal is the directory's answer, so the pending key is spent. A 5xx may be a lost commit: keep it for the retry.
+        if (response.status < 500)
+            rmSync(pendingPath(), { force: true });
+        throw new InputError({
+            error: 'join_refused',
+            message: `directory refused the registration: ${response.status} ${text.slice(0, 500)}`,
+            next: `Create a new join token at ${directory.replace(/\/$/, '')}/account/machines (tokens are single-use and expire after 10 minutes), and run \`crtr sys join\` again.`,
+        });
+    }
+    try {
+        return registration(JSON.parse(text));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw network('directory registration answer is not JSON');
+        throw error;
+    }
+}
+/** What a successful `crtr sys join` recorded in the client file, or null when join never wrote it (no file, or one provisioned
+ *  without join, which has no `token_sha256`). Join writes no settings: the daemon applies this at its start (`applyBootSettings`),
+ *  and its `retireLocalPerson` makes `owner` the install's person. */
+function readJoined() {
+    const stored = readJsonIfExists(clientPath());
+    if (stored?.token_sha256 === undefined)
+        return null;
+    const { owner } = stored;
+    if (typeof owner !== 'string' || !/^user:.+/.test(owner))
+        throw new Error(`${clientPath()} was written by join but has a missing or invalid owner`);
+    return stored;
+}
+/** The owner a successful join recorded, or null when `crtr sys join` never wrote the client file. */
+export function joinedOwner() { return readJoined()?.owner ?? null; }
+/** The issuer a successful join recorded, or null. */
+export function joinedIssuer() { return readJoined()?.issuer ?? null; }
+/** The whole registration a successful join recorded, or null; a damaged file throws. */
+export function joinedClient() {
+    const stored = readJoined();
+    return stored === null ? null : registration(stored);
+}
+function daemonRunningError(socket) {
+    return new InputError({
+        error: 'daemon_running',
+        message: `cannot join while a daemon answers on ${socket}`,
+        next: 'This daemon is managed outside crtr, so join cannot restart it: stop the daemon that owns this volume, then run `crtr sys join` again.',
+    });
+}
+/** Register (or reuse the stored registration) without touching local state beyond the pending key. */
+async function obtainRegistration(directory, token, name, tokenHash) {
+    const stored = readJsonIfExists(clientPath());
+    if (stored?.token_sha256 === tokenHash)
+        return { joined: registration(stored), registered: false };
+    mkdirSync(secretsDir(), { recursive: true, mode: 0o700 });
+    let pending = readJsonIfExists(pendingPath());
+    if (pending?.token_sha256 !== tokenHash || pending.directory !== directory || !pending.jwk || !pending.public_jwk) {
+        const { privateKey, publicKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
+        const kid = randomUUID();
+        pending = { token_sha256: tokenHash, directory,
+            jwk: { ...privateKey.export({ format: 'jwk' }), kid, alg: 'ES256', use: 'sig' },
+            public_jwk: { ...publicKey.export({ format: 'jwk' }), kid, alg: 'ES256', use: 'sig' } };
+        atomicWriteJson(pendingPath(), pending, { mode: 0o600 });
+    }
+    const { jwk, public_jwk: publicJwk } = pending;
+    const joined = await register(directory, token, publicJwk, name);
+    return { joined, registered: true, client: { jwk, kid: jwk.kid, alg: 'ES256', ...joined, token_sha256: tokenHash } };
+}
+/** Join this runtime to a directory.
+ *
+ *  With `daemon` control, a running daemon is no obstacle: the join holds the
+ *  join lock (so no viewer's redial can autostart a daemon while it is down),
+ *  registers with the directory while the daemon still serves, stops the
+ *  daemon, writes the identity, and starts the daemon again so its start
+ *  applies the person change to canvas.db. Without it, a running daemon refuses. */
+export async function joinDirectory(directory, token, name = hostname(), daemon) {
+    if (!isUrl(directory))
+        throw new InputError({ error: 'invalid_directory', message: 'directory must be an http or https URL', received: directory, field: 'directory', next: 'Pass the directory base URL, for example https://directory.example.' });
+    if (token === '')
+        throw new InputError({ error: 'invalid_token', message: 'token is empty', field: 'token', next: 'Pass the enrollment token provisioning supplied.' });
+    const socket = apiSocketPath();
+    const tokenHash = createHash('sha256').update(token).digest('hex');
+    if (daemon === undefined) {
+        if (await daemonAnswers(socket))
+            throw daemonRunningError(socket);
+        const { joined, registered, client } = await obtainRegistration(directory, token, name, tokenHash);
+        if (client) {
+            atomicWriteJson(clientPath(), client, { mode: 0o600 });
+            rmSync(pendingPath(), { force: true });
+        }
+        return { ...joined, registered, daemon: 'not_running' };
+    }
+    return withJoinLock(async () => {
+        const refuseInsideNode = () => new InputError({
+            error: 'join_inside_node',
+            message: 'a daemon is running and this command is inside a node: stopping the daemon would kill this node\'s broker and this command with it',
+            next: 'Run `crtr sys join` from a plain terminal outside any crtr node. It stops the daemon, joins, and starts it again for you.',
+        });
+        if (await daemon.running() && daemon.insideNode())
+            throw refuseInsideNode();
+        const { joined, registered, client } = await obtainRegistration(directory, token, name, tokenHash);
+        let stopped = false;
+        let failure;
+        try {
+            if (await daemon.running()) {
+                // The daemon may have started during the registration call: decide again, here, where the stop happens.
+                if (daemon.insideNode())
+                    throw refuseInsideNode();
+                stopped = true;
+                await daemon.stop();
+                if (await daemon.running())
+                    throw daemonRunningError(socket);
+            }
+            if (client) {
+                atomicWriteJson(clientPath(), client, { mode: 0o600 });
+                rmSync(pendingPath(), { force: true });
+            }
+            // Nothing may start a daemon now (the lock is held), so one seen here began before the lock and read the old settings.
+            if (await daemon.running()) {
+                if (daemon.insideNode())
+                    throw refuseInsideNode();
+                stopped = true;
+                await daemon.stop();
+            }
+        }
+        catch (error) {
+            failure = error;
+        }
+        // Bring the daemon back whether or not the join finished: it was running when we began. The lock is held until it serves, so no redial races it.
+        // With none running, start one anyway: grant sync is what installs `cloud`, and a bare `crtr cloud …` is an unknown
+        // command (it never reaches the daemon, so never autostarts one) until some daemon has synced.
+        let restart = { daemon: 'not_running' };
+        if (failure === undefined || stopped) {
+            try {
+                await daemon.start();
+                restart = { daemon: stopped ? 'restarted' : 'started' };
+            }
+            catch (error) {
+                restart = { daemon: 'restart_failed', daemon_error: error instanceof Error ? error.message : String(error) };
+            }
+        }
+        if (failure !== undefined)
+            throw failure;
+        if (restart.daemon === 'started')
+            await daemon.firstSync?.();
+        return { ...joined, registered, ...restart };
+    });
+}