@oh-my-pi/pi-coding-agent 15.12.4 → 15.13.0

package/dist/types/tts/player.d.ts

@@ -0,0 +1,32 @@
+export interface PlayerCommand {
+    cmd: string;
+    args: string[];
+}
+/** Injection seam for {@link playerCommandsFor} — defaults to real PATH/tools lookups. */
+export interface PlayerLookup {
+    which?: (bin: string) => string | null;
+    ffmpeg?: () => string | null;
+}
+/**
+ * Build the ordered list of playback commands to try for `filePath` on the
+ * given platform. Pure + injectable so the selection logic is testable without
+ * spawning anything.
+ *
+ * - darwin: `afplay` (always present on macOS).
+ * - win32: PowerShell `Media.SoundPlayer.PlaySync()` (no extra deps).
+ * - linux/other POSIX: `paplay` (PulseAudio) → `aplay` (ALSA) → the bundled
+ *   static `ffmpeg` (`-f pulse` then `-f alsa`). Empty result means nothing is
+ *   available and the caller should surface an install hint.
+ */
+export declare function playerCommandsFor(platform: NodeJS.Platform, filePath: string, lookup?: PlayerLookup): PlayerCommand[];
+export interface PlayAudioOptions {
+    signal?: AbortSignal;
+}
+/**
+ * Play `filePath` through the speakers, trying each candidate command in order
+ * and returning on the first clean exit. Throws an actionable Error if no
+ * player exists or every candidate fails (with the collected stderr).
+ */
+export declare function playAudioFile(filePath: string, options?: PlayAudioOptions): Promise<void>;
+/** Best-effort temp-file cleanup used by callers after playback. */
+export declare function removeTempFile(filePath: string): Promise<void>;

package/dist/types/tts/runtime.d.ts

@@ -0,0 +1,6 @@
+export declare const KOKORO_PACKAGE = "kokoro-js";
+export declare const KOKORO_VERSION = "1.2.1";
+export declare const ONNXRUNTIME_NODE_PACKAGE = "onnxruntime-node";
+export declare const ONNXRUNTIME_NODE_VERSION = "1.26.0";
+export declare function getTtsRuntimeDir(): string;
+export declare function isTtsRuntimeCached(): Promise<boolean>;

package/dist/types/tts/streaming-player.d.ts

@@ -0,0 +1,41 @@
+import { type PlayerCommand } from "./player";
+/** Output gain applied while ducked (the user is speaking over the assistant). */
+export declare const DUCK_GAIN = 0.25;
+/** Injection seam for {@link streamingPlayerCommandsFor} — defaults to real PATH/tools lookups. */
+export interface StreamingPlayerLookup {
+    which?: (bin: string) => string | null;
+    ffmpeg?: () => string | null;
+}
+/**
+ * Ordered candidate commands for a persistent raw-PCM player on `platform`: each
+ * reads 32-bit-float little-endian mono PCM at `sampleRate` from stdin (`pipe:0`)
+ * and plays it to the default output device. An empty list means no streaming
+ * backend is available and the caller should fall back to per-file playback.
+ *
+ * - darwin: none; `afplay` is file-only, so macOS uses the interruptible
+ *   per-file fallback.
+ * - linux/other POSIX: `ffmpeg` (`-f pulse` then `-f alsa`) → `paplay`/`aplay`
+ *   raw fallbacks.
+ * - win32: none (PowerShell `SoundPlayer` is file-only).
+ */
+export declare function streamingPlayerCommandsFor(platform: NodeJS.Platform, sampleRate: number, lookup?: StreamingPlayerLookup): PlayerCommand[];
+/**
+ * Single-session gapless player. Lifecycle: {@link start} once, {@link write}
+ * chunks in order, then {@link end} to drain or {@link stop} to abort. Not
+ * reusable after stop/end — create a new instance per utterance.
+ */
+export declare class StreamingAudioPlayer {
+    #private;
+    /** Pick a backend and begin draining. Idempotent; the first call's rate wins. */
+    start(sampleRate: number): void;
+    /** Queue a mono float32 PCM chunk for playback in arrival order. */
+    write(pcm: Float32Array): void;
+    /** Scale subsequent output (1 = normal, <1 = ducked). Applies within {@link LEAD_SECONDS}. */
+    setGain(gain: number): void;
+    /** Close the input; resolves once all queued audio has finished playing. */
+    end(): Promise<void>;
+    /** Stop immediately: kill the player, drop everything still queued. */
+    stop(): void;
+}
+/** Factory the vocalizer calls; a function so tests can stub it without spawning a player. */
+export declare function createStreamingPlayer(): StreamingAudioPlayer;

