gentle-pi 4.0.0 → 4.2.0

package/lib/orchestrator-tool-card.ts

@@ -0,0 +1,280 @@
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { sanitizeTerminalText } from "./terminal-theme.ts";
+import {
+	CARD_TONE, cardAwaitingResult, cardBodyRows, cardBottom, cardInnerWidth, cardLine, cardRunningLine, cardTop,
+	floatRows, markCardResult, type CardRowContext, type CardTheme, type CardTone,
+} from "./shell-card.ts";
+
+type Operation = "session" | "consult" | "list";
+type Result = { content: Array<{ type: string; text?: string }>; details?: unknown };
+interface Context extends CardRowContext {
+	args?: Record<string, unknown>;
+	expanded?: boolean;
+	isError?: boolean;
+	state?: { orchestratorFailed?: boolean };
+}
+const clean = (value: unknown): string => typeof value === "string" ? sanitizeTerminalText(value) : "";
+const line = (value: unknown): string => clean(value).replace(/\s+/gu, " ").trim();
+const text = (result: Result): string => clean(result.content.filter(part => part.type === "text").map(part => part.text ?? "").join("\n"));
+const record = (value: unknown): Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+const hiddenFields = new Set(["schema", "digest", "publication"]);
+const fieldLabels: Record<string, string> = {
+	sessionId: "Session ID", senderSessionId: "Sender session", recipientSessionId: "Recipient session",
+	targetSessionId: "Target session", id: "ID", cwd: "Workspace",
+};
+function label(key: string): string {
+	const named = Object.hasOwn(fieldLabels, key) ? fieldLabels[key]
+		: line(key).replace(/([a-z])([A-Z])/g, "$1 $2").replace(/_/g, " ").trim().toLowerCase().replace(/^./u, char => char.toUpperCase());
+	return named.replace(/\bid\b/gi, "ID");
+}
+const section = (title: string, rows: string[]): string[] => rows.length ? ["", `${title}:`, ...rows] : [];
+
+/** Format plain tool data as labelled rows, never as JSON or executable terminal text. */
+export function readableDataRows(value: unknown, indent = ""): string[] {
+	const fields = record(value);
+	const unknownRepository = Object.hasOwn(fields, "root") && Object.hasOwn(fields, "cloneHash")
+		&& (fields.root === null || fields.cloneHash === null);
+	return [...(unknownRepository ? [`${indent}Repository identity: unknown`] : []), ...Object.entries(fields).flatMap(([key, entry]) => {
+		if (hiddenFields.has(key) || entry === undefined || entry === null) return [];
+		const heading = `${indent}${label(key)}:`;
+		if (key === "cursor") return [`${indent}Continuation token: provided`];
+		if (Array.isArray(entry)) {
+			const rows = entry.flatMap((item, index) => {
+				if (item !== null && typeof item === "object") {
+					const { label: itemLabel, ...fields } = record(item);
+					return [`${indent}  ${index + 1}.${line(itemLabel) ? ` ${line(itemLabel)}` : ""}`, ...readableDataRows(fields, `${indent}    `)];
+				}
+				return item === null ? [] : [`${indent}  • ${line(String(item))}`];
+			});
+			return rows.length ? [heading, ...rows] : [];
+		}
+		if (typeof entry === "object") {
+			const rows = readableDataRows(entry, `${indent}  `);
+			return rows.length ? [heading, ...rows] : [];
+		}
+		const shown = typeof entry === "boolean" ? entry ? "yes" : "no" : clean(String(entry));
+		return shown ? [`${heading} ${shown}`] : [];
+	})];
+}
+
+function parsedOutput(result: Result): unknown {
+	const body = text(result);
+	try { return JSON.parse(body); } catch { return body; }
+}
+
+function requestRows(args: unknown): string[] {
+	const input = record(args);
+	return readableDataRows(input.state === null ? { ...input, state: "withdrawn" } : input);
+}
+
+/** Prefer structured data over its duplicated model-facing serialization. */
+export function expandedToolRows(args: unknown, result: Result): string[] {
+	const data = record(record(result.details).gentleAgents);
+	const output = Object.keys(data).length ? data : parsedOutput(result);
+	return [...section("Request", requestRows(args)), ...section("Details", typeof output === "string" ? output.split("\n") : readableDataRows(output)),
+		...result.content.filter(part => part.type !== "text").map(part => `Attachment: ${line(part.type)}`)];
+}
+
+function discoveredSessionRows(candidates: unknown[]): string[] {
+	const missing = candidates.filter(candidate => record(candidate).freshness !== "recent").length;
+	return [...(missing ? [`Metadata unavailable for ${missing} session${missing === 1 ? "" : "s"}; no current context inferred.`, ""] : []),
+		...candidates.flatMap((candidate, index) => {
+			const peer = record(candidate);
+			const { sessionId, label: peerLabel, reachability, freshness, ...context } = peer;
+			const recent = freshness === "recent";
+			return [`${index + 1}. ${recent && line(peerLabel) ? line(peerLabel) : "Session"}`,
+				`  Session ID: ${line(sessionId)}`, ...(recent ? [
+					...(!Object.keys(record(context.scope)).length ? ["  Repository scope: unknown"] : []),
+					...readableDataRows(context, "  "),
+				] : []), ""];
+		})];
+}
+
+const OVERVIEW_LIMIT = 6;
+interface OverviewRow { name: string; id: string; context: string; tasks: string }
+interface OverviewTheme extends CardTheme { bold?(value: string): string }
+const shortId = (value: unknown): string => {
+	const id = line(value);
+	return visibleWidth(id) <= 13 ? id : `${Array.from(id).slice(0, 8).join("")}…${Array.from(id).slice(-4).join("")}`;
+};
+const workspaceName = (value: unknown): string => line(value).split(/[\\/]/).filter(Boolean).at(-1) || line(value) || "—";
+const positiveCount = (value: unknown): number => typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : 0;
+
+/** One physical row per item, including on narrow terminals; expansion is not an unbounded dump. */
+function overviewTable(rows: OverviewRow[], width: number, work: boolean, theme: OverviewTheme): string[] {
+	const cell = (value: string, columns: number, role: string, heading: boolean) => {
+		const clipped = truncateToWidth(value, columns, "…");
+		const styled = theme.fg(heading ? "toolTitle" : role, clipped);
+		return (heading && theme.bold ? theme.bold(styled) : styled) + " ".repeat(Math.max(0, columns - visibleWidth(clipped)));
+	};
+	const format = (row: OverviewRow, heading = false) => {
+		if (width < 40) {
+			const styled = truncateToWidth(`${theme.fg(heading ? "toolTitle" : "dim", row.id)} ${theme.fg(heading ? "toolTitle" : "accent", row.name)}`, width, "…");
+			return heading && theme.bold ? theme.bold(styled) : styled;
+		}
+		const name = (columns: number) => cell(row.name, columns, "accent", heading);
+		const id = cell(row.id, 13, "dim", heading);
+		if (width < 64) return `${name(width - 15)}  ${id}`;
+		const nameWidth = Math.min(36, width - (work ? 37 : 44));
+		const tasksRole = row.tasks === "?" ? "warning" : row.tasks === "0" ? "muted" : "syntaxNumber";
+		return `${name(nameWidth)}  ${id}  ${cell(row.context, 20, "muted", heading)}${work ? "" : `  ${cell(row.tasks, 5, tasksRole, heading)}`}`;
+	};
+	return rows.length ? [format({ name: "Alias", id: "ID (short)", context: work ? "Work" : "Workspace", tasks: "Tasks" }, true), ...rows.slice(0, OVERVIEW_LIMIT).map(row => format(row))] : [];
+}
+
+function discoveryOverviewRows(candidates: unknown[], width: number, theme: OverviewTheme): string[] {
+	const recent = candidates.map(record).filter(peer => peer.freshness === "recent");
+	const rows = recent.map(peer => {
+		const catalog = record(peer.catalog);
+		const tasks = Array.isArray(peer.tasks) ? peer.tasks : Array.isArray(catalog.tasks) ? catalog.tasks : undefined;
+		const omitted = Array.isArray(peer.tasks) ? peer.omitted : catalog.omittedTasks;
+		return { name: line(peer.label) || "Unnamed", id: shortId(peer.sessionId), context: workspaceName(peer.workspace), tasks: tasks ? `${tasks.length}${positiveCount(omitted) ? "+" : ""}` : "?" };
+	});
+	return [...overviewTable(rows, width, false, theme),
+		...(recent.length > OVERVIEW_LIMIT ? [theme.fg("muted", `+${recent.length - OVERVIEW_LIMIT} more recorded sessions`)] : []),
+		...(candidates.length > recent.length ? [theme.fg("muted", `${candidates.length - recent.length} without recent metadata`)] : []),
+		theme.fg("dim", "Detail: consult(full ID)")];
+}
+
+function workOverviewRows(search: Record<string, unknown>, width: number, theme: OverviewTheme): string[] {
+	const matches = (Array.isArray(search.matches) ? search.matches : []).map(record);
+	const rows = matches.map(match => {
+		const work = record(match.work);
+		return { name: line(match.label) || line(match.taskId) || "Work item", id: shortId(match.sessionId), context: [line(work.area), line(work.topic)].filter(Boolean).join("/") || "—", tasks: "" };
+	});
+	const coverage = record(search.coverage);
+	const limits = [positiveCount(coverage.omittedMatches) && `${coverage.omittedMatches} matches omitted`, positiveCount(coverage.unexaminedPeers) && `${coverage.unexaminedPeers} peers not scanned`, positiveCount(coverage.unknownContext) && `${coverage.unknownContext} unknown contexts`].filter(Boolean).join(" · ");
+	const source = record(search.source);
+	return [...overviewTable(rows, width, true, theme), ...(matches.length > OVERVIEW_LIMIT ? [theme.fg("muted", `+${matches.length - OVERVIEW_LIMIT} more work matches`)] : []),
+		...(limits ? [theme.fg("warning", limits)] : []), ...(source.status === "unavailable" ? [theme.fg("warning", `Source unavailable: ${line(source.reason) || "unknown"}`)] : []),
+		theme.fg("dim", "No authority · detail: consult(full ID)")];
+}
+
+function overviewSummary(row: string, theme: CardTheme): string {
+	const count = /^(\d+)(.*)$/.exec(row);
+	return count ? theme.fg(count[1] === "0" ? "muted" : "syntaxNumber", count[1]) + theme.fg("muted", count[2]) : theme.fg("muted", row);
+}
+
+const taskIdentity = (data: Record<string, unknown>): boolean => Object.hasOwn(data, "sessionName") || Object.hasOwn(data, "currentAlias") || Object.hasOwn(data, "initialAlias");
+
+function identityBodyRows(rows: string[], tone: CardTone, theme: CardTheme, width: number, expanded: boolean): string[] {
+	// Wrap plain text before coloring: ANSI can otherwise add empty rows at narrow widths.
+	const wrapped = rows.flatMap(row => row.split("\n").flatMap(source => {
+		const field = /^(Current alias|Initial alias|Session name|Routing ID|Requested subject): (.*)$/.exec(source);
+		let offset = 0;
+		return (source === "" ? [""] : wrapTextWithAnsi(source, cardInnerWidth(width))).map(fragment => {
+			if (!field) return source === "Existing alias preserved; subject does not rename it." || source === "Session name preserved; subject updates task aliases." ? theme.fg("muted", fragment) : fragment;
+			const start = source.indexOf(fragment, offset);
+			offset = start + fragment.length;
+			const labelLength = Math.max(0, Math.min(fragment.length, field[1].length + 2 - start));
+			const role = field[1] === "Routing ID" ? "dim" : field[2] === "unknown" ? "muted" : "accent";
+			return theme.fg("muted", fragment.slice(0, labelLength)) + theme.fg(role, fragment.slice(labelLength));
+		});
+	}));
+	return (expanded ? wrapped : wrapped.slice(0, 3)).map(row => cardLine(row, tone, theme, width));
+}
+
+function summary(operation: Operation, args: Record<string, unknown>, result: Result, failed: boolean): string[] {
+	const body = text(result);
+	if (failed) return [line(body) || "Operation failed"];
+	const data = record(record(result.details).gentleAgents);
+	if (operation === "session" && typeof data.alias === "string") {
+		if (taskIdentity(data)) {
+			const name = line(data.sessionName) || line(data.alias) || "unnamed";
+			const rows = [`Current alias: ${line(data.currentAlias) || "unknown"}`, `Session name: ${name}`];
+			if (line(args.subject) && name !== "unnamed" && name !== line(args.subject)) rows.push("Session name preserved; subject updates task aliases.");
+			return rows;
+		}
+		const rows = [`Current alias: ${line(data.alias) || "unnamed"}`];
+		if (line(data.alias) && line(args.subject) && line(args.subject) !== line(data.alias)) rows.push("Existing alias preserved; subject does not rename it.");
+		return rows;
+	}
+	if (operation === "consult") {
+		const receipt = record(data.receipt ?? parsedOutput(result));
+		if (typeof receipt.status === "string") {
+			const code = line(receipt.code) || (Array.isArray(receipt.unknowns) ? line(receipt.unknowns[0]) : "");
+			return [`${line(receipt.status)}${code ? ` (${code})` : ""} · not an owner reply; authority none`];
+		}
+	}
+	if (operation === "list") {
+		const work = record(data.workSearch);
+		if (Array.isArray(work.matches)) return [`${work.matches.length} work matches · non-exhaustive; reachability unknown`];
+		if (Array.isArray(data.candidates)) return [`${data.candidates.length} advertised session${data.candidates.length === 1 ? "" : "s"} · reachability unknown`];
+	}
+	const parsed = parsedOutput(result);
+	return [typeof parsed === "string" ? line(body.split("\n").find(row => row.trim())) || "No output" : readableDataRows(parsed)[0] || "No output"];
+}
+
+export function orchestratorToolRenderers(operation: Operation, hint: (expanded: boolean) => string) {
+	const title = operation === "session" ? "Session identity" : operation === "consult" ? "Consult orchestrator" : "Discover orchestrators";
+	return {
+		renderShell: "self" as const,
+		renderCall(args: Record<string, unknown>, theme: CardTheme, context: Context) {
+			return {
+				render(width: number) {
+					if (width <= 0) return [];
+					const pending = cardAwaitingResult(context);
+					const tone = context.isError || context.state?.orchestratorFailed ? CARD_TONE.ERROR : CARD_TONE.INFO;
+					const subtitle = operation === "session" ? (line(args.subject) ? `Subject: ${line(args.subject)}` : "This session")
+						: operation === "consult" ? line(args.kind) || "metadata"
+						: Object.hasOwn(args, "filter") ? "Classified work" : args.recipient_session_id ? "Selected session" : "Advertised sessions";
+					return floatRows(tone, theme, width, inner => ({
+						head: [cardTop({ title, subtitle, body: [], tone, glyph: "🤖" }, theme, inner, hint(!!context.expanded))],
+						...(pending ? {
+							body: [...(context.expanded ? cardBodyRows(requestRows(args), tone, theme, inner, { expanded: true }) : []), cardRunningLine(tone, theme, inner)],
+							bottom: cardBottom(tone, theme, inner),
+						} : {}),
+					}));
+				},
+				invalidate() {},
+			};
+		},
+		renderResult(result: Result, options: { expanded: boolean; isPartial?: boolean }, theme: CardTheme, context: Context) {
+			const failed = !!record(result.details).error || !!context.isError;
+			if (!options.isPartial) markCardResult(context.state);
+			if (context.state) context.state.orchestratorFailed = failed;
+			const tone = failed ? CARD_TONE.ERROR : CARD_TONE.INFO;
+			const args = context.args ?? {};
+			const data = record(record(result.details).gentleAgents);
+			const discoveryOverview = operation === "list" && !failed && !args.recipient_session_id && Array.isArray(data.candidates);
+			const workOverview = operation === "list" && !failed && Array.isArray(record(data.workSearch).matches);
+			const overview = options.expanded && (discoveryOverview || workOverview);
+			const body = options.isPartial && !failed ? ["Receiving partial result…"] : summary(operation, args, result, failed);
+			if (options.expanded && !overview) {
+				if (operation === "session" && typeof data.alias === "string" && !failed) {
+					if (taskIdentity(data)) body.push(`Initial alias: ${line(data.initialAlias) || "unknown"}`);
+					if (line(data.senderSessionId)) body.push(`Routing ID: ${line(data.senderSessionId)}`);
+					if (line(args.subject) && (!taskIdentity(data) || line(args.subject) !== line(data.currentAlias))) body.push(`Requested subject: ${line(args.subject)}`);
+					body.push(...(args.state === null ? ["Published state: withdrawn"] : section("Published state", readableDataRows(args.state))));
+				} else if (operation === "list" && Array.isArray(data.candidates) && !failed) {
+					body.push(...section("Request", requestRows(args)), ...section("Sessions", discoveredSessionRows(data.candidates)));
+				} else if (operation === "consult" && data.receipt !== undefined && !failed) {
+					body.push(...section("Request", requestRows(args)), ...section("Published context / advice", readableDataRows(data.receipt)));
+				} else if (!Object.keys(data).length && typeof parsedOutput(result) === "string") {
+					body.splice(0, body.length, ...section("Request", requestRows(args)), ...text(result).split("\n"));
+				} else {
+					body.push(...expandedToolRows(args, result));
+				}
+			}
+			return {
+				render(width: number) {
+					if (width <= 0) return [];
+					return floatRows(tone, theme, width, inner => {
+						const columns = cardInnerWidth(inner);
+						const summaries = discoveryOverview || workOverview ? body.map(row => overviewSummary(row, theme)) : body;
+						const rows = overview ? [...summaries, ...(discoveryOverview ? discoveryOverviewRows(data.candidates as unknown[], columns, theme) : workOverviewRows(record(data.workSearch), columns, theme))]
+							.map(row => truncateToWidth(row, columns, "…")) : summaries;
+						return {
+							afterHeading: true,
+							body: operation === "session" && !failed && typeof data.alias === "string"
+								? identityBodyRows(body, tone, theme, inner, options.expanded)
+								: cardBodyRows(rows, tone, theme, inner, { expanded: options.expanded, previewRows: 3 }),
+							bottom: cardBottom(tone, theme, inner),
+						};
+					});
+				},
+				invalidate() {},
+			};
+		},
+	};
+}

