@aeondave/pi-persona 1.15.2

package/src/exocom/codes.ts

@@ -0,0 +1,261 @@
+/**
+ * Persistent four-character Exocom join aliases.
+ *
+ * The alias is presentation-only: the durable value is the existing 24-hex scope id.  Alias
+ * files are intentionally kept out of the registry directory because this allocator owns a
+ * different invariant: once a code has been assigned, it is never assigned to another scope.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import {
+	closeSync,
+	constants as fsConstants,
+	fstatSync,
+	fsyncSync,
+	linkSync,
+	lstatSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+export const JOIN_CODE_LENGTH = 4;
+export const JOIN_CODE_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+export const MAX_JOIN_CODE_ATTEMPTS = 256;
+const MAPPING_MAX_BYTES = 4 * 1024;
+const CODES_DIRECTORY = "codes";
+const USED_DIRECTORY = ".used";
+const MAPPING_VERSION = 1;
+const JOIN_CODE_PATTERN = /^[0-9A-Za-z]{4}$/;
+const SCOPE_ID_PATTERN = /^[0-9a-f]{24}$/i;
+
+type Mapping = { code: string; scope_id: string; version: number };
+type Reservation = { code: string; scope_id: string; version: number };
+type ReadState<T> = { kind: "missing" } | { kind: "invalid" } | { kind: "valid"; value: T };
+
+/** Return true only for the public, case-sensitive four-character Base62 grammar. */
+export function isJoinCode(value: unknown): value is string {
+	return typeof value === "string" && JOIN_CODE_PATTERN.test(value);
+}
+
+/** Validate and return a join code; callers that accept untrusted input should catch this error. */
+export function validateJoinCode(value: unknown): string {
+	if (!isJoinCode(value)) throw new TypeError("join code must be exactly four Base62 characters");
+	return value;
+}
+
+function normalizeScopeId(value: unknown): string {
+	if (typeof value !== "string" || !SCOPE_ID_PATTERN.test(value)) {
+		throw new TypeError("scope id must be exactly 24-hex characters");
+	}
+	return value.toLowerCase();
+}
+
+function codesDirectory(agentDir: string): string {
+	return join(agentDir, "persona", "exocom", CODES_DIRECTORY);
+}
+
+function usedDirectory(agentDir: string): string {
+	return join(codesDirectory(agentDir), USED_DIRECTORY);
+}
+
+/** Encode each ASCII byte so a mixed-case alias is never used as a case-folding filesystem name. */
+export function encodeJoinCode(code: string): string {
+	return Buffer.from(validateJoinCode(code), "ascii").toString("hex");
+}
+
+export function joinCodePath(agentDir: string, code: string): string {
+	return join(codesDirectory(agentDir), `${encodeJoinCode(code)}.json`);
+}
+
+export function joinCodeReservationPath(agentDir: string, code: string): string {
+	return join(usedDirectory(agentDir), `${encodeJoinCode(code)}.json`);
+}
+
+function candidateBytes(scopeId: string, attempt: number): Buffer {
+	return createHash("sha256")
+		.update("pi-persona-exocom-join-code-v1\0", "utf8")
+		.update(scopeId, "utf8")
+		.update("\0", "utf8")
+		.update(String(attempt), "utf8")
+		.digest();
+}
+
+/** Generate the deterministic candidate for one bounded allocation attempt. */
+export function candidateJoinCode(scopeId: string, attempt = 0): string {
+	const normalizedScope = normalizeScopeId(scopeId);
+	if (!Number.isInteger(attempt) || attempt < 0 || attempt >= MAX_JOIN_CODE_ATTEMPTS) {
+		throw new RangeError(`join-code attempt must be an integer from 0 to ${MAX_JOIN_CODE_ATTEMPTS - 1}`);
+	}
+	let value = BigInt(`0x${candidateBytes(normalizedScope, attempt).toString("hex")}`);
+	let code = "";
+	for (let i = 0; i < JOIN_CODE_LENGTH; i++) {
+		const index = Number(value % BigInt(JOIN_CODE_ALPHABET.length));
+		code = `${JOIN_CODE_ALPHABET[index]!}${code}`;
+		value /= BigInt(JOIN_CODE_ALPHABET.length);
+	}
+	return code;
+}
+
+function ensureDirectory(path: string): void {
+	try {
+		const existing = lstatSync(path);
+		if (!existing.isDirectory() || existing.isSymbolicLink()) throw new Error(`unsafe join-code directory: ${path}`);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		mkdirSync(path, { recursive: true, mode: 0o700 });
+		const created = lstatSync(path);
+		if (!created.isDirectory() || created.isSymbolicLink()) throw new Error(`unsafe join-code directory: ${path}`);
+	}
+}
+
+function readJson<T>(path: string, parse: (value: unknown) => T | undefined): ReadState<T> {
+	let stat;
+	try {
+		stat = lstatSync(path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { kind: "missing" };
+		return { kind: "invalid" };
+	}
+	if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAPPING_MAX_BYTES) return { kind: "invalid" };
+	const noFollow = (fsConstants as typeof fsConstants & { O_NOFOLLOW?: number }).O_NOFOLLOW ?? 0;
+	let fd: number | undefined;
+	try {
+		fd = openSync(path, fsConstants.O_RDONLY | noFollow);
+		const opened = fstatSync(fd);
+		if (!opened.isFile() || opened.size > MAPPING_MAX_BYTES) return { kind: "invalid" };
+		const parsed: unknown = JSON.parse(readFileSync(fd, { encoding: "utf8" }));
+		const value = parse(parsed);
+		return value === undefined ? { kind: "invalid" } : { kind: "valid", value };
+	} catch {
+		return { kind: "invalid" };
+	} finally {
+		if (fd !== undefined) closeSync(fd);
+	}
+}
+
+function parseMapping(expectedCode: string): (value: unknown) => Mapping | undefined {
+	return (value) => {
+		if (!value || typeof value !== "object") return undefined;
+		const candidate = value as Record<string, unknown>;
+		if (candidate.version !== MAPPING_VERSION || candidate.code !== expectedCode) return undefined;
+		if (typeof candidate.scope_id !== "string" || !SCOPE_ID_PATTERN.test(candidate.scope_id)) return undefined;
+		return { version: MAPPING_VERSION, code: expectedCode, scope_id: candidate.scope_id.toLowerCase() };
+	};
+}
+
+function reservationState(agentDir: string, code: string): ReadState<Reservation> {
+	return readJson(joinCodeReservationPath(agentDir, code), (value) => {
+		if (!value || typeof value !== "object") return undefined;
+		const candidate = value as Record<string, unknown>;
+		if (candidate.version !== MAPPING_VERSION || candidate.code !== code) return undefined;
+		if (typeof candidate.scope_id !== "string" || !SCOPE_ID_PATTERN.test(candidate.scope_id)) return undefined;
+		return { version: MAPPING_VERSION, code, scope_id: candidate.scope_id.toLowerCase() };
+	});
+}
+
+/** Publish complete JSON at an unused path. A hard-link makes the fully written inode visible in one
+ * step, avoiding the open-before-write window where another Pi could observe an empty reservation. */
+function publishJsonExclusive(path: string, value: unknown): boolean {
+	const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+	let fd: number | undefined;
+	try {
+		fd = openSync(tempPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+		writeFileSync(fd, `${JSON.stringify(value)}\n`, { encoding: "utf8" });
+		fsyncSync(fd);
+	} finally {
+		if (fd !== undefined) closeSync(fd);
+	}
+	try {
+		linkSync(tempPath, path);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+		throw error;
+	} finally {
+		try { unlinkSync(tempPath); } catch { /* a crash-equivalent orphan is harmless */ }
+	}
+}
+
+/** Reserve a code with an atomic exclusive publish; a failed/invalid reservation remains occupied. */
+function reserveCode(agentDir: string, code: string, scopeId: string): boolean {
+	return publishJsonExclusive(
+		joinCodeReservationPath(agentDir, code),
+		{ version: MAPPING_VERSION, code, scope_id: scopeId },
+	);
+}
+
+function mappingState(agentDir: string, code: string): ReadState<Mapping> {
+	return readJson(joinCodePath(agentDir, code), parseMapping(code));
+}
+
+/** Create a mapping once, preserving a raced/existing path rather than overwriting it. */
+function createMapping(agentDir: string, code: string, scopeId: string): boolean {
+	return publishJsonExclusive(
+		joinCodePath(agentDir, code),
+		{ version: MAPPING_VERSION, code, scope_id: scopeId },
+	);
+}
+
+/** Complete a same-scope reservation that won the race before its mapping was written. */
+function recoverReservedCode(agentDir: string, code: string, scopeId: string): boolean {
+	const reserved = reservationState(agentDir, code);
+	if (reserved.kind !== "valid" || reserved.value.scope_id !== scopeId) return false;
+	const existing = mappingState(agentDir, code);
+	if (existing.kind === "valid") return existing.value.scope_id === scopeId;
+	if (existing.kind !== "missing") return false;
+	if (createMapping(agentDir, code, scopeId)) return true;
+	const raced = mappingState(agentDir, code);
+	return raced.kind === "valid" && raced.value.scope_id === scopeId;
+}
+
+/**
+ * Allocate (or recover) the persistent alias for a full scope id.
+ *
+ * Existing files and reservations are never overwritten.  Every collision advances to the next
+ * candidate derived from the same scope id, and reservations are retained even if mapping write
+ * fails so a code cannot later be recycled for another scope.
+ */
+export function allocateJoinCode(agentDir: string, scopeId: string, options: { maxAttempts?: number } = {}): string {
+	const normalizedScope = normalizeScopeId(scopeId);
+	const maxAttempts = options.maxAttempts ?? MAX_JOIN_CODE_ATTEMPTS;
+	if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > MAX_JOIN_CODE_ATTEMPTS) {
+		throw new RangeError(`maxAttempts must be an integer from 1 to ${MAX_JOIN_CODE_ATTEMPTS}`);
+	}
+	ensureDirectory(codesDirectory(agentDir));
+	ensureDirectory(usedDirectory(agentDir));
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		const code = candidateJoinCode(normalizedScope, attempt);
+		const reservation = reservationState(agentDir, code);
+		if (reservation.kind !== "missing") {
+			if (recoverReservedCode(agentDir, code, normalizedScope)) return code;
+			continue;
+		}
+		const existing = mappingState(agentDir, code);
+		if (existing.kind !== "missing") {
+			// Adopt old mappings into the tombstone set before returning or skipping them.
+			const reservationScope = existing.kind === "valid" ? existing.value.scope_id : normalizedScope;
+			if (!reserveCode(agentDir, code, reservationScope)) {
+				if (recoverReservedCode(agentDir, code, normalizedScope)) return code;
+				continue;
+			}
+			if (existing.kind === "valid" && existing.value.scope_id === normalizedScope) return code;
+			continue;
+		}
+		if (!reserveCode(agentDir, code, normalizedScope)) {
+			if (recoverReservedCode(agentDir, code, normalizedScope)) return code;
+			continue;
+		}
+		if (recoverReservedCode(agentDir, code, normalizedScope)) return code;
+	}
+	throw new Error(`unable to allocate an Exocom join code after ${maxAttempts} attempts`);
+}
+
+/** Resolve a public alias to its canonical 24-hex scope id; every malformed state fails closed. */
+export function resolveJoinCode(agentDir: string, code: unknown): string | undefined {
+	if (!isJoinCode(code)) return undefined;
+	const state = mappingState(agentDir, code);
+	return state.kind === "valid" ? state.value.scope_id : undefined;
+}

