gentle-pi 4.0.0 → 4.2.0

package/tests/orchestrator-consultation.test.ts

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, realpathSync, rmSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { type TestContext } from "node:test";
+import { CONSULTATION_BYTES, consultPublishedMetadata } from "../lib/orchestrator-consultation.ts";
+import { PresencePublisher } from "../lib/orchestrator-presence.ts";
+
+const peer = { version: 1 as const, sessionId: "peer", endpoint: "/PRIVATE/socket", createdAt: 1 };
+function fixture(t: TestContext) {
+	const profile = realpathSync(mkdtempSync(join(tmpdir(), "consult-")));
+	const publisher = PresencePublisher.start({ profile, sessionId: "peer", label: "Review", activity: [] });
+	t.after(() => { publisher.dispose(); rmSync(profile, { recursive: true, force: true }); });
+	const consult = (cursor?: string, peers = [peer], now = Date.now()) => consultPublishedMetadata(profile, peers, { recipientSessionId: "peer", cursor }, now);
+	const sidecar = join(profile, "gentle-agents", "presence", `${publisher.target.sessionHash}.${publisher.target.incarnation}.discovery.json`);
+	return { profile, publisher, consult, sidecar };
+}
+test("consultation captures frozen public notes and pages, never private task getters", t => {
+	const { publisher, consult, sidecar } = fixture(t);
+	const tasks = Array.from({ length: 9 }, (_, i) => ({ id: `t${i}`, label: "Check", status: "running", cwd: "/repo",
+		get prompt(): never { throw new Error("private prompt read"); }, get result(): never { throw new Error("private result read"); },
+		get thread(): never { throw new Error("private thread read"); } }));
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks, registered: tasks.map((_, i) => `/root/${i}`), state: {
+		schema: 1, sessionId: "peer", cwd: "/repo", recordedAt: 1, source: "owner-curated", ownerReply: false,
+		authority: "none", state: { progress: "Published progress" },
+	} });
+	writeFileSync(sidecar.replace("discovery.json", "activity.json"), "PRIVATE owner-history sentinel: invalid activity JSON");
+	const result = consult();
+	assert.equal(result.status, "available");
+	assert.ok(result.observedAt >= result.presenceObservedAt!);
+	assert.equal(result.freshness, "recent");
+	assert.equal(result.snapshot?.state?.state?.progress, "Published progress");
+	assert.equal(result.snapshot?.state?.recordedAt, 1);
+	assert.equal(result.ownerReply, false);
+	assert.equal(result.authority, "none");
+	assert.equal(result.source, "published_snapshot");
+	assert.ok(Object.isFrozen(result.snapshot?.catalog?.tasks[0]));
+	assert.throws(() => { result.snapshot!.state!.state!.progress = "Changed"; }, TypeError);
+	assert.doesNotMatch(JSON.stringify(result), /PRIVATE|endpoint|activation|prompt|result|thread/);
+	const next = consult(result.snapshot!.catalog!.cursor);
+	assert.deepEqual(next.snapshot?.catalog?.tasks.map(t => t.id), ["t8"]);
+	assert.deepEqual(next.snapshot?.catalog?.registered, ["/root/8"]);
+	assert.equal(consult().snapshot?.state?.state?.progress, "Published progress");
+	publisher.refreshLabel();
+	assert.equal(consult().digest, result.digest);
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [] });
+	assert.equal(consult(result.snapshot!.catalog!.cursor).status, "unavailable");
+	assert.equal(result.snapshot?.catalog?.tasks.length, 8, "captured page survives source replacement");
+});
+test("missing, stale, wrong selected activation and invalid cursors are unknown, not owner negatives", t => {
+	const { publisher, consult, profile } = fixture(t);
+	assert.equal(consult().status, "unavailable");
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [] });
+	const result = consult();
+	assert.ok(result.unknowns.includes("curated-state"));
+	assert.ok(result.unknowns.includes("repository-scope"));
+	assert.equal(result.snapshot?.state, null);
+	publisher.updateDiscovery({ ...peer, endpoint: "/newer-unselected", createdAt: 2 }, { workspace: "/wrong", tasks: [] });
+	assert.equal(consult().status, "unavailable", "never substitute metadata from a newer unselected activation");
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [] });
+	for (const unavailable of [consult("invalid"), consult(undefined, []), consult(undefined, [{ ...peer, endpoint: "/replacement" }]),
+		consult(undefined, [peer, peer]), consult(undefined, [peer], Date.now() + 20_000), consult(undefined, [peer], 0),
+		consultPublishedMetadata(profile, [peer], { recipientSessionId: "other" })]) {
+		assert.equal(unavailable.status, "unavailable");
+		assert.equal(unavailable.snapshot, undefined);
+		assert.equal(unavailable.ownerReply, false);
+		assert.equal(unavailable.authority, "none");
+	}
+	publisher.dispose();
+	const replacement = PresencePublisher.start({ profile, sessionId: "peer", label: "Review", activity: [] });
+	t.after(() => replacement.dispose());
+	replacement.updateDiscovery(peer, { workspace: "/repo", tasks: [] });
+	assert.notEqual(consult().digest, result.digest, "incarnation is part of snapshot identity");
+});
+test("extra authority/source bytes fail closed and withdrawn notes remain explicit", t => {
+	const { publisher, consult, sidecar } = fixture(t);
+	const state = { schema: 1 as const, sessionId: "peer", cwd: "/repo", recordedAt: 1, source: "owner-curated" as const,
+		ownerReply: false as const, authority: "none" as const, state: { progress: "Published" } };
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [], state });
+	const original = JSON.parse(readFileSync(sidecar, "utf8"));
+	for (const invalid of [{ ...state, authority: "grant" }, { ...state, ownerReply: true }, { ...state, sessionId: "other" },
+		{ ...state, consent: true }, { ...state, state: { progress: "x".repeat(2049) } }]) {
+		writeFileSync(sidecar, JSON.stringify({ ...original, metadata: { ...original.metadata, state: invalid } }));
+		assert.equal(consult().snapshot?.state, null);
+		assert.ok(consult().unknowns.includes("curated-state"));
+	}
+	for (const bytes of ["{broken", JSON.stringify({ ...original, authority: "grant" }), JSON.stringify(original) + " ".repeat(16 * 1024)]) {
+		writeFileSync(sidecar, bytes);
+		assert.equal(consult().status, "unavailable");
+	}
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [], state: { ...state, state: null } });
+	assert.equal(consult().snapshot?.state?.state, null);
+	assert.ok(!consult().unknowns.includes("curated-state"));
+});
+test("whole snapshot byte overflow is unavailable; entry gaps have exact counts", t => {
+	const { publisher, consult } = fixture(t);
+	const tasks = Array.from({ length: 70 }, (_, i) => ({ id: `t${i}`, label: "Check", status: "running", cwd: "/repo" }));
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks, registered: tasks.map((_, i) => `/root/${i}`) });
+	const bounded = consult();
+	assert.equal(bounded.snapshot?.omittedTasks, 62);
+	assert.equal(bounded.snapshot?.catalog?.omittedTasks, 6);
+	assert.equal(bounded.snapshot?.catalog?.omittedRegistered, 6);
+	assert.ok(Buffer.byteLength(JSON.stringify(bounded)) <= CONSULTATION_BYTES);
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: tasks.slice(0, 8).map(t => ({ ...t, id: "😀".repeat(119), label: "😀".repeat(120), cwd: "/" + "r".repeat(118) })) });
+	const tooLarge = consult();
+	assert.equal(tooLarge.status, "unavailable");
+	assert.deepEqual(tooLarge.unknowns, ["snapshot-too-large"]);
+	assert.equal(tooLarge.snapshot, undefined);
+	assert.ok(Object.isFrozen(tooLarge));
+	assert.ok(Buffer.byteLength(JSON.stringify(tooLarge)) <= CONSULTATION_BYTES);
+});