package/lib/orchestrator-work-search.ts

@@ -0,0 +1,218 @@
+import { isAbsolute } from "node:path";
+import type { PresenceRecord } from "./agents-session-transport.ts";
+import { discoverOrchestrators, type OrchestratorCandidate } from "./orchestrator-discovery.ts";
+import { decodeWorkDescriptor, type WorkDescriptor, type WorkRef } from "./orchestrator-work.ts";
+import type { RepositoryFact } from "./orchestrator-scope.ts";
+
+export interface WorkFilter {
+	area?: string;
+	topic?: string;
+	tag?: string;
+	text?: string;
+	ref?: WorkRef;
+	repository_root?: string;
+	related_to?: { session_id: string; task_id?: string };
+}
+const safeText = (v: unknown, max: number): v is string => typeof v === "string" && !!v.trim()
+	&& Buffer.byteLength(v) <= max && !/[\p{Cc}\p{Cf}\p{Cs}]/u.test(v);
+const fold = (s: string) => s.normalize("NFC").trim().toLowerCase();
+
+/** Validate before discovery; preserve public spelling and exact reference identity. */
+export function validateWorkFilter(value: unknown): WorkFilter {
+	const invalid = () => { throw new Error("invalid-work-filter"); };
+	if (!value || typeof value !== "object" || Array.isArray(value)) return invalid();
+	const input = value as Record<string, unknown>;
+	if (Object.keys(input).some(k => !["area", "topic", "tag", "text", "ref", "repository_root", "related_to"].includes(k))) return invalid();
+	const result: WorkFilter = {};
+	for (const key of ["area", "topic", "tag", "text", "repository_root"] as const) {
+		if (!Object.hasOwn(input, key)) continue;
+		const v = input[key];
+		if (!safeText(v, key === "text" ? 1024 : key === "repository_root" ? 256 : 64)) return invalid();
+		if (key === "repository_root" && (!isAbsolute(v) || /[\u00a0\u2000-\u200a\u202f\u205f\u3000]/u.test(v))) return invalid();
+		result[key] = v;
+	}
+	if (result.topic && !result.area) return invalid();
+	if (Object.hasOwn(input, "ref")) {
+		try { result.ref = decodeWorkDescriptor({ refs: [input.ref] }).refs![0]; }
+		catch { return invalid(); }
+	}
+	if (Object.hasOwn(input, "related_to")) {
+		const source = input.related_to;
+		if (!source || typeof source !== "object" || Array.isArray(source)) return invalid();
+		const keys = source as Record<string, unknown>;
+		if (Object.keys(keys).some(k => !["session_id", "task_id"].includes(k))
+			|| !Object.hasOwn(keys, "session_id") || !safeText(keys.session_id, 256)
+			|| (Object.hasOwn(keys, "task_id") && !safeText(keys.task_id, 256))) return invalid();
+		result.related_to = { session_id: keys.session_id,
+			...(Object.hasOwn(keys, "task_id") ? { task_id: keys.task_id as string } : {}) };
+	}
+	return result;
+}
+
+interface WorkNode {
+	sessionId: string;
+	taskId?: string;
+	label?: string;
+	aliases?: OrchestratorCandidate["aliases"];
+	workspace?: string | null;
+	status?: string;
+	repository?: RepositoryFact;
+	work: WorkDescriptor;
+	recordedAt: number;
+}
+export interface WorkSearchResult {
+	schema: 1;
+	ownerReply: false;
+	authority: "none";
+	reachability: "unknown";
+	observedAt: number;
+	coverage: {
+		exhaustive: false;
+		examinedPeers: number;
+		unexaminedPeers: number;
+		unknownContext: number;
+		unclassified: number;
+		unmatchedTaskAnnotations: number;
+		catalogUnknown: number;
+		catalogOmittedTasks: number;
+		pendingCatalogPages: number;
+		omittedMatches: number;
+	};
+	source?: {
+		status: "available" | "unavailable";
+		provenance: "published-work";
+		selector: NonNullable<WorkFilter["related_to"]>;
+		reason?: string;
+		node?: WorkNode;
+	};
+	matches: (WorkNode & { reasons: string[] })[];
+}
+
+/** Only current catalog IDs are task identities; annotations never imply liveness. */
+function collectNodes(candidate: OrchestratorCandidate, coverage: WorkSearchResult["coverage"]): WorkNode[] {
+	const record = candidate.workRecord;
+	if (!record) coverage.unknownContext++;
+	if (!candidate.catalog) coverage.catalogUnknown++;
+	else {
+		coverage.catalogOmittedTasks += candidate.catalog.omittedTasks;
+		if (candidate.catalog.cursor) coverage.pendingCatalogPages++;
+	}
+	const nodes: WorkNode[] = [];
+	const { tasks: annotations = {}, ...root } = record?.work ?? {};
+	const classified = (work: WorkDescriptor) => !!(work.area || work.tags?.length || work.refs?.length);
+	const base = { sessionId: candidate.sessionId, recordedAt: record?.recordedAt ?? 0 };
+	if (record && classified(root)) nodes.push({ ...base, label: candidate.aliases?.currentAlias ?? candidate.label, aliases: candidate.aliases, workspace: candidate.workspace,
+		repository: candidate.scope?.host, work: root });
+	else if (record) coverage.unclassified++;
+	const live = candidate.catalog?.tasks ?? [];
+	coverage.unmatchedTaskAnnotations += Object.keys(annotations).filter(id => !live.some(t => t.id === id)).length;
+	for (const task of live) {
+		const work = Object.hasOwn(annotations, task.id) ? annotations[task.id] : undefined;
+		if (!work) {
+			if (record) coverage.unclassified++;
+			continue;
+		}
+		nodes.push({ ...base, taskId: task.id, label: task.label, workspace: task.cwd, status: task.status,
+			repository: candidate.scope?.tasks.find(t => t.id === task.id)?.repository, work });
+	}
+	return nodes;
+}
+
+function matchReasons(node: WorkNode, filter: WorkFilter): string[] | undefined {
+	const reasons: string[] = [];
+	const check = (present: boolean, matches: boolean, reason: string) => {
+		if (!present) return true;
+		if (!matches) return false;
+		reasons.push(reason);
+		return true;
+	};
+	const work = node.work;
+	if (!check(filter.area !== undefined, !!work.area && fold(work.area) === fold(filter.area ?? ""), "area")) return;
+	if (!check(filter.topic !== undefined, !!work.topic && fold(work.topic) === fold(filter.topic ?? ""), "topic")) return;
+	if (!check(filter.tag !== undefined, !!work.tags?.some(t => fold(t) === fold(filter.tag ?? "")), "tag")) return;
+	const text = [node.label, work.area, work.topic, ...(work.tags ?? []),
+		...(work.refs ?? []).flatMap(r => [r.kind, r.repository, r.id])].filter((s): s is string => s !== undefined);
+	if (!check(filter.text !== undefined, text.some(s => fold(s).includes(fold(filter.text ?? ""))), "text")) return;
+	const ref = filter.ref;
+	if (!check(!!ref, !!work.refs?.some(r => r.kind === ref?.kind && r.repository === ref.repository && r.id === ref.id), "ref")) return;
+	if (!check(filter.repository_root !== undefined, node.repository?.root === filter.repository_root, "repository_root")) return;
+	return reasons.length ? reasons : ["classified"];
+}
+
+function relationReasons(node: WorkNode, source: WorkNode): string[] {
+	if (node.sessionId === source.sessionId && node.taskId === source.taskId) return [];
+	const work = node.work;
+	const other = source.work;
+	const reasons: string[] = [];
+	if (work.refs?.some(r => other.refs?.some(s => r.kind === s.kind && r.repository === s.repository && r.id === s.id)))
+		reasons.push("shared-declared-reference");
+	const area = !!work.area && !!other.area && fold(work.area) === fold(other.area);
+	if (area) reasons.push("possible-area-overlap");
+	if (area && work.topic && other.topic && fold(work.topic) === fold(other.topic)) reasons.push("possible-topic-overlap");
+	if (work.tags?.some(t => other.tags?.some(s => fold(t) === fold(s)))) reasons.push("possible-tag-overlap");
+	return reasons;
+}
+
+/** Detached bounded index, not an owner reply, live probe, or exhaustive search. */
+export function searchPublishedWork(profile: string, peers: readonly PresenceRecord[], filter: unknown = {},
+	selection?: { recipientSessionId?: string; cursor?: string }, now = Date.now()): WorkSearchResult {
+	const validated = validateWorkFilter(filter);
+	if (selection !== undefined) {
+		if (!selection || typeof selection !== "object" || Array.isArray(selection)
+			|| Object.keys(selection).some(k => !["recipientSessionId", "cursor"].includes(k))
+			|| (selection.recipientSessionId !== undefined && !safeText(selection.recipientSessionId, 256))
+			|| (selection.cursor !== undefined && (typeof selection.cursor !== "string" || selection.cursor.length > 1024)))
+			throw new Error("invalid-work-selection");
+	}
+	if (selection?.cursor !== undefined && selection.recipientSessionId === undefined) throw new Error("work-cursor-requires-recipient");
+	const ids = [...new Set(peers.map(p => p.sessionId))].sort();
+	const eligible = selection?.recipientSessionId !== undefined ? ids.filter(id => id === selection.recipientSessionId) : ids;
+	const selected = new Set(eligible.slice(0, 64));
+	const sourceId = validated.related_to?.session_id;
+	if (sourceId !== undefined && ids.includes(sourceId) && !selected.has(sourceId)) {
+		if (selected.size === 64) selected.delete(eligible[63]);
+		selected.add(sourceId);
+	}
+	const result: WorkSearchResult = { schema: 1, ownerReply: false, authority: "none", reachability: "unknown", observedAt: now,
+		coverage: { exhaustive: false, examinedPeers: selected.size, unexaminedPeers: ids.length - selected.size,
+			unknownContext: 0, unclassified: 0, unmatchedTaskAnnotations: 0, catalogUnknown: 0,
+			catalogOmittedTasks: 0, pendingCatalogPages: 0, omittedMatches: 0 }, matches: [] };
+	// Retain duplicate activations so discovery can refuse ambiguous joins.
+	const candidatePeers = peers.filter(p => selected.has(p.sessionId));
+	const candidates = discoverOrchestrators(profile, candidatePeers, now, { ...selection, includeWork: true });
+	if (sourceId !== undefined && selected.has(sourceId) && selection?.recipientSessionId !== undefined
+		&& selection.recipientSessionId !== sourceId) {
+		candidates.push(...discoverOrchestrators(profile, candidatePeers.filter(p => p.sessionId === sourceId), now, { includeWork: true }));
+	}
+	candidates.sort((a, b) => a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0);
+	const nodes = candidates.flatMap(c => collectNodes(c, result.coverage));
+	let source: WorkNode | undefined;
+	if (validated.related_to) {
+		const selector = validated.related_to;
+		const candidate = candidates.find(c => c.sessionId === sourceId);
+		source = nodes.find(n => n.sessionId === sourceId && n.taskId === selector.task_id);
+		const reason = !candidate ? "source-not-advertised" : !candidate.workRecord ? "source-context-unavailable"
+			: selector.task_id !== undefined && !candidate.catalog ? "source-catalog-unavailable"
+			: selector.task_id !== undefined && !candidate.catalog?.tasks.some(t => t.id === selector.task_id)
+				? "source-task-not-on-current-page" : "source-unclassified";
+		result.source = { status: source ? "available" : "unavailable", provenance: "published-work", selector,
+			...(source ? { node: source } : { reason }) };
+	}
+	const matches = nodes.filter(n => selection?.recipientSessionId === undefined || n.sessionId === selection.recipientSessionId)
+		.map(node => {
+			const ordinary = matchReasons(node, validated);
+			if (!validated.related_to) return { node, reasons: ordinary };
+			const related = source ? relationReasons(node, source) : [];
+			return { node, reasons: ordinary && related.length ? [...ordinary.filter(r => r !== "classified"), ...related] : undefined };
+		}).filter(m => m.reasons !== undefined);
+	result.coverage.omittedMatches = matches.length;
+	for (const { node, reasons } of matches) {
+		result.matches.push({ ...node, reasons: reasons! });
+		result.coverage.omittedMatches--;
+		if (Buffer.byteLength(JSON.stringify(result)) > 16 * 1024) {
+			result.matches.pop();
+			result.coverage.omittedMatches++;
+		}
+	}
+	return structuredClone(result);
+}