package/src/exocom/envelope.ts

@@ -0,0 +1,180 @@
+/** exocom wire envelopes + validators + truncation. Pure. */
+export interface AgentCard { name: string; persona: string; model: string; context_pct: number; inbox: number; }
+export interface ExocomMessage {
+	kind: "message"; msg_id: string; from_session: string; from_endpoint: string; from_name: string;
+	text: string; in_reply_to?: string; hops: number; ts: string; signature?: string;
+}
+/** The only structured text payload the receiver interprets specially. The marker and exact
+ * field set keep arbitrary peer-authored JSON as ordinary untrusted message text. */
+export interface ExocomArtifactDescriptor {
+	kind: "exocom_artifact";
+	preview: string;
+	path: string;
+	size: number;
+}
+export interface ExocomBye { kind: "bye"; from_session: string; from_endpoint?: string; signature?: string; }
+export interface ExocomAck { kind: "ack"; msg_id: string; from_session?: string; signature?: string; }
+export interface ExocomNack { kind: "nack"; msg_id: string; error: string; from_session?: string; signature?: string; }
+
+/** Semantic collaboration frames — ack/nack stay TRANSPORT. */
+export interface ExocomClaim {
+	kind: "claim"; work_key: string; from_session: string; from_name: string;
+	write_set: string[]; slice: string; msg_id: string; ts: string; signature?: string;
+}
+export interface ExocomAsk {
+	kind: "ask"; ask_id: string; work_key: string; from_session: string; from_name: string;
+	to_session: string; question: string; msg_id: string; ts: string; signature?: string;
+}
+export interface ExocomAnswer {
+	kind: "answer"; ask_id: string; work_key: string; from_session: string; from_name: string;
+	ok: boolean; evidence: string; msg_id: string; ts: string; signature?: string;
+}
+export interface ExocomProgress {
+	kind: "progress"; work_key: string; from_session: string; from_name: string;
+	note: string; msg_id: string; ts: string; signature?: string;
+}
+export interface ExocomRelease {
+	kind: "release"; work_key: string; from_session: string; from_name: string;
+	msg_id: string; ts: string; signature?: string;
+}
+export type ExocomSemanticFrame = ExocomClaim | ExocomAsk | ExocomAnswer | ExocomProgress | ExocomRelease;
+export type ExocomFrame = ExocomMessage | ExocomBye | ExocomAck | ExocomNack | ExocomSemanticFrame;
+
+const str = (v: unknown): v is string => typeof v === "string";
+const num = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
+const bounded = (v: unknown, max: number): v is string => str(v) && v.length > 0 && v.length <= max;
+const token = (v: unknown): v is string => bounded(v, 128) && /^[A-Za-z0-9._:-]+$/.test(v);
+const optionalBounded = (v: unknown, max: number): boolean => v === undefined || bounded(v, max);
+const metadata = (v: unknown, max: number): v is string =>
+	bounded(v, max) && !/[\p{Cc}\p{Zl}\p{Zp}<>]/u.test(v);
+const timestamp = (v: unknown): v is string =>
+	bounded(v, 128)
+	&& /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(v)
+	&& Number.isFinite(Date.parse(v));
+const writeSet = (v: unknown): v is string[] =>
+	Array.isArray(v) && v.length > 0 && v.length <= 64 && v.every((p) => str(p) && p.length > 0 && p.length <= 256);
+
+export function isSemanticFrame(v: unknown): v is ExocomSemanticFrame {
+	if (!v || typeof v !== "object") return false;
+	const o = v as Record<string, unknown>;
+	switch (o.kind) {
+		case "claim":
+			return token(o.work_key) && token(o.from_session) && metadata(o.from_name, 256)
+				&& writeSet(o.write_set) && bounded(o.slice, 256) && token(o.msg_id) && timestamp(o.ts)
+				&& optionalBounded(o.signature, 512);
+		case "ask":
+			return token(o.ask_id) && token(o.work_key) && token(o.from_session) && metadata(o.from_name, 256)
+				&& token(o.to_session) && o.to_session !== "*" && bounded(o.question, 4_096)
+				&& token(o.msg_id) && timestamp(o.ts) && optionalBounded(o.signature, 512);
+		case "answer":
+			return token(o.ask_id) && token(o.work_key) && token(o.from_session) && metadata(o.from_name, 256)
+				&& typeof o.ok === "boolean" && bounded(o.evidence, 8_192)
+				&& token(o.msg_id) && timestamp(o.ts) && optionalBounded(o.signature, 512);
+		case "progress":
+			return token(o.work_key) && token(o.from_session) && metadata(o.from_name, 256)
+				&& bounded(o.note, 4_096) && token(o.msg_id) && timestamp(o.ts)
+				&& optionalBounded(o.signature, 512);
+		case "release":
+			return token(o.work_key) && token(o.from_session) && metadata(o.from_name, 256)
+				&& token(o.msg_id) && timestamp(o.ts) && optionalBounded(o.signature, 512);
+		default:
+			return false;
+	}
+}
+
+/** Fail-closed structural validation of an inbound frame (R5). */
+export function isExocomFrame(v: unknown): v is ExocomFrame {
+	if (!v || typeof v !== "object") return false;
+	const o = v as Record<string, unknown>;
+	switch (o.kind) {
+		case "message":
+			return token(o.msg_id) && token(o.from_session) && bounded(o.from_endpoint, 1_024) && bounded(o.from_name, 256)
+				&& str(o.text) && Number.isInteger(o.hops) && num(o.hops) && o.hops >= 0 && bounded(o.ts, 128)
+				&& (o.in_reply_to === undefined || token(o.in_reply_to)) && optionalBounded(o.signature, 512);
+		case "bye":
+			return token(o.from_session) && optionalBounded(o.from_endpoint, 1_024) && optionalBounded(o.signature, 512);
+		case "ack":
+			return token(o.msg_id) && optionalBounded(o.from_session, 128) && optionalBounded(o.signature, 512);
+		case "nack":
+			return token(o.msg_id) && bounded(o.error, 512) && optionalBounded(o.from_session, 128) && optionalBounded(o.signature, 512);
+		case "claim":
+		case "ask":
+		case "answer":
+		case "progress":
+		case "release":
+			return isSemanticFrame(v);
+		default: return false;
+	}
+}
+
+/** Stable representation signed by an exocom instance. The signature field itself is excluded. */
+export function frameSigningPayload(frame: ExocomFrame): string {
+	switch (frame.kind) {
+		case "message":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.from_session, frame.from_endpoint, frame.from_name,
+				frame.text, frame.in_reply_to ?? null, frame.hops, frame.ts]);
+		case "bye": return JSON.stringify([frame.kind, frame.from_session, frame.from_endpoint ?? null]);
+		case "ack": return JSON.stringify([frame.kind, frame.msg_id, frame.from_session ?? null]);
+		case "nack": return JSON.stringify([frame.kind, frame.msg_id, frame.error, frame.from_session ?? null]);
+		case "claim":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.work_key, frame.from_session, frame.from_name,
+				frame.write_set, frame.slice, frame.ts]);
+		case "ask":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.ask_id, frame.work_key, frame.from_session, frame.from_name,
+				frame.to_session, frame.question, frame.ts]);
+		case "answer":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.ask_id, frame.work_key, frame.from_session, frame.from_name,
+				frame.ok, frame.evidence, frame.ts]);
+		case "progress":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.work_key, frame.from_session, frame.from_name,
+				frame.note, frame.ts]);
+		case "release":
+			return JSON.stringify([frame.kind, frame.msg_id, frame.work_key, frame.from_session, frame.from_name, frame.ts]);
+	}
+}
+
+export function nextHops(current: number): number { return current + 1; }
+
+const NOTICE = "\n\n…[exocom: truncated — ask the sender for the rest]";
+/** Head-truncate to a UTF-8 byte budget, adding a notice when cut (R1). */
+export function truncateForInject(text: string, maxBytes: number): { text: string; truncated: boolean } {
+	if (Buffer.byteLength(text, "utf8") <= maxBytes) return { text, truncated: false };
+	const budget = Math.max(0, Math.floor(maxBytes));
+	const chunks: string[] = [];
+	let used = 0;
+	for (const codePoint of text) {
+		const bytes = Buffer.byteLength(codePoint, "utf8");
+		if (used + bytes > budget) break;
+		chunks.push(codePoint);
+		used += bytes;
+	}
+	return { text: chunks.join("") + NOTICE, truncated: true };
+}
+
+/**
+ * Parse the descriptor emitted by ExocomPlane.payloadFor(). Deliberately fail closed:
+ * unmarked/arbitrary JSON remains ordinary peer text, and malformed descriptors never
+ * become an instruction to read an attacker-chosen path as an artifact.
+ */
+export function parseExocomArtifactDescriptor(text: string): ExocomArtifactDescriptor | undefined {
+	let value: unknown;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	const keys = Object.keys(record).sort();
+	if (keys.join(",") !== "kind,path,preview,size") return undefined;
+	if (record.kind !== "exocom_artifact" || typeof record.preview !== "string" || typeof record.path !== "string") return undefined;
+	if (record.preview.length > 4_096 || record.path.length === 0 || record.path.length > 4_096) return undefined;
+	if (/[\u0000-\u001F\u007F-\u009F]/.test(record.path)) return undefined;
+	if (typeof record.size !== "number" || !Number.isSafeInteger(record.size) || record.size <= 0) return undefined;
+	return {
+		kind: "exocom_artifact",
+		preview: record.preview,
+		path: record.path,
+		size: record.size,
+	};
+}

