gentle-pi 4.2.0 → 4.4.0

package/lib/notification-service.ts

@@ -15,7 +15,7 @@ export interface NotificationServiceDependencies {
 	policy?: NotificationOptions;
 	read?: () => NotificationResolution;
 	write?: (settings: NotificationSettings) => string;
-	backend?: Pick<NotificationPlayer, "play" | "availability" | "capabilities">;
+	backend?: Pick<NotificationPlayer, "play" | "availability" | "capabilities"> & { dispose?: () => void };
 	setTimeout?: SchedulerOptions["setTimeout"];
 	clearTimeout?: SchedulerOptions["clearTimeout"];
 }
@@ -175,6 +175,10 @@ export function claimNotificationOwner(retireRuntime: () => void, deps: Notifica
 	const retire = () => {
 		if (disposed) return;
 		shutdown(); disposed = true; retireRuntime();
+		// End of life for the claim also ends the audio backend: the persistent
+		// serve worker (if one was spawned) is killed here; a re-bind through
+		// attach() keeps it, and an abandoned claim self-retires idle after 60 s.
+		backend.dispose?.();
 		if (shared.ownerLease === lease) { shared.ownerLease = undefined; shared.retire = undefined; }
 	};
 	shared.retire = retire;

package/lib/orchestrator-discovery.ts

@@ -1,13 +1,16 @@
 import { readCatalog, type CatalogPage } from "./orchestrator-catalog.ts";
 import type { PublishedWork } from "./orchestrator-work.ts";
 import type { PresenceRecord } from "./agents-session-transport.ts";
-import { activationHash, listPresence, readDiscovery, sessionHash, type DiscoveryMetadata } from "./orchestrator-presence.ts";
+import { activationHash, discoveryAbsent, listPresence, readDiscovery, sessionHash, type DiscoveryMetadata } from "./orchestrator-presence.ts";
 
 export interface OrchestratorCandidate {
 	sessionId: string;
 	reachability: "unknown";
 	freshness: "unknown" | "recent" | "stale";
 	label?: string;
+	/** Display-only label of a live peer whose code predates discovery publication:
+	 * its schema-1 header heartbeats, but it never writes a discovery sidecar. */
+	legacyLabel?: string;
 	aliases?: DiscoveryMetadata["aliases"];
 	workspace?: string;
 	tasks?: DiscoveryMetadata["tasks"];
@@ -36,6 +39,7 @@ export function discoverOrchestrators(profile: string, peers: readonly PresenceR
 		if (matches.length !== 1) return unknown;
 		const header = matches[0];
 		const metadata = readDiscovery(profile, header);
+		if (!metadata && header.recent && discoveryAbsent(profile, header)) return { ...unknown, legacyLabel: header.label };
 		if (metadata?.activation !== activationHash(activations[0])) return unknown;
 		if (!header.recent) return { ...unknown, freshness: "stale" };
 		const catalog = readCatalog(profile, header, metadata.activation, selection?.recipientSessionId === sessionId ? selection.cursor : undefined);

package/lib/orchestrator-presence.ts

@@ -171,18 +171,25 @@ function reason(error: unknown) {
 	return code === "ENOENT" ? "missing" : code ? "io-error" : error instanceof SyntaxError ? "malformed" : (error as Error).message;
 }
 function atomicWrite(root: string, name: string, bytes: string) {
-	directory(root, true);
+	// Ancestor validation is the heartbeat's cached responsibility; the destination
+	// identity check remains per-write so a replaced or linked file is never overwritten.
 	const destination = join(root, name);
 	try { regular(fs.lstatSync(destination)); }
 	catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
 	const temp = join(root, `.${name}.${randomUUID()}.tmp`);
 	const fd = fs.openSync(temp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+	let identity: { dev: number; ino: number };
+	try {
+		fs.writeFileSync(fd, bytes);
+		const stat = fs.fstatSync(fd);
+		identity = { dev: stat.dev, ino: stat.ino };
+	} finally { fs.closeSync(fd); }
 	try {
-		try { fs.writeFileSync(fd, bytes); } finally { fs.closeSync(fd); }
 		fs.renameSync(temp, destination);
 	} finally {
 		try { fs.unlinkSync(temp); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
 	}
+	return identity;
 }
 
 export interface PresencePage {
@@ -263,6 +270,15 @@ export function readActivity(profile: string, selection: Header): { activity?: A
 	} catch (error) { return { unavailable: reason(error) }; }
 }
 
+/** True only when no discovery sidecar exists for this header: the publisher
+ * predates discovery publication. A present but unreadable sidecar is not absent. */
+export function discoveryAbsent(profile: string, h: Header): boolean {
+	try {
+		fs.lstatSync(join(rootFor(profile), filename(h, "discovery")));
+		return false;
+	} catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT"; }
+}
+
 /** Optional derived sidecar; failures never invalidate the schema-1 header. */
 export function readDiscovery(profile: string, h: Header): DiscoveryMetadata | undefined {
 	try {
@@ -292,6 +308,11 @@ export class PresencePublisher {
 	private heartbeat?: ReturnType<typeof setInterval>;
 	private disposed = false;
 	private owned = new Map<string, { dev: number; ino: number }>();
+	/** Root paths whose ancestor chain was validated for this session identity.
+	 * Seeded by the one synchronous rootFor() in start(); refreshed asynchronously
+	 * by the heartbeat so writes never probe directories on the caller's thread. */
+	private readonly validRoots = new Set<string>();
+	private validating = false;
 	/** Timer I/O failures stop publication; consumers still apply the recent TTL. */
 	error?: string;
 
@@ -304,10 +325,10 @@ export class PresencePublisher {
 	static start(options: { profile: string; sessionId: string; label: string; labelSource?: () => string; activity: readonly ActivityInput[] }) {
 		const publisher = new PresencePublisher(options);
 		try {
-			rootFor(options.profile, true);
+			publisher.validRoots.add(rootFor(options.profile, true));
 			publisher.pending = JSON.stringify(projectActivity(options.activity));
 			publisher.flush();
-			publisher.heartbeat = setInterval(() => publisher.guarded(() => publisher.publishHeader()), 5000);
+			publisher.heartbeat = setInterval(() => publisher.pulse(), 5000);
 			publisher.heartbeat.unref();
 			return publisher;
 		} catch (error) { publisher.dispose(); throw error; }
@@ -375,12 +396,68 @@ export class PresencePublisher {
 		if (this.disposed) return;
 		try { action(); } catch (error) { this.error = reason(error); this.dispose(); }
 	}
+	private rootPath(kind: "header" | "activity" | "discovery" | "catalog") {
+		return join(resolve(this.profile), "gentle-agents", kind === "catalog" ? "catalog" : "presence");
+	}
+	/** Publishes from the warm cache synchronously, then refreshes the validated
+	 * ancestor chain asynchronously without ever overlapping itself. */
+	private pulse() {
+		this.guarded(() => this.publishHeader());
+		if (this.validating) return;
+		this.validating = true;
+		void this.revalidate().finally(() => { this.validating = false; }).catch(() => { /* revalidate never rejects */ });
+	}
+	/** Async mirror of rootFor(): same ancestor chain, modes, and ownership, so the
+	 * sync write path stays cache-only. A failed validation only cools the cache. */
+	private async revalidate() {
+		const absolute = resolve(this.profile);
+		const shared = join(absolute, "gentle-agents");
+		const chains: { root: string; create: boolean }[] = [{ root: join(shared, "presence"), create: false }];
+		if (this.catalog) chains.push({ root: join(shared, "catalog"), create: true });
+		for (const { root, create } of chains) {
+			try {
+				for (let path = absolute;; path = dirname(path)) {
+					const stat = await fs.promises.lstat(path);
+					if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("unsafe-directory");
+					if (dirname(path) === path) break;
+				}
+				if (create) {
+					try { await fs.promises.mkdir(root, { mode: 0o700 }); }
+					catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+				}
+				await this.checkedDirectory(shared, false);
+				await this.checkedDirectory(root, true);
+				this.validRoots.add(root);
+			} catch { this.validRoots.delete(root); }
+		}
+	}
+	private async checkedDirectory(path: string, privateMode: boolean) {
+		const stat = await fs.promises.lstat(path);
+		if (!stat.isDirectory() || stat.isSymbolicLink() || (process.platform !== "win32"
+			&& ((stat.mode & (privateMode ? 0o077 : 0o022)) !== 0 || stat.uid !== process.getuid?.()))) throw new Error("unsafe-directory");
+	}
 	private write(kind: "header" | "activity" | "discovery" | "catalog", bytes: string) {
-		const root = rootFor(this.profile, kind === "catalog", kind === "catalog");
+		// A cold cache validates synchronously exactly once for that path — the same
+		// rootFor() validation the old per-write path performed — then caches and
+		// writes, so the first publication after a cold start is never deferred to a
+		// heartbeat. A failed validation (vanished or unsafe tree) is the only skip
+		// path; the heartbeat's async refresh re-warms the cache once the tree returns.
+		const root = this.rootPath(kind);
+		if (!this.validRoots.has(root)) {
+			try { rootFor(this.profile, kind === "catalog", kind === "catalog"); }
+			catch { return; }
+			this.validRoots.add(root);
+		}
 		const name = kind === "catalog" ? `${this.target.sessionHash}.${this.target.incarnation}.json` : filename(this.target, kind);
-		atomicWrite(root, name, bytes);
-		const { dev, ino } = fs.lstatSync(join(root, name));
-		this.owned.set(join(root, name), { dev, ino });
+		let identity: { dev: number; ino: number };
+		try { identity = atomicWrite(root, name, bytes); }
+		catch (error) {
+			// A tree that vanished mid-flight is skipped, not fatal; other failures stay fatal.
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			this.validRoots.delete(root);
+			return;
+		}
+		this.owned.set(join(root, name), identity);
 	}
 	private writeDiscovery() {
 		if (!this.discovery) return;
@@ -393,6 +470,7 @@ export class PresencePublisher {
 		} catch { /* Metadata failure must not withdraw an existing activity peer. */ }
 	}
 	private publishHeader() {
+		if (!this.validRoots.has(this.rootPath("header"))) return;
 		const header = { ...this.header, label: label(this.labelSource?.() ?? this.displayLabel), heartbeat: Date.now() };
 		if (!validHeader(header)) throw new Error("malformed-header");
 		this.write("header", JSON.stringify(header));
@@ -401,6 +479,7 @@ export class PresencePublisher {
 	}
 	private flush() {
 		if (this.pending === this.published) return;
+		if (!this.validRoots.has(this.rootPath("activity"))) return;
 		const activity: Activity = JSON.parse(this.pending);
 		const generation = (this.header?.generation ?? 0) + 1;
 		const bytes = JSON.stringify({ schema: 1, ...this.target, generation, activity });

package/lib/orchestrator-scope.ts

@@ -41,9 +41,14 @@ export function validRecordedScope(value: any): value is RecordedScope {
 /** One bounded derivative snapshot, not a registry or authority. The caller supplies
  * only admitted, unfinished, non-restored owned children and durable registry roots.
  * Membership/cwd changes invalidate even unknown facts; session replacement clears.
- * No resolution runs on a stable heartbeat/token update. */
+ * Recency reorders rebuild caller-ordered snapshots without refreshing visible facts.
+ * Resolution stays bounded to the host and first eight tasks/registered roots;
+ * newly visible paths are resolved lazily, including after a reorder. */
 export class OrchestratorScopeCache {
 	private key = "";
+	private membershipKey = "";
+	private facts = new Map<string, RepositoryFact>();
+	private resolvedAt = 0;
 	private snapshot?: RecordedScope;
 	private resolver: WorktreeResolver;
 	private now: () => number;
@@ -53,14 +58,34 @@ export class OrchestratorScopeCache {
 	}
 	clear() {
 		this.key = "";
+		this.membershipKey = "";
+		this.facts.clear();
 		this.snapshot = undefined;
 	}
+	/** Snapshot for deferred (render-cadence trailing) publications: it never
+	 * touches the resolver. A deferred publish reuses the last event-time
+	 * projection as-is even when membership changed since — its Git resolution
+	 * must never race a peer metadata query, whose contract adds no caller Git
+	 * probes. Returns undefined when nothing has been projected yet (or the
+	 * cache was cleared), in which case the caller omits the scope rather than
+	 * probing; the next event-time publication refreshes the facts. */
+	cachedScope(): RecordedScope | undefined {
+		return this.snapshot;
+	}
 	project(cwd: string, tasks: readonly { id: string; cwd: string }[], roots: readonly string[]): RecordedScope {
 		const registered = [...new Set(roots)];
 		const key = createHash("sha256").update(JSON.stringify([cwd, tasks.map(t => [t.id, t.cwd]), registered])).digest("hex");
 		if (key === this.key && this.snapshot) return this.snapshot;
-		const resolvedAt = this.now();
-		const facts = new Map<string, RepositoryFact>();
+		const membershipKey = createHash("sha256").update(JSON.stringify([
+			cwd, tasks.map(t => JSON.stringify([t.id, t.cwd])).sort(), [...registered].sort(),
+		])).digest("hex");
+		if (membershipKey !== this.membershipKey) {
+			this.facts.clear();
+			this.resolvedAt = this.now();
+			this.membershipKey = membershipKey;
+		}
+		const resolvedAt = this.resolvedAt;
+		const facts = this.facts;
 		const fact = (path: string) => {
 			if (facts.has(path)) return facts.get(path)!;
 			const unknown: RepositoryFact = { root: null, cloneHash: null, resolvedAt, source: "recorded-workspace/git" };
@@ -74,6 +99,9 @@ export class OrchestratorScopeCache {
 		this.snapshot = { host: fact(cwd), tasks: tasks.slice(0, 8).map(t => ({ id: t.id, repository: fact(t.cwd) })),
 			registered: registered.slice(0, 8).map(fact), omittedTasks: Math.max(0, tasks.length - 8),
 			omittedRegistered: Math.max(0, registered.length - 8), complete: tasks.length <= 8 && registered.length <= 8 };
+		// Keep fact retention bounded even when an oversized task list rotates.
+		const visible = new Set([cwd, ...tasks.slice(0, 8).map(t => t.cwd), ...registered.slice(0, 8)]);
+		for (const path of facts.keys()) if (!visible.has(path)) facts.delete(path);
 		this.key = key;
 		return this.snapshot;
 	}

package/lib/orchestrator-state.ts

@@ -89,11 +89,19 @@ export class OrchestratorStateCache {
 		const previous = this.value?.aliases;
 		// Null/null marks a new publication with no declaration yet; legacy absence
 		// cannot establish historical first-task knowledge.
+		// An explicitly published work topic is owner-curated public task
+		// classification, so it refreshes the current alias when the caller omits
+		// the subject (#2553). State-only refreshes and automatic republications of
+		// unchanged state must not re-derive it, and an explicit subject in the
+		// same publication always wins.
+		const topic = input !== undefined && !declared && state?.work?.topic
+			? normalizeTaskSubject(state.work.topic) : undefined;
 		let aliases = previous;
-		if (declared) {
+		if (declared || topic) {
+			const current = declared ?? topic;
 			let initialAlias = previous?.initialAlias ?? null;
-			if (!this.value || previous?.currentAlias === null) initialAlias = declared;
-			aliases = { initialAlias, currentAlias: declared };
+			if (!this.value || previous?.currentAlias === null) initialAlias = current;
+			aliases = { initialAlias, currentAlias: current };
 		} else if (!this.value) aliases = { initialAlias: null, currentAlias: null };
 		const cwd = input === undefined && this.value ? this.value.cwd : manager.getCwd();
 		const record = decodePublishedState({ schema: state?.work ? 2 : 1, sessionId: manager.getSessionId(),

package/lib/permission-mode-policy.ts

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { gentlePiConfigHome } from "./agent-home.ts";
 
-export type PermissionMode = "normal" | "auto" | "yolo";
+export type PermissionMode = "normal" | "auto" | "yolo" | "super-yolo";
 export const PERMISSION_MODE_SCHEMA = "gentle-pi.permission-mode/v1";
 export interface PermissionModeOptions { gentlePiConfigHome?: string }
 export interface PermissionModeResolution {
@@ -13,7 +13,7 @@ export interface PermissionModeResolution {
 	globalFile: string;
 }
 export function isPermissionMode(value: unknown): value is PermissionMode {
-	return value === "normal" || value === "auto" || value === "yolo";
+	return value === "normal" || value === "auto" || value === "yolo" || value === "super-yolo";
 }
 /** Never consult merged Pi settings or repository configuration. */
 export function permissionModePolicyFile(options: PermissionModeOptions = {}): string {

package/lib/provider-contract-bundle.ts

@@ -4,7 +4,9 @@
 // release bundle (or its extracted tree) and verifies it fail-closed before
 // any layout, role, schema, or capability inside it is trusted:
 //
-// - exact eight-entry inventory (README.md, manifest.json, 3 schemas, 3 vectors);
+// - exact inventory: eight base entries (README.md, manifest.json, 3 schemas,
+//   3 vectors) plus one `orchestration/<runtime>.md` (>= 1.2.0) and one
+//   `routing/<runtime>.md` (>= 1.4.0) per runtime the manifest lists;
 // - strict manifest decode: single JSON object, no duplicate keys, no unknown fields;
 // - per-file SHA-256 agreement between the manifest and the actual bytes;
 // - pinned transport capability and supported contract major (1);
@@ -33,6 +35,8 @@ export const SUPPORTED_PROVIDER_CONTRACT_MAJOR = 1;
 export const RUNTIMES_REQUIRED_SINCE_MINOR = 1;
 // `orchestration` became part of the manifest in contract 1.2.0.
 export const ORCHESTRATION_REQUIRED_SINCE_MINOR = 2;
+// `routing` became part of the manifest in contract 1.4.0.
+export const ROUTING_REQUIRED_SINCE_MINOR = 4;
 // Exactly the provider roles gentle-pi supports, in the manifest's strict order.
 export const PROVIDER_CONTRACT_ROLE_IDS = ["lens", "refuter", "targeted-validator"] as const;
 // Every mandatory capability a role may declare. An unknown mandatory
@@ -46,11 +50,11 @@ const MAX_MANIFEST_BYTES = 64 * 1024;
 const BUNDLE_ENTRY_COUNT = 8;
 // Generous fixed safety bound on raw archive/tree entries read BEFORE the
 // manifest itself is parsed (the exact expected count, base entries plus one
-// per `orchestration` runtime, is known only after manifest decode). Real
-// contracts register a handful of runtimes; this bound only rules out an
-// absurd smuggled inventory, it is not the exact-count check.
-const MAX_ORCHESTRATION_ENTRIES = 64;
-const MAX_RAW_BUNDLE_ENTRIES = BUNDLE_ENTRY_COUNT + MAX_ORCHESTRATION_ENTRIES;
+// per `orchestration` and one per `routing` runtime, is known only after
+// manifest decode). Real contracts register a handful of runtimes; this bound
+// only rules out an absurd smuggled inventory, it is not the exact-count check.
+const MAX_RUNTIME_FILE_ENTRIES = 64;
+const MAX_RAW_BUNDLE_ENTRIES = BUNDLE_ENTRY_COUNT + 2 * MAX_RUNTIME_FILE_ENTRIES;
 // setuid/setgid/sticky, any execute bit, or world-writable content is never
 // acceptable for a data-only contract bundle.
 const FORBIDDEN_MODE_BITS = 0o7113;
@@ -99,7 +103,13 @@ export interface VerifiedProviderContractBundle {
 	 * 1.2.0, where `orchestration` does not exist in the manifest.
 	 */
 	readonly orchestration: ReadonlyMap<string, string>;
-	/** Canonical path -> exact verified bytes for all entries (base eight plus one per orchestration runtime). */
+	/**
+	 * Verified ODD implementation-routing block, runtime identity -> UTF-8
+	 * `routing/<runtime>.md` contents. Empty before contract 1.4.0, where
+	 * `routing` does not exist in the manifest.
+	 */
+	readonly routing: ReadonlyMap<string, string>;
+	/** Canonical path -> exact verified bytes for all entries (base eight plus one per orchestration and routing runtime). */
 	readonly entries: ReadonlyMap<string, Buffer>;
 	/** Canonical path -> SHA-256 of the exact verified bytes. */
 	readonly entrySha256: ReadonlyMap<string, string>;
@@ -321,23 +331,65 @@ function parseManifestRole(value: unknown, index: number): ManifestRole {
 	};
 }
 
-interface ManifestOrchestrationEntry {
+// One entry of a runtime-file inventory: `orchestration` (>= 1.2.0) or
+// `routing` (>= 1.4.0). Both share the shape `{ runtime, file }` with the file
+// at `<inventory>/<runtime>.md`.
+interface ManifestRuntimeFileEntry {
 	readonly runtime: string;
 	readonly file: ManifestFileReference;
 }
 
-function parseOrchestrationEntry(value: unknown, index: number): ManifestOrchestrationEntry {
-	const where = `manifest.orchestration[${index}]`;
+type RuntimeFileInventory = "orchestration" | "routing";
+
+function parseRuntimeFileEntry(inventory: RuntimeFileInventory, value: unknown, index: number): ManifestRuntimeFileEntry {
+	const where = `manifest.${inventory}[${index}]`;
 	const object = requireObject(value, where);
 	requireExactKeys(object, ["runtime", "file"], ["runtime", "file"], where);
 	const runtime = requireString(object.runtime, `${where}.runtime`);
 	if (!RUNTIME_IDENTITY_PATTERN.test(runtime)) invalid(`${where}.runtime ${JSON.stringify(runtime)} is not a runtime identity`);
 	const file = parseFileReference(object.file, `${where}.file`);
-	const expectedPath = `orchestration/${runtime}.md`;
+	const expectedPath = `${inventory}/${runtime}.md`;
 	if (file.path !== expectedPath) invalid(`${where}.file.path must be ${JSON.stringify(expectedPath)}`);
 	return { runtime, file };
 }
 
+// Decodes one runtime-file inventory: absent before the contract minor that
+// introduced it, required from it on, strictly sorted, every runtime
+// registered in manifest.runtimes, and `pi` always present.
+function parseRuntimeFileInventory(
+	object: Record<string, unknown>,
+	inventory: RuntimeFileInventory,
+	requiredSinceMinor: number,
+	contractSemver: string,
+	minor: number,
+	runtimes: readonly string[] | undefined,
+): readonly ManifestRuntimeFileEntry[] {
+	const required = minor >= requiredSinceMinor;
+	if (!Object.prototype.hasOwnProperty.call(object, inventory)) {
+		if (required) invalid(`manifest.${inventory} is required from contract 1.${requiredSinceMinor}.0 (got ${contractSemver} without it)`);
+		return [];
+	}
+	if (!required) {
+		invalid(`manifest.${inventory} is not part of contract ${contractSemver}; it exists from 1.${requiredSinceMinor}.0`);
+	}
+	const value = object[inventory];
+	if (!Array.isArray(value) || value.length === 0) invalid(`manifest.${inventory} must be a non-empty array`);
+	const entries = value.map((entry, index) => parseRuntimeFileEntry(inventory, entry, index));
+	for (let position = 0; position < entries.length; position += 1) {
+		const entry = entries[position] as ManifestRuntimeFileEntry;
+		if (position > 0 && (entries[position - 1] as ManifestRuntimeFileEntry).runtime >= entry.runtime) {
+			invalid(`manifest.${inventory} must be strictly sorted by runtime and unique`);
+		}
+		if (runtimes === undefined || !runtimes.includes(entry.runtime)) {
+			invalid(`manifest.${inventory}[${position}].runtime ${JSON.stringify(entry.runtime)} is not registered in manifest.runtimes`);
+		}
+	}
+	if (!entries.some((entry) => entry.runtime === PI_RUNTIME_IDENTITY)) {
+		invalid(`manifest.${inventory} does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
+	}
+	return entries;
+}
+
 interface ParsedManifest {
 	readonly contractSemver: string;
 	readonly major: number;
@@ -347,14 +399,15 @@ interface ParsedManifest {
 	readonly runtimes: readonly string[] | undefined;
 	readonly readme: ManifestFileReference;
 	readonly roles: readonly ManifestRole[];
-	readonly orchestration: readonly ManifestOrchestrationEntry[];
+	readonly orchestration: readonly ManifestRuntimeFileEntry[];
+	readonly routing: readonly ManifestRuntimeFileEntry[];
 }
 
 function parseManifest(payload: Buffer): ParsedManifest {
 	const object = decodeStrictManifestObject(payload);
 	requireExactKeys(
 		object,
-		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles", "orchestration"],
+		["schema", "contract_semver", "transport_capability", "runtimes", "readme", "roles", "orchestration", "routing"],
 		["schema", "contract_semver", "transport_capability", "readme", "roles"],
 		"manifest",
 	);
@@ -398,32 +451,8 @@ function parseManifest(payload: Buffer): ParsedManifest {
 		invalid(`manifest.runtimes does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
 	}
 
-	const orchestrationRequired = minor >= ORCHESTRATION_REQUIRED_SINCE_MINOR;
-	let orchestration: readonly ManifestOrchestrationEntry[] = [];
-	if (Object.prototype.hasOwnProperty.call(object, "orchestration")) {
-		if (!orchestrationRequired) {
-			invalid(`manifest.orchestration is not part of contract ${contractSemver}; it exists from 1.${ORCHESTRATION_REQUIRED_SINCE_MINOR}.0`);
-		}
-		if (!Array.isArray(object.orchestration) || object.orchestration.length === 0) {
-			invalid("manifest.orchestration must be a non-empty array");
-		}
-		const parsedOrchestration = object.orchestration.map((entry, index) => parseOrchestrationEntry(entry, index));
-		for (let position = 0; position < parsedOrchestration.length; position += 1) {
-			const entry = parsedOrchestration[position] as ManifestOrchestrationEntry;
-			if (position > 0 && (parsedOrchestration[position - 1] as ManifestOrchestrationEntry).runtime >= entry.runtime) {
-				invalid("manifest.orchestration must be strictly sorted by runtime and unique");
-			}
-			if (runtimes === undefined || !runtimes.includes(entry.runtime)) {
-				invalid(`manifest.orchestration[${position}].runtime ${JSON.stringify(entry.runtime)} is not registered in manifest.runtimes`);
-			}
-		}
-		if (!parsedOrchestration.some((entry) => entry.runtime === PI_RUNTIME_IDENTITY)) {
-			invalid(`manifest.orchestration does not register the ${JSON.stringify(PI_RUNTIME_IDENTITY)} runtime identity`);
-		}
-		orchestration = parsedOrchestration;
-	} else if (orchestrationRequired) {
-		invalid(`manifest.orchestration is required from contract 1.${ORCHESTRATION_REQUIRED_SINCE_MINOR}.0 (got ${contractSemver} without it)`);
-	}
+	const orchestration = parseRuntimeFileInventory(object, "orchestration", ORCHESTRATION_REQUIRED_SINCE_MINOR, contractSemver, minor, runtimes);
+	const routing = parseRuntimeFileInventory(object, "routing", ROUTING_REQUIRED_SINCE_MINOR, contractSemver, minor, runtimes);
 
 	if (!Array.isArray(object.roles)) invalid("manifest.roles must be an array");
 	const roles = object.roles.map((role, index) => parseManifestRole(role, index));
@@ -446,6 +475,7 @@ function parseManifest(payload: Buffer): ParsedManifest {
 		readme: parseFileReference(object.readme, "manifest.readme"),
 		roles,
 		orchestration,
+		routing,
 	};
 }
 
@@ -541,8 +571,9 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 
 	// The exact expected inventory size is only known once the manifest is
 	// decoded: base entries plus exactly one `orchestration/<runtime>.md` per
-	// registered orchestration runtime.
-	const expectedEntryCount = BUNDLE_ENTRY_COUNT + manifest.orchestration.length;
+	// registered orchestration runtime and one `routing/<runtime>.md` per
+	// registered routing runtime.
+	const expectedEntryCount = BUNDLE_ENTRY_COUNT + manifest.orchestration.length + manifest.routing.length;
 	if (rawEntries.size !== expectedEntryCount) {
 		invalid(`bundle inventory has ${rawEntries.size} files; exactly ${expectedEntryCount} are expected`);
 	}
@@ -554,13 +585,18 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 		expected.add(`schemas/${role.id}.schema.json`);
 		expected.add(`vectors/${role.id}.json`);
 	}
-	const orchestration = new Map<string, string>();
-	for (const entry of manifest.orchestration) {
-		const path = `orchestration/${entry.runtime}.md`;
-		const payload = verifyFileReference(rawEntries, entry.file, path);
-		orchestration.set(entry.runtime, payload.toString("utf8"));
-		expected.add(path);
-	}
+	const verifyRuntimeFiles = (inventory: RuntimeFileInventory, manifestEntries: readonly ManifestRuntimeFileEntry[]): Map<string, string> => {
+		const texts = new Map<string, string>();
+		for (const entry of manifestEntries) {
+			const path = `${inventory}/${entry.runtime}.md`;
+			const payload = verifyFileReference(rawEntries, entry.file, path);
+			texts.set(entry.runtime, payload.toString("utf8"));
+			expected.add(path);
+		}
+		return texts;
+	};
+	const orchestration = verifyRuntimeFiles("orchestration", manifest.orchestration);
+	const routing = verifyRuntimeFiles("routing", manifest.routing);
 	for (const name of rawEntries.keys()) {
 		if (!expected.has(name)) invalid(`bundle has unexpected file ${JSON.stringify(name)}`);
 	}
@@ -591,6 +627,7 @@ export function verifyProviderContractBundleEntries(rawEntries: ReadonlyMap<stri
 			vectorSha256: role.vector.sha256,
 		})),
 		orchestration,
+		routing,
 		entries,
 		entrySha256,
 		treeSha256: bundleTreeSha256(entrySha256),
@@ -745,6 +782,18 @@ export const PROVIDER_CAPABILITIES_BASELINE_SCHEMA = "gentle-pi.provider-contrac
 export const PROVIDER_ROLES_BASELINE_FILE = "provider-roles.baseline.json";
 export const PROVIDER_CAPABILITIES_BASELINE_FILE = "provider-capabilities.baseline.json";
 
+function runtimeFileBaseline(
+	bundle: VerifiedProviderContractBundle,
+	inventory: RuntimeFileInventory,
+	texts: ReadonlyMap<string, string>,
+): { runtime: string; path: string; sha256: string | undefined }[] {
+	return [...texts.keys()].sort().map((runtime) => ({
+		runtime,
+		path: `${inventory}/${runtime}.md`,
+		sha256: bundle.entrySha256.get(`${inventory}/${runtime}.md`),
+	}));
+}
+
 /**
  * Deterministically derives the provider-owned consumer contract surface from
  * a verified bundle. Pi overlays never live in these files; they are pure
@@ -773,11 +822,8 @@ export function generateProviderContractBaselines(bundle: VerifiedProviderContra
 		mandatory_capabilities: mandatory,
 		runtimes: bundle.runtimes === undefined ? null : [...bundle.runtimes],
 		pi_registered: piRuntimeRegistration(bundle).registered,
-		orchestration: [...bundle.orchestration.keys()].sort().map((runtime) => ({
-			runtime,
-			path: `orchestration/${runtime}.md`,
-			sha256: bundle.entrySha256.get(`orchestration/${runtime}.md`),
-		})),
+		orchestration: runtimeFileBaseline(bundle, "orchestration", bundle.orchestration),
+		routing: runtimeFileBaseline(bundle, "routing", bundle.routing),
 	};
 	return new Map([
 		[PROVIDER_ROLES_BASELINE_FILE, `${JSON.stringify(roles, null, 2)}\n`],