gentle-pi 3.7.0 → 4.1.0

package/lib/odd-phase-inference.ts

@@ -0,0 +1,231 @@
+// Deterministic ODD phase inference from observed tool activity. The Gentle
+// Shell working label used to depend only on the model calling
+// gentle_odd_phase, which models routinely skip; the tools the primary
+// session actually runs are a reliable, observable signal instead.
+//
+// The mapping is deliberately conservative: an unknown tool, unknown subagent
+// role, or an ambiguous shell command returns undefined so the caller leaves
+// the current label unchanged. This module is pure (no Pi or registry
+// imports); precedence against explicit reports lives in OddPhaseRegistry.
+
+import type { OddPhase } from "./odd-phase.ts";
+
+const TOOL_PHASES: Readonly<Record<string, OddPhase>> = {
+	read: "exploring",
+	grep: "exploring",
+	find: "exploring",
+	ls: "exploring",
+	codegraph: "exploring",
+	ask_user_choice: "deciding",
+	ask_user_question: "deciding",
+	todo: "planning",
+	gentle_review: "checking",
+	gentle_review_scope: "checking",
+	gentle_review_capture: "checking",
+	gentle_review_capture_group: "checking",
+};
+
+const DELEGATED_PHASES: Readonly<Record<string, OddPhase>> = {
+	"gentle-ai-worker": "implementing",
+	"gentle-ai-verify": "checking",
+	"gentle-ai-explore": "exploring",
+};
+
+const WRITE_TOOLS = new Set(["edit", "write"]);
+const SHELL_TOOLS = new Set(["bash", "powershell"]);
+
+// Test, typecheck, lint, and build runners. Matched per shell segment.
+const CHECKING_COMMANDS: readonly RegExp[] = [
+	/^(pnpm|npm|yarn|bun)\s+(run\s+)?(test|typecheck|lint|build|check)\b/,
+	/^node\b.*\s--test\b/,
+	/^node\s+\S*(test|check|lint|typecheck)[\w-]*\.m?[jt]s\b/,
+	/^((npx|pnpx|bunx)\s+|(pnpm|yarn)\s+exec\s+)?(vitest|jest|mocha|tsc|eslint|pytest)\b/,
+	/^python3?\s+-m\s+pytest\b/,
+	/^go\s+(test|build|vet)\b/,
+	/^cargo\s+(test|build|check|clippy)\b/,
+	/^make\b/,
+	// Waiting on or reading CI results verifies work; it is not exploration.
+	/^gh\s+pr\s+checks\b/,
+	/^gh\s+run\s+(view|watch|list)\b/,
+];
+
+// Git listing flags that may take one non-flag argument (`--contains <rev>`)
+// without turning `git branch`/`git tag` into a create.
+const GIT_LIST_FLAG = String.raw`(\s+(-a|-r|-l|-v|-vv|-n\d*|--all|--remotes|--list|--show-current|--contains|--merged|--no-merged|--points-at|--sort=\S+)(\s+[^-\s]\S*)?)*$`;
+
+// Read-only inspection. Matched per shell segment.
+const EXPLORING_COMMANDS: readonly RegExp[] = [
+	/^git\s+(status|log|diff|show|blame|rev-parse|rev-list|merge-base|ls-files|ls-remote|ls-tree|cat-file|describe|shortlog|reflog|grep|check-ignore|for-each-ref|name-rev|count-objects)\b/,
+	new RegExp(String.raw`^git\s+(branch|tag)${GIT_LIST_FLAG}`),
+	/^git\s+remote(\s+(-v|--verbose|show|get-url)\b.*)?$/,
+	/^git\s+(worktree|stash)\s+list\b/,
+	/^git\s+config\s+(--get|--get-all|--get-regexp|-l|--list)\b/,
+	/^gh\s+(pr|issue|repo|release)\s+(view|list|diff|status)\b/,
+	/^(ls|cat|head|tail|grep|egrep|rg|wc|pwd|tree|stat|file|which|type|readlink|realpath|dirname|basename|cut|uniq|tr|nl|column|strings|diff|cmp|od|xxd|hexdump|shasum|sha256sum|md5|md5sum|du|df|date|uname|whoami|ps|pgrep|lsof|jq|awk)\b/,
+	/^command\s+-v\b/,
+	/^(\[\[?|test)\s/,
+	/^sort\b(?!.*\s(-o|--output)\b)/,
+	/^sed\b(?!.*\s(-[a-zA-Z]*i|--in-place)\b)/,
+	/^find\b(?!.*\s-(delete|exec|execdir|ok|okdir|fprint\w*)\b)/,
+];
+
+// Segments that neither inspect nor change anything worth labeling: shell
+// control words, no-op builtins, and bare variable assignments (their
+// command substitutions are classified as commands of their own).
+const NEUTRAL_COMMANDS: readonly RegExp[] = [
+	/^(cd|pushd|popd|echo|printf|sleep|true|false|export|set)\b/,
+	/^(done|fi|esac|\}|\))$/,
+	/^for\s+\w+(\s+in\b.*)?$/,
+	// Each assignment must end at whitespace or the end: an optional separator
+	// would let `a=a=a=…` split anywhere and backtrack exponentially.
+	/^([A-Za-z_][A-Za-z0-9_]*=("[^"]*"|'[^']*'|[^\s"'])*(\s+|$))+$/,
+];
+
+// Shell keywords that prefix the command they introduce (`do grep x`).
+const LEADING_KEYWORDS = /^(do|then|else|elif|if|while|until|time|!|\{|\()\s+/;
+
+/**
+ * Infers the ODD phase implied by a tool call, or undefined when the call
+ * carries no reliable phase signal and the label must stay as it is.
+ */
+export function inferOddPhase(toolName: string, args: unknown): OddPhase | undefined {
+	const name = normalizeToolName(toolName);
+	if (name === "subagent_run") {
+		const agent = stringArg(args, "agent");
+		return agent && Object.hasOwn(DELEGATED_PHASES, agent) ? DELEGATED_PHASES[agent] : undefined;
+	}
+	if (WRITE_TOOLS.has(name)) return isOddTaskPath(stringArg(args, "path") ?? stringArg(args, "file_path")) ? "planning" : "implementing";
+	if (SHELL_TOOLS.has(name)) return inferShellPhase(stringArg(args, "command"));
+	return Object.hasOwn(TOOL_PHASES, name) ? TOOL_PHASES[name] : undefined;
+}
+
+// Some runtimes expose tools through an MCP proxy as `mcp__<server>__<tool>`.
+function normalizeToolName(toolName: string): string {
+	return toolName.replace(/^mcp__.+?__/, "");
+}
+
+function stringArg(args: unknown, key: string): string | undefined {
+	if (typeof args !== "object" || args === null) return undefined;
+	const value = (args as Record<string, unknown>)[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+function isOddTaskPath(path: string | undefined): boolean {
+	return path !== undefined && /(^|\/)odd\/tasks\//.test(path.replaceAll("\\", "/"));
+}
+
+/**
+ * A command checks when any segment runs a checker; it explores only when
+ * every segment is read-only inspection (or neutral like `cd`). Anything
+ * else — a mutation, an install, an unknown program — is ambiguous.
+ */
+function inferShellPhase(command: string | undefined): OddPhase | undefined {
+	if (command === undefined) return undefined;
+	const segments = splitShellCommands(command)
+		.map(stripSegment)
+		.filter((segment) => segment.length > 0 && !isNeutral(segment));
+	if (segments.length === 0) return undefined;
+	if (segments.some((segment) => matchesAny(CHECKING_COMMANDS, segment))) return "checking";
+	return segments.every(isReadOnlyInspection) ? "exploring" : undefined;
+}
+
+/**
+ * Splits a shell command into simple commands. Top-level `&&`, `||`, `;`,
+ * `|`, `&`, and newlines separate them; quoted text never does; and every
+ * `$(...)` substitution contributes its own commands, leaving a `$_`
+ * placeholder behind. Not a full shell parser: whatever it cannot follow
+ * lands in a segment that matches no pattern, so the label stays unchanged.
+ */
+function splitShellCommands(command: string): string[] {
+	const commands: string[] = [];
+	let current = "";
+	let quote: "'" | '"' | undefined;
+	for (let i = 0; i < command.length; i++) {
+		const char = command[i];
+		if (quote === "'") {
+			current += char;
+			if (char === "'") quote = undefined;
+		} else if (char === "\\") {
+			current += char + (command[i + 1] ?? "");
+			i++;
+		} else if (char === "$" && command[i + 1] === "(") {
+			const end = findSubstitutionEnd(command, i + 2);
+			if (end < 0) return [...commands, current + command.slice(i)];
+			commands.push(...splitShellCommands(command.slice(i + 2, end)));
+			current += "$_";
+			i = end;
+		} else if (quote === '"') {
+			current += char;
+			if (char === '"') quote = undefined;
+		} else if (char === "'" || char === '"') {
+			quote = char;
+			current += char;
+		} else if (isSeparator(command, i)) {
+			commands.push(current);
+			current = "";
+			if ((char === "|" || char === "&") && command[i + 1] === char) i++;
+		} else {
+			current += char;
+		}
+	}
+	commands.push(current);
+	return commands;
+}
+
+// `&` inside a redirection (`2>&1`, `&>/dev/null`) is not a separator.
+function isSeparator(command: string, i: number): boolean {
+	const char = command[i];
+	if (char === "&") return command[i - 1] !== ">" && command[i + 1] !== ">";
+	return char === ";" || char === "|" || char === "\n";
+}
+
+// Index of the `)` closing a `$(` whose body starts at `start`, or -1.
+function findSubstitutionEnd(command: string, start: number): number {
+	let depth = 1;
+	let quote: "'" | '"' | undefined;
+	for (let i = start; i < command.length; i++) {
+		const char = command[i];
+		if (quote) {
+			if (char === quote) quote = undefined;
+			else if (char === "\\" && quote === '"') i++;
+		} else if (char === "\\") i++;
+		else if (char === "'" || char === '"') quote = char;
+		else if (char === "(") depth++;
+		else if (char === ")" && --depth === 0) return i;
+	}
+	return -1;
+}
+
+// Drops harmless redirections (`2>&1`, `2>/dev/null`), leading shell
+// keywords (`do grep x`), environment assignments (`CI=1 pnpm test`), git
+// global options (`git -C dir status`), and whitespace. A bare assignment
+// is left intact for NEUTRAL_COMMANDS.
+function stripSegment(segment: string): string {
+	let stripped = segment.replace(HARMLESS_REDIRECTS, "").trim();
+	while (LEADING_KEYWORDS.test(stripped)) stripped = stripped.replace(LEADING_KEYWORDS, "");
+	return stripped
+		.replace(/^([A-Za-z_][A-Za-z0-9_]*=("[^"]*"|'[^']*'|[^\s"'])*\s+)+(?=\S)/, "")
+		.replace(/^git\s+((-C|-c)\s+\S+\s+|--no-pager\s+)+/, "git ");
+}
+
+// A segment that writes a file (`echo x > out`) is never a no-op.
+function isNeutral(segment: string): boolean {
+	return !writesFile(segment) && matchesAny(NEUTRAL_COMMANDS, segment);
+}
+
+function isReadOnlyInspection(segment: string): boolean {
+	return !writesFile(segment) && matchesAny(EXPLORING_COMMANDS, segment);
+}
+
+// Stream merges and discarded output; neither writes a file.
+const HARMLESS_REDIRECTS = /\s*(\d?>&\d|&?\d?>\s*\/dev\/null)/g;
+
+// Output redirection to a file is a write. Deliberately naive: a `>` inside
+// quoted text also counts, which only ever leaves the label unchanged.
+function writesFile(segment: string): boolean {
+	return segment.replace(HARMLESS_REDIRECTS, "").includes(">");
+}
+
+function matchesAny(patterns: readonly RegExp[], segment: string): boolean {
+	return patterns.some((pattern) => pattern.test(segment));
+}

package/lib/odd-phase.ts

@@ -0,0 +1,141 @@
+// Bounded ODD phase signal for the Gentle prompt's working label. There is
+// no Pi runtime event for ODD phases, so the label comes from two sources:
+// phases inferred deterministically from the primary session's tool activity
+// (lib/odd-phase-inference.ts, wired in extensions/gentle-shell.ts) and
+// explicit reports by the orchestrator through gentle_odd_phase, which
+// refine it with phases tools cannot show (see
+// assets/orchestrator-tracking.md). Never inferred from assistant prose;
+// the prompt falls back to the generic "working…" label when nothing applies.
+
+// Covers the ODD protocol steps in AGENTS.md (1 authorize .. 7 close); not a
+// strict one-to-one mapping. "researching"/"deciding" both cover step 3
+// (resolve uncertainty), and "deciding" also covers step 4's classify
+// decision (no dedicated label: classifying is typically an instantaneous
+// internal decision, not standalone visible work). "checking"/"closing"
+// both cover step 7 (close).
+export const ODD_PHASES = [
+	"authorizing",
+	"exploring",
+	"researching",
+	"deciding",
+	"planning",
+	"implementing",
+	"checking",
+	"closing",
+] as const;
+
+export type OddPhase = (typeof ODD_PHASES)[number];
+
+export function isOddPhase(value: unknown): value is OddPhase {
+	return typeof value === "string" && (ODD_PHASES as readonly string[]).includes(value);
+}
+
+export function oddPhaseLabel(phase: OddPhase): string {
+	return `${phase}…`;
+}
+
+/** Who set a session's phase: the orchestrator through gentle_odd_phase, or tool-activity inference. */
+export type OddPhaseSource = "explicit" | "inferred";
+
+interface ReportedOddPhase {
+	phase: OddPhase;
+	source: OddPhaseSource;
+}
+
+/**
+ * Session-scoped, best-effort ODD phase signal. Keyed by Pi session id so a
+ * background/child agent — which runs as its own OS process with its own
+ * module state (see lib/agents-runner.ts) — can never see or override the
+ * primary session's reported phase. The owning extension clears a session's
+ * entry at turn and session boundaries (agent_start, agent_settled,
+ * session_shutdown) so a stale phase from a finished turn never leaks into
+ * the next one.
+ */
+export class OddPhaseRegistry {
+	private readonly phases = new Map<string, ReportedOddPhase>();
+	// The WORKING-state pulse loop does not run at all under the "potato"
+	// animation policy (see GentlePromptEditor.startPulse), and workingLabel
+	// is otherwise only read on the next incidental render. Pi's own docs
+	// (docs/tui.md) instruct components to call requestRender() themselves
+	// after a state change; no host re-render is implicitly guaranteed. The
+	// owning prompt registers its own redraw callback here so a phase change
+	// is visible immediately regardless of animation policy.
+	private readonly renderRequests = new Map<string, () => void>();
+
+	/**
+	 * Sets the current ODD phase for a session. Only accepts an
+	 * already-validated OddPhase; callers must validate untrusted input
+	 * with isOddPhase() (or use clear() for the explicit "clear" token)
+	 * before calling this. Returns undefined, without mutating any state or
+	 * requesting a redraw, when there is no session id to scope the report
+	 * to. The source defaults to "explicit"; tool-activity inference goes
+	 * through infer() so its precedence rule applies.
+	 */
+	report(sessionId: string | undefined, phase: OddPhase, source: OddPhaseSource = "explicit"): OddPhase | undefined {
+		if (!sessionId) return undefined;
+		this.phases.set(sessionId, { phase, source });
+		this.renderRequests.get(sessionId)?.();
+		return phase;
+	}
+
+	/**
+	 * Applies a phase inferred from tool activity and returns the session's
+	 * resulting phase. An explicit report is not overridden by an inferred
+	 * "exploring" (read-only tools are routine while researching or
+	 * deciding). Incidental reads and planning bookkeeping also cannot
+	 * displace active implementation/checking. A known delegated exploration
+	 * is a deliberate transition, not an incidental read; later edits and
+	 * checks can still move between active work phases. Inferring the phase
+	 * already shown changes nothing,
+	 * keeps an explicit source explicit, and never requests a redraw, so
+	 * repeated tool calls do not repaint the prompt.
+	 */
+	infer(sessionId: string | undefined, phase: OddPhase, cause: "tool" | "delegation" = "tool"): OddPhase | undefined {
+		if (!sessionId) return undefined;
+		const current = this.phases.get(sessionId);
+		if (current?.phase === phase) return phase;
+		if (phase === "exploring" && cause !== "delegation" &&
+			(current?.source === "explicit" || current?.phase === "implementing" || current?.phase === "checking")) return current?.phase;
+		if (phase === "planning" && (current?.phase === "implementing" || current?.phase === "checking")) return current.phase;
+		return this.report(sessionId, phase, "inferred");
+	}
+
+	/**
+	 * Clears a session's reported phase (turn/session boundary, or the
+	 * explicit "clear" token). An invalid/unrecognized phase report is
+	 * never a reason to clear: only this method resets the session, so a
+	 * malformed report leaves the previously reported phase in place.
+	 * Clearing also drops the report's source.
+	 */
+	clear(sessionId: string | undefined): void {
+		if (!sessionId) return;
+		if (this.phases.delete(sessionId)) this.renderRequests.get(sessionId)?.();
+	}
+
+	get(sessionId: string | undefined): OddPhase | undefined {
+		return sessionId ? this.phases.get(sessionId)?.phase : undefined;
+	}
+
+	/** Working label for the reported phase, or undefined to fall back to the generic "working…" label. */
+	label(sessionId: string | undefined): string | undefined {
+		const phase = this.get(sessionId);
+		return phase ? oddPhaseLabel(phase) : undefined;
+	}
+
+	/** Registers (replacing any previous registration) the callback used to request an immediate redraw when this session's phase changes. */
+	setRenderRequest(sessionId: string | undefined, requestRender: () => void): void {
+		if (sessionId) this.renderRequests.set(sessionId, requestRender);
+	}
+
+	clearRenderRequest(sessionId: string | undefined): void {
+		if (sessionId) this.renderRequests.delete(sessionId);
+	}
+}
+
+// Pi loads extensions with separate jiti moduleCache:false loaders, so a
+// module-local singleton is duplicated. The global symbol bridges only those
+// loaders inside this process; subagents run in separate OS processes. Keep
+// the session key inside the registry and clear it at turn/session boundaries.
+const ODD_PHASE_REGISTRY = Symbol.for("gentle-pi.odd-phase-registry");
+const processState = globalThis as typeof globalThis & { [ODD_PHASE_REGISTRY]?: OddPhaseRegistry };
+export const oddPhaseRegistry = processState[ODD_PHASE_REGISTRY] ??= new OddPhaseRegistry();

package/lib/orchestrator-alias.ts

@@ -0,0 +1,20 @@
+import { stripVTControlCharacters } from "node:util";
+
+export interface TaskAliases { initialAlias: string | null; currentAlias: string | null }
+/** Explicit public topic only; never infer from names or private conversation. */
+export function normalizeTaskSubject(value: unknown): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string" || /\p{Cs}/u.test(value)) throw new Error("invalid-task-subject");
+	const clean = stripVTControlCharacters(value).replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim();
+	return Array.from(clean).slice(0, 120).join("").trimEnd() || undefined;
+}
+export function decodeTaskAliases(value: unknown): TaskAliases | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const input = value as Record<string, unknown>;
+	const valid = (v: unknown): v is string => typeof v === "string" && !!v && !/[\p{Cc}\p{Cf}\p{Cs}]/u.test(v)
+		&& Array.from(v).length <= 120 && normalizeTaskSubject(v) === v;
+	if (Object.keys(input).length !== 2 || !Object.hasOwn(input, "initialAlias") || !Object.hasOwn(input, "currentAlias")
+		|| !(input.initialAlias === null || valid(input.initialAlias))
+		|| !(valid(input.currentAlias) || (input.currentAlias === null && input.initialAlias === null))) return undefined;
+	return { initialAlias: input.initialAlias as string | null, currentAlias: input.currentAlias as string | null };
+}

package/lib/orchestrator-catalog.ts

@@ -0,0 +1,79 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+import { boundedRead, rootFor, sanitizeDisplayLabel, type Header } from "./orchestrator-presence.ts";
+
+// Private bounded derivative, never an identity/authority registry. Each request
+// reads at most one 64 KiB snapshot and returns eight entries of each category.
+export const CATALOG_BYTES = 64 * 1024;
+export const CATALOG_ENTRIES = 64;
+export const CATALOG_PAGES = 8;
+type Task = { id: string; label: string; status: string; cwd: string | null };
+type Catalog = { tasks: Task[]; registered: (string | null)[]; omittedTasks: number; omittedRegistered: number };
+export type CatalogPage = Catalog & { cursor?: string };
+const hash = (bytes: string | Buffer) => createHash("sha256").update(bytes).digest("hex");
+const safePath = (path: string) => isAbsolute(path) && Buffer.byteLength(path) <= 256
+	&& !/[\p{Cc}\p{Cf}\u00a0\u2000-\u200a\u202f\u205f\u3000]/u.test(path);
+const pathFact = (path: string) => safePath(path) ? path : null;
+const exact = (value: any, keys: string[]) => value && typeof value === "object" && !Array.isArray(value)
+	&& Object.keys(value).length === keys.length && keys.every(k => Object.hasOwn(value, k));
+const count = (n: unknown) => Number.isSafeInteger(n) && (n as number) >= 0;
+const text = (s: unknown) => typeof s === "string" && s === sanitizeDisplayLabel(s);
+const path = (s: unknown) => s === null || typeof s === "string" && safePath(s);
+function valid(c: any): c is Catalog {
+	return exact(c, ["tasks", "registered", "omittedTasks", "omittedRegistered"])
+		&& count(c.omittedTasks) && count(c.omittedRegistered)
+		&& Array.isArray(c.tasks) && c.tasks.length <= CATALOG_ENTRIES
+		&& c.tasks.every((t: any) => exact(t, ["id", "label", "status", "cwd"])
+			&& text(t.id) && text(t.label) && ["running", "queued", "waiting"].includes(t.status) && path(t.cwd))
+		&& Array.isArray(c.registered) && c.registered.length <= CATALOG_ENTRIES && c.registered.every(path);
+}
+/** Explicit whitelist; eagerly detached, no task spreads or thread access. */
+export function projectCatalog(tasks: readonly { id: string; label: string; status: string; cwd: string }[], roots: readonly string[]): Catalog {
+	const c: Catalog = { tasks: [], registered: [], omittedTasks: tasks.length, omittedRegistered: roots.length };
+	// Reserve envelope space; byte overflow is an exact omission, not truncation.
+	for (let i = 0; i < Math.min(CATALOG_ENTRIES, Math.max(tasks.length, roots.length)); i++) {
+		if (i < tasks.length) {
+			const t = tasks[i];
+			c.tasks.push({ id: sanitizeDisplayLabel(t.id), label: sanitizeDisplayLabel(t.label), status: t.status, cwd: pathFact(t.cwd) });
+			if (Buffer.byteLength(JSON.stringify(c)) > CATALOG_BYTES - 1024) c.tasks.pop();
+			else c.omittedTasks--;
+		}
+		if (i < roots.length) {
+			c.registered.push(pathFact(roots[i]));
+			if (Buffer.byteLength(JSON.stringify(c)) > CATALOG_BYTES - 1024) c.registered.pop();
+			else c.omittedRegistered--;
+		}
+	}
+	if (!valid(c)) throw new Error("malformed-catalog");
+	return c;
+}
+/** Cursor binds only public catalog fields and producer activation, not private
+ * activity churn. Current envelope/header generation must still agree on every
+ * read; no cached pages, paths or authority are carried by the cursor. */
+export function readCatalog(profile: string, h: Header, activation: string, cursor?: string): { page?: CatalogPage; unavailable?: string } {
+	try {
+		const bytes = boundedRead(join(rootFor(profile, false, true), `${h.sessionHash}.${h.incarnation}.json`), CATALOG_BYTES);
+		const value = JSON.parse(bytes.toString("utf8"));
+		if (!exact(value, ["schema", "sessionHash", "incarnation", "generation", "activation", "tokens", "catalog"])
+			|| value.schema !== 1 || value.sessionHash !== h.sessionHash || value.incarnation !== h.incarnation
+			|| value.generation !== h.generation || value.activation !== activation || !valid(value.catalog)
+			|| !Array.isArray(value.tokens) || value.tokens.length !== 7 || !value.tokens.every((s: unknown) => typeof s === "string" && /^[a-f0-9-]{36}$/.test(s))) throw new Error("unavailable");
+		const c: Catalog = value.catalog;
+		const publicBytes = JSON.stringify({ tasks: c.tasks.map(t => ({ id: t.id, label: t.label, status: t.status, cwd: t.cwd })),
+			registered: c.registered, omittedTasks: c.omittedTasks, omittedRegistered: c.omittedRegistered });
+		const binding = [h.sessionHash, h.incarnation, activation, hash(publicBytes)];
+		let offset = 0;
+		const token = (n: number) => Buffer.from(JSON.stringify([...binding, n, value.tokens[n / 8 - 1]])).toString("base64url");
+		if (cursor !== undefined) {
+			if (typeof cursor !== "string" || cursor.length > 1024) throw new Error("invalid-cursor");
+			const decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+			offset = decoded?.[4];
+			if (!count(offset) || offset < 8 || offset >= CATALOG_ENTRIES || offset % 8 || token(offset) !== cursor) throw new Error("invalid-cursor");
+		}
+		if (cursor && offset >= Math.max(c.tasks.length, c.registered.length)) throw new Error("invalid-cursor");
+		const end = offset + 8;
+		return { page: { tasks: c.tasks.slice(offset, end), registered: c.registered.slice(offset, end),
+			omittedTasks: c.omittedTasks, omittedRegistered: c.omittedRegistered,
+			...(end < Math.max(c.tasks.length, c.registered.length) ? { cursor: token(end) } : {}) } };
+	} catch { return { unavailable: "catalog-unknown-or-invalid-cursor" }; }
+}

package/lib/orchestrator-consultation.ts

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import type { PresenceRecord } from "./agents-session-transport.ts";
+import { discoverOrchestrators } from "./orchestrator-discovery.ts";
+
+export const CONSULTATION_BYTES = 16 * 1024;
+export interface MetadataSelection { recipientSessionId: string; cursor?: string }
+type Candidate = ReturnType<typeof discoverOrchestrators>[number];
+export interface MetadataReceipt {
+	schema: "gentle-agents.consultation/v1";
+	kind: "metadata"; status: "available" | "unavailable";
+	source: "published_snapshot"; ownerReply: false; authority: "none";
+	targetSessionId: string; observedAt: number;
+	freshness: "unknown" | "recent" | "stale";
+	presenceObservedAt?: number;
+	digest?: string;
+	snapshot?: { label: string | null; aliases?: Candidate["aliases"]; workspace: string | null; tasks: Candidate["tasks"];
+		omittedTasks: number; scope: Candidate["scope"] | null; catalog: Candidate["catalog"] | null;
+		state: Candidate["state"] | null };
+	unknowns: string[]; omissions: string[];
+}
+function freeze<T>(value: T): T {
+	if (value && typeof value === "object") {
+		for (const child of Object.values(value)) freeze(child);
+		Object.freeze(value);
+	}
+	return value;
+}
+export function unavailableMetadata(targetSessionId: string, reason: string, now = Date.now(), freshness: MetadataReceipt["freshness"] = "unknown"): MetadataReceipt {
+	return freeze({ schema: "gentle-agents.consultation/v1", kind: "metadata", status: "unavailable",
+		source: "published_snapshot", ownerReply: false, authority: "none", targetSessionId, observedAt: now,
+		freshness, unknowns: [reason], omissions: ["private-context", "owner-decision", "reachability", "exclusive-writer-ownership"] });
+}
+/** Reads the existing bounded, selected-activation projection, never activity.
+ * Identity excludes private activity generation/digests and observation clocks.
+ * Existing readers validate exact field whitelists before this detached capture. */
+export function consultPublishedMetadata(profile: string, peers: readonly PresenceRecord[], selection: MetadataSelection, now = Date.now()): MetadataReceipt {
+	const peer = discoverOrchestrators(profile, peers, now, { recipientSessionId: selection.recipientSessionId,
+		cursor: selection.cursor, consultation: true })[0];
+	if (!peer?.publication || peer.freshness !== "recent") return unavailableMetadata(selection.recipientSessionId, "publication-unknown-or-stale", now, peer?.freshness);
+	if (selection.cursor !== undefined && !peer.catalog) return unavailableMetadata(selection.recipientSessionId, "catalog-unknown-or-invalid-cursor", now);
+	const snapshot = {
+		label: peer.label || null, ...(peer.aliases ? { aliases: peer.aliases } : {}), workspace: peer.workspace || null,
+		tasks: peer.tasks?.map(t => ({ id: t.id, label: t.label, status: t.status, workspace: t.workspace })) ?? [],
+		omittedTasks: peer.omitted ?? 0, scope: peer.scope ?? null, catalog: peer.catalog ?? null, state: peer.state ?? null,
+	};
+	const unknowns = ["reachability", "exclusive-writer-ownership", "owner-decision"];
+	if (!snapshot.workspace) unknowns.push("workspace");
+	if (!snapshot.scope) unknowns.push("repository-scope");
+	if (!snapshot.catalog) unknowns.push("catalog");
+	if (!snapshot.state) unknowns.push("curated-state");
+	const digest = createHash("sha256").update(JSON.stringify([selection.recipientSessionId,
+		peer.publication.incarnation, peer.publication.activation, snapshot])).digest("hex");
+	const receipt: MetadataReceipt = { schema: "gentle-agents.consultation/v1", kind: "metadata", status: "available",
+		source: "published_snapshot", ownerReply: false, authority: "none", targetSessionId: selection.recipientSessionId,
+		observedAt: now, freshness: peer.freshness, presenceObservedAt: peer.publication.heartbeat, digest, snapshot,
+		unknowns, omissions: ["private-context", "git-facts-beyond-published-prefix"] };
+	// JSON capture detaches every nested list/record and guarantees plain JSON.
+	const bytes = JSON.stringify(receipt);
+	if (Buffer.byteLength(bytes) > CONSULTATION_BYTES) return unavailableMetadata(selection.recipientSessionId, "snapshot-too-large", now);
+	return freeze(JSON.parse(bytes) as MetadataReceipt);
+}

package/lib/orchestrator-discovery.ts

@@ -0,0 +1,49 @@
+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";
+
+export interface OrchestratorCandidate {
+	sessionId: string;
+	reachability: "unknown";
+	freshness: "unknown" | "recent" | "stale";
+	label?: string;
+	aliases?: DiscoveryMetadata["aliases"];
+	workspace?: string;
+	tasks?: DiscoveryMetadata["tasks"];
+	omitted?: number;
+	scope?: DiscoveryMetadata["scope"];
+	state?: DiscoveryMetadata["state"];
+	workRecord?: { work: PublishedWork | null; recordedAt: number };
+	catalog?: CatalogPage;
+	catalogUnavailable?: string;
+	/** Internal binding for targeted consultation; never expose transport records. */
+	publication?: { incarnation: string; activation: string; heartbeat: number };
+}
+
+/** One bounded metadata page, no thread reads or transport probes. The registry
+ * selects a canonical routing activation; metadata must bind to that exact one.
+ * Incomplete scans and duplicate presence headers fail closed. */
+export function discoverOrchestrators(profile: string, peers: readonly PresenceRecord[], now = Date.now(), selection?: { recipientSessionId?: string; cursor?: string; consultation?: boolean; includeWork?: boolean }): OrchestratorCandidate[] {
+	const page = listPresence(profile, now);
+	const ids = [...new Set(peers.map(peer => peer.sessionId))];
+	return ids.filter(id => selection?.recipientSessionId === undefined || selection.recipientSessionId === id).map(sessionId => {
+		const unknown: OrchestratorCandidate = { sessionId, reachability: "unknown", freshness: "unknown" };
+		const activations = peers.filter(peer => peer.sessionId === sessionId);
+		if (page.unavailable || page.overflow || page.rejected || activations.length !== 1) return unknown;
+		const matches = page.entries.filter(h => h.sessionHash === sessionHash(sessionId));
+		// Even a stale duplicate could represent another process with the same ID.
+		if (matches.length !== 1) return unknown;
+		const header = matches[0];
+		const metadata = readDiscovery(profile, header);
+		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);
+		return { ...unknown, ...(catalog.page ? { catalog: catalog.page } : { catalogUnavailable: catalog.unavailable }), freshness: "recent", label: header.label, workspace: metadata.workspace,
+			tasks: metadata.tasks, omitted: metadata.omitted, ...(metadata.aliases ? { aliases: metadata.aliases } : {}), ...(metadata.scope ? { scope: metadata.scope } : {}),
+			...(selection?.consultation ? { publication: { incarnation: header.incarnation, activation: metadata.activation, heartbeat: header.heartbeat } } : {}),
+			...(selection?.includeWork && metadata.state?.sessionId === sessionId
+				? { workRecord: { work: metadata.state.state?.work ?? null, recordedAt: metadata.state.recordedAt } } : {}),
+			...(!selection?.includeWork && selection?.recipientSessionId === sessionId && metadata.state?.sessionId === sessionId ? { state: metadata.state } : {}) };
+	});
+}