omp-onlyne 0.1.0 → 0.3.0

package/src/runtime.ts

@@ -1,18 +1,33 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 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 { OnlyneError, trustPhase, type DiscoveryCandidate, type DiscoveryRecord, type KeyExchange, type KeyHook, type MaintenanceClock, type NotifyEvent, type OnlyneNode, type Outbound, type Page, type TrustEntry } 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 { acquisitionOf, evaluateAcquisition, type AcquireInput, type AcquireVerdict } from "@onlyne/node-host/acquire";
+import { AcquisitionLog, approvePeer, beginPeer, handshakeEntry, isTrustThread, judgeApproval, judgementFacts, revokePeer, trustThread, TRUST_THREAD, type ApprovalDeps, type ApprovalJudgement, type ApprovalRequest } from "./handshake.ts";
 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 { advertisedHost, createOnlyneNode } from "@onlyne/node-host/node";
+import { canAnswer, ContextRegistry, SqliteStorage } from "@onlyne/node-host/store";
 import { resourceQuery } from "./resources.ts";
-import type { OnlyneConfig, OnlyneStatus, QueueItem, ViewerContact, ViewerDiscovery, ViewerMessage, ViewerSnapshot, ViewerThread } from "./types.ts";
+import type { OnlyneConfig } from "@onlyne/node-host/types";
+import type { AcquisitionAuditEntry, OnlyneStatus, QueueItem, ViewerContact, ViewerDiscovery, ViewerMessage, ViewerSnapshot, ViewerThread, ViewerTrustRow } from "./types.ts";
+
+/** The trust transition of RFC 0017 §5, as the host receives it. */
+type TrustNotify = Extract<NotifyEvent, { event: "trust" }>;
+
+/** Which actor a judgement in flight belongs to: the agent that asked, or the policy approving on its own. */
+interface AuditScope {
+	actor: AcquisitionAuditEntry["actor"];
+	action: string;
+	/** The judgement this scope produced, kept because a refusal throws away the value the caller sees. */
+	capture?: (judgement: ApprovalJudgement) => void;
+}
 
 export interface PluginRuntime {
 	readonly config: OnlyneConfig;
@@ -32,9 +47,16 @@ export interface PluginRuntime {
 	contact(endpoint: string): Promise<void>;
 	/** Stage one of one exchange; the returned session carries the fingerprint the peer proved. */
 	trustBegin(node: string): Promise<KeyExchange>;
+	/** A human's confirmation in the panel: RFC 0018 §2 keeps that gate outside the policy. */
 	trustAccept(node: string, fingerprint: string): Promise<void>;
 	trustRevoke(node: string): Promise<void>;
 	trustRotate(): Promise<{ fingerprint: string }>;
+	/** RFC 0018 §2/§3.1: an agent's approval, judged against the acquisition policy first. */
+	acquireAccept(node: string, fingerprint: string): Promise<TrustEntry>;
+	/** RFC 0018 §2/§3.1: an agent's revocation. The policy never applies to dropping a peer. */
+	acquireRevoke(node: string): Promise<void>;
+	/** RFC 0018 §2/§3.1: an agent's initiation, judged before the key read that would begin it. */
+	acquireBegin(node: string): Promise<TrustEntry>;
 	refreshDiscovery(): Promise<void>;
 	updateConfig(next: OnlyneConfig): Promise<void>;
 	close(): Promise<void>;
@@ -61,11 +83,45 @@ export async function restartRuntime(config: OnlyneConfig, pi: ExtensionAPI, ctx
 	registerMsgTool(pi);
 	return runtime;
 }
-export async function stopRuntime(): Promise<void> { await active?.close(); }
+export async function stopRuntime(): Promise<void> {
+	const closing = active;
+	active = undefined;
+	await closing?.close();
+}
 
 /** How often the discovery catalog is re-observed; well inside the library's 120 s freshness window. */
 const DISCOVERY_REFRESH_MS = 30_000;
 
+/**
+ * The discovery layer's loopback switch. `createOnlyneNode` passes no `plugins.allow_loopback`,
+ * so this host always runs the documented default; the panel reports it beside the policy.
+ */
+const ALLOW_LOOPBACK = false;
+/** Audit rows kept in the store; the panel renders the newest 20, pruning keeps the file bounded. */
+const AUDIT_PREFIX = "acquisition/audit/";
+const AUDIT_KEEP = 64;
+const AUDIT_VISIBLE = 20;
+
+/** The alias the context registry gives this node's main session (`ContextRegistry.ensureMain`). */
+const MAIN_CONTEXT = "main";
+
+/** One mutation's identity for the library: a fresh key and a window that outlives this call. */
+function mutation(): { idempotency_key: string; retry_until: string } {
+	return { idempotency_key: crypto.randomUUID(), retry_until: new Date(Date.now() + 60_000).toISOString() };
+}
+
+/** The port a configured public_url names, defaulting by scheme; undefined when it names none. */
+function publicPort(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	try {
+		const url = new URL(value);
+		if (url.port !== "") return Number(url.port);
+		return url.protocol === "https:" ? 443 : 80;
+	} catch {
+		return undefined;
+	}
+}
+
 class OmpRuntime implements PluginRuntime {
 	readonly contexts: ContextRegistry;
 	readonly storage: SqliteStorage;
@@ -73,6 +129,15 @@ class OmpRuntime implements PluginRuntime {
 	node!: OnlyneNode;
 	decider!: JudgeDecider;
 	endpoint = "";
+	/** RFC 0018 §2.1: where the connection being served came from, for the library's own call into `notify`. */
+	private readonly connection = new AsyncLocalStorage<string | undefined>();
+	/** RFC 0018 §5: the actor a judgement in flight belongs to, so the audit can tell an agent from the policy. */
+	private readonly auditScope = new AsyncLocalStorage<AuditScope>();
+	/** Two audit rows can share a millisecond; the tick keeps their stored order equal to their arrival. */
+	private auditTick = 0;
+	private readonly log: AcquisitionLog;
+	/** The host side of one approval, built once with the node in `start`. */
+	private peers!: ApprovalDeps;
 	private server?: ReturnType<typeof Bun.serve>;
 	private keyDir?: string;
 	private network?: NetworkDiscovery;
@@ -88,12 +153,60 @@ class OmpRuntime implements PluginRuntime {
 		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);
+		this.log = new AcquisitionLog(this.storage);
 	}
 	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) });
