omp-onlyne 0.1.0 → 0.2.0

package/src/handshake.ts

@@ -0,0 +1,291 @@
+import { OnlyneError, type Json, type KeyExchange, type Message, type NodeId, type Storage, type ThreadRef, type TrustEntry, type TrustPhase } from "@onlyne/lib";
+import { evaluateAcquisition, type AcquireInput, type AcquireVerdict, type AcquisitionPolicy } from "./acquire.ts";
+import { bridgeText as t } from "./bridge-text.ts";
+import { hostText } from "./host-text.ts";
+
+/**
+ * RFC 0018 §3.2: the handshake entries live in one thread this node owns alone, so nothing in
+ * them ever leaves the node, and the business thread tree stays a record of conversations
+ * rather than a log of system events.
+ */
+export const TRUST_THREAD = "trust";
+
+export function trustThread(nodeId: NodeId): ThreadRef {
+	return { owner: nodeId, id: TRUST_THREAD };
+}
+
+export function isTrustThread(nodeId: NodeId, ref: ThreadRef | undefined): boolean {
+	return ref !== undefined && ref.owner === nodeId && ref.id === TRUST_THREAD;
+}
+
+/** RFC 0018 §2.1: where one peer statement's connection arrived from. */
+export interface StatementObservation {
+	/** The address the connection came from; absent when this host could not observe one. */
+	observed?: string;
+	at: string;
+	cause: string;
+}
+
+const OBSERVED = "acquire/observed/";
+const DELIVERED = "acquire/delivered/";
+
+function observedKey(nodeId: NodeId, fingerprint: string): string {
+	return `${OBSERVED}${encodeURIComponent(nodeId)}/${encodeURIComponent(fingerprint)}`;
+}
+
+function deliveredKey(nodeId: NodeId, fingerprint: string, phase: TrustPhase): string {
+	return `${DELIVERED}${encodeURIComponent(nodeId)}/${encodeURIComponent(fingerprint)}/${phase}`;
+}
+
+/**
+ * RFC 0018 §2.1/§3: the two durable records this host keeps about a handshake. The observed
+ * address is written for every statement, before any verdict, so an approval decided later
+ * reads the address that statement itself arrived from and never the address of the call that
+ * asks (§2.1). The delivered records are one per `(node_id, fingerprint, phase)`, so a
+ * replayed event appends no second entry.
+ */
+export class AcquisitionLog {
+	constructor(private readonly storage: Storage) {}
+
+	async observe(nodeId: NodeId, fingerprint: string, observation: StatementObservation): Promise<void> {
+		await this.storage.transaction(tx => tx.put(observedKey(nodeId, fingerprint), observation));
+	}
+
+	/**
+	 * A local transition is still an observed trust event, but it must not replace the address
+	 * of the peer statement. Keep its timestamp and cause beside the original address instead.
+	 */
+	async transition(nodeId: NodeId, fingerprint: string, at: string, cause: string): Promise<void> {
+		await this.storage.transaction(async tx => {
+			const key = observedKey(nodeId, fingerprint);
+			const current = await tx.get<StatementObservation>(key);
+			await tx.put(key, { ...(current?.observed === undefined ? {} : { observed: current.observed }), at, cause });
+		});
+	}
+
+	async observation(nodeId: NodeId, fingerprint: string): Promise<StatementObservation | undefined> {
+		return this.storage.transaction(tx => tx.get<StatementObservation>(observedKey(nodeId, fingerprint)));
+	}
+
+	async delivered(nodeId: NodeId, fingerprint: string, phase: TrustPhase): Promise<boolean> {
+		return (await this.storage.transaction(tx => tx.get(deliveredKey(nodeId, fingerprint, phase)))) !== undefined;
+	}
+
+	async markDelivered(nodeId: NodeId, fingerprint: string, phase: TrustPhase, at: string): Promise<void> {
+		await this.storage.transaction(tx => tx.put(deliveredKey(nodeId, fingerprint, phase), { node_id: nodeId, fingerprint, phase, at }));
+	}
+
+	/**
+	 * RFC 0018 §3: the reports an agent already acted on are settled. A revocation names no
+	 * fingerprint, so it settles every report held for the node; a later statement opens its own.
+	 */
+	async settle(nodeId: NodeId, fingerprint?: string): Promise<void> {
+		const prefix = `${DELIVERED}${encodeURIComponent(nodeId)}/${fingerprint === undefined ? "" : `${encodeURIComponent(fingerprint)}/`}`;
+		await this.storage.transaction(async tx => {
+			for (const row of await tx.scan(prefix)) await tx.delete(row.key);
+		});
+	}
+}
+
+/** The machine facts a handshake entry carries beside its body (RFC 0018 §3). */
+export interface HandshakeFacts {
+	node_id: NodeId;
+	fingerprint: string;
+	phase: TrustPhase;
+	/** Whether this entry owes an agent decision; a status update owes none. */
+	pending: boolean;
+}
+
+/** The facts one handshake entry carries, or undefined for an entry that is not one. */
+export function handshakeFacts(meta: Message["meta"] | undefined): HandshakeFacts | undefined {
+	const value = meta?.data?.trust;
+	if (value === null || value === undefined || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const row = value as Record<string, Json>;
+	const { node_id: node, fingerprint, phase, pending } = row;
+	if (typeof node !== "string" || typeof fingerprint !== "string" || typeof pending !== "boolean") return undefined;
+	if (phase !== "invited" && phase !== "requested" && phase !== "exchanged" && phase !== "revoked") return undefined;
+	return { node_id: node, fingerprint, phase, pending };
+}
+
+export interface HandshakeInput {
+	node_id: NodeId;
+	fingerprint: string;
+	phase: TrustPhase;
+	/** The address the peer wrote into its own statement. */
+	declared: string;
+	/** The address that statement arrived from; absent when this host observed none. */
+	observed?: string;
+	policy: AcquisitionPolicy;
+	/** The judgement made for this event, when one was made. */
+	judgement?: ApprovalJudgement;
+	/** Whether an approval was committed without an agent deciding first. */
+	approved: boolean;
+}
+
+/**
+ * RFC 0018 §3: one handshake entry. The body carries what the judgement read and concluded;
+ * the action identifiers appear only when a decision is actually owed, and a status update
+ * says so instead. `pending` is the same fact for the host's todo hook.
+ */
+export function handshakeEntry(input: HandshakeInput): { msg: string; trust: { [key: string]: Json } } {
+	// RFC 0018 §3: only an invitation this host did not approve itself is work. A pending local
+	// approval waits on the peer, so there is nothing to do and nothing to wake a turn for.
+	const pending = input.phase === "invited" && !input.approved;
+	const lines = [
+		t("trustHeader", { phase: input.phase, node: input.node_id }),
+		t("trustFingerprint", { fingerprint: input.fingerprint }),
+		t("trustDeclared", { declared: input.declared }),
+		t("trustObserved", { observed: input.observed ?? t("trustUnobserved") }),
+		t("trustPolicy", { policy: input.policy.policy }),
+	];
+	if (input.judgement !== undefined) {
+		lines.push(t("trustJudgement", {
+			reason: input.judgement.verdict.reason,
+			conclusion: input.judgement.verdict.allowed ? t("trustAllowed") : t("trustRefused"),
+		}));
+	}
+	if (input.phase === "invited") lines.push(input.approved ? t("trustApproved") : t("trustInvited"));
+	else if (input.phase === "requested") lines.push(t("trustRequested"));
+	else if (input.phase === "exchanged") lines.push(t("trustExchanged"));
+	else lines.push(t("trustRevoked"));
+	if (input.phase === "invited" && !input.approved) {
+		// RFC 0018 §3: under `none` the agent may only look. Offering an action the policy
+		// refuses would ask for a decision that can never be made.
+		lines.push(input.policy.policy === "none"
+			? t("trustPanelOnly")
+			: t("trustAcceptAction", { node: input.node_id, fingerprint: input.fingerprint }));
+	}
+	if (pending) lines.push(t("trustRevokeAction", { node: input.node_id }));
+	return { msg: lines.join("\n"), trust: { node_id: input.node_id, fingerprint: input.fingerprint, phase: input.phase, pending } };
+}
+
+/** RFC 0018 §2: one approval judgement and every input it read. */
+export interface ApprovalJudgement {
+	at: string;
+	node_id: NodeId;
+	/** Absent when no fingerprint has been proved yet: an initiation reads the peer's key after the gate. */
+	fingerprint?: string;
+	policy: AcquisitionPolicy;
+	input: AcquireInput;
+	verdict: AcquireVerdict;
+}
+
+/** The judgement as the audit line records it: the time, the peer, and every input the verdict read. */
+export function judgementFacts(judgement: ApprovalJudgement): Record<string, unknown> {
+	const { input, verdict } = judgement;
+	return {
+		at: judgement.at,
+		node: judgement.node_id,
+		fingerprint: judgement.fingerprint ?? null,
+		policy: judgement.policy.policy,
+		allow: [...judgement.policy.allow],
+		observed: input.observed ?? null,
+		declared: input.declared ?? null,
+		recorded: [...(input.recorded ?? [])],
+		allowed: verdict.allowed,
+		reason: verdict.reason,
+		...(verdict.matched === undefined ? {} : { matched: verdict.matched }),
+	};
+}
+
+/** Everything the judgement reads from the host, and the two calls it may then commit. */
+export interface ApprovalDeps {
+	policy: AcquisitionPolicy;
+	log: AcquisitionLog;
+	/** RFC 0018 §2.1: the address the peer's last statement arrived from, as this host recorded it. */
+	observed(nodeId: NodeId, fingerprint: string): Promise<string | undefined>;
+	/** The address the peer wrote into its own statement, never the address of this call. */
+	declared(nodeId: NodeId): Promise<string | undefined>;
+	/** Every discovery address recorded for this node id; each is an outbound candidate (§2.2). */
+	recorded(nodeId: NodeId): Promise<string[]>;
+	/** The audit line, written whether or not the verdict allows the approval (§4.1). */
+	audit(judgement: ApprovalJudgement): void;
+	accept(nodeId: NodeId, fingerprint: string): Promise<TrustEntry>;
+	revoke(nodeId: NodeId): Promise<void>;
+	now(): string;
+}
+
+export interface ApprovalRequest {
+	node_id: NodeId;
+	/** The fingerprint the peer proved. Omitted by an initiation, whose key read comes after the gate. */
+	fingerprint?: string;
+	/** The statement's own connection address, when the caller is holding it. */
+	observed?: string;
+	/**
+	 * The discovery addresses as they stood when the statement arrived (RFC 0018 §2.2). A record
+	 * this host derives from the statement itself is not part of the judgement.
+	 */
+	recorded?: string[];
+}
+
+/**
+ * RFC 0018 §2: the one judgement, read by both the agent path and the auto-approval path.
+ * `observed` is the address a recorded statement arrived from — the caller's live connection
+ * address only when it is judging the statement it just received — and the declared address
+ * and every recorded address are checked with it (§2.1–2.2).
+ */
+export async function judgeApproval(deps: ApprovalDeps, request: ApprovalRequest): Promise<ApprovalJudgement> {
+	const observed = request.observed
+		?? (request.fingerprint === undefined ? undefined : await deps.observed(request.node_id, request.fingerprint));
+	const declared = await deps.declared(request.node_id);
+	const input: AcquireInput = {
+		...(observed === undefined || observed === "" ? {} : { observed }),
+		...(declared === undefined || declared === "" ? {} : { declared }),
+		recorded: request.recorded ?? await deps.recorded(request.node_id),
+	};
+	const judgement: ApprovalJudgement = {
+		at: deps.now(), node_id: request.node_id, fingerprint: request.fingerprint,
+		policy: deps.policy, input, verdict: await evaluateAcquisition(deps.policy, input),
+	};
+	deps.audit(judgement);
+	return judgement;
+}
+
+/** The refusal an agent-initiated approval gets. A refused approval is not a revocation: the peer's row is left as it is. */
+export function approvalRefused(judgement: ApprovalJudgement): OnlyneError {
+	const { policy, verdict } = judgement;
+	return new OnlyneError("forbidden", hostText("acquireDenied", { policy: policy.policy, reason: verdict.reason }), {
+		policy_denied: verdict.reason,
+		policy: policy.policy,
+		...(judgement.input.observed === undefined ? {} : { observed: judgement.input.observed }),
+		...(judgement.input.declared === undefined ? {} : { declared: judgement.input.declared }),
+	});
+}
+
+/** RFC 0018 §2/§3.1: the agent's `trust_accept`, judged before anything is committed. */
+export async function approvePeer(deps: ApprovalDeps, nodeId: NodeId, fingerprint: string): Promise<TrustEntry> {
+	const judgement = await judgeApproval(deps, { node_id: nodeId, fingerprint });
+	if (!judgement.verdict.allowed) throw approvalRefused(judgement);
+	const entry = await deps.accept(nodeId, fingerprint);
+	await deps.log.settle(nodeId, fingerprint);
+	return entry;
+}
+
+/**
+ * RFC 0018 §2/§3.1: the agent's `trust_begin`. The judgement reads stored facts only and runs
+ * before `exchange`, which is this path's first outbound request — the key read that starts the
+ * exchange — so a refusal sends nothing and leaves the peer's row untouched. On an allow the
+ * library commits the local approval and mails the statement, and the entry it returns carries
+ * the phase that commit produced.
+ */
+export async function beginPeer(
+	deps: ApprovalDeps,
+	exchange: (nodeId: NodeId) => Promise<KeyExchange>,
+	request: ApprovalRequest,
+): Promise<{ session: KeyExchange; entry: TrustEntry }> {
+	const judgement = await judgeApproval(deps, request);
+	if (!judgement.verdict.allowed) throw approvalRefused(judgement);
+	const session = await exchange(request.node_id);
+	const entry = await session.confirm(session.fingerprint);
+	await deps.log.settle(request.node_id, entry.fingerprint);
+	return { session, entry };
+}
+
+/**
+ * RFC 0018 §2: the agent's `trust_revoke`, never judged. The policy decides who may come in;
+ * it has no say over who may be turned away, which is also why this path reads no address.
+ */
+export async function revokePeer(deps: ApprovalDeps, nodeId: NodeId): Promise<void> {
+	await deps.revoke(nodeId);
+	await deps.log.settle(nodeId);
+}

package/src/host-text.ts

@@ -14,8 +14,8 @@ const en = {
   bindEmpty: "server.bind must not be empty.",
   bindShape: "server.bind must be a hostname or IP address, got {value}.",
   pageSizeRange: "threads.page_size must be an integer from 1 to 100, got {value}.",
-  retiredEndpoint: "node.endpoint is not supported; the endpoint comes from server.bind and the assigned port.",
-  retiredPort: "server.port is not supported; the operating system assigns the listening port.",
+  retiredEndpoint: "node.endpoint is not supported; the endpoint comes from server.bind and the listening port.",
+  portRange: "server.port must be an integer from 0 to 65535, got {value}.",
   retiredPeers: "peers is not supported; peers are discovered over the network and kept in the project SQLite.",
   retiredOmp: "omp is not supported; delivery and spawning are decided by the OMP judge.",
   retiredAttention: "threads.default_attention is not supported; reads default to the attention list.",
@@ -25,6 +25,9 @@ const en = {
   stringArrayExpected: "{field} must be an array of non-empty strings.",
   trustArray: "{path}: trust must be an array of tables.",
   trustEntry: "{path}: a trust entry needs node_id and a 16-character fingerprint.",
+  acquirePolicy: "acquisition.policy must be all, segment or none, got {value}.",
+  acquireAllow: "acquisition.allow entries must be network/prefix blocks, got {value}.",
+  acquireDenied: "The acquisition policy {policy} refused this approval: {reason}.",
   addressUnavailable: "No concrete network address is available for this bind host.",
   keyProvider: "External credential references need a host key provider.",
   loopbackBind: "The unauthenticated development binding requires a loopback bind host. Create a node key to serve a remote address.",
@@ -56,8 +59,8 @@ const zh: Record<keyof typeof en, string> = {
   bindEmpty: "server.bind 不能为空。",
   bindShape: "server.bind 必须是主机名或 IP 地址，收到的是 {value}。",
   pageSizeRange: "threads.page_size 必须是 1 到 100 之间的整数，收到的是 {value}。",
-  retiredEndpoint: "不支持 node.endpoint；端点由 server.bind 和系统分配的端口决定。",
-  retiredPort: "不支持 server.port；监听端口由操作系统分配。",
+  retiredEndpoint: "不支持 node.endpoint；端点由 server.bind 和监听端口决定。",
+  portRange: "server.port 必须是 0 到 65535 之间的整数，收到的是 {value}。",
   retiredPeers: "不支持 peers；对端通过网络发现，并保存在项目 SQLite 中。",
   retiredOmp: "不支持 omp；投送与派生由 OMP judge 决定。",
   retiredAttention: "不支持 threads.default_attention；读取默认使用关注列表。",
@@ -67,6 +70,9 @@ const zh: Record<keyof typeof en, string> = {
   stringArrayExpected: "{field} 必须是非空字符串数组。",
   trustArray: "{path}: trust 必须是表数组。",
   trustEntry: "{path}: 每条 trust 记录需要 node_id 和 16 个字符的指纹。",
+  acquirePolicy: "acquisition.policy 必须是 all、segment 或 none，收到的是 {value}。",
+  acquireAllow: "acquisition.allow 的条目必须是 network/prefix 形式，收到的是 {value}。",
+  acquireDenied: "获取策略 {policy} 拒绝了这次批准：{reason}。",
   addressUnavailable: "这个绑定主机没有可用的具体网络地址。",
   keyProvider: "外部凭据引用需要主机密钥提供者。",
   loopbackBind: "未认证的开发绑定需要回环绑定主机。要对外提供服务，请创建节点密钥。",

package/src/messages.ts

@@ -8,6 +8,7 @@ import type { ContextRecord } from "./types.ts";
 import { AWAIT_CONSUMED, pendingAwaitResults } from "./tool.ts";
 import { applyMessageTodo, type TodoPlanner } from "./todo.ts";
 import { getRuntime } from "./runtime.ts";
+import { handshakeFacts } from "./handshake.ts";
 import { bridgeText as t } from "./bridge-text.ts";
 
 export const INBOUND = "onlyne.inbound";
@@ -20,6 +21,8 @@ export interface BridgeDeps {
 	decider: JudgeDecider;
 	contexts: ContextRegistry;
 	nodeId: string;
+	/** Wall clock, so the escalation window can be tested without waiting for it. */
+	now?: () => number;
 }
 /**
  * One inbound entry is judged once per process. A retry replays the recorded decision
@@ -31,8 +34,44 @@ interface InboundAttempt {
 	decision?: InboundDecision;
 	failure?: OnlyneError;
 	landed?: string;
+	/** Maintenance passes this entry has been reported landed without being confirmed. */
+	passes?: number;
+	/** Whether the held delivery has already been forced through as a trigger. */
+	escalated?: boolean;
+	/** Set once the second window passed with no confirmation; the warning is written once. */
+	unconfirmed?: boolean;
+	/** How the delivery was submitted: a trigger starts work, a next-turn fragment waits. */
+	delivery?: { via: "trigger" | "nextTurn"; at: number };
 }
+
+/**
+ * How long a next-turn fragment may stay unread before the host offers it again. A turn takes at
+ * least one provider round trip, so a window measured in maintenance passes fires while the
+ * session is still working and duplicates the delivery (dpdp report, follow_up queue).
+ */
+const NEXT_TURN_ESCALATE_MS = 60_000;
+/** Times an entry may be decided again after its binding went away before it is delivered instead. */
+const MAX_REDECISIONS = 2;
 const inboundAttempts = new Map<string, InboundAttempt>();
+/**
+ * Deliveries attempted per entry, kept outside the attempt record: dropping that record is what
+ * makes the next pass decide again, and it must not reset the budget that bounds the deciding.
+ */
+const deliveryAttempts = new Map<string, number>();
+
+function countedAttempt(key: string): number {
+	const next = (deliveryAttempts.get(key) ?? 0) + 1;
+	deliveryAttempts.set(key, next);
+	return next;
+}
+
+/** The end of the line for an entry nothing can hold: the main session takes it once, visibly. */
+function escalate(deps: BridgeDeps, entry: Entry, key: string, reason: string) {
+	const token = registerPending(entry, deps.main.agent.id, "fragment");
+	deps.pi.sendMessage(payload(entry, INBOUND, token), { triggerTurn: true });
+	deps.pi.logger.info("onlyne.delivery.escalated", { entry: key, reason, attempts: deliveryAttempts.get(key) });
+	return { context: deps.main.agent.id, consumed: false, outcome: "delivered" as const };
+}
 
 function inboundKey(entry: Entry): string {
 	return `${entry.thread_ref.owner}/${entry.thread_ref.id}/${entry.seq}`;
@@ -41,6 +80,7 @@ function inboundKey(entry: Entry): string {
 const TRACE_DEBUG = new Set(["inbound.inject", "inbound.duplicate"]);
 
 export function createRuntimeBridge(deps: BridgeDeps): Runtime {
+	const now = deps.now ?? Date.now;
 	return {
 		/**
 		 * Admission is the last cheap place to refuse a plan this host cannot honor (RFC 0005
@@ -87,23 +127,68 @@ export function createRuntimeBridge(deps: BridgeDeps): Runtime {
 				});
 			}
 			if (attempt.failure !== undefined) {
+				// A lost binding cannot be re-decided into existence: past the budget the entry is
+				// delivered to the main session instead, so the judgement stops burning model calls
+				// and the message stops being invisible.
+				if (attempt.failure.error.code === "context_lost" && countedAttempt(key) > MAX_REDECISIONS) {
+					return escalate(deps, entry, key, "context-lost");
+				}
 				deps.pi.logger.debug("onlyne.delivery.held", { entry: key, reason: "judge-failed", error: attempt.failure.message });
 				throw attempt.failure;
 			}
 			const decision = attempt.decision;
 			if (decision === undefined) throw new OnlyneError("decision_unavailable", t("noDecision"));
-			if (decision.action === "new_subagent") {
-				attempt.landed ??= await startSubagent(deps, entry);
-				// A spawn is a submission, not a read: the child's prompt carries the token and its
-				// first provider request is the proof, so nothing is consumed here.
-				return { context: attempt.landed, consumed: false, outcome: "delivered" as const };
-			}
 			// The body is already where the decision put it; re-sending it would append a
 			// second copy that the cursor can only confirm once.
 			if (attempt.landed !== undefined) {
+			// RFC 0008 §5: a delivery is landed only while the context holding it can still
+			// confirm it. A subagent session that ended leaves the entry unconfirmed forever,
+			// and reporting it delivered on every maintenance pass is a retry storm, not a
+			// delivery. Mark the dead binding lost and let the next pass decide again.
+			const holder = (await deps.contexts.list()).find(record => record.agent_id === attempt.landed);
+			if (holder !== undefined && holder.state !== "idle" && holder.state !== "running") {
+				if (countedAttempt(key) > MAX_REDECISIONS) return escalate(deps, entry, key, "context-lost");
+				await deps.contexts.updateState(holder.alias, "lost").catch(() => undefined);
+				inboundAttempts.delete(key);
+				throw new OnlyneError("context_lost", t("contextLost", { alias: holder.alias }), { context: holder.alias });
+			}
+			// A delivery nobody confirmed has two shapes and one bound. A next-turn fragment waits
+			// for an assembly the session may never reach. A trigger starts its own turn, and that
+			// turn can die before the model reads the payload — a provider response at or above 400
+			// drops the observation it recorded — leaving the entry unconfirmed while every pass
+			// reports it delivered. Both are retried once, after a window long enough to be sure the
+			// session is not simply working, and only while it is idle right now.
+			attempt.passes = (attempt.passes ?? 0) + 1;
+			const delivery = attempt.delivery;
+			const waiting = delivery !== undefined && now() - delivery.at >= NEXT_TURN_ESCALATE_MS;
+			if (attempt.landed === deps.main.agent.id && waiting && delivery !== undefined && deps.main.isIdle()) {
+				if (attempt.escalated !== true) {
+					attempt.escalated = true;
+					// The retry opens its own window; measuring the second one from the first send
+					// would report it as unconfirmed on the very next pass.
+					attempt.delivery = { via: "trigger", at: now() };
+					const token = registerPending(entry, deps.main.agent.id, "fragment");
+					deps.pi.sendMessage(payload(entry, INBOUND, token), { triggerTurn: true });
+					deps.pi.logger.info("onlyne.delivery.escalated", {
+						entry: key, reason: "unconfirmed", via: delivery.via, waited_ms: now() - delivery.at,
+					});
+				} else if (attempt.unconfirmed !== true) {
+					// One warning per entry: the reason is recorded once, and the pass stops shouting.
+					attempt.unconfirmed = true;
+					deps.pi.logger.warn("onlyne.delivery.unconfirmed", {
+						entry: key, via: delivery.via, passes: attempt.passes, waited_ms: now() - delivery.at, context: attempt.landed,
+					});
+				}
+			}
 				deps.pi.logger.debug("onlyne.delivery.held", { entry: key, reason: "already-delivered", context: attempt.landed });
 				return { context: attempt.landed, consumed: false, outcome: "delivered" as const };
 			}
+			if (decision.action === "new_subagent") {
+				attempt.landed = await startSubagent(deps, entry);
+				// A spawn is a submission, not a read: the child's prompt carries the token and its
+				// first provider request is the proof, so nothing is consumed here.
+				return { context: attempt.landed, consumed: false, outcome: "delivered" as const };
+			}
 			if (decision.action === "context") {
 				const alias = decision.context;
 				if (alias === undefined) throw new OnlyneError("decision_unavailable", t("noContextNamed"));
@@ -137,8 +222,15 @@ export function createRuntimeBridge(deps: BridgeDeps): Runtime {
 					payload(entry, INBOUND, token),
 					mode === undefined ? { triggerTurn: true } : { deliverAs: mode === "steer" ? "steer" : "followUp" },
 				);
+				attempt.delivery = { via: "trigger", at: now() };
 			} else {
-				deps.pi.sendMessage(payload(entry, INBOUND, token), { deliverAs: "nextTurn" });
+				// RFC 0008 §7: a fragment enters the next context assembly without starting a turn.
+				// An idle session never reaches that assembly by itself, so the entry would sit in
+				// the queue as `injected: false` forever; idle means there is no turn to wait for.
+				const idle = deps.main.isIdle();
+				deps.pi.sendMessage(payload(entry, INBOUND, token), idle ? { triggerTurn: true } : { deliverAs: "nextTurn" });
+				if (idle) deps.pi.logger.info("onlyne.delivery.escalated", { entry: key, reason: "idle-fragment" });
+				attempt.delivery = { via: idle ? "trigger" : "nextTurn", at: now() };
 			}
 			attempt.landed = deps.main.agent.id;
 			deps.pi.logger.info("onlyne.delivery.sent", {
@@ -149,6 +241,13 @@ export function createRuntimeBridge(deps: BridgeDeps): Runtime {
 		},
 		todo: async (entry, context) => {
 			inboundAttempts.delete(inboundKey(entry));
+			deliveryAttempts.delete(inboundKey(entry));
+			// RFC 0018 §3: a handshake status update is delivered for the record, not as work.
+			// Only an entry that owes a decision takes the todo decision path.
+			if (handshakeFacts(entry.message.meta)?.pending === false) {
+				refreshMailCards();
+				return;
+			}
 			const planner: TodoPlanner = {
 				decideTodo: (incoming, current) => deps.decider.decideTodo(deps.main, incoming, current),
 			};
@@ -172,8 +271,7 @@ const pending = new Map<string, PendingObservation>();
 const toolResults = new Map<string, PendingObservation>();
 const observed = new Map<string, string[]>();
 
-function registerPending(entry: Entry, context: string, kind: PendingObservation["kind"]): string {
-	const token = `onlyne-${crypto.randomUUID()}`;
+function registerPending(entry: Entry, context: string, kind: PendingObservation["kind"], token = `onlyne-${crypto.randomUUID()}`): string {
 	pending.set(token, { entry, context, kind });
 	return token;
 }
@@ -283,7 +381,9 @@ async function startSubagent(deps: BridgeDeps, entry: Entry): Promise<string> {
 	await deps.contexts.bind(record.alias, { agent_id: child, ...(parentId === undefined ? {} : { parent_id: parentId }) });
 	// The token is already in the child's prompt, so it can only be registered once the child's
 	// identity is known; until then there is no provider boundary to observe it at.
-	registerPending(entry, child, "fragment");
+	// It is registered as the token the prompt carries: a fresh one would never appear in any
+	// provider payload, and the delivery could never be confirmed.
+	registerPending(entry, child, "fragment", token);
 	return child;
 }
 async function findContextBySource(contexts: ContextRegistry, entry: Entry): Promise<ContextRecord | undefined> {

package/src/node.ts

@@ -45,9 +45,21 @@ export function createOnlyneNode(deps: NodeDeps): OnlyneNode {
 		return { actor };
 	};
 	const resolve = async (id: string): Promise<Target> => {
-		const target = id === config.node.id
-			? { node_id: id, base_url: deps.endpoint }
-			: await node.discovery.resolve(id);
+		let target: Target;
+		if (id === config.node.id) {
+			target = { node_id: id, base_url: deps.endpoint };
+		} else {
+			try {
+				target = await node.discovery.resolve(id);
+			} catch (error) {
+				const trustEntry = await node.trust.entry(id).catch(() => undefined);
+				if (trustEntry?.base_url) {
+					target = { node_id: id, base_url: trustEntry.base_url };
+				} else {
+					throw error;
+				}
+			}
+		}
 		return { ...target, headers: { "Onlyne-Actor": config.node.id } };
 	};
 	/**