gentle-pi 4.0.0 → 4.2.0

package/docs/render-cache-performance.md

@@ -0,0 +1,28 @@
+# Verify render-cache effectiveness without removing animations
+
+Use the diagnostic runner to compare two worktrees based on the same commit. It loads both through Pi's native virtual modules, verifies exact editor class identity, and retains quality animation, the Shell editor/header/sidebar, native messages, native tool components and fullscreen frame rendering.
+
+## Run
+
+```bash
+node scripts/render-cache-performance.mjs \
+  --baseline-root=<before-worktree> \
+  --candidate-root=<fixed-worktree> \
+  --pi-root=<installed-pi-package> \
+  --output=/tmp/render-cache-performance.json
+```
+
+Default matrix: 100/1,000/5,000 tools × 100/160 columns × float/neon × pulse, scroll, typing, streaming, append, resize and theme. Four fresh-process paired replicas alternate before/after order (AB/BA/AB/BA). `--counts`, `--widths`, `--styles`, `--samples`, `--repetitions` and `--live-ms` override these settings; use small counts and samples for a smoke run. Run serially on an otherwise idle machine.
+
+## Read the evidence
+
+- `runs`: raw action-plus-frame wall/CPU times, cold render, construction time, paint/projection counters, visible-screen hashes, memory snapshots and a separate live quality-timer/typing run.
+- `comparisons`: per-replica medians and exploratory p95, speedup and enforced cold/warm output equivalence. All tracked source files, host/native dependency files and instrumentation fingerprints must remain unchanged.
+- Stable cases use 50 measured frames after five warmup frames. Resize/theme deliberately invalidate caches and use at most eight frames; do not treat their tail percentile as statistically robust.
+- Heap/RSS snapshots use explicit GC outside timing, including a job boundary after teardown. They characterize retention for these fixtures, not all transient allocations or proof of absence of leaks.
+
+## Limits
+
+Reports must use a new path outside the source/harness/host roots; existing files and symlinks are rejected. Read only reports with a `finished` field after successful process exit: progress writes are not atomic.
+
+The transcript is synthetic. Deterministic cases drive the real quality interval callback with controlled time; the separate live run uses real timers and records input-to-frame latency and timer drift. The ANSI sink has no terminal emulator or real terminal-write cost. Model/network latency, other extensions and real session restore/startup are not measured. Private APIs are audited only on Pi and pi-tui 1.1.0 and fail closed on version/editor identity/output mismatches. Preserve raw data and report replicas separately; consecutive frames are correlated, so neither p95 nor a render speedup describes the entire application's latency.

package/docs/session-profile-format.md

@@ -0,0 +1,39 @@
+# Session profile record format
+
+`lib/session-profile-persistence.ts` defines the optional session profile v1
+codec and pure replay contract. Adding this module does not change Enter,
+startup, routing, shared defaults, or live orchestrator behavior.
+
+## Payloads
+
+A custom entry uses `customType: "gentle-pi.session-profile/v1"` and one payload:
+
+```json
+{"kind":"bind","origin":"user","name":"work","modelProfiles":{"worker":{"model":"provider/model"},"orchestrator":{"thinking":"high"}}}
+{"kind":"clear"}
+```
+
+The encoder creates only explicit `user` selections. The decoder accepts the
+closed origin set `user`, `local`, `repo`, and `global`; this does not implement
+inherited startup persistence or follow mode. A bound empty snapshot is not a
+clear. Snapshots are detached, known invalid fields reject the whole binding,
+and unknown extra fields carry no routing meaning. Existing route normalization
+supports legacy model strings and `effort`; valid `thinking` takes precedence.
+
+## Replay
+
+`replaySessionProfileBranch` requires entries already corroborated on disk,
+ordered oldest to newest on the active branch. Supplying `getBranch()` alone
+does not establish persistence. The newest profile-family entry is terminal:
+
+| Result | Meaning |
+| --- | --- |
+| `absent` | No profile-family entry on the supplied branch. |
+| `bound` | A detached, validated binding, including an empty snapshot. |
+| `cleared` | An explicit clear; fallback is a later consumer's decision. |
+| `invalid` | Invalid v1 data; never resurrect an earlier binding. |
+| `unsupported` | Unknown profile-family identifier, regardless of payload. |
+
+Replay neither appends nor publishes bindings and never applies a model or
+thinking level. A subsequent disk-reader slice supplies corroboration; this
+codec alone cannot establish it.

package/docs/sound-notifications-proposal.md