package/lib/orchestrator-work.ts

@@ -0,0 +1,79 @@
+export interface WorkRef {
+	kind: "issue" | "pr" | "task";
+	repository: string;
+	id: string;
+}
+export interface WorkDescriptor {
+	area?: string;
+	topic?: string;
+	tags?: string[];
+	refs?: WorkRef[];
+}
+export interface PublishedWork extends WorkDescriptor {
+	tasks?: Record<string, WorkDescriptor>;
+}
+const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const text = (v: unknown, max: number): v is string => typeof v === "string" && !!v.trim()
+	&& !/[\p{Cc}\p{Cf}\p{Cs}]/u.test(v) && Buffer.byteLength(v) <= max;
+const keys = (v: Record<string, unknown>, allowed: string[]) => Object.keys(v).every(k => allowed.includes(k));
+// Explicit public host/owner/repo spelling only: no URLs, credentials, ports or inferred identity.
+const repository = (v: unknown): v is string => text(v, 256)
+	&& /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,63}\/[a-z0-9_-][a-z0-9_.-]*\/[a-z0-9_-][a-z0-9_.-]*$/i.test(v)
+	&& v.split("/")[0].split(".").every(label => label.length <= 63);
+
+/** Pure, detached validation. References are descriptive identifiers, never routing targets. */
+function descriptor(value: unknown, allowEmpty = false): WorkDescriptor {
+	const invalid = () => { throw new Error("invalid-published-state"); };
+	if (!object(value) || !keys(value, ["area", "topic", "tags", "refs"])) return invalid();
+	const result: WorkDescriptor = {};
+	for (const key of ["area", "topic"] as const) {
+		if (Object.hasOwn(value, key)) {
+			if (!text(value[key], 64)) return invalid();
+			result[key] = value[key];
+		}
+	}
+	if (result.topic && !result.area) return invalid();
+	if (Object.hasOwn(value, "tags")) {
+		if (!Array.isArray(value.tags) || value.tags.length > 8 || !Array.from(value.tags).every(tag => text(tag, 64))
+			|| new Set(value.tags).size !== value.tags.length) return invalid();
+		result.tags = [...value.tags];
+	}
+	if (Object.hasOwn(value, "refs")) {
+		if (!Array.isArray(value.refs) || value.refs.length > 8) return invalid();
+		result.refs = [];
+		const seen = new Set<string>();
+		for (const ref of value.refs) {
+			if (!object(ref) || Object.keys(ref).length !== 3 || !keys(ref, ["kind", "repository", "id"])
+				|| !["issue", "pr", "task"].includes(ref.kind as string) || !repository(ref.repository)
+				|| !text(ref.id, 256) || (ref.kind !== "task" && !/^[1-9][0-9]*$/.test(ref.id))) return invalid();
+			const key = JSON.stringify([ref.kind, ref.repository, ref.id]);
+			if (seen.has(key)) return invalid();
+			seen.add(key);
+			result.refs.push({ kind: ref.kind as WorkRef["kind"], repository: ref.repository, id: ref.id });
+		}
+	}
+	if (!allowEmpty && !result.area && !result.tags?.length && !result.refs?.length) return invalid();
+	return result;
+}
+
+export function decodeWorkDescriptor(value: unknown): WorkDescriptor {
+	return descriptor(value);
+}
+
+/** Only the curated root accepts exact owner-declared task IDs. */
+export function decodeWork(value: unknown): PublishedWork {
+	if (!object(value) || !keys(value, ["area", "topic", "tags", "refs", "tasks"])) throw new Error("invalid-published-state");
+	const { tasks, ...fields } = value;
+	const result: PublishedWork = descriptor(fields, true);
+	if (Object.hasOwn(value, "tasks")) {
+		if (!object(tasks) || Object.keys(tasks).length > 8) throw new Error("invalid-published-state");
+		result.tasks = {};
+		for (const id of Object.keys(tasks)) {
+			if (!text(id, 256) || ["__proto__", "prototype", "constructor"].includes(id)) throw new Error("invalid-published-state");
+			result.tasks[id] = decodeWorkDescriptor(tasks[id]);
+		}
+	}
+	if (!result.area && !result.tags?.length && !result.refs?.length && !Object.keys(result.tasks ?? {}).length)
+		throw new Error("invalid-published-state");
+	return result;
+}

