Copy: selections, picker, sticky Copy; Smart Folding folds long output

docs/design/terminal-workflow.md

@@ -0,0 +1,72 @@
+# Terminal workflow: making one command's result useful for the next
+
+Status: living design for the workflow initiative. Ledger: [docs/development/workflow-initiative-ledger.md](../development/workflow-initiative-ledger.md).
+
+NMSh already owns what most of these features need: a structured record per command (command text, stored
+output, exit code, duration, waits, lifecycle row, stable `startId`), its own viewport and hit-testing, a
+session service that owns the shell, the paste guard, and provider/tool integration. The work below builds on
+those records instead of the rendered screen.
+
+## What other terminals teach (and what NMSh takes)
+
+| System | Proven idea | Cumbersome / not for NMSh | NMSh decision |
+| --- | --- | --- | --- |
+| Warp | Blocks as the unit of copy/share; per-block actions; "copy output" without selecting | Blocks require Warp's own shell integration and editor model; sharing defaults toward its cloud | Already block-based. Copy/report/compare act on block records; nothing leaves the machine. |
+| Wave Terminal | Rich block widgets, file previews in place | Heavy UI per block; a second app model | Rejected: NMSh stays text-first; previews go to pager/editor handoffs. |
+| iTerm2 | Triggers (regex → action), semantic history (cmd-click paths), "copy output of last command" via shell integration | Regex triggers run automatically on output; easy to make unsafe | References are recognized lazily, offered on explicit invocation, never auto-run. |
+| Ghostty / WezTerm / Kitty | Hyperlinks (OSC 8), hints/quick-select modes that pick URLs/paths/hashes by keyboard | Mode-heavy key schemes | Keyboard "references in this block" list from the Actions menu; OSC 8 links already honoured. |
+| Zellij / tmux | Session persistence, panes; copy mode | NMSh is not a multiplexer | Keep the session service; integrate with tmux, do not replace it. |
+| Atuin | Context-rich history (cwd, exit, duration, session), fuzzy search | Separate history database and sync | NMSh already has a history provider for Atuin; pins/recipes reuse history and presets. |
+| Pueue | A daemon queue for background jobs, separate shells, logs | Loses the interactive shell's state (cwd, env, functions) | Distinct concept. NMSh's queue runs in the *same* shell; Pueue is an optional integration for detached jobs, not the queue. |
+| fzf / Television | Fast fuzzy pickers with preview | External process handoff | Native picker first; fzf/Television stay optional providers. |
+| Yazi | File manager with previews | A whole TUI | Handoff only (open a directory/file with it when installed). |
+| delta / bat | Readable diffs and highlighted sources | External binaries | Compare renders its own unified view; delta is an optional renderer when installed. |
+| Nushell | Structured data between commands | A different shell language | Out of scope: NMSh preserves the user's shell. |
+| Gum | Prompts for scripts (choose, confirm, input) | — | Must keep working: input awareness and passthrough already route keys to such prompts. |
+
+## Decisions and defaults
+
+| Capability | Default | Why |
+| --- | --- | --- |
+| `/copy` (Quick Copy), output only | Always available | Existing behaviour; fastest path. |
+| Completion status in copies | Off; `--status` per copy | The output is what people paste; status is opt-in context. |
+| Interactive copy picker | `/copy ui`, or Settings → Copy | Progressive disclosure. |
+| Copy as Report (Markdown, plain) | Explicit action (`--report`, picker, Actions) | Reports carry commands, paths, exit codes: shared deliberately. |
+| Report redaction | Offered in the review, never claimed complete | Heuristic; the person inspects the result. |
+| Compare output | Explicit action ("Compare output…", `/compare`) | Computed lazily, never per command. |
+| Reference recognition | Lazy, on Actions/hover; no decoration | Avoids noise and false confidence. |
+| Error navigation | On demand (`/find` filters, Actions) | Exit status is authoritative; text matches are hints. |
+| Pins and recipes | Explicit; nothing persisted otherwise | Never auto-run. |
+| Queue after failure/interrupt | Paused | Dependent commands must not run blindly. |
+| Paste | Never executes; batches are reviewed | Pasting is not execution. |
+| Clipboard-change suggestion | Opt-in where detection is cheap and private | No polling of contents; no history. |
+| Sticky block controls | Contextual: only while a block's header is scrolled away | No permanent buttons on every block. |
+| Animation | Minimal; obeys reduced motion | Restraint. |
+
+## Rejected or deferred
+
+- Automatic execution of clipboard, AI or output-derived commands: never.
+- Background AI interpretation of output; any AI dependency in these features.
+- Clipboard history or persistence; transmitting output anywhere.
+- A workflow engine: recipes are reviewed sequences fed to the existing queue.
+- A competing log analyzer: error navigation extends `/find`.
+- Embedded file manager or diff engine of our own beyond a small line diff for Compare (an LCS line diff
+  is a few dozen lines; delta renders when present).
+
+## Shared foundations
+
+- **Block identity:** every action names a block by `startId`; records that fail ownership checks after clears or
+  legacy restores are dropped (see transcript repair), so actions never land on recycled line positions.
+- **Provenance:** `output` is what the command wrote (NMSh lines inside a running block excluded);
+  `lifecycleText` is NMSh's completion row, kept separate; reports and copies compose from these.
+- **One action path:** mouse, keyboard, slash commands and menus call the same handlers (`copyRecords`,
+  `runBlockAction`, the queue's `QueueOp`s).
+- **Input ownership:** a program waiting for input owns Enter; NMSh never turns a reply into a queued command.
+- **Ephemeral by default:** pickers, staging and reviews hold data in memory only.
+
+## Limits stated plainly
+
+- Sticky controls exist in NMSh's viewport only; the terminal's own scrollback cannot be decorated.
+- Redaction is pattern-based; it will miss things. The review exists for that reason.
+- Clipboard-change detection depends on the platform. Reading the clipboard's contents to notice a change is
+  not acceptable; only a change signal that does not expose the text qualifies (decided in the clipboard slice).

docs/development/workflow-initiative-ledger.md

@@ -0,0 +1,81 @@
+# Terminal workflow initiative: ledger
+
+The durable record for the "make the result of one command useful for the next" initiative (queue, copy,
+paste, reports, comparison, references, error navigation, pins/recipes, integrations). A fresh session resumes
+from this file and Git, not from a conversation. Update it with every slice.
+
+Design and research: [docs/design/terminal-workflow.md](../design/terminal-workflow.md).
+
+## Rules this work keeps
+
+- The real shell is authoritative; NMSh never executes clipboard, AI or output-derived text without an explicit
+  submit or confirmation, and never runs a queued entry twice.
+- Copying reads stored command data; folding is presentation. Only "Auto-expand copied output" connects them.
+- Nothing is persisted (clipboard, pins, recipes) unless the person asks.
+- No merge to master, tag, release, deploy or change to real account configuration without explicit approval.
+- Commits and PRs carry no AI attribution lines (repository rule).
+
+## Branch stack (bottom to top)
+
+| Branch | Worktree | PR | State |
+| --- | --- | --- | --- |
+| `release/v0.18.0` | `/private/tmp/nmsh-rel-fix` | #345 | base of the stack; CI green |
+| `feature/input-awareness` | `../notMyShell-input-awareness` | #348 | timed-read test fixed (Ubuntu); lapsed-wait start fixed (macOS); CI re-running |
+| `feature/command-queue` | `../notMyShell-command-queue` | #357 (draft, base #348) | complete; full verify green when the machine is not saturated |
+| `feature/copy-selection` | `../notMyShell-copy` | #358 (draft, base #357) | copy selection, picker, settings, sticky controls, Smart folding fix |
+
+Other open PRs (independent, not part of this stack): #347 agent workspace, #349 notice word wrap, #346 mods.
+
+## Work completed
+
+| Slice | Commits | Evidence |
+| --- | --- | --- |
+| PR #348 Ubuntu failure: a timed `read -t` waits in poll/select, so Linux evidence is "probably" (test assumption) | `68ea9d7` | syscall unit test; live suite 30/30 |
+| PR #348 macOS failure: a lapsed prompt resumed as a new wait (product bug) | `c4c891e` | unit test pins same start, time counted once |
+| Command queue (session-owned, same shell, pause on failure/interrupt, detach-safe) | `b302cd9` | 13 live PTY tests zsh/Bash/Fish; unit + protocol tests |
+| Queue: exec events carry "from queue" so late-attaching windows show it | in `b302cd9` | detach/reattach live test |
+| Queue: a fresh prompt's reply is answered, never queued (security review) | in `b302cd9` | `read -s` live test |
+| Queue: Ctrl+Q compose mode never leaks Enter to the program | in `b302cd9` | key-input live test |
+| Queue: command text drawn safely (security review: escape injection) | `15147d1` | hostile-content unit test |
+| Queue: type-ahead after Ctrl+C/Ctrl+Z bounded to 2 s (security review: input routing) | `a257438` | surviving-program live test |
+| Live tests: a start that never becomes ready disposes its sandbox (was hanging the suite) | in `b302cd9` | — |
+| Copy: `/copy` and `/cp` N, -N, A-B, lists, `latest`, `ui`, `--status/--no-status` | `7a94ce5` | unit + 5 live PTY tests |
+| Copy settings (mode, include status, auto-expand); picker with search/preview | `7a94ce5` | unit, live, settings/setup coverage |
+| Direct block Copy + sticky Copy/Actions on the sticky header | `7a94ce5` | app-level tests; captures `docs/captures/sticky-*.png` |
+| Smart folding: long output folds whatever the command; important lines stay visible | `7a94ce5` | rewritten policy tests incl. 5/50/200/500/5000 lines, wrapped lines, errors mid-log |
+| Copy never changes folding; opt-in auto-expand of copied blocks only | `7a94ce5` | `tests/copyFolding.test.ts` |
+
+## Findings worth remembering
+
+- Smart folding root cause: the policy only folded output that looked noisy; varied diagnostics scored about 0
+  against a threshold of 3, and one "error" word anywhere vetoed folding. Now length decides above 120 lines.
+- `/copy` expanding a block could not be reproduced on release or this branch (app-level and PTY). Most likely
+  the block was never folded (the Smart bug). Regression tests now pin that no copy path changes fold state.
+- Full-suite failures while other heavy work runs on the machine (VHS recordings, parallel suites) are load
+  timeouts in startup/service tests; the same files pass 65/65 when run alone. Run `npm run verify` on an idle
+  machine before trusting a red result.
+- Known flake, still tracked: Fish can lose keys typed within ~1 s after a handed-over `read` returns
+  (docs/development/fish-typeahead.md).
+
+## Issues
+
+Epic #359. Slices: #350 folding/copy (fixed in #358), #351 report, #352 compare, #353 references and failure
+navigation, #354 paste batches and clipboard, #355 pins/recipes/queue conditions, #356 Fish type-ahead flake.
+
+## Next
+
+1. (done) Stack pushed; draft PRs #357, #358; issues filed.
+2. Phase B: Copy as Report (Markdown/plain, review + optional redaction), Compare output, contextual references,
+   error navigation.
+3. Paste batches → queue (`/ps`, syntax-aware splitting), clipboard-change suggestion (opt-in where detection is
+   reliable).
+4. Phase C: pins and recipes, queue conditions (manual approval).
+5. Phase D: integrations where they add value (delta for compare, fzf/Television preview).
+6. Integration branch for physical QA; prioritized QA checklist.
+
+## Physical QA needed (not yet done by a person)
+
+- Sticky Copy/Actions while scrolling long blocks; click targets in your terminal; "Copied" feedback.
+- `/copy ui` picker keys, search and preview at your usual window sizes.
+- Queue in daily use: Enter while a command runs, Ctrl+Q/Ctrl+S, a failing step pausing the rest.
+- Smart folding on your adb/diagnostic commands; the important-lines preview.

scripts/demos/sticky-controls.tape

@@ -0,0 +1,33 @@
+# Sticky block controls: one long command block at its beginning, middle and end, then the hand-off to the next block.
+# The controls ride on NMSh's own sticky header row (its viewport, not the terminal's native scrollback).
+Output docs/captures/sticky-controls.gif
+# demo-config: {"outputFolding": "never"}
+# demo-still: docs/captures/sticky-1-beginning.png 3.4s
+# demo-still: docs/captures/sticky-2-middle.png 6.4s
+# demo-still: docs/captures/sticky-3-end.png 9.4s
+# demo-still: docs/captures/sticky-4-transition.png 11.6s
+# demo-still: docs/captures/sticky-5-next-block.png 14.6s
+
+Hide
+Type "cd ~/Projects/demo && clear && nmsh"
+Enter
+Sleep 5s
+Type "seq -f 'build step %g of 300' 1 300"
+Enter
+Sleep 1.5s
+Type "seq -f 'test case %g passed' 1 40"
+Enter
+Sleep 1.5s
+Show
+
+Sleep 0.5s
+PageUp 11
+Sleep 2.4s
+PageDown 4
+Sleep 2.6s
+PageDown 4
+Sleep 2.6s
+PageDown 2
+Sleep 3s
+PageDown 1
+Sleep 4s