gentle-pi 4.0.0 → 4.2.0

package/lib/notification-scheduler.ts

@@ -0,0 +1,173 @@
+import {
+	NOTIFICATION_PRIORITY, notificationSoundFor,
+	type NotificationEvent, type NotificationSettings, type NotificationSound,
+} from "./notification-policy.ts";
+
+export const NOTIFICATION_TTL_MS = 2000;
+export const NOTIFICATION_DEDUPE_CAPACITY = 256;
+export interface NotificationOccurrence {
+	sessionId: string;
+	/** Run or task identity; sequence identifies the occurrence, not the state name. */
+	runId: string;
+	sequence: number;
+	event: NotificationEvent;
+	/** Same monotonic clock domain as SchedulerOptions.now. */
+	occurredAt: number;
+}
+export interface PlaybackPermit {
+	/** Backend MUST call once, synchronously immediately before spawn, after async detection/validation.
+	 * false means do not spawn. Backend owns bounded playback timeout and must honor abort,
+	 * settling only after its process stops. Resolving early violates serial playback. */
+	start(): boolean;
+}
+export interface SchedulerOptions {
+	now(): number;
+	setTimeout(callback: () => void, delayMs: number): number;
+	clearTimeout(handle: number): void;
+	player(sound: Exclude<NotificationSound, null>, signal: AbortSignal, permit: PlaybackPermit): Promise<void>;
+	/** Local diagnostics only. Exceptions here are contained; at most one report per 5 seconds. */
+	onError?(error: unknown): void;
+	dedupeCapacity?: number;
+}
+interface Pending {
+	sound: Exclude<NotificationSound, null>;
+	priority: number;
+	expiresAt: number;
+	readyAt: number;
+	/** Time spent waiting for started playback does not consume the remaining TTL. */
+	pausedAt?: number;
+}
+interface Active {
+	controller: AbortController;
+	generation: number;
+	started: boolean;
+	expiryTimer?: number;
+}
+/** Owner supplies validated settings and TUI/parent guards (including preview). No IO or backend detection here. */
+export class NotificationScheduler {
+	private settings?: NotificationSettings;
+	private muted = false;
+	private sessionId?: string;
+	private generation = 0;
+	private disposed = false;
+	private pending?: Pending;
+	private active?: Active;
+	private timer?: number;
+	private lastStart = -Infinity;
+	private lastError = -Infinity;
+	private readonly seen = new Set<string>();
+	private readonly capacity: number;
+	private readonly options: SchedulerOptions;
+
+	constructor(options: SchedulerOptions) {
+		this.options = options;
+		this.capacity = options.dedupeCapacity ?? NOTIFICATION_DEDUPE_CAPACITY;
+		if (!Number.isInteger(this.capacity) || this.capacity < 1) throw new RangeError("Invalid dedupe capacity");
+	}
+	configure(settings: NotificationSettings, muted: boolean): void {
+		if (this.disposed) return;
+		this.settings = structuredClone(settings); this.muted = muted;
+		if (!settings.enabled || muted) this.invalidate();
+		else this.schedule();
+	}
+	resetSession(sessionId: string): void {
+		if (this.disposed || this.sessionId === sessionId) return;
+		this.invalidate(); this.sessionId = sessionId; this.seen.clear();
+	}
+	/** Returns accepted-to-coalesce, NOT a promise of playback. Off/muted occurrences are consumed too.
+	 * Selected sound is snapshotted here; priority always comes from the event, not the sound. */
+	enqueue(occurrence: NotificationOccurrence): boolean {
+		if (this.disposed || occurrence.sessionId !== this.sessionId) return false;
+		const key = JSON.stringify([occurrence.sessionId, occurrence.runId, occurrence.sequence]);
+		if (this.seen.has(key)) return false;
+		this.seen.add(key);
+		if (this.seen.size > this.capacity) this.seen.delete(this.seen.values().next().value!);
+		const now = this.options.now();
+		const expiresAt = occurrence.occurredAt + NOTIFICATION_TTL_MS;
+		if (!this.automaticEnabled() || !Number.isFinite(occurrence.occurredAt) || occurrence.occurredAt > now || now >= expiresAt) return false;
+		const sound = notificationSoundFor(this.settings!, occurrence.event);
+		if (sound === null) return false;
+		if (this.pending && this.pending.pausedAt === undefined && now >= this.pending.expiresAt) this.pending = undefined;
+		const priority = NOTIFICATION_PRIORITY[occurrence.event];
+		if (this.pending && priority < this.pending.priority) return false;
+		this.pending = { sound, priority, expiresAt,
+			readyAt: this.pending?.readyAt ?? now + this.settings!.audio.coalesceWindowMs,
+			pausedAt: this.active?.started ? now : undefined };
+		this.schedule(); return true;
+	}
+	/** Explicit, bypasses enabled/mute only. Busy when active OR pending; never flushes autos.
+	 * Preview starts count toward automatic minimum interval, but previews themselves are not throttled. */
+	preview(sound: Exclude<NotificationSound, null>): boolean {
+		if (this.disposed || this.active || this.pending) return false;
+		this.play(sound); return true;
+	}
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true; this.invalidate(); this.seen.clear();
+	}
+	private automaticEnabled(): boolean { return !!this.settings?.enabled && !this.muted && !this.disposed; }
+	private clearTimer(): void {
+		if (this.timer !== undefined) this.options.clearTimeout(this.timer);
+		this.timer = undefined;
+	}
+	private invalidate(): void {
+		this.generation++; this.pending = undefined; this.clearTimer();
+		if (this.active) {
+			this.active.controller.abort();
+			if (this.active.expiryTimer !== undefined) this.options.clearTimeout(this.active.expiryTimer);
+		}
+		// Keep active reservation until backend settles, even after abort. Never overlap an uncooperative backend.
+	}
+	private schedule(): void {
+		this.clearTimer();
+		if (!this.pending || !this.automaticEnabled()) return;
+		const now = this.options.now();
+		if (this.pending.pausedAt !== undefined && !this.active?.started) {
+			this.pending.expiresAt += now - this.pending.pausedAt;
+			this.pending.pausedAt = undefined;
+		}
+		if (this.pending.pausedAt === undefined && now >= this.pending.expiresAt) { this.pending = undefined; return; }
+		if (this.active?.started) {
+			// Backend timeout bounds playback. Keep just one candidate, not an accumulating queue.
+			this.pending.pausedAt ??= now;
+			return;
+		}
+		const due = Math.max(this.pending.readyAt, this.lastStart + this.settings!.audio.minimumIntervalMs);
+		if (!this.active && now >= due) {
+			const pending = this.pending; this.pending = undefined;
+			this.play(pending.sound, pending.expiresAt); return;
+		}
+		const wake = this.active ? this.pending.expiresAt : Math.min(due, this.pending.expiresAt);
+		this.timer = this.options.setTimeout(() => { this.timer = undefined; this.schedule(); }, wake - now);
+	}
+	private play(sound: Exclude<NotificationSound, null>, expiresAt?: number): void {
+		const active: Active = { controller: new AbortController(), generation: this.generation, started: false };
+		this.active = active;
+		const permit: PlaybackPermit = { start: () => {
+			if (this.active !== active || active.started || active.controller.signal.aborted || this.disposed || active.generation !== this.generation
+				|| (expiresAt !== undefined && (!this.automaticEnabled() || this.options.now() >= expiresAt))) return false;
+			active.started = true; this.lastStart = this.options.now();
+			if (active.expiryTimer !== undefined) this.options.clearTimeout(active.expiryTimer);
+			this.schedule(); return true;
+		} };
+		if (expiresAt !== undefined) active.expiryTimer = this.options.setTimeout(() => {
+			if (!active.started) active.controller.abort();
+		}, expiresAt - this.options.now());
+		// Calling synchronously also supports a player that throws before returning its promise.
+		try { Promise.resolve(this.options.player(sound, active.controller.signal, permit))
+			.then(() => this.finish(active), error => { this.report(error, active); this.finish(active); }); }
+		catch (error) { this.report(error, active); this.finish(active); }
+	}
+	private report(error: unknown, active: Active): void {
+		if (active.controller.signal.aborted || active.generation !== this.generation || this.disposed) return;
+		const now = this.options.now();
+		if (now - this.lastError < 5000) return;
+		this.lastError = now;
+		try { this.options.onError?.(error); } catch { /* Diagnostics must not produce unhandled rejections. */ }
+	}
+	private finish(active: Active): void {
+		if (active.expiryTimer !== undefined) this.options.clearTimeout(active.expiryTimer);
+		if (this.active === active) this.active = undefined;
+		this.schedule();
+	}
+}

