gentle-pi 4.3.0 → 4.5.0

package/lib/notification-pulse-worker.ts

@@ -3,8 +3,18 @@
  * owned Node child (`node --experimental-strip-types --max-old-space-size=32`)
  * and speaks a single bounded JSON envelope on stdout:
  *   probe -> { schema, ok, available, formats }
- *   play  -> { schema, ok, played }
- * Failures are private: a generic `{ schema, ok:false }` and a nonzero exit.
+ * Serve protocol (persistent mode): line-delimited JSON requests on stdin,
+ *   `{ schema, op: "play", path }`, answered by one bounded
+ *   `{ schema, ok, played }` envelope per play on stdout. Requests carry a
+ *   snapshot PATH reference, not inline bytes: the worker re-reads the owner's
+ *   private snapshot with the same bounded nofollow `readSnapshot()` on every
+ *   play, so the fail-closed validation of snapshots is preserved verbatim and
+ *   no audio bytes ever cross the stdio channel (request lines stay tiny and
+ *   bounded). Protocol violations crash the worker with a nonzero exit and the
+ *   owner respawns it on the next play; stdin EOF (owner death) exits cleanly
+ *   and an idle worker self-retires, so teardown needs no owner round trip.
+ * Failures are private: a generic `{ schema, ok:false }` and, for protocol
+ * violations, a nonzero exit.
  * It reads only argv, the environment and the owner-supplied snapshot; no SDK,
  * UI, extension, config-owner, cookie-content logging or OS audio surface.
  */
@@ -15,18 +25,25 @@ import { playPulseWav } from "./notification-pulse-stream.ts";
 
 const SCHEMA = "gentle.audio.pulse/v1";
 const MAX_SNAPSHOT_BYTES = 2 * 1024 * 1024;
+/** Request lines carry only a schema/op/path triple; anything longer is a protocol violation. */
+const MAX_REQUEST_BYTES = 4096;
+/** Bounded request backlog; an overflow is a protocol violation (crash, owner restarts). */
+const MAX_PENDING_REQUESTS = 16;
+/** An idle worker self-retires so one owner process never accumulates workers; unref'd, never busy. */
+const SERVE_IDLE_EXIT_MS = 60000;
 
 function emit(payload: Record<string, unknown>): void {
 	process.stdout.write(`${JSON.stringify({ schema: SCHEMA, ...payload })}\n`);
 }
 