+		// RFC 0018 §2.1: the address a peer statement arrived from is known only here. The
+		// library calls `notify` synchronously from inside the request it is serving, so the
+		// connection's own store is still in scope when the trust event is handled.
+		const serve = (port: number) => Bun.serve({
+			hostname: this.config.server.bind, port,
+			fetch: (request, server) => this.connection.run(server.requestIP(request)?.address, () => handler(request)),
+		});
+		// A configured public_url is a promise about where this node answers. Advertising it
+		// without listening there leaves every peer that pinned the address calling a port
+		// nobody serves, so the port is taken unless it is already in use. Without a public_url
+		// the port this node last bound is reused: an address that changes on every start is one
+		// every peer has to be taught again, and the operator's only recourse is to pin it by hand.
+		const wanted = publicPort(this.config.server.public_url) ?? this.config.server.port;
+		let fellBack = false;
+		// `server.port` is optional because Bun omits it for a unix socket; this listener is TCP.
+		let bound: number;
+		try {
+			this.server = serve(wanted ?? 0);
+			bound = this.server.port!;
+		} catch (error) {
+			if (wanted === undefined) throw error;
+			fellBack = true;
+			this.server = serve(0);
+			bound = this.server.port!;
+			this.pi.logger.warn("onlyne.port.taken", { wanted, bound, error: errorText(error) });
+		}
 		const host = advertisedHost(this.config.server.bind);
