pmacs/docs/active-work.md

# Active work — cross-machine resume ledger

**Snapshot: 2026-07-22.** This file records volatile work that has not
landed on `main`. Read it after `docs/agent-handoff.md`. Remove completed
entries when their PR merges; do not let this become a second permanent
backlog.

## Repository authority

- Canonical development URL:
  `https://github.com/levineuwirth/pmacs.git`. This ledger uses the
  normalized local alias `githubsucks` so its refs and recovery commands
  are identical on every machine. Remote names are otherwise
  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` @ `d5d9b9c` (mode system handoff #131 merged;
  protocol v18).
- 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
  verifying URLs and normalizing `githubsucks` rather than trusting
  `origin/main`.
- The shared desktop checkout contained unrelated uncommitted work. The
  branches below were prepared in isolated worktrees; never clean or
  overwrite the shared checkout to recover them.

Start on another machine by inspecting its remotes:

```sh
git remote -v
git remote get-url githubsucks
```

If the second command says the alias is absent, add it; if it prints a
different URL, stop and resolve that collision rather than overwriting an
unknown remote:

```sh
git remote add githubsucks https://github.com/levineuwirth/pmacs.git
```

Then recover current refs:

```sh
git fetch githubsucks --prune
git log -1 --oneline githubsucks/main
git worktree list
git status --short --branch
```

The first command must expose `d5d9b9c` or a newer intentional main.
If it does not, stop and repair the remote/fetch configuration.

## Vterm Stage 2 implementation lane

- Portable branch: `githubsucks/vterm-tui`
- Integrated feature head: `3f0252f` (review-fix head `b9a7e40`)
- Base: originally canonical `main` @ `f1a2f75`; current canonical `main`
  @ `d5d9b9c` (mode system wiring #129 and handoff #131) is integrated before
  merge.
- PR: #130, <https://github.com/levineuwirth/pmacs/pull/130>, open against
  canonical `main` and explicitly authorized for merge.
- State: `docs/vterm-framing.md` Revision 7 criteria 15–27 are implemented.
  The lane composes per-frontend/window terminal views in the TUI, installs
  the strict `pmacs.terminal` API and terminal-local bindings, drains
  clipboard/BEL through the authenticated frontend, and routes daemon
  terminal input by connection source. Protocol remains v18; Stage 2 changes
  neither the wire schema nor the GPU renderer.
- Review round 1: addressed. Dispatch now requires `C-c` before terminal-local
  editor bindings; non-terminal context operations error; controller
  replacement is atomic per frontend; zero-area layouts retain view anchors;
  view projection borrows retained rows instead of deep-cloning scrollback.
- Review round 2: addressed. Partial eviction clamps anchors to the first
  surviving wrapped-line cell; `invoke_interactive` now inherits only an
  authenticated dispatch origin; explicit context failures are named; terminal
  mouse routing reads geometry without cloning cells; the framing records the
  v18 semantic-controller boundary and bracketed-paste injection deferral.
- Implementation commits: `39e07cb`, `7c39535`, `0a846d9`, `0dacac7`,
  `dc92257`, merge `0ddff24`, integration hardening `da8f6ae`, first-review
  fixes `8702791`, second-review fixes `b9a7e40`, and current-main integration
  `3f0252f`.
- Post-integration verification: `cargo fmt --check`; strict workspace
  Clippy; 1,753 default + 1,929 CRDT library tests (3 ignored each);
  mode-system acceptance 1 default + 1 CRDT; Stage 1 acceptance 9 default +
  10 CRDT; Stage 2 acceptance 4 default + 4 CRDT; statusline acceptance
  7 default + 8 CRDT; M4 114 passed (3 ignored, 1 filtered); required GPU
  109; workspace 2,882 passed across 82 suites (19 ignored, 1 filtered);
  `git diff --check` clean. The first parallel M4 attempt timed out after
  partial progress; a serial isolation pass and the immediate exact parallel
  rerun both passed, and the workspace sweep also passed.
- Next: push the integrated head and merge PR #130 as authorized.

Recovery worktree on a machine that does not already own the branch:

```sh
git worktree add --track \
  -b vterm-tui \
  ../pmacs-vterm-tui \
  githubsucks/vterm-tui
```

## Parked lane: kill-ring browser + persistence

- Portable branch: `githubsucks/kill-ring-browser`
- Parked framing head: `503c489`
- State: framing only, revision 2; no implementation and no PR.
- Status: explicitly parked by the user on 2026-07-20.
- Its original scout was based on `0efb5cd`. The preserved framing marks
  this ground truth stale and requires a complete re-scout against the
  then-current `githubsucks/main` before implementation.
- Compile-mode has merged since the original scout, so old
  “compile-mode in flight” keybinding/touch-set assumptions are not
  authoritative.

Recovery worktree, only when the user un-parks it:

```sh
git worktree add --track \
  -b kill-ring-browser \
  ../pmacs-kill-ring-browser \
  githubsucks/kill-ring-browser
```

## Documentation lane

- Portable branch: `githubsucks/handoff-2026-07-20`
- Carries synchronized `AGENTS.md` / `CLAUDE.md`, this ledger, the
  durable handoff refresh, and the keybinding reference correction.
- It changes no runtime code.
- Review and merge this documentation branch separately; it must not be
  folded into a feature framing branch.
- Now also absorbs both landed arcs: Vterm Stage 1 (#126) and the config
  registry (#127). Canonical `main` is merged into it up to `2e37c04`,
  so its diff against `main` is documentation only.

## Closed since the last snapshot

- **Config registry — MERGED as #127** (`main` @ `2e37c04`). Its lane
  (`config-registry`, worktree `../pmacs-config-registry`) is done; the
  branch is kept but carries nothing unmerged. Durable substrate facts
  moved to `docs/agent-handoff.md` §1 per rule 3 below.
- Both this and Vterm Stage 1 ran as **concurrent lanes in sibling
  worktrees off `main`**, with the shared files (`src/editor.rs`,
  `src/lua_bindings/mod.rs`, `src/lib.rs`) assigned to one lane each in
  advance. The rebase of the second lane onto the first had **zero
  conflicts** — worth repeating for future parallel work, along with its
  precondition: agree the file split before either lane starts, and keep
  each lane's footprint in the other's files to a single line.

## Update protocol

Whenever a listed lane changes materially:

1. update its public branch and head/state here;
2. record new verification and remove superseded caveats;
3. keep durable architecture in `docs/agent-handoff.md`, not here;
4. remove the lane after merge or abandonment;
5. verify every recovery command from a clean worktree before calling
   the transfer complete.