omp-onlyne 0.0.0-stage → 0.1.0

package/src/runtime.ts

@@ -0,0 +1,416 @@
+import { dirname, join } from "node:path";
+import { OnlyneError, trustPhase, type DiscoveryCandidate, type DiscoveryRecord, type KeyExchange, type KeyHook, type MaintenanceClock, type NotifyEvent, type OnlyneNode, type Outbound, type Page } from "@onlyne/lib";
+import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { ensureKeyDir } from "@onlyne/node-host/keys";
+import { NetworkDiscovery } from "@onlyne/node-host/network";
+import { resolveLocale, setLocale } from "@onlyne/node-host/i18n";
+import { commandText as t } from "./ui/command-text.ts";
+import { registerMsgTool } from "./tool.ts";
+import { currentDecision, JudgeDecider } from "./decider.ts";
+import { loadConfig, normalizeServiceUrl, saveConfig, shortNodeId } from "./config.ts";
+import { createRuntimeBridge } from "./messages.ts";
+import { advertisedHost, createOnlyneNode } from "./node.ts";
+import { canAnswer, ContextRegistry, SqliteStorage } from "./store.ts";
+import { resourceQuery } from "./resources.ts";
+import type { OnlyneConfig, OnlyneStatus, QueueItem, ViewerContact, ViewerDiscovery, ViewerMessage, ViewerSnapshot, ViewerThread } from "./types.ts";
+
+export interface PluginRuntime {
+	readonly config: OnlyneConfig;
+	readonly endpoint: string;
+	readonly mainAgentId: string;
+	readonly main: ExtensionContext;
+	readonly pi: ExtensionAPI;
+	readonly contexts: ContextRegistry;
+	readonly node: OnlyneNode;
+	readonly storage: SqliteStorage;
+	readonly decider: JudgeDecider;
+	snapshot(): Promise<ViewerSnapshot>;
+	status(): Promise<OnlyneStatus>;
+	onChange(listener: () => void): () => void;
+	/** The library's one notification channel: trust transitions, inbound entries, pending-work flips. */
+	notify(event: NotifyEvent): void;
+	contact(endpoint: string): Promise<void>;
+	/** Stage one of one exchange; the returned session carries the fingerprint the peer proved. */
+	trustBegin(node: string): Promise<KeyExchange>;
+	trustAccept(node: string, fingerprint: string): Promise<void>;
+	trustRevoke(node: string): Promise<void>;
+	trustRotate(): Promise<{ fingerprint: string }>;
+	refreshDiscovery(): Promise<void>;
+	updateConfig(next: OnlyneConfig): Promise<void>;
+	close(): Promise<void>;
+}
+let active: PluginRuntime | undefined;
+export interface RuntimeHost {
+	config?: () => Promise<OnlyneConfig>;
+	keys?: KeyHook;
+}
+export function getRuntime(): PluginRuntime | undefined { return active; }
+export function setRuntime(runtime: PluginRuntime | undefined): void { active = runtime; }
+export async function startRuntime(pi: ExtensionAPI, ctx: ExtensionContext, host: RuntimeHost = {}): Promise<PluginRuntime> {
+	const config = await (host.config === undefined ? loadConfig(ctx.cwd) : host.config());
+	setLocale(resolveLocale(config.language));
+	if (active && active.config.path === config.path && JSON.stringify(active.config) === JSON.stringify(config)) return active;
+	return restartRuntime(config, pi, ctx, host);
+}
+export async function restartRuntime(config: OnlyneConfig, pi: ExtensionAPI, ctx: ExtensionContext, host: RuntimeHost = {}): Promise<PluginRuntime> {
+	setLocale(resolveLocale(config.language));
+	await active?.close();
+	const runtime = new OmpRuntime(config, pi, ctx, host);
+	try { await runtime.start(); } catch (error) { await runtime.close(); throw error; }
+	active = runtime;
+	registerMsgTool(pi);
+	return runtime;
+}
+export async function stopRuntime(): Promise<void> { await active?.close(); }
+
+/** How often the discovery catalog is re-observed; well inside the library's 120 s freshness window. */
+const DISCOVERY_REFRESH_MS = 30_000;
+
+class OmpRuntime implements PluginRuntime {
+	readonly contexts: ContextRegistry;
+	readonly storage: SqliteStorage;
+	readonly mainAgentId: string;
+	node!: OnlyneNode;
+	decider!: JudgeDecider;
+	endpoint = "";
+	private server?: ReturnType<typeof Bun.serve>;
+	private keyDir?: string;
+	private network?: NetworkDiscovery;
+	/** The host's one periodic job: re-observing discovery. Delivery cadence belongs to the library. */
+	private timer?: Timer;
+	/** A round that outlives its interval must not overlap the next one. */
+	private rediscovering = false;
+	private discoveryError?: string;
+	private controller = new AbortController();
+	private listeners = new Set<() => void>();
+	private closed = false;
+	constructor(readonly config: OnlyneConfig, readonly pi: ExtensionAPI, readonly main: ExtensionContext, readonly host: RuntimeHost = {}) {
+		this.mainAgentId = main.agent.id;
+		this.storage = new SqliteStorage(join(dirname(config.path), "omp.db"));
+		this.contexts = new ContextRegistry(this.storage, config.node.id, main.agent.id);
+	}
+	async start(): Promise<void> {
+		let handler: (request: Request) => Promise<Response> = async () => new Response(t("initializing"), { status: 503 });
+		this.server = Bun.serve({ hostname: this.config.server.bind, port: 0, fetch: request => handler(request) });
+		const host = advertisedHost(this.config.server.bind);
+		this.endpoint = `http://${host.includes(":") ? `[${host}]` : host}:${this.server.port}/onlyne/v3`;
+		const instanceId = crypto.randomUUID();
+		// The decider probes peers for their execution contexts, so it must use the node's own
+		// transport: an unsigned probe is refused by every keyed peer.
+		let transport: OnlyneNode["transport"] | undefined;
+		this.decider = new JudgeDecider({
+			config: this.config, contexts: this.contexts, mainAgentId: this.mainAgentId,
+			resourceQuery: meta => resourceQuery(this.node, meta),
+			log: (message, fields) => {
+				// Judge decisions and their trims are the tuning record; everything else stays debug.
+				if (message.startsWith("onlyne.judge.")) this.pi.logger.info(message, fields);
+				else this.pi.logger.debug(message, fields);
+			},
+			listPeers: async () => (await this.node.discovery.listRecords()).filter(record => record.verified_at !== undefined && Date.parse(record.expires_at) > Date.now()),
+			listReceiverContexts: async id => id === this.config.node.id
+				? [
+						{ alias: "main", summary: t("main"), state: this.main.isIdle() ? "idle" : "running" },
+						// A lost or never-bound record cannot receive a continuation; advertising it
+						// would invite the sender to pick a context that fails on arrival.
+						...await this.contexts.list().then(records => records
+							.filter(record => record.state !== "lost" && record.state !== "unbound" && canAnswer(record))
+							.map(record => ({ alias: record.alias, summary: record.summary, state: record.state }))),
+					]
+				: transport!.request(id, "GET", "/contexts", undefined, this.controller.signal),
+			listThreads: () => allPages(cursor => this.node.threads.list(this.node.auth, { page_size: 100, cursor })),
+			listMessages: (thread, cursor) => this.node.messages.list(this.node.auth, thread, { attention: "thread", page_size: 100, cursor }),
+		});
+		const bridge = createRuntimeBridge({ pi: this.pi, main: this.main, decider: this.decider, contexts: this.contexts, nodeId: this.config.node.id });
+		const projectRoot = dirname(dirname(this.config.path));
+		// `node.key_scope` names where the identity lives. Without it the historic global
+		// store stays in effect; `none` runs the keyless loopback development binding. A
+		// refused project directory (git work tree without an ignore rule) fails the start.
+		const keyScope = this.config.node.key_scope ?? "global";
+		const keyDir = this.host.keys !== undefined || keyScope === "none" ? undefined : await ensureKeyDir(projectRoot, this.config.node.id, keyScope);
+		this.keyDir = keyDir;
+		// The library owns the maintenance cadence; the host only lends it one-shot session
+		// timers. The loop re-arms after every pass, so a repeating timer would double it.
+		const clock: MaintenanceClock = {
+			setTimer: (ms, run) => this.main.setTimeout(run, ms),
+			clearTimer: handle => this.main.clearTimer(handle as Timer),
+		};
+		this.node = createOnlyneNode({ config: this.config, endpoint: this.endpoint, instanceId, storage: this.storage, contexts: this.contexts, runtime: bridge, clock,
+			...(keyDir === undefined ? {} : { keyDir }),
+			...(this.host.keys === undefined ? {} : { keys: this.host.keys }),
+			decide: input => {
+				const scope = currentDecision();
+				if (!scope) throw new OnlyneError("decision_unavailable", "No OMP session is bound to this decision.");
+				scope.input = input;
+				return this.decider.decide(scope);
+			},
+		});
+		transport = this.node.transport;
+		const memberships = (await this.node.domains.list(this.node.auth)).items;
+		const current = memberships[0];
+		const mutation = () => ({ idempotency_key: crypto.randomUUID(), retry_until: new Date(Date.now() + 60_000).toISOString() });
+		if (current && current.domain_id !== this.config.region) await this.node.domains.leave(this.node.auth, current.domain_id, { ...mutation(), expected_revision: current.revision });
+		if (!current || current.domain_id !== this.config.region) {
+			let expected_revision: string | undefined;
+			try { expected_revision = (await this.node.domains.describe(this.node.auth, this.config.region)).revision; }
+			catch (error) { if (!(error instanceof OnlyneError && error.error.code === "not_found")) throw error; }
+			await this.node.domains.join(this.node.auth, this.config.region, { ...mutation(), expected_revision });
+		}
+		handler = request => this.node.fetch(request);
+		this.network = new NetworkDiscovery({ node_id: this.config.node.id, instance_id: instanceId, endpoint: this.endpoint, bind: this.config.server.bind,
+			onCandidate: async (url, source, expectedNode) => {
+				if (expectedNode === this.config.node.id) return;
+				await this.node.discovery.observe(url, source, expectedNode, this.controller.signal);
+				this.discoveryError = undefined;
+				this.changed();
+			},
+			onError: error => { this.discoveryError = errorText(error); this.pi.logger.warn("onlyne.discovery.failed", { error: errorText(error) }); },
+		});
+		try { await this.network.start(); } catch (error) { this.pi.logger.warn("onlyne.discovery.unavailable", { error: errorText(error) }); }
+		await this.contexts.ensureMain();
+		await this.node.client.recover(this.controller.signal);
+		// A saved seed is reached on every start, so a node that moved ports is found again even
+		// where mDNS never hears it. One unreachable seed is a logged fact, never a failed start,
+		// and the seeds are read together so a dead address costs one wait rather than one each.
+		await Promise.all((this.config.discovery?.seeds ?? []).map(async seed => {
+			try { await this.follow(seed); }
+			catch (error) { this.pi.logger.warn("onlyne.seed.failed", { seed, error: errorText(error) }); }
+		}));
+		this.changed();
+		this.node.client.runMaintenance();
+		this.rediscover();
+		this.timer = this.main.setInterval(() => this.rediscover(), DISCOVERY_REFRESH_MS);
+		this.pi.logger.info("onlyne.listening", { endpoint: this.endpoint, node: this.config.node.id, region: this.config.region });
+	}
+	/**
+	 * RFC 0017 §5: the library reports every committed trust transition, every inbound entry
+	 * and every pending-work flip here. The viewer repaints from it; it never polls storage
+	 * for these.
+	 */
+	notify(event: NotifyEvent): void {
+		if (event.event === "trust") {
+			this.pi.logger.info(`onlyne.trust.${event.cause}`, {
+				node: event.entry.node_id, phase: event.phase, fingerprint: event.entry.fingerprint,
+			});
+		}
+		this.changed();
+	}
+	onChange(listener: () => void): () => void { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+	private changed(): void { for (const listener of this.listeners) listener(); }
+	/**
+	 * A user-typed address. It is normalized once, read for its own identity and everything it
+	 * declares, and only a successful read becomes a seed. The node keeps running: a seed is a
+	 * routing hint, not a second binding.
+	 */
+	async contact(endpoint: string): Promise<void> {
+		const seed = normalizeServiceUrl(endpoint);
+		await this.follow(seed);
+		await this.rememberSeed(seed);
+		this.changed();
+	}
+	/**
+	 * Reads one address into the discovery catalog. The peer's own directory is a bonus: a
+	 * node that answers `/description` but not `/discovery` is still a usable neighbor.
+	 */
+	private async follow(seed: string): Promise<void> {
+		await this.node.discovery.observe(seed, "bootstrap", undefined, this.controller.signal);
+		await this.followDirectory(seed).catch(error => {
+			this.pi.logger.debug("onlyne.seed.directory", { seed, error: errorText(error) });
+		});
+	}
+	/** Every peer the address declares, each read on its own: one failure does not stop the rest. */
+	private async followDirectory(seed: string): Promise<void> {
+		const url = new URL(`${seed}/discovery`);
+		let cursor: string | undefined;
+		do {
+			url.search = "";
+			if (cursor) url.searchParams.set("cursor", cursor);
+			const response = await fetch(url, { signal: this.controller.signal });
+			if (!response.ok) throw new OnlyneError("unavailable", `Discovery directory answered HTTP ${response.status}.`);
+			const page = await response.json() as Page<DiscoveryCandidate>;
+			if (!Array.isArray(page.items)) throw new OnlyneError("invalid_request", "The discovery page has no items.");
+			for (const candidate of page.items) {
+				if (candidate.node_id === this.config.node.id) continue;
+				await this.node.discovery.observe(candidate.base_url, seed, candidate.node_id, this.controller.signal).catch(() => undefined);
+			}
+			cursor = page.next_cursor ?? undefined;
+		} while (cursor);
+	}
+	/** The seed list is configuration: one write per new address, and none on a start. */
+	private async rememberSeed(seed: string): Promise<void> {
+		const seeds = this.config.discovery?.seeds ?? [];
+		if (seeds.includes(seed)) return;
+		const saved = await saveConfig({ ...this.config, discovery: { seeds: [...seeds, seed] } });
+		this.config.discovery = saved.discovery;
+	}
+	/** Stage one of one exchange: the peer's proved fingerprint, and the session that commits it. */
+	async trustBegin(node: string): Promise<KeyExchange> {
+		return this.node.trust.begin(this.node.auth, node);
+	}
+	async trustAccept(node: string, fingerprint: string): Promise<void> {
+		await this.node.trust.accept(this.node.auth, node, fingerprint);
+	}
+	async trustRevoke(node: string): Promise<void> {
+		await this.node.trust.revoke(this.node.auth, node);
+	}
+	async trustRotate(): Promise<{ fingerprint: string }> {
+		const identity = await this.node.trust.rotate(this.node.auth);
+		return { fingerprint: identity.fingerprint };
+	}
+	async refreshDiscovery(): Promise<void> {
+		await this.node.discovery.refresh(this.controller.signal);
+		this.changed();
+	}
+	/** One discovery round on the host's timer; a failed round keeps the last good catalog. */
+	private rediscover(): void {
+		if (this.rediscovering) return;
+		this.rediscovering = true;
+		void this.refreshDiscovery()
+			.catch(error => { if (!this.closed) this.pi.logger.warn("onlyne.discovery.failed", { error: errorText(error) }); })
+			.finally(() => { this.rediscovering = false; });
+	}
+
+	async status(): Promise<OnlyneStatus> {
+		const records = await this.node.discovery.listRecords();
+		const inbox = await allPages(cursor => this.node.messages.inbox(this.node.auth, { page_size: 100, cursor }));
+		const at = Date.now();
+		// Reachable now: a fresh direct observation, never an expired or never-verified clue.
+		const reachable = new Set(records
+			.filter(record => record.verified_at !== undefined && Date.parse(record.expires_at) > at)
+			.map(record => record.node_id));
+		reachable.add(this.config.node.id);
+		// One hop is the set this node can actually address: peers it has verified and, when
+		// keys are in use, trusted. A clue from a relay is not a neighbor.
+		const peers = new Set(records
+			.filter(record => record.node_id !== this.config.node.id && record.verified_at !== undefined && Date.parse(record.expires_at) > at)
+			.map(record => record.node_id));
+		if (this.node.keys.enabled) {
+			const trusted = new Set((await this.node.trust.list(this.node.auth)).filter(entry => trustPhase(entry) === "exchanged").map(entry => entry.node_id));
+			for (const node of [...peers]) if (!trusted.has(node)) peers.delete(node);
+		}
+		// Live attention only: an acknowledged or consumed item is history, not an alert.
+		const alerts = inbox.filter(item => !item.attention.acked && !item.injected).length;
+		return {
+			region: this.config.region, node_id: this.config.node.id, nodes: reachable.size, neighbors: peers.size,
+			alerts, unread: inbox.filter(item => !item.injected).length,
+			...(this.discoveryError === undefined ? {} : { discovery_error: this.discoveryError }),
+		};
+	}
+	async snapshot(): Promise<ViewerSnapshot> {
+		const contexts = await this.contexts.list();
+		const records = await this.node.discovery.listRecords();
+		const inbox = await allPages(cursor => this.node.messages.inbox(this.node.auth, { page_size: 100, cursor }));
+		const views: ViewerThread[] = [];
+		// Hosted threads are read locally. A thread this node only belongs to lives on its
+		// owner, so it is shown from the attention rows already held here; the viewer never
+		// reaches across the network.
+		const hosted = new Set<string>();
+		for (const thread of await allPages(cursor => this.node.threads.list(this.node.auth, { page_size: 100, cursor }))) {
+			const ref = thread.thread_ref;
+			hosted.add(`${ref.owner}/${ref.id}`);
+			const entries = await allPages(cursor => this.node.messages.list(this.node.auth, ref, { attention: "thread", page_size: 100, cursor }));
+			views.push({ ref, alias: `${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`, title: thread.title, state: thread.state,
+				unread: inbox.filter(item => !item.injected && item.attention.thread_ref.owner === ref.owner && item.attention.thread_ref.id === ref.id).length,
+				last_seq: entries.at(-1)?.seq ?? "0", messages: entries.map(entry => ({ ref: { sender: entry.message.sender, id: entry.message.id }, seq: entry.seq, direction: entry.message.sender === this.config.node.id ? "out" : "in", author: entry.authenticated_author, at: entry.at, text: entry.message.msg, relation: entry.message.meta?.relation })),
+			});
+		}
+		// A member's own message never comes back through its inbox, so the message that
+		// opened a thread it only takes part in survives only in the outbound record that
+		// carried it. Read those here and merge them below the inbox rows, or the member
+		// sees the reply and not the question that started it.
+		const outbound = await this.storage.transaction(tx => tx.scan<Outbound>("outbound/"));
+		const seen = new Map<string, ViewerThread>();
+		for (const item of inbox) {
+			const ref = item.attention.thread_ref;
+			const key = `${ref.owner}/${ref.id}`;
+			if (hosted.has(key)) continue;
+			const view = seen.get(key) ?? { ref, alias: `${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`, title: t("thread", { node: shortNodeId(ref.owner) }), state: "open", unread: 0, last_seq: "0", messages: [] };
+			seen.set(key, view);
+			if (!item.injected) view.unread++;
+			const entry = item.attention.entry;
+			if (entry !== undefined) {
+				view.messages.push({ ref: { sender: entry.message.sender, id: entry.message.id }, seq: entry.seq, direction: entry.message.sender === this.config.node.id ? "out" : "in", author: entry.authenticated_author, at: entry.at, text: entry.message.msg, relation: entry.message.meta?.relation });
+				view.last_seq = entry.seq;
+			}
+		}
+		for (const row of outbound) {
+			const receipt = row.value.receipt;
+			if (receipt === undefined) continue;
+			const ref = receipt.thread_ref;
+			const key = `${ref.owner}/${ref.id}`;
+			if (hosted.has(key)) continue;
+			const view = seen.get(key) ?? { ref, alias: `${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`, title: t("thread", { node: shortNodeId(ref.owner) }), state: "open", unread: 0, last_seq: "0", messages: [] };
+			seen.set(key, view);
+			const message = row.value.request.message;
+			view.messages.push({ ref: { sender: message.sender, id: message.id }, seq: receipt.seq, direction: "out", author: message.sender, at: row.value.created_at ?? "", text: message.msg, relation: message.meta?.relation });
+			if (Number(receipt.seq) > Number(view.last_seq)) view.last_seq = receipt.seq;
+		}
+		for (const view of seen.values()) view.messages.sort((left, right) => Number(left.seq) - Number(right.seq));
+		views.push(...seen.values());
+		const queue: QueueItem[] = inbox.filter(item => !item.injected).map(item => ({ id: `inbound:${item.attention.obligation_id}`, kind: "inbound", label: `${item.attention.thread_ref.id}/${item.attention.seq}`, detail: t("pending", { author: item.attention.authenticated_author }), at: item.attention.entry?.at }));
+		queue.push(...contexts.filter(record => record.state === "running" || record.state === "unbound").map(record => ({ id: `context:${record.alias}`, kind: "context" as const, label: record.alias, detail: `${record.summary} · ${record.state}`, at: record.created_at })));
+		queue.push(...outbound.filter(row => row.value.state === "unknown" || row.value.state === "pending").map(row => ({ id: row.key, kind: "outbound" as const, label: row.value.request.target_endpoint, detail: row.value.state })));
+		const at = Date.now();
+		// One row per node: a node that moved ports would otherwise appear once per address.
+		// A verified record beats an unverified one; within each class the newest wins.
+		const byNode = new Map<string, DiscoveryRecord>();
+		for (const record of records) {
+			const kept = byNode.get(record.node_id);
+			if (kept === undefined || newerRecord(record, kept)) byNode.set(record.node_id, record);
+		}
+		const discovery: ViewerDiscovery[] = [...byNode.values()].map(record => ({
+			node_id: record.node_id, instance_id: record.instance_id, base_url: record.base_url, source: record.source,
+			...(record.membership?.domain_id === undefined ? {} : { region: record.membership.domain_id }),
+			...(record.membership?.state === undefined ? {} : { membership_state: record.membership.state }),
+			...(record.verified_at === undefined ? {} : { verified_at: record.verified_at }),
+			expires_at: record.expires_at, last_seen: record.last_seen,
+			...(record.error === undefined ? {} : { error: record.error.message }),
+		}));
+		const newest = new Map<string, DiscoveryRecord>();
+		for (const record of records) {
+			if (record.node_id === this.config.node.id || record.verified_at === undefined || Date.parse(record.expires_at) <= at) continue;
+			const kept = newest.get(record.node_id);
+			if (kept === undefined || newerRecord(record, kept)) newest.set(record.node_id, record);
+		}
+		const contacts: ViewerContact[] = [...newest.values()].map(record => ({
+			node_id: record.node_id, instance_id: record.instance_id, base_url: record.base_url,
+			...(record.membership?.domain_id === undefined ? {} : { region: record.membership.domain_id }),
+			last_seen: record.last_seen,
+		}));
+		const trust = this.node.keys.enabled ? await this.node.trust.list(this.node.auth) : [];
+		const identity = this.node.keys.enabled ? await this.node.keys.describe() : undefined;
+		return { region: this.config.region, endpoint: this.endpoint, contexts, queue, threads: views, discovery, contacts,
+			trust: trust.map(row => ({ node_id: row.node_id, fingerprint: row.fingerprint, phase: trustPhase(row), base_url: row.base_url })),
+			...(identity === undefined ? {} : { identity: { public_key: identity.public_key, fingerprint: identity.fingerprint } }),
+			...(this.discoveryError === undefined ? {} : { discovery_error: this.discoveryError }) };
+	}
+	async updateConfig(next: OnlyneConfig): Promise<void> { await saveConfig(next); await restartRuntime(next, this.pi, this.main, this.host); }
+	async close(): Promise<void> {
+		if (this.closed) return;
+		this.closed = true;
+		this.controller.abort();
+		if (this.timer) this.main.clearTimer(this.timer);
+		// A start that failed before the node existed still comes here to release the server.
+		this.node?.client.stopMaintenance();
+		await this.network?.close();
+		this.server?.stop(true);
+		this.storage.close();
+		this.listeners.clear();
+		if (active === this) active = undefined;
+	}
+}
+export async function allPages<T>(read: (cursor?: string) => Promise<Page<T>>): Promise<T[]> {
+	const items: T[] = [];
+	let cursor: string | undefined;
+	do { const page = await read(cursor); items.push(...page.items); cursor = page.next_cursor ?? undefined; } while (cursor);
+	return items;
+}
+
+function errorText(error: unknown): string { return error instanceof Error ? error.message : String(error); }
+
+/** A verified record beats an unverified one; within each class the newest observation wins. */
+function newerRecord(candidate: DiscoveryRecord, kept: DiscoveryRecord): boolean {
+	const candidateVerified = candidate.verified_at !== undefined;
+	const keptVerified = kept.verified_at !== undefined;
+	if (candidateVerified !== keptVerified) return candidateVerified;
+	return Date.parse(candidate.last_seen) > Date.parse(kept.last_seen);
+}

package/src/store.ts

@@ -0,0 +1,189 @@
+import { Database } from "bun:sqlite";
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type { Entry, Storage, ThreadRef, Transaction } from "@onlyne/lib";
+import type { ContextRecord } from "./types.ts";
+import { bridgeText as t } from "./bridge-text.ts";
+
+/** Key/value rows under one SQLite file; the library's durable state and the plugin's registry share it. */
+export class SqliteStorage implements Storage {
+	readonly guarantee = "durable" as const;
+	readonly #db: Database;
+	#tail: Promise<unknown> = Promise.resolve();
+	#closed = false;
+
+	constructor(path: string) {
+		// The store carries trust rows and, while a rotation is unacknowledged, the old private
+		// key that proves it. It is secret material: 0700 for the directory, 0600 for the files,
+		// including the WAL and shared-memory sidecars SQLite creates beside them.
+		const dir = dirname(path);
+		mkdirSync(dir, { recursive: true, mode: 0o700 });
+		chmodSync(dir, 0o700);
+		this.#db = new Database(path, { create: true });
+		this.#db.exec("PRAGMA journal_mode = WAL");
+		this.#db.exec("PRAGMA synchronous = FULL");
+		this.#db.exec("PRAGMA busy_timeout = 5000");
+		this.#db.exec("CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
+		for (const file of [path, `${path}-wal`, `${path}-shm`]) {
+			if (existsSync(file)) chmodSync(file, 0o600);
+		}
+	}
+
+	/** Serialize every transaction; SQLite's own BEGIN IMMEDIATE would otherwise race across awaits. */
+	transaction<T>(work: (tx: Transaction) => Promise<T>): Promise<T> {
+		const run = () => this.#execute(work);
+		const result = this.#tail.then(run, run);
+		this.#tail = result.then(
+			() => undefined,
+			() => undefined,
+		);
+		return result;
+	}
+
+	async #execute<T>(work: (tx: Transaction) => Promise<T>): Promise<T> {
+		if (this.#closed) throw new Error(t("storeClosed"));
+		this.#db.exec("BEGIN IMMEDIATE");
+		const tx: Transaction = {
+			get: async <V>(key: string) => this.#get<V>(key),
+			put: async <V>(key: string, value: V) => this.#put(key, value),
+			delete: async (key: string) => {
+				this.#db.query("DELETE FROM kv WHERE key = ?").run(key);
+			},
+			scan: async <V>(prefix: string) => this.#scan<V>(prefix),
+		};
+		try {
+			const value = await work(tx);
+			this.#db.exec("COMMIT");
+			return value;
+		} catch (error) {
+			try {
+				this.#db.exec("ROLLBACK");
+			} catch {
+				// The transaction may already be gone; preserve the original failure.
+			}
+			throw error;
+		}
+	}
+
+	#get<T>(key: string): T | undefined {
+		const row = this.#db.query<{ value: string }, [string]>("SELECT value FROM kv WHERE key = ?").get(key);
+		return row === null ? undefined : (JSON.parse(row.value) as T);
+	}
+
+	#put(key: string, value: unknown): void {
+		this.#db
+			.query("INSERT INTO kv (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+			.run(key, JSON.stringify(value));
+	}
+
+	#scan<T>(prefix: string): Array<{ key: string; value: T }> {
+		const rows = this.#db
+			.query<{ key: string; value: string }, [number, string]>(
+				"SELECT key, value FROM kv WHERE substr(key, 1, ?) = ? ORDER BY key",
+			)
+			.all(prefix.length, prefix);
+		return rows.map(row => ({ key: row.key, value: JSON.parse(row.value) as T }));
+	}
+
+	close(): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#db.close();
+	}
+}
+
+const COUNTER_KEY = "meta/context-counter";
+const CONTEXT_PREFIX = "context/";
+
+/**
+ * Whether a registered context can answer a delivery. Only the session holding this node's
+ * own send right can: a subagent context reads and drafts, never sends. Advertising one as a
+ * continuation target hands the sender a message nobody there can reply to, and the sender
+ * has no way to see that from the alias (caerulea report 4, problem 7).
+ */
+export function canAnswer(record: ContextRecord): boolean {
+	return record.agent_id !== undefined && record.agent_id === record.main_agent_id;
+}
+
+/** Alias allocation and binding for execution contexts; the store is the authority across restarts. */
+export class ContextRegistry {
+	constructor(private readonly storage: Storage, private readonly nodeId: string, private readonly mainAgentId: string) {}
+
+	/** The main OMP session is addressable like a registered execution context. */
+	async ensureMain(): Promise<ContextRecord> {
+		return this.storage.transaction(async tx => {
+			const key = `${CONTEXT_PREFIX}main`;
+			const current = await tx.get<ContextRecord>(key);
+			if (current !== undefined) return current;
+			const record: ContextRecord = {
+				alias: "main", node_id: this.nodeId, main_agent_id: this.mainAgentId, agent_id: this.mainAgentId,
+				summary: t("mainSummary"), state: "idle", created_at: new Date().toISOString(),
+			};
+			await tx.put(key, record);
+			return record;
+		});
+	}
+
+	async allocate(thread_ref: ThreadRef | undefined, summary: string, source?: Entry["message"]): Promise<ContextRecord> {
+		return this.storage.transaction(async tx => {
+			const counter = (await tx.get<number>(COUNTER_KEY)) ?? 0;
+			const next = counter + 1;
+			await tx.put(COUNTER_KEY, next);
+			const alias = `c-${String(next)}`;
+			const record: ContextRecord = {
+				alias,
+				node_id: this.nodeId,
+				main_agent_id: this.mainAgentId,
+				...(source === undefined ? {} : { source: { sender: source.sender, id: source.id } }),
+				...(thread_ref === undefined ? {} : { thread_ref }),
+				summary,
+				state: "unbound",
+				created_at: new Date().toISOString(),
+			};
+			await tx.put(`${CONTEXT_PREFIX}${alias}`, record);
+			return record;
+		});
+	}
+
+	async bind(
+		alias: string,
+		binding: { agent_id: string; session_file?: string; parent_id?: string },
+	): Promise<ContextRecord> {
+		return this.storage.transaction(async tx => {
+			const key = `${CONTEXT_PREFIX}${alias}`;
+			const current = await tx.get<ContextRecord>(key);
+			if (current === undefined) throw new Error(t("contextNotRegistered", { alias }));
+			const next: ContextRecord = {
+				...current,
+				agent_id: binding.agent_id,
+				...(binding.session_file === undefined ? {} : { session_file: binding.session_file }),
+				...(binding.parent_id === undefined ? {} : { parent_id: binding.parent_id }),
+				state: current.agent_id === binding.agent_id ? current.state : "idle",
+				bound_at: new Date().toISOString(),
+			};
+			await tx.put(key, next);
+			return next;
+		});
+	}
+
+	async find(alias: string): Promise<ContextRecord | undefined> {
+		return this.storage.transaction(tx => tx.get<ContextRecord>(`${CONTEXT_PREFIX}${alias}`));
+	}
+
+	async list(): Promise<ContextRecord[]> {
+		return this.storage.transaction(async tx =>
+			(await tx.scan<ContextRecord>(CONTEXT_PREFIX)).map(row => row.value),
+		);
+	}
+
+	async updateState(alias: string, state: ContextRecord["state"]): Promise<ContextRecord | undefined> {
+		return this.storage.transaction(async tx => {
+			const key = `${CONTEXT_PREFIX}${alias}`;
+			const current = await tx.get<ContextRecord>(key);
+			if (current === undefined) return undefined;
+			const next = { ...current, state };
+			await tx.put(key, next);
+			return next;
+		});
+	}
+}