package/lib/notification-service.ts

@@ -0,0 +1,202 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { NotificationPlayer, validateNotificationAudio } from "./notification-audio.ts";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import {
+	DEFAULT_NOTIFICATION_SETTINGS, NOTIFICATION_EVENTS, isNotificationSettings, isNotificationSound,
+	resolveNotificationSettings, restoreNotificationPreset, writeNotificationSettings,
+	type NotificationOptions, type NotificationResolution, type NotificationSettings, type NotificationSound,
+} from "./notification-policy.ts";
+import { NotificationScheduler, type NotificationOccurrence, type SchedulerOptions } from "./notification-scheduler.ts";
+
+export interface NotificationServiceDependencies {
+	now?: () => number;
+	env?: NodeJS.ProcessEnv;
+	policy?: NotificationOptions;
+	read?: () => NotificationResolution;
+	write?: (settings: NotificationSettings) => string;
+	backend?: Pick<NotificationPlayer, "play" | "availability" | "capabilities">;
+	setTimeout?: SchedulerOptions["setTimeout"];
+	clearTimeout?: SchedulerOptions["clearTimeout"];
+}
+export interface NotificationState extends NotificationResolution {
+	muted: boolean;
+	supportedEvents: readonly NotificationOccurrence["event"][];
+}
+/** UI consumers only retrieve this facade. They never claim a lease or subscribe to events. */
+export interface NotificationService {
+	getState(): NotificationState;
+	setConfig(ctx: ExtensionContext, settings: NotificationSettings, options?: { confirmRecovery?: boolean }): boolean;
+	restorePreset(ctx: ExtensionContext, options?: { confirmRecovery?: boolean }): boolean;
+	setMuted(ctx: ExtensionContext, muted: boolean): boolean;
+	preview(ctx: ExtensionContext, sound: Exclude<NotificationSound, null>): boolean;
+	availability(ctx: ExtensionContext): Promise<"available" | "unavailable">;
+	/** Selection-time validation only; never discovers or starts a player. */
+	validateFile(ctx: ExtensionContext, sound: `file:${string}`): Promise<boolean>;
+}
+interface Holder {
+	muted: boolean;
+	epoch: number;
+	ownerLease?: symbol;
+	retire?: () => void;
+	service?: NotificationService;
+	startupNotified: boolean;
+	sourceSession?: string;
+	highwater: Map<string, number>;
+	/** A retired scheduler's backend must settle before any replacement can play. */
+	playback?: object;
+}
+const HOLDER = Symbol.for("gentle-pi.notification-service.v1");
+function holder(): Holder {
+	const root = globalThis as typeof globalThis & { [HOLDER]?: Holder };
+	return root[HOLDER] ??= { muted: false, epoch: 0, startupNotified: false, highwater: new Map() };
+}
+export function getNotificationService(): NotificationService | undefined { return holder().service; }
+export function notificationContextAllowed(ctx: ExtensionContext, env: NodeJS.ProcessEnv = process.env): boolean {
+	// Dialog-capable interactive RPC is intentionally NOT an audio host.
+	return ctx.mode === "tui" && env.GENTLE_PI_AGENTS_CHILD !== "1";
+}
+
+/** Owner-only claim; factory collision invalidates old hooks before the new owner attaches. */
+export function claimNotificationOwner(retireRuntime: () => void, deps: NotificationServiceDependencies = {}) {
+	const shared = holder(); shared.retire?.();
+	const lease = Symbol("notification-owner"); const epoch = ++shared.epoch;
+	shared.ownerLease = lease;
+	const now = deps.now ?? (() => performance.now());
+	const env = deps.env ?? process.env;
+	const backend = deps.backend ?? new NotificationPlayer();
+	let ctx: ExtensionContext | undefined; let sessionId: string | undefined;
+	let scheduler: NotificationScheduler | undefined; let disposed = false; let attachment = 0;
+	let resolution: NotificationResolution | undefined;
+	const diagnostics = new Set<string>();
+	const current = () => !disposed && shared.ownerLease === lease && shared.epoch === epoch;
+	const allowed = (candidate?: ExtensionContext) => current() && !!ctx && !!candidate
+		&& notificationContextAllowed(candidate, env) && notificationContextAllowed(ctx, env)
+		&& candidate.sessionManager.getSessionId() === sessionId && ctx.sessionManager.getSessionId() === sessionId;
+	const report = (category: string, message: string) => {
+		if (!allowed(ctx) || diagnostics.has(category)) return;
+		diagnostics.add(category);
+		try { ctx!.ui.notify(message, "warning"); } catch { /* Local diagnostics cannot fail a run. */ }
+	};
+	const read = () => {
+		resolution = structuredClone((deps.read ?? (() => resolveNotificationSettings(deps.policy)))());
+		if (resolution.malformed || resolution.readError) {
+			resolution.settings = structuredClone(DEFAULT_NOTIFICATION_SETTINGS);
+			report("config", "Notification configuration unavailable or invalid; audio disabled.");
+		}
+	};
+	const makeScheduler = () => {
+		scheduler = new NotificationScheduler({ now,
+			// SAFETY: scheduler treats this handle as opaque; Node's Timeout is returned unchanged to clearTimeout.
+			setTimeout: deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms) as unknown as number),
+			clearTimeout: deps.clearTimeout ?? (id => clearTimeout(id)),
+			player: async (sound, signal, permit) => {
+				if (!allowed(ctx) || shared.playback || signal.aborted) return;
+				const reservation = {}; shared.playback = reservation;
+				try {
+					const available = await backend.availability();
+					if (signal.aborted || !allowed(ctx)) return;
+					if (available === "unavailable") { report("backend", "Notification audio backend unavailable."); return; }
+					await backend.play(sound, signal, { start: () => allowed(ctx) && permit.start() });
+				} finally { if (shared.playback === reservation) shared.playback = undefined; }
+			},
+			onError: () => report("playback", "Notification audio could not be played."),
+		});
+		scheduler.resetSession(sessionId!); scheduler.configure(resolution!.settings, shared.muted);
+	};
+	const shutdown = () => {
+		scheduler?.dispose(); scheduler = undefined; ctx = undefined; sessionId = undefined;
+		attachment++;
+		if (shared.ownerLease === lease) shared.service = undefined;
+	};
+	const service: NotificationService = {
+		getState: () => ({ ...structuredClone(resolution!), muted: shared.muted,
+			// Quit cannot await lazy detection/playback without delaying cleanup/exit.
+			supportedEvents: NOTIFICATION_EVENTS.filter(event => event !== "session.shutdown") }),
+		setConfig: (candidate, settings, options = {}) => {
+			if (!allowed(candidate) || !resolution || !isNotificationSettings(settings, deps.policy?.pathFlavor)
+				|| ((resolution.malformed || resolution.readError) && options.confirmRecovery !== true)) return false;
+			try {
+				const snapshot = structuredClone(settings);
+				const globalFile = (deps.write ?? (value => writeNotificationSettings(value, deps.policy)))(snapshot);
+				// Invalidate even enabled->enabled changes: pending mappings must not become stale.
+				scheduler?.dispose();
+				resolution = { settings: snapshot, globalFile, source: "global_file", malformed: false, readError: false };
+				makeScheduler(); return true;
+			} catch { report("write", "Notification configuration could not be saved."); return false; }
+		},
+		restorePreset: (candidate, options) => service.setConfig(candidate, restoreNotificationPreset(resolution!.settings), options),
+		setMuted: (candidate, muted) => {
+			if (!allowed(candidate) || typeof muted !== "boolean") return false;
+			shared.muted = muted; scheduler?.configure(resolution!.settings, muted); return true;
+		},
+		preview: (candidate, sound) => allowed(candidate) && !shared.playback && isNotificationSound(sound, deps.policy?.pathFlavor)
+			&& sound !== null && !!scheduler?.preview(sound),
+		validateFile: async (candidate, sound) => {
+			if (!allowed(candidate) || !isNotificationSound(sound) || !sound.startsWith("file:")) return false;
+			const activeScheduler = scheduler;
+			try {
+				const handle = await open(sound.slice(5), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+				try {
+					const stat = await handle.stat();
+					if (!stat.isFile() || stat.size < 44 || stat.size > 2 * 1024 * 1024) return false;
+					const bytes = Buffer.alloc(stat.size + 1);
+					const { bytesRead } = await handle.read(bytes);
+					if (bytesRead !== stat.size) return false;
+					const { format } = validateNotificationAudio(bytes.subarray(0, bytesRead));
+					// Assignment-time rejection: a player that cannot play this container must never receive it.
+					if (format !== "wav" && !(await backend.capabilities()).has(format)) return false;
+					return allowed(candidate) && scheduler === activeScheduler;
+				} finally { await handle.close(); }
+			} catch { return false; }
+		},
+		availability: async candidate => {
+			if (!allowed(candidate)) return "unavailable";
+			const activeScheduler = scheduler;
+			try {
+				const result = await backend.availability();
+				return allowed(candidate) && scheduler === activeScheduler ? result : "unavailable";
+			} catch { return "unavailable"; }
+		},
+	};
+	const bindService = (): NotificationService => {
+		const generation = attachment;
+		const live = () => generation === attachment && current();
+		return {
+			getState: service.getState,
+			setConfig: (candidate, settings, options) => live() && service.setConfig(candidate, settings, options),
+			restorePreset: (candidate, options) => live() && service.restorePreset(candidate, options),
+			setMuted: (candidate, muted) => live() && service.setMuted(candidate, muted),
+			preview: (candidate, sound) => live() && service.preview(candidate, sound),
+			availability: candidate => live() ? service.availability(candidate) : Promise.resolve("unavailable"),
+			validateFile: (candidate, sound) => live() ? service.validateFile(candidate, sound) : Promise.resolve(false),
+		};
+	};
+	const retire = () => {
+		if (disposed) return;
+		shutdown(); disposed = true; retireRuntime();
+		if (shared.ownerLease === lease) { shared.ownerLease = undefined; shared.retire = undefined; }
+	};
+	shared.retire = retire;
+	return { now, current, allowed, shutdown, retire,
+		acceptSource: (producerId: string, runId: string, sequence: number) => {
+			if (!allowed(ctx)) return false;
+			const key = JSON.stringify([producerId, runId]);
+			if (sequence <= (shared.highwater.get(key) ?? 0)) return false;
+			shared.highwater.set(key, sequence); return true;
+		},
+		attach: (candidate: ExtensionContext) => {
+			if (!current()) return false;
+			shutdown();
+			if (!notificationContextAllowed(candidate, env)) return false;
+			ctx = candidate; sessionId = candidate.sessionManager.getSessionId();
+			if (shared.sourceSession !== sessionId) { shared.highwater.clear(); shared.sourceSession = sessionId; }
+			read(); makeScheduler(); shared.service = bindService(); return true;
+		},
+		enqueue: (event: NotificationOccurrence) => allowed(ctx) && scheduler?.enqueue(event),
+		startup: () => {
+			if (!allowed(ctx) || shared.startupNotified) return false;
+			shared.startupNotified = true; return true;
+		},
+	};
+}