package/lib/permission-mode-policy.ts

@@ -0,0 +1,59 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { gentlePiConfigHome } from "./agent-home.ts";
+
+export type PermissionMode = "normal" | "auto" | "yolo";
+export const PERMISSION_MODE_SCHEMA = "gentle-pi.permission-mode/v1";
+export interface PermissionModeOptions { gentlePiConfigHome?: string }
+export interface PermissionModeResolution {
+	mode: PermissionMode;
+	malformed: boolean;
+	source: "global_file" | "default";
+	globalFile: string;
+}
+export function isPermissionMode(value: unknown): value is PermissionMode {
+	return value === "normal" || value === "auto" || value === "yolo";
+}
+/** Never consult merged Pi settings or repository configuration. */
+export function permissionModePolicyFile(options: PermissionModeOptions = {}): string {
+	return join(options.gentlePiConfigHome ?? gentlePiConfigHome(), "permission-mode.json");
+}
+export const permissionModePolicyPath = permissionModePolicyFile;
+export function parsePermissionModePolicyFile(raw: string): PermissionMode | undefined {
+	try {
+		const value: unknown = JSON.parse(raw);
+		if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).length !== 2) return undefined;
+		if (!("schema" in value) || value.schema !== PERMISSION_MODE_SCHEMA || !("mode" in value)) return undefined;
+		return isPermissionMode(value.mode) ? value.mode : undefined;
+	} catch { return undefined; }
+}
+export function resolvePermissionModePolicy(options: PermissionModeOptions = {}): PermissionModeResolution {
+	const globalFile = permissionModePolicyFile(options);
+	try {
+		const mode = parsePermissionModePolicyFile(readFileSync(globalFile, "utf8"));
+		return { mode: mode ?? "normal", malformed: mode === undefined, source: "global_file", globalFile };
+	} catch (error) {
+		const missing = typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+		return { mode: "normal", malformed: !missing, source: missing ? "default" : "global_file", globalFile };
+	}
+}
+/** Private same-directory atomic replacement; malformed/unreadable preferences require human repair. */
+export function writePermissionModePolicy(mode: PermissionMode, options: PermissionModeOptions = {}): string {
+	if (!isPermissionMode(mode)) throw new Error("Invalid permission mode");
+	const resolution = resolvePermissionModePolicy(options);
+	if (resolution.malformed) throw new Error("Permission mode preference is malformed or unreadable; repair it before saving.");
+	const home = options.gentlePiConfigHome ?? gentlePiConfigHome();
+	const path = resolution.globalFile;
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	mkdirSync(home, { recursive: true });
+	try {
+		writeFileSync(temporary, `${JSON.stringify({ schema: PERMISSION_MODE_SCHEMA, mode })}\n`, { flag: "wx", mode: 0o600 });
+		// Recheck immediately before replacing: never silently repair an invalid file.
+		if (resolvePermissionModePolicy(options).malformed) throw new Error("Permission mode preference changed or is unreadable.");
+		renameSync(temporary, path);
+	} finally {
+		try { unlinkSync(temporary); } catch { /* Rename already consumed it. */ }
+	}
+	return path;
+}