gentle-pi 4.2.0 → 4.4.0

package/docs/voice.md

@@ -0,0 +1,259 @@
+# Optional local voice dictation
+
+Voice dictation is optional. It transcribes speech locally with NVIDIA Parakeet
+through sherpa-onnx, with no API key and no cloud inference. Everything happens
+from `/gentle:voice`; nothing described here runs at startup.
+
+## Quick path
+
+1. Run `/gentle:voice` and choose **Download voice dictation**. The
+   confirmation lists each component, its size, the destination directory,
+   the licenses and the platform limitations. Esc during the download cancels it.
+2. Run `/gentle:voice` again and choose **Start dictation**. Speak, then press
+   Enter to stop. Esc cancels at any point.
+3. The transcript is pasted into the editor draft at the cursor. It is never
+   sent automatically. Pi collapses pastes over 1,000 characters or 10 lines into
+   a `[paste #N …]` marker; the full text is retained and expanded when you submit.
+   Long transcripts are therefore not displayed as editable text in the draft.
+4. Or hold Space in the editor: push-to-talk is turned on by a successful
+   download. See [Push-to-talk](#push-to-talk-hold-space).
+
+## The command
+
+| Topic | Behavior |
+|-------|----------|
+| Menu | Built-in select and confirm dialogs. **Show status and notices** reports the target, both components, limitations and licenses. **Disable push-to-talk (hold Space)** appears while it is on; **Enable push-to-talk (hold Space)** appears only when voice is installed. |
+| Download | Only after the confirmation; runtime first, then the model. A cancelled download keeps components that already finished. |
+| Dictation | A compact overlay shows preparing, recording, transcribing. Enter stops recording; the overlay stays until the transcript is ready. |
+| Recording limit | After 2 minutes recording stops by itself, and the transcript is pasted without a key press. |
+| Insertion | The recognized text goes through Pi's editor paste pipeline, which may collapse long text into a paste marker. A blank result pastes nothing. |
+| One at a time | A second `/gentle:voice` while a download or dictation runs is refused with a notice. A Space hold during either one types spaces as usual. |
+| Cancel and shutdown | Esc, reload or session shutdown aborts the download or cancels the session. A transcript that arrives afterwards is dropped. |
+| Where it runs | Interactive TUI parent sessions only. RPC, print, JSON and delegated child sessions refuse it. No model-callable tool exists. |
+| Errors | Fixed messages with the action to take, such as installing ALSA or the Visual C++ runtime. Gentle AI never runs those installers. |
+
+The command is tested with fake dialogs, downloads and sessions only. No real
+download, native load or microphone recording has been exercised through it.
+
+## Push-to-talk (hold Space)
+
+Hold Space in the editor to record; release it to stop. The transcript is
+pasted at the cursor and never sent. Esc cancels while recording or
+transcribing. A one-line footer status shows preparing, recording and
+transcribing; no overlay opens, so the editor keeps the focus.
+
+| Topic | Behavior |
+|-------|----------|
+| Toggle | Stored as `voice-settings.json` (`gentle-pi.voice-settings/v1`) in the Gentle AI config home. A successful download turns it on; the `/gentle:voice` menu turns it off and on, effective immediately. A missing or malformed file means off. |
+| When it is armed | Only with the toggle on, in an interactive TUI parent session. Delegated child sessions, RPC, print and JSON modes never arm it. Reload or shutdown disarms it and cancels a running dictation. |
+| Startup | Reads the toggle file only. No voice files are checked, nothing is downloaded or loaded, and no worker starts. |
+| First hold | Checks that the runtime and model are installed; the spaces keep typing meanwhile. If voice is not installed, a notice points to `/gentle:voice` and push-to-talk stays off for the session; the saved choice is kept. |
+| One at a time | A hold while a download or dictation runs types spaces normally. |
+
+### How a hold is recognized
+
+With Pi's keyboard mode, terminals report Space as plain text and never report
+its release, so push-to-talk relies on the operating system's key auto-repeat.
+Pi lets an extension drop or replace a key as it arrives, but not type one
+later, so every space reaches the editor unchanged:
+
+- **Typing:** a tap, several spaces, an indent or Space then a letter are
+  typed exactly as without push-to-talk, with no delay.
+- **Hold:** auto-repeat has a long initial delay followed by short, regular
+  repeats; typing does not. A hold needs a first gap of 180 to 1000 ms (macOS
+  allows at least about 225 ms, X11 defaults to 660 ms), then three repeats
+  each at most 250 ms apart and regular (the slowest at most 1.6 times the
+  fastest), with the first gap at least 1.5 times the slowest repeat. Each
+  space must have added exactly one space to the draft. The following repeats
+  are turned into Backspace, through the editor's normal key path, until the
+  spaces the hold typed are removed; when the hold followed a word, one space
+  stays as the separator before the transcript. Later repeats are dropped.
+  While recording starts, those spaces can be seen briefly.
+- **Release:** no repeat for 2.5 times the observed repeat interval, between
+  150 and 400 ms. The decision waits until input already queued is handled, so
+  a repeat delayed by a busy moment is not taken for a release.
+- **Guards:** only single-space input counts. Pastes, escape sequences and
+  multi-character input pass through and end the attempt. If the draft changes
+  in any other way, for example Vim NORMAL mode where Space only moves the
+  cursor, autocomplete, or another key, the hold is not confirmed, or erasing
+  stops, and nothing else is removed. Spaces that were in the draft before the
+  hold are never removed.
+
+Limitations: the timing depends on the keyboard repeat settings. An initial
+repeat delay under 180 ms or over 1000 ms, or a repeat interval over 250 ms,
+prevents a hold from being recognized. Five or more spaces typed with a pause
+and then a very even fast rhythm could still look like a hold. Whether a space
+precedes the hold is judged as if typing at the end of the draft; in the
+middle of existing spaces the separator may be missing. Esc pressed while
+repeats are still arriving, and a release right as the hold is confirmed, can
+leave a stray space. Recording starts once the hold is confirmed and the
+microphone is open; the model is verified while you speak (see below). A hold
+while a dialog or overlay has the focus does not change the draft and is
+ignored. Push-to-talk is tested with fake terminals, editors and sessions
+only.
+
+## What gets downloaded
+
+All versions, sizes and digests are pinned in `lib/voice-artifacts.ts`.
+
+| Component | Source | Size | Verified by |
+|-----------|--------|------|-------------|
+| `sherpa-onnx-node@1.13.8` | npm registry | 12 KB | `dist.integrity` (SHA-512) |
+| `sherpa-onnx-<platform>-<arch>@1.13.8` | npm registry | 9–14 MB | `dist.integrity` (SHA-512) |
+| `node-cpal@1.0.0` (microphone capture) | npm registry | 7.7 MB | `dist.integrity` (SHA-512) |
+| Parakeet TDT 0.6B v3, int8 | Hugging Face, commit `2bda32ec70b0` | about 670 MB | per-file size and SHA-256 |
+
+The model is the sherpa-onnx export
+`csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8`: `encoder.int8.onnx`,
+`decoder.int8.onnx`, `joiner.int8.onnx` and `tokens.txt`.
+
+## Where it is stored
+
+Everything lives in `<Gentle AI config home>/voice` (by default
+`~/.pi/gentle-ai/voice`; see `gentlePiConfigHome()`):
+
+```text
+voice/
+  runtime/sherpa-onnx-1.13.8-node-cpal-1.0.0-<target>/node_modules/
+    sherpa-onnx-node/
+    sherpa-onnx-<platform>-<arch>/
+    node-cpal/
+  models/parakeet-tdt-0.6b-v3-int8-2bda32ec70b0/
+```
+
+The platform package sits next to `sherpa-onnx-node` because its loader resolves
+`../sherpa-onnx-<platform>-<arch>/sherpa-onnx.node`. node-cpal loads
+`bin/<platform>-<arch>/index.node` from its own directory. The runtime directory
+names both native versions, so a runtime installed with other pins is never
+reported as the current one.
+
+## How an install stays safe
+
+- **Explicit only.** Importing the voice modules performs no filesystem or
+  network access. Status checks never create the voice directory.
+- **Streamed and bounded.** Each file is hashed while it streams to disk and is
+  cut off as soon as it exceeds its pinned size. A wrong length or digest fails
+  the install.
+- **Pinned redirects.** npm tarballs are fetched without redirects. Hugging Face
+  redirects are followed only over HTTPS to the paths observed for this revision:
+  `huggingface.co/api/resolve-cache/...` and `us.aws.cdn.hf.co/xet-bridge-us/...`.
+  Any other host, including other CDN regions, is refused.
+- **Cancellable and time-bounded.** An install can be aborted. It also stops
+  when no data arrives for 60 seconds, or when it runs past 20 minutes for the
+  runtime or 2 hours for the model.
+- **Checked archives.** Every tarball is validated before anything is
+  extracted. Only regular files under `package/` are accepted, within the
+  registry's file count and unpacked size. Links, directories, traversal,
+  duplicates and Windows device names are refused. No package script runs, and
+  no downloaded code is loaded during installation.
+- **Atomic publication.** Work happens in a private `.staging-*` directory. The
+  install marker is written last, and one rename publishes the component. A
+  failure or cancellation removes only that staging directory. An existing
+  installation is never partially overwritten: a valid one is kept as is, and an
+  invalid one is replaced only by a complete, verified copy.
+
+## Dictation session
+
+`lib/voice-session.ts` records one dictation and returns its text. It never
+submits the text or touches the editor; the caller decides what to do with it.
+
+- **Separate process.** `start()` runs `scripts/voice-worker.cjs` with the same
+  Node executable, from the runtime directory, with no shell. Microphone
+  capture, the model load and the decode all happen in that process, so a
+  native crash or a long decode cannot freeze Gentle AI. Importing the module or
+  creating a session does nothing until `start()`.
+- **Checked before loading.** `start()` first requires both components to be
+  reported installed. The worker then checks the files again before it loads
+  the native code that uses them: every entry in the runtime and model
+  directories must be a plain directory or regular file, owned by the current
+  user and not writable by everyone (ownership and modes are not checked on
+  Windows). Each required runtime file must be present, and each model file
+  must match its pinned size and SHA-256. The digests are recomputed on every
+  session, which reads the whole model (about 670 MB). Directories above the
+  voice home are not checked. These checks catch broken or swapped installs;
+  they cannot stop someone with the same user account from replacing the files,
+  which is the same as running code as that user.
+- **Order.** So that the first words are recorded, the worker validates the
+  runtime files, loads node-cpal and opens the microphone, then reports
+  `recording` and verifies the model digests while recording, reading each
+  file in chunks so capture keeps running. sherpa-onnx and the model are loaded
+  only after every digest matched and recording stopped, because that load is
+  synchronous and would stall capture. A mismatch found while recording closes
+  the microphone at once and reports the model as invalid; one found after stop
+  is reported instead of a transcript. Cancel stops the verification and loads
+  nothing. The tradeoff: the recognizer load (about 0.85 seconds measured on an
+  Apple Silicon Mac) now happens after stop, so a transcript takes that much
+  longer to arrive, and any verification still running when you stop is
+  awaited too.
+- **Lifecycle.** A session is used once: `start()` resolves when recording
+  begins, `stop()` resolves with `{ text, truncated }`, and `cancel()` (or
+  `dispose()`) discards everything, including a transcript that arrives late.
+  `start()` resolves while the worker keeps recording; `stop()`, `cancel()` and
+  a failed `start()` settle only after the worker has exited. A worker that does
+  not exit within 2 seconds of finishing or being cancelled is killed. If the parent
+  disappears, the worker sees its input close and stops capturing.
+- **Bounds.** Recording stops by itself after 120 seconds, and the worker then
+  transcribes what it has (`truncated: true`). Starting (runtime checks and
+  opening the microphone) and transcribing (the rest of the model
+  verification, the model load and the decode) each have a 120-second limit. Audio is kept in memory
+  only up to the recording limit. All of these are options.
+- **Audio.** The worker opens the default input device through node-cpal,
+  preferring 32-bit float samples and otherwise using the device's default
+  integer or float format. It mixes all channels down to mono and resamples to
+  16 kHz in JavaScript (averaging when downsampling, linear interpolation when
+  upsampling). No SoX or FFmpeg is used. Less than 0.1 seconds of audio is
+  reported as empty, and a blank transcript as no speech.
+- **Errors.** The worker reports a fixed code only, and the session turns it
+  into a fixed message. Native error text, file paths and environment values
+  are never included, and the worker's stderr is discarded.
+- **Environment.** The worker gets only home, temp, locale and audio-session
+  variables (`HOME`, `USERPROFILE`, `SystemRoot`, `windir`, `TEMP`, `TMP`,
+  `TMPDIR`, `XDG_RUNTIME_DIR`, `PULSE_SERVER`, `PULSE_COOKIE`, `LANG`, `LC_ALL`,
+  `LC_CTYPE`). Credentials, `PATH`, `NODE_OPTIONS` and loader variables are
+  dropped.
+- **Protocol.** JSON lines with schema `gentle.voice/v1`. The parent sends
+  `start` (with paths computed from the pinned manifests), then `stop` or
+  `cancel`. The worker answers `recording`, `transcribing`, and one final
+  `result` or `error`. Any other message, an unknown field, more than 16 lines
+  or a line over 64 KB stops the worker.
+
+The session has been tested only with scripted fake workers and with the real
+worker driving fake capture and recognizer modules. It has not loaded the real
+native modules, opened a real microphone or transcribed real speech.
+
+## Platform support
+
+All five targets get the pinned runtime and a `node-cpal@1.0.0` capture binary
+built for their architecture (checked from the binary headers, not by loading).
+
+| Target | Prerequisites (not checked before loading) |
+|--------|--------------------------------------------|
+| macOS arm64 | macOS 11 or newer |
+| macOS x64 | macOS 10.12 or newer |
+| Linux x64, glibc 2.34+ | ALSA `libasound.so.2` |
+| Linux arm64, glibc 2.34+ | ALSA `libasound.so.2` |
+| Windows x64 | Microsoft Visual C++ runtime (`vcruntime140.dll`) |
+
+node-cpal requires Node 22 or newer, and a dictation session refuses to start
+on an older Node. Gentle AI never downloads or installs the Visual C++ runtime;
+a missing runtime is expected to surface as a runtime load failure, which has
+not been observed on hardware. `/gentle:voice` then names the runtime to install.
+
+None of these targets has been verified on real hardware yet: native loading,
+library paths and microphone capture have not been executed. Linux with a glibc
+older than 2.34 is unsupported and the diagnosis names the version found.
+Windows ARM64 has no native sherpa-onnx package and is unsupported. musl Linux
+is unsupported. WSL is reported as unproven.
+
+## Licenses and attribution
+
+- **Model:** Parakeet TDT 0.6B v3 by NVIDIA, licensed under CC-BY-4.0. The int8
+  sherpa-onnx export is by csukuangfj. The export repository has no license file
+  of its own; its license is taken from the upstream NVIDIA model.
+- **Runtime:** sherpa-onnx, Apache-2.0. The npm tarballs ship no LICENSE or
+  NOTICE file. The platform packages bundle onnxruntime (MIT) without its
+  license text.
+- **Capture:** node-cpal 1.0.0, ISC. The tarball ships no LICENSE or NOTICE file. Its prebuilt
+  binaries link Rust crates whose notices are not included.
+
+These gaps are unresolved and are listed in `VOICE_NOTICES`.

package/docs/yolo-mode.md

@@ -1,6 +1,6 @@
 # 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.
+> 🚀 **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; the one exception is recursive removal of the session's own temp scratch (see [Temp scratch removal](#temp-scratch-removal)).
 
 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.
 
@@ -9,12 +9,27 @@ Use `/gentle:yolo enable` in the interactive primary Pi TUI to stop repeated per
 | `/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`. |
+| `/gentle:yolo` | Open a menu titled **🚀 Gentle YOLO 🔥 — standing permission (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. 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.
 
+## Super Yolo
+
+**💥 Super Yolo removes every permission prompt; the only line left is private material.** Select it with `/gentle:mode super-yolo` or save it for new sessions with `/gentle:mode default super-yolo`.
+
+While it is active:
+
+- Every shell-guard confirmation is waived, data loss included: recursive `rm`, SQL drops, ordinary pushes, rebases, forced branch deletion, `npm publish` and configured guardrail `confirm`/`block` rules all run without dialogs. Code-level hard denies stay blocked (`git reset --hard`, forced clean, force push); see below.
+- The Auto classifier does not run.
+- The **sensitive-path guard stays hard-blocked**: `read`, `write` and `edit` of `.env` files, `.ssh`, keychains, `*.pem/*.key/*.p12/*.pfx`, `secrets/` directories and cloud credential files are refused in every mode, Super Yolo included.
+- Code-level catastrophic denies remain: `rm -rf /`, `rm -rf ~`, `--no-preserve-root`, `git reset --hard`, forced clean and force push are blocked without a dialog.
+- `ask_user` tools, provider consent, maintenance/recovery authorization and opaque-token decisions are never automatically answered.
+- The `/gentle:yolo` toggle shows **ON** while Super Yolo is active and turning it off returns to Normal. Children never inherit Super Yolo; their bounded delegation and child guards are unchanged.
+
+Super Yolo is deliberate maximum autonomy for a workspace you accept the consequences of. The shell recognition remains lexical, not a sandbox: unrecognized script forms, custom tools and prompt injection can still reach destructive effects, and OS-level isolation remains your real containment boundary.
+
 ## Configuration menu path
 
 1. Open `/gentle:customize` → **Editor**.
@@ -23,23 +38,35 @@ The Session command palette also includes YOLO. Interactive selection requires a
 
 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.
 
-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.
+The live YOLO toggle does not save preferences. The separate **Default permissions** rows can save Normal, Auto, YOLO or Super 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.
 
-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`.
+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. Either segment may also carry output redirections that write nothing (`2>&1`, `>&2`, `>/dev/null`, `2>/dev/null`, `&>/dev/null`) and may be piped into the read-only filters `tail`, `head`, `cat`, `grep` and `wc` with plain or literally quoted arguments, so `git push -u origin feature 2>&1 | tail -5` runs without a prompt. Redirection to a file, a pipe into any other command (`| sh`, `| tee file`, `| xargs`) and a trailing background `&` still ask: Git output carries text the remote controls. 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
 
-- Destructive operations retain fresh confirmations or hard denial: recognized SQL DROP/TRUNCATE and broad deletion, recursive removal, destructive Git and other guarded operations are not waived. Explicit configured confirmations/blocks and sensitive-path protection remain.
+- Destructive operations retain fresh confirmations or hard denial: recognized SQL DROP/TRUNCATE and broad deletion, recursive removal, destructive Git and other guarded operations are not waived. The only exception is [temp scratch removal](#temp-scratch-removal). Explicit configured confirmations/blocks and sensitive-path protection remain.
 - Current explicit human restrictions, repository policy, project trust and authorized scope still apply. Scope expansion, privacy-sensitive disclosure and genuinely unresolved consequential product choices require a human decision.
 - Ambiguous destinations or credentials remain unresolved. YOLO does not invent a remote, deployment destination, account or credential, nor authorize discovery or reuse of ambient credentials.
 - `ask_user` tools, provider consent, maintenance/recovery authorization and opaque-token choices are never automatically answered. Native review, RDD and review standing permission remain separate and unchanged.
 
 Children retain only their bounded delegated scope. They cannot activate or inherit YOLO, and receive no independent delivery permission.
 
+### Temp scratch removal
+
+In the primary session with YOLO active, a recursive `rm` whose every target is the session's own temp scratch runs without the data-loss confirmation. For example, `rm -rf /tmp/tmp.8phya1BpFr /tmp/build.log; git log --oneline -1` runs directly when both targets qualify. A target qualifies only when all of these hold:
+
+- The segment is a plain `rm` with no wrapper (`sudo`, `env`, `xargs`, assignments), not inside `sh -c` or `find -exec`, and without `--no-preserve-root`.
+- The removal runs before anything else in the command. The command must start with one or more such `rm` segments joined by `;`, `&&`, `||` or newlines. Nothing may precede them: no `mv`, `cp`, `ln`, redirection, subshell or other command. They also may not be backgrounded with `&` or piped with `|`. Otherwise an earlier step could put other data into a target that looked like scratch when the command was checked, so `mv ~/data /tmp/tmp.abcdef1234 && rm -rf /tmp/tmp.abcdef1234` still asks. Commands after the removals, such as `cd … && git log`, are allowed.
+- The target is an unquoted literal absolute path made only of letters, digits, `/` and `._-+@%=:,`. It has no `$`, backtick, `~`, glob, brace or redirection characters, no `.`/`..` components and no trailing `/`.
+- The target is exactly one path component under `/tmp`, `/var/tmp` or the resolved `os.tmpdir()`. The temp root itself never qualifies, and a temp root that is `/`, your home directory, one of its ancestors or a directory inside your home is ignored.
+- When the command is checked, the target is missing, a symlink, a regular file you own, or a directory you own named like `mktemp` output (`tmp.` followed by six or more letters or digits).
+
+Anything else keeps asking, including another user's directory, a directory not named like `mktemp` output, an unreadable path and `$TMPDIR/...`. Every other effect in the same command keeps its ordinary guard: `rm -rf /tmp/tmp.abcdef1234 && rm -rf data` still asks, and `rm -rf /tmp/tmp.abcdef1234 ~/foo` is still hard-blocked. Normal and Auto modes still ask, and children still block. The check runs when the command is admitted; it does not lock the path until `rm` runs.
+
 ## Lifetime and limits
 
 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.
@@ -50,7 +77,7 @@ This is permission guidance and shell-guard defense in depth, **not a sandbox or
 
 ## Recognized data-loss boundary
 
-Recognized destructive database and broad filesystem commands require **fresh primary confirmation** and are **blocked in package-owned children**, independently of YOLO and existing autonomous-mode configuration.
+Recognized destructive database and broad filesystem commands require **fresh primary confirmation** and are **blocked in package-owned children**, independently of YOLO and existing autonomous-mode configuration. The only YOLO exception is [temp scratch removal](#temp-scratch-removal).
 
 | Recognized executable form | Primary session | Delegated child |
 |---|---|---|
@@ -58,12 +85,13 @@ Recognized destructive database and broad filesystem commands require **fresh pr
 | SQL `DELETE FROM` without `WHERE`, or a trailing literal `WHERE 1=1` / `WHERE TRUE` | Fresh confirmation | Block |
 | Recursive `rm` (`-r`, `-R`, combined short flags, `--recursive`), `find -delete`, recognized destructive `find -exec/-execdir` and `xargs` invocations | Fresh confirmation | Block |
 | Recursive `rm` targeting `/`, `/*`, `.`, `..`, home or home descendants | Hard block | Block |
+| Temp scratch recursive removal ([conditions](#temp-scratch-removal)) | Waived under YOLO (primary only); fresh confirmation otherwise | Block |
 | Git force push, hard reset, forced clean | Hard block | Block |
 | Git forced branch deletion, reset/clean/restore/rebase, checkout with `--` or force, stash drop/clear | Existing primary policy remains | Block |
 
 SQL recognition is limited to literal arguments passed to `psql`, `mysql`, `mariadb`, or `sqlite3`, literal `echo`/`printf` pipelines into those clients, and simple named heredocs. SQL string literals and comments are excluded from the new SQL recognition; printing or searching destructive prose alone does not trigger it.
 
-Command recognition follows simple shell separators, pipelines and parenthesized command groups. It handles executable paths, leading assignments, common `env`, `sudo`, `command`, `exec`, `nohup`, `timeout` and `xargs` wrappers, and literal `sh/bash/zsh/dash -c` payloads (up to five recognition levels). Every recognized operation in a compound command participates; an earlier allowed delivery action cannot hide later data loss.
+Command recognition follows simple shell separators, pipelines and parenthesized command groups. It handles executable paths, leading assignments, common `env`, `sudo`, `command`, `exec`, `nohup`, `timeout` and `xargs` wrappers, and literal `sh/bash/zsh/dash -c` payloads (up to five recognition levels). A command after the unquoted reserved words `then`, `else`, `elif`, `do`, `{`, `!`, `if`, `while` and `until` is recognized like a command at the start of a segment, so `if true; then rm -rf data; fi` and `for d in a b; do rm -rf "$d"; done` are guarded like `rm -rf data`, and a root or home target behind them is still hard-blocked. Backtick substitutions outside single quotes (also inside double quotes) and literal `eval` payloads, quoted or bare words, are recognized like literal `sh -c` payloads within the same recognition levels; `eval "$x"` and other expanded payloads are not resolved. A recursive `rm` behind a reserved word, in backticks or in `eval` never qualifies for [temp scratch removal](#temp-scratch-removal). Every recognized operation in a compound command participates; an earlier allowed delivery action cannot hide later data loss.
 
 Ordinary builds, tests, read-only SQL, predicate-bounded literal deletes, Git status/log and plain pushes are unchanged by the shared data-loss classifier. A build command that explicitly includes recursive deletion is still guarded.
 
@@ -71,15 +99,15 @@ Ordinary builds, tests, read-only SQL, predicate-bounded literal deletes, Git st
 
 1. Existing hard denies and newly recognized hard-deny forms win across the command.
 2. Explicit configured blocks retain their existing semantics and win before data-loss confirmation. Active YOLO additionally honors explicit push restrictions in either configuration layer.
-3. Recognized database/filesystem data loss always requires fresh confirmation, even when autonomous mode or a matched delivery action is configured to allow.
+3. Recognized database/filesystem data loss always requires fresh confirmation, even when autonomous mode or a matched delivery action is configured to allow. The only exception is [temp scratch removal](#temp-scratch-removal) under active YOLO in the primary session.
 4. No UI, cancellation, a non-true answer or a dialog error cannot authorize execution. Approval is not cached; permission and Herdr blocker lifecycle events remain balanced.
 
 Children receive the lightweight `child-safety.ts` entry alongside `child-context.ts`; they do not need the full primary extension. The safety entry registers nothing outside `GENTLE_PI_AGENTS_CHILD=1`, preventing duplicate primary prompts during package auto-discovery. If the full primary extension is explicitly loaded in a child, its destructive-command path also blocks instead of prompting.
 
 ### 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.
+- This is deterministic lexical recognition, **not** shell or SQL evaluation. Aliases, functions, other reserved words (`time`, `function`, `coproc`), commands inside double-quoted `$(...)`, 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`. Plain assignment segments (`f=x;`) and simple command substitutions whose body is itself only data or inert commands (`f=$(ls -t *.jsonl | head -40); grep -l "git push" $f`) keep the exemption. 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`), a command substitution that runs anything else or nests quotes, expansions or another substitution, a command substitution together with a heredoc, process substitution, backticks, 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

@@ -326,7 +326,10 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 			if (details?.selection) {
 				return new Text(theme.fg("success", `✓ ${details.selection.index}. ${details.selection.label}`), 0, 0);
 			}
-			if (details?.customResponse !== undefined) return new Text(theme.fg("success", "✓ Custom response"), 0, 0);
+			if (details?.customResponse !== undefined) {
+				const text = details.customResponse.trim();
+				return new Text(theme.fg("success", text ? `✓ Custom response — ${details.customResponse}` : "✓ Custom response"), 0, 0);
+			}
 			return new Text(theme.fg("warning", "Cancelled"), 0, 0);
 		},
 	});

package/extensions/codegraph-tools.ts

@@ -1,7 +1,7 @@
 import { execFile, execFileSync } from "node:child_process";
-import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
@@ -38,11 +38,18 @@ export interface CodeGraphRunOptions {
 	maxBuffer: number;
 }
 
+interface CodeGraphLocalExclude {
+	status: "added" | "present" | "failed";
+	path?: string;
+	reason?: string;
+}
+
 interface CodeGraphFallbackDetails {
 	status: CodeGraphStatus;
 	operation: CodeGraphOperation;
 	cwd: string;
 	fallback: string;
+	localExclude?: CodeGraphLocalExclude;
 }
 
 export type CodeGraphRunner = (
@@ -109,6 +116,55 @@ function assertSafeIndexDirectory(cwd: string): void {
 	}
 }
 
+function indexExists(cwd: string): boolean {
+	try {
+		return lstatSync(join(cwd, ".codegraph")).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function gitOutput(cwd: string, args: readonly string[]): string {
+	return execFileSync("git", [...args], {
+		cwd,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+		windowsHide: true,
+	}).trim();
+}
+
+// CodeGraph writes .codegraph/.gitignore with `*` and `!.gitignore`, so that file
+// stays untracked and enters every diff. Keep the whole index out of git through
+// the worktree's local exclude file; tracked files and .gitignore are never edited.
+const LOCAL_EXCLUDE_PATTERN = ".codegraph/";
+const EQUIVALENT_EXCLUDE_PATTERNS = new Set([".codegraph", ".codegraph/", "/.codegraph", "/.codegraph/"]);
+
+function excludeIndexLocally(cwd: string): CodeGraphLocalExclude | undefined {
+	let path: string | undefined;
+	try {
+		if (gitOutput(cwd, ["rev-parse", "--is-inside-work-tree"]) !== "true") return undefined;
+		// --git-path resolves the exclude file a linked worktree actually reads.
+		path = resolve(cwd, gitOutput(cwd, ["rev-parse", "--git-path", "info/exclude"]));
+		const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+		mkdirSync(dirname(path), { recursive: true });
+		path = join(realpathSync(dirname(path)), basename(path));
+		if (current.split(/\r?\n/).some((line) => EQUIVALENT_EXCLUDE_PATTERNS.has(line.trim()))) {
+			return { status: "present", path };
+		}
+		const separator = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+		appendFileSync(path, `${separator}${LOCAL_EXCLUDE_PATTERN}\n`);
+		return { status: "added", path };
+	} catch (error: unknown) {
+		const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
+		return { status: "failed", ...(path ? { path } : {}), reason };
+	}
+}
+
+function withLocalExcludeNote(text: string, localExclude: CodeGraphLocalExclude | undefined): string {
+	if (localExclude?.status !== "failed") return text;
+	return `${text}\n\n.codegraph/ is not excluded from git locally (${localExclude.reason}). Keep .codegraph/ out of the change.`;
+}
+
 function resolveLimit(limit: number | undefined): number {
 	if (limit === undefined) return DEFAULT_LIMIT;
 	if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
@@ -304,7 +360,7 @@ export function createCodeGraphTool(
 			signal: AbortSignal | undefined,
 			_onUpdate: undefined,
 			ctx: ExtensionContext,
-		): Promise<{ content: { type: "text"; text: string }[]; details: { operation: CodeGraphOperation; cwd: string; args: string[] } | CodeGraphFallbackDetails }> {
+		): Promise<{ content: { type: "text"; text: string }[]; details: { operation: CodeGraphOperation; cwd: string; args: string[]; localExclude?: CodeGraphLocalExclude } | CodeGraphFallbackDetails }> {
 			const cwd = resolveWorkspaceCwd(ctx.cwd);
 			assertSafeIndexDirectory(cwd);
 			const args = commandArguments(parameters, cwd);
@@ -313,18 +369,24 @@ export function createCodeGraphTool(
 			try {
 				const result = await runner(args, { cwd, signal: runSignal, maxBuffer: PROCESS_MAX_BUFFER });
 				const output = truncateOutput([result.stdout, result.stderr].filter(Boolean).join("\n"));
+				const localExclude = parameters.operation === CODEGRAPH_OPERATION.INIT || indexExists(cwd)
+					? excludeIndexLocally(cwd)
+					: undefined;
 				return {
-					content: [{ type: "text" as const, text: output || "CodeGraph completed without output." }],
-					details: { operation: parameters.operation, cwd, args },
+					content: [{ type: "text" as const, text: withLocalExcludeNote(output || "CodeGraph completed without output.", localExclude) }],
+					details: { operation: parameters.operation, cwd, args, ...(localExclude ? { localExclude } : {}) },
 				};
 			} catch (error: unknown) {
 				const details = codeGraphFailureDetails(error, parameters.operation, cwd);
+				// A failed init can still leave a partial index behind.
+				const localExclude = indexExists(cwd) ? excludeIndexLocally(cwd) : undefined;
+				if (localExclude) details.localExclude = localExclude;
 				const timedOut = timeout?.aborted === true && signal?.aborted !== true;
 				const text = timedOut
 					? `CodeGraph timed out after ${queryTimeoutMs} ms (a slow filesystem such as a WSL /mnt mount, or a very large workspace). ${FALLBACK_INSTRUCTIONS}`
 					: codeGraphFailureMessage(details.status);
 				return {
-					content: [{ type: "text" as const, text }],
+					content: [{ type: "text" as const, text: withLocalExcludeNote(text, localExclude) }],
 					details,
 				};
 			}