From f49b621d2f69fb9828aaf2b6f49ee10bdd210752 Mon Sep 17 00:00:00 2001
From: Christopher Sardegna <github@reagentx.net>
Date: Tue, 28 Jul 2026 15:29:44 -0700
Subject: [PATCH 1/7] docs: update README and sessions documentation for
 clarity and security details

---
 docs/README.md   | 6 +++---
 docs/sessions.md | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index b86fd45..b7e6ae2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -29,7 +29,7 @@ Runtime state contains the daemon socket and lock. Configuration contains durabl
 
 ### Runtime directory (socket + lock)
 
-The runtime directory holds `default.sock`, the mode-`0600` client↔daemon socket, and `daemon.lock`, the single-instance `flock`. The daemon records its PID in the lock file; `--kill` uses that PID rather than waiting for the socket. `fleetcom` creates the directory with mode `0700`. An existing path must be a real directory owned by the current user, so symlinks and directories owned by another user are rejected.
+The runtime directory holds `default.sock`, the client↔daemon socket; `daemon.lock`, the single-instance `flock`; and `daemon.log`, the stderr of an autostarted daemon. The daemon records its PID in the lock file; `--kill` uses that PID rather than waiting for the socket. [Security](#security) documents the permissions and the ownership checks this directory must satisfy.
 
 Resolved in this order:
 
@@ -51,7 +51,7 @@ Holds saved sessions under a `sessions/` subdirectory: one sanitized-name `.json
 | 2 | Linux | `${XDG_CONFIG_HOME:-~/.config}/fleetcom/sessions` |
 | 2 | macOS | `~/Library/Application Support/fleetcom/sessions` |
 
-The platform default is [`dirs::config_dir()`](https://docs.rs/dirs/latest/dirs/fn.config_dir.html) joined with `fleetcom`. The first save creates missing session directories with mode `0700`; recipe files use mode `0600`.
+The platform default is [`dirs::config_dir()`](https://docs.rs/dirs/latest/dirs/fn.config_dir.html) joined with `fleetcom`. The first save creates any missing session directories.
 
 ## First-run walkthrough
 
@@ -187,7 +187,7 @@ Because the daemon holds each PTY master, daemon termination closes the terminal
 
 ### Environment and directory
 
-Each launch uses the launching client's environment and working directory, sent once per connection during the hello handshake. Connect from a venv terminal and your spawns, reruns, and session loads all see that venv, whichever client originally autostarted the daemon. Environment is never written to disk; session files store only directories, commands, group assignments, and display names.
+Each launch uses the launching client's environment and working directory, sent once per connection during the hello handshake. Connect from a venv terminal and your spawns, reruns, and session loads all see that venv, whichever client originally autostarted the daemon. [Security](#security) covers what that context does and does not persist.
 
 ### Scrollback depth is fixed per supervisor
 
diff --git a/docs/sessions.md b/docs/sessions.md
index 6d8f4a4..6fa467d 100644
--- a/docs/sessions.md
+++ b/docs/sessions.md
@@ -45,7 +45,7 @@ The `version` field must be an integer from 1 through the newest format supporte
 
 The shape, not the version, discriminates the schema. An object-valued `dirs` marks the wrapped form shown above. The loader also accepts a flat map whose top-level keys are directories and whose values are entry arrays. In that form, an array-valued key named `dirs` remains a directory entry, but a top-level `version` member is always the format version, never a directory. Flat-map files list by filename stem because they have no stored name. Saving one writes the wrapped form and permits overwriting it without a stored-name collision check.
 
-Saves are atomic: `fleetcom` writes and syncs a private temporary file in the session directory, then renames it over the recipe. Recipes persist full command lines, which can embed secrets. New session directories use mode 0700, saves remove group and other permissions from existing session directories, and recipe files use mode 0600.
+Saves are atomic: `fleetcom` writes and syncs a private temporary file in the session directory, then renames it over the recipe. Recipes persist full command lines, which can embed secrets. [Security](README.md#security) documents the directory and file permissions.
 
 The file is plain JSON and practical to edit by hand. Editing the `name` field changes which session the file claims to be: collision checks compare it, so a save under the old name will be refused. On load, the daemon removes control characters, trims surrounding whitespace, and limits group and display names to 64 characters. `Unassigned` maps to no group but remains a legal display name. Invalid JSON fails the entire load. Within valid JSON, `fleetcom` drops any member that matches neither entry form, including a non-string scalar, an object without a string `cmd`, or an object with a non-string `group` or `name`.
 
@@ -79,7 +79,7 @@ A snapshot uses the session format above, with an `autosaved <timestamp>` UTC la
 
 In the dashboard, `o` opens the [session picker](commands.md#the-o-session-picker) on the saved list; while snapshots exist, `Tab` flips it to the recovery list.
 
-Recovery files carry the same caveat as saved recipes: they persist full command lines, which can embed secrets. New recovery directories use mode 0700, and snapshot files use mode 0600.
+Recovery files carry the same caveat as saved recipes: they persist full command lines, which can embed secrets.
 
 ## Saving and loading
 

From 06fbe97919d5e7a6eb6e91111cd1cad65a29701b Mon Sep 17 00:00:00 2001
From: Christopher Sardegna <github@reagentx.net>
Date: Tue, 28 Jul 2026 15:32:58 -0700
Subject: [PATCH 2/7] refactor: enhance scratch directory management and PID
 handling in tests

---
 src/testutil.rs | 74 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 71 insertions(+), 3 deletions(-)

diff --git a/src/testutil.rs b/src/testutil.rs
index 4d1f399..21caa06 100644
--- a/src/testutil.rs
+++ b/src/testutil.rs
@@ -8,20 +8,88 @@ use std::{
     os::unix::fs::PermissionsExt,
     path::{Path, PathBuf},
     process::Command,
+    sync::{
+        Once,
+        atomic::{AtomicU32, Ordering},
+    },
     time::{Duration, Instant, SystemTime},
 };
 
 use crate::{emulator::Emulator, format::civil_from_days};
 
-/// Fresh scratch directory under the system temp dir. Any leftover from a
-/// previous run is removed first; the pid suffix isolates concurrent suites.
+/// Scratch-directory name prefix, shared by creation and the sweep.
+const SCRATCH_PREFIX: &str = "fleetcom_test_";
+
+/// Create an empty `fleetcom_test_<tag>_<pid>_<seq>` directory under the system
+/// temp directory. The PID separates test processes, and the sequence separates
+/// calls within one process. Any existing path with the same name is removed.
 pub(crate) fn temp(tag: &str) -> PathBuf {
-    let d = std::env::temp_dir().join(format!("fleetcom_test_{tag}_{}", std::process::id()));
+    static SEQ: AtomicU32 = AtomicU32::new(0);
+    sweep_dead_scratch();
+    let seq = SEQ.fetch_add(1, Ordering::Relaxed);
+    let d = std::env::temp_dir().join(format!(
+        "{SCRATCH_PREFIX}{tag}_{}_{seq}",
+        std::process::id()
+    ));
     let _ = fs::remove_dir_all(&d);
     fs::create_dir_all(&d).unwrap();
     d
 }
 
+/// Remove scratch directories whose recorded processes no longer exist.
+///
+/// This runs once, before the current process creates its first directory, so
+/// this process's directories remain available for post-failure inspection.
+fn sweep_dead_scratch() {
+    static ONCE: Once = Once::new();
+    ONCE.call_once(|| {
+        let Ok(entries) = fs::read_dir(std::env::temp_dir()) else {
+            return;
+        };
+        for entry in entries.flatten() {
+            let name = entry.file_name();
+            let Some(suffix) = name.to_str().and_then(|n| n.strip_prefix(SCRATCH_PREFIX)) else {
+                continue;
+            };
+            if scratch_pid(suffix).is_some_and(pid_is_dead) {
+                let _ = fs::remove_dir_all(entry.path());
+            }
+        }
+    });
+}
+
+/// Parse the `<pid>` from a `<tag>_<pid>_<seq>` scratch suffix. Tags contain
+/// underscores, so both trailing fields are read from the right.
+fn scratch_pid(suffix: &str) -> Option<i32> {
+    let (rest, seq) = suffix.rsplit_once('_')?;
+    let (_, pid) = rest.rsplit_once('_')?;
+    let digits = |s: &str| !s.is_empty() && s.bytes().all(|b| b.is_ascii_digit());
+    if !digits(seq) || !digits(pid) {
+        return None;
+    }
+    pid.parse::<i32>().ok().filter(|p| *p > 0)
+}
+
+/// Whether a PID is known to be dead. Only `ESRCH` proves death, so a live
+/// process and one owned by another user both keep their directory.
+fn pid_is_dead(pid: i32) -> bool {
+    use nix::{errno::Errno, sys::signal::kill, unistd::Pid};
+    matches!(kill(Pid::from_raw(pid), None), Err(Errno::ESRCH))
+}
+
+/// Accept the current suffix format and reject malformed fields.
+#[test]
+fn scratch_pid_reads_the_pid_field() {
+    assert_eq!(scratch_pid("tag_with_underscores_123_4"), Some(123));
+    assert_eq!(scratch_pid("session_mode_7_0"), Some(7));
+    // Both trailing fields must be decimal integers.
+    assert_eq!(scratch_pid("tag_with_underscores_x_4"), None);
+    assert_eq!(scratch_pid("tag_123_x"), None);
+    // A suffix without all three components is invalid.
+    assert_eq!(scratch_pid("tag_123"), None);
+    assert_eq!(scratch_pid("tag_0_4"), None);
+}
+
 /// Poll `pred` until it holds or `budget` elapses; returns the final answer.
 /// `pred` always runs at least once.
 pub(crate) fn wait_until(budget: Duration, mut pred: impl FnMut() -> bool) -> bool {

From 500b92cb7ab189c242a790c2ce907f38a442ccca Mon Sep 17 00:00:00 2001
From: Christopher Sardegna <github@reagentx.net>
Date: Tue, 28 Jul 2026 15:54:09 -0700
Subject: [PATCH 3/7] feat(app): add the `/` find palette for jumping the
 dashboard selection

---
 docs/README.md   |   4 +-
 docs/commands.md |  11 ++
 src/app.rs       |  96 ++++++++++++++++
 src/app_tests.rs | 279 +++++++++++++++++++++++++++++++++++++++++++++++
 src/ui.rs        |  66 +++++++++--
 5 files changed, 447 insertions(+), 9 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index b7e6ae2..463a247 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -62,7 +62,7 @@ Run `fleetcom`. The first invocation starts the daemon and opens an empty dashbo
 ```text
   fleetcom   0 running · 0 idle · 0 done      by state · dir · custom
 
-  ❯ n run · @ dir · s sort · w save · o load
+  ❯ n run · @ dir · / find · s sort · w save · o load
   ↑↓ select · enter attach · space peek · m tag · g group · R rename · r rerun · X kill · q detach · Q quit
 ```
 
@@ -75,7 +75,7 @@ Press `n`, enter a command, and press `Enter`. The command runs in its own PTY a
   ✻  cargo watch -x test      test result: ok. 42 passed         9s
   ✻  npm run dev              VITE v5.0  ready in 312 ms         4s
 
-  ❯ n run · @ dir · s sort · w save · o load
+  ❯ n run · @ dir · / find · s sort · w save · o load
   ↑↓ select · enter attach · space peek · m tag · g group · R rename · r rerun · X kill · q detach · Q quit
 ```
 
diff --git a/docs/commands.md b/docs/commands.md
index 58e1ac2..834d16e 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -26,6 +26,7 @@
 | `Space` | Peek at the selected task |
 | `n` | New command in the invocation directory |
 | `@` | New command in a directory you pick |
+| `/` | Jump the selection to a task by name, command, or group (opens the [find palette](#the--find-palette)) |
 | `s` | Cycle grouping: by state / by directory / by custom group |
 | `m` | Tag the selected task "in use" (toggles) |
 | `g` | Assign the selected task to a group (opens the group picker) |
@@ -145,6 +146,16 @@ The daemon removes control characters, trims surrounding whitespace, and limits
 
 Typing filters the rows; `Backspace` deletes one character and the matches re-filter; `↑`/`↓` move the highlight; `Esc` cancels. Completion updates on each input, permitting navigation and launch without leaving the dashboard. `←`/`→` move the caret within the typed path (`→` descends only when the caret is at the end), and `Ctrl-A`/`Ctrl-E` (or `Home`/`End`) jump to either end; the same caret keys work in every `fleetcom` text field.
 
+## The `/` find palette
+
+`/` opens a bottom panel over the dashboard listing the tasks that match what you type. Each row reads `<glyph> <label> · <section>`: the task's status glyph, its name (or its command when unnamed), and the section it currently sits in. Empty input lists the whole fleet, and every list is in dashboard order, so the panel reads the same way as the list behind it. With no tasks, `/` does nothing.
+
+Matching is a case-insensitive substring of three fields: name, command, and group. Substring, not prefix: `eep` finds `sleep 5`. A name adds a field rather than replacing one, so a task renamed `api tests` is still reachable by typing `cargo`.
+
+The working directory is not matched. In a monorepo every task shares one directory, and cross-repo tasks often carry `~` as their base, so the directory separates nothing.
+
+`Enter` moves the dashboard selection to the highlighted task and closes the panel. It does not attach: `Enter` attaches from the dashboard, so `/api` `Enter` `Enter` attaches and `/api` `Enter` `Space` peeks. With nothing matched, `Enter` leaves the panel open so the query can be corrected. `↑`/`↓` move the highlight; `Esc` closes and leaves the selection where it was. The palette changes nothing else: no task is spawned, tagged, grouped, renamed, or killed through it.
+
 ## The `g` group picker
 
 `g` on a selected task opens a bottom panel with the same structure as the `@` picker: a typed-name field plus the matching rows. Row 0 is always Unassigned, so the list is never empty; the fleet's existing group names follow, sorted, filtered by case-insensitive prefix as you type. The task's current group is marked `(current)`.
diff --git a/src/app.rs b/src/app.rs
index cae075b..c6f3373 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -85,6 +85,8 @@ pub enum Mode {
     PickDir,
     /// Live group picker (the `g` flow) that reassigns the selected task's group.
     PickGroup,
+    /// Live find palette (the `/` flow) that jumps the selection to a task.
+    Find,
     /// Typing a name to save the current tasks as a session.
     SaveSession,
     /// Editing the display name of the task selected when the prompt opened.
@@ -217,6 +219,13 @@ pub struct App {
     pub group_sel: usize,
     /// Id of the task being reassigned by the open group picker.
     group_target: Option<u64>,
+    // `/` find-palette state (only meaningful in `Mode::Find`).
+    pub find_input: EditBuffer,
+    /// Matching task *ids*, in display order. Ids, not `views` indices: a
+    /// daemon snapshot can land while the panel is open and reorder `views`,
+    /// which would point a stored index at a different task.
+    pub find_candidates: Vec<u64>,
+    pub find_sel: usize,
     /// Task ID captured when the rename prompt opens.
     rename_target: Option<u64>,
     // Load-session picker state.
@@ -410,6 +419,9 @@ impl App {
             group_candidates: Vec::new(),
             group_sel: 0,
             group_target: None,
+            find_input: EditBuffer::default(),
+            find_candidates: Vec::new(),
+            find_sel: 0,
             rename_target: None,
             session_names: Vec::new(),
             session_sel: 0,
@@ -1014,6 +1026,40 @@ impl App {
         self.mode = Mode::Dashboard;
     }
 
+    // --- `/` find palette -------------------------------------------------------
+
+    /// Open the `/` palette with the whole fleet listed. A no-op on an empty
+    /// fleet: there is nothing to find, so the panel would be a dead end.
+    fn open_find_palette(&mut self) {
+        if self.views.is_empty() {
+            return;
+        }
+        self.find_input.clear();
+        self.refresh_find_candidates();
+        self.mode = Mode::Find;
+    }
+
+    /// Rebuild the palette rows in display order, so the panel reads in the
+    /// same order as the list behind it, and highlight the first match.
+    fn refresh_find_candidates(&mut self) {
+        let needle = self.find_input.to_lowercase();
+        self.find_candidates = self
+            .display_order()
+            .into_iter()
+            .filter(|&i| task_matches(&self.views[i], &needle))
+            .map(|i| self.views[i].id)
+            .collect();
+        self.find_sel = 0;
+    }
+
+    /// Clear the palette state and return to the dashboard.
+    fn close_find_palette(&mut self) {
+        self.find_input.clear();
+        self.find_candidates.clear();
+        self.find_sel = 0;
+        self.mode = Mode::Dashboard;
+    }
+
     // --- `R` rename prompt ------------------------------------------------------
 
     /// Open the rename prompt for the selected task, prefilled with its name.
@@ -1052,6 +1098,7 @@ impl App {
             Mode::Spawn => self.on_key_spawn(k),
             Mode::PickDir => self.on_key_pickdir(k),
             Mode::PickGroup => self.on_key_pickgroup(k),
+            Mode::Find => self.on_key_find(k),
             Mode::SaveSession => self.on_key_savesession(k),
             Mode::Rename => self.on_key_rename(k),
             Mode::LoadSession => self.on_key_loadsession(k),
@@ -1100,6 +1147,7 @@ impl App {
                 }
             }
             KeyCode::Char('g') => self.open_group_picker(),
+            KeyCode::Char('/') => self.open_find_palette(),
             // Uppercase R renames; lowercase r reruns.
             KeyCode::Char('R') => self.open_rename_prompt(),
             KeyCode::Char('n') => {
@@ -1291,6 +1339,31 @@ impl App {
         }
     }
 
+    fn on_key_find(&mut self, k: KeyEvent) {
+        match k.code {
+            KeyCode::Esc => self.close_find_palette(),
+            KeyCode::Up => self.find_sel = self.find_sel.saturating_sub(1),
+            KeyCode::Down => self.find_sel = step_down(self.find_sel, self.find_candidates.len()),
+            KeyCode::Enter => {
+                // Enter moves the dashboard selection and nothing else. It
+                // deliberately does not attach: Enter attaches *from* the
+                // dashboard, so `/api` Enter Enter attaches and `/api` Enter
+                // Space peeks. With nothing matched the panel stays open, so a
+                // mistyped query can be corrected instead of being cancelled.
+                if let Some(&id) = self.find_candidates.get(self.find_sel) {
+                    self.selected_id = Some(id);
+                    self.close_find_palette();
+                }
+            }
+            // Caret motion does not affect the matches.
+            _ => {
+                if on_key_edit(&mut self.find_input, k) == Some(true) {
+                    self.refresh_find_candidates();
+                }
+            }
+        }
+    }
+
     fn on_key_spawn(&mut self, k: KeyEvent) {
         self.on_key_textinput(k, |app, cmd| {
             if !cmd.is_empty() {
@@ -1407,6 +1480,10 @@ impl App {
                 paste_into(&mut self.group_input, s);
                 self.refresh_group_candidates();
             }
+            Mode::Find => {
+                paste_into(&mut self.find_input, s);
+                self.refresh_find_candidates();
+            }
             _ => {}
         }
     }
@@ -1722,6 +1799,25 @@ fn on_key_edit(buf: &mut EditBuffer, k: KeyEvent) -> Option<bool> {
     }
 }
 
+/// Whether a task matches the find palette's lowercased `needle`: a
+/// case-insensitive substring of its name, command, or group. A named task
+/// still matches its command, so a task renamed "api tests" is found by typing
+/// `cargo`. The empty needle matches everything.
+///
+/// The working directory is deliberately absent. In a monorepo every task
+/// shares one directory and cross-repo tasks often carry `~` as their base, so
+/// the directory separates nothing and would only dilute the matches.
+fn task_matches(v: &TaskView, needle: &str) -> bool {
+    [
+        v.name.as_deref(),
+        Some(v.command.as_str()),
+        v.group.as_deref(),
+    ]
+    .into_iter()
+    .flatten()
+    .any(|field| field.to_lowercase().contains(needle))
+}
+
 /// Insert pasted text at the caret after removing control characters.
 fn paste_into(buf: &mut EditBuffer, s: &str) {
     for c in s.chars().filter(|c| !c.is_control()) {
diff --git a/src/app_tests.rs b/src/app_tests.rs
index d3701a0..2ed5082 100644
--- a/src/app_tests.rs
+++ b/src/app_tests.rs
@@ -1514,6 +1514,285 @@ fn group_esc_cancels_without_sending() {
     assert_eq!(v.group.as_deref(), Some("alpha"), "Esc must send nothing");
 }
 
+// --- `/` find palette ---------------------------------------------------
+
+/// Candidate ids for the current palette state.
+fn find_ids(app: &App) -> Vec<u64> {
+    app.find_candidates.clone()
+}
+
+/// Type `text` into the open palette one key at a time.
+fn find_type(app: &mut App, text: &str) {
+    for c in text.chars() {
+        app.on_key_find(key(KeyCode::Char(c)));
+    }
+}
+
+/// `/` needs tasks, not a selection: it no-ops on an empty fleet and opens
+/// before anything is selected.
+#[test]
+fn find_palette_opens_on_slash_only_with_tasks() {
+    let mut app = App::new_local(30, 100);
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    assert!(app.mode == Mode::Dashboard, "empty fleet: / must no-op");
+    assert!(app.find_candidates.is_empty());
+
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv);
+    app.pump();
+    assert_eq!(app.selected_id, None, "nothing selected yet");
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    assert!(app.mode == Mode::Find);
+    assert_eq!(find_ids(&app), vec![1]);
+}
+
+/// Candidates arrive in display order, not id order: tagging id 3 floats it
+/// to the top of the list and to the top of the palette with it.
+#[test]
+fn find_candidates_follow_display_order() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv.clone()); // id 1
+    app.spawn_in("sleep 5", inv.clone()); // id 2
+    app.spawn_in("sleep 5", inv); // id 3
+    app.transport.send(Command::Tag { id: 3, on: true });
+    app.pump();
+    let order: Vec<u64> = app
+        .display_order()
+        .into_iter()
+        .map(|i| app.views[i].id)
+        .collect();
+    assert_eq!(order, vec![3, 1, 2], "tag floats id 3 first");
+
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    assert_eq!(find_ids(&app), order);
+    assert_eq!(app.find_sel, 0, "the first match is highlighted");
+}
+
+/// Empty input lists the whole fleet.
+#[test]
+fn find_empty_input_lists_every_task() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv.clone()); // id 1
+    app.spawn_grouped("sleep 5", inv, "alpha"); // id 2
+    app.pump();
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    assert_eq!(find_ids(&app), vec![1, 2]);
+
+    // Typing then deleting returns the full fleet.
+    find_type(&mut app, "alpha");
+    assert_eq!(find_ids(&app), vec![2]);
+    for _ in 0.."alpha".len() {
+        app.on_key_find(key(KeyCode::Backspace));
+    }
+    assert_eq!(find_ids(&app), vec![1, 2]);
+}
+
+/// Matching ignores case and hits substrings anywhere in the field, not just
+/// its prefix.
+#[test]
+fn find_matches_case_insensitive_substrings() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv.clone()); // id 1
+    app.spawn_in("true", inv); // id 2
+    app.pump();
+
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    find_type(&mut app, "SLEEP");
+    assert_eq!(find_ids(&app), vec![1], "case-insensitive");
+
+    app.on_key_find(key(KeyCode::Esc));
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    find_type(&mut app, "eep");
+    assert_eq!(find_ids(&app), vec![1], "matches mid-command, not a prefix");
+
+    app.on_key_find(key(KeyCode::Esc));
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    find_type(&mut app, "ru");
+    assert_eq!(find_ids(&app), vec![2], "matches mid-command of \"true\"");
+}
+
+/// A renamed task keeps matching its command: the name is another haystack,
+/// not a replacement for one.
+#[test]
+fn find_matches_a_named_task_on_both_fields() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv.clone()); // id 1
+    app.spawn_in("true", inv); // id 2
+    app.transport.send(Command::SetName {
+        id: 1,
+        name: Some("api tests".to_string()),
+    });
+    app.pump();
+
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    find_type(&mut app, "api");
+    assert_eq!(find_ids(&app), vec![1], "matches the name");
+
+    app.on_key_find(key(KeyCode::Esc));
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    find_type(&mut app, "sleep");
+    assert_eq!(find_ids(&app), vec![1], "still matches the command");
+}
+
+/// Group names are a match field.
+#[test]
+fn find_matches_group_names() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_grouped("sleep 5", inv.clone(), "backend"); // id 1
+    app.spawn_in("sleep 5", inv); // id 2, no group
+    app.pump();
+
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    find_type(&mut app, "backend");
+    assert_eq!(find_ids(&app), vec![1]);
+}
+
+/// The working directory is not a match field: a task spawned in a uniquely
+/// named directory is unreachable by that name.
+#[test]
+fn find_does_not_match_the_directory() {
+    let mut app = App::new_local(30, 100);
+    let dir = temp("findpalettedir");
+    let name = dir.file_name().unwrap().to_string_lossy().into_owned();
+    app.spawn_in("sleep 5", dir); // id 1
+    app.pump();
+    assert!(name.contains("findpalettedir"), "scratch dir name: {name}");
+
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    find_type(&mut app, "findpalettedir");
+    assert!(
+        find_ids(&app).is_empty(),
+        "the directory must not match: {:?}",
+        find_ids(&app)
+    );
+
+    // The same task is reachable through a field that is matched.
+    app.on_key_find(key(KeyCode::Esc));
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    find_type(&mut app, "sleep");
+    assert_eq!(find_ids(&app), vec![1]);
+}
+
+/// Enter jumps the dashboard selection to the highlighted task and closes.
+#[test]
+fn find_enter_jumps_the_selection() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv.clone()); // id 1
+    app.spawn_in("sleep 5", inv.clone()); // id 2
+    app.spawn_in("sleep 5", inv); // id 3
+    app.pump();
+    app.resolve_selection();
+    assert_eq!(app.selected_id, Some(1));
+
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    app.on_key_find(key(KeyCode::Down));
+    app.on_key_find(key(KeyCode::Down));
+    assert_eq!(app.find_sel, 2);
+    app.on_key_find(key(KeyCode::Enter));
+    assert!(
+        app.mode == Mode::Dashboard,
+        "Enter jumps, it never attaches"
+    );
+    assert_eq!(app.focused_id, None);
+    assert_eq!(app.selected_id, Some(3));
+    assert!(app.find_input.is_empty() && app.find_candidates.is_empty());
+}
+
+/// Esc closes the palette and leaves the selection where it was.
+#[test]
+fn find_esc_leaves_the_selection_alone() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv.clone()); // id 1
+    app.spawn_in("true", inv); // id 2
+    app.pump();
+    app.resolve_selection();
+    assert_eq!(app.selected_id, Some(1));
+
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    find_type(&mut app, "true");
+    assert_eq!(find_ids(&app), vec![2]);
+    app.on_key_find(key(KeyCode::Esc));
+    assert!(app.mode == Mode::Dashboard);
+    assert_eq!(app.selected_id, Some(1), "Esc must not move the selection");
+    assert!(app.find_input.is_empty() && app.find_candidates.is_empty());
+    assert_eq!(app.find_sel, 0);
+}
+
+/// Enter on an empty candidate list changes nothing and keeps the panel open,
+/// so a typo can be corrected in place.
+#[test]
+fn find_enter_without_candidates_keeps_the_panel_open() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv);
+    app.pump();
+    app.resolve_selection();
+
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    find_type(&mut app, "zzz");
+    assert!(find_ids(&app).is_empty());
+    app.on_key_find(key(KeyCode::Enter));
+    assert!(app.mode == Mode::Find, "no match: Enter must not close");
+    assert_eq!(app.selected_id, Some(1), "selection is untouched");
+
+    // Correcting the query recovers a match.
+    for _ in 0.."zzz".len() {
+        app.on_key_find(key(KeyCode::Backspace));
+    }
+    find_type(&mut app, "sleep");
+    assert_eq!(find_ids(&app), vec![1]);
+}
+
+/// The panel paints its rows as `<glyph> <label> · <section>`, and says so
+/// when a query matches nothing.
+#[test]
+fn find_panel_rows_name_the_task_and_its_section() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv);
+    app.transport.send(Command::SetName {
+        id: 1,
+        name: Some("api tests".to_string()),
+    });
+    app.pump();
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+
+    let mut out = Vec::new();
+    crate::ui::render(&mut out, &mut app).unwrap();
+    let frame = String::from_utf8_lossy(&out).into_owned();
+    assert!(frame.contains("✻ api tests · Running"), "{frame:?}");
+    assert!(frame.contains("enter jump · ↑↓ pick · esc"), "{frame:?}");
+
+    find_type(&mut app, "zzz");
+    app.last_frame.clear();
+    let mut out = Vec::new();
+    crate::ui::render(&mut out, &mut app).unwrap();
+    let frame = String::from_utf8_lossy(&out).into_owned();
+    assert!(frame.contains("(no matching tasks)"), "{frame:?}");
+}
+
+/// A paste lands in the palette field and re-filters, like the other pickers.
+#[test]
+fn find_paste_filters_the_candidates() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv.clone()); // id 1
+    app.spawn_in("true", inv); // id 2
+    app.pump();
+
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    app.on_paste("true");
+    assert_eq!(app.find_input.as_str(), "true");
+    assert_eq!(find_ids(&app), vec![2]);
+}
+
 // --- `R` rename prompt --------------------------------------------------
 
 /// The rename prompt captures the selected task ID and current name.