-		this.endpoint = `http://${host.includes(":") ? `[${host}]` : host}:${this.server.port}/onlyne/v3`;
+		const actual = `http://${host.includes(":") ? `[${host}]` : host}:${bound}/onlyne/v3`;
+		this.endpoint = this.config.server.public_url === undefined || fellBack ? actual : normalizeServiceUrl(this.config.server.public_url);
+		// The port the system chose is this node's address for as long as it keeps it. Writing it
+		// back is what makes the next start answer where the peers already look, and it costs one
+		// file write on the first start and none afterwards.
+		if (this.config.server.public_url === undefined && this.config.server.port !== bound) {
+			await this.rememberPort(bound);
+		}
+		// RFC 0018 §2.3/§5.1: a trust seed is a human pre-authorization the policy never judges,
+		// so the bypass is written where it can be re-read: one line per seed naming the config
+		// file it came from, and the policy status beside it. A fingerprint is the audit fact,
+		// never a credential. The discovery axis is separate and, like the policy, reported here.
+		const policy = acquisitionOf(this.config);
+		this.pi.logger.info("onlyne.acquisition.policy", {
+			policy: policy.policy, allow: [...policy.allow],
+			allow_loopback: ALLOW_LOOPBACK,
+		});
+		for (const seed of this.config.trust ?? []) {
+			this.pi.logger.info("onlyne.acquisition.seed", {
+				node: seed.node_id, fingerprint: seed.fingerprint, source: this.config.path,
+				actor: "human", conclusion: "seed_authorized",
+			});
+		}
 		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.
@@ -107,6 +220,9 @@ class OmpRuntime implements PluginRuntime {
 				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()),
+			listTrust: async () => (await this.node.trust.list(this.node.auth)).map(row => ({
+				node_id: row.node_id, phase: trustPhase(row), base_url: row.base_url,
+			})),
 			listReceiverContexts: async id => id === this.config.node.id
 				? [
 						{ alias: "main", summary: t("main"), state: this.main.isIdle() ? "idle" : "running" },
@@ -117,8 +233,24 @@ class OmpRuntime implements PluginRuntime {
 							.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 }),
+			// RFC 0018 §3.2: the handshake thread is this host's own record, never a candidate
+			// for a conversation the agent routes or reads by name.
+			listThreads: async () => (await allPages(cursor => this.node.threads.list(this.node.auth, { page_size: 100, cursor })))
+				.filter(thread => !isTrustThread(this.config.node.id, thread.thread_ref)),
+			listJoinedThreads: async () => (await allPages(cursor => this.node.threads.joined(this.node.auth, { page_size: 100, cursor })))
+				.filter(thread => !isTrustThread(this.config.node.id, thread.thread_ref)),
+			// A joined thread's entries live on its owner; this node holds no local copy, so the
+			// owner's message route is the only source. Both legs keep the same page shape, and
+			// resolving a joined `{thread, seq}` reference now reads the entries it names.
+			listMessages: async (thread, cursor) => {
+				const query = { attention: "thread" as const, page_size: 100, ...(cursor === undefined ? {} : { cursor }) };
+				return thread.owner === this.config.node.id
+					? this.node.messages.list(this.node.auth, thread, query)
+					: this.node.client.threadEntries(thread, query);
+			},
+			listInbox: async () => (await allPages(cursor => this.node.messages.inbox(this.node.auth, { page_size: 100, cursor })))
+				.map(row => ({ context: row.context, attention: row.attention })),
+			threadMembers: async thread => (await this.node.threads.describe(this.node.auth, thread)).members.map(member => member.peer),
 		});
 		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));
@@ -145,14 +277,28 @@ class OmpRuntime implements PluginRuntime {
 			},
 		});
 		transport = this.node.transport;
+		this.peers = {
+			policy: acquisitionOf(this.config),
+			log: this.log,
+			observed: async (nodeId, fingerprint) => (await this.log.observation(nodeId, fingerprint))?.observed,
+			declared: async nodeId => (await this.node.trust.entry(nodeId))?.base_url,
+			recorded: nodeId => this.recorded(nodeId),
+			audit: judgement => {
+				this.pi.logger.info("onlyne.acquire.decided", judgementFacts(judgement));
+				// The caller decided the actor; a judgement made with no scope is the policy's own.
+				this.auditScope.getStore()?.capture?.(judgement);
+			},
+			accept: (nodeId, fingerprint) => this.node.trust.accept(this.node.auth, nodeId, fingerprint),
+			revoke: nodeId => this.node.trust.revoke(this.node.auth, nodeId),
+			now: () => new Date().toISOString(),
+		};
 		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; }