package/src/exocom/gate.ts

@@ -0,0 +1,6 @@
+/** Identity metadata does not claim work or settle asks. Persona denials still apply first. */
+const ALLOWED = new Set(["exocom_name", "exocom_answer", "exocom_decline", "exocom_status", "read", "grep", "find", "ls"]);
+
+export function constrainedTurnAllows(toolName: string): boolean {
+	return ALLOWED.has(toolName);
+}

package/src/exocom/guards.ts

@@ -0,0 +1,45 @@
+/** exocom inbound guardrails — per-sender budget (R2) and (sender,msg_id) dedup (R8). Pure. */
+export class SenderBudget {
+	private readonly windowMs: number;
+	private readonly maxMsgs: number;
+	private readonly maxBytes: number;
+	private readonly now: () => number;
+	private readonly buckets = new Map<string, { start: number; msgs: number; bytes: number }>();
+	constructor(opts: { windowMs: number; maxMsgs: number; maxBytes: number; now?: () => number }) {
+		this.windowMs = opts.windowMs; this.maxMsgs = opts.maxMsgs; this.maxBytes = opts.maxBytes;
+		this.now = opts.now ?? Date.now;
+	}
+	allow(sender: string, bytes: number): boolean {
+		const t = this.now();
+		let b = this.buckets.get(sender);
+		if (!b || t - b.start >= this.windowMs) { b = { start: t, msgs: 0, bytes: 0 }; this.buckets.set(sender, b); }
+		if (b.msgs + 1 > this.maxMsgs || b.bytes + bytes > this.maxBytes) return false;
+		b.msgs += 1; b.bytes += bytes;
+		return true;
+	}
+}
+
+export class SeenMessages {
+	private readonly ttlMs: number;
+	private readonly now: () => number;
+	private readonly seen = new Map<string, number>(); // "sender\x1fmsg" -> firstSeenAt
+	constructor(opts: { ttlMs: number; now?: () => number }) { this.ttlMs = opts.ttlMs; this.now = opts.now ?? Date.now; }
+	seenBefore(sender: string, msgId: string): boolean {
+		const t = this.now();
+		// \x1f (US): collision-proof composite key — sender (from_session) and msgId are
+		// self-reported by the peer, so a plain space would let crafted pairs alias each other.
+		const key = `${sender}\x1f${msgId}`;
+		const at = this.seen.get(key);
+		if (at !== undefined && t - at < this.ttlMs) return true;
+		this.seen.set(key, t);
+		if (this.seen.size > 4096) for (const [k, ts] of this.seen) { if (t - ts >= this.ttlMs) this.seen.delete(k); }
+		return false;
+	}
+
+	/** Undo a reservation made by seenBefore when a later guard rejects the message.
+	 * A sender may retry the same id after a transient budget window; recording it before
+	 * charging the budget would turn that legitimate retry into a permanent duplicate. */
+	forget(sender: string, msgId: string): void {
+		this.seen.delete(`${sender}\x1f${msgId}`);
+	}
+}

