ramdisk: headless planning, staging, mounts, recovery + tokenized CLI (PR2 of #377 split)

[BColsey]

Draft successor — supersedes #377. One of three dependent PRs reconstructed from the frozen green donor 5f6f31a. Do not merge #377.

• Supersedes: feat: Add NUMA-aware RAM-disk streaming #377
• Sibling successors: engine: RAMMAP, NUMA, and telemetry (PR1 of #377 split) #820 (engine RAMMAP/NUMA/telemetry), managed runner, deterministic benchmark, and causal evidence (PR3 of #377 split) #822 (managed runner/benchmark/evidence)
• Chain: PR1 (engine: RAMMAP, NUMA, and telemetry (PR1 of #377 split) #820) → PR2 (this) → PR3 (managed runner, deterministic benchmark, and causal evidence (PR3 of #377 split) #822); this branch is based on the PR1 branch
• Design: docs/superpowers/specs/2026-08-01-pr-377-stabilization-design.md (PR2, L82-87)
• Ledger: docs/superpowers/specs/2026-08-02-pr-377-successor-reconstruction.md

Scope

Headless planning/discovery, platform ops, durable state, safe mount recovery, the reduced facade + tokenized CLI, packaging, and portable tests. No frontend/TUI; managed start/stop deferred to PR3.

Control plane: c/ramdisk.py, c/__init__.py, c/ramdisk_support/{__init__,accelerator,cli,common,discovery,lifecycle,linux_ops,model,mounts,planning,platform_ops,presentation,presets,processes,state}.py. Packaging: c/coli, c/tools/clean.py, pyproject.toml, flake.nix. Portable tests (state_lifecycle, processes, mounts, planning, platform, packaging, CLI/JSON smoke, facade, …) + docs/CI.

Reconstruction work (drafts may not build in isolation until these land)

• Tokenized JSON CLI (design L56-73): plan / stage --plan-token / read-only verify / status / destroy --deployment-token, all --json; versioned result/error schemas. prepare stays an alias; managed start/stop stay deferred to PR3.
• Sever the eager UI import: presentation.py imports ramdisk_ui at module top level — relocate the data contracts + token builders into a headless ramdisk_support module so PR2 builds with ramdisk_ui/ramdisk_textual/curses_ui physically absent.
• Packaging: drop textual as a hard pyproject.toml dep (→ tui extra); stop c/coli and flake.nix from requiring/bundling UI files; update test_ramdisk_packaging.py bundle assertions.

Dependency

Depends on PR1 (#820): c/coli imports resource_plan.py (PR1). PR3 (#822) depends on this PR's durable state + recovery.

Build verification (subagent worktree)

• Package imports; lifecycle/state/processes import cleanly. 233 passed / 36 failed — every failure traces to the intentionally-excluded UI/benchmark/curses bundle (no unexpected defect).
• Sharper blocker found by execution: it is not only presentation.py:10 importing ramdisk_ui — the coli launcher top-level bundle self-check (_complete_support, c/coli:67-162) hard-aborts with SystemExit("coli: incomplete colocated support bundle …") when ramdisk_ui.py/ramdisk_textual.py/benchmark.py/curses_ui.py/runtime_monitor.py are absent, killing the unittest runner. PR2 must make that self-check absence-tolerant (and have the lazy importlib accessors treat a missing optional module as "feature unavailable", not a hard abort).

Reconstruction update

PR2 reconstruction landed (commit b7a6df4): builds and tests UI-free. Absence-tolerant coli bundle self-check (no SystemExit); new headless ramdisk_support/contracts.py (contracts relocated out of the excluded ramdisk_ui); presentation.py imports from .contracts; textual moved to an optional tui extra; lazy accessors raise only on use. Green: 705 passed / 0 failed (3.10 + Win32 matrix). Still TODO: tokenized JSON CLI (stage/verify/destroy).

---

Update — 2026-08-07: forward-merged upstream/dev (two forward-only merge commits; reconstruct history preserved). Conflicts resolved against the green donor 3658a5d; merged dev @ aa46e7b then @ 8d06bd1 (dev advanced mid-work). Linux-green: python suite 809 OK (incl. dev's new test_launcher_dispatch), make portable clean, test_uring/test_serve_sentinel pass, headless/UI-free build confirmed. GitHub reports this branch MERGEABLE into dev.

[BColsey]

Merge order: 2 of 3

Merge this PR only after #820. After this merges, merge #822.

Dependency chain: #820 → #821 → #822

[BColsey]

@JustVugg, this PR is ready for review.

The current CI workflow and check workflow are both action_required with no jobs started. Because this is a fork PR, they require approval from a base-repository maintainer before CI can run.

Merge position: 2 of 3 — merge after #820 and before #822.