feat(guard): F1 confine — user-reachable via enable --confine + doctor-confine

[m1ngshum]

What

The final PR of the F1 arc — wires the confine engine (#110) to the enable path so it's actually usable.

• mcpm guard enable --confine (bare → standard tier; --confine off disables) enrolls every unwrapped stdio server it wraps into an OS sandbox. The cli layer derives each server's ConfineProfile once (a single capturedAt → an identical content hash across every client that wraps it, so the spawn-time verify never mismatches → decide.ts row 3), merges them into ~/.mcpm/guard-confine.yaml, and hands the orchestrator a name → ConfineMarker map.
• Orchestrator seam: the single wrapEntry call embeds --confine-profile-hash (+ --confine-required) via a new optional confineMarkers dep — the only behavioral change there.
• mcpm guard disable removes the marker (unconfines); the lingering profile is harmless (spawn row 5b: no marker → not confined).
• mcpm guard doctor-confine [--json] — read-only report of backend availability (platform + sandbox-exec presence) and enrolled servers (tier / net / require_confine), pointing at guard status for per-client wrap state.

Hybrid posture, surfaced honestly: when no OS backend is present (Linux/CI/Windows today), enable still enrolls + embeds markers but prints a loud notice that those servers run UNCONFINED until a backend exists (a require_confine server fails closed at spawn per the #110 decision table).

Verification

• ✅ 1886 tests pass (+10: orchestrator marker-embed, computeConfineMarkers dedup/skip-url/skip-wrapped/merge, enable --confine end-to-end, doctor-confine JSON/text/empty) · tsc + pnpm build clean.
• ✅ macOS dogfood on the built binary (isolated HOME, real sandbox-exec): enable --confine → the rewritten config entry's args carry both --orig-hash and --confine-profile-hash before -- (neutrality holds live — disable unwraps by verifying orig-hash through the confine tokens); the profile landed in guard-confine.yaml; doctor-confine --json reported backendAvailable: true + the enrolled server; disable removed the marker cleanly.

Scope note

Built the clean, load-bearing core (enable path + doctor + orchestrator seam), which makes confine fully user-reachable. Deferred to a fast-follow: the per-server guard confine <server> / --off / --show / --require / --allow-* command — its re-wrap-already-wrapped logic + the --off re-wrap-before-delete ordering contract are a distinct chunk best done on its own. Per-server confinement is still achievable today via enable --confine --server X + disable --server X.

Risk

Confine is opt-in (--confine only). Without the flag, enable/disable behavior is unchanged (confineMarkers undefined → wrapEntry called exactly as before). The spawn path (#110) only acts on servers present in guard-confine.yaml.

[m1ngshum]

Adversarial review pass (two independent agents) + fixes

Ran two independent adversarial reviews on this PR's code delta (matching the rigor #110 got): a security / spawn-path lens and a TypeScript-correctness lens. Both confirmed the core is sound — the marker↔store hash binding is stable within a run, the store merge is a pure immutable upsert, marker-embedding scope matches what the orchestrator wraps, doctor-confine is read-only, the SBPL scratch-read re-allow ordering is correct, and a hostile server name can't traverse or reach SBPL. Findings fixed in da95057:

HIGH — false "tamper" fail-closed on a multi-client partial-enable retry. hashConfineProfile included captured_at and computeConfineMarkers re-timestamped each run, so re-deriving an already-enrolled server minted a new hash → the already-wrapped clients' markers mismatched → spawn decision row 3 (fail-closed) bricked a working server. Fixed at the root: hash only the enforcement-policy fields (captured_at is provenance, excluded), and reuse an already-stored profile instead of re-deriving.

HIGH — silent clobber of a corrupt/tampered store. The read-error path fell back to an empty store and overwrote the file, erasing prior enrollments and masking the tamper signal. Fixed: the integrity/shape error now propagates; enable aborts with ⚠ OS confinement aborted, store left byte-for-byte intact (ENOENT still returns empty and never throws).

HIGH — untested invariant + 3 functions over the 50-line rule. The e2e test now asserts the embedded --confine-profile-hash value equals hashConfineProfile(store.servers[name]); helpers extracted to satisfy the length rule.

MEDIUM/LOW — --client now threaded into marker computation (was ignored; also removes a multi-client net-misclassification); --confine off acknowledged (was a silent no-op); storeError sanitized in JSON; --confine true/1 accepted; orchestrator arg-adjacency assertion strengthened.

Verification: 1890 tests pass (+4 regression tests for the retry, corrupt-store abort, --client scoping, and the hash-value invariant); tsc + pnpm build clean; macOS dogfood on the built binary confirms embedded hash == stored hash, a retry enrolls nothing new (no captured_at churn → no false tamper), --client scopes enrollment, and disable unwraps through the confine tokens.