docs: record folding Stage 1 (#142) landing; open Stage 2 lane

Post-merge housekeeping owed from #142, kept as its own docs PR (no
runtime code).

- agent-handoff.md §1: bump main to c49a8c7, add the folding Stage 1
  substrate bullet (store/View, structural source, C-c @ surface,
  command-path unfold, FoldState production; no protocol bump), refresh
  the "Last updated" line and the roadmap Arc 6 entry, and note Stage 2
  is in framing on folding-tui (the visible-line-map reframe).
- active-work.md: retire the Stage 1 folding lane (PR #142 was OPEN),
  add a "Closed since the last snapshot" entry for #142, open the
  Stage 2 (grid/daemon collapse) framing lane on folding-tui, and
  refresh the canonical base snapshot to c49a8c7.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q5BkezMppbpCgGAYk2ftxV

docs/active-work.md

@@ -14,8 +14,8 @@ backlog.
   machine-local: `origin` may name this canonical URL, a release mirror,
   or something else, and therefore has no authority by name alone.
 - Canonical base at this snapshot:
-  `githubsucks/main` @ `63fbc66` (one-command GPU invocation #141 atop
-  documentation refresh #140; protocol v19).
+  `githubsucks/main` @ `c49a8c7` (folding Stage 1 #142 atop one-command GPU
+  invocation #141 and documentation refresh #140; protocol v19).
 - On the transfer source, `origin/main` named a release mirror at
   `d3fa632` and lagged badly. On the current destination, `origin` names
   the canonical URL. This difference is why all recovery begins by
@@ -49,43 +49,41 @@ git worktree list
 git status --short --branch
 ```
 
-The first command must expose `63fbc66` or a newer intentional main.
+The first command must expose `c49a8c7` or a newer intentional main.
 If it does not, stop and repair the remote/fetch configuration.
 
-## Folding framing lane (Arc 6)
+## Folding Stage 2 framing lane (Arc 6)
 
-- Portable branch: `githubsucks/folding`; worktree `../pmacs-folding`.
-- Base: **rebased onto canonical `main` @ `96d0bae`** at implementation
-  start (was `cac4961`; the earlier base fell behind the docs + tab-width
-  housekeeping).
-- Framing head: revision 5 of `docs/folding-framing.md` (rev 1 → … → rev 4
-  absorbed three review rounds; rev 5 records approval + the Q#FD4 binding
-  decision).
-- State: **Stage 1 (fold engine, headless) implemented; PR #142 OPEN**,
-  two review rounds landed on the branch. Bindings decided (Q#FD4 → Emacs
-  hideshow `C-c @` set); Bet B1 accepted as framed.
-  Load-bearing decision (Q#FD1): the bundled grammars ship no fold query and
-  no `folds.scm`, so the roadmap's "tree-sitter fold ranges" is not free; v1
-  is structural node folding (block-like node ≥2 source lines, derived head
-  line, closer-aware tail), with indentation fallback and curated queries
-  deferred. `FoldState` already exists in the protocol; Stage 1 starts
-  *producing* it (authoritative-empty), no protocol bump; gutter markers are
-  frontend-derived like the diagnostic sign bars, so no new wire type. Staged
-  like vterm: Stage 1 engine (headless), Stage 2 TUI, Stage 3 GPU.
-- PR: **#142** (`Arc 6 folding — Stage 1: instance fold engine`), open
-  against `main`. Round 1 (tail-boundary delete bug + buffer-kill cleanup +
-  close-all point-move) and round 2 (pin the kill-path + close-all through
-  the real command surface) are landed as fix commits on the branch.
-- Next: land Stage 1; Stages 2/3 are separate branches/PRs, each re-framed
-  in detail after the prior stage lands.
+Stage 1 (the headless fold engine) is MERGED as **#142** (see "Closed since
+the last snapshot"); this lane carries the Stage 2 (grid/daemon collapse)
+work off the resulting main.
+
+- Portable branch: `githubsucks/folding-tui`; worktree `../pmacs-folding-tui`.
+- Base: canonical `main` @ `c49a8c7` (folding Stage 1 / #142 merged).
+- Framing head: `docs/folding-stage2-framing.md` (rev 1 → rev 2; rev 2
+  absorbs review round 1's five findings + two rulings). Numbering continues
+  the parent `Q#FD` scheme from `Q#FD12`.
+- State: **framing only, rev 2, under review; no implementation, no PR.**
+  Load-bearing reframe (Q#FD12): the TUI has no non-identity
+  source-line↔display-row map today (`view_top + row` is baked into ~13
+  sites), so Stage 2's spine is one shared visible-line-map primitive that
+  every consumer routes through. Correction to the parent premise (Q#FD19):
+  yank + query-replace are `apply_active_edit` callers (local), not
+  Lua-mutator callers; only comment-toggle/yank-pop take the Lua path
+  (shared with the remote/optimistic-CRDT apply deferred to Stage 3). No
+  wire schema or protocol change — `FoldState` production (Stage 1) is
+  untouched; the GPU render path is Stage 3.
+- Next: land the remaining review rounds → implement Stage 2 on this branch
+  → PR. Stage 3 (GPU) is a separate branch/PR off the resulting main,
+  re-framed in detail after Stage 2 lands.
 
 Recovery worktree:
 
 ```sh
 git worktree add --track \
-  -b folding \
-  ../pmacs-folding \
-  githubsucks/folding
+  -b folding-tui \
+  ../pmacs-folding-tui \
+  githubsucks/folding-tui
 ```
 
 ## Parked lane: kill-ring browser + persistence
@@ -124,6 +122,19 @@ git worktree add --track \
 
 ## Closed since the last snapshot
 
+- **Folding Stage 1 (headless fold engine) — MERGED as #142** (`main` @
+  `c49a8c7`, 2026-07-23, after three review rounds; round 3 clean). The
+  instance-side fold store + translating/dropping `View`, the structural
+  source (derived head line, closer-aware tail), the Lua data API +
+  interactive `C-c @` commands, the command-path pre-edit unfold, and
+  authoritative-empty `FoldState` production landed with no protocol bump.
+  The `folding` branch and worktree (`../pmacs-folding`) are retained but
+  carry nothing unmerged; the `folding-framing.md` framing is preserved.
+  CI red at merge was an unrelated environmental perf flake
+  (`outline_5_level_100_entry_renders_within_100ms`, macOS/luajit only),
+  green on rerun. Stage 2 continues on `folding-tui` (see the lane above);
+  durable substrate seams live in `docs/agent-handoff.md` §1.
+
 - **Vterm Stage 3 (protocol v19 + GPU terminal) — MERGED as #135** (`main`
   @ `cac4961`, 2026-07-22, after two review rounds). Arc 5's terminal stage
   is complete (compile mode #113, Stage 1 #126, Stage 2 #130, Stage 3 #135).

docs/agent-handoff.md

@@ -1,11 +1,11 @@
 # Agent handoff — cross-machine continuity
 
-**Last updated: 2026-07-23, after one-command GPU invocation (#141) landed,
-following the documentation refresh (#140), Vterm Stage 3 (#135, protocol v19
-and native GPU terminal), tab-width rendering parity (#137), locals-query
-processing (#134), modeline detection (#132), mode system wiring (#129),
-config registry (#127), Vterm Stages 1–2 (#126/#130), and completed Themes
-Arc 4 (#120/#124/#125).**
+**Last updated: 2026-07-23, after folding Stage 1 (#142, the headless fold
+engine) landed, following one-command GPU invocation (#141), the documentation
+refresh (#140), Vterm Stage 3 (#135, protocol v19 and native GPU terminal),
+tab-width rendering parity (#137), locals-query processing (#134), modeline
+detection (#132), mode system wiring (#129), config registry (#127), Vterm
+Stages 1–2 (#126/#130), and completed Themes Arc 4 (#120/#124/#125).**
 This file is the
 bridge between development machines. If you are an agent reading
 this on a fresh clone: this document plus the `docs/*-framing.md`
@@ -19,9 +19,52 @@ commands, read `docs/active-work.md` immediately after this file.
 
 ## 1. Where the project stands (2026-07-23)
 
-- `main` @ `63fbc66` (one-command GPU invocation #141 atop documentation
-  refresh #140), protocol **v19** (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`,
-  v17 = `FontFacts`, v18 = `StatuslineSegments`, v19 = terminal frames/events).
+- `main` @ `c49a8c7` (folding Stage 1 #142 atop one-command GPU invocation
+  #141 and documentation refresh #140), protocol **v19** (`SUPPORTED=[6..=19]`;
+  v16 = `ThemeFacts`, v17 = `FontFacts`, v18 = `StatuslineSegments`, v19 =
+  terminal frames/events).
+- **Folding Stage 1 (headless fold engine) LANDED — #142**
+  (`docs/folding-framing.md` rev 5; merge `c49a8c7`; three review rounds,
+  round 3 clean). Arc 6's engine — instance-side and headless; **no frontend
+  renders a collapse yet** (that is Stage 2). No protocol bump.
+  - `src/fold.rs`: a per-buffer `FoldStore` of byte ranges attached as a
+    translating/dropping `View` (the `BufferStyleSpanTranslator` pattern — it
+    translates strictly-inside edits and DROPS boundary-crossers,
+    provenance-blind); `FoldRegistry`/`SharedFoldRegistry` =
+    `Rc<RefCell<HashMap<BufferId, {Arc<Mutex<FoldStore>>, ViewId}>>>` (the
+    SyntaxRegistry per-buffer model), held on both `EditorCore`
+    (`src/editor_core.rs:223`) and `EditorState` (`src/editor.rs:110`).
+    Containment is **start-exclusive, end-inclusive `(start, end]`**; the
+    stored range is `[end of head line, end of last hidden line]` (NOT the
+    `ByteRange` struct doc's `[start,end)`).
+  - Structural source: nearest enclosing block-like node ≥2 source lines →
+    resolve introducer↔body → **derived head line** (the line immediately
+    above the first hidden line, so wrapped signatures / `where` clauses stay
+    visible) → **closer-aware tail** (a closing-delimiter line stays visible,
+    e.g. `} else {`). Stale/absent parse tree refuses.
+  - The six `EditorCore` edit primitives call `unfold_before_point_edit`
+    first (command-path pre-edit unfold, keyed on the active frontend's
+    point). Interactive Lua-command unfold (yank/query-replace/comment) is a
+    Stage 2 obligation; CRDT-origin unfold is Stage 3.
+  - `src/lua_bindings/fold.rs` (`install_fold`): `pmacs.fold.*` data API
+    (explicit buffer, no ambient resolution, matching #127) + interactive
+    commands on the **Emacs hideshow `C-c @` prefix set**;
+    `builtin/runtime/fold.lua`.
+  - `src/semantic_render.rs`: `fold_state_msg` PRODUCES `FoldState`
+    (semantic/GPU sessions) — authoritative-empty, diff-suppressed, per-session
+    baseline reset on `BufferSnapshot` (the #120 stale-mirror trap class; the
+    GPU fold-mirror clear-on-snapshot is a named Stage 3 obligation).
+  - Durable lesson (round 2): after wiring a cleanup into a production hook,
+    PIN IT THROUGH THE REAL PATH — a direct-call unit test misses the wiring
+    (falsify by revert).
+  - **Stage 2 (grid/daemon collapse) is in framing** on `folding-tui`
+    (`docs/folding-stage2-framing.md`, rev 2). Its load-bearing reframe: the
+    TUI has **no non-identity source-line↔display-row map** today (`view_top +
+    row` is baked into ~13 sites), so Stage 2's spine is one shared
+    visible-line-map primitive that the render loop, gutter, diagnostics,
+    caret, selection, peer presence, viewport/scroll/motion, and the mode-line
+    indicator all route through, plus the interactive-Lua unfold widening.
+    Stage 3 (GPU) follows.
 - **One-command GPU invocation LANDED — #141**
   (`docs/gpu-invocation-framing.md` rev 6; merge `63fbc66`; two implementation
   reviews). The additive public path is `pmacs --gpu [--socket NAME|PATH]`;
@@ -421,8 +464,12 @@ commands, read `docs/active-work.md` immediately after this file.
     lexical resolution, settled per-layer facts, shared TUI/GPU
     local-predicate filtering, and a registry-wide locals-query invariant
     shipped without a protocol change.
-  - Remaining ranked arcs: 6 folding, 7 DAP, 8 GPU splits, plus the
-    `.ipynb` arc (its JSON-grammar prerequisite shipped in #123).
+  - **Arc 6 (folding) Stage 1 LANDED — #142** — the headless fold engine
+    (store, structural source, Lua `C-c @` surface, command-path unfold,
+    `FoldState` production). Stage 2 (grid/daemon collapse) is in framing on
+    `folding-tui`; Stage 3 (GPU) follows.
+  - Remaining ranked arcs: 6 folding Stages 2–3, 7 DAP, 8 GPU splits, plus
+    the `.ipynb` arc (its JSON-grammar prerequisite shipped in #123).
 
 ## 2. How we work (the part that must not drift)