package/src/exocom/inbound.ts

@@ -0,0 +1,141 @@
+/**
+ * Pure inbound-delivery decision for exocom — isolates every guardrail (hop cap, dedup,
+ * per-sender budget, inject truncation) plus the fence/attribute step from all I/O, so the
+ * whole chain is unit-testable without a live plane (test/unit/exocom/inbound.test.ts).
+ *
+ * Preconditions this module cannot check itself: a caller must only pass messages whose artifact
+ * descriptor the transport has already verified against local ground truth (`ExocomPlane`'s
+ * `artifactClaimError`), since a path claim can only be judged against the receiver's own
+ * artifacts directory and the file on disk. That check is also where a spill's SIZE is bounded
+ * (`ARTIFACT_MAX_BYTES`) and reconciled with the bytes actually there — nothing below can do
+ * either, so an unverified caller would advertise a payload of any size to its model.
+ *
+ * Attribution MUST come from the caller's `resolvedLabel` (the registry-resolved identity) —
+ * this module never reads `msg.from_name`, which is the envelope's own self-report and not to be
+ * trusted (a peer could otherwise spoof its sender for attribution purposes). The canonical
+ * `fencePeer` implementation is used here directly: there is one trust-sensitive path, not an
+ * injectable callback whose tests could pass while production attribution drifted.
+ */
+import { parseExocomArtifactDescriptor, truncateForInject, type ExocomMessage } from "./envelope.ts";
+import type { SeenMessages, SenderBudget } from "./guards.ts";
+import { EXOCOM } from "./limits.ts";
+import { fencePeer } from "../core/fence.ts";
+import { peerSentLabel } from "../core/time.ts";
+
+export interface InboundDeps {
+	budget: SenderBudget;
+	seen: SeenMessages;
+	injectMaxBytes: number;
+	/** Authenticated, caller-resolved route for the sender. The plane supplies a stable,
+	 *  session-qualified reply token; this pure layer never derives routing from the human label.
+	 *  Unset is a defensive fallback for callers that have no registry context. */
+	replyTarget?: string;
+	/** The RECEIVER's clock, injected so the delivered age is deterministic under test. The
+	 *  sender's `ts` is authenticated but peer-chosen, so it is never the measuring stick. */
+	now?: () => number;
+}
+
+export type InboundDecision = { deliver: string } | { duplicate: true } | { drop: "budget" | "hops" };
+
+function routingToken(value: string): string {
+	return /^[A-Za-z0-9._:-]{1,128}$/.test(value) ? value : "invalid";
+}
+
+function headerLabel(value: string, fallback: string): string {
+	const clean = value
+		.normalize("NFKC")
+		.replace(/[\r\n\t\u0000-\u001F\u007F-\u009F]+/g, " ")
+		.replace(/[^A-Za-z0-9 ._@#()\/+:-]/g, "_")
+		.replace(/\s+/g, " ")
+		.trim()
+		.slice(0, 96);
+	return clean || fallback;
+}
+
+/** The reply hint carries an ADDRESS, not a label: `plane.send` compares it byte-for-byte against
+ *  the session-qualified token it cached for the authenticated sender, so any character rewritten
+ *  here makes the peer unrepliable ("does not match the authenticated sender"). A call-sign is the
+ *  model's free choice and `normalizePeerName` keeps every printable character, so this strips only
+ *  what a registry name can never legally carry (control characters, line/paragraph separators and
+ *  markup — see registry.ts's `normalizeMetadataText`) and leaves the rest intact. Quoting is the
+ *  call site's job: the token is embedded with `JSON.stringify`, so even a `"` or a backslash
+ *  cannot escape the hint line. */
+function routeToken(value: string, fallback: string): string {
+	const clean = value
+		.normalize("NFKC")
+		.replace(/[\p{Cc}\p{Zl}\p{Zp}<>]+/gu, " ")
+		.replace(/\s+/g, " ")
+		.trim()
+		.slice(0, 96);
+	return clean || fallback;
+}
+
+function formatArtifactSize(bytes: number): string {
+	if (bytes < 1_024) return `${bytes} B`;
+	const kib = bytes / 1_024;
+	if (kib < 1_024) return `${kib.toFixed(1)} KiB`;
+	return `${(kib / 1_024).toFixed(1)} MiB`;
+}
+
+/** Renders the spill as the readable form the model sees. `path` is peer-authored and this line
+ *  is an invitation to READ it, so it may only be rendered for a descriptor the transport already
+ *  verified against this Exocom scope's own artifacts directory and the bytes on disk — that the file
+ *  is this scope's own unlinked spill, and that its size matches and is bounded (see
+ *  `ExocomPlane.artifactClaimError`). Nothing here can check a path or a file. */
+function artifactBody(descriptor: ReturnType<typeof parseExocomArtifactDescriptor>): string {
+	if (!descriptor) return "";
+	return [
+		`Artifact preview · ${formatArtifactSize(descriptor.size)}`,
+		`Full payload: ${descriptor.path}`,
+		descriptor.preview || "(empty preview)",
+	].join("\n");
+}
+
+/** Apply the guardrails IN ORDER — hop cap, dedup, budget, truncate, fence+attribute — and
+ *  return either the ready-to-deliver follow-up text or a drop reason. */
+export function buildInboundDelivery(msg: ExocomMessage, resolvedLabel: string, deps: InboundDeps): InboundDecision {
+	if (!Number.isInteger(msg.hops) || msg.hops < 0 || msg.hops > EXOCOM.MAX_HOPS) return { drop: "hops" };
+	if (deps.seen.seenBefore(msg.from_session, msg.msg_id)) return { duplicate: true };
+	const descriptor = parseExocomArtifactDescriptor(msg.text);
+	// Charge what actually crossed the wire, never the size a spill DECLARES: that number is the
+	// sender's own, for a payload this receiver never inlines. Charging it would drop legitimate
+	// large spills (`exocom_send` accepts a 1 MB message) on the first message of a window, and a
+	// peer wanting to bypass the window would just under-declare. The artifact channel is bounded
+	// by the per-sender message count and by the plane's descriptor verification instead — which
+	// is what makes the declared number honest AND caps it (`ARTIFACT_MAX_BYTES`, plane.ts).
+	const wireBytes = Buffer.byteLength(msg.text, "utf8");
+	if (!deps.budget.allow(msg.from_session, wireBytes)) {
+		// seenBefore reserves the id so a duplicate can be rejected without charging the
+		// budget twice. A budget rejection is different: it is transient, and the sender
+		// must be able to retry the same id after the window rolls over.
+		deps.seen.forget(msg.from_session, msg.msg_id);
+		return { drop: "budget" };
+	}
+	// Artifacts are structured transport metadata, but their preview/path are still peer-authored
+	// text. Apply the exact same injection budget after rendering the readable form; otherwise a
+	// small wire descriptor can expand into several KiB inside the supervisor's next turn.
+	const text = truncateForInject(descriptor ? artifactBody(descriptor) : msg.text, deps.injectMaxBytes).text;
+	const msgId = routingToken(msg.msg_id);
+	const label = headerLabel(resolvedLabel, "unknown");
+	const target = routeToken(deps.replyTarget ?? label.replace(/\s+\([^)]*\)$/, ""), "peer");
+	const kind = msg.in_reply_to === undefined ? "message" : "reply";
+	// How old this message is when it lands is part of what it MEANS — a reply that took twenty
+	// minutes is a different event from an instant one, and the header was the only place the
+	// receiver could learn it. Precise here on purpose: the delivery is appended to the conversation
+	// TAIL, written once, so it is never re-sent as a cached prompt prefix. `peerSentLabel` measures
+	// against OUR clock and degrades an unbelievable peer timestamp to an honest label instead of
+	// dressing a peer-chosen value in the harness's voice (src/core/time.ts).
+	const sent = peerSentLabel(msg.ts, (deps.now ?? Date.now)());
+	const peerBlock = fencePeer(text);
+	const quotedBody = peerBlock.slice(peerBlock.indexOf("\n") + 1);
+	// Conditional, not an invitation: this delivery is a FRESH PROMPT on the receiver, so a bare
+	// "Reply:" makes answering the default and silence the exception — which is how a settled point
+	// keeps running on agreement and thanks. The hint stays ONE line and names the correlation id
+	// once, so the routing shape below is unchanged.
+	// JSON-quoted, not raw: the token keeps every character `plane.send` will match on, while a
+	// quote/backslash a peer put in its call-sign is escaped instead of ending the hint early.
+	const reply = `Reply only if it changes what someone does, otherwise send nothing: exocom_send({ target:${JSON.stringify(target)}, message:"...", in_reply_to:"${msgId}" })`;
+	return {
+		deliver: `[${label}] — ${kind} · ${sent}\nPeer data · untrusted equal-status collaborator:\n${quotedBody}\n${reply}`,
+	};
+}