gentle-pi 4.3.0 → 4.4.0

package/lib/nan-provider.ts

@@ -57,6 +57,8 @@ const CHAT_MODELS: NanChatModelConfig[] = ([
 	{
 		id: "deepseek-v4-flash", name: "DeepSeek V4 Flash", input: ["text", "image"], contextWindow: 1_000_000,
 		thinkingLevelMap: EXTENDED_THINKING_LEVEL_MAP, maxTokens: 16_384,
+		// NaN's DeepSeek route enforces this field, not max_completion_tokens.
+		compat: { maxTokensField: "max_tokens" },
 	},
 	{
 		id: "glm5.3-flash", name: "GLM 5.3 Flash", input: ["text", "image"], contextWindow: 1_000_000,
@@ -96,6 +98,7 @@ function cloneModel(model: NanChatModelConfig): NanChatModelConfig {
 		input: [...model.input],
 		cost: { ...model.cost },
 		thinkingLevelMap: model.thinkingLevelMap ? { ...model.thinkingLevelMap } : undefined,
+		...(model.compat ? { compat: { ...model.compat } } : {}),
 	};
 }
 

package/lib/native-review-cli.ts

@@ -202,10 +202,10 @@ export interface NativeReviewModeResult {
 // stream while still succeeding. That last qualifier is what keeps this list
 // honest: v2.4.0 deleted reviewConsentSkippedDefaultProvenance ("Reviews are
 // on by default; this was never explicitly chosen. ..."), which used to ride
-// with the skip notice whenever the resolved mode source was `default`. Under
-// opt-in receipt-driven development a default-source clone is refused long
-// before the consent ceremony runs, so the pinned binary can no longer emit
-// that line and it is removed here rather than left as dead tolerance. Multi-
+// with the skip notice whenever the resolved mode source was `default`. Reviews
+// are on by default again since gentle-ai v4.0.0, but the pinned binary no
+// longer has that function and cannot emit the line, so it is removed here
+// rather than left as dead tolerance. Multi-
 // line stderr is still expected in principle — these are separate Fprintln
 // calls, never one joined string — which is why membership is per line.
 export const REVIEW_CONSENT_NOTICES = Object.freeze([
@@ -1090,6 +1090,13 @@ export const NATIVE_CLI_CONTRACTS = Object.freeze({
 	// 9d2927a84ba9a596f69029e3f854b16f86ca4c8b32cc5d63683764ccf2fb394b.
 	// No new negotiated capability identity is asserted.
 	"4.2.0": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
+	// v4.3.1 repeats 4.2.0: the published binary still advertises
+	// capabilities/v2.6 under review-integration/v2, and the provider contract
+	// stays at 1.4.0, with published tarball SHA-256
+	// 58450471280aeb357443d6a28c819132d8c8eb78dd25b12bac64296b2f8c27c2.
+	// The v4.3.0 tag has no release and is never pinned.
+	// No new negotiated capability identity is asserted.
+	"4.3.1": Object.freeze({ start: true, finalize: true, validate: true, bindSdd: true, status: true, inventory: true, reclaim: true, recover: true, abandon: true, quarantineLegacy: true, reconcileAuthority: true, repairLegacyAlias: true, mode: true, riskEvidence: false, hint: false, delivery: true }),
 });
 
 export interface NativeReviewProcessDiagnostics {

package/lib/notification-audio-native.ts

@@ -8,6 +8,14 @@
  * worker as a Node child with fixed literal flags and a scrubbed environment.
  * Linux only; macOS/Windows never spawn. No real audio, no real Pulse stream
  * beyond the worker's own fake-test sockets; there is no physical-playback claim.
+ *
+ * Playback persistence: plays share ONE long-lived `serve` worker per bridge
+ * instance (line-delimited JSON over stdin, one bounded envelope per play).
+ * A crashed worker is replaced by a fresh spawn on the next play; abort,
+ * timeout, a malformed serve line and `dispose()` all SIGKILL it once and
+ * settle only on `close`. Requests are serialized through the worker with a
+ * bounded pending queue. Teardown is the owner's `dispose()` (session shutdown),
+ * plus the worker's own stdin-EOF exit when the owner process dies.
  */
 import { spawn } from "node:child_process";
 import type { EventEmitter } from "node:events";
@@ -21,18 +29,21 @@ const MAX_STDERR = 4096;
 const DEFAULT_PROBE_TIMEOUT_MS = 1200;
 /** 10 s maximum validated duration plus a 1 s termination margin; must outlive every accepted sound. */
 const DEFAULT_PLAY_TIMEOUT_MS = 11000;
+/** Bounded pending plays per serve worker (1 active + queue), mirroring the repo's small caps. */
+const MAX_PENDING_PLAYS = 8;
 
 export interface NativePulseProbeResult { readonly available: boolean; readonly formats: readonly ("wav")[]; }
 export interface NativePulseSpawnOptions {
 	readonly shell: false;
 	readonly windowsHide: true;
 	readonly detached: false;
-	readonly stdio: readonly ["ignore", "pipe", "pipe"];
+	readonly stdio: readonly ("ignore" | "pipe")[];
 	readonly env: NodeJS.ProcessEnv;
 }
 export interface NativePulseChild {
 	stdout: EventEmitter | null;
 	stderr: EventEmitter | null;
+	stdin: { write(chunk: string): boolean } | null;
 	kill(signal: string): boolean;
 	once(event: string, listener: (...args: unknown[]) => void): EventEmitter;
 }
@@ -49,6 +60,25 @@ export interface NativePulseOptions {
 
 interface Envelope { schema?: unknown; ok?: unknown; available?: unknown; formats?: unknown; played?: unknown; }
 interface RunResult { readonly stdout: string; readonly stderr: string; readonly aborted: boolean; readonly timedOut: boolean; }
+/** One queued/active play through the persistent serve worker. */
+interface ServeRequest {
+	readonly snapshot: string;
+	readonly signal: AbortSignal | undefined;
+	readonly resolve: () => void;
+	readonly reject: (error: Error) => void;
+	timer?: ReturnType<typeof setTimeout> | number;
+	onAbort?: () => void;
+	aborted: boolean;
+	timedOut: boolean;
+	settled: boolean;
+}
+interface ServeWorker {
+	readonly child: NativePulseChild;
+	line: string;
+	active?: ServeRequest;
+	readonly queued: ServeRequest[];
+	dead: boolean;
+}
 
 /** Distinct from other native failures so the owner can treat a false permit as "not started". */
 export class NativePulseNotPermittedError extends Error {
@@ -58,9 +88,8 @@ export class NativePulseNotPermittedError extends Error {
 function unrefTimer(handle: ReturnType<typeof setTimeout> | number): void { (handle as { unref?: () => void }).unref?.(); }
 function abortError(): Error { const error = new Error("Native pulse: aborted"); error.name = "AbortError"; return error; }
 function defaultSpawn(executable: string, args: string[], options: NativePulseSpawnOptions): NativePulseChild {
-	const stdio: ("ignore" | "pipe")[] = ["ignore", "pipe", "pipe"];
-	// SAFETY: Node's ChildProcess exposes stdout/stderr/once/kill compatible with the narrower NativePulseChild interface; the cast only bridges that structural narrowing.
-	return spawn(executable, args, { ...options, stdio }) as unknown as NativePulseChild;
+	// SAFETY: Node's ChildProcess exposes stdout/stderr/stdin/once/kill compatible with the narrower NativePulseChild interface; the cast only bridges that structural narrowing.
+	return spawn(executable, args, { ...options, stdio: [...options.stdio] }) as unknown as NativePulseChild;
 }
 function parseEnvelope(stdout: string): Envelope | undefined {
 	const text = stdout.trim();
@@ -78,6 +107,7 @@ export class NativePulsePlayer {
 	private readonly setTimer: NonNullable<NativePulseOptions["setTimeout"]>;
 	private readonly clearTimer: NonNullable<NativePulseOptions["clearTimeout"]>;
 	private formats: readonly ("wav")[] = [];
+	private worker?: ServeWorker;
 
 	constructor(options: NativePulseOptions = {}) {
 		this.options = { ...options };
@@ -107,10 +137,9 @@ export class NativePulsePlayer {
 	}
 
 	/** Spawns synchronously; resolves ONLY on the child `close` event (never exit/error/kill). */
-	private run(mode: "probe" | "play", snapshot: string | undefined, signal: AbortSignal | undefined, timeoutMs: number): Promise<RunResult> {
+	private run(signal: AbortSignal | undefined, timeoutMs: number): Promise<RunResult> {
 		return new Promise<RunResult>(resolve => {
-			const args = [...FIXED_NODE_FLAGS, this.workerPath(), mode];
-			if (snapshot !== undefined) args.push(snapshot);
+			const args = [...FIXED_NODE_FLAGS, this.workerPath(), "probe"];
 			const child = (this.options.spawn ?? defaultSpawn)(process.execPath, args, {
 				shell: false, windowsHide: true, detached: false, stdio: ["ignore", "pipe", "pipe"], env: this.childEnv(),
 			});
@@ -142,21 +171,128 @@ export class NativePulsePlayer {
 	/** Offline/malformed/unsupported probe resolves unavailable; it never throws private IPC. */
 	async probe(signal?: AbortSignal): Promise<NativePulseProbeResult> {
 		if (!this.supportsTarget() || signal?.aborted) { this.formats = []; return { available: false, formats: [] }; }
-		const result = await this.run("probe", undefined, signal, this.options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS);
+		const result = await this.run(signal, this.options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS);
 		const parsed = result.aborted || result.timedOut ? { available: false, formats: [] as const } : this.parseProbe(result.stdout);
 		this.formats = parsed.available ? ["wav"] : [];
 		return parsed;
 	}
 
-	/** `gate` (permit or predicate) runs synchronously before spawn; false means no child at all. */
+	/** Spawns or reuses the persistent `serve` worker. A dead worker is replaced by a fresh spawn. */
+	private ensureWorker(): ServeWorker {
+		if (this.worker && !this.worker.dead) return this.worker;
+		const child = (this.options.spawn ?? defaultSpawn)(process.execPath, [...FIXED_NODE_FLAGS, this.workerPath(), "serve"], {
+			shell: false, windowsHide: true, detached: false, stdio: ["pipe", "pipe", "pipe"], env: this.childEnv(),
+		});
+		const worker: ServeWorker = { child, line: "", queued: [], dead: false };
+		this.worker = worker;
+		child.stdout?.on("data", chunk => this.onServeStdout(worker, chunk));
+		child.stderr?.on("data", () => { /* drained: a full stderr pipe must never stall the worker */ });
+		child.once("close", () => this.closeWorker(worker));
+		child.once("error", () => { /* Node emits close after spawn errors; keep waiting */ });
+		return worker;
+	}
+
+	private armGuards(request: ServeRequest): void {
+		const timer = this.setTimer(() => { request.timedOut = true; this.killWorker(); },
+			this.options.playTimeoutMs ?? DEFAULT_PLAY_TIMEOUT_MS);
+		unrefTimer(timer);
+		request.timer = timer;
+		request.onAbort = () => { request.aborted = true; this.killWorker(); };
+		request.signal?.addEventListener("abort", request.onAbort, { once: true });
+		if (request.signal?.aborted) request.onAbort();
+	}
+
+	private settleSuccess(request: ServeRequest): void {
+		if (request.settled) return;
+		request.settled = true;
+		if (request.timer !== undefined) this.clearTimer(request.timer);
+		if (request.onAbort) request.signal?.removeEventListener("abort", request.onAbort);
+		request.resolve();
+	}
+
+	/** Private failure: aborted requests reject with the abort error, everything else with the generic one. */
+	private settleFailure(request: ServeRequest): void {
+		if (request.settled) return;
+		request.settled = true;
+		if (request.timer !== undefined) this.clearTimer(request.timer);
+		if (request.onAbort) request.signal?.removeEventListener("abort", request.onAbort);
+		request.reject(request.aborted ? abortError() : new Error("Native pulse playback failed"));
+	}
+
+	/** SIGKILL once; the pending plays settle on the child `close` event (never exit/error/kill). */
+	private killWorker(): void {
+		const worker = this.worker;
+		if (!worker || worker.dead) return;
+		worker.dead = true;
+		try { worker.child.kill("SIGKILL"); } catch { /* close still settles every pending play */ }
+	}
+
+	private closeWorker(worker: ServeWorker): void {
+		worker.dead = true;
+		if (this.worker === worker) this.worker = undefined;
+		for (const request of [worker.active, ...worker.queued]) if (request) this.settleFailure(request);
+		worker.active = undefined;
+		worker.queued.length = 0;
+	}
+
+	private dispatch(worker: ServeWorker, request: ServeRequest): void {
+		if (worker.dead) { this.settleFailure(request); return; }
+		worker.active = request;
+		const stdin = worker.child.stdin;
+		if (!stdin) { this.killWorker(); return; }
+		try { stdin.write(`${JSON.stringify({ schema: NATIVE_PULSE_SCHEMA, op: "play", path: request.snapshot })}\n`); }
+		catch { this.killWorker(); }
+	}
+
+	private onServeStdout(worker: ServeWorker, chunk: unknown): void {
+		worker.line += String(chunk);
+		for (;;) {
+			const index = worker.line.indexOf("\n");
+			if (index === -1) break;
+			const line = worker.line.slice(0, index);
+			worker.line = worker.line.slice(index + 1);
+			const envelope = parseEnvelope(line);
+			if (!envelope) { this.killWorker(); return; } // Protocol violation: `close` settles every pending play.
+			const request = worker.active;
+			worker.active = undefined;
+			if (envelope.ok === true && envelope.played === true) { if (request) this.settleSuccess(request); }
+			else if (request) this.settleFailure(request); // A private ok:false leaves the worker serviceable.
+			const next = worker.queued.shift();
+			if (next) this.dispatch(worker, next);
+		}
+		if (worker.line.length > MAX_STDOUT) this.killWorker(); // Unterminated envelope line over the bound.
+	}
+
+	/** `gate` (permit or predicate) runs synchronously before any spawn/write; false means no child at all.
+	 *  Plays serialize through one persistent worker; extras wait in a bounded queue. */
 	async play(snapshot: string, signal?: AbortSignal, gate?: (() => boolean) | { permit(): boolean }): Promise<void> {
 		if (!this.supportsTarget()) throw new Error("Native pulse: unsupported platform");
 		if (signal?.aborted) throw abortError();
 		const permitted = typeof gate === "function" ? gate() : gate?.permit();
 		if (permitted === false) throw new NativePulseNotPermittedError();
-		const result = await this.run("play", snapshot, signal, this.options.playTimeoutMs ?? DEFAULT_PLAY_TIMEOUT_MS);
-		if (result.aborted) throw abortError();
-		const envelope = parseEnvelope(result.stdout);
-		if (result.timedOut || !envelope || envelope.ok !== true || envelope.played !== true) throw new Error("Native pulse playback failed");
+		return new Promise<void>((resolve, reject) => {
+			const worker = this.ensureWorker();
+			const request: ServeRequest = { snapshot, signal, resolve, reject, aborted: false, timedOut: false, settled: false };
+			if (worker.active) {
+				if (worker.queued.length >= MAX_PENDING_PLAYS) { reject(new Error("Native pulse: too many pending plays")); return; }
+				this.armGuards(request);
+				worker.queued.push(request);
+				return;
+			}
+			this.armGuards(request);
+			this.dispatch(worker, request);
+		});
+	}
+
+	/** Owner teardown: SIGKILL the persistent worker once and settle every pending play. */
+	dispose(): void {
+		const worker = this.worker;
+		this.worker = undefined;
+		if (!worker) return;
+		worker.dead = true;
+		try { worker.child.kill("SIGKILL"); } catch { /* the child is already gone */ }
+		for (const request of [worker.active, ...worker.queued]) if (request) this.settleFailure(request);
+		worker.active = undefined;
+		worker.queued.length = 0;
 	}
 }

package/lib/notification-audio.ts

@@ -157,6 +157,8 @@ export interface NativeAudioBackend {
 	probe(signal?: AbortSignal): Promise<{ available: boolean; formats: readonly NotificationAudioFormat[] }>;
 	getNativeFormats(): readonly NotificationAudioFormat[];
 	play(snapshot: string, signal?: AbortSignal, gate?: (() => boolean) | { permit(): boolean }): Promise<void>;
+	/** Optional owner teardown: a persistent native worker (Linux pulse) kills its child. */
+	dispose?(): void;
 }
 interface DiscoveredSystem { executable: string; formats: readonly NotificationAudioFormat[]; }
 interface Discovery { native: readonly NotificationAudioFormat[]; system?: DiscoveredSystem; }
@@ -240,6 +242,8 @@ export class NotificationPlayer {
 		}
 		return undefined;
 	}
+	/** Owner teardown: disposes the native backend, killing a persistent worker if one exists. */
+	dispose(): void { this.native.dispose?.(); }
 	async play(sound: Exclude<NotificationSound, null>, signal: AbortSignal, permit: PlaybackPermit): Promise<void> {
 		if (signal.aborted) return;
 		const discovered = await this.discover();

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 {