@@ -0,0 +1,191 @@
+# Propuesta: notificaciones sonoras nativas
+
+**Propuesta histórica aprobada y ejecutada por unidades; ver [estado actual](#estado-actual-sn6).** El texto original debajo conserva las decisiones propuestas, no afirma que sigan sin implementar.
+
+Incorporar a gentle-shell notificaciones sonoras configurables para sesión, agente principal y subagentes. El audio estará **desactivado por defecto** y no alterará la ejecución, las decisiones ni los permisos del harness.
+
+## Decisión propuesta
+
+Crear una capa independiente de notificaciones: los adaptadores observan eventos reales, una política decide si notificarlos y un backend reproduce el sonido sin bloquear el trabajo. La reproducción pertenece a la sesión interactiva padre, nunca a cada proceso hijo.
+
+La primera versión ofrece configuración por origen y transición, sonidos incluidos, archivos propios, prueba de sonido y silencio temporal. No añade notificaciones de escritorio ni un bus de eventos generalista.
+
+## Encaje en la estructura actual
+
+| Punto existente | Papel en la propuesta |
+|---|---|
+| `extensions/gentle-shell.ts` | Integrar el acceso a configuración; ya observa eventos de sesión y agente principal. |
+| `extensions/gentle-agents.ts` | Publicar transiciones de tareas vivas, sin reproducir audio directamente. |
+| `lib/agents-protocol.ts` | Fuente del vocabulario de estados de subagentes. No duplicar su máquina de estados. |
+| `lib/agent-home.ts` | Resolver el directorio global con `gentlePiConfigHome()`. |
+| `lib/visual-customization-policy.ts` | Referencia de configuración validada y escritura atómica; no mezclar audio con ajustes visuales. |
+
+Archivos nuevos orientativos:
+
+- `extensions/gentle-notifications.ts`: ciclo de vida, suscripciones y propietario único del servicio.
+- `lib/notification-policy.ts`: esquema, resolución de configuración, selección de sonido, deduplicación y límites.
+- `lib/notification-audio.ts`: detección de capacidades y reproducción por plataforma.
+- `assets/sounds/`: sonidos breves con licencia redistribuible documentada.
+- Pruebas de política, adaptadores y reproducción bajo `tests/`.
+
+La integración usará el mecanismo de eventos existente. Los nuevos eventos internos serán tipados y específicos de notificaciones; no se introducirán dependencias desde los runners hacia audio o UI.
+
+## Qué se puede configurar
+
+Se notifican **entradas en estados o eventos de ciclo de vida**, no snapshots ni cada actualización de texto. Sesión, agente principal y subagentes no comparten necesariamente los mismos estados.
+
+| Origen | Transiciones/eventos propuestos | Condición |
+|---|---|---|
+| Sesión | `started`, `shutdown` | Inicio interactivo y cierre; el sonido de cierre es de mejor esfuerzo. |
+| Agente principal | `started`, `completed`, `failed`, `cancelled`, `attention` | Derivados de evidencia del runtime, no de etiquetas visuales. |
+| Subagente | `queued`, `running`, `waiting`, `completed`, `failed`, `cancelled`, `timed_out` | Vocabulario actual de `TASK_STATUS`. |
+
+`attention` significa una petición explícita de intervención, no estar pensando ni ejecutar una herramienta. `waiting` conservará su significado real en el protocolo de subagentes; no se asumirá que todo tiempo de espera requiere al usuario.
+
+**Antes de implementar:** confirmar qué eventos distinguen fallo, cancelación y finalización del agente principal, qué productores representan intervención humana y si `session_start` también cubre cambios de sesión. No interpretar `agent_end` como éxito por sí solo. Si una transición no tiene evidencia fiable, quedará fuera del catálogo inicial y se documentará la limitación.
+
+### Preset recomendado
+
+El interruptor general empieza apagado. Al activarlo con el preset recomendado:
+
+- Finalización de agente principal o subagente: sonido breve de éxito.
+- Fallo y timeout: sonido de error.
+- Intervención humana explícita: sonido de atención.
+- Inicio, ejecución, cancelación y cierre: silencio.
+
+Todos los eventos disponibles pueden asignarse a un sonido o a silencio. El catálogo de la UI mostrará solo eventos realmente soportados.
+
+## Configuración
+
+Archivo global propuesto: `<gentlePiConfigHome()>/notifications.json`; por defecto, `~/.pi/gentle-ai/notifications.json`. Se respeta `GENTLE_PI_CONFIG_HOME`.
+
+Ejemplo ilustrativo del esquema propuesto, no configuración funcional actual:
+
+```json
+{
+  "schema": "gentle-shell.notifications/v1",
+  "enabled": false,
+  "audio": {
+    "backend": "auto",
+    "minimumIntervalMs": 1000,
+    "coalesceWindowMs": 300,
+    "events": {
+      "session.started": null,
+      "session.shutdown": null,
+      "agent.started": null,
+      "agent.completed": "builtin:success",
+      "agent.failed": "builtin:error",
+      "agent.cancelled": null,
+      "agent.attention": "builtin:attention",
+      "subagent.queued": null,
+      "subagent.running": null,
+      "subagent.waiting": null,
+      "subagent.completed": "builtin:success",
+      "subagent.failed": "builtin:error",
+      "subagent.cancelled": null,
+      "subagent.timed_out": "builtin:error"
+    }
+  }
+}
+```
+
+Reglas:
+
+- `null` significa silencio; un evento omitido también significa silencio. No habilitar sonidos nuevos implícitamente al actualizar.
+- `builtin:<id>` selecciona un sonido incluido; `file:<ruta-absoluta>` selecciona un archivo local validado.
+- Archivo ausente: configuración desactivada sin escribir archivos ni detectar reproductores.
+- Archivo inválido o ilegible: audio desactivado y diagnóstico discreto, una sola vez. La UI no sobrescribe un archivo inválido silenciosamente.
+- Escritura atómica, siguiendo el patrón de configuración existente.
+- Sin configuración por repositorio en v1: un proyecto no puede activar audio ni seleccionar archivos o ejecutables en la máquina del usuario.
+- Silencio temporal en memoria, no persistente. Cambiar de sesión conserva ese silencio mientras viva la misma instancia interactiva; reiniciar el proceso lo elimina.
+
+## Experiencia de usuario
+
+Añadir una sección **Notificaciones** al acceso de personalización/configuración existente, separada de los ajustes visuales:
+
+1. Activar/desactivar audio.
+2. Elegir origen y evento; asignar sonido o silencio.
+3. Seleccionar sonido incluido o introducir un archivo local.
+4. Probar el sonido elegido mediante una acción explícita.
+5. Silenciar/reanudar durante esta instancia interactiva.
+6. Consultar disponibilidad del backend y restaurar el preset.
+
+La prueba es una excepción explícita al interruptor general: el usuario puede preescuchar sin activar notificaciones automáticas. No reproduce eventos pendientes ni cambia configuración por sí sola.
+
+No se modifica el resultado de herramientas ni se añaden mensajes al contexto del modelo. No se requiere un comando nuevo en v1.
+
+## Fiabilidad, ruido y seguridad
+
+- **Una sola reproducción:** los hijos publican estados; solo el propietario interactivo padre puede reproducir. RPC/headless y procesos de subagentes permanecen silenciosos.
+- **Sin replay:** restaurar tareas o historial establece la referencia inicial, pero no genera sonidos. Desactivar o silenciar descarta pendientes; reactivar no reproduce el pasado.
+- **Identidad:** deduplicar por sesión, tarea/run y transición. Reinicios o ejecuciones nuevas no reutilizan la identidad anterior.
+- **Ráfagas:** agrupar durante 300 ms y reproducir un sonido con prioridad error > atención > éxito > otros. El intervalo mínimo limita la frecuencia global; no acumular una cola que suene después de perder relevancia.
+- **Sin solapamiento:** reproducción serial y cola acotada a un candidato pendiente. Un sonido más prioritario puede sustituir al pendiente, no al que ya se está reproduciendo.
+- **No bloquear:** procesos asíncronos, timeout acotado y limpieza al cerrar. Ningún fallo de audio cambia el estado del agente.
+- **Archivos seguros:** validar archivo regular, formato permitido y tamaño acotado; no aceptar URL, comandos ni expansión de shell. Ejecutar binarios conocidos con argumentos separados, nunca `shell: true`.
+- **Diagnósticos discretos:** backend ausente o fallo de reproducción produce una advertencia local limitada, nunca spam ni contaminación del transcript.
+- **Sin sonido obligatorio:** no usar BEL como fallback automático; puede producir sonido o aviso visual según el terminal y no permite distinguir los eventos.
+
+## Plataformas
+
+Proponer adaptadores para Linux, macOS y Windows, con detección perezosa al activar o probar audio. No instalar dependencias del sistema automáticamente.
+
+| Entorno | Comportamiento esperado |
+|---|---|
+| Linux | Elegir un reproductor conocido disponible y probar reproducción local. |
+| macOS | Usar reproducción nativa disponible, con el mismo contrato asíncrono. |
+| Windows | Usar un mecanismo nativo sin abrir ventanas de consola auxiliares. |
+| SSH, contenedores o equipos sin audio | Reproducción en la máquina del proceso; no prometer audio en el equipo cliente. Si no hay backend utilizable, informar y seguir. |
+
+WAV sería el formato base para sonidos incluidos y archivos propios en v1, evitando una matriz de codecs. El backend exacto de cada plataforma y los límites de tamaño/duración se concretarán tras una prueba técnica; no se considerará soportada una plataforma sin verificación real.
+
+## Alcance y no objetivos
+
+**Incluido:** configuración global opt-in, catálogo de transiciones verificables, sonidos incluidos/propios, UI de configuración, prueba, silencio temporal, deduplicación, agrupación y fallos no bloqueantes.
+
+**Fuera de v1:** notificaciones de escritorio, voz, URLs de audio, ejecutables configurables, horarios, reglas por agente individual/proyecto, sincronización entre sesiones independientes, detección de foco de ventana y perfiles visuales con audio.
+
+Dos sesiones independientes pueden sonar a la vez; la política limita cada instancia, no todos los procesos del equipo.
+
+## Criterios de aceptación y verificación
+
+- [ ] Sin archivo de configuración o con `enabled: false`, no hay audio automático, subprocesses de reproducción ni detección de backend.
+- [ ] Cada evento soportado puede configurarse independientemente por origen.
+- [ ] `agent_end` no genera éxito cuando el resultado indica fallo o cancelación.
+- [ ] Una transición duplicada produce como máximo una notificación; una ejecución nueva puede notificar de nuevo.
+- [ ] La restauración de historial y tareas no reproduce sonidos.
+- [ ] Los hijos y sesiones no interactivas nunca reproducen audio.
+- [ ] Silenciar/desactivar limpia pendientes; reanudar no genera replay.
+- [ ] Ráfagas respetan prioridad, intervalo mínimo y ausencia de solapamiento.
+- [ ] Configuración inválida, archivo ausente y reproductor fallido no bloquean ni alteran el trabajo.
+- [ ] Rutas con espacios y caracteres especiales no se interpretan como comandos.
+- [ ] La UI permite configurar, probar y silenciar; la prueba no habilita audio automático.
+- [ ] El cierre limpia procesos y listeners sin prolongar indebidamente la salida.
+- [ ] Se documentan y verifican manualmente las plataformas declaradas como soportadas.
+
+Usar tests deterministas con reloj y reproductor inyectados para política y deduplicación; tests de adaptadores para eventos reales, restauración y resultado del agente; tests de configuración y argumentos del backend. Aplicar RED/GREEN a esas conductas durante implementación. Complementar con pruebas manuales de UI, escucha y cierre por plataforma. Esta propuesta documental no requiere RED/GREEN.
+
+## Unidades de implementación propuestas
+
+1. **Contrato y política:** confirmar productores de eventos, esquema, configuración y tests de deduplicación/ráfagas.
+2. **Audio:** adaptadores, sonidos redistribuibles y tests de fallos, timeout y seguridad.
+3. **Integración:** propietario padre, eventos de agente/subagentes y pruebas de no replay/headless.
+4. **Configuración y entrega:** UI, documentación y matriz de verificación manual por plataforma.
+
+Cada unidad conservará sus tests junto al código. Estimar el diff antes de implementar y dividir la entrega si el volumen dificulta la revisión.
+
+## Próximo paso
+
+Aprobar o ajustar el alcance de v1 y la configuración global. Después, realizar una exploración técnica acotada de productores de estados y reproducción por plataforma antes de fijar el contrato e implementar.
+
+## Estado de ejecución en este worktree
+
+**Estado histórico al copiar esta propuesta: ejecución aprobada; implementación todavía no iniciada en aquel turno.**
+El estado inicial y el texto anterior se conservan como propuesta histórica, sin modificar el original de `gentle-shell`. El alcance aprobado, los contratos refinados y las seis unidades futuras se concretan en el [plan ODD](../odd/tasks/sound-notifications.md), que rige la ejecución.
+Esta entrega es solo planificación y copia: sin implementación, review, subagentes ni commits. La elección «Por unidades revisables (recomendado)» autoriza para la ejecución posterior commits LOCALES por unidad con sus tests, no push ni PR.
+
+## Estado actual SN6
+
+SN1–SN5 implementados y entregados por el parent; SN5 `c3a20d8e` (548 líneas, contexto confirmado por parent). SN6 añade el panel Notifications desde customize, validación WAV al seleccionar, consentimiento de recuperación estrictamente booleano y documentación de uso. La guía vigente es [sound-notifications.md](sound-notifications.md); el [ODD](../odd/tasks/sound-notifications.md) conserva RED/GREEN y pendientes.
+
+No se declara aceptación completa: SN6 espera commit del parent, full checks/verifier y manuales de UI, escucha, reload y quit. Linux/macOS tienen adaptadores implementados **UNVERIFIED manual listening**; Windows permanece unavailable. `session.shutdown` se excluye del catálogo runtime/UI para no demorar el cierre, aunque la propuesta histórica pedía mejor esfuerzo y el esquema conserva la clave. La sección Plataformas anterior es intención histórica, no una afirmación actual de soporte Windows ni verificación física. No hay review, commits ni subagentes en este turno de implementación.

package/docs/sound-notifications.md

@@ -0,0 +1,114 @@
+# Sound notifications
+
+Audio is **off by default**. In a primary Pi terminal, open `/gentle:customize` → **Notifications** (the card header reads **Audio notifications**) and use the controls **directly in the same two-column card**: the global switch, process mute and three independent type groups (**Success**, **Error**, **Attention**) that each own their included tone or a local WAV. Per-event exceptions stay folded behind **Advanced**. Nothing closes the overlay or opens a second menu, and audio preferences stay separate from visual settings, profiles and visual reset. No new command is needed.
+
+**Quick answer (Linux/WSLg):** on **plain Linux** the installed package prefers the native WAV backend and needs no external player; it connects to the local PulseAudio/PipeWire-Pulse Unix socket and needs a running server with a default sink. Inside **WSL** the Windows system `SoundPlayer` is preferred instead: the validated WAV snapshot is mapped to the derived `\\wsl.localhost\<distro>\...` UNC path and played by the fixed system host, so no Pulse server or RDP audio dependency is required; it does depend on the default `/mnt/c` automount and the standard `C:\Windows` root and falls back to the trusted Linux CLI before any playback otherwise. **Native Windows** WAV uses the same system `SoundPlayer` through the fixed `C:\Windows\...\powershell.exe` host. A read-only probe succeeded here, but physical audio is not claimed. OGG/FLAC always use the legacy CLI backend on Linux and WSL; native OGG/FLAC codecs are a future phase and Windows OGG/FLAC is unsupported. macOS keeps `afplay` for WAV and FLAC (own CoreAudio phase planned).
+
+## Use the direct controls
+
+- **Audio notifications: on / off** toggles the global switch. Highlighting or rendering the row never discovers a player or enables anything.
+- **Audio: unmuted / muted** toggles this process' mute. Mute survives reload and session replacement; restarting Pi clears it. Muting/disabling discards pending events; resuming never replays them.
+- **Success / Error / Attention** are the three basic types. Each shows its human selection — `success tone` / `error tone` / `attention tone`, `silence`, a local WAV basename, or `Custom (varies)` when the type's events diverge. **Enter** cycles that type between `silence → builtin:success → builtin:error → builtin:attention → silence`; on a mixed type Enter applies the recommended tone for that type. **`f`** opens an inline field to assign a literal absolute local WAV to that type, independently of the other types; the field is prefilled with the current path when the type already owns a file. **`p`** explicitly previews the type's selected sound, never an arbitrary one.
+- **Advanced: show/hide per-event exceptions** reveals the per-event rows (`agent.completed`, `context.high`, …) for one-off overrides. They start folded; expanding or collapsing only changes the card view and never writes configuration or reproduces sound. Each per-event row cycles and assigns its own WAV like a type row. **`f`** and **`p`** on any type or per-event row stay inside the same card; in Notifications `p` never opens the visual profiles pane.
+
+**Context warning.** When context usage reaches **90%** of the active model's window, Gentle warns once per high episode. The sound is the `context.high` event: turn **Audio notifications** on, expand **Advanced**, and select its sound. A file saved before `context.high` existed stays silent for it, so select a sound on that Advanced row to hear it; its recommended tone is `builtin:attention`. The visual warning is fully independent: the **Sections → Section contextWarning** row in `/gentle:customize` (shown by default) toggles it, and neither toggle changes the other. The episode rearms when usage drops below 90%, after a successful compaction, or in a new session; a canceled or failed compaction does not rearm, and the unknown reading right after a successful compaction never repeats the warning.
+
+The inline field and the recovery confirmation render inside the same card. **Escape** cancels the field or confirmation; a second Escape closes the card. If the field, value or `y yes` cannot be shown in full (a resize or a very small terminal), Enter or `y` is refused instead of acting on something invisible. Invalid/unreadable configuration disables automatic audio: saving in that state requires a fresh explicit inline confirmation to replace it, cancel preserves the file and settings, and a failed write does not grant consent to the next attempt. Diagnostics are generic local UI notices, not conversation messages, tools, model context or agent state.
+
+## Supported events and defaults
+
+| Origin | Events | Recommended sound |
+| --- | --- | --- |
+| Session | `session.started` | Silence |
+| Main agent | `agent.started`, `agent.cancelled` | Silence |
+| Main agent | `agent.completed` | `builtin:success` |
+| Main agent | `agent.failed` | `builtin:error` |
+| Main agent | `agent.attention` | `builtin:attention` |
+| Context | `context.high` | `builtin:attention` |
+| Subagent | `subagent.queued`, `subagent.running`, `subagent.waiting`, `subagent.cancelled` | Silence |
+| Subagent | `subagent.completed` | `builtin:success` |
+| Subagent | `subagent.failed`, `subagent.timed_out` | `builtin:error` |
+
+`session.started` means initial process startup only, once per process, not reload/new/resume/fork. Main outcomes use settled-run evidence; `agent_end` is not success. Attention is an active main-run edge from the existing explicit intervention lifecycle (`herdr:blocked`), not every dialog. Subagent waiting does not imply attention. Restored tasks/history and unchanged snapshots are silent. `context.high` is a local runtime signal from the context-usage probe, never a producer bus event, and fires at most once per high episode.
+
+**Shutdown limitation:** `session.shutdown` remains in the schema for compatibility but is excluded from the runtime/UI catalog. Lazy playback cannot reliably finish during immediate cleanup without delaying exit. The historical best-effort proposal is not a promise of a quit sound; shutdown cancels audio instead.
+
+## Global configuration
+
+Only `<gentlePiConfigHome()>/notifications.json` is read. It normally resolves to `~/.pi/gentle-ai/notifications.json`; `GENTLE_PI_CONFIG_HOME` overrides the directory. No repository override can activate audio. Missing configuration reads the preset with `enabled: false`, without creating a file. Saved files are strict, not merged with defaults: omitted event keys and `null` both mean silence, including after upgrades.
+
+Complete default schema (the shutdown entry is inert):
+
+```json
+{
+  "schema": "gentle-shell.notifications/v1",
+  "enabled": false,
+  "audio": {
+    "backend": "auto",
+    "minimumIntervalMs": 1000,
+    "coalesceWindowMs": 300,
+    "events": {
+      "session.started": null,
+      "session.shutdown": null,
+      "agent.started": null,
+      "agent.completed": "builtin:success",
+      "agent.failed": "builtin:error",
+      "agent.cancelled": null,
+      "agent.attention": "builtin:attention",
+      "context.high": "builtin:attention",
+      "subagent.queued": null,
+      "subagent.running": null,
+      "subagent.waiting": null,
+      "subagent.completed": "builtin:success",
+      "subagent.failed": "builtin:error",
+      "subagent.cancelled": null,
+      "subagent.timed_out": "builtin:error"
+    }
+  }
+}
+```
+
+Unknown keys/schema/events are rejected. `enabled` must be boolean; backend must be `auto`; timing values are integer milliseconds: minimum interval 0–60000, coalesce window 0–2000, inclusive. Zero disables that timing window, not the TTL. Writes use an exclusive 0600 temporary file beside the target followed by atomic rename. Changes apply to the live owner immediately and invalidate stale pending mappings. Direct external edits are read on the next session attachment/reload, not polled in the background. A file saved before `context.high` existed keeps that event silent; selecting a sound on its Advanced row is the only explicit way to enable it.
+
+## Local WAV security
+
+Builtins `success`, `error`, `attention` are original synthetic tones under the [MIT license, provenance and reproduction recipe](../assets/sounds/LICENSE.md).
+
+Enter a **literal absolute local path** in the file dialog (without the `file:` prefix). JSON references use `file:/absolute/path/my sound.wav`. Spaces and punctuation are literal; no shell interprets them. No URLs, UNC/network or device paths, relative paths, `~`, environment expansion, commands or configurable player executables. Selection and playback both validate; extension alone does not prove format.
+
+Allowed content: RIFF/WAVE integer PCM (format 1), mono or stereo, 8/16/24/32-bit, 8000–192000 Hz, nonempty aligned data, coherent chunk bounds/padding and rate metadata; maximum **2 MiB** and **10 seconds**. Compressed/float/extensible WAV is not accepted. The final source must be a readable regular file, not a symlink or FIFO. No-follow/nonblocking descriptor opening, bounded reads and WAV validation fail closed. Intermediate directories are not a sandbox against other same-user filesystem writers.
+
+Playback revalidates and snapshots the bytes in a private 0700 temporary directory with an exclusive 0600 file named for the validated format, then selects a backend **after** the format is known: native WAV first on Linux, otherwise the trusted absolute CLI with separate literal argv and `shell:false`. Source changes after selection cannot substitute unchecked playback bytes. A format no available backend supports is rejected before any snapshot or spawn. A native failure after a spawn is never retried through the CLI, so partial audio cannot duplicate. Abort/timeout kills the child/worker; the serial reservation is held until close and cleanup, not merely until kill was requested. Playback timeout is 11000 ms (native bridge + socket + owned Node): the validated 10 s duration limit plus a 1 s termination margin. OS-denied termination/cleanup cannot be guaranteed by mocks.
+
+## Noise and retention
+
+Only the primary **TUI** owner plays. Child processes, print/JSON and **all RPC**, including interactive RPC hosts, are silent. The context visual warning shares that owner guard, so it is also primary-TUI only. There is no desktop notification or BEL fallback. Two independent Pi processes can overlap; serialization is per process.
+
+Ráfagas coalesce into at most one pending candidate, in event priority order: failed/timed_out > main attention > completed > other. Changing the sound does not change event priority. Equal priority selects the latest sound but keeps the first coalesce deadline. Starts respect the minimum interval. Pending events have a **2000 ms** freshness budget (including slow discovery/validation and minimum-interval waits). That budget pauses only while another sound has actually started playing, so a long WAV does not silently discard the next candidate; it resumes with the remaining budget when playback settles. Already stale incoming events are still rejected. Waiting behind discovery that has not started playback does not pause expiry. There is still only one pending candidate, not a growing queue. Preview remains subject to context, file validation, serialization and timeout.
+
+The scheduler keeps a bounded 256-identity FIFO. The owner additionally retains the highest sequence **per producer/run** for the active parent session, across reload, preventing old wire duplicates after FIFO eviction. This map is not size-capped: it costs O(distinct runs) during a long session, is cleared when attaching a different session ID, and disappears on process exit. The actual TaskStore producer increments a store-global sequence on each status change, but current retention is still keyed per run; no producer-wide compaction is claimed here. Muted/off occurrences are consumed, not buffered.
+
+## Runtime backend selection
+
+| Format | Plain Linux | WSL (Windows interop) | Native Windows | macOS |
+| --- | --- | --- | --- | --- |
+| WAV | Native Pulse backend (preferred); trusted CLI fallback | Windows `SoundPlayer` through the derived `\\wsl.localhost\<distro>\...` UNC (preferred); trusted Linux CLI fallback | Windows `SoundPlayer` via the fixed `C:\Windows\...\powershell.exe` host | `/usr/bin/afplay` (legacy) |
+| OGG / FLAC | Legacy CLI: first of `/usr/bin/paplay`, `/usr/bin/pw-play`, `/usr/bin/aplay` that supports it | Same trusted Linux CLI | Unsupported | `afplay` supports FLAC; OGG unverified |
+
+Capabilities are aggregated, not replaced: a native WAV backend never removes the CLI OGG/FLAC capability. `availability` and `capabilities` discover only on an explicit request, never on import, render, or while audio is off. Selection is pure and IO-free (`createDefaultNotificationBackend`): `win32` and a valid WSL interop environment take the Windows adapter, every other platform keeps the local Pulse bridge, whose target is unavailable on macOS so `afplay` owns playback. On plain Linux the native backend probes the local Unix socket once per discovery and requires a default sink; when it is unavailable the CLI is used, and the probe result is cached until the owner is rebuilt. The WSL route uses only the default `/mnt/c` automount and the standard `C:\Windows` root: a non-standard mount or root, a missing `/run/WSL/*_interop` socket, or a failed read-only probe falls back to the trusted Linux CLI **before** any playback — there is deliberately no automatic Pulse fallback on WSL (a silent Pulse path is avoided) and no arbitrary binary, configurable route or route scheme. Native codecs (OGG/FLAC) are a future phase; own CoreAudio (macOS) and WASAPI (Windows) phases are planned. No system players are installed automatically and no new package dependency is added.
+
+## Platforms and manual verification
+
+Physical listening, UI, reload and quit remain **PENDING / UNVERIFIED** on every platform. The Linux/WSLg native path reached a real read-only Pulse `AUTH`/ServerInfo probe with a default sink (not a physical-listen claim); the WSL and native Windows routes use the system `SoundPlayer` for WAV and need no separate WASAPI phase, while Windows OGG/FLAC stays unsupported. macOS still uses `afplay` for WAV and FLAC while its own CoreAudio phase is planned. No physical playback or audible evidence is claimed for any route.
+
+No system dependencies are installed automatically. No usable backend produces silence plus a bounded local warning, not an agent failure. SSH and containers play on the process host, not necessarily your client; an executable may exist without a usable device/server. Automated tests use injected clocks/processes and WAV validation; they do **not** establish physical audio or manual TUI correctness.
+
+Manual acceptance remains pending for every applicable platform:
+
+- [ ] Navigate customize → Notifications in narrow/wide, regular/fullscreen terminals; cancel every inline field and confirmation. Verify Enter, `f` and `p` stay inside the same card and never open another menu.
+- [ ] Assign a valid local WAV with spaces via `f` to one type; confirm the other types keep their own sounds, preview off/muted with `p`, enable, verify live outcomes and independent mappings; verify bad files and consent cancellation preserve bytes.
+- [ ] Mute and reload/change session, then resume without replay; confirm no probe while off unless explicitly requested.
+- [ ] Quit/reload during probe, validation and active playback: no late spawn, overlap, stale write, leaked process or delayed exit.
+- [ ] Listen to builtin/custom tones and exercise missing player, failed player and hanging player on the real host.
+
+Implementation progress and automated evidence live in the [ODD task](../odd/tasks/sound-notifications.md). Full closure and manual acceptance are not inferred from the mock suite.

package/docs/yolo-mode.md

@@ -1,19 +1,19 @@
-# Session-only YOLO permission
+# YOLO permission
 
 > 🚀 **Full speed, destructive actions still ask.** YOLO lets the agent implement, commit, push and open PRs within the already authorized task without asking each time, which suits long autonomous runs. Destructive operations still require fresh confirmation.
 
-Use `/gentle:yolo enable` in the interactive primary Pi TUI to stop repeated permission questions for ordinary work **within your already authorized task**. YOLO defaults **OFF**. The active status and a separate editor widget both say **🚀 YOLO ON 🔥 — destructive confirmations remain**, even when Gentle Shell hides its status layout.
+Use `/gentle:yolo enable` in the interactive primary Pi TUI to stop repeated permission questions for ordinary work **within your already authorized task**. YOLO is **OFF** unless you select it or save YOLO as the user-global default. [Normal, Auto and global defaults](permission-modes.md) are managed separately from the live-session toggle. The active status and a separate editor widget both say **🚀 YOLO ON 🔥 — destructive confirmations remain**, even when Gentle Shell hides its status layout.
 
 | Command | Effect |
 | --- | --- |
-| `/gentle:yolo enable` | Activate for this live session and Git clone. |
-| `/gentle:yolo disable` | Revoke immediately and clear the indicators. |
+| `/gentle:yolo enable` | Select YOLO for this live session and workspace/clone. |
+| `/gentle:yolo disable` | Select Normal immediately and clear the YOLO indicators; saved defaults stay unchanged. |
 | `/gentle:yolo status` | Show the current state without activating. |
 | `/gentle:yolo` | Open a menu titled **🚀 Gentle YOLO 🔥 — full speed, destructive actions still ask (current: ON\|OFF)** with `enable`, `disable` and `status`. Cancelling changes nothing. Without an interactive menu UI it behaves like `status`. |
 
 Invalid arguments leave state unchanged.
 
-The Session command palette also includes YOLO. Activation fails closed without an identifiable Git clone, interactive TUI or live session identity. There is no YOLO environment variable, persisted configuration or model-callable activation tool.
+The Session command palette also includes YOLO. Interactive selection requires an eligible primary TUI, live session identity and identifiable workspace. Outside Git, the canonical workspace directory supplies identity. There is no model-callable activation tool. `/gentle:mode default yolo` optionally saves a trusted user-global default for new primary sessions; `/gentle:mode default normal` removes that elevated default. Neither command changes the current mode.
 
 ## Configuration menu path
 
@@ -21,15 +21,15 @@ The Session command palette also includes YOLO. Activation fails closed without
 2. Select **YOLO: OFF · session only**, immediately after the Vim enable/disable rows.
 3. Press **Enter** or **Space** to toggle the same permission as `/gentle:yolo`. The row updates to **YOLO: ON · session only**; slash changes and revocation also update an open menu.
 
-Navigation, the read-only preview and Escape never grant permission. The preview reminds you that ordinary scoped commits/push/PR are covered, destructive confirmations remain, review consent is unchanged and reload resets the grant. **UNAVAILABLE** means the live primary owner or eligible session/clone cannot be used; selecting it cannot activate YOLO.
+Navigation, the read-only preview and Escape never grant permission. The preview reminds you that ordinary scoped commits/push/PR are covered, destructive confirmations remain, review consent is unchanged and reload resets the live grant. **UNAVAILABLE** means the live primary owner or eligible session/workspace cannot be used; selecting it cannot activate YOLO.
 
-Unlike Vim, this control does not write a global/repository preference, visual profile, prompt-history preference or guardrail setting. Closing the menu removes its observers and cancels unfinished menu activation; it does not revoke an already completed activation. Reload or session replacement invalidates old menu callbacks and resets the permission.
+The live YOLO toggle does not save preferences. The separate **Default permissions** rows can save Normal, Auto or YOLO in the dedicated user-global permission store, never a repository preference or visual profile. **Session permissions** selects the current mode without changing that default. Closing the menu removes its observers and cancels unfinished menu activation; it does not revoke an already completed activation. Reload or session replacement invalidates old menu callbacks and resets the live permission.
 
 ## What activation authorizes
 
 YOLO supplies standing human permission for ordinary already-scoped implementation, checks, commits, non-force pushes and PR creation. Its active-only system instruction qualifies the default commit/push/PR confirmation clauses; it also tells the primary agent to make ordinary reversible implementation choices without needless interviews.
 
-Only a single plain `git push` can skip the shell guard's routine default confirmation. Simple remote/ref arguments and `-u`/`--set-upstream` are eligible. Compound commands, wrappers, repository-changing options and other push options conservatively retain normal guard behavior. Full command evaluation, including the recognized data-loss guards, runs first. Explicit push confirmations or blocks in either configuration layer remain restrictions, including when legacy persistent autonomy or its environment override would ignore them. YOLO never changes persistent `autonomousMode`.
+The shell guard's routine default confirmation is skipped for reversible delivery only. Every guarded segment of the command is judged on its own, so `git commit -m "..." && git push -u origin feature`, `git push && gh pr create --fill`, `git -C <dir> push origin main` and `git fetch && git rebase origin/main && git push` run without a prompt, while the other segments keep their ordinary guard (`git push && rm -rf data` still asks for the `rm`). A push segment is eligible with plain remote/ref arguments, `src:dst` refspecs with both sides present, and the options `-u`/`--set-upstream`, `-q`/`--quiet`, `-v`/`--verbose`, `--tags`, `--follow-tags`, `--no-verify` and `--porcelain`. A rebase segment is eligible with plain refs, `--onto`, `--continue`, `--abort`, `--skip` and `--autostash`; it is recoverable from the reflog. Anything that deletes or rewrites a remote ref, publishes, or runs arbitrary commands never qualifies: `--delete`/`-d`, `:branch` and `+branch` refspecs, `--mirror`, `--prune`, `--all`, every force spelling (hard-blocked), `--receive-pack`/`--exec`, `--repo`, `-o`, `sudo`, shell wrappers such as `sh -c`, interactive or `--exec` rebases, `git branch -D`, `pi remove` and `npm publish`. Full command evaluation, including the recognized data-loss guards, runs first. Explicit push or rebase confirmations or blocks in either configuration layer remain restrictions, including when legacy persistent autonomy or its environment override would ignore them. YOLO never changes persistent `autonomousMode`.
 
 ## What still requires a decision
 
@@ -42,9 +42,9 @@ Children retain only their bounded delegated scope. They cannot activate or inhe
 
 ## Lifetime and limits
 
-Permission is in memory in the extension instance, bound to the exact live SessionManager, session ID and canonical Git common-directory identity. Sibling worktrees in one clone may retain it; an unrelated clone or session identity cannot. Scope loss revokes rather than hiding permission until you return.
+Live permission is held in the extension instance, bound to the exact live SessionManager, session ID and canonical Git common-directory identity, or canonical workspace directory outside Git. Sibling worktrees in one clone may retain it; an unrelated workspace or session identity cannot. Scope loss revokes rather than hiding permission until you return.
 
-New, resumed, forked or replaced sessions, shutdown/quit, **reload** and process restart reset YOLO to OFF. Re-activate explicitly after reload. No session entry restores a grant.
+Shutdown, **reload** and session replacement revoke live grants and callbacks. New primary session instances may apply a saved global YOLO default; they never restore a grant from transcript entries. An explicit Normal selection wins over that default in the current session. To keep both this session and future sessions in Normal, use `/gentle:yolo disable` and `/gentle:mode default normal`.
 
 This is permission guidance and shell-guard defense in depth, **not a sandbox or an all-tools safety guarantee**. Detection only covers recognized command forms; scripts, custom tools and prompt injection can bypass semantic guidance. Tools and extensions retain the operating-system permissions of the process. Trusted SDK callers can invoke command handlers and supply interactive contexts; the human command path is not an OS security boundary against those callers. Use OS/container isolation and narrowly scoped credentials when you need an actual containment boundary.
 
@@ -79,6 +79,7 @@ Children receive the lightweight `child-safety.ts` entry alongside `child-contex
 ### Detection limitations
 
 - This is deterministic lexical recognition, **not** shell or SQL evaluation. Aliases, functions, dynamically assembled commands, variable/command expansion inside quoted payloads, unusual wrapper flags, complex heredocs and deeply nested wrappers can evade recognition. Simple recursive removal of a variable target is guarded, but its expanded target cannot reliably be identified as a hard-deny path.
+- Guarded-command confirmations and hard-denied patterns ignore text that only appears as an argument of a known data command (`grep`, `rg`, `cat`, `echo`, `printf`, `head`, `tail`, `jq`, `sort`, `uniq`, `wc` and similar), including the body of a real heredoc fed to one. Searching a file for a push or printing a reset command does not open a dialog. The exemption applies only when every command in the line is such a data command or an inert one (`cd`, `pwd`, `test`, `mkdir`, `touch`), optionally after plain `VAR=value` assignments or a flagless `env`. Anything else anywhere in the line keeps the full lexical match: any other command or wrapper (`sed`, `sh`, `python`, `awk`, `xargs`, `sudo`, `exec`, `at`, `./script`), command or process substitution, a `<<` that is not an unquoted heredoc, and quoting the tokenizer cannot account for. `sed` is excluded because GNU sed can execute its script.
 - Scripts, migration files, redirected SQL files, arbitrary interpreter programs (Python/Node/etc.), encoded payloads and remote execution are not inspected. Non-recursive wildcard deletion, file truncation, other database clients and nontrivial tautological SQL predicates are not comprehensively classified. A `WHERE` clause is not proof of bounded impact.
 - Only `bash` tool calls reach this data-loss boundary, including nested calls dispatched through Pi's tool-event pipeline. Direct process execution, user shell commands, MCP tools and other tools are not covered by these hooks.
 - The older primary regex safeguards remain authoritative and may be more conservative about text than the shared recognizer. Missing or explicitly overridden child extension paths remove the lightweight boundary; a valid package installation must include the safety entry.

package/extensions/ask-user-choice.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { DynamicBorder } from "@earendil-works/pi-coding-agent";
 import { Container, Input, isKeyRelease, matchesKey, Text, type KeybindingsManager, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
+import { captureChoiceAnswer } from "../lib/auto-permission-answers.ts";
 import { NativeChoiceList } from "../lib/native-choice-list.ts";
 import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
 import { isInteractiveMode, isInteractiveRpcHost } from "../lib/rpc-host.ts";
@@ -226,6 +227,7 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 		parameters: ChoiceParamsSchema,
 		executionMode: "sequential",
 		async execute(_toolCallId, params: ChoiceParams, _signal, _onUpdate, ctx) {
+			const captureAnswer = captureChoiceAnswer(ctx, _toolCallId, params, _signal);
 			if (ctx.mode !== "tui") {
 				if (!isInteractiveRpcHost(ctx.mode, process.env)) {
 					throw new Error("ask_user_choice is unavailable outside the interactive TUI");
@@ -238,6 +240,7 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 				finally {
 					pi.events.emit(ASK_USER_CHOICE_BLOCKED_EVENT, { active: false });
 				}
+				captureAnswer(rpcSelection);
 				return choiceToolResult(params, rpcSelection);
 			}
 
@@ -302,6 +305,7 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 				pi.events.emit(ASK_USER_CHOICE_BLOCKED_EVENT, { active: false });
 			}
 
+			captureAnswer(selection);
 			return choiceToolResult(params, selection);
 		},
 		renderCall(args, theme) {

package/extensions/ask-user-question.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { DynamicBorder } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { captureQuestionnaireAnswers } from "../lib/auto-permission-answers.ts";
 import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
 import { type QuestionData, type QuestionParams, QuestionParamsSchema } from "../lib/questionnaire/schema.ts";
 import {
@@ -264,11 +265,14 @@ export default function askUserQuestion(pi: ExtensionAPI): void {
 		): Promise<QuestionnaireToolResult> {
 			const error = validateQuestionnaire(params);
 			if (error) return invalidQuestionnaireResult(error);
+			const captureAnswers = captureQuestionnaireAnswers(ctx, _toolCallId, params, _signal);
 			if (ctx.mode !== "tui") {
 				if (!isInteractiveRpcHost(ctx.mode, process.env)) return unavailableResult();
 				try {
 					pi.events.emit(ASK_USER_QUESTION_BLOCKED_EVENT, { active: true });
-					return await askThroughDialogs(ctx, params);
+					const result = await askThroughDialogs(ctx, params);
+					if (!result.details.cancelled) captureAnswers(result.details.answers);
+					return result;
 				}
 				finally {
 					pi.events.emit(ASK_USER_QUESTION_BLOCKED_EVENT, { active: false });
@@ -307,6 +311,7 @@ export default function askUserQuestion(pi: ExtensionAPI): void {
 					details: { cancelled: true },
 				};
 			}
+			captureAnswers(selection.answers);
 			return {
 				content: [{ type: "text", text: answersText(selection.answers) }],
 				details: { answers: selection.answers },

package/extensions/child-context.ts

@@ -1,13 +1,22 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { filterChildSessionContextFiles, type ContextFileOptions } from "../lib/child-context-files.ts";
+import { REQUESTED_TOOLS_ENV } from "../lib/agents-runner.ts";
+import { registerCodeGraphTool } from "./codegraph-tools.ts";
 
 // gentle-shell#1587: delegated children drop the orchestrator-only gentle-ai
 // managed blocks from their context files. Gentle Agents passes this file to
 // every child with --extension because children do not load the gentle-pi
-// package in the isolated Gentle Shell home. It registers one hook and has no
-// other side effects; outside a child session it is a no-op.
+// package in the isolated Gentle Shell home. At startup it also supplies the
+// existing CodeGraph implementation only when explicitly requested and absent
+// (the full package already registers it). Outside a child session it is inert.
 export function createChildContextExtension(env: NodeJS.ProcessEnv = process.env): (pi: ExtensionAPI) => void {
 	return (pi) => {
+		const requested = (env[REQUESTED_TOOLS_ENV] ?? "").split(",").map(name => name.trim());
+		if (env.GENTLE_PI_AGENTS_CHILD === "1" && requested.includes("codegraph")) {
+			pi.on("session_start", () => {
+				if (!pi.getAllTools().some(tool => tool.name === "codegraph")) registerCodeGraphTool(pi);
+			});
+		}
 		pi.on("before_agent_start", (event) => {
 			if (env.GENTLE_PI_AGENTS_CHILD !== "1") return undefined;
 			// The filtered copies replace contextFiles on the same options object

package/extensions/child-safety.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ToolCallEventResult } from "@earendil-works/pi-coding-agent";
+import { SHELL_COMMAND_TOOLS } from "../lib/background-jobs.ts";
 import { recognizeDestructiveCommands } from "../lib/destructive-command-guard.ts";
 
 export function blockChildDestructiveCommand(command: string): ToolCallEventResult | undefined {
@@ -12,8 +13,9 @@ export function createChildSafetyExtension(env: NodeJS.ProcessEnv = process.env)
 	return (pi) => {
 		if (env.GENTLE_PI_AGENTS_CHILD !== "1") return;
 		pi.on("tool_call", (event) => {
-			if (event.toolName !== "bash" || typeof event.input.command !== "string") return undefined;
-			return blockChildDestructiveCommand(event.input.command);
+			const command = (event.input as { command?: unknown }).command;
+			if (!SHELL_COMMAND_TOOLS.has(event.toolName) || typeof command !== "string") return undefined;
+			return blockChildDestructiveCommand(command);
 		});
 	};
 }