package/lib/notification-ui.ts

@@ -0,0 +1,87 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_NOTIFICATION_IDS, isNotificationSound, type NotificationEvent, type NotificationSettings, type NotificationSound } from "./notification-policy.ts";
+import { getNotificationService, notificationContextAllowed, type NotificationService } from "./notification-service.ts";
+
+/**
+ * Native dialogs, outside the transcript. No owner creation, commands or visual-store writes.
+ * @deprecated Superseded by the direct rows in `lib/notification-customize.ts`; kept as an
+ * unused test-covered fallback, not wired into `/gentle:customize` anymore.
+ */
+export async function openNotificationPanel(ctx: ExtensionContext): Promise<void> {
+	if (!ctx.hasUI || !notificationContextAllowed(ctx)) return;
+	const fresh = (expected: NotificationService) => {
+		const service = getNotificationService();
+		return service === expected ? service : undefined;
+	};
+	const notify = (message: string, error = false) => ctx.ui.notify(message, error ? "warning" : "info");
+	const chooseSound = async (expected: NotificationService): Promise<NotificationSound | undefined> => {
+		const choice = await ctx.ui.select("Notification sound", ["Silence", ...BUILTIN_NOTIFICATION_IDS.map(id => `builtin:${id}`), "Local WAV file"]);
+		if (!fresh(expected) || choice === undefined) return undefined;
+		if (choice === "Silence") return null;
+		if (choice !== "Local WAV file") return isNotificationSound(choice) ? choice : undefined;
+		const path = await ctx.ui.input("Local WAV file", "Absolute path (no URLs or shell expansion)");
+		const service = fresh(expected);
+		if (!service || path === undefined) return undefined;
+		const sound = `file:${path}` as const;
+		if (!isNotificationSound(sound) || !await service.validateFile(ctx, sound)) {
+			if (fresh(expected)) notify("Select a readable regular PCM WAV (≤2 MiB, ≤10 seconds); absolute local path only.", true);
+			return undefined;
+		}
+		return fresh(expected) ? sound : undefined;
+	};
+	const save = async (expected: NotificationService, change?: (settings: NotificationSettings) => void) => {
+		let service = fresh(expected);
+		if (!service) return;
+		const state = service.getState();
+		let confirmRecovery = false;
+		if (state.malformed || state.readError) {
+			confirmRecovery = await ctx.ui.confirm("Replace invalid notification configuration?",
+				"The existing configuration is invalid or unreadable. Replace it with these settings? Cancellation leaves it untouched.") === true;
+			if (!confirmRecovery) return;
+		}
+		service = fresh(expected);
+		if (!service) return;
+		// Read again after all prompts: never overwrite another action with an old snapshot.
+		const settings = service.getState().settings;
+		change?.(settings);
+		const saved = change ? service.setConfig(ctx, settings, { confirmRecovery }) : service.restorePreset(ctx, { confirmRecovery });
+		notify(saved ? "Notification preferences saved." : "Notification preferences not saved; choose again to retry.", !saved);
+	};
+	while (true) {
+		const service = getNotificationService();
+		if (!service) return;
+		const state = service.getState();
+		const enable = state.settings.enabled ? "Disable audio" : "Enable audio";
+		const mute = state.muted ? "Resume" : "Mute";
+		const action = await ctx.ui.select(`Notifications · audio ${state.settings.enabled ? "on" : "off"} · ${state.muted ? "muted" : "unmuted"}`,
+			[enable, "Assign sound", "Preview sound", mute, "Check availability", "Restore preset"]);
+		if (!fresh(service) || action === undefined) return;
+		try {
+			if (action === enable) await save(service, settings => { settings.enabled = action === "Enable audio"; });
+			else if (action === mute) fresh(service)?.setMuted(ctx, action === "Mute");
+			else if (action === "Restore preset") await save(service);
+			else if (action === "Check availability") {
+				const result = await fresh(service)!.availability(ctx);
+				if (fresh(service)) notify(`Notification audio backend: ${result}.`);
+			} else if (action === "Preview sound") {
+				const sound = await chooseSound(service);
+				const current = fresh(service);
+				if (current && sound !== undefined && sound !== null && !current.preview(ctx, sound)) notify("Preview unavailable or audio busy; try again.", true);
+			} else if (action === "Assign sound") {
+				const origins = [...new Set(service.getState().supportedEvents.map(event => event.split(".")[0]!))];
+				const origin = await ctx.ui.select("Notification origin", origins);
+				let current = fresh(service);
+				if (!current || origin === undefined || !origins.includes(origin)) continue;
+				const events = current.getState().supportedEvents.filter(event => event.startsWith(`${origin}.`));
+				const event = await ctx.ui.select("Notification event", [...events]);
+				current = fresh(service);
+				if (!current || !events.includes(event as NotificationEvent)) continue;
+				const sound = await chooseSound(service);
+				if (sound !== undefined) await save(service, settings => { settings.audio.events[event as NotificationEvent] = sound; });
+			}
+		} catch {
+			if (fresh(service)) notify("Notification action failed; no automatic retry.", true);
+		}
+		if (!fresh(service)) return;
+	}
+}

package/lib/odd-phase.ts

@@ -4,7 +4,7 @@
 // (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-delegation.md). Never inferred from assistant prose;
+// 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

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);
+}