package/dist/types/tts/tts-client.d.ts

@@ -0,0 +1,93 @@
+import type { Subprocess } from "bun";
+import type { TtsProgressEvent, TtsWorkerInbound, TtsWorkerOutbound } from "./tts-protocol";
+/** Decoded PCM returned by a local synthesis request. */
+export interface TtsAudio {
+    pcm: Float32Array;
+    sampleRate: number;
+}
+/**
+ * Abstraction over the TTS subprocess. The runtime implementation is a Bun child
+ * process so `onnxruntime-node`'s NAPI finalizer never runs inside the main agent
+ * address space — that destructor segfaults Bun during shutdown (issue #1606).
+ */
+interface WorkerHandle {
+    send(message: TtsWorkerInbound): void;
+    onMessage(handler: (message: TtsWorkerOutbound) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    /** Re-reference the subprocess so a pending request keeps the parent event loop alive. */
+    ref(): void;
+    /** Drop the reference once the worker is idle so it never blocks process exit. */
+    unref(): void;
+    terminate(): Promise<void>;
+}
+export interface TtsSynthesizeOptions {
+    voice?: string;
+    signal?: AbortSignal;
+}
+export interface TtsDownloadOptions {
+    signal?: AbortSignal;
+    onProgress?: (event: TtsProgressEvent) => void;
+}
+export interface TtsStreamOptions {
+    voice?: string;
+    signal?: AbortSignal;
+}
+/** One synthesized sentence of a streaming session, in emission order. */
+export interface TtsAudioChunk {
+    index: number;
+    text: string;
+    pcm: Float32Array;
+    sampleRate: number;
+}
+/**
+ * A live streaming-synthesis session. Feed text incrementally with {@link push}
+ * and close the input with {@link end}; `chunks` yields each synthesized
+ * sentence's audio as soon as it is ready, then completes once the worker
+ * finishes draining the closed input.
+ */
+export interface TtsStreamHandle {
+    push(text: string): void;
+    end(): void;
+    chunks: AsyncIterableIterator<TtsAudioChunk>;
+}
+/**
+ * Hidden subcommand on the main CLI that boots the TTS worker in the spawned
+ * subprocess. Kept in sync with the dispatch in `cli.ts` (Main-owned).
+ */
+export declare const TTS_WORKER_ARG = "__omp_tts_worker";
+interface SpawnedSubprocess {
+    proc: Subprocess<"ignore", "ignore", "ignore">;
+    inbound: Set<(message: TtsWorkerOutbound) => void>;
+    errors: Set<(error: Error) => void>;
+    /** Flipped to `true` right before the deliberate SIGKILL so `onExit` can tell it apart from a crash. */
+    intentionalExit: {
+        value: boolean;
+    };
+}
+/**
+ * Spawn the TTS worker as a subprocess. Exported for tests and the smoke probe;
+ * production callers go through {@link spawnTtsWorker}.
+ */
+export declare function createTtsSubprocess(): SpawnedSubprocess;
+export declare class TtsClient {
+    #private;
+    constructor(spawnWorker?: () => WorkerHandle);
+    onProgress(listener: (event: TtsProgressEvent) => void): () => void;
+    synthesize(modelKey: string, text: string, options?: TtsSynthesizeOptions): Promise<TtsAudio | null>;
+    /**
+     * Open a streaming-synthesis session. Text is fed incrementally through the
+     * returned handle's `push`/`end`; audio is emitted one synthesized sentence at
+     * a time via `chunks`, so playback can begin before the full text is known.
+     * Returns an inert handle (immediately-ended `chunks`) for unknown models or
+     * an already-aborted signal, and fails the iterator if the worker cannot spawn.
+     */
+    synthesizeStream(modelKey: string, options?: TtsStreamOptions): TtsStreamHandle;
+    downloadModel(modelKey: string, options?: TtsDownloadOptions): Promise<boolean>;
+    terminate(): Promise<void>;
+}
+export declare const ttsClient: TtsClient;
+export declare function shutdownTtsClient(): Promise<void>;
+export declare function smokeTestTtsWorker({ timeoutMs, }?: {
+    timeoutMs?: number;
+}): Promise<void>;
+export {};

package/dist/types/tts/tts-protocol.d.ts

@@ -0,0 +1,95 @@
+import type { TtsLocalModelKey } from "./models";
+export type TtsProgressStatus = "initiate" | "download" | "progress" | "progress_total" | "done" | "ready" | "error";
+export interface TtsProgressFileState {
+    loaded: number;
+    total: number;
+}
+export interface TtsProgressEvent {
+    modelKey: TtsLocalModelKey;
+    status: TtsProgressStatus;
+    name?: string;
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+    files?: Record<string, TtsProgressFileState>;
+    task?: string;
+    model?: string;
+}
+export type TtsWorkerInbound = {
+    type: "ping";
+    id: string;
+} | {
+    type: "synthesize";
+    id: string;
+    modelKey: TtsLocalModelKey;
+    text: string;
+    voice?: string;
+} | {
+    type: "download";
+    id: string;
+    modelKey: TtsLocalModelKey;
+} | {
+    type: "stream-start";
+    id: string;
+    modelKey: TtsLocalModelKey;
+    voice?: string;
+} | {
+    type: "stream-push";
+    id: string;
+    text: string;
+} | {
+    type: "stream-end";
+    id: string;
+} | {
+    type: "stream-cancel";
+    id: string;
+};
+export type TtsWorkerOutbound = {
+    type: "pong";
+    id: string;
+} | {
+    type: "audio";
+    id: string;
+    pcm: Float32Array;
+    sampleRate: number;
+} | {
+    type: "downloaded";
+    id: string;
+} | {
+    type: "error";
+    id: string;
+    error: string;
+} | {
+    type: "progress";
+    id: string;
+    event: TtsProgressEvent;
+} | {
+    type: "log";
+    level: "debug" | "warn" | "error";
+    msg: string;
+    meta?: Record<string, unknown>;
+} | {
+    type: "audio-chunk";
+    id: string;
+    index: number;
+    text: string;
+    pcm: Float32Array;
+    sampleRate: number;
+} | {
+    type: "stream-done";
+    id: string;
+};
+/**
+ * Wire transport between the parent (`TtsClient`) and the local TTS subprocess.
+ * The parent owns the subprocess lifecycle (graceful work, hard SIGKILL on
+ * shutdown); the protocol carries no explicit close handshake — once the parent
+ * decides to terminate, it signals the OS to reap the child so
+ * `onnxruntime-node`'s NAPI finalizer never runs in the main agent address
+ * space (it segfaults Bun on shutdown — issue #1606). See `tts-client.ts` for
+ * the spawn/kill glue.
+ */
+export interface TtsTransport {
+    send(message: TtsWorkerOutbound): void;
+    onMessage(handler: (message: TtsWorkerInbound) => void): () => void;
+}

package/dist/types/tts/tts-worker.d.ts

@@ -0,0 +1,2 @@
+import type { TtsTransport } from "./tts-protocol";
+export declare function startTtsWorker(transport: TtsTransport): void;

package/dist/types/tts/vocalizer.d.ts

@@ -0,0 +1,41 @@
+export interface VocalizerPlayer {
+    start(sampleRate: number): void;
+    write(pcm: Float32Array): void;
+    setGain(gain: number): void;
+    end(): Promise<void>;
+    stop(): void;
+}
+export declare class Vocalizer {
+    #private;
+    constructor(createPlayer?: () => VocalizerPlayer);
+    /**
+     * Stream a delta of assistant text into the engine. No-op when vocalization
+     * is disabled. The engine buffers the running text and emits audio for each
+     * complete sentence; the trailing partial is flushed by {@link flush}.
+     */
+    pushDelta(text: string): void;
+    /**
+     * Close the current input stream (call at message/turn end). The engine
+     * flushes its trailing partial as a final chunk; the player keeps draining
+     * queued audio until it completes.
+     */
+    flush(): void;
+    /**
+     * Speak a complete piece of text in one shot (ask questions, yield-mode final
+     * message): stream it in and immediately close the input. No-op when disabled.
+     */
+    speak(text: string): void;
+    /**
+     * Interrupt and drop the current session, killing in-flight playback and
+     * synthesis (new turn / user message / Esc interrupt). Audio stops at once.
+     */
+    clear(): void;
+    /** Lower the volume while the user is speaking (push-to-talk), so speech doesn't drown them out. */
+    duck(): void;
+    /** Restore full volume once the user stops speaking. */
+    unduck(): void;
+    /** Resolve once the playback chain has drained (tests / shutdown). */
+    idle(): Promise<void>;
+}
+/** Process-level vocalizer shared by the event controller and the ask tool. */
+export declare const vocalizer: Vocalizer;

package/dist/types/tts/wav.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Assemble a mono PCM16 WAV byte buffer from Float32 PCM samples (the shape
+ * transformers.js `RawAudio` emits: normalized [-1, 1] amplitudes plus a sample
+ * rate). No external encoder is involved — we write a canonical 44-byte RIFF/
+ * WAVE header followed by little-endian signed 16-bit samples. Samples are
+ * clamped before quantization so out-of-range float values do not wrap.
+ */
+export declare function encodeWav(samples: Float32Array, sampleRate: number): Uint8Array;

package/dist/types/utils/tool-choice.d.ts

@@ -5,3 +5,11 @@ import type { Api, Model, ToolChoice } from "@oh-my-pi/pi-ai";
  * narrowing their request tool list before transport.
  */
 export declare function buildNamedToolChoice(toolName: string, model?: Model<Api>): ToolChoice | undefined;
+/**
+ * Whether the given tool choice can be satisfied by the active tool set for the
+ * upcoming turn. Non-named choices (`"none"`, `"required"`, etc.) do not name a
+ * specific tool and are therefore always active.
+ */
+export declare function isToolChoiceActive(toolChoice: ToolChoice | undefined, tools: readonly {
+    name: string;
+}[]): boolean;

package/dist/types/utils/tools-manager.d.ts

@@ -1,4 +1,5 @@
-export type ToolName = "sd" | "sg" | "yt-dlp" | "trafilatura";
+export declare function ffmpegAssetName(_version: string, plat: string, architecture: string): string | null;
+export type ToolName = "sd" | "sg" | "yt-dlp" | "trafilatura" | "ffmpeg";
 export declare function getToolPath(tool: ToolName): string | null;
 type EnsureToolOptions = {
     signal?: AbortSignal;

package/dist/types/utils/tools-manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/web/scrapers/github.d.ts

@@ -1,6 +1,6 @@
 import type { SpecialHandler } from "./types";
 interface GitHubUrl {
-    type: "blob" | "tree" | "repo" | "issue" | "issues" | "pull" | "pulls" | "discussion" | "discussions" | "actions-run" | "actions-job" | "other";
+    type: "blob" | "tree" | "repo" | "commit" | "issue" | "issues" | "pull" | "pulls" | "discussion" | "discussions" | "actions-run" | "actions-job" | "other";
     owner: string;
     repo: string;
     ref?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.12.4",
+	"version": "15.13.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,7 +35,7 @@
 		"check": "biome check . && bun run check:types",
 		"check:types": "tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
-		"test": "bun test --parallel",
+		"test": "bun test --parallel=2",
 		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index",
 		"fmt": "biome format --write . && bun run format-prompts",
 		"format-prompts": "bun scripts/format-prompts.ts",
@@ -47,17 +47,17 @@
 		"@agentclientprotocol/sdk": "0.25.0",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "15.12.4",
-		"@oh-my-pi/omp-stats": "15.12.4",
-		"@oh-my-pi/pi-agent-core": "15.12.4",
-		"@oh-my-pi/pi-ai": "15.12.4",
-		"@oh-my-pi/pi-catalog": "15.12.4",
-		"@oh-my-pi/pi-mnemopi": "15.12.4",
-		"@oh-my-pi/pi-natives": "15.12.4",
-		"@oh-my-pi/pi-tui": "15.12.4",
-		"@oh-my-pi/pi-utils": "15.12.4",
-		"@oh-my-pi/pi-wire": "15.12.4",
-		"@oh-my-pi/snapcompact": "15.12.4",
+		"@oh-my-pi/hashline": "15.13.0",
+		"@oh-my-pi/omp-stats": "15.13.0",
+		"@oh-my-pi/pi-agent-core": "15.13.0",
+		"@oh-my-pi/pi-ai": "15.13.0",
+		"@oh-my-pi/pi-catalog": "15.13.0",
+		"@oh-my-pi/pi-mnemopi": "15.13.0",
+		"@oh-my-pi/pi-natives": "15.13.0",
+		"@oh-my-pi/pi-tui": "15.13.0",
+		"@oh-my-pi/pi-utils": "15.13.0",
+		"@oh-my-pi/pi-wire": "15.13.0",
+		"@oh-my-pi/snapcompact": "15.13.0",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",
@@ -80,7 +80,8 @@
 		"zod": "^4"
 	},
 	"optionalDependencies": {
-		"@huggingface/transformers": "^4.2.0"
+		"@huggingface/transformers": "^4.2.0",
+		"sherpa-onnx-node": "1.13.2"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/async/job-manager.ts

@@ -6,6 +6,27 @@ const DELIVERY_RETRY_JITTER_MS = 200;
 const DEFAULT_RETENTION_MS = 5 * 60 * 1000;
 const DEFAULT_MAX_RUNNING_JOBS = 15;
 
+/**
+ * Adaptive ("smart") `job` poll-wait ladder (ms). A tight poll loop climbs
+ * these rungs so each immediate re-poll backs off and stops spending turns on
+ * "still running" frames; the floor (first rung) is the shortest wait and the
+ * top rung is the longest a smart poll will ever block. Only used when
+ * `async.pollWaitDuration` is set to `smart`; fixed durations wait verbatim.
+ */
+const POLL_WAIT_LADDER_MS = [5_000, 10_000, 30_000, 60_000, 300_000] as const;
+/**
+ * Going at least this long between poll calls means the agent stepped out of
+ * the poll loop to do real work — the next poll drops back to the ladder floor.
+ */
+const POLL_ESCALATION_RESET_MS = 60_000;
+
+interface PollEscalationState {
+	/** Index into POLL_WAIT_LADDER_MS used for the most recent poll wait. */
+	level: number;
+	/** Timestamp (ms) when the most recent poll wait returned. */
+	lastPollEndAt: number;
+}
+
 export interface AsyncJob {
 	id: string;
 	type: "bash" | "task";
@@ -96,6 +117,7 @@ export class AsyncJobManager {
 	readonly #suppressedDeliveries = new Set<string>();
 	readonly #watchedJobs = new Set<string>();
 	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
+	readonly #pollEscalation = new Map<string | undefined, PollEscalationState>();
 	readonly #onJobComplete: AsyncJobManagerOptions["onJobComplete"];
 	readonly #maxRunningJobs: number;
 	readonly #retentionMs: number;
@@ -295,6 +317,32 @@ export class AsyncJobManager {
 		return removed;
 	}
 
+	/**
+	 * Compute the next adaptive ("smart") wait (ms) for a blocking `job` poll by
+	 * the given owner. Consecutive polls — those starting within
+	 * POLL_ESCALATION_RESET_MS of the previous poll returning — climb
+	 * POLL_WAIT_LADDER_MS so a tight wait loop backs off; a longer gap means the
+	 * agent left to do real work, so the wait resets to the floor. Pair each call
+	 * with `recordPollWaitEnd()` once the wait returns.
+	 */
+	nextPollWaitMs(ownerId: string | undefined, now: number = Date.now()): number {
+		const prev = this.#pollEscalation.get(ownerId);
+		const reset = !prev || now - prev.lastPollEndAt >= POLL_ESCALATION_RESET_MS;
+		const level = reset ? 0 : Math.min(prev.level + 1, POLL_WAIT_LADDER_MS.length - 1);
+		this.#pollEscalation.set(ownerId, { level, lastPollEndAt: prev?.lastPollEndAt ?? now });
+		return POLL_WAIT_LADDER_MS[level];
+	}
+
+	/**
+	 * Mark a blocking poll wait as finished so the idle-reset window is measured
+	 * from now. Polling again before POLL_ESCALATION_RESET_MS elapses keeps
+	 * climbing the ladder; waiting longer resets it to the floor.
+	 */
+	recordPollWaitEnd(ownerId: string | undefined, now: number = Date.now()): void {
+		const prev = this.#pollEscalation.get(ownerId);
+		this.#pollEscalation.set(ownerId, { level: prev?.level ?? 0, lastPollEndAt: now });
+	}
+
 	acknowledgeDeliveries(jobIds: string[]): number {
 		const uniqueJobIds = Array.from(new Set(jobIds.map(id => id.trim()).filter(id => id.length > 0)));
 		if (uniqueJobIds.length === 0) return 0;
@@ -405,6 +453,7 @@ export class AsyncJobManager {
 		this.#inFlightDeliveries.length = 0;
 		this.#suppressedDeliveries.clear();
 		this.#watchedJobs.clear();
+		this.#pollEscalation.clear();
 		return drained;
 	}
 

package/src/autolearn/controller.ts

@@ -0,0 +1,139 @@
+/**
+ * Auto-learn session controller (experimental).
+ *
+ * Subscribes to the session event stream and, after a substantive turn,
+ * nudges the agent to capture reusable lessons. Default posture is passive
+ * (a hidden reminder rides the next real turn); with `autolearn.autoContinue`
+ * it auto-runs exactly one synthetic capture turn at stop.
+ *
+ * Installed once per top-level session (taskDepth 0). The subscription lives
+ * for the session's lifetime — `newSession` resets the session in place
+ * without re-running startup — so the controller needs no disposal.
+ */
+import { logger } from "@oh-my-pi/pi-utils";
+import type { Settings } from "../config/settings";
+import autolearnGuidance from "../prompts/system/autolearn-guidance.md" with { type: "text" };
+import autolearnGuidanceLearn from "../prompts/system/autolearn-guidance-learn.md" with { type: "text" };
+import autolearnNudge from "../prompts/system/autolearn-nudge.md" with { type: "text" };
+import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+
+const AUTOLEARN_NUDGE = autolearnNudge.trim();
+const DEFAULT_MIN_TOOL_CALLS = 5;
+
+/**
+ * Build the standing auto-learn guidance for the system prompt from the tools
+ * actually present in the active set, or null when `manage_skill` is absent.
+ *
+ * Driven by tool presence rather than live settings: the `learn`/`manage_skill`
+ * registry is built ONCE at session start (and only for top-level sessions), so
+ * keying the guidance on `autolearn.enabled` would let a mid-session enable — or
+ * a subagent that filtered the tools out — inject guidance pointing at tools the
+ * session never built. The `learn` addendum is included only when the `learn`
+ * tool is present (it requires a memory backend).
+ */
+export function buildAutoLearnInstructions(available: { manageSkill: boolean; learn: boolean }): string | null {
+	if (!available.manageSkill) return null;
+	const parts = [autolearnGuidance.trim()];
+	if (available.learn) parts.push(autolearnGuidanceLearn.trim());
+	return parts.join("\n\n");
+}
+
+export interface AutoLearnControllerOptions {
+	session: AgentSession;
+	settings: Settings;
+}
+
+export class AutoLearnController {
+	readonly #session: AgentSession;
+	readonly #settings: Settings;
+	#toolCalls = 0;
+	/**
+	 * Whether the in-flight turn BEGAN while goal mode was active. Captured at
+	 * agent_start because a `goal` tool can complete or drop the goal mid-turn,
+	 * clearing the live flag before agent_end — so the end-of-turn state alone
+	 * would let a goal-continuation turn slip through and get nudged.
+	 */
+	#turnStartedInGoalMode = false;
+	/** Swallow the agent_end produced by an auto-run capture turn so it cannot re-trigger. */
+	#suppressNext = false;
+
+	constructor(options: AutoLearnControllerOptions) {
+		this.#session = options.session;
+		this.#settings = options.settings;
+		// The listener closure captures `this`, so the session's listener array
+		// keeps the controller alive — no stored unsubscribe needed.
+		this.#session.subscribe(event => this.#onEvent(event));
+	}
+
+	#onEvent(event: AgentSessionEvent): void {
+		if (event.type === "agent_start") {
+			// Capture goal-mode state at the turn boundary, before any tool runs.
+			this.#turnStartedInGoalMode = this.#session.getGoalModeState()?.enabled === true;
+			return;
+		}
+		if (event.type === "tool_execution_end") {
+			this.#toolCalls++;
+			return;
+		}
+		if (event.type === "agent_end") {
+			this.#onAgentEnd();
+		}
+	}
+
+	#onAgentEnd(): void {
+		// Snapshot and reset every turn: the counter describes only the
+		// just-finished turn, so below-threshold, disabled, and plan-mode stops
+		// must not let tool calls accumulate into a later turn.
+		const toolCalls = this.#toolCalls;
+		this.#toolCalls = 0;
+		// Snapshot the turn-start goal flag alongside the counter so a turn that
+		// observed no agent_start can never inherit a stale value.
+		const startedInGoalMode = this.#turnStartedInGoalMode;
+		this.#turnStartedInGoalMode = false;
+
+		if (this.#suppressNext) {
+			this.#suppressNext = false;
+			return;
+		}
+		// Honor a live opt-out: the subscription outlives the setting, so re-check
+		// the current flag rather than trusting install-time state.
+		if (!this.#settings.get("autolearn.enabled")) return;
+		const minToolCalls = this.#settings.get("autolearn.minToolCalls") ?? DEFAULT_MIN_TOOL_CALLS;
+		if (toolCalls < minToolCalls) return;
+		// Never interrupt plan-mode review.
+		if (this.#session.getPlanModeState()?.enabled) return;
+		// Never divert a goal loop. Skip when the turn STARTED in goal mode — a
+		// `goal` tool may have completed/dropped the goal before this stop — or is
+		// still in it: a passive nudge would ride the goal continuation, and
+		// auto-continue would compete with it.
+		if (startedInGoalMode || this.#session.getGoalModeState()?.enabled) return;
+
+		// Auto-run a capture turn only when explicitly enabled; otherwise the
+		// hidden reminder rides the next real turn passively.
+		const autoContinue = this.#settings.get("autolearn.autoContinue") === true;
+		// Arm suppression synchronously: the synthetic capture turn's agent_end
+		// fires inside sendCustomMessage (before it resolves), so the flag must be
+		// set before then. Disarm when no turn actually started — a deferred/queued
+		// dispatch or a failed send produces no agent_end, and a latched flag would
+		// otherwise swallow the next real stop.
+		if (autoContinue) this.#suppressNext = true;
+
+		this.#session
+			.sendCustomMessage(
+				{
+					customType: "autolearn-nudge",
+					content: AUTOLEARN_NUDGE,
+					display: false,
+					attribution: "user",
+				},
+				{ deliverAs: "nextTurn", triggerTurn: autoContinue },
+			)
+			.then(started => {
+				if (!started) this.#suppressNext = false;
+			})
+			.catch(err => {
+				this.#suppressNext = false;
+				logger.warn("auto-learn nudge delivery failed", { err });
+			});
+	}
+}