diff --git a/src/ui.rs b/src/ui.rs
index 5455fd7..8575806 100644
--- a/src/ui.rs
+++ b/src/ui.rs
@@ -43,6 +43,10 @@ pub fn render(out: &mut impl Write, app: &mut App) -> io::Result<bool> {
             render_dashboard(&mut buf, app)?;
             render_pickgroup(&mut buf, app)?;
         }
+        Mode::Find => {
+            render_dashboard(&mut buf, app)?;
+            render_find(&mut buf, app)?;
+        }
         Mode::LoadSession => {
             render_dashboard(&mut buf, app)?;
             render_session_picker(&mut buf, app)?;
@@ -201,7 +205,7 @@ fn render_dashboard(out: &mut impl Write, app: &App) -> io::Result<()> {
             None => dim(
                 out,
                 cmd_y,
-                "  ❯ n run · @ dir · s sort · w save · o load",
+                "  ❯ n run · @ dir · / find · s sort · w save · o load",
                 cols,
             )?,
         },
@@ -338,16 +342,21 @@ fn row_age(v: &TaskView) -> Duration {
     edge.unwrap_or(v.started_ago)
 }
 
-/// Split a task row into its leading, preview, and time cells so the preview
-/// can be styled independently. Each cell is padded to its display-column
-/// budget, and the budgets sum to `cols`.
-fn task_row_parts(v: &TaskView, cols: usize) -> (String, String, String) {
-    let glyph = match v.lifecycle {
+/// A task's lifecycle glyph, shared by the dashboard row and the `/` palette.
+fn status_glyph(v: &TaskView) -> &'static str {
+    match v.lifecycle {
         Lifecycle::Active => "✻",
         Lifecycle::Idle => "∙",
         Lifecycle::Ok => "✓",
         Lifecycle::Failed => "✗",
-    };
+    }
+}
+
+/// Split a task row into its leading, preview, and time cells so the preview
+/// can be styled independently. Each cell is padded to its display-column
+/// budget, and the budgets sum to `cols`.
+fn task_row_parts(v: &TaskView, cols: usize) -> (String, String, String) {
+    let glyph = status_glyph(v);
     let tag = if v.tagged { "◆" } else { " " };
     let time = rel_time(row_age(v));
     let title_w = 26.min(cols / 3);
@@ -610,6 +619,49 @@ fn render_pickgroup(out: &mut impl Write, app: &App) -> io::Result<()> {
     )
 }
 
+/// The `/` palette: a bottom panel with the typed text and the matching tasks,
+/// `find_sel` highlighted. Each row names the task and the section it sits in,
+/// so a jump is aimed at a known place in the list behind the panel.
+fn render_find(out: &mut impl Write, app: &App) -> io::Result<()> {
+    let sections = app.sections();
+    let section_of = |id: u64| -> &str {
+        sections
+            .iter()
+            .find(|(_, idxs)| idxs.iter().any(|&i| app.views[i].id == id))
+            .map_or("", |(label, _)| label.as_str())
+    };
+    let labels: Vec<String> = app
+        .find_candidates
+        .iter()
+        .map(|&id| match app.views.iter().find(|v| v.id == id) {
+            Some(v) => format!(
+                "{} {} · {}",
+                status_glyph(v),
+                display_label(v),
+                section_of(id)
+            ),
+            // A snapshot removed the task after the last refresh. Keep the row
+            // so the highlight still lines up with `find_candidates`.
+            None => String::new(),
+        })
+        .collect();
+    let (line, cx) = caret_line("  / ", &app.find_input);
+    let cx = clamp_caret(cx, &line, app.cols as usize);
+    render_panel(
+        out,
+        app,
+        &Panel {
+            header: format!("  / {}   ", app.find_input.as_str()),
+            labels: &labels,
+            sel: app.find_sel,
+            max_rows: 8,
+            hint: "enter jump · ↑↓ pick · esc".to_string(),
+            empty: Some("    (no matching tasks)"),
+            cursor: Some(cx),
+        },
+    )
+}
+
 /// Format a recovery row with its variable-length label last for clipping.
 fn recovery_row(e: &RecoveryEntry) -> String {
     let unit = if e.tasks == 1 { "task" } else { "tasks" };

From e5f0d65ab064e8f95a133395e8b4f3436accba1b Mon Sep 17 00:00:00 2001
From: Christopher Sardegna <github@reagentx.net>
Date: Wed, 29 Jul 2026 14:32:43 -0700
Subject: [PATCH 4/7] fix(app): stop sorting dashboard rows on the reversible
 parked flag

---
 docs/commands.md     |   2 +-
 docs/how-it-works.md |   2 +-
 src/app.rs           |  40 ++++++++--
 src/app_tests.rs     | 185 ++++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 215 insertions(+), 14 deletions(-)

diff --git a/docs/commands.md b/docs/commands.md
index 834d16e..8a9e68a 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -124,7 +124,7 @@ A `TERM`-ignoring member can also survive when its leader exits during shutdown.
 
 Groups belong to task state: an assignment survives client detach and rerun (`r`), and switching grouping modes does not modify it. `g` reassigns the selected task through the [group picker](#the-g-group-picker).
 
-`m` toggles the "in use" tag and marks the task with `◆`. In state mode, tagged tasks form the In use section at the top. In custom mode, a tag moves the task to the top of its existing group rather than creating a global section. Within each group, the order is tagged, running, idle, completed; each bucket then sorts by directory and spawn order.
+`m` toggles the "in use" tag and marks the task with `◆`. In state mode, tagged tasks form the In use section at the top. In custom mode, a tag moves the task to the top of its existing group rather than creating a global section. Within a dir or custom section, the order is tagged, live, completed; each bucket then sorts by directory and spawn order. The idle transition is absent from that order by design: it reverses on its 10-second timer, so ranking on it moved a row twice per interaction, both times off screen. A task that goes quiet keeps its row and shows `∙`. State mode still separates Running from Idle, because there the split is the section, not the row order.
 
 In custom mode only, a new command inherits the selected task's group, through both `n` and the `@` picker. The spawn prompt shows the destination as `❯ dir ▸ group ▸ command`, each segment present only when it applies: the dir segment for a non-default directory, the group segment when a group will be inherited. State- and dir-mode spawns start unassigned.
 
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 601ba43..48d9a79 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -10,4 +10,4 @@ Attached input follows the terminal modes reported by the child. Modified Enter
 
 ## Grouping follows one activity window
 
-The dashboard groups tasks by state (In use / Running / Idle / Completed), working directory, or names assigned with `g`. One 10-second window drives both idle signals: after 10 s without output, the row glyph changes from `✻` to `∙` and the task moves to Idle in the same refresh. A tool such as `top`, which prints every 1–2 s, never crosses the window, so it stays `✻` under Running. The preview text holds separately: a status from a weaker source must persist for 600 ms before it replaces a stronger one, which absorbs repaint flicker without affecting grouping.
+The dashboard groups tasks by state (In use / Running / Idle / Completed), working directory, or names assigned with `g`. One 10-second window drives both idle signals: after 10 s without output, the row glyph changes from `✻` to `∙` and, under state grouping, the task moves to the Idle section in the same refresh. Row order within a section never consults that transition, because it reverses on the same timer: a task that goes quiet holds its row. A tool such as `top`, which prints every 1–2 s, never crosses the window, so it stays `✻` under Running. The preview text holds separately: a status from a weaker source must persist for 600 ms before it replaces a stronger one, which absorbs repaint flicker without affecting grouping.
diff --git a/src/app.rs b/src/app.rs
index c6f3373..b3eb714 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -299,13 +299,13 @@ fn step_down(sel: usize, len: usize) -> usize {
     (sel + 1).min(len.saturating_sub(1))
 }
 
-/// Dashboard grouping bucket: 0 tagged, 1 live, 2 parked live, 3 completed.
+/// State-grouping section identity: 0 In use, 1 Running, 2 Idle, 3 Completed.
 /// Tagged wins over everything; completed is classified by `lifecycle`, never
 /// by trusting `parked == false`, so a core that ever shipped both signals
-/// still lands finished tasks in Completed. Placement follows `parked`, the
-/// core's debounced quiet signal: it shares the 10 s window with
+/// still lands finished tasks in Completed. The Running/Idle split follows
+/// `parked`, the core's debounced quiet signal: it shares the 10 s window with
 /// `Lifecycle::Idle`, so the idle glyph and the row's section flip together.
-fn bucket(v: &TaskView) -> u8 {
+fn section_rank(v: &TaskView) -> u8 {
     if v.tagged {
         0
     } else if matches!(v.lifecycle, Lifecycle::Ok | Lifecycle::Failed) {
@@ -317,6 +317,28 @@ fn bucket(v: &TaskView) -> u8 {
     }
 }
 
+/// Within-section row order: 0 tagged, 1 live, 2 finished. Applies in every
+/// grouping mode. Finished is classified by `lifecycle`, for the same reason
+/// `section_rank` does it that way.
+///
+/// `parked` is deliberately absent. It reverses on a 10 s timer, so ranking on
+/// it moved a row twice per interaction: up the moment the child echoed a
+/// keystroke, back down ten seconds after the typing stopped. Both moves landed
+/// while the user was attached to some other task, so the dashboard they
+/// returned to had silently reindexed itself — worst for the tasks they touched
+/// most. A row's rank now moves only on a monotonic edge (`finished`) or a
+/// deliberate one (`tagged`). The idle signal keeps its glyph, and in State mode
+/// its own section.
+fn row_rank(v: &TaskView) -> u8 {
+    if v.tagged {
+        0
+    } else if matches!(v.lifecycle, Lifecycle::Ok | Lifecycle::Failed) {
+        2
+    } else {
+        1
+    }
+}
+
 impl App {
     /// Default client: connect to the daemon (autostarting it if needed) and
     /// complete the hello handshake, so tasks outlive the UI and run under
@@ -508,7 +530,7 @@ impl App {
             .map(|(i, v)| {
                 let (rank, label) = match self.group_mode {
                     GroupMode::State => {
-                        let b = bucket(v);
+                        let b = section_rank(v);
                         let l = match b {
                             0 => "In use",
                             1 => "Running",
@@ -529,9 +551,11 @@ impl App {
                         None => (1, "Unassigned".to_string()),
                     },
                 };
-                // Within each section, sort by tag/lifecycle bucket, directory,
-                // then task id.
-                (rank, label, bucket(v), self.dir_label(&v.cwd), v.id, i)
+                // Within each section: tagged first, finished last, then
+                // directory, then task id. In State mode `row_rank` is constant
+                // across a section (the section *is* the bucket), so it drops
+                // out and the order stays directory-then-id.
+                (rank, label, row_rank(v), self.dir_label(&v.cwd), v.id, i)
             })
             .collect();
         labeled.sort();
diff --git a/src/app_tests.rs b/src/app_tests.rs
index 2ed5082..bad7f68 100644
--- a/src/app_tests.rs
+++ b/src/app_tests.rs
@@ -376,10 +376,11 @@ fn selection_follows_task_across_parked_rebucket() {
     assert_eq!(app.views[app.selected_task().unwrap()].id, 1);
 }
 
-/// `bucket` doubles as the within-group tiebreak, so a parked task sinks
-/// below a running one inside a Custom group too, not only in State mode.
+/// Row order ignores `parked`, so going quiet does not move a task inside its
+/// Custom group. The flip reverses on the 10 s window; ranking on it made a row
+/// travel twice per interaction, out of sight of a user attached elsewhere.
 #[test]
-fn custom_mode_parked_sinks_within_group() {
+fn custom_mode_parked_task_holds_its_row() {
     let mut app = App::new_local(30, 100);
     let inv = app.invocation_dir.clone();
     app.spawn_grouped("sleep 5", inv.clone(), "alpha"); // id 1
@@ -390,13 +391,189 @@ fn custom_mode_parked_sinks_within_group() {
 
     let i = app.views.iter().position(|v| v.id == 1).unwrap();
     app.views[i].parked = true;
+    assert_eq!(
+        app.section_ids(),
+        vec![("alpha".to_string(), vec![1, 2])],
+        "parked id 1 keeps its row above id 2 within alpha"
+    );
+}
+
+/// Same guarantee one section wider: dir mode also holds a row through the
+/// quiet transition.
+#[test]
+fn dir_mode_parked_task_holds_its_row() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv.clone()); // id 1
+    app.spawn_in("sleep 5", inv); // id 2
+    app.pump();
+    app.group_mode = GroupMode::Dir;
+    let label = app.invocation_label.clone();
+    assert_eq!(app.section_ids(), vec![(label.clone(), vec![1, 2])]);
+
+    let i = app.views.iter().position(|v| v.id == 1).unwrap();
+    app.views[i].parked = true;
+    assert_eq!(
+        app.section_ids(),
+        vec![(label, vec![1, 2])],
+        "parked id 1 keeps its row above id 2 within its directory"
+    );
+}
+
+/// `parked` round trip: the row sits in the same place before, during, and
+/// after the quiet window. This is the property the sort key now guarantees.
+#[test]
+fn parked_round_trip_leaves_row_order_identical() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_grouped("sleep 5", inv.clone(), "alpha"); // id 1
+    app.spawn_grouped("sleep 5", inv.clone(), "alpha"); // id 2
+    app.spawn_grouped("sleep 5", inv, "alpha"); // id 3
+    app.pump();
+    app.group_mode = GroupMode::Custom;
+    let want = vec![("alpha".to_string(), vec![1, 2, 3])];
+    assert_eq!(app.section_ids(), want);
+
+    let i = app.views.iter().position(|v| v.id == 2).unwrap();
+    app.views[i].parked = true;
+    assert_eq!(app.section_ids(), want, "quiet does not move id 2");
+
+    app.views[i].parked = false;
+    assert_eq!(app.section_ids(), want, "waking does not move id 2 back");
+}
+
+/// Finished is monotonic, so it stays in the row key: a completed task sinks
+/// below its live siblings inside a Custom group.
+#[test]
+fn custom_mode_finished_sinks_within_group() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_grouped("true", inv.clone(), "alpha"); // id 1: exits ~immediately
+    app.spawn_grouped("sleep 30", inv, "alpha"); // id 2: stays live
+    wait_until(Duration::from_secs(5), || {
+        app.pump();
+        app.views
+            .iter()
+            .any(|v| v.id == 1 && matches!(v.lifecycle, Lifecycle::Ok | Lifecycle::Failed))
+    });
+    app.group_mode = GroupMode::Custom;
     assert_eq!(
         app.section_ids(),
         vec![("alpha".to_string(), vec![2, 1])],
-        "parked id 1 sinks below running id 2 within alpha"
+        "finished id 1 sinks below live id 2 within alpha"
     );
 }
 
+/// The same monotonic sink in dir mode.
+#[test]
+fn dir_mode_finished_sinks_within_section() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("true", inv.clone()); // id 1: exits ~immediately
+    app.spawn_in("sleep 30", inv); // id 2: stays live
+    wait_until(Duration::from_secs(5), || {
+        app.pump();
+        app.views
+            .iter()
+            .any(|v| v.id == 1 && matches!(v.lifecycle, Lifecycle::Ok | Lifecycle::Failed))
+    });
+    app.group_mode = GroupMode::Dir;
+    assert_eq!(
+        app.section_ids(),
+        vec![(app.invocation_label.clone(), vec![2, 1])],
+        "finished id 1 sinks below live id 2 within its directory"
+    );
+}
+
+/// A tag is user-controlled, so it stays in the row key: the tagged task floats
+/// to the top of its Custom group and holds that row when it goes quiet.
+#[test]
+fn custom_mode_tagged_task_floats_and_holds_while_parked() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_grouped("sleep 5", inv.clone(), "alpha"); // id 1
+    app.spawn_grouped("sleep 5", inv, "alpha"); // id 2: tagged
+    app.pump();
+    app.transport.send(Command::Tag { id: 2, on: true });
+    app.pump();
+    app.group_mode = GroupMode::Custom;
+    assert_eq!(app.section_ids(), vec![("alpha".to_string(), vec![2, 1])]);
+
+    let i = app.views.iter().position(|v| v.id == 2).unwrap();
+    app.views[i].parked = true;
+    assert_eq!(
+        app.section_ids(),
+        vec![("alpha".to_string(), vec![2, 1])],
+        "tagged id 2 stays at the top of alpha while parked"
+    );
+}
+
+/// State mode is unchanged by the row-key split, because within a State section
+/// every member shares one `row_rank`: In use all tagged, Running and Idle all
+/// live, Completed all finished. A constant contributes nothing to the sort, so
+/// section order and within-section order (directory, then id) stand exactly as
+/// before. Asserting the whole shape catches a collapsed Running/Idle split or
+/// a `dir_label` dropped from the sort key.
+#[test]
+fn state_mode_ordering_survives_the_row_key_split() {
+    let mut app = App::new_local(30, 100);
+    let base = temp("app_state_order");
+    let (dir_a, dir_b) = (base.join("a"), base.join("b"));
+    std::fs::create_dir_all(&dir_a).unwrap();
+    std::fs::create_dir_all(&dir_b).unwrap();
+
+    app.spawn_in("sleep 30", dir_b.clone()); // id 1: running, dir b
+    app.spawn_in("sleep 30", dir_a.clone()); // id 2: running, dir a
+    app.spawn_in("sleep 30", dir_b.clone()); // id 3: parked -> Idle, dir b
+    app.spawn_in("sleep 30", dir_a.clone()); // id 4: parked -> Idle, dir a
+    app.spawn_in("sleep 30", dir_b.clone()); // id 5: tagged, dir b
+    app.spawn_in("sleep 30", dir_a.clone()); // id 6: tagged + parked, dir a
+    app.spawn_in("true", dir_b.clone()); // id 7: finished, dir b
+    app.spawn_in("true", dir_a.clone()); // id 8: finished, dir a
+    wait_until(Duration::from_secs(5), || {
+        app.pump();
+        [7u64, 8].iter().all(|id| {
+            app.views
+                .iter()
+                .any(|v| v.id == *id && matches!(v.lifecycle, Lifecycle::Ok | Lifecycle::Failed))
+        })
+    });
+    for id in [5u64, 6] {
+        app.transport.send(Command::Tag { id, on: true });
+    }
+    app.pump();
+
+    // Pin `parked` in both directions after the last pump. Later than the last
+    // pump because a fresh core snapshot would overwrite it; both directions
+    // because ids 1, 2, and 5 print nothing, so on a loaded machine they would
+    // cross the real 10 s window and desert Running before the assert.
+    for (id, parked) in [
+        (1u64, false),
+        (2, false),
+        (3, true),
+        (4, true),
+        (5, false),
+        (6, true),
+    ] {
+        let i = app.views.iter().position(|v| v.id == id).unwrap();
+        app.views[i].parked = parked;
+    }
+
+    let (a, b) = (app.dir_label(&dir_a), app.dir_label(&dir_b));
+    assert!(a < b, "dir a must sort before dir b for this test to bite");
+    assert_eq!(
+        app.section_ids(),
+        vec![
+            ("In use".to_string(), vec![6, 5]),
+            ("Running".to_string(), vec![2, 1]),
+            ("Idle".to_string(), vec![4, 3]),
+            ("Completed".to_string(), vec![8, 7]),
+        ],
+        "four sections in state order; within each, dir a before dir b, then id"
+    );
+    let _ = std::fs::remove_dir_all(&base);
+}
+
 /// `r` sends `Restart` only for a finished selection. On a running task
 /// the key is a client-side no-op: nothing crosses the transport, so no
 /// supervisor complaint lands in the status line. On a finished one the

From e350b250e3ef61e56660f66c8b5143301297e60a Mon Sep 17 00:00:00 2001
From: Christopher Sardegna <github@reagentx.net>
Date: Thu, 30 Jul 2026 18:51:32 -0700
Subject: [PATCH 5/7] fix(sort): collate human-readable names
 case-insensitively

---
 docs/README.md   |   2 +-
 docs/commands.md |   8 +--
 src/app.rs       |  30 ++++++++++--
 src/app_tests.rs | 123 +++++++++++++++++++++++++++++++++++++++++++++--
 src/format.rs    |  56 +++++++++++++++++++++
 src/session.rs   |  26 ++++++++--
 6 files changed, 230 insertions(+), 15 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 463a247..1ad66dc 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -107,7 +107,7 @@ Each row is `glyph · tag · command · latest output · age`. The age counts fr
   ✻  npm run dev              VITE v5.0  ready in 312 ms        1m
 ```
 
-`s` cycles through state, directory, and custom grouping. The header renders the active mode in bold. In custom mode, `g` assigns the selected task to a named group. Named sections sort alphabetically; Unassigned appears last when at least one task has no group:
+`s` cycles through state, directory, and custom grouping. The header renders the active mode in bold. In custom mode, `g` assigns the selected task to a named group. Named sections sort by name and ignore case, so `API` files next to `api` rather than ahead of every lowercase name; the two remain separate sections, because group identity stays case-sensitive. Unassigned appears last when at least one task has no group:
 
 ```text
   fleetcom   2 running · 0 idle · 0 done      by state · dir · custom
diff --git a/docs/commands.md b/docs/commands.md
index 8a9e68a..773d091 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -119,9 +119,11 @@ A `TERM`-ignoring member can also survive when its leader exits during shutdown.
 `s` cycles three grouping modes: state, dir, custom. The header shows the strip `by state · dir · custom` with the active mode bold and the rest dim.
 
 - By state: In use / Running / Idle / Completed. A running task files under Idle after 10 s without output; Completed stays one section (`✓`/`✗` show exit status).
-- By dir: one section per working directory; the invocation directory first, the rest alphabetical.
+- By dir: one section per working directory; the invocation directory first, the rest sorted by name.
 - By custom group: one section per group name, sorted by name, with Unassigned last. Fresh spawns remain unassigned unless they inherit a group, and the Unassigned section exists only while it has a member.
 
+Every name sort ignores case, section labels and the within-section directory tiebreak alike: `API` files next to `api`, not ahead of every lowercase name. Names differing only by case sort adjacent and stay distinct — group comparison remains case-sensitive, so `API` and `api` are two sections, in a fixed order that does not shift between renders.
+
 Groups belong to task state: an assignment survives client detach and rerun (`r`), and switching grouping modes does not modify it. `g` reassigns the selected task through the [group picker](#the-g-group-picker).
 
 `m` toggles the "in use" tag and marks the task with `◆`. In state mode, tagged tasks form the In use section at the top. In custom mode, a tag moves the task to the top of its existing group rather than creating a global section. Within a dir or custom section, the order is tagged, live, completed; each bucket then sorts by directory and spawn order. The idle transition is absent from that order by design: it reverses on its 10-second timer, so ranking on it moved a row twice per interaction, both times off screen. A task that goes quiet keeps its row and shows `∙`. State mode still separates Running from Idle, because there the split is the section, not the row order.
@@ -158,7 +160,7 @@ The working directory is not matched. In a monorepo every task shares one direct
 
 ## The `g` group picker
 
-`g` on a selected task opens a bottom panel with the same structure as the `@` picker: a typed-name field plus the matching rows. Row 0 is always Unassigned, so the list is never empty; the fleet's existing group names follow, sorted, filtered by case-insensitive prefix as you type. The task's current group is marked `(current)`.
+`g` on a selected task opens a bottom panel with the same structure as the `@` picker: a typed-name field plus the matching rows. Row 0 is always Unassigned, so the list is never empty; the fleet's existing group names follow, sorted ignoring case to match the filter, filtered by case-insensitive prefix as you type. The task's current group is marked `(current)`.
 
 `Enter` acts on the highlighted row, and the hint line names the action:
 
@@ -172,7 +174,7 @@ The daemon normalizes every group name received from the picker or a [session](s
 
 ## The `o` session picker
 
-`o` opens a bottom panel listing the saved [sessions](sessions.md): `↑`/`↓` move the highlight, `Enter` loads, `Esc` cancels. While [recovery snapshots](sessions.md#recovery) exist, the hint adds `tab recovery (N)` and `Tab` (or `Shift-Tab`) flips the panel to them; `Tab` again returns to the saved list. Each list keeps its own highlight. With no snapshots, `Tab` does nothing and the hint omits it.
+`o` opens a bottom panel listing the saved [sessions](sessions.md), sorted by name ignoring case: `↑`/`↓` move the highlight, `Enter` loads, `Esc` cancels. While [recovery snapshots](sessions.md#recovery) exist, the hint adds `tab recovery (N)` and `Tab` (or `Shift-Tab`) flips the panel to them; `Tab` again returns to the saved list. Each list keeps its own highlight. With no snapshots, `Tab` does nothing and the hint omits it.
 
 A recovery row reads `<age> ago · <tasks> task(s) · <label>`: the file's age, its command count, and its stored label (normally `autosaved <timestamp>`). `Enter` loads the highlighted snapshot; the status line confirms the load and suggests saving it. Press `w` to save the recovered fleet as a named session.
 
diff --git a/src/app.rs b/src/app.rs
index b3eb714..33b3822 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -26,6 +26,7 @@ use crossterm::{
 
 use crate::{
     editbuf::EditBuffer,
+    format::collation_key,
     path,
     protocol::{
         ClipboardKind, Command, Event, Key, Lifecycle, Mods, MouseBtn, MouseKind, RecoveryEntry,
@@ -541,7 +542,7 @@ impl App {
                     }
                     GroupMode::Dir => {
                         let label = self.dir_label(&v.cwd);
-                        // Invocation dir sorts first; everything else alphabetical.
+                        // Invocation dir sorts first; the rest collate by name.
                         let rank = if label == self.invocation_label { 0 } else { 1 };
                         (rank, label)
                     }
@@ -558,8 +559,22 @@ impl App {
                 (rank, label, row_rank(v), self.dir_label(&v.cwd), v.id, i)
             })
             .collect();
-        labeled.sort();
+        // Both strings are human-readable names, so both collate. `cached_key`
+        // builds each element's key once; a comparator would rebuild it on
+        // every comparison.
+        labeled.sort_by_cached_key(|(rank, label, row, dir, id, i)| {
+            (
+                *rank,
+                collation_key(label),
+                *row,
+                collation_key(dir),
+                *id,
+                *i,
+            )
+        });
 
+        // Section boundaries compare the exact label, never the folded one:
+        // `API` and `api` sort adjacent and stay two sections.
         let mut out: Vec<(String, Vec<usize>)> = Vec::new();
         for (_, label, _, _, _, i) in labeled {
             match out.last_mut() {
@@ -1019,7 +1034,9 @@ impl App {
             .filter_map(|v| v.group.as_ref())
             .filter(|g| g.to_lowercase().starts_with(&needle))
             .collect();
-        names.sort();
+        names.sort_by_cached_key(|g| collation_key(g.as_str()));
+        // Exact duplicates share a key and stay adjacent under a stable sort,
+        // so `dedup` still collapses them — and only them.
         names.dedup();
         for name in names {
             cands.push(GroupCand {
@@ -1859,7 +1876,8 @@ fn split_input(input: &str) -> (&str, &str) {
 }
 
 /// Subdirectories of `base` whose name prefix-matches `partial` (case-
-/// insensitive), sorted. Hidden entries appear only when `partial` starts `.`.
+/// insensitive), collated case-insensitively so the order matches the filter.
+/// Hidden entries appear only when `partial` starts `.`.
 fn list_dirs(base: &Path, partial: &str) -> Vec<String> {
     let needle = partial.to_lowercase();
     let mut out: Vec<String> = Vec::new();
@@ -1878,7 +1896,9 @@ fn list_dirs(base: &Path, partial: &str) -> Vec<String> {
             }
         }
     }
-    out.sort();
+    // `read_dir` yields entries in arbitrary order, so this sort is also what
+    // makes the panel deterministic.
+    out.sort_by_cached_key(|n| collation_key(n));
     out
 }
 
diff --git a/src/app_tests.rs b/src/app_tests.rs
index bad7f68..d359bfd 100644
--- a/src/app_tests.rs
+++ b/src/app_tests.rs
@@ -125,6 +125,58 @@ fn dir_mode_groups_by_cwd() {
     assert_eq!(s[1].0, "/tmp");
 }
 
+/// Group sections collate case-insensitively. Byte order would read
+/// `API, Review, api, zebra`, stranding `API` at the opposite end of the list
+/// from `api`; folded order reads `API, api, Review, zebra`. The two `api`
+/// sections stay separate, because group identity remains case-sensitive:
+/// merging them would be a data bug, not a display change.
+#[test]
+fn custom_sections_collate_case_insensitively() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_grouped("sleep 5", inv.clone(), "zebra"); // id 1
+    app.spawn_grouped("sleep 5", inv.clone(), "API"); // id 2
+    app.spawn_grouped("sleep 5", inv.clone(), "Review"); // id 3
+    app.spawn_grouped("sleep 5", inv, "api"); // id 4
+    app.pump();
+    app.group_mode = GroupMode::Custom;
+
+    assert_eq!(
+        app.section_ids(),
+        vec![
+            ("API".to_string(), vec![2]),
+            ("api".to_string(), vec![4]),
+            ("Review".to_string(), vec![3]),
+            ("zebra".to_string(), vec![1]),
+        ],
+        "folded order, with API and api adjacent and still two sections"
+    );
+}
+
+/// Dir-mode section labels collate too. `Zed` and `apple` discriminate: byte
+/// order puts `Zed` first, folded order puts `apple` first.
+#[test]
+fn dir_sections_collate_case_insensitively() {
+    let mut app = App::new_local(30, 100);
+    let base = temp("app_dir_collate");
+    let (upper, lower) = (base.join("Zed"), base.join("apple"));
+    std::fs::create_dir_all(&upper).unwrap();
+    std::fs::create_dir_all(&lower).unwrap();
+    app.spawn_in("sleep 5", upper.clone()); // id 1
+    app.spawn_in("sleep 5", lower.clone()); // id 2
+    app.pump();
+    app.group_mode = GroupMode::Dir;
+
+    let (z, a) = (app.dir_label(&upper), app.dir_label(&lower));
+    assert!(z < a, "byte order must put Zed first for this test to bite");
+    assert_eq!(
+        app.section_ids(),
+        vec![(a, vec![2]), (z, vec![1])],
+        "apple before Zed once the label folds"
+    );
+    let _ = std::fs::remove_dir_all(&base);
+}
+
 /// `s` cycles through all grouping modes.
 #[test]
 fn group_mode_cycles_state_dir_custom() {
@@ -518,7 +570,11 @@ fn custom_mode_tagged_task_floats_and_holds_while_parked() {
 fn state_mode_ordering_survives_the_row_key_split() {
     let mut app = App::new_local(30, 100);
     let base = temp("app_state_order");
-    let (dir_a, dir_b) = (base.join("a"), base.join("b"));
+    // `apple` and `Zed` disagree between the two collations — byte order puts
+    // `Zed` first, folded order puts `apple` first — so this test also locks
+    // the half of the collation change that State mode is not neutral to: the
+    // within-section `dir_label` tiebreak.
+    let (dir_a, dir_b) = (base.join("apple"), base.join("Zed"));
     std::fs::create_dir_all(&dir_a).unwrap();
     std::fs::create_dir_all(&dir_b).unwrap();
 
@@ -560,7 +616,10 @@ fn state_mode_ordering_survives_the_row_key_split() {
     }
 
     let (a, b) = (app.dir_label(&dir_a), app.dir_label(&dir_b));
-    assert!(a < b, "dir a must sort before dir b for this test to bite");
+    assert!(
+        b < a,
+        "byte order must put dir b first, or this test cannot see the collation"
+    );
     assert_eq!(
         app.section_ids(),
         vec![
@@ -961,6 +1020,29 @@ fn picker_puts_current_dir_first_and_selected() {
     assert_eq!(app.dir_candidates[0].path, app.invocation_dir);
 }
 
+/// Subdirectory rows collate case-insensitively, matching the case-insensitive
+/// prefix filter above them. `read_dir` yields entries in arbitrary order, so
+/// this also pins the panel's determinism. The names differ by more than case:
+/// APFS is case-insensitive by default, so `API` and `api` cannot coexist as
+/// directories on this machine.
+#[test]
+fn list_dirs_collates_case_insensitively() {
+    let base = temp("app_list_dirs_collate");
+    for name in ["Zed", "apple", "Beta", "cider"] {
+        std::fs::create_dir_all(base.join(name)).unwrap();
+    }
+    // A file is not a directory row, and neither is a dotfile.
+    std::fs::write(base.join("Alpha.txt"), b"x").unwrap();
+    std::fs::create_dir_all(base.join(".hidden")).unwrap();
+
+    assert_eq!(
+        list_dirs(&base, ""),
+        vec!["apple", "Beta", "cider", "Zed"],
+        "byte order would read Beta, Zed, apple, cider"
+    );
+    let _ = std::fs::remove_dir_all(&base);
+}
+
 /// Focus is by id, so it points at the same task even after the list shifts
 /// (a lower-id task is removed) and reports gone once it's removed.
 #[test]
@@ -1547,7 +1629,7 @@ fn group_picker_opens_on_g_only_with_a_selection() {
     assert_eq!(app.group_target, Some(1));
 }
 
-/// Picker candidates are distinct byte-sorted groups after Unassigned, with
+/// Picker candidates are the distinct groups, collated, after Unassigned, with
 /// the target's assignment marked "(current)".
 #[test]
 fn group_candidates_are_distinct_sorted_and_marked() {
@@ -1582,6 +1664,41 @@ fn group_candidates_are_distinct_sorted_and_marked() {
     assert_eq!(app.group_candidates[0].label, "Unassigned (current)");
 }
 
+/// The picker's group rows collate case-insensitively, matching the filter that
+/// already lowercases both sides. Unassigned stays pinned at row 0, and `API`
+/// and `api` both survive: the sort orders, `dedup` still removes only exact
+/// duplicates.
+#[test]
+fn group_candidates_collate_case_insensitively() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_grouped("sleep 5", inv.clone(), "zebra"); // id 1
+    app.spawn_grouped("sleep 5", inv.clone(), "API"); // id 2
+    app.spawn_grouped("sleep 5", inv.clone(), "Review"); // id 3
+    app.spawn_grouped("sleep 5", inv.clone(), "api"); // id 4
+    app.spawn_grouped("sleep 5", inv, "api"); // id 5, exact duplicate
+    app.pump();
+
+    app.selected_id = Some(1);
+    app.on_key_dashboard(key(KeyCode::Char('g')));
+    let groups: Vec<Option<&str>> = app
+        .group_candidates
+        .iter()
+        .map(|c| c.group.as_deref())
+        .collect();
+    assert_eq!(
+        groups,
+        vec![
+            None,
+            Some("API"),
+            Some("api"),
+            Some("Review"),
+            Some("zebra")
+        ],
+        "Unassigned pinned first; byte order would read API, Review, api, zebra"
+    );
+}
+
 /// Typing applies a case-insensitive prefix filter and selects the first
 /// match; Backspace expands the candidate set again.
 #[test]
diff --git a/src/format.rs b/src/format.rs
index fd7f6f8..5d905cd 100644
--- a/src/format.rs
+++ b/src/format.rs
@@ -75,6 +75,25 @@ pub fn pad(s: &str, width: usize) -> String {
     t
 }
 
+/// Sort key for a human-readable name: case-folded first, exact bytes second.
+///
+/// `String` orders byte-wise, so every uppercase ASCII letter sorts before every
+/// lowercase one and `API` lands at the opposite end of a list from `api`, with
+/// everything else in between. Folding with `to_lowercase` — Unicode-aware, in
+/// std, no locale — puts them side by side. The exact name then breaks the tie,
+/// so two names differing only by case hold one fixed order across every render
+/// instead of an unspecified one.
+///
+/// The key never merges: distinct names produce distinct keys, so collation
+/// changes display order and nothing else. Identity comparisons stay exact.
+///
+/// Call-site details: each call allocates two `String`s, so compute the key once
+/// per element — `sort_by_cached_key`, or store it in the value being sorted —
+/// never inside a comparator, which would rebuild it O(n log n) times.
+pub(crate) fn collation_key(name: &str) -> (String, String) {
+    (name.to_lowercase(), name.to_string())
+}
+
 /// Convert days since 1970-01-01 to a proleptic Gregorian date.
 pub(crate) fn civil_from_days(days: i64) -> (i64, u32, u32) {
     let z = days + 719_468;
@@ -149,6 +168,43 @@ mod tests {
         assert_eq!(pad("e\u{0301}", 3), "e\u{0301}  ");
     }
 
+    #[test]
+    fn collation_key_folds_then_breaks_ties_on_exact_bytes() {
+        assert_eq!(collation_key("API"), ("api".to_string(), "API".to_string()));
+        // Folded first: `api` beats `Zebra`, which byte order reverses.
+        assert!(collation_key("api") < collation_key("Zebra"));
+        // Exact bytes second: same fold, so the tiebreak decides, and it is
+        // total — the two keys are never equal, so a sort cannot merge them.
+        assert!(collation_key("API") < collation_key("api"));
+        assert_ne!(collation_key("API"), collation_key("api"));
+        // Folding is Unicode-aware, not ASCII-only.
+        assert_eq!(collation_key("ÉCOLE").0, "école");
+    }
+
+    #[test]
+    fn collation_is_deterministic_regardless_of_input_order() {
+        fn collate(mut v: Vec<&str>) -> Vec<&str> {
+            v.sort_by_cached_key(|s| collation_key(s));
+            v
+        }
+        let want = vec!["API", "api", "Apple", "banana", "Zebra"];
+        assert_eq!(
+            collate(vec!["Zebra", "api", "API", "banana", "Apple"]),
+            want
+        );
+        assert_eq!(
+            collate(vec!["API", "Apple", "banana", "api", "Zebra"]),
+            want
+        );
+        assert_eq!(collate(want.clone()), want, "already sorted is a fixpoint");
+
+        // The defect this replaces: byte order strands API and Apple at the
+        // far end of the list from api.
+        let mut bytewise = vec!["Zebra", "api", "API", "banana", "Apple"];
+        bytewise.sort();
+        assert_eq!(bytewise, vec!["API", "Apple", "Zebra", "api", "banana"]);
+    }
+
     #[test]
     fn civil_from_days_matches_known_dates() {
         assert_eq!(civil_from_days(0), (1970, 1, 1));
diff --git a/src/session.rs b/src/session.rs
index 57342d6..52c05c2 100644
--- a/src/session.rs
+++ b/src/session.rs
@@ -280,8 +280,8 @@ pub fn load_in(dir: &Path, name: &str) -> io::Result<SessionConfig> {
     from_json(&fs::read_to_string(file)?).map(|(_, cfg)| cfg)
 }
 
-/// Return sorted recipe names under `dir`. Wrapped files use their stored name;
-/// flat files use the filename stem.
+/// Return recipe names under `dir`, collated case-insensitively. Wrapped files
+/// use their stored name; flat files use the filename stem.
 pub fn list_in(dir: &Path) -> Vec<String> {
     let mut names = Vec::new();
     if let Ok(entries) = fs::read_dir(dir) {
@@ -298,7 +298,7 @@ pub fn list_in(dir: &Path) -> Vec<String> {
             }
         }
     }
-    names.sort();
+    names.sort_by_cached_key(|n| crate::format::collation_key(n));
     names
 }
 
@@ -499,6 +499,26 @@ mod tests {
         let _ = fs::remove_dir_all(&dir);
     }
 
+    /// The `o` picker's saved list collates case-insensitively: byte order
+    /// would read `Beta, Zed, apple`, stranding every capitalized name ahead of
+    /// every lowercase one. The names differ by more than case because APFS is
+    /// case-insensitive by default, so `API.json` and `api.json` cannot coexist
+    /// on this machine.
+    #[test]
+    fn list_in_collates_case_insensitively() {
+        let dir = temp("session_list_collate");
+        let mut cfg = SessionConfig::new();
+        cfg.insert("/tmp".into(), vec![e("top")]);
+        for name in ["Zed", "apple", "Beta"] {
+            save_in(&dir, name, &cfg).unwrap();
+        }
+        assert_eq!(
+            list_in(&dir),
+            vec!["apple".to_string(), "Beta".to_string(), "Zed".to_string()]
+        );
+        let _ = fs::remove_dir_all(&dir);
+    }
+
     /// Mixed string and object entries survive one serialization round trip.
     #[test]
     fn round_trips_mixed_grouped_and_ungrouped_entries() {

From bf5a3aeb38f3da528fbb23c457254160120b0f45 Mon Sep 17 00:00:00 2001
From: Christopher Sardegna <github@reagentx.net>
Date: Thu, 30 Jul 2026 19:09:33 -0700
Subject: [PATCH 6/7] fix(test): version the scratch prefix so legacy names are
 never swept

---
 src/testutil.rs | 45 ++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 38 insertions(+), 7 deletions(-)

diff --git a/src/testutil.rs b/src/testutil.rs
index 21caa06..197c226 100644
--- a/src/testutil.rs
+++ b/src/testutil.rs
@@ -18,9 +18,18 @@ use std::{
 use crate::{emulator::Emulator, format::civil_from_days};
 
 /// Scratch-directory name prefix, shared by creation and the sweep.
-const SCRATCH_PREFIX: &str = "fleetcom_test_";
-
-/// Create an empty `fleetcom_test_<tag>_<pid>_<seq>` directory under the system
+///
+/// The `2` is a format version. Release-era names were
+/// `fleetcom_test_<tag>_<pid>`, with no sequence field, and a tag whose own name
+/// ends in digits makes the two shapes indistinguishable when read from the
+/// right: legacy `fleetcom_test_app_1007_456` parses as pid 1007 and seq 456,
+/// when 456 is the real owner. Sweeping on that misread deletes scratch
+/// belonging to a live process. The versioned prefix is disjoint from the old
+/// one — the byte after `fleetcom_test` is `2`, never `_` — so a legacy name
+/// cannot reach the parser at all.
+const SCRATCH_PREFIX: &str = "fleetcom_test2_";
+
+/// Create an empty `fleetcom_test2_<tag>_<pid>_<seq>` directory under the system
 /// temp directory. The PID separates test processes, and the sequence separates
 /// calls within one process. Any existing path with the same name is removed.
 pub(crate) fn temp(tag: &str) -> PathBuf {
@@ -48,16 +57,24 @@ fn sweep_dead_scratch() {
         };
         for entry in entries.flatten() {
             let name = entry.file_name();
-            let Some(suffix) = name.to_str().and_then(|n| n.strip_prefix(SCRATCH_PREFIX)) else {
-                continue;
-            };
-            if scratch_pid(suffix).is_some_and(pid_is_dead) {
+            if name
+                .to_str()
+                .and_then(scratch_pid_of)
+                .is_some_and(pid_is_dead)
+            {
                 let _ = fs::remove_dir_all(entry.path());
             }
         }
     });
 }
 
+/// Parse the owning PID from a whole scratch directory name, or `None` when the
+/// name is not one of ours. The prefix check is the version gate: release-era
+/// `fleetcom_test_` names fail it, so they are never parsed and never swept.
+fn scratch_pid_of(name: &str) -> Option<i32> {
+    scratch_pid(name.strip_prefix(SCRATCH_PREFIX)?)
+}
+
 /// Parse the `<pid>` from a `<tag>_<pid>_<seq>` scratch suffix. Tags contain
 /// underscores, so both trailing fields are read from the right.
 fn scratch_pid(suffix: &str) -> Option<i32> {
@@ -90,6 +107,20 @@ fn scratch_pid_reads_the_pid_field() {
     assert_eq!(scratch_pid("tag_0_4"), None);
 }
 
+/// A release-era name never reaches the parser, so it is never swept. Read from
+/// the right, legacy `fleetcom_test_app_1007_456` looks like pid 1007 and seq
+/// 456 — 1007 being the tag's own digits, from the DECSET-1007 test — while 456
+/// is the process that actually owns the directory. Sweeping on that misread
+/// would delete scratch out from under a live test run.
+#[test]
+fn legacy_scratch_names_are_rejected_by_the_prefix() {
+    assert_eq!(scratch_pid_of("fleetcom_test_app_1007_456"), None);
+    assert_eq!(scratch_pid_of("fleetcom_test_tag_123"), None);
+    // The current format still parses, and to the pid rather than the tag.
+    assert_eq!(scratch_pid_of("fleetcom_test2_app_1007_456_0"), Some(456));
+    assert_eq!(scratch_pid_of("unrelated_dir_123_4"), None);
+}
+
 /// Poll `pred` until it holds or `budget` elapses; returns the final answer.
 /// `pred` always runs at least once.
 pub(crate) fn wait_until(budget: Duration, mut pred: impl FnMut() -> bool) -> bool {

From d688a75d520492b8af13cc3a65a5dcd65af99d6f Mon Sep 17 00:00:00 2001
From: Christopher Sardegna <github@reagentx.net>
Date: Thu, 30 Jul 2026 19:20:52 -0700
Subject: [PATCH 7/7] docs: update README, commands, and how-it-works for
 clarity and consistency; improve task sorting descriptions

---
 docs/README.md       | 12 +++---
 docs/commands.md     | 18 ++++-----
 docs/how-it-works.md |  4 +-
 src/app.rs           | 81 ++++++++++++---------------------------
 src/app_tests.rs     | 90 ++++++++++++++------------------------------
 src/format.rs        | 28 ++++----------
 src/session.rs       |  6 +--
 src/testutil.rs      | 35 ++++-------------
 src/ui.rs            |  7 +---
 9 files changed, 89 insertions(+), 192 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 1ad66dc..eace472 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,7 +8,7 @@
 - [How it works](how-it-works.md): the PTY emulation, input routing, and activity grouping
 - [Sessions](sessions.md): the task recipe format and where it lives
 - [Agent session resume](agent-resume.md): how `fleetcom` captures and resumes supported `claude`, `codex`, and `grok` sessions
-- [Storage paths](#storage-paths): the socket, the lock, and the session paths
+- [Storage paths](#storage-paths): runtime and session paths
 - [First-run walkthrough](#first-run-walkthrough): a first run, start to finish
 - [Security](#security): the trust boundary, on-disk state, and what is not protected
 - [Operational constraints](#operational-constraints): process and protocol boundaries
@@ -25,9 +25,9 @@ From a repository clone:
 
 ## Storage paths
 
-Runtime state contains the daemon socket and lock. Configuration contains durable session recipes. The paths resolve independently.
+Runtime state contains the daemon socket, lock, and log. Configuration contains durable session recipes. The paths resolve independently.
 
-### Runtime directory (socket + lock)
+### Runtime directory (socket + lock + log)
 
 The runtime directory holds `default.sock`, the client↔daemon socket; `daemon.lock`, the single-instance `flock`; and `daemon.log`, the stderr of an autostarted daemon. The daemon records its PID in the lock file; `--kill` uses that PID rather than waiting for the socket. [Security](#security) documents the permissions and the ownership checks this directory must satisfy.
 
@@ -107,7 +107,7 @@ Each row is `glyph · tag · command · latest output · age`. The age counts fr
   ✻  npm run dev              VITE v5.0  ready in 312 ms        1m
 ```
 
-`s` cycles through state, directory, and custom grouping. The header renders the active mode in bold. In custom mode, `g` assigns the selected task to a named group. Named sections sort by name and ignore case, so `API` files next to `api` rather than ahead of every lowercase name; the two remain separate sections, because group identity stays case-sensitive. Unassigned appears last when at least one task has no group:
+`s` cycles through state, directory, and custom grouping. The header renders the active mode in bold. In custom mode, `g` assigns the selected task to a named group. Named sections sort without regard to case, so `API` and `api` are adjacent. They remain separate because group identity is case-sensitive. Unassigned appears last when at least one task has no group:
 
 ```text
   fleetcom   2 running · 0 idle · 0 done      by state · dir · custom
@@ -145,7 +145,7 @@ The attached status bar shows both: `[attached] api tests · cargo watch -x test
 
 | Path | Mode | Contents |
 | -- | -- | -- |
-| [runtime directory](#runtime-directory-socket--lock) | `0700` | the socket, lock, daemon log, and any capture roots resolved beneath it |
+| [runtime directory](#runtime-directory-socket--lock--log) | `0700` | the socket, lock, daemon log, and any capture roots resolved beneath it |
 | `<runtime>/default.sock` | `0600` | the client↔daemon socket |
 | `<runtime>/daemon.lock` | `0666 & ~umask` when new; otherwise unchanged | the owning daemon's PID, trustworthy only while its `flock` is held |
 | `<runtime>/daemon.log` | `0666 & ~umask` when new; otherwise unchanged | stderr from the autostarted daemon |
@@ -187,7 +187,7 @@ Because the daemon holds each PTY master, daemon termination closes the terminal
 
 ### Environment and directory
 
-Each launch uses the launching client's environment and working directory, sent once per connection during the hello handshake. Connect from a venv terminal and your spawns, reruns, and session loads all see that venv, whichever client originally autostarted the daemon. [Security](#security) covers what that context does and does not persist.
+Each client sends its environment and working directory once during the connection handshake. Spawns, reruns, and session loads initiated by that client use the same launch context. [Security](#security) covers what persists.
 
 ### Scrollback depth is fixed per supervisor
 
diff --git a/docs/commands.md b/docs/commands.md
index 773d091..29df21e 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -119,14 +119,14 @@ A `TERM`-ignoring member can also survive when its leader exits during shutdown.
 `s` cycles three grouping modes: state, dir, custom. The header shows the strip `by state · dir · custom` with the active mode bold and the rest dim.
 
 - By state: In use / Running / Idle / Completed. A running task files under Idle after 10 s without output; Completed stays one section (`✓`/`✗` show exit status).
-- By dir: one section per working directory; the invocation directory first, the rest sorted by name.
-- By custom group: one section per group name, sorted by name, with Unassigned last. Fresh spawns remain unassigned unless they inherit a group, and the Unassigned section exists only while it has a member.
+- By dir: one section per working directory; the invocation directory first, then the remaining labels sorted without regard to case.
+- By custom group: one section per group name, sorted without regard to case, with Unassigned last. Fresh spawns remain unassigned unless they inherit a group, and the Unassigned section exists only while it has a member.
 
-Every name sort ignores case, section labels and the within-section directory tiebreak alike: `API` files next to `api`, not ahead of every lowercase name. Names differing only by case sort adjacent and stay distinct — group comparison remains case-sensitive, so `API` and `api` are two sections, in a fixed order that does not shift between renders.
+Dashboard section labels and within-section directory tiebreaks use the same case-insensitive order. Names that differ only by case sort next to each other in a deterministic order. Group identity remains case-sensitive, so `API` and `api` stay separate sections.
 
 Groups belong to task state: an assignment survives client detach and rerun (`r`), and switching grouping modes does not modify it. `g` reassigns the selected task through the [group picker](#the-g-group-picker).
 
-`m` toggles the "in use" tag and marks the task with `◆`. In state mode, tagged tasks form the In use section at the top. In custom mode, a tag moves the task to the top of its existing group rather than creating a global section. Within a dir or custom section, the order is tagged, live, completed; each bucket then sorts by directory and spawn order. The idle transition is absent from that order by design: it reverses on its 10-second timer, so ranking on it moved a row twice per interaction, both times off screen. A task that goes quiet keeps its row and shows `∙`. State mode still separates Running from Idle, because there the split is the section, not the row order.
+`m` toggles the "in use" tag and marks the task with `◆`. In state mode, tagged tasks form the In use section at the top. In custom mode, a tag moves the task to the top of its existing group rather than creating a global section. Within a dir or custom section, tasks sort as tagged, live, then completed; each class then sorts by directory and spawn order. Idle state does not affect row order in these modes, so a quiet task keeps its position and shows `∙`. State mode instead moves quiet tasks from Running to Idle.
 
 In custom mode only, a new command inherits the selected task's group, through both `n` and the `@` picker. The spawn prompt shows the destination as `❯ dir ▸ group ▸ command`, each segment present only when it applies: the dir segment for a non-default directory, the group segment when a group will be inherited. State- and dir-mode spawns start unassigned.
 
@@ -150,17 +150,17 @@ Typing filters the rows; `Backspace` deletes one character and the matches re-fi
 
 ## The `/` find palette
 
-`/` opens a bottom panel over the dashboard listing the tasks that match what you type. Each row reads `<glyph> <label> · <section>`: the task's status glyph, its name (or its command when unnamed), and the section it currently sits in. Empty input lists the whole fleet, and every list is in dashboard order, so the panel reads the same way as the list behind it. With no tasks, `/` does nothing.
+`/` opens a bottom panel listing tasks that match the query. Each row reads `<glyph> <label> · <section>`: the status glyph, display name (or command when unnamed), and current section. Empty input lists the whole fleet. Results follow dashboard order. With no tasks, `/` does nothing.
 
-Matching is a case-insensitive substring of three fields: name, command, and group. Substring, not prefix: `eep` finds `sleep 5`. A name adds a field rather than replacing one, so a task renamed `api tests` is still reachable by typing `cargo`.
+Matching checks case-insensitive substrings in the name, command, and group. For example, `eep` finds `sleep 5`. A display name adds a searchable field without replacing the command, so a task named `api tests` can still match `cargo`.
 
-The working directory is not matched. In a monorepo every task shares one directory, and cross-repo tasks often carry `~` as their base, so the directory separates nothing.
+The working directory is not a match field.
 
-`Enter` moves the dashboard selection to the highlighted task and closes the panel. It does not attach: `Enter` attaches from the dashboard, so `/api` `Enter` `Enter` attaches and `/api` `Enter` `Space` peeks. With nothing matched, `Enter` leaves the panel open so the query can be corrected. `↑`/`↓` move the highlight; `Esc` closes and leaves the selection where it was. The palette changes nothing else: no task is spawned, tagged, grouped, renamed, or killed through it.
+`Enter` moves the dashboard selection to the highlighted task and closes the panel; it does not attach. Press `Enter` again from the dashboard to attach, or `Space` to peek. With no matches, `Enter` leaves the panel open. `↑`/`↓` move the highlight. `Esc` closes the panel without changing the selection.
 
 ## The `g` group picker
 
-`g` on a selected task opens a bottom panel with the same structure as the `@` picker: a typed-name field plus the matching rows. Row 0 is always Unassigned, so the list is never empty; the fleet's existing group names follow, sorted ignoring case to match the filter, filtered by case-insensitive prefix as you type. The task's current group is marked `(current)`.
+`g` on a selected task opens a bottom panel with a typed-name field and matching rows. Row 0 is always Unassigned, so the list is never empty. Existing group names follow in case-insensitive order and are filtered by case-insensitive prefix. The task's current group is marked `(current)`.
 
 `Enter` acts on the highlighted row, and the hint line names the action:
 
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 48d9a79..cc4230c 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -6,8 +6,8 @@ Every task runs in its own pseudo-terminal, emulated with `alacritty_terminal`.
 
 ## Input fidelity
 
-Attached input follows the terminal modes reported by the child. Modified Enter becomes `ESC CR` when the terminal reports the modifier. Paste receives bracketed-paste markers only when the child enables them. Mouse events go to children that request a mouse protocol. Full-screen children receive alternate-scroll input only while DECSET 1007 is enabled; otherwise `fleetcom` suppresses wheel events. Each task retains 2,000 lines of scrollback. For inline children, wheel-up or `Shift+PageUp` enters history; paging keys navigate it, while `Esc` or ordinary input returns to live output. [`commands.md`](commands.md) documents the exact routing rules.
+Attached input follows the terminal modes reported by the child. Modified Enter becomes `ESC CR` when the terminal reports the modifier. Paste receives bracketed-paste markers only when the child enables them. Mouse events go to children that request a mouse protocol. Full-screen children receive alternate-scroll input only while DECSET 1007 is enabled; otherwise `fleetcom` suppresses wheel events. Each task retains 2,000 lines of scrollback by default; the supervisor can set another depth at startup. For inline children, wheel-up or `Shift+PageUp` enters history; paging keys navigate it, while `Esc` or ordinary input returns to live output. [`commands.md`](commands.md) documents the exact routing rules.
 
 ## Grouping follows one activity window
 
-The dashboard groups tasks by state (In use / Running / Idle / Completed), working directory, or names assigned with `g`. One 10-second window drives both idle signals: after 10 s without output, the row glyph changes from `✻` to `∙` and, under state grouping, the task moves to the Idle section in the same refresh. Row order within a section never consults that transition, because it reverses on the same timer: a task that goes quiet holds its row. A tool such as `top`, which prints every 1–2 s, never crosses the window, so it stays `✻` under Running. The preview text holds separately: a status from a weaker source must persist for 600 ms before it replaces a stronger one, which absorbs repaint flicker without affecting grouping.
+The dashboard groups tasks by state (In use / Running / Idle / Completed), working directory, or names assigned with `g`. One 10-second window drives both idle signals: after 10 s without output, the row glyph changes from `✻` to `∙` and, under state grouping, the task moves to the Idle section in the same refresh. Idle state does not affect row order within directory or custom sections. A tool such as `top`, which prints every 1–2 s, never crosses the window, so it stays `✻` under Running. Preview text is independent: a status from a weaker source must persist for 600 ms before it replaces a stronger one, which absorbs repaint flicker without affecting grouping.
diff --git a/src/app.rs b/src/app.rs
index 33b3822..2599b6e 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -86,7 +86,7 @@ pub enum Mode {
     PickDir,
     /// Live group picker (the `g` flow) that reassigns the selected task's group.
     PickGroup,
-    /// Live find palette (the `/` flow) that jumps the selection to a task.
+    /// Find palette for selecting a task from filtered results.
     Find,
     /// Typing a name to save the current tasks as a session.
     SaveSession,
@@ -222,9 +222,8 @@ pub struct App {
     group_target: Option<u64>,
     // `/` find-palette state (only meaningful in `Mode::Find`).
     pub find_input: EditBuffer,
-    /// Matching task *ids*, in display order. Ids, not `views` indices: a
-    /// daemon snapshot can land while the panel is open and reorder `views`,
-    /// which would point a stored index at a different task.
+    /// Matching task IDs in display order. IDs remain stable if a daemon
+    /// snapshot reorders `views` while the palette is open.
     pub find_candidates: Vec<u64>,
     pub find_sel: usize,
     /// Task ID captured when the rename prompt opens.
@@ -300,12 +299,9 @@ fn step_down(sel: usize, len: usize) -> usize {
     (sel + 1).min(len.saturating_sub(1))
 }
 
-/// State-grouping section identity: 0 In use, 1 Running, 2 Idle, 3 Completed.
-/// Tagged wins over everything; completed is classified by `lifecycle`, never
-/// by trusting `parked == false`, so a core that ever shipped both signals
-/// still lands finished tasks in Completed. The Running/Idle split follows
-/// `parked`, the core's debounced quiet signal: it shares the 10 s window with
-/// `Lifecycle::Idle`, so the idle glyph and the row's section flip together.
+/// State-section order: In use, Running, Idle, then Completed.
+/// Tags take precedence, completion follows `lifecycle`, and live tasks use
+/// `parked` to distinguish Running from Idle.
 fn section_rank(v: &TaskView) -> u8 {
     if v.tagged {
         0
@@ -318,18 +314,9 @@ fn section_rank(v: &TaskView) -> u8 {
     }
 }
 
-/// Within-section row order: 0 tagged, 1 live, 2 finished. Applies in every
-/// grouping mode. Finished is classified by `lifecycle`, for the same reason
-/// `section_rank` does it that way.
-///
-/// `parked` is deliberately absent. It reverses on a 10 s timer, so ranking on
-/// it moved a row twice per interaction: up the moment the child echoed a
-/// keystroke, back down ten seconds after the typing stopped. Both moves landed
-/// while the user was attached to some other task, so the dashboard they
-/// returned to had silently reindexed itself — worst for the tasks they touched
-/// most. A row's rank now moves only on a monotonic edge (`finished`) or a
-/// deliberate one (`tagged`). The idle signal keeps its glyph, and in State mode
-/// its own section.
+/// Within-section row order: tagged, live, then finished.
+/// `parked` does not affect row order, so transitions between active and idle
+/// preserve a task's position outside state grouping.
 fn row_rank(v: &TaskView) -> u8 {
     if v.tagged {
         0
@@ -542,7 +529,7 @@ impl App {
                     }
                     GroupMode::Dir => {
                         let label = self.dir_label(&v.cwd);
-                        // Invocation dir sorts first; the rest collate by name.
+                        // Keep the invocation directory first.
                         let rank = if label == self.invocation_label { 0 } else { 1 };
                         (rank, label)
                     }
@@ -552,16 +539,11 @@ impl App {
                         None => (1, "Unassigned".to_string()),
                     },
                 };
-                // Within each section: tagged first, finished last, then
-                // directory, then task id. In State mode `row_rank` is constant
-                // across a section (the section *is* the bucket), so it drops
-                // out and the order stays directory-then-id.
+                // Within each section, sort by row rank, directory, then task ID.
                 (rank, label, row_rank(v), self.dir_label(&v.cwd), v.id, i)
             })
             .collect();
-        // Both strings are human-readable names, so both collate. `cached_key`
-        // builds each element's key once; a comparator would rebuild it on
-        // every comparison.
+        // Apply the same case-insensitive collation to section and directory labels.
         labeled.sort_by_cached_key(|(rank, label, row, dir, id, i)| {
             (
                 *rank,
@@ -573,8 +555,7 @@ impl App {
             )
         });
 
-        // Section boundaries compare the exact label, never the folded one:
-        // `API` and `api` sort adjacent and stay two sections.
+        // Case-distinct labels sort together but remain separate sections.
         let mut out: Vec<(String, Vec<usize>)> = Vec::new();
         for (_, label, _, _, _, i) in labeled {
             match out.last_mut() {
@@ -1035,8 +1016,7 @@ impl App {
             .filter(|g| g.to_lowercase().starts_with(&needle))
             .collect();
         names.sort_by_cached_key(|g| collation_key(g.as_str()));
-        // Exact duplicates share a key and stay adjacent under a stable sort,
-        // so `dedup` still collapses them — and only them.
+        // The exact-name tiebreak keeps duplicates adjacent for `dedup`.
         names.dedup();
         for name in names {
             cands.push(GroupCand {
@@ -1069,8 +1049,7 @@ impl App {
 
     // --- `/` find palette -------------------------------------------------------
 
-    /// Open the `/` palette with the whole fleet listed. A no-op on an empty
-    /// fleet: there is nothing to find, so the panel would be a dead end.
+    /// Open the `/` palette with every task listed.
     fn open_find_palette(&mut self) {
         if self.views.is_empty() {
             return;
@@ -1080,8 +1059,7 @@ impl App {
         self.mode = Mode::Find;
     }
 
-    /// Rebuild the palette rows in display order, so the panel reads in the
-    /// same order as the list behind it, and highlight the first match.
+    /// Rebuild matches in dashboard order and select the first result.
     fn refresh_find_candidates(&mut self) {
         let needle = self.find_input.to_lowercase();
         self.find_candidates = self
@@ -1386,11 +1364,8 @@ impl App {
             KeyCode::Up => self.find_sel = self.find_sel.saturating_sub(1),
             KeyCode::Down => self.find_sel = step_down(self.find_sel, self.find_candidates.len()),
             KeyCode::Enter => {
-                // Enter moves the dashboard selection and nothing else. It
-                // deliberately does not attach: Enter attaches *from* the
-                // dashboard, so `/api` Enter Enter attaches and `/api` Enter
-                // Space peeks. With nothing matched the panel stays open, so a
-                // mistyped query can be corrected instead of being cancelled.
+                // Select the highlighted task without attaching. An empty
+                // result set leaves the palette open.
                 if let Some(&id) = self.find_candidates.get(self.find_sel) {
                     self.selected_id = Some(id);
                     self.close_find_palette();
@@ -1840,14 +1815,9 @@ fn on_key_edit(buf: &mut EditBuffer, k: KeyEvent) -> Option<bool> {
     }
 }
 
-/// Whether a task matches the find palette's lowercased `needle`: a
-/// case-insensitive substring of its name, command, or group. A named task
-/// still matches its command, so a task renamed "api tests" is found by typing
-/// `cargo`. The empty needle matches everything.
-///
-/// The working directory is deliberately absent. In a monorepo every task
-/// shares one directory and cross-repo tasks often carry `~` as their base, so
-/// the directory separates nothing and would only dilute the matches.
+/// Match a lowercased query against a task's name, command, or group.
+/// Matching is substring-based; an empty query matches every task. The working
+/// directory is not a match field.
 fn task_matches(v: &TaskView, needle: &str) -> bool {
     [
         v.name.as_deref(),
@@ -1875,9 +1845,9 @@ fn split_input(input: &str) -> (&str, &str) {
     }
 }
 
-/// Subdirectories of `base` whose name prefix-matches `partial` (case-
-/// insensitive), collated case-insensitively so the order matches the filter.
-/// Hidden entries appear only when `partial` starts `.`.
+/// Subdirectories of `base` whose names start with `partial`, ignoring case.
+/// Results use the same case-insensitive collation. Hidden entries appear only
+/// when `partial` starts with `.`.
 fn list_dirs(base: &Path, partial: &str) -> Vec<String> {
     let needle = partial.to_lowercase();
     let mut out: Vec<String> = Vec::new();
@@ -1896,8 +1866,7 @@ fn list_dirs(base: &Path, partial: &str) -> Vec<String> {
             }
         }
     }
-    // `read_dir` yields entries in arbitrary order, so this sort is also what
-    // makes the panel deterministic.
+    // `read_dir` order is unspecified.
     out.sort_by_cached_key(|n| collation_key(n));
     out
 }
diff --git a/src/app_tests.rs b/src/app_tests.rs
index d359bfd..1fa8058 100644
--- a/src/app_tests.rs
+++ b/src/app_tests.rs
@@ -125,11 +125,8 @@ fn dir_mode_groups_by_cwd() {
     assert_eq!(s[1].0, "/tmp");
 }
 
-/// Group sections collate case-insensitively. Byte order would read
-/// `API, Review, api, zebra`, stranding `API` at the opposite end of the list
-/// from `api`; folded order reads `API, api, Review, zebra`. The two `api`
-/// sections stay separate, because group identity remains case-sensitive:
-/// merging them would be a data bug, not a display change.
+/// Custom-group labels sort case-insensitively without merging case-distinct
+/// groups.
 #[test]
 fn custom_sections_collate_case_insensitively() {
     let mut app = App::new_local(30, 100);
@@ -153,8 +150,7 @@ fn custom_sections_collate_case_insensitively() {
     );
 }
 
-/// Dir-mode section labels collate too. `Zed` and `apple` discriminate: byte
-/// order puts `Zed` first, folded order puts `apple` first.
+/// Directory-section labels use case-insensitive collation.
 #[test]
 fn dir_sections_collate_case_insensitively() {
     let mut app = App::new_local(30, 100);
@@ -428,9 +424,7 @@ fn selection_follows_task_across_parked_rebucket() {
     assert_eq!(app.views[app.selected_task().unwrap()].id, 1);
 }
 
-/// Row order ignores `parked`, so going quiet does not move a task inside its
-/// Custom group. The flip reverses on the 10 s window; ranking on it made a row
-/// travel twice per interaction, out of sight of a user attached elsewhere.
+/// Idle state does not affect row order within a custom group.
 #[test]
 fn custom_mode_parked_task_holds_its_row() {
     let mut app = App::new_local(30, 100);
@@ -450,8 +444,7 @@ fn custom_mode_parked_task_holds_its_row() {
     );
 }
 
-/// Same guarantee one section wider: dir mode also holds a row through the
-/// quiet transition.
+/// Idle state does not affect row order within a directory section.
 #[test]
 fn dir_mode_parked_task_holds_its_row() {
     let mut app = App::new_local(30, 100);
@@ -472,8 +465,7 @@ fn dir_mode_parked_task_holds_its_row() {
     );
 }
 
-/// `parked` round trip: the row sits in the same place before, during, and
-/// after the quiet window. This is the property the sort key now guarantees.
+/// Entering and leaving idle state preserves row order.
 #[test]
 fn parked_round_trip_leaves_row_order_identical() {
     let mut app = App::new_local(30, 100);
@@ -494,8 +486,7 @@ fn parked_round_trip_leaves_row_order_identical() {
     assert_eq!(app.section_ids(), want, "waking does not move id 2 back");
 }
 
-/// Finished is monotonic, so it stays in the row key: a completed task sinks
-/// below its live siblings inside a Custom group.
+/// Completed tasks sort after live tasks within a custom group.
 #[test]
 fn custom_mode_finished_sinks_within_group() {
     let mut app = App::new_local(30, 100);
@@ -516,7 +507,7 @@ fn custom_mode_finished_sinks_within_group() {
     );
 }
 
-/// The same monotonic sink in dir mode.
+/// Completed tasks sort after live tasks within a directory section.
 #[test]
 fn dir_mode_finished_sinks_within_section() {
     let mut app = App::new_local(30, 100);
@@ -537,8 +528,7 @@ fn dir_mode_finished_sinks_within_section() {
     );
 }
 
-/// A tag is user-controlled, so it stays in the row key: the tagged task floats
-/// to the top of its Custom group and holds that row when it goes quiet.
+/// Tagged tasks sort first within a custom group, including while idle.
 #[test]
 fn custom_mode_tagged_task_floats_and_holds_while_parked() {
     let mut app = App::new_local(30, 100);
@@ -560,20 +550,13 @@ fn custom_mode_tagged_task_floats_and_holds_while_parked() {
     );
 }
 
-/// State mode is unchanged by the row-key split, because within a State section
-/// every member shares one `row_rank`: In use all tagged, Running and Idle all
-/// live, Completed all finished. A constant contributes nothing to the sort, so
-/// section order and within-section order (directory, then id) stand exactly as
-/// before. Asserting the whole shape catches a collapsed Running/Idle split or
-/// a `dir_label` dropped from the sort key.
+/// State mode orders In use, Running, Idle, and Completed sections, with rows
+/// ordered by directory then task ID.
 #[test]
 fn state_mode_ordering_survives_the_row_key_split() {
     let mut app = App::new_local(30, 100);
     let base = temp("app_state_order");
-    // `apple` and `Zed` disagree between the two collations — byte order puts
-    // `Zed` first, folded order puts `apple` first — so this test also locks
-    // the half of the collation change that State mode is not neutral to: the
-    // within-section `dir_label` tiebreak.
+    // Mixed-case paths make the directory tiebreak observable.
     let (dir_a, dir_b) = (base.join("apple"), base.join("Zed"));
     std::fs::create_dir_all(&dir_a).unwrap();
     std::fs::create_dir_all(&dir_b).unwrap();
@@ -599,10 +582,7 @@ fn state_mode_ordering_survives_the_row_key_split() {
     }
     app.pump();
 
-    // Pin `parked` in both directions after the last pump. Later than the last
-    // pump because a fresh core snapshot would overwrite it; both directions
-    // because ids 1, 2, and 5 print nothing, so on a loaded machine they would
-    // cross the real 10 s window and desert Running before the assert.
+    // Override the time-dependent idle state after the final snapshot.
     for (id, parked) in [
         (1u64, false),
         (2, false),
@@ -1020,18 +1000,14 @@ fn picker_puts_current_dir_first_and_selected() {
     assert_eq!(app.dir_candidates[0].path, app.invocation_dir);
 }
 
-/// Subdirectory rows collate case-insensitively, matching the case-insensitive
-/// prefix filter above them. `read_dir` yields entries in arbitrary order, so
-/// this also pins the panel's determinism. The names differ by more than case:
-/// APFS is case-insensitive by default, so `API` and `api` cannot coexist as
-/// directories on this machine.
+/// Subdirectory rows use the same case-insensitive order as their filter.
 #[test]
 fn list_dirs_collates_case_insensitively() {
     let base = temp("app_list_dirs_collate");
     for name in ["Zed", "apple", "Beta", "cider"] {
         std::fs::create_dir_all(base.join(name)).unwrap();
     }
-    // A file is not a directory row, and neither is a dotfile.
+    // Exclude files and hidden directories.
     std::fs::write(base.join("Alpha.txt"), b"x").unwrap();
     std::fs::create_dir_all(base.join(".hidden")).unwrap();
 
@@ -1629,8 +1605,8 @@ fn group_picker_opens_on_g_only_with_a_selection() {
     assert_eq!(app.group_target, Some(1));
 }
 
-/// Picker candidates are the distinct groups, collated, after Unassigned, with
-/// the target's assignment marked "(current)".
+/// Group candidates are distinct, case-insensitively sorted, and follow
+/// Unassigned. The target's group is marked "(current)".
 #[test]
 fn group_candidates_are_distinct_sorted_and_marked() {
     let mut app = App::new_local(30, 100);
@@ -1664,10 +1640,8 @@ fn group_candidates_are_distinct_sorted_and_marked() {
     assert_eq!(app.group_candidates[0].label, "Unassigned (current)");
 }
 
-/// The picker's group rows collate case-insensitively, matching the filter that
-/// already lowercases both sides. Unassigned stays pinned at row 0, and `API`
-/// and `api` both survive: the sort orders, `dedup` still removes only exact
-/// duplicates.
+/// Group candidates sort case-insensitively while preserving case-distinct
+/// names and removing exact duplicates.
 #[test]
 fn group_candidates_collate_case_insensitively() {
     let mut app = App::new_local(30, 100);
@@ -1810,7 +1784,7 @@ fn group_esc_cancels_without_sending() {
 
 // --- `/` find palette ---------------------------------------------------
 
-/// Candidate ids for the current palette state.
+/// Candidate IDs for the current palette state.
 fn find_ids(app: &App) -> Vec<u64> {
     app.find_candidates.clone()
 }
@@ -1822,8 +1796,7 @@ fn find_type(app: &mut App, text: &str) {
     }
 }
 
-/// `/` needs tasks, not a selection: it no-ops on an empty fleet and opens
-/// before anything is selected.
+/// The find palette requires at least one task but no current selection.
 #[test]
 fn find_palette_opens_on_slash_only_with_tasks() {
     let mut app = App::new_local(30, 100);
@@ -1840,8 +1813,7 @@ fn find_palette_opens_on_slash_only_with_tasks() {
     assert_eq!(find_ids(&app), vec![1]);
 }
 
-/// Candidates arrive in display order, not id order: tagging id 3 floats it
-/// to the top of the list and to the top of the palette with it.
+/// Find candidates follow dashboard order rather than task-ID order.
 #[test]
 fn find_candidates_follow_display_order() {
     let mut app = App::new_local(30, 100);
@@ -1908,8 +1880,7 @@ fn find_matches_case_insensitive_substrings() {
     assert_eq!(find_ids(&app), vec![2], "matches mid-command of \"true\"");
 }
 
-/// A renamed task keeps matching its command: the name is another haystack,
-/// not a replacement for one.
+/// A named task matches both its display name and command.
 #[test]
 fn find_matches_a_named_task_on_both_fields() {
     let mut app = App::new_local(30, 100);
@@ -1946,8 +1917,7 @@ fn find_matches_group_names() {
     assert_eq!(find_ids(&app), vec![1]);
 }
 
-/// The working directory is not a match field: a task spawned in a uniquely
-/// named directory is unreachable by that name.
+/// Find does not match working-directory names.
 #[test]
 fn find_does_not_match_the_directory() {
     let mut app = App::new_local(30, 100);
@@ -1965,7 +1935,7 @@ fn find_does_not_match_the_directory() {
         find_ids(&app)
     );
 
-    // The same task is reachable through a field that is matched.
+    // The command remains searchable.
     app.on_key_find(key(KeyCode::Esc));
     app.on_key_dashboard(key(KeyCode::Char('/')));
     find_type(&mut app, "sleep");
@@ -2019,8 +1989,7 @@ fn find_esc_leaves_the_selection_alone() {
     assert_eq!(app.find_sel, 0);
 }
 
-/// Enter on an empty candidate list changes nothing and keeps the panel open,
-/// so a typo can be corrected in place.
+/// Enter with no candidates keeps the palette open and preserves selection.
 #[test]
 fn find_enter_without_candidates_keeps_the_panel_open() {
     let mut app = App::new_local(30, 100);
@@ -2036,7 +2005,7 @@ fn find_enter_without_candidates_keeps_the_panel_open() {
     assert!(app.mode == Mode::Find, "no match: Enter must not close");
     assert_eq!(app.selected_id, Some(1), "selection is untouched");
 
-    // Correcting the query recovers a match.
+    // Editing the query refreshes candidates.
     for _ in 0.."zzz".len() {
         app.on_key_find(key(KeyCode::Backspace));
     }
@@ -2044,8 +2013,7 @@ fn find_enter_without_candidates_keeps_the_panel_open() {
     assert_eq!(find_ids(&app), vec![1]);
 }
 
-/// The panel paints its rows as `<glyph> <label> · <section>`, and says so
-/// when a query matches nothing.
+/// Find rows include status, label, and section; empty results show a message.
 #[test]
 fn find_panel_rows_name_the_task_and_its_section() {
     let mut app = App::new_local(30, 100);
@@ -2072,7 +2040,7 @@ fn find_panel_rows_name_the_task_and_its_section() {
     assert!(frame.contains("(no matching tasks)"), "{frame:?}");
 }
 
-/// A paste lands in the palette field and re-filters, like the other pickers.
+/// Pasting into the find field refreshes its candidates.
 #[test]
 fn find_paste_filters_the_candidates() {
     let mut app = App::new_local(30, 100);
diff --git a/src/format.rs b/src/format.rs
index 5d905cd..519b66b 100644
--- a/src/format.rs
+++ b/src/format.rs
@@ -75,21 +75,9 @@ pub fn pad(s: &str, width: usize) -> String {
     t
 }
 
-/// Sort key for a human-readable name: case-folded first, exact bytes second.
-///
-/// `String` orders byte-wise, so every uppercase ASCII letter sorts before every
-/// lowercase one and `API` lands at the opposite end of a list from `api`, with
-/// everything else in between. Folding with `to_lowercase` — Unicode-aware, in
-/// std, no locale — puts them side by side. The exact name then breaks the tie,
-/// so two names differing only by case hold one fixed order across every render
-/// instead of an unspecified one.
-///
-/// The key never merges: distinct names produce distinct keys, so collation
-/// changes display order and nothing else. Identity comparisons stay exact.
-///
-/// Call-site details: each call allocates two `String`s, so compute the key once
-/// per element — `sort_by_cached_key`, or store it in the value being sorted —
-/// never inside a comparator, which would rebuild it O(n log n) times.
+/// Sort key for human-readable names.
+/// The lowercase value provides case-insensitive collation; the exact value
+/// makes ordering deterministic and keeps case-distinct names separate.
 pub(crate) fn collation_key(name: &str) -> (String, String) {
     (name.to_lowercase(), name.to_string())
 }
@@ -171,13 +159,12 @@ mod tests {
     #[test]
     fn collation_key_folds_then_breaks_ties_on_exact_bytes() {
         assert_eq!(collation_key("API"), ("api".to_string(), "API".to_string()));
-        // Folded first: `api` beats `Zebra`, which byte order reverses.
+        // The lowercase component controls primary ordering.
         assert!(collation_key("api") < collation_key("Zebra"));
-        // Exact bytes second: same fold, so the tiebreak decides, and it is
-        // total — the two keys are never equal, so a sort cannot merge them.
+        // The exact component orders names with the same lowercase value.
         assert!(collation_key("API") < collation_key("api"));
         assert_ne!(collation_key("API"), collation_key("api"));
-        // Folding is Unicode-aware, not ASCII-only.
+        // `to_lowercase` handles Unicode characters.
         assert_eq!(collation_key("ÉCOLE").0, "école");
     }
 
@@ -198,8 +185,7 @@ mod tests {
         );
         assert_eq!(collate(want.clone()), want, "already sorted is a fixpoint");
 
-        // The defect this replaces: byte order strands API and Apple at the
-        // far end of the list from api.
+        // Byte ordering produces a different order for mixed-case names.
         let mut bytewise = vec!["Zebra", "api", "API", "banana", "Apple"];
         bytewise.sort();
         assert_eq!(bytewise, vec!["API", "Apple", "Zebra", "api", "banana"]);
diff --git a/src/session.rs b/src/session.rs
index 52c05c2..37bcd31 100644
--- a/src/session.rs
+++ b/src/session.rs
@@ -499,11 +499,7 @@ mod tests {
         let _ = fs::remove_dir_all(&dir);
     }
 
-    /// The `o` picker's saved list collates case-insensitively: byte order
-    /// would read `Beta, Zed, apple`, stranding every capitalized name ahead of
-    /// every lowercase one. The names differ by more than case because APFS is
-    /// case-insensitive by default, so `API.json` and `api.json` cannot coexist
-    /// on this machine.
+    /// Saved session names use case-insensitive collation.
     #[test]
     fn list_in_collates_case_insensitively() {
         let dir = temp("session_list_collate");
diff --git a/src/testutil.rs b/src/testutil.rs
index 197c226..7a47ac3 100644
--- a/src/testutil.rs
+++ b/src/testutil.rs
@@ -17,21 +17,11 @@ use std::{
 
 use crate::{emulator::Emulator, format::civil_from_days};
 
-/// Scratch-directory name prefix, shared by creation and the sweep.
-///
-/// The `2` is a format version. Release-era names were
-/// `fleetcom_test_<tag>_<pid>`, with no sequence field, and a tag whose own name
-/// ends in digits makes the two shapes indistinguishable when read from the
-/// right: legacy `fleetcom_test_app_1007_456` parses as pid 1007 and seq 456,
-/// when 456 is the real owner. Sweeping on that misread deletes scratch
-/// belonging to a live process. The versioned prefix is disjoint from the old
-/// one — the byte after `fleetcom_test` is `2`, never `_` — so a legacy name
-/// cannot reach the parser at all.
+/// Versioned prefix for scratch directories eligible for sweeping.
 const SCRATCH_PREFIX: &str = "fleetcom_test2_";
 
-/// Create an empty `fleetcom_test2_<tag>_<pid>_<seq>` directory under the system
-/// temp directory. The PID separates test processes, and the sequence separates
-/// calls within one process. Any existing path with the same name is removed.
+/// Create an empty `<prefix><tag>_<pid>_<seq>` directory under the system temp
+/// directory. The PID separates processes; the sequence separates calls.
 pub(crate) fn temp(tag: &str) -> PathBuf {
     static SEQ: AtomicU32 = AtomicU32::new(0);
     sweep_dead_scratch();
@@ -45,10 +35,7 @@ pub(crate) fn temp(tag: &str) -> PathBuf {
     d
 }
 
-/// Remove scratch directories whose recorded processes no longer exist.
-///
-/// This runs once, before the current process creates its first directory, so
-/// this process's directories remain available for post-failure inspection.
+/// Once per process, remove scratch directories owned by dead processes.
 fn sweep_dead_scratch() {
     static ONCE: Once = Once::new();
     ONCE.call_once(|| {
@@ -68,9 +55,7 @@ fn sweep_dead_scratch() {
     });
 }
 
-/// Parse the owning PID from a whole scratch directory name, or `None` when the
-/// name is not one of ours. The prefix check is the version gate: release-era
-/// `fleetcom_test_` names fail it, so they are never parsed and never swept.
+/// Parse the owner PID from a scratch name in the current namespace.
 fn scratch_pid_of(name: &str) -> Option<i32> {
     scratch_pid(name.strip_prefix(SCRATCH_PREFIX)?)
 }
@@ -94,7 +79,7 @@ fn pid_is_dead(pid: i32) -> bool {
     matches!(kill(Pid::from_raw(pid), None), Err(Errno::ESRCH))
 }
 
-/// Accept the current suffix format and reject malformed fields.
+/// Parse valid suffixes and reject malformed PID or sequence fields.
 #[test]
 fn scratch_pid_reads_the_pid_field() {
     assert_eq!(scratch_pid("tag_with_underscores_123_4"), Some(123));
@@ -107,16 +92,12 @@ fn scratch_pid_reads_the_pid_field() {
     assert_eq!(scratch_pid("tag_0_4"), None);
 }
 
-/// A release-era name never reaches the parser, so it is never swept. Read from
-/// the right, legacy `fleetcom_test_app_1007_456` looks like pid 1007 and seq
-/// 456 — 1007 being the tag's own digits, from the DECSET-1007 test — while 456
-/// is the process that actually owns the directory. Sweeping on that misread
-/// would delete scratch out from under a live test run.
+/// Names outside the current namespace are ineligible for sweeping.
 #[test]
 fn legacy_scratch_names_are_rejected_by_the_prefix() {
     assert_eq!(scratch_pid_of("fleetcom_test_app_1007_456"), None);
     assert_eq!(scratch_pid_of("fleetcom_test_tag_123"), None);
-    // The current format still parses, and to the pid rather than the tag.
+    // Parse the PID field even when the tag ends in digits.
     assert_eq!(scratch_pid_of("fleetcom_test2_app_1007_456_0"), Some(456));
     assert_eq!(scratch_pid_of("unrelated_dir_123_4"), None);
 }
diff --git a/src/ui.rs b/src/ui.rs
index 8575806..9424fb0 100644
--- a/src/ui.rs
+++ b/src/ui.rs
@@ -619,9 +619,7 @@ fn render_pickgroup(out: &mut impl Write, app: &App) -> io::Result<()> {
     )
 }
 
-/// The `/` palette: a bottom panel with the typed text and the matching tasks,
-/// `find_sel` highlighted. Each row names the task and the section it sits in,
-/// so a jump is aimed at a known place in the list behind the panel.
+/// Render the `/` palette with matching tasks in dashboard order.
 fn render_find(out: &mut impl Write, app: &App) -> io::Result<()> {
     let sections = app.sections();
     let section_of = |id: u64| -> &str {
@@ -640,8 +638,7 @@ fn render_find(out: &mut impl Write, app: &App) -> io::Result<()> {
                 display_label(v),
                 section_of(id)
             ),
-            // A snapshot removed the task after the last refresh. Keep the row
-            // so the highlight still lines up with `find_candidates`.
+            // Preserve row alignment if a snapshot removed this task.
             None => String::new(),
         })
         .collect();