package/src/tern.ts

@@ -0,0 +1,66 @@
+/**
+ * Tern identity for the bootstrap defaults.
+ *
+ * `TERN_PANE` is the block id the process runs in. `tern ls --json` is the
+ * supported query for the session that owns a block; a missing binary, a
+ * non-zero exit, malformed JSON or an unknown block all return `undefined`.
+ * The caller may fall back to its own default, but this module never guesses a
+ * session name from the cwd or from a prefix.
+ */
+
+interface TernBlock {
+	id?: unknown;
+}
+
+interface TernTab {
+	blocks?: TernBlock[];
+}
+
+interface TernSession {
+	name?: unknown;
+	tabs?: TernTab[];
+}
+
+interface TernList {
+	sessions?: TernSession[];
+}
+
+/** The Tern block this process runs in, when Tern set it. */
+export function detectTernBlock(): string | undefined {
+	const block = process.env.TERN_PANE?.trim();
+	return block === undefined || block.length === 0 ? undefined : block;
+}
+
+/** The session name owning `block` (default: this process's block), `onlyne:` stripped. */
+export function detectTernSession(block: string | undefined = detectTernBlock()): string | undefined {
+	if (block === undefined) return undefined;
+	let output: string;
+	try {
+		const result = Bun.spawnSync([process.env.TERN_ACP ?? "tern", "ls", "--json"], {
+			stdout: "pipe",
+			stderr: "ignore",
+		});
+		if (result.exitCode !== 0) return undefined;
+		output = new TextDecoder().decode(result.stdout);
+	} catch {
+		return undefined;
+	}
+	let parsed: TernList;
+	try {
+		parsed = JSON.parse(output) as TernList;
+	} catch {
+		return undefined;
+	}
+	const sessions = Array.isArray(parsed.sessions) ? parsed.sessions : [];
+	for (const session of sessions) {
+		const tabs = Array.isArray(session.tabs) ? session.tabs : [];
+		for (const tab of tabs) {
+			const blocks = Array.isArray(tab.blocks) ? tab.blocks : [];
+			if (!blocks.some(candidate => String(candidate.id) === block)) continue;
+			if (typeof session.name !== "string") return undefined;
+			const name = session.name.replace(/^onlyne:/, "").trim();
+			return name.length === 0 ? undefined : name;
+		}
+	}
+	return undefined;
+}