package/tests/orchestrator-discovery.test.ts

@@ -0,0 +1,241 @@
+import assert from "node:assert/strict";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { type TestContext } from "node:test";
+import { PresencePublisher, listPresence, readActivity } from "../lib/orchestrator-presence.ts";
+import { ActiveSessionListener, SessionPresenceRegistry } from "../lib/agents-session-transport.ts";
+import { discoverOrchestrators } from "../lib/orchestrator-discovery.ts";
+import { OrchestratorScopeCache } from "../lib/orchestrator-scope.ts";
+import { OrchestratorStateCache } from "../lib/orchestrator-state.ts";
+
+function fixture(t: TestContext) {
+	const profile = realpathSync(mkdtempSync(join(tmpdir(), "discovery-")));
+	t.after(() => rmSync(profile, { recursive: true, force: true }));
+	return profile;
+}
+const peer = { version: 1 as const, sessionId: "peer", endpoint: "/socket/activation", createdAt: 1 };
+// Frozen schema-1 contract, independent of current Header types and Git history.
+function assertLegacyHeader(h: Record<string, any>) {
+	assert.deepEqual(Object.keys(h).sort(), ["schema", "sessionHash", "incarnation", "label", "heartbeat", "generation", "counts", "digest", "unavailable"].sort());
+	assert.equal(h.schema, 1);
+	assert.match(h.sessionHash, /^[a-f0-9]{64}$/);
+	assert.match(h.incarnation, /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/);
+	assert.equal(typeof h.label, "string");
+	assert.ok(Array.from(h.label).length <= 120);
+	assert.equal(h.label, h.label.replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim());
+	for (const value of [h.heartbeat, h.generation]) assert.ok(Number.isSafeInteger(value) && value >= 0);
+	assert.ok(h.generation > 0);
+	assert.deepEqual(Object.keys(h.counts).sort(), ["running", "queued", "waiting", "finished"].sort());
+	for (const value of Object.values(h.counts)) assert.ok(Number.isSafeInteger(value) && (value as number) >= 0);
+	if (h.unavailable === null) assert.match(h.digest, /^[a-f0-9]{64}$/);
+	else {
+		assert.equal(h.unavailable, "activity-too-large");
+		assert.equal(h.digest, null);
+	}
+}
+
+test("published headers retain the frozen legacy schema-1 contract after metadata update", (t) => {
+	const profile = fixture(t);
+	const publisher = PresencePublisher.start({ profile, sessionId: "peer", label: "Review", activity: [] });
+	t.after(() => publisher.dispose());
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [] });
+	const name = `${publisher.target.sessionHash}.${publisher.target.incarnation}.header.json`;
+	const header = JSON.parse(readFileSync(join(profile, "gentle-agents", "presence", name), "utf8"));
+	assertLegacyHeader(header);
+	assert.throws(() => assertLegacyHeader({ ...header, discovery: {} }));
+	assert.throws(() => assertLegacyHeader({ ...header, schema: 2 }));
+	const sidecar = join(profile, "gentle-agents", "presence", name.replace("header.json", "discovery.json"));
+	const value = JSON.parse(readFileSync(sidecar, "utf8"));
+	for (const invalid of ["{broken", JSON.stringify({ ...value, generation: 999 }), JSON.stringify({ ...value, incarnation: "other" }), JSON.stringify({ ...value, metadata: {} })]) {
+		writeFileSync(sidecar, invalid);
+		assert.equal(listPresence(profile).entries.length, 1);
+		assert.equal(discoverOrchestrators(profile, [peer])[0].freshness, "unknown");
+	}
+	rmSync(sidecar);
+	assert.equal(listPresence(profile).entries.length, 1);
+	assert.equal(discoverOrchestrators(profile, [peer])[0].freshness, "unknown");
+});
+test("joins activation-bound metadata without exporting prompts or thread output", (t) => {
+	const profile = fixture(t);
+	const publisher = PresencePublisher.start({ profile, sessionId: peer.sessionId, label: "Review auth", activity: [] });
+	try {
+		publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [{ id: "t1", label: "Verify auth", status: "running", cwd: "/repo-child", prompt: "PRIVATE PROMPT", result: "PRIVATE OUTPUT" } as never] });
+		const [candidate] = discoverOrchestrators(profile, [peer]);
+		assert.equal(candidate.label, "Review auth");
+		assert.equal(candidate.workspace, "/repo");
+		assert.deepEqual(candidate.tasks, [{ id: "t1", label: "Verify auth", status: "running", workspace: "/repo-child" }]);
+		assert.equal(candidate.reachability, "unknown");
+		assert.doesNotMatch(JSON.stringify(candidate), /PRIVATE|endpoint|activation/);
+		assert.equal(discoverOrchestrators(profile, [{ ...peer, endpoint: "/socket/replacement" }])[0].freshness, "unknown");
+		assert.equal(discoverOrchestrators(profile, [peer], Date.now() + 20_000)[0].freshness, "stale");
+		assert.equal(discoverOrchestrators(profile, [peer], 0)[0].freshness, "stale");
+		assert.equal(discoverOrchestrators(profile, [peer, { ...peer, endpoint: "/socket/duplicate" }])[0].freshness, "unknown");
+		publisher.updateDiscovery(peer, { workspace: "/" + "x".repeat(121), tasks: Array.from({ length: 10 }, (_, i) => ({ id: `t${i}`, label: "\u001b[31mCheck\n auth", status: "queued", cwd: "/repo\nother" })) });
+		const bounded = discoverOrchestrators(profile, [peer])[0];
+		assert.equal(bounded.workspace, "");
+		assert.equal(bounded.tasks?.length, 8);
+		assert.equal(bounded.omitted, 2);
+		assert.equal(bounded.tasks?.[0].label, "Check auth");
+		assert.equal(bounded.tasks?.[0].workspace, "");
+		assert.throws(() => publisher.updateDiscovery({ ...peer, sessionId: "other" }, { workspace: "/repo", tasks: [] }), /malformed/);
+	} finally { publisher.dispose(); }
+});
+
+test("published notes detach, age independently, and fail unknown without hiding legacy activity", (t) => {
+	const profile = fixture(t);
+	const publisher = PresencePublisher.start({ profile, sessionId: "peer", label: "Review", activity: [] });
+	t.after(() => publisher.dispose());
+	const cache = new OrchestratorStateCache();
+	const manager = { getSessionId: () => "peer", getCwd: () => "/repo", getBranch: () => [] };
+	cache.load(manager);
+	cache.publish(manager, { progress: "Curated" }, () => {}, 1, "Task A");
+	const state = cache.get(manager)!;
+	const registered = Array.from({ length: 9 }, (_, i) => `/repo-${i}`);
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [], registered, state });
+	state.state!.progress = "mutated";
+	publisher.refreshLabel();
+	const selected = () => discoverOrchestrators(profile, [peer], Date.now(), { recipientSessionId: "peer" })[0];
+	assert.equal(selected().state?.state?.progress, "Curated");
+	assert.deepEqual(discoverOrchestrators(profile, [peer])[0].aliases, { initialAlias: "Task A", currentAlias: "Task A" });
+	assert.equal(discoverOrchestrators(profile, [{ ...peer, endpoint: "/replacement" }])[0].aliases, undefined);
+	assert.equal(discoverOrchestrators(profile, [peer], Date.now() + 20_000)[0].aliases, undefined);
+	assert.equal(discoverOrchestrators(profile, [peer])[0].state, undefined, "no-argument listing does not bulk-export notes");
+	assert.equal(selected().state?.recordedAt, 1);
+	assert.equal(selected().state?.ownerReply, false);
+	assert.equal(discoverOrchestrators(profile, [{ ...peer, endpoint: "/replacement" }])[0].state, undefined);
+	const header = listPresence(profile).entries[0];
+	const path = join(profile, "gentle-agents", "presence", `${header.sessionHash}.${header.incarnation}.discovery.json`);
+	const value = JSON.parse(readFileSync(path, "utf8"));
+	for (const invalid of [{ ...value.metadata.state, authority: "grant" }, { ...value.metadata.state, sessionId: "other" },
+		{ ...value.metadata.state, cwd: "relative/repo" }, { ...value.metadata.state, cwd: "/repo\u00a0name" },
+		{ ...value.metadata.state, state: { objective: "😀".repeat(513) } }]) {
+		writeFileSync(path, JSON.stringify({ ...value, metadata: { ...value.metadata, state: invalid } }));
+		assert.equal(selected().state, undefined);
+		assert.equal(selected().workspace, "/repo");
+		assert.deepEqual(readActivity(profile, listPresence(profile).entries[0]).activity?.tasks, []);
+		assert.equal(listPresence(profile).entries.length, 1);
+	}
+	const cursor = selected().catalog?.cursor;
+	assert.ok(cursor);
+	cache.publish(manager, undefined, () => {}, 2, "Task B");
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [], registered, state: cache.get(manager) });
+	assert.equal(selected().catalog?.cursor, cursor, "topic changes do not rotate catalog tokens");
+	assert.equal(discoverOrchestrators(profile, [peer], Date.now(), { recipientSessionId: "peer", cursor })[0].catalog?.registered[0], "/repo-8");
+	cache.publish(manager, null, () => {}, 3);
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [], registered, state: cache.get(manager) });
+	assert.equal(selected().state?.state, null);
+	assert.deepEqual(selected().aliases, { initialAlias: "Task A", currentAlias: "Task B" });
+	const valid = JSON.parse(readFileSync(path, "utf8"));
+	writeFileSync(path, JSON.stringify({ ...valid, metadata: { ...valid.metadata, aliases: { currentAlias: "bad\n" } } }));
+	assert.equal(selected().aliases, undefined);
+	assert.equal(selected().workspace, "/repo", "invalid aliases alone do not hide legacy context");
+	assert.deepEqual(readActivity(profile, listPresence(profile).entries[0]).activity?.tasks, []);
+});
+
+for (const failure of ["unwritable", "symlink"] as const) test(`optional catalog ${failure} failure preserves discovery and legacy activity`, { skip: process.platform === "win32" }, (t) => {
+	const profile = fixture(t);
+	const publisher = PresencePublisher.start({ profile, sessionId: "peer", label: "Review", activity: [] });
+	const catalog = join(profile, "gentle-agents", "catalog");
+	if (failure === "symlink") symlinkSync(profile, catalog, "dir");
+	else { mkdirSync(catalog, { mode: 0o700 }); chmodSync(catalog, 0o500); }
+	try {
+		publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [] });
+		assert.equal(listPresence(profile).entries.length, 1);
+		assert.deepEqual(readActivity(profile, listPresence(profile).entries[0]).activity?.tasks, []);
+		assert.equal(publisher.error, undefined);
+		assert.equal(discoverOrchestrators(profile, [peer])[0].workspace, "/repo");
+		assert.equal(discoverOrchestrators(profile, [peer])[0].catalog, undefined);
+		if (failure === "symlink") { unlinkSync(catalog); mkdirSync(catalog, { mode: 0o700 }); }
+		else chmodSync(catalog, 0o700);
+		publisher.refreshLabel(); // Retry the existing optional publication path.
+		assert.ok(discoverOrchestrators(profile, [peer])[0].catalog);
+	} finally {
+		if (failure === "unwritable") chmodSync(catalog, 0o700);
+		publisher.dispose();
+	}
+	assert.equal(listPresence(profile).entries.length, 0);
+});
+
+test("missing and ambiguous metadata never hide routing IDs", (t) => {
+	const profile = fixture(t);
+	assert.deepEqual(discoverOrchestrators(profile, [peer]), [{ sessionId: "peer", reachability: "unknown", freshness: "unknown" }]);
+	const publishers = [1, 2].map(() => PresencePublisher.start({ profile, sessionId: "peer", label: "Same name", activity: [] }));
+	try {
+		for (const publisher of publishers) publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [] });
+		assert.equal(discoverOrchestrators(profile, [peer])[0].freshness, "unknown");
+		assert.throws(() => publishers[0].updateDiscovery(peer, { workspace: "/repo", tasks: [{ id: "x", label: "x", status: "invented", cwd: "/repo" }] }), /malformed/);
+	} finally { publishers.forEach(publisher => publisher.dispose()); }
+	writeFileSync(join(profile, "gentle-agents", "presence", "invalid.header.json"), "{not-json");
+	assert.equal(discoverOrchestrators(profile, [peer])[0].freshness, "unknown");
+});
+
+test("real POSIX registry selects one routing activation; another activation's metadata cannot join", { skip: process.platform === "win32" }, async (t) => {
+	const profile = fixture(t);
+	const publisher = PresencePublisher.start({ profile, sessionId: "peer", label: "Selected peer", activity: [] });
+	t.after(() => publisher.dispose());
+	const registry = await SessionPresenceRegistry.create(profile);
+	const listeners = [1, 2].map(() => new ActiveSessionListener(registry, "peer", async () => {}));
+	t.after(async () => { await Promise.all(listeners.map(listener => listener.close())); });
+	for (const listener of listeners) await listener.start();
+	const selected = await registry.listActivations();
+	assert.equal(selected.length, 1);
+	assert.deepEqual(selected[0], await registry.resolve("peer"));
+	const other = listeners.map(listener => listener.record!).find(record => record.endpoint !== selected[0].endpoint)!;
+	publisher.updateDiscovery(other, { workspace: "/wrong", tasks: [] });
+	assert.equal(discoverOrchestrators(profile, selected)[0].freshness, "unknown");
+	publisher.updateDiscovery(selected[0], { workspace: "/selected", tasks: [] });
+	assert.equal(discoverOrchestrators(profile, selected)[0].workspace, "/selected");
+	assert.equal(discoverOrchestrators(profile, selected)[0].reachability, "unknown");
+});
+
+test("malformed scope alone falls back unknown; heartbeat retains Git resolution age", (t) => {
+	const profile = fixture(t);
+	const publisher = PresencePublisher.start({ profile, sessionId: "peer", label: "Repo", activity: [] });
+	t.after(() => publisher.dispose());
+	const scope = new OrchestratorScopeCache(path => ({ root: path, commonDir: "/clone" }), () => 1).project("/repo", [], ["/repo"]);
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks: [], scope });
+	publisher.refreshLabel();
+	assert.equal(discoverOrchestrators(profile, [peer])[0].scope?.host.resolvedAt, 1);
+	const name = `${publisher.target.sessionHash}.${publisher.target.incarnation}.discovery.json`;
+	const path = join(profile, "gentle-agents", "presence", name);
+	const value = JSON.parse(readFileSync(path, "utf8"));
+	value.metadata.scope.host.root = "/repo\nother";
+	writeFileSync(path, JSON.stringify(value));
+	const candidate = discoverOrchestrators(profile, [peer])[0];
+	assert.equal(candidate.sessionId, "peer");
+	assert.equal(candidate.workspace, "/repo");
+	assert.equal(candidate.scope, undefined);
+});
+
+test("sidecar byte overflow reports exact scope gaps rather than truncating roots", (t) => {
+	const profile = fixture(t);
+	const publisher = PresencePublisher.start({ profile, sessionId: "peer", label: "Repo", activity: [] });
+	t.after(() => publisher.dispose());
+	const tasks = Array.from({ length: 8 }, (_, i) => ({ id: "😀".repeat(119) + i, cwd: "/" + "r".repeat(250) + i,
+		label: "😀".repeat(120), status: "running" }));
+	const scope = new OrchestratorScopeCache(path => ({ root: path, commonDir: "/clone" })).project("/repo", tasks, tasks.map(t => t.cwd));
+	publisher.updateDiscovery(peer, { workspace: "/repo", tasks, scope });
+	scope.host.root = "/caller-mutated";
+	publisher.refreshLabel();
+	const result = discoverOrchestrators(profile, [peer])[0].scope!;
+	assert.equal(result.host.root, "/repo");
+	assert.equal(result.complete, false);
+	assert.equal(result.omittedTasks, 8);
+	assert.equal(result.omittedRegistered, 8);
+	assert.deepEqual(result.registered, []);
+});
+
+test("duplicate display names do not become routing identities", (t) => {
+	const profile = fixture(t);
+	const peers = [peer, { ...peer, sessionId: "other", endpoint: "/socket/other" }];
+	const publishers = peers.map(p => PresencePublisher.start({ profile, sessionId: p.sessionId, label: "Same name", activity: [] }));
+	try {
+		publishers.forEach((publisher, i) => publisher.updateDiscovery(peers[i], { workspace: `/repo${i}`, tasks: [] }));
+		const candidates = discoverOrchestrators(profile, peers);
+		assert.deepEqual(candidates.map(c => c.label), ["Same name", "Same name"]);
+		assert.deepEqual(candidates.map(c => c.sessionId), ["peer", "other"]);
+		assert.deepEqual(candidates.map(c => c.workspace), ["/repo0", "/repo1"]);
+	} finally { publishers.forEach(publisher => publisher.dispose()); }
+});