-/** Re-read the trusted owner snapshot with the same bounded nofollow pattern. */
-async function readSnapshot(path: string): Promise<Buffer> {
+/** Re-read the trusted owner snapshot with the same bounded nofollow pattern.
+ *  `buffer` is a caller-owned scratch space so persistent serving never
+ *  reallocates the 2 MiB read window per play; the returned bytes are a copy. */
+async function readSnapshot(path: string, buffer: Buffer): Promise<Buffer> {
 	const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
 	try {
 		const stat = await handle.stat();
 		if (!stat.isFile() || stat.size < 44 || stat.size > MAX_SNAPSHOT_BYTES) throw new Error("invalid snapshot");
-		const buffer = Buffer.alloc(MAX_SNAPSHOT_BYTES + 1);
 		const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
 		if (bytesRead !== stat.size) throw new Error("invalid snapshot");
 		return Buffer.from(buffer.subarray(0, bytesRead));
@@ -35,6 +52,63 @@ async function readSnapshot(path: string): Promise<Buffer> {
 	}
 }
 
+/** Protocol violation: one generic envelope so the waiting owner settles, then a crash. */
+function crash(): never {
+	emit({ ok: false });
+	process.exit(1);
+}
+
+async function serve(): Promise<void> {
+	const buffer = Buffer.alloc(MAX_SNAPSHOT_BYTES + 1);
+	const queue: string[] = [];
+	let running = false;
+	let idleTimer: ReturnType<typeof setTimeout> | undefined;
+	const armIdle = () => {
+		clearTimeout(idleTimer);
+		idleTimer = setTimeout(() => { if (queue.length === 0 && !running) process.exit(0); }, SERVE_IDLE_EXIT_MS);
+		idleTimer.unref?.();
+	};
+	const runOne = async (line: string): Promise<void> => {
+		let request: { schema?: unknown; op?: unknown; path?: unknown };
+		try {
+			const parsed: unknown = JSON.parse(line);
+			if (typeof parsed !== "object" || parsed === null) return crash();
+			request = parsed as { schema?: unknown; op?: unknown; path?: unknown };
+		} catch { return crash(); }
+		if (request.schema !== SCHEMA || request.op !== "play" || typeof request.path !== "string" || request.path.length === 0) return crash();
+		try {
+			const bytes = await readSnapshot(request.path, buffer);
+			await playPulseWav(bytes, undefined, { clientOptions: { env: process.env } });
+			emit({ ok: true, played: true });
+		} catch { emit({ ok: false }); } // A private play failure leaves the healthy worker serviceable.
+	};
+	const drain = async (): Promise<void> => {
+		if (running) return;
+		running = true;
+		while (queue.length > 0) { const line = queue.shift()!; armIdle(); await runOne(line); }
+		running = false;
+		armIdle();
+	};
+	process.stdin.setEncoding("utf8");
+	let text = "";
+	process.stdin.on("data", (chunk: string) => {
+		armIdle();
+		text += chunk;
+		for (;;) {
+			const index = text.indexOf("\n");
+			if (index === -1) break;
+			const line = text.slice(0, index);
+			text = text.slice(index + 1);
+			if (line.length > MAX_REQUEST_BYTES || queue.push(line) > MAX_PENDING_REQUESTS) crash();
+		}
+		if (text.length > MAX_REQUEST_BYTES) crash(); // Unterminated request line over the bound.
+		void drain();
+	});
+	process.stdin.on("end", () => process.exit(0));
+	process.stdin.on("error", () => process.exit(1));
+	armIdle();
+}
+
 async function main(): Promise<void> {
 	const mode = process.argv[2];
 	if (mode === "probe") {
@@ -46,21 +120,11 @@ async function main(): Promise<void> {
 		}
 		return;
 	}
-	if (mode === "play") {
-		const snapshot = process.argv[3];
-		if (snapshot === undefined) { emit({ ok: false }); process.exitCode = 1; return; }
-		try {
-			const bytes = await readSnapshot(snapshot);
-			await playPulseWav(bytes, undefined, { clientOptions: { env: process.env } });
-			emit({ ok: true, played: true });
-		} catch {
-			emit({ ok: false });
-			process.exitCode = 1;
-		}
+	if (mode === "serve") {
+		await serve();
 		return;
 	}
-	emit({ ok: false });
-	process.exitCode = 1;
+	crash();
 }
 
 await main();

package/lib/notification-service.ts

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

package/lib/orchestrator-presence.ts

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

package/lib/orchestrator-scope.ts

@@ -62,6 +62,16 @@ export class OrchestratorScopeCache {
 		this.facts.clear();
 		this.snapshot = undefined;
 	}
+	/** Snapshot for deferred (render-cadence trailing) publications: it never
+	 * touches the resolver. A deferred publish reuses the last event-time
+	 * projection as-is even when membership changed since — its Git resolution
+	 * must never race a peer metadata query, whose contract adds no caller Git
+	 * probes. Returns undefined when nothing has been projected yet (or the
+	 * cache was cleared), in which case the caller omits the scope rather than
+	 * probing; the next event-time publication refreshes the facts. */
+	cachedScope(): RecordedScope | undefined {
+		return this.snapshot;
+	}
 	project(cwd: string, tasks: readonly { id: string; cwd: string }[], roots: readonly string[]): RecordedScope {
 		const registered = [...new Set(roots)];
 		const key = createHash("sha256").update(JSON.stringify([cwd, tasks.map(t => [t.id, t.cwd]), registered])).digest("hex");

package/lib/orchestrator-state.ts

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

package/lib/permission-mode-policy.ts

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

package/lib/review-host-relay.ts

@@ -630,8 +630,15 @@ function snapshotReviewHostRelayRequest(request: ReviewHostRelayRequest): Review
 	// are TypeErrors — a programmer mistake, never a typed relay refusal — and
 	// are checked before the business-level reviewer selection below.
 	assertTokens("capture", request.captureArgumentTokens);
-	const gentleAiExecutable = request.gentleAiExecutable ?? resolveGentleAiBinary();
-	if (!isAbsolute(gentleAiExecutable)) throw new TypeError("Pi host relay requires an absolute gentle-ai executable path");
+	// A caller-supplied executable path is input, validated like every other
+	// input before anything else. Only the environment-dependent resolution of
+	// an unspecified executable is deferred below: the executable supply is
+	// environment state (a missing pinned binary, an invalid dev override, a
+	// transient filesystem error under load), and letting its untyped errors
+	// escape ahead of the config check turned the typed configuration refusal
+	// into an environment-dependent unknown failure (gentle-shell#2256).
+	const suppliedExecutable = request.gentleAiExecutable;
+	if (suppliedExecutable !== undefined && !isAbsolute(suppliedExecutable)) throw new TypeError("Pi host relay requires an absolute gentle-ai executable path");
 	// Caller-owned reviewer selection is validated before any process launches:
 	// a broken configuration is a typed refusal, never a mid-review transport
 	// failure (gentle-pi#311 P2).
@@ -640,6 +647,8 @@ function snapshotReviewHostRelayRequest(request: ReviewHostRelayRequest): Review
 	// slot without a provider-owned submission is a typed contract mismatch,
 	// never a synthesized invocation.
 	resolveReviewHostRelaySubmission(request.submission);
+	const gentleAiExecutable = suppliedExecutable ?? resolveGentleAiBinary();
+	if (!isAbsolute(gentleAiExecutable)) throw new TypeError("Pi host relay requires an absolute gentle-ai executable path");
 	const environment = Object.freeze({ ...(request.environment ?? process.env) }) as NodeJS.ProcessEnv;
 	const submission = request.submission === undefined ? undefined : Object.freeze({
 		operationToken: request.submission.operationToken,

package/lib/review-reminder-receipt.ts

@@ -6,6 +6,9 @@ export const REVIEW_REMINDER_RECEIPT = "gentle-pi.review-reminder-receipt/v1";
 export interface ReceiptSession {
 	getSessionId(): string;
 	getBranch(): readonly { type: string; customType?: string; data?: unknown }[];
+	/** Append-only identity for memoizing repeated scans; hosts without it stay uncached. */
+	getLeafId?(): string | null;
+	getEntryCount?(): number;
 }
 interface ReceiptHost { appendEntry(type: string, data: unknown): void }
 export interface MutationEvidence {
@@ -59,7 +62,14 @@ function receipts(session: ReceiptSession, root: string): Receipt[] {
 
 // The first receipt per mutation id, in branch order, plus the index of the
 // last consumed one (-1 when nothing was consumed).
-function mutationLedger(session: ReceiptSession, root: string): { mutations: Mutation[]; consumed: number } {
+type Ledger = { mutations: Mutation[]; consumed: number };
+// Entries are append-only, so an unchanged (leafId, entryCount) identity means
+// the scan result is unchanged: each (session, root) ledger is memoized until
+// the next append (which moves the leaf) invalidates it. Hosts without leaf
+// identity stay uncached, the same way sessionStats must.
+const ledgerMemo = new WeakMap<object, Map<string, Ledger>>();
+
+function scanLedger(session: ReceiptSession, root: string): Ledger {
 	const mutations: Mutation[] = [];
 	let consumed = -1;
 	for (const receipt of receipts(session, root)) {
@@ -74,6 +84,19 @@ function mutationLedger(session: ReceiptSession, root: string): { mutations: Mut
 	return { mutations, consumed };
 }
 
+function mutationLedger(session: ReceiptSession, root: string): Ledger {
+	const leafId = typeof session.getLeafId === "function" ? session.getLeafId() : null;
+	if (leafId === null) return scanLedger(session, root);
+	const key = JSON.stringify([session.getSessionId(), leafId, session.getEntryCount?.(), root] as const);
+	let byKey = ledgerMemo.get(session);
+	const cached = byKey?.get(key);
+	if (cached) return cached;
+	const ledger = scanLedger(session, root);
+	if (!byKey) ledgerMemo.set(session, (byKey = new Map()));
+	byKey.set(key, ledger);
+	return ledger;
+}
+
 export function pendingReviewMutation(session: ReceiptSession, root: string, captured?: string): string | undefined {
 	const { mutations, consumed } = mutationLedger(session, root);
 	if (captured !== undefined) return mutations.findIndex((mutation) => mutation.id === captured) > consumed ? captured : undefined;