+			catch (error) { if (!isNotFoundError(error)) throw error; }
 			await this.node.domains.join(this.node.auth, this.config.region, { ...mutation(), expected_revision });
 		}
 		handler = request => this.node.fetch(request);
@@ -191,11 +337,169 @@ class OmpRuntime implements PluginRuntime {
 			this.pi.logger.info(`onlyne.trust.${event.cause}`, {
 				node: event.entry.node_id, phase: event.phase, fingerprint: event.entry.fingerprint,
 			});
+			// RFC 0018 §2.1: the address this statement arrived from exists only inside the
+			// call the library is making right now, and nothing after it can recover it.
+			this.trustEvent(event, this.connection.getStore());
 		}
 		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(); }
+	/**
+	 * RFC 0018 §2/§3: one trust transition's host work — the observation its statement's
+	 * connection left, the judgement of an invitation this host may approve itself, and the
+	 * handshake entry the agent reads. Everything is reported by the library's own call, so it
+	 * runs beside it; a failure here is logged and is never a reason to doubt the committed row.
+	 */
+	private trustEvent(event: TrustNotify, observed: string | undefined): void {
+		void this.handleTrust(event, observed).catch(error => {
+			this.pi.logger.warn("onlyne.trust.handling_failed", { node: event.entry.node_id, phase: event.phase, error: errorText(error) });
+		});
+	}
+	private async handleTrust(event: TrustNotify, observed: string | undefined): Promise<void> {
+		const node = event.entry.node_id;
+		const fingerprint = event.entry.fingerprint;
+		// The address is recorded for every peer statement, before its verdict. Local
+		// transitions never replace it with the address of the approval call (which has none),
+		// so an approval decided later still reads the statement's original connection.
+		const at = new Date().toISOString();
+		if (event.cause === "peer-statement") {
+			await this.log.observe(node, fingerprint, {
+				...(observed === undefined ? {} : { observed }), at, cause: event.cause,
+			});
+		} else await this.log.transition(node, fingerprint, at, event.cause);
+		// RFC 0018 §2.3/§5: a pinned seed is a human pre-authorization the policy never judges.
+		// The startup log lists the seeds; this row records the statement that actually used one.
+		const seed = (this.config.trust ?? []).find(row => row.node_id === node && row.fingerprint === fingerprint);
+		if (event.cause === "peer-statement" && seed !== undefined) {
+			await this.recordAudit({
+				at, actor: "seed", action: "seed_authorized", node_id: node, fingerprint,
+				...(observed === undefined ? {} : { observed }),
+				...(event.entry.base_url === "" ? {} : { declared: event.entry.base_url }),
+				policy: this.peers.policy.policy, allowed: true, reason: "seed_authorized", override: true, source: this.config.path,
+			});
+		}
+		// RFC 0018 §2.2: the verdict reads the catalog as it stood when the statement arrived.
+		// The record this host derives from that statement is not part of the judgement, or the
+		// two conditions would collapse into one.
+		const recorded = await this.recorded(node);
+		// The statement's own address is also a discovery candidate here, as the tern host's
+		// bridge records it.
+		if (event.entry.base_url) {
+			await this.node.discovery.observe(event.entry.base_url, "trust-statement", node).catch(() => undefined);
+		}
+		// §2.2: only an invitation whose statement covered a connection this host observed, and
+		// whose declared and recorded addresses all stay inside the allow set, is committed
+		// without a human deciding first.
+		const judgement = event.phase === "invited" && event.cause === "peer-statement"
+			? await judgeApproval(this.peers, { node_id: node, fingerprint, observed, recorded })
+			: undefined;
+		// §4.1: a verdict is audited whether it allows the approval or refuses it.
+		if (judgement !== undefined) await this.recordAudit(this.auditEntry(judgement, "policy", "approve"));
+		if (judgement?.verdict.allowed === true) this.approveDeferred(node, fingerprint);
+		await this.deliverHandshake(event, observed, judgement);
+	}
+	/**
+	 * RFC 0018 §2: the approval an invitation earned is committed outside the library's call,
+	 * so the admission that notified this host is never re-entered.
+	 */
+	private approveDeferred(node: string, fingerprint: string): void {
+		queueMicrotask(() => {
+			void this.peers.accept(node, fingerprint)
+				.catch(error => this.pi.logger.warn("onlyne.acquire.approve_failed", { node, error: errorText(error) }));
+		});
+	}
+	/**
+	 * RFC 0018 §3: one handshake entry per `(node, fingerprint, phase)`, written into this
+	 * node's own thread under a plan bound to the main session. The thread has this node as its
+	 * only member, so the entry never leaves the node.
+	 */
+	private async deliverHandshake(event: TrustNotify, observed: string | undefined, judgement: ApprovalJudgement | undefined): Promise<void> {
+		const node = event.entry.node_id;
+		const fingerprint = event.entry.fingerprint;
+		if (await this.log.delivered(node, fingerprint, event.phase)) return;
+		const handshake = handshakeEntry({
+			node_id: node, fingerprint, phase: event.phase, declared: event.entry.base_url, observed,
+			policy: this.peers.policy, judgement, approved: judgement?.verdict.allowed === true,
+		});
+		await this.ensureTrustThread();
+		const outcome = await this.node.client.send(this.config.node.id, {
+			id: crypto.randomUUID(),
+			sender: this.config.node.id,
+			delivery_kind: "trust",
+			msg: handshake.msg,
+			// The mention is what puts the entry in this node's own inbox: the delivery plan
+			// names the main context, and the bridge reads the facts for its todo hook.
+			meta: { thread: trustThread(this.config.node.id), mentions: [this.config.node.id], data: { trust: handshake.trust } },
+		}, { response: "none", execution: "existing", context: MAIN_CONTEXT });
+		if (outcome.admission !== "accepted") {
+			this.pi.logger.warn("onlyne.trust.delivery_failed", { node, phase: event.phase, error: outcome.error?.message });
+			return;
+		}
+		await this.log.markDelivered(node, fingerprint, event.phase, new Date().toISOString());
+	}
+	/** RFC 0018 §3.2: the handshake thread, created on first use. Its id is fixed, so it is one thread for the node's lifetime. */
+	private async ensureTrustThread(): Promise<void> {
+		const ref = trustThread(this.config.node.id);
+		try {
+			await this.node.threads.describe(this.node.auth, ref);
+			return;
+		} catch (error) {
+			if (!isNotFoundError(error)) throw error;
+		}
+		await this.node.threads.create(this.node.auth, { title: TRUST_THREAD, id: ref.id, ...mutation() });
+	}
+	/** RFC 0018 §2.2: every address discovery holds for this node is an outbound candidate the policy must allow. */
+	private async recorded(node: string): Promise<string[]> {
+		const records = await this.node.discovery.listRecords();
+		return [...new Set(records.filter(record => record.node_id === node).map(record => record.base_url))];
+	}
+	/**
+	 * The persisted acquisition audit. One row per fact, keyed by its own time so the scan is the
+	 * history; the oldest rows are pruned past `AUDIT_KEEP`, and the panel reads the newest
+	 * `AUDIT_VISIBLE` back out. A failed write is logged and never doubts a committed decision.
+	 */
+	private async recordAudit(entry: AcquisitionAuditEntry): Promise<void> {
+		if (this.closed) return;
+		try {
+			await this.storage.transaction(async tx => {
+				const rows = await tx.scan<AcquisitionAuditEntry>(AUDIT_PREFIX);
+				await tx.put(`${AUDIT_PREFIX}${entry.at}/${String(this.auditTick++).padStart(12, "0")}-${crypto.randomUUID()}`, entry);
+				const excess = rows.length + 1 - AUDIT_KEEP;
+				for (const row of rows.slice(0, Math.max(0, excess))) await tx.delete(row.key);
+			});
+		} catch (error) {
+			this.pi.logger.warn("onlyne.acquisition.audit_failed", { error: errorText(error) });
+		}
+	}
+	/** One judgement as the audit stores it: the time, the actor, and every input the verdict read. */
+	private auditEntry(judgement: ApprovalJudgement, actor: AcquisitionAuditEntry["actor"], action: string): AcquisitionAuditEntry {
+		return {
+			at: judgement.at, actor, action, node_id: judgement.node_id,
+			...(judgement.fingerprint === undefined ? {} : { fingerprint: judgement.fingerprint }),
+			...(judgement.input.observed === undefined ? {} : { observed: judgement.input.observed }),
+			...(judgement.input.declared === undefined ? {} : { declared: judgement.input.declared }),
+			policy: judgement.policy.policy, allowed: judgement.verdict.allowed, reason: judgement.verdict.reason,
+		};
+	}
+	/**
+	 * What the policy would say about this peer right now, read from the same stored facts a
+	 * judgement reads. The human path asks only to mark an override; it never gates the action.
+	 */
+	private async policyVerdict(node: string, fingerprint?: string): Promise<{ observed?: string; declared?: string; verdict: AcquireVerdict }> {
+		const observed = fingerprint === undefined ? undefined : (await this.log.observation(node, fingerprint))?.observed;
+		const declared = (await this.node.trust.entry(node))?.base_url;
+		const input: AcquireInput = {
+			...(observed === undefined || observed === "" ? {} : { observed }),
+			...(declared === undefined || declared === "" ? {} : { declared }),
+			recorded: await this.recorded(node),
+		};
+		return {
+			...(observed === undefined ? {} : { observed }),
+			...(declared === undefined ? {} : { declared }),
+			verdict: await evaluateAcquisition(this.peers.policy, input),
+		};
+	}
 	/**
 	 * 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
@@ -242,18 +546,90 @@ class OmpRuntime implements PluginRuntime {
 		const saved = await saveConfig({ ...this.config, discovery: { seeds: [...seeds, seed] } });
 		this.config.discovery = saved.discovery;
 	}
+	/**
+	 * The listening port is configuration for the same reason a seed is: a peer holds the
+	 * address it last reached, and a node that answers somewhere new has moved without telling
+	 * anyone. One write on the first start, and one more only after a port conflict moved it.
+	 */
+	private async rememberPort(port: number): Promise<void> {
+		const saved = await saveConfig({ ...this.config, server: { ...this.config.server, port } });
+		this.config.server = saved.server;
+		this.pi.logger.info("onlyne.port.persisted", { port, path: this.config.path });
+	}
 	/** 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);
+		const session = await this.node.trust.begin(this.node.auth, node);
+		await this.recordAudit({
+			at: new Date().toISOString(), actor: "human", action: "begin",
+			node_id: node, fingerprint: session.fingerprint, declared: session.base_url,
+		});
+		return session;
 	}
 	async trustAccept(node: string, fingerprint: string): Promise<void> {
+		// The panel keeps the human gate outside the policy (RFC 0018 §2). Read the verdict first
+		// so a row the policy would have refused is recorded as the override it is.
+		const admission = await this.policyVerdict(node, fingerprint);
 		await this.node.trust.accept(this.node.auth, node, fingerprint);
+		await this.recordAudit({
+			at: new Date().toISOString(), actor: "human", action: "accept", node_id: node, fingerprint,
+			...(admission.observed === undefined ? {} : { observed: admission.observed }),
+			...(admission.declared === undefined ? {} : { declared: admission.declared }),
+			policy: this.peers.policy.policy, allowed: admission.verdict.allowed, reason: admission.verdict.reason,
+			...(admission.verdict.allowed ? {} : { override: true }),
+		});
 	}
 	async trustRevoke(node: string): Promise<void> {
+		const row = await this.node.trust.entry(node);
+		const observed = row === undefined ? undefined : (await this.log.observation(node, row.fingerprint))?.observed;
 		await this.node.trust.revoke(this.node.auth, node);
+		await this.recordAudit({
+			at: new Date().toISOString(), actor: "human", action: "revoke", node_id: node,
+			...(row === undefined ? {} : { fingerprint: row.fingerprint, declared: row.base_url }),
+			...(observed === undefined ? {} : { observed }),
+		});
+	}
+	/** RFC 0018 §2/§3.1: the agent's approval, refused with `policy_denied` when the policy does not allow it. */
+	async acquireAccept(node: string, fingerprint: string): Promise<TrustEntry> {
+		let judged: ApprovalJudgement | undefined;
+		try {
+			return await this.auditScope.run({ actor: "agent", action: "accept", capture: judgement => { judged = judgement; } },
+				() => approvePeer(this.peers, node, fingerprint));
+		} finally {
+			if (judged !== undefined) await this.recordAudit(this.auditEntry(judged, "agent", "accept"));
+		}
+	}
+	/** RFC 0018 §2/§3.1: the agent's revocation, which no policy judges. */
+	async acquireRevoke(node: string): Promise<void> {
+		await revokePeer(this.peers, node);
+		await this.recordAudit({ at: new Date().toISOString(), actor: "agent", action: "revoke", node_id: node });
+	}
+	/**
+	 * RFC 0018 §2/§3.1: the agent's initiation of one exchange. The judgement reads only what this
+	 * host already stores; the peer's key is read after it, so a refusal sends nothing.
+	 */
+	async acquireBegin(node: string): Promise<TrustEntry> {
+		let judged: ApprovalJudgement | undefined;
+		try {
+			return await this.auditScope.run({ actor: "agent", action: "begin", capture: judgement => { judged = judgement; } }, async () => {
+				const row = await this.node.trust.entry(node);
+				const statement = row === undefined ? undefined : (await this.log.observation(node, row.fingerprint))?.observed;
+				const records = (await this.node.discovery.listRecords()).filter(record => record.node_id === node);
+				const observed = outboundObserved({ statement, records, declared: row?.base_url });
+				const request: ApprovalRequest = {
+					node_id: node,
+					...(row === undefined ? {} : { fingerprint: row.fingerprint }),
+					...(observed === undefined ? {} : { observed }),
+				};
+				const committed = await beginPeer(this.peers, target => this.node.trust.begin(this.node.auth, target), request);
+				return committed.entry;
+			});
+		} finally {
+			if (judged !== undefined) await this.recordAudit(this.auditEntry(judged, "agent", "begin"));
+		}
 	}
 	async trustRotate(): Promise<{ fingerprint: string }> {
 		const identity = await this.node.trust.rotate(this.node.auth);
+		await this.recordAudit({ at: new Date().toISOString(), actor: "human", action: "rotate", fingerprint: identity.fingerprint });
 		return { fingerprint: identity.fingerprint };
 	}
 	async refreshDiscovery(): Promise<void> {
@@ -307,10 +683,13 @@ class OmpRuntime implements PluginRuntime {
 		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}`);
+			// RFC 0018 §3.2: the handshake entries stay out of the conversation tree. The
+			// thread is still recorded above, so its own inbox rows are not re-rendered here.
+			if (isTrustThread(this.config.node.id, ref)) continue;
 			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 })),
+				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, ...(entry.message.meta?.work === undefined ? {} : { work: entry.message.meta.work }) })),
 			});
 		}
 		// A member's own message never comes back through its inbox, so the message that
@@ -319,16 +698,25 @@ class OmpRuntime implements PluginRuntime {
 		// 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>();
+		// A grant can arrive before any message, and a thread this node was invited into is a row
+		// the viewer must show. The local joined listing supplies those rows; the owner is never
+		// asked here, so the viewer stays a read of this node's own records.
+		for (const row of await allPages(cursor => this.node.threads.joined(this.node.auth, { page_size: 100, cursor }))) {
+			const ref = row.thread_ref;
+			const key = `${ref.owner}/${ref.id}`;
+			if (hosted.has(key) || seen.has(key)) continue;
+			seen.set(key, { ref, alias: `${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.id)}`, title: t("thread", { node: shortNodeId(ref.owner) }), state: "open", unread: 0, last_seq: row.last_seq, messages: [], read_only: true });
+		}
 		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: [] };
+			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: [], read_only: true };
 			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.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, ...(entry.message.meta?.work === undefined ? {} : { work: entry.message.meta.work }) });
 				view.last_seq = entry.seq;
 			}
 		}
@@ -338,10 +726,10 @@ class OmpRuntime implements PluginRuntime {
 			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: [] };
+			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: [], read_only: true };
 			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 });
+			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, ...(message.meta?.work === undefined ? {} : { work: message.meta.work }) });
 			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));
@@ -377,9 +765,28 @@ class OmpRuntime implements PluginRuntime {
 			last_seen: record.last_seen,
 		}));
 		const trust = this.node.keys.enabled ? await this.node.trust.list(this.node.auth) : [];
+		// RFC 0018 §2.1: the declared address is what the peer wrote; the observed one is the
+		// connection this host recorded for its last statement. Both are shown, never merged.
+		const trustRows: ViewerTrustRow[] = [];
+		for (const row of trust) {
+			const observation = await this.log.observation(row.node_id, row.fingerprint);
+			trustRows.push({
+				node_id: row.node_id, fingerprint: row.fingerprint, phase: trustPhase(row), base_url: row.base_url,
+				...(observation?.observed === undefined ? {} : { observed: observation.observed }),
+			});
+		}
+		// Newest first: the panel renders this array in order and never sorts it.
+		const auditRows = await this.storage.transaction(tx => tx.scan<AcquisitionAuditEntry>(AUDIT_PREFIX));
+		const audit = auditRows
+			.sort((left, right) => right.value.at.localeCompare(left.value.at) || right.key.localeCompare(left.key))
+			.slice(0, AUDIT_VISIBLE)
+			.map(row => row.value);
+		const policy = acquisitionOf(this.config);
 		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 })),
+			trust: trustRows,
+			acquisition: { policy: policy.policy, allow: [...policy.allow], allow_loopback: ALLOW_LOOPBACK },
+			audit,
 			...(identity === undefined ? {} : { identity: { public_key: identity.public_key, fingerprint: identity.fingerprint } }),
 			...(this.discoveryError === undefined ? {} : { discovery_error: this.discoveryError }) };
 	}
@@ -407,6 +814,35 @@ export async function allPages<T>(read: (cursor?: string) => Promise<Page<T>>):
 
 function errorText(error: unknown): string { return error instanceof Error ? error.message : String(error); }
 
+/** Check if an error represents an Onlyne not_found condition, independent of instanceof identity. */
+function isNotFoundError(error: unknown): boolean {
+	if (error instanceof OnlyneError) return error.error.code === "not_found";
+	if (typeof error === "object" && error !== null) {
+		const failure = (error as { error?: { code?: string } }).error;
+		if (failure?.code === "not_found") return true;
+		if ((error as { message?: string }).message === "The requested record is unavailable.") return true;
+	}
+	return false;
+}
+
+/**
+ * RFC 0018 §2.1–2.2: the address an outbound judgement reads for a peer this host may initiate
+ * with. The arrival address this host recorded for the peer's last statement is the strongest
+ * fact it holds; a peer that never sent one is judged at an address discovery verified by
+ * probing, and with no record at all at the address the library's own fallback would connect to.
+ */
+export function outboundObserved(facts: {
+	statement?: string;
+	records: readonly DiscoveryRecord[];
+	declared?: string;
+}): string | undefined {
+	if (facts.statement !== undefined && facts.statement !== "") return facts.statement;
+	const verified = facts.records
+		.filter(record => record.verified_at !== undefined)
+		.sort((left, right) => right.received_at.localeCompare(left.received_at));
+	return verified[0]?.base_url ?? (facts.declared === "" ? undefined : facts.declared);
+}
+
 /** 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;