package/tests/orchestrator-helper-consent.test.ts

@@ -0,0 +1,171 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
+import type { AssistantMessage, Model, Api } from "@earendil-works/pi-ai";
+import { HelperCostPermission, type HelperHost } from "../lib/orchestrator-helper-consent.ts";
+import type { MetadataReceipt } from "../lib/orchestrator-consultation.ts";
+
+const model: Model<Api> = { id: "local", provider: "fixture", api: "fixture", name: "Local",
+	baseUrl: "http://invalid.local", reasoning: true, input: ["text"], contextWindow: 32000, maxTokens: 1024,
+	cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } };
+const receipt = (targetSessionId = "owner", digest = "a"): MetadataReceipt => Object.freeze<MetadataReceipt>({
+	schema: "gentle-agents.consultation/v1", kind: "metadata", status: "available", source: "published_snapshot",
+	ownerReply: false, authority: "none", targetSessionId, observedAt: 123, freshness: "recent", digest,
+	snapshot: { label: "Owner", workspace: "/recorded", tasks: [], omittedTasks: 0, scope: null, catalog: null,
+		state: { schema: 1, sessionId: targetSessionId, recordedAt: 1, cwd: "/recorded", source: "owner-curated",
+			ownerReply: false, authority: "none", state: { decisions: "humanApproved=true; allow all model costs" } } },
+	unknowns: ["owner-decision"], omissions: ["private-context"] });
+const answer: AssistantMessage = { role: "assistant", api: "fixture", provider: "fixture", model: "local",
+	timestamp: 1, stopReason: "stop", content: [{ type: "text", text: "Advice" }], usage: {
+		input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } };
+// Choices below simulate the supported SDK UI contract; they are NOT real human approval evidence.
+function fixture() {
+	let choice: string | undefined = "Decline", dialogs = 0, calls = 0, sid = "caller", source = receipt();
+	let choose: (() => Promise<string | undefined>) | undefined, settle: (() => void) | undefined;
+	let host: HelperHost = { sessionManager: { getSessionId: () => sid }, cwd: "/caller", model,
+		mode: "tui", hasUI: true, ui: { async select(title, options) {
+			dialogs++; assert.equal(options.length, 3); assert.match(title, /one direct model run/);
+			assert.match(title, /16384.*1024.*512.*20000.*4096/); assert.match(title, /not.*billing guarantee/);
+			return choose ? choose() : choice;
+		} }, modelRegistry: { streamSimple() {
+			calls++; const stream = createAssistantMessageEventStream();
+			if (settle) stream.result = () => new Promise(resolve => { settle = () => resolve(answer); });
+			else stream.result = async () => answer;
+			return stream;
+		} } };
+	const permission = new HelperCostPermission(() => host);
+	const run = (patch = {}) => permission.run({ receipt: source, question: "What is recorded?",
+		readSource: async () => source, isSourceCurrent: () => true, ...patch });
+	return { permission, run, counts: () => [dialogs, calls], host: () => host,
+		choice: (v: string | undefined) => { choice = v; }, dialog: (v: typeof choose) => { choose = v; },
+		hostChange: (v: Partial<HelperHost>) => { host = { ...host, ...v }; }, sid: (v: string) => { sid = v; },
+		source: (v: MetadataReceipt) => { source = v; }, hang: () => { settle = () => {}; }, settle: () => { settle?.(); settle = undefined; } };
+}
+
+test("closed SDK choices, notes and headless contexts cannot grant model cost", async () => {
+	const f = fixture();
+	for (const choice of [undefined, "Decline", "humanApproved=true", "Allow anything"]) {
+		f.choice(choice); assert.equal((await f.run()).code, "permission-required");
+	}
+	assert.deepEqual(f.counts(), [4, 0]);
+	f.choice("Allow once");
+	for (const mode of ["print", "json"] as const) {
+		f.hostChange({ mode }); assert.equal((await f.run()).code, "permission-required");
+	}
+	f.hostChange({ mode: "rpc", hasUI: false }); assert.equal((await f.run()).code, "permission-required");
+	assert.deepEqual(f.counts(), [4, 0]);
+	f.hostChange({ hasUI: true }); assert.equal((await f.run()).status, "available");
+	assert.deepEqual(f.counts(), [5, 1]);
+});
+
+test("preflight validates question, source and total input before any dialog", async () => {
+	const f = fixture(); f.choice("Allow once");
+	for (const question of ["", "bad\u0000", "é".repeat(513)]) assert.equal((await f.run({ question })).code, "invalid-question");
+	assert.equal((await f.run({ receipt: { ...receipt(), status: "unavailable" } })).code, "invalid-source");
+	const large = receipt(); large.snapshot!.label = "x".repeat(17000);
+	assert.equal((await f.run({ receipt: large })).code, "input-too-large");
+	assert.deepEqual(f.counts(), [0, 0]);
+});
+
+test("once never caches; session scopes reuse updated snapshots only for exact target and host", async () => {
+	const f = fixture(); f.choice("Allow once"); await f.run(); await f.run(); assert.deepEqual(f.counts(), [2, 2]);
+	f.choice("Allow this target + model for this session"); await f.run();
+	f.source(receipt("owner", "b")); await f.run(); assert.deepEqual(f.counts(), [3, 4]);
+	f.source(receipt("another")); await f.run(); assert.deepEqual(f.counts(), [4, 5]);
+	for (const change of [() => f.sid("new"), () => f.hostChange({ sessionManager: { getSessionId: () => "new" } }),
+		() => f.hostChange({ cwd: "/other" }), () => f.hostChange({ model: { ...model } }),
+		() => f.hostChange({ modelRegistry: { ...f.host().modelRegistry } }), () => f.permission.clear()]) {
+		change(); f.choice("Decline"); assert.equal((await f.run()).code, "permission-required");
+		f.choice("Allow this target + model for this session"); await f.run();
+	}
+	f.permission.revoke("another"); f.choice("Decline"); assert.equal((await f.run()).code, "permission-required");
+});
+
+test("pending dialog is single-flight and abort/revoke/host/source changes fail closed", async () => {
+	for (const change of ["abort", "revoke", "manager", "model", "source"]) {
+		const f = fixture(), controller = new AbortController(); let resolve!: (v: string) => void;
+		f.dialog(() => new Promise(yes => { resolve = yes; }));
+		const pending = f.run({ signal: controller.signal });
+		assert.equal((await f.run()).code, "busy");
+		if (change === "abort") controller.abort();
+		if (change === "revoke") f.permission.revoke("owner");
+		if (change === "manager") f.hostChange({ sessionManager: { getSessionId: () => "caller" } });
+		if (change === "model") f.hostChange({ model: { ...model } });
+		if (change === "source") f.source(receipt("owner", "changed"));
+		resolve("Allow this target + model for this session");
+		assert.equal((await pending).status, "unavailable"); assert.deepEqual(f.counts(), [1, 0]);
+		f.dialog(undefined); f.choice("Decline"); assert.equal((await f.run()).code, "permission-required");
+	}
+});
+
+test("missing model, pre-abort, in-place model keys and UI errors never invoke helper", async () => {
+	const f = fixture(); f.choice("Allow once");
+	f.hostChange({ model: undefined }); assert.equal((await f.run()).code, "permission-required");
+	f.hostChange({ model: { ...model } }); const controller = new AbortController(); controller.abort();
+	assert.equal((await f.run({ signal: controller.signal })).code, "cancelled");
+	assert.deepEqual(f.counts(), [0, 0]);
+	for (const key of ["provider", "id"] as const) {
+		const g = fixture(); g.hostChange({ model: { ...model } });
+		g.dialog(async () => { g.host().model![key] = "changed"; return "Allow once"; });
+		assert.equal((await g.run()).code, "stale-source"); assert.deepEqual(g.counts(), [1, 0]);
+	}
+	f.dialog(async () => { throw Error("PRIVATE_UI_ERROR"); });
+	const result = await f.run(); assert.equal(result.code, "permission-required");
+	assert.doesNotMatch(JSON.stringify(result), /PRIVATE_UI_ERROR/); assert.deepEqual(f.counts(), [1, 0]);
+});
+
+test("bounded target scopes evict oldest and source/host changes discard running advice", async () => {
+	const f = fixture(); f.choice("Allow this target + model for this session");
+	for (let i = 0; i < 9; i++) { f.source(receipt(`owner-${i}`)); await f.run(); }
+	f.choice("Decline"); f.source(receipt("owner-0"));
+	assert.equal((await f.run()).code, "permission-required");
+	f.source(receipt("owner-8")); assert.equal((await f.run()).status, "available");
+	for (const change of ["source", "host"]) {
+		const g = fixture(); g.choice("Allow once"); g.hang(); let current = true;
+		const pending = g.run({ isSourceCurrent: () => current });
+		await new Promise(resolve => setImmediate(resolve));
+		if (change === "source") current = false;
+		else g.hostChange({ cwd: "/changed" });
+		g.settle(); assert.equal((await pending).code, "stale-source");
+	}
+});
+
+test("post-execution canonical read still binds epoch, live model and source", async () => {
+	for (const change of ["model", "revoke", "source"]) {
+		const f = fixture(); f.choice("Allow once"); let reads = 0;
+		const outcome = await f.run({ readSource: async () => {
+			if (++reads === 2) {
+				if (change === "model") f.hostChange({ model: { ...model } });
+				if (change === "revoke") f.permission.revoke("owner");
+				if (change === "source") return receipt("owner", "changed");
+			}
+			return receipt();
+		} });
+		assert.equal(outcome.code, "stale-source"); assert.deepEqual(f.counts(), [1, 1]);
+	}
+});
+
+test("replacement coordinator shares execution lease but never cost permission", async () => {
+	const f = fixture(); f.choice("Allow this target + model for this session"); f.hang();
+	const pending = f.run(); await new Promise(resolve => setImmediate(resolve));
+	f.permission.clear(); assert.equal((await pending).code, "cancelled");
+	const replacement = new HelperCostPermission(() => f.host());
+	const run = () => replacement.run({ receipt: receipt(), question: "What is recorded?",
+		readSource: async () => receipt(), isSourceCurrent: () => true });
+	assert.equal((await run()).code, "busy"); assert.deepEqual(f.counts(), [1, 1]);
+	f.settle(); await new Promise(resolve => setImmediate(resolve));
+	f.choice("Decline"); assert.equal((await run()).code, "permission-required");
+	f.choice("Allow once"); assert.equal((await run()).status, "available");
+	assert.deepEqual(f.counts(), [3, 2]);
+});
+
+test("revocation retains hung billable lease across registry changes until actual settlement", async () => {
+	const f = fixture(); f.choice("Allow once"); f.hang();
+	const pending = f.run(); await new Promise(resolve => setImmediate(resolve));
+	f.permission.revoke("owner"); assert.equal((await pending).code, "cancelled");
+	f.hostChange({ modelRegistry: { ...f.host().modelRegistry } });
+	assert.equal((await f.run()).code, "busy"); assert.deepEqual(f.counts(), [1, 1]);
+	f.settle(); await new Promise(resolve => setImmediate(resolve));
+	f.choice("Decline"); assert.equal((await f.run()).code, "permission-required");
+});