test(mosaic): make #791 PR2 Part 7 symlink control busybox-portable (#791 PR2)

CI #1881 failed at head 8bee1b65: the durable-snapshot gate was 40/41, the sole failure being the Part 7 NEGATIVE control ("secret leaked through the symlink"). Root cause is a test-harness portability gap, not a code defect: node:24-alpine runs busybox cp as root, and busybox cp REPLACES a symlinked destination instead of following it, whereas GNU/BSD cp — what a real operator runs `mosaic update` under — follows the link and leaks. So under the CI harness the CWE-59 leak vector the control asserts simply cannot occur, and the negative control can't reproduce. Fix is test-only; install.sh (independently approved at 8bee1b65) and the real security assertions are untouched. make_symlink_leaf_shim now emulates GNU cp's follow-through-dest-symlink behavior portably: when the destination is a symlink it writes the source bytes through the link via redirection (which follows symlinks on every coreutils, busybox included); otherwise it delegates to the host cp unchanged. Both the shipped-case and the control run through this single shim, so the ONLY difference between them remains the SYMLINK-LEAF-GUARD — the control stays load-bearing and non-tautological, now on busybox too. With the guard present the symlinked leaf is dropped before this cp runs, so the shipped path is unchanged. Verified in the exact CI image (node:24-alpine, busybox, root, apk add bash rsync): durable-snapshot 41/41, manifest-guard 193, rollback 28. GNU host 41/41, shellcheck clean. Sole tracked delta vs 8bee1b65 = this test file. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat(mosaic): durable pre-update snapshot + verify net + restore CLI (#791 PR2)
2026-07-16 19:24:49 -05:00 · 2026-07-16 19:04:14 -05:00
38 changed files with 104 additions and 3857 deletions
--- a/Dockerfile.ci
+++ b/Dockerfile.ci
@@ -22,10 +22,10 @@
 FROM node:24-alpine

 # Native toolchain required to compile node-gyp deps on musl, plus the
-# postgresql-client used by the test step's pg_isready readiness probe. `bash`,
-# `git`, and `jq` are baked here too — framework shell tests and the shipped
-# Codex review wrappers require them without per-run installation in ci.yml.
-RUN apk add --no-cache python3 make g++ postgresql-client bash git jq
+# postgresql-client used by the test step's pg_isready readiness probe. `bash`
+# is baked here too — the sanitization step in ci.yml otherwise does a per-run
+# `apk add bash`.
+RUN apk add --no-cache python3 make g++ postgresql-client bash

 # Pin pnpm to the repo's packageManager version via corepack.
 RUN corepack enable && corepack prepare pnpm@10.6.2 --activate
--- a/README.md
+++ b/README.md
@@ -97,10 +97,7 @@ mosaic config path           # Print config file path
 ```bash
 mosaic doctor                # Health audit — detect drift and missing files
 mosaic sync                  # Sync skills from canonical source
-mosaic skill list            # Audit Claude skill registrations and conflicts
-mosaic skill register <name> # Register one canonical skill with Claude Code
-mosaic skill unregister <name> # Remove one Mosaic-owned Claude link
-mosaic update                # Update CLI/framework and auto-register canonical skills
+mosaic update                # Check for and install CLI updates
 mosaic wizard                # Full guided setup wizard
 mosaic bootstrap <path>      # Bootstrap a repo with Mosaic standards
 mosaic coord init            # Initialize a new orchestration mission
@@ -352,8 +349,6 @@ bash tools/install.sh --yes             # Non-interactive, accept all defaults
 bash tools/install.sh --no-auto-launch  # Skip auto-launch of wizard
 ```

-The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
-
 ## Contributing

 ```bash
--- a/docs/SITEMAP.md
+++ b/docs/SITEMAP.md
@@ -1,10 +1,5 @@
 # Documentation Sitemap

-## CLI and skill management
-
- [Skill registration user guide](guides/user-guide.md#claude-code-skill-registration) — register, unregister, list statuses, automatic install/update reconciliation, and Claude reload behavior.
- [Skill bridge developer guide](guides/dev-guide.md#claude-code-skill-bridge) — path-validation, ownership, clobber-protection, install/update wiring, tests, and Pi/Codex scope notes.
-
 ## Fleet configuration management

 - [Generated environment boundary](fleet/reference/generated-env-boundary.md) — roster-derived launch projection, strict local data, legacy quarantine, and downstream interface evidence.
--- a/docs/guides/dev-guide.md
+++ b/docs/guides/dev-guide.md
@@ -8,9 +8,8 @@
 4. [Adding New Agent Tools](#adding-new-agent-tools)
 5. [Adding New MCP Tools](#adding-new-mcp-tools)
 6. [Database Schema and Migrations](#database-schema-and-migrations)
-7. [Claude Code Skill Bridge](#claude-code-skill-bridge)
-8. [API Endpoint Reference](#api-endpoint-reference)
-9. [Local Fleet Canary](./fleet-local-canary.md)
+7. [API Endpoint Reference](#api-endpoint-reference)
+8. [Local Fleet Canary](./fleet-local-canary.md)

 ---

@@ -354,37 +353,6 @@ defined there.

 ---

-## Claude Code Skill Bridge
-
-The framework's canonical skill root is `~/.config/mosaic/skills/`; Claude Code
-requires registrations under `~/.claude/skills/`. The implementation in
-`packages/mosaic/src/commands/skill.ts` owns only direct-child symlinks whose
-resolved target remains inside the canonical root.
-
-Security invariants:
-
-1. Validate the user-supplied name before filesystem access against
-   `[A-Za-z0-9][A-Za-z0-9._-]*`. Separators, control characters, whitespace,
-   `..`, absolute paths, and leading `-` are invalid; filesystem-derived invalid
-   names are escaped before terminal output.
-2. Never replace a real file, directory, foreign symlink, or live misdirected
-   symlink in the Claude skill directory.
-3. Repair a dangling link only when its lexical target is inside the canonical
-   Mosaic skills root.
-4. Unregister only a symlink pointing inside that root.
-5. Enumerate canonical directories at runtime; never hardcode framework skill
-   names.
-
-`finalizeStage` reconciles after wizard/framework synchronization, and
-`runFrameworkReseed` reconciles after the sync-only `mosaic update` path. A
-foreign conflict is reported but does not prevent unrelated canonical skills
-from registering. Filesystem tests use injected temporary roots in
-`skill.spec.ts`, `finalize-skills.spec.ts`, and `update-checker.reseed.spec.ts`.
-
-M1 intentionally manages Claude Code only. Pi's Mosaic launcher can discover the
-canonical root directly. Codex still relies on the existing full skill-sync
-linker and needs separate parity analysis before this lifecycle API is extended.
-
 ## API Endpoint Reference

 All endpoints are served by the gateway at `http://localhost:14242` by default.
--- a/docs/guides/fleet-local-canary.md
+++ b/docs/guides/fleet-local-canary.md
@@ -98,39 +98,6 @@ Expected results:
  that means the unit ran, not that an agent pane is live. Treat tmux
  `has-session`, `list-panes`, process tree, and logs as the liveness evidence.

-## Recovery — rebuild generated env projections
-
-Each agent's `~/.config/mosaic/fleet/agents/<name>.env.generated` is a
-deterministic projection of `roster.yaml` (the SSOT) that the launcher
-(`start-agent-session.sh`) sources at start. If an upgrade or a manual mistake
-wipes or diverges those projections, rebuild them from the roster with
-`mosaic fleet regen` — do NOT restart the affected unit first.
-
-```bash
-mosaic fleet regen            # dry-run (default): show create/rebuild plan per agent
-mosaic fleet regen --json     # same plan, machine-readable
-mosaic fleet regen --write    # rebuild fleet/agents/<name>.env.generated on disk
-```
-
-`regen` is projection-only and **never restarts an agent** — it has no path to
-systemd lifecycle. It is dry-run by default, deterministic/idempotent, uses the
-same roster→env mapping as `mosaic fleet reconcile`, and emits paths and counts
-only (never the projected `KEY=value` body). After `--write`, verify each unit
-resolves the intended values before restarting one unit at a time. The unit sets
-no `EnvironmentFile=` — `start-agent-session.sh` sources `.env.generated` itself —
-so verify the generated file directly and the launcher path, not a nonexistent
-`EnvironmentFile` property:
-
-```bash
-test -f ~/.config/mosaic/fleet/agents/<name>.env.generated
-systemctl --user cat mosaic-agent@<name> | grep ExecStart
-systemctl --user restart mosaic-agent@<name>
-```
-
-Full recovery runbook and the three-layer #791 protection model (manifest
-ownership → pre-update snapshot/restore → regen): see
-[Upgrade Safety & Recovery](./upgrade-safety-and-recovery.md).
-
 ## Release Preflight

 Run this checklist before cutting or dogfooding a fleet release:
--- a/docs/guides/upgrade-safety-and-recovery.md
+++ b/docs/guides/upgrade-safety-and-recovery.md
@@ -1,147 +0,0 @@
-# Upgrade Safety & Recovery
-
-How Mosaic protects operator-owned configuration under `~/.config/mosaic` across
-framework upgrades, and how to recover if a projection is ever lost.
-
-A framework upgrade runs `install.sh` in keep-mode (`MOSAIC_INSTALL_MODE=keep`,
-`MOSAIC_SYNC_ONLY=1`) to refresh framework-owned files in place. The incident
-this hardening addresses: an upgrade that silently overwrites or deletes a file
-the operator owns — credentials, personas, a roster, or a generated agent env —
-with no snapshot to fall back to.
-
-Protection is layered. Each layer is independent; a later layer catches what an
-earlier one misses.
-
-## Layer 1 — Manifest-owned sync (prevention)
-
-The single source of truth for ownership is
-[`framework-manifest.txt`](../../packages/mosaic/framework/framework-manifest.txt).
-Both the bash installer and the TypeScript sync path resolve every path against
-this one file (parity is enforced by test), so they can never drift.
-
- Ownership is **allow-list, deny-wins**: a path is framework-owned only if a
-  `[framework]` glob matches and no `[operator]` carve-out overrides it.
- **Unknown paths default to operator** (fail-safe): a file the manifest never
-  anticipated is treated as operator-owned and is never pruned.
- Keep-mode does a non-deleting copy plus an explicit, manifest-scoped prune that
-  only ever iterates framework globs — operator and unknown paths are
-  structurally unreachable by the prune.
-
-Result: a correct upgrade cannot touch operator config at all.
-
-## Layer 2 — Durable pre-update snapshot + verify net (safety + rollback)
-
-Before **any** mutation, the installer snapshots the operator-owned surface that
-exists into:
-
-```
-${XDG_STATE_HOME:-~/.local/state}/mosaic/backups/pre-update-<UTC-timestamp>/
-```
-
- `0700` directories / `0600` files (`umask 077`, scoped and restored),
-  outside `~/.config/mosaic` and outside any repo.
- **Fail-open**: a snapshot failure warns but never aborts the upgrade it
-  protects.
- Retention is `MOSAIC_BACKUP_RETENTION` snapshots (default 5).
-
-After the sync, a **verify net** compares each snapshot file against its target
-and restores (with a loud warning) any operator file the upgrade diverged or
-removed — a divergence means a manifest bug slipped through Layer 1.
-
-Inspect and restore snapshots with the CLI:
-
-```bash
-mosaic restore --list                 # dry-run: enumerate snapshots by timestamp
-mosaic restore --from <UTC-timestamp> # restore the operator surface from one snapshot
-mosaic restore --from <ts> --dry-run  # preview a specific restore without writing
-```
-
-`mosaic restore` reports **counts and relative paths only** — it never emits file
-contents, so a secret in `tools/_lib/credentials.json` is never echoed. Restores
-are confirmation-gated (`--yes` or `MOSAIC_ASSUME_YES`) and write each leaf
-atomically with `O_NOFOLLOW` (a symlink swapped in after the snapshot fails
-closed rather than following out of the managed tree).
-
-## Layer 3 — Regeneration from roster SSOT (recovery)
-
-Some operator files are **derived** and do not need a byte-for-byte snapshot to
-recover — they can be rebuilt from their source of truth. The fleet's per-agent
-generated env projections are the prime case:
-
- `~/.config/mosaic/fleet/agents/<name>.env.generated` is a deterministic
-  projection of `~/.config/mosaic/fleet/roster.yaml`.
- The launcher (`start-agent-session.sh`, invoked by
-  `mosaic-agent@<name>.service`) sources that generated projection to establish
-  each agent's identity, runtime, model, and working directory. If it is missing
-  or wrong, the agent cannot launch with its intended identity.
-
-`mosaic fleet regen` rebuilds those projections from the roster SSOT:
-
-```bash
-mosaic fleet regen            # dry-run (default): show what would be rebuilt
-mosaic fleet regen --json     # same, machine-readable
-mosaic fleet regen --write    # rebuild the projections on disk
-```
-
- **Dry-run by default.** Nothing is written until you pass `--write`.
- **Deterministic and idempotent** — the projection is a pure function of the
-  roster, so repeated `--write` runs produce byte-identical files.
- **Projection-only. It never restarts an agent.** Recovery order forbids
-  restart-before-verify; `regen` has no path to systemd lifecycle at all.
- **It rebuilds only `<name>.env.generated`** — it never writes, relocates, or
-  deletes the operator-owned `.env` / `.env.local` surface.
- It **validates the roster the same way `reconcile` does** (persona resolution
-  and protected-class tool-policy match), so a hand-edited or corrupt roster is
-  rejected rather than projected, and a `--write` takes the shared reconcile
-  lock so it cannot race a concurrent reconcile.
- Output is **paths and counts only** — the rendered `KEY=value` body is never
-  echoed.
-
-`regen` uses the exact same roster→env mapping as `mosaic fleet reconcile`, so a
-recovered projection matches what a normal reconcile would have written.
-
-## Recovery runbook — wiped `fleet/agents/*.env.generated`
-
-If an upgrade (or a manual mistake) has left an agent without its generated
-projection, **do not restart the unit first** — a launch against a missing
-projection fails closed, and any stale state must be corrected before restart,
-not after.
-
-1. **Prefer a snapshot restore if one exists** (byte-exact operator state):
-
-   ```bash
-   mosaic restore --list
-   mosaic restore --from <UTC-timestamp>
-   ```
-
-2. **Otherwise regenerate the derived projections from the roster SSOT:**
-
-   ```bash
-   mosaic fleet regen            # confirm the plan (create vs rebuild per agent)
-   mosaic fleet regen --write    # rebuild fleet/agents/<name>.env.generated
-   ```
-
-3. **Verify each unit will resolve the intended runtime/workdir _before_ any
-   restart.** The unit sets **no** `EnvironmentFile=` — it launches from a minimal
-   environment and `start-agent-session.sh` sources `.env.generated` itself, so
-   verify the generated file directly and confirm the launcher path:
-
-   ```bash
-   # Confirm fleet/agents/<name>.env.generated exists and carries the intended
-   # MOSAIC_AGENT_* values (name, runtime, model, workdir, socket).
-   test -f ~/.config/mosaic/fleet/agents/<name>.env.generated
-   # Confirm the unit launches the session script that reads it.
-   systemctl --user cat mosaic-agent@<name> | grep ExecStart
-   ```
-
-4. **Only then restart, one unit at a time:**
-
-   ```bash
-   systemctl --user restart mosaic-agent@<name>
-   ```
-
-## See also
-
- Design: [`docs/design/791-upgrade-config-protection.md`](../design/791-upgrade-config-protection.md)
- Fleet operations: [`docs/guides/fleet-local-canary.md`](./fleet-local-canary.md)
- Ownership SSOT: [`packages/mosaic/framework/framework-manifest.txt`](../../packages/mosaic/framework/framework-manifest.txt)
--- a/docs/guides/user-guide.md
+++ b/docs/guides/user-guide.md
@@ -183,8 +183,6 @@ non-interactive use:
 --no-auto-launch    # Skip auto-launch of wizard after install
 ```

-Unrecognized flags or positional arguments fail before installation starts and print the supported-option usage.
-
 Or if installed globally:

 ```bash
@@ -309,39 +307,6 @@ mosaic quality-rails

 ---

-### Claude Code Skill Registration
-
-Mosaic stores canonical skills under `~/.config/mosaic/skills/`. Claude Code scans
-`~/.claude/skills/`, so Mosaic maintains one symlink per skill between those
-directories.
-
-```bash
-mosaic skill list
-mosaic skill register <name>
-mosaic skill unregister <name>
-```
-
- `register` is idempotent and repairs a dangling Mosaic-owned link. Names use
-  the safe grammar `[A-Za-z0-9][A-Za-z0-9._-]*`; files, directories, foreign
-  symlinks, path traversal, absolute paths, and names beginning with `-` are
-  refused.
- `unregister` is idempotent when no entry exists. It removes only symlinks that
-  point inside `~/.config/mosaic/skills/`; foreign entries are never removed.
- `list` reports `registered`, `unregistered`, `dangling`, `foreign`,
-  `foreign-dangling`, or `misdirected` for each canonical or Claude entry.
-
-Install, wizard finalization, and `mosaic update` framework re-seeding reconcile
-every canonical skill automatically. A skill directory added after initial
-setup therefore receives its Claude bridge without a per-skill code change or
-manual `ln -s`. If Claude Code is already running, use `/reload-skills` or start
-a new session after registration so its in-process skill registry rescans.
-
-This command group is Claude-only in M1. Pi can consume Mosaic's canonical skill
-root through its Mosaic launcher configuration and does not need this Claude
-bridge. Codex has a separate link path managed by the legacy full skill-sync
-script; equivalent lifecycle management remains follow-up scope and is not
-changed here.
-
 ## Sub-package Commands

 Each Mosaic sub-package exposes its full API surface through the `mosaic` CLI.
--- a/docs/scratchpads/791-upgrade-config-protection.md
+++ b/docs/scratchpads/791-upgrade-config-protection.md
@@ -296,234 +296,3 @@ vitest **1252** · restore.spec **30** · durable-snapshot **41** · manifest-gu
 migration 21. shellcheck clean on all new lines; new test markers mirror the existing `# VERIFY-NET`
 anchor convention. NOTE: codex self-review does NOT satisfy the independent-review gate — an independent
 (author≠reviewer) review + durable Gitea Reviewer-of-Record comment is still required before MS-LEAD merges.
-
-## Session 4 (2026-07-16) — PR2 MERGED, PR3 built (fleet regen — recovery layer)
-PR2 (#811) squash-merged → main `31607a4a`; issue #791 stays open (final PR of the 3-PR DAG). Independent
-exact-head RoR at `d12c5f78` APPROVE (Gitea cmt 17904); #1882 green; busybox-portable Part 7 control fix
-verified in-Alpine. PR3 UNBLOCKED.
-
-PR3 branch: `feat/791-pr3-fleet-regen` off `origin/main` 31607a4. Same discipline: tests-first red-first,
-independent review + durable Gitea RoR BEFORE MS-LEAD runs the queue guard/merge. PR body `Part of #791`.
-
-### PR3 scope (ratified §4/§7 of design doc) — `mosaic fleet regen`
-Projection-only recovery command: rebuilds each `fleet/agents/<name>.env.generated` from `roster.yaml`
-(SSOT). Dry-run default; `--write` applies; `--json` machine output. Structural guarantee: NO code path to
-systemd lifecycle — **never restarts an agent**. Single-SSOT: reuses `projectRosterV2AgentGeneratedEnv`
-(extracted, shared with the reconciler apply path) so regen and reconcile cannot drift. Secrev: paths +
-counts only, never the rendered KEY=value body.
-
-New files: `commands/fleet-regen-command.ts` (+ `.spec.ts`), guide `docs/guides/upgrade-safety-and-recovery.md`
-(three-layer model: PR1 manifest ownership → PR2 snapshot/restore → PR3 regen; do-NOT-restart-before-verify
-runbook), regen reference added to `docs/guides/fleet-local-canary.md`. Wired in `commands/fleet.ts`.
-
-### Independent review (3 reviewers: subagent code-reviewer + codex code-review + codex security) → 4 fixes, red-first
- **A · BLOCKER (codex) — regen mutated/deleted legacy operator env.** `applyPreparedAgentEnvironmentProjection`
-  also writes `.env.local`/`.env.quarantine` and unlinks legacy `.env`. Violated projection-only contract.
-  **Fix:** NEW generated-only boundary primitives `prepareGeneratedAgentEnvironmentProjection` +
-  `applyPreparedGeneratedAgentEnvironmentProjection` (write ONLY `<name>.env.generated`). regen now has no
-  code path that touches `.env`/`.env.local`/`.env.quarantine`. **Test:** projection-only leaves legacy `.env`
-  verbatim, no local/quarantine fabricated.
- **B · should-fix (codex + subagent + security) — partial write on mid-loop failure.** Interleaved
-  prepare/apply left earlier agents written when a later agent failed prepare. **Fix:** PREPARE ALL agents
-  before writing ANY (mirrors reconciler `defaultPrepareProjections`). **Test:** 2nd agent's projection
-  pre-seeded 0644 → prepare rejects → coder0 NOT written, exit 1.
- **C · subagent — semantic-validation bypass.** Default readRoster skipped `validateRosterV2Semantics`, so
-  a tampered protected-class `tool_policy` would be silently projected. **Fix:** default readRoster now runs
-  `validateRosterV2Semantics` (persona resolution + protected-class match), rolesDir/overrideDir defaults
-  mirroring the reconciler. **Test:** merge-gate agent w/ tool_policy=code → fails closed, no write.
- **D · MEDIUM (codex security, CWE-362) — concurrent-reconcile race.** regen `--write` wrote without the
-  reconcile lock. **Fix:** `--write` acquires `acquirePrivateReconcileLock(mosaicHome)` for the whole
-  read-prepare-apply sequence, released in `finally`; dry-run stays lock-free. **Test:** pre-held lock →
-  regen fails closed, no write.
-
-**Gate suite after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1265**
-(regen spec 13, incl. 4 new red-first regressions). NOTE: codex self-review does NOT satisfy the
-independent-review gate — an independent (author≠reviewer) review + durable Gitea RoR is still required
-before MS-LEAD merges. STOP at PR-open for MS-LEAD's exact-head review; do NOT self-merge.
-
-## Session 5 — PR3 review round 2 (finding L + M1/M2/M3), red-first fixes
-
-Second review pass on the lock-cleanup plumbing surfaced one round-1 residual (L) and three round-2
-findings (M1 blocker, M2/M3 should-fix). All fixed red-first (RED proven per-finding, then GREEN).
-
- **L · should-fix (codex r1) — mutation-lock release swallowed unlink failures.** regen's
-  `acquirePrivateRosterMutationLock` release copied CRUD's `unlink().catch(()=>{})`, hiding a stale
-  `roster.yaml.mutation.lock`. **Fix:** its release PROPAGATES the unlink fault (finding-J stale-lock
-  warning then fires for this lock too). **Test:** acquire real lock, `rm` it, assert `release()` rejects.
- **M1 · BLOCKER (codex r2) — replacement-lock race.** The propagating release from L did an
-  UNCONDITIONAL `unlink(lockPath)` without proving ownership. If the lock is cleared + re-created by
-  another writer mid-op, regen deletes the STRANGER's live lock → a third writer enters → mutual
-  exclusion defeated. **Fix (reuse, not reimplement):** generalized the reconciler's ownership-proving
-  lock body into shared `acquirePrivateManagedRosterLock(mosaicHome, lockLeaf, busyMessage, openLock)`;
-  `acquirePrivateReconcileLock` delegates to it (behavior-identical: same leaf/codes/messages), and a NEW
-  hardened `acquirePrivateRosterMutationLock` (now in fleet-reconciler.ts, leaf `roster.yaml.mutation.lock`)
-  records dev/ino + ownership token and RE-PROVES ownership (`assertLockOwnership`) before unlinking —
-  fails closed as `lock-cleanup-failed` if replaced. Removed the crud-based export; reverted
-  `acquireMutationLock` (fleet-agent-crud.ts) to its original inline empty-file/swallowing-release form
-  (CRUD behavior intentionally unchanged). Compatibility: CRUD empty-file `wx` and regen tokened `wx`
-  contend on the same path but never co-own (wx winner owns; loser → concurrent-mutation), so the token
-  is only ever read back by the same regen invocation. **Test:** acquire, `rm`+recreate lock (new inode),
-  assert `release()` rejects AND the replacement survives (not unlinked).
- **M2 · should-fix (codex r2) — acquire-unwind fault dropped.** The acquire-failure catch discarded
-  `releaseFleetLocks`' return (a possible fault on the already-held first lock). **Fix:** capture and
-  augment — `const releaseFault = await releaseFleetLocks(releases); throw augmentWithLockCleanupFault(error, releaseFault);`
-  (symmetric to finding J). **Test:** mutation lock acquires w/ faulting release + reconcile acquire
-  throws → thrown error mentions stale/lock, nothing written.
- **M3 · should-fix (codex r2 + subagent REQUEST-CHANGES) — cleanup warning named only reconcile lock.**
-  Finding L made the mutation-lock release fault reachable, so the `cleanup` marker can originate from
-  EITHER lock. **Fix:** `formatFleetRegenReport`'s WARNING now names BOTH `roster.yaml.mutation.lock` and
-  `roster.yaml.reconcile.lock`, matching `augmentWithLockCleanupFault`. **Test:** fault the mutation-lock
-  release specifically → report names both lock files.
-
-**Refactor note (no cycle):** neither fleet-reconciler nor fleet-agent-crud imports the other; regen
-imports lock acquirers from fleet-reconciler and the projection mapping from fleet-reconciler. The two
-reconcile-lock reviewers reconciled: independent reviewer validated acquire-time empty-file compatibility
-(preserved), codex flagged RELEASE-time replacement race (closed by ownership proof) — non-contradictory.
-
-**Gate suite after fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1275**
-(regen spec 23, incl. 7 red-first lock regressions E/F/G/K/L/M1/M2/M3). RED proven per-finding by
-temporary revert before re-applying each fix. Independent (author≠reviewer) review of M1/M2/M3 + codex
-code/security re-run in flight. STOP at PR-open for MS-LEAD's exact-head review + durable Gitea RoR; do
-NOT self-merge; #791 umbrella stays OPEN; PR body `Part of #791`.
-
-### Round 3 review (after M1/M2/M3) — independent review PASS + codex residual-TOCTOU disposition
-Three reviewers on the post-M1/M2/M3 head:
- **Independent (subagent, author≠reviewer) — PASS.** Verified M1/M2/M3 all correctly fixed; "never
-  restarts" is STRUCTURAL (runner never referenced in executable code); no secrets; no deadlock (only
-  regen holds both locks); tests meaningful (assert inode preservation + exact lock-file names). Raised:
-  - **should-fix #1 (fixed, red-first):** generalizing the lock helper left `assertSafeLockLeafIfPresent`/
-    `assertLockOwnership` hardcoding "reconciliation lock" in thrown messages → a MUTATION-lock fault
-    misreported as the reconcile lock, undercutting M3's accurate-diagnosis goal. **Fix:** thread
-    `lockLabel = fleet/<leaf>` through both helpers + the generic lock-io messages, so every fault names
-    the actual lock file. Red-first: strengthened the M1 test to assert `/roster\.yaml\.mutation\.lock/`
-    (RED: got "reconciliation lock"; GREEN after). Also resolves nit #3 (generic-message drift).
-  - **nit #2 (fixed):** `FleetRegenResult.cleanup` JSDoc still said "the shared reconcile lock"; now names
-    both locks (regen holds both).
-  - **nit #4 (fixed):** removed the redundant duplicate `assertLockOwnership` call before unlink
-    (pre-existing in merged main; harmless but dead — dropped since the fn was already being touched).
- **Codex security — clean (risk: none).** Validates roster semantics, constrains env values, no shell
-  eval, no secret output, generated-only writes, serialized against both locks.
- **Codex code — request-changes, 1 "blocker": residual check-then-unlink TOCTOU.** Between the final
-  `assertLockOwnership` and the path-based `unlink`, an external actor could vacate our inode and a new
-  writer grab the path, so the unlink deletes the stranger's lock. **Disposition: documented known
-  limitation, NOT fixed in PR3.** Rationale: (1) byte-identical to the MERGED, shipped reconcile-lock
-  release on origin/main (fleet-reconciler.ts L654-659) — not introduced here; (2) UNREACHABLE within the
-  `wx` writer protocol — no Mosaic writer removes a lock it doesn't own (wx fails EEXIST while our inode
-  exists), so only external interference can vacate our inode in the sub-instruction window; (3) the
-  ownership guard DOES close the reachable case (stale-lock reaper/operator cleared our lock + another
-  writer took it BEFORE release began → fail closed, don't delete stranger's lock); (4) the true atomic
-  fix — fd-held advisory lock (flock/lockf) adopted by ALL fleet writers (CRUD + reconcile + regen) — is
-  a cross-cutting mechanism change touching merged CRUD + reconciler, out of scope for a projection-only
-  recovery PR. Documented honestly in the acquirer doc + M1 test comment. **The binding independent
-  review did NOT treat this as a blocker.** Recommendation to MS-LEAD: proceed to PR-open + spin a
-  SEPARATE follow-up issue for the fd-advisory-lock migration; MS-LEAD adjudicates scope at exact-head
-  review (merge authority).
-
-**Gates after round-3 fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
-**1275** (regen spec 23). Fresh codex code re-run in flight to confirm no NEW issues from the label fix.
-
---
-
-## Session 6 — Round 4/5 convergence (stranded-lock robustness)
-
-**Two independent reviewers converged on the SAME should-fix** on the init-failure cleanup path,
-strengthening confidence it was real:
-
- **Codex code-review-5 — 0 blockers, 1 should-fix.** "Stat failure after lock creation strands the new
-  lock." When `handle.stat()` ITSELF fails right after the `wx` create (transient EIO/EBADF), `created`
-  is `undefined`, so `removeOwnedLockLeafBestEffort` had `if (!created) return;` → no cleanup → the
-  just-created `roster.yaml.mutation.lock`/`reconcile.lock` is stranded, permanently blocking future
-  regen + CRUD. (Notably NO blocker, and the TOCTOU is no longer flagged in code-review as of r5.)
- **Independent delta reviewer (author≠reviewer, pr-review-toolkit) — no blockers, same should-fix.**
-  Independently flagged the identical `!created` gap; validated FIX 1 (label threading — no call site
-  missed, codes unchanged, no test depended on old text) and FIX 2 (dev/ino-guarded cleanup, best-effort,
-  happy-path release reuses captured dev/ino) as correct. Suggested an unconditional best-effort unlink
-  in the `!created` branch; I took the **safer** variant below.
- **Codex security-review-5 — 0 crit / 0 high / 1 medium.** The single medium is the SAME residual
-  check-then-unlink TOCTOU already dispositioned in round 3 (its own remediation = "migrate every writer
-  to an fd-held advisory lock" = the follow-up issue). No new security finding. No secrets.
-
-**Fix (red-first, safer than an unconditional unlink):** thread the persisted random `token` into
-`removeOwnedLockLeafBestEffort`. Two independent ownership proofs now: primary dev/ino (unchanged), and a
-**fallback** when the post-create stat failed — read the leaf and unlink ONLY if its content equals our
-`randomUUID()` token. Only OUR lock carries that token, so a CRUD (empty) or differently-tokened
-replacement is never deleted. `tokenPersisted` guards passing the token (only after `writeFile` lands).
-Doubly-degenerate case (stat fails AND token write never landed) leaves the lock in place rather than
-risk deleting a stranger's file — requires two independent fs faults on a just-created fd; documented.
-
- **Red-first proof:** new test `does not strand the lock file when the post-create stat itself fails`
-  injects a real `wx` create + a Proxy handle whose `stat()` rejects (writeFile/close succeed), asserts
-  `exists(lockPath) === false`. RED before fix (`expected true to be false` — lock stranded); GREEN after.
- **Also fixed (delta nit #3):** `fleet-regen-command.ts` `acquireRosterMutationLock` JSDoc said "CRUD's
-  private lock"; the default is the reconciler's hardened ownership-proving acquirer for the same
-  `fleet/roster.yaml.mutation.lock` path. Corrected.
- **PR-description note (delta nit #2):** FIX 1 also collapsed a pre-existing duplicate back-to-back
-  `assertLockOwnership` call in the release closure (identical args, no intervening logic) into one — a
-  no-op simplification of merged code, not a behavior change. Called out so a future reader doesn't
-  wonder if the duplicate had a purpose.
-
-**Gates after round-4 fixes (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
-**1277** (regen spec now 25: +1 stat-failure stranded-lock regression). Residual TOCTOU still deferred to
-the fd-advisory-lock follow-up issue; MS-LEAD adjudicates scope at exact-head review (merge authority).
-
---
-
-## Session 6 — Round 6 (persona-root wiring)
-
-**Codex code-review-6 — 0 blockers, 1 should-fix (NEW, distinct from the lock work).** "Forward
-configured persona directories to regen." `registerFleetRegenCommand` was registered at
-`fleet.ts:2069` with only `{ runner, mosaicHome }`, discarding `deps.reconcileDeps.rolesDir` /
-`overrideDir`. The regen command ALREADY has those seams (validates roster semantics via
-`validateRosterV2Semantics({ rolesDir, overrideDir })`, defaulting to `<mosaicHome>/fleet/roles{,.local}`),
-but the top-level wiring never forwarded the configured roots. **Impact:** in a deployment with custom
-persona roots, `fleet reconcile` (which honors the overrides) would ACCEPT a roster while `fleet regen`
-REJECTS the same roster (persona resolution against the wrong default dir) — blocking the recovery
-command and violating the documented "resolves personas the SAME way reconcile does" contract.
-
-**Fix (red-first):** forward `rolesDir`/`overrideDir` from `deps.reconcileDeps` into
-`registerFleetRegenCommand` at `fleet.ts:2069`. Red-first test `forwards configured persona roots
-(rolesDir/overrideDir) from reconcileDeps into regen`: seeds personas ONLY under a custom root, leaves
-the default `<home>/fleet/roles` empty, registers with `reconcileDeps: { rolesDir, overrideDir }`, and
-requires `fleet regen` to SUCCEED. RED before fix (`expected 1 not to be 1` — regen validated against the
-empty default and exited 1); GREEN after.
-
-**Codex security-review-6 — 0 crit / 0 high / 1 medium.** Same residual check-then-unlink TOCTOU, now
-noted at BOTH the release closure and the init-cleanup path; remediation = fd-held advisory lock across
-all writers = the SAME deferred follow-up item. No new security finding, no secrets.
-
-**Independent confirmation review of the token-fallback fix (Session 6/round 4) — PASS, no findings.**
-All 7 verification points confirmed; reviewer mechanically reverted `removeOwnedLockLeafBestEffort` to
-the pre-fix `if (!created) return;` and re-ran the new test → RED (`expected true to be false`),
-confirming the test genuinely pins the fix; restored after. No lint/type issues; doc-comment accurate.
-
-**Gates after round-6 fix (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest
-**1278** (regen spec now 26: +1 persona-root wiring regression).
-
---
-
-## Session 6 — Round 7 convergence (review CLOSED for PR-open)
-
- **Codex code-review-7 — 0 blockers, 1 should-fix = the residual TOCTOU** (previously a "blocker" in r3,
-  dropped in r4/r5, now re-surfaced as a should-fix). **Codex security-review-7 — 0 crit / 0 high /
-  1 medium = the SAME residual TOCTOU.** Codex has CONVERGED: the only remaining finding across both
-  streams is that one race, whose own remediation is "fd-held advisory lock shared by all fleet writers"
-  = the deferred follow-up. No new distinct finding; the wiring fix introduced nothing.
- **Independent confirmation review of the persona-root wiring fix — PASS, no findings.** Reviewer
-  mechanically reverted the two forwarded lines → RED (`Roster v2 agent "coder0" class "code" does not
-  resolve to a readable persona` → exit 1), restored → GREEN (26 regen + 204 fleet tests). Confirmed the
-  optional-chaining fallback preserves default-deployment behavior and no type/lint issue.
-
-**Review disposition for PR-open:** ALL actionable findings fixed red-first across rounds 3–6 (label
-threading, stranded-lock on init failure, stat-failure strand, persona-root wiring). The residual
-check-then-unlink TOCTOU is the ONLY open item and is DEFERRED to a follow-up issue (fd-advisory-lock
-migration across CRUD + reconcile + regen) — byte-identical to merged origin/main's reconcile-lock
-release, unreachable within the `wx` writer protocol (no Mosaic writer removes a lock it doesn't own;
-only external `rm`/a stale-lock reaper can vacate the inode mid-release), and its true fix is a
-cross-cutting mechanism change out of scope for a projection-only recovery PR. Two independent human-agent
-reviews (author≠reviewer) treated it as non-blocking. MS-LEAD adjudicates scope at exact-head review
-(merge authority); recommendation = proceed to PR-open + spin the follow-up issue.
-
-**Final gates (all green):** typecheck ✓ · lint ✓ · format:check ✓ · full mosaic vitest **1278**
-(regen spec 26). No secret values in any snapshot/projection/report output (counts + paths only). Regen
-NEVER issues a lifecycle/restart call (load-bearing recordingRunner gate). STOP at PR-open for MS-LEAD's
-exact-head review + durable Reviewer-of-Record before any merge; do NOT self-merge.
--- a/docs/scratchpads/804-install-unknown-flags.md
+++ b/docs/scratchpads/804-install-unknown-flags.md
@@ -1,86 +0,0 @@
-# Issue #804 — fail closed on unknown installer arguments
-
-## Objective
-
-Implement Part 1 of Gitea issue #804 only: `tools/install.sh` must reject every unrecognized flag or argument with an actionable STDERR error and nonzero exit before installation starts.
-
-## Scope and constraints
-
- Preserve all currently recognized options and behavior, including `-y` and `--ref <branch>`.
- No positional arguments are currently accepted by the parser.
- Do not add `--next`, `MOSAIC_NEXT`, prerelease routing, or any Part 2 behavior.
- TDD is mandatory: add and observe a failing process-level regression test before changing `tools/install.sh`.
- Worker lifecycle ends after branch push, PR creation, and coordinator notification; do not merge or close #804.
- Existing launcher-owned changes in `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are out of scope and must not be committed.
-
-## Requirements and acceptance criteria
-
- Unknown input names the offending argument on STDERR.
- STDERR includes a short installer usage hint.
- Exit status is nonzero.
- The installer does not invoke npm or otherwise proceed into installation.
- Existing recognized flags remain unchanged.
-
-## Plan
-
-1. Add a process-level Vitest regression using the installer test location under `packages/mosaic/src/commands/`.
-2. Run the focused test and record the expected RED failure.
-3. Commit the RED test as `test(#804): ...`.
-4. Replace the parser catch-all with a fail-closed STDERR error and usage hint.
-5. Update concise installer-facing documentation without introducing prerelease behavior.
-6. Run focused tests, shell syntax validation, package tests, lint, typecheck, and format checks.
-7. Run independent review tooling and remediate findings.
-8. Commit as `fix(#804): ...`, queue-guard, push, open a PR containing `Closes #804.`, notify the coordinator, and exit.
-
-## Budget
-
- No explicit token cap supplied.
- Working estimate: 8K tokens; narrow two-file behavior/test change plus concise docs and delivery gates.
-
-## Progress
-
- 2026-07-17: Loaded mission state, issue #804, delivery/QA/documentation rails, and relevant TDD/Vitest/pnpm/Gitea skills.
- 2026-07-17: Confirmed the parser has no legitimate positional arguments and currently drops all unmatched input via `*) shift ;;`.
- 2026-07-17: Installed locked workspace dependencies with a worktree-local pnpm store; no lockfile changes.
- 2026-07-17: Added the process-level unknown-argument regression with an isolated `$HOME` and npm shim.
- 2026-07-17: Replaced the silent catch-all with STDERR error + usage output and exit 2 before preflight or installation.
- 2026-07-17: Initial Codex code review found an unknown option could still be consumed as the `--ref` value. Added a second RED reproducer, then rejected option-shaped/missing `--ref` values without changing valid `--ref <branch>` behavior. The review's launcher-state note is handled by excluding both `.mosaic/orchestrator/` files from commits.
- 2026-07-17: Updated README, user guide, and packaged framework README with the fail-closed argument contract. No API, auth, admin, sitemap/navigation, or publishing surface changed.
-
-## Verification
-
- RED: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts` — expected failure: installer exited `0` instead of nonzero at the exit-status assertion; confirms the test reproduces the silent-drop defect before production changes.
- Remediation RED: the added `--cli --ref --bogus` case exited `0`, proving `--ref` could swallow an unknown option before the guard was added.
- GREEN: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/install-arguments.spec.ts src/commands/install-heading.spec.ts` — 2 files, 3 tests passed.
- Situational process check: unknown positional input exited 2, named the input on STDERR, printed usage, and did not call the npm shim.
- `bash -n tools/install.sh` — passed.
- Bare `--ref` process check — exited 2 with `Missing value for --ref` and usage.
- `pnpm --filter @mosaicstack/mosaic test` — 69 files, 1,287 tests passed; framework shell checks passed. The first attempt lacked generated `dist/cli.js`; `pnpm --filter @mosaicstack/mosaic build` restored the required test precondition and the full rerun passed.
- `pnpm lint` — 23/23 tasks passed.
- `pnpm typecheck` — 42/42 tasks passed.
- `pnpm format:check` — passed.
- Codex code re-review against `origin/main` — `approve`, 0 blockers/should-fix/suggestions.
- Codex security re-review against `origin/main` — risk `none`, 0 findings.
-
-## Acceptance evidence
-
-| Criterion | Evidence |
-| --- | --- |
-| Unknown input is named on STDERR | Process-level Vitest assertions for `--bogus`, including after `--ref` |
-| Short usage hint is printed on STDERR | Vitest usage regex + manual process output |
-| Exit is nonzero | Vitest status assertions and manual exit 2 |
-| Installation does not proceed | Isolated npm shim marker remains absent |
-| Recognized behavior is preserved | Parser cases are unchanged except validation of malformed `--ref`; full Mosaic package suite passed |
-| Part 2 is excluded | No `--next`, `MOSAIC_NEXT`, dist-tag, or prerelease routing changes |
-
-## Documentation checklist
-
- Current canonical `docs/PRD.md` remains unchanged; issue #804 and the coordinator brief supply this bounded defect's acceptance contract.
- Updated installer behavior in root README, user guide, and packaged framework README in the same logical change set.
- API/OpenAPI, auth/permissions, admin operations, developer architecture, sitemap/navigation, and external publishing are not affected.
- Scratchpad remains under `docs/scratchpads/`; no root-hygiene changes.
-
-## Risks and blockers
-
- Part 2 remains owner-gated under #805 and is intentionally excluded.
- No implementation blocker remains. Independent coordinator RoR, CI, merge, and issue closure remain pending after worker handoff.
--- a/docs/scratchpads/824-mosaic-skill-cli.md
+++ b/docs/scratchpads/824-mosaic-skill-cli.md
@@ -1,112 +0,0 @@
-# Issue #824 — Mosaic skill CLI and Claude bridge auto-sync
-
-## Objective
-
-Deliver `mosaic skill register|unregister|list` plus install/upgrade reconciliation of every canonical `~/.config/mosaic/skills/*` entry into `~/.claude/skills/`, without clobbering runtime-owned files or directories.
-
-## Scope and constraints
-
- Issue: mosaicstack/stack#824
- Branch: `feat/824-mosaic-skill-cli`
- M1 runtime: Claude Code only.
- Pi/Codex parity is documentation-only; no non-Claude bridge implementation.
- Do not author the downstream `mosaic-context-refresh` skill.
- Workers do not modify `docs/TASKS.md`, merge, close #824, or touch `main`.
- TDD is mandatory and red-first; filesystem tests use temporary directories only.
- Budget: no explicit token cap supplied; use a focused single-worker implementation with no new dependencies.
-
-## Requirements mapping
-
-1. Register creates the canonical Claude symlink and is idempotent.
-2. Names are untrusted: reject empty/escaping/absolute/separator/`..`/leading-dash names before filesystem mutation, with clear CLI stderr and nonzero status.
-3. Register repairs only Mosaic-owned dangling symlinks and refuses foreign files, directories, and symlinks.
-4. Unregister removes only symlinks pointing inside the canonical Mosaic skills root and is idempotent when absent.
-5. List reports registered, dangling, foreign, and canonical-but-unregistered skills.
-6. Install and upgrade generically reconcile all canonical skills after framework sync/re-seed, continuing past foreign conflicts without clobbering them.
-7. User/developer documentation describes commands, status meanings, security boundaries, and Claude-only M1 scope.
-
-## Plan
-
-1. Add co-located failing Vitest coverage for all filesystem behaviors and auto-sync.
-2. Run the focused spec and record the expected RED failure.
-3. Commit the red contract as `test(#824): ...`.
-4. Implement the skill bridge and Commander command registration.
-5. Wire reconciliation into wizard finalize and `mosaic update` re-seed, preserving non-clobber behavior.
-6. Update canonical docs and sitemap if navigation changes.
-7. Run focused tests, package tests, typecheck, lint, and formatting.
-8. Commit implementation/docs as `feat(#824): ...`, queue-guard, push, open PR with `Closes #824.`, fire completion event, and notify the coordinator.
-
-## Progress
-
- 2026-07-17: Loaded mission/delivery/TDD/documentation rails, issue #824, active mission state, and relevant installer/update paths.
- 2026-07-17: Confirmed `mosaic update` invokes `framework/install.sh` with `MOSAIC_SYNC_ONLY=1`; that path exits before existing post-install skill linking, leaving newly present canonical skills unregistered.
- 2026-07-17: Coordinator addendum classified the user-supplied skill name and runtime symlink target as a path-traversal/symlink-injection surface. Expanded the initial red contract to reject traversal before mutation, preserve every foreign entry, and unregister Mosaic-owned links only.
- 2026-07-17: Implemented the Commander command group and secure generic bridge; wired wizard finalize and successful framework re-seed reconciliation; updated user/developer/installed/root docs and sitemap.
- 2026-07-17: Focused, package-wide, repository baseline, temp-home situational, and independent review gates completed. Ready for scoped feature commit, queue guard, push, and PR handoff.
-
-## Tests and evidence
-
-### TDD evidence
-
- RED environment attempt: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/skill.spec.ts` initially could not locate Vitest because this fresh worktree had no dependencies.
- Dependency setup: `pnpm install --frozen-lockfile --store-dir /home/hermes/.local/share/pnpm/store` succeeded. The explicit store was required because machine pnpm config incorrectly resolves the default store under `/root`.
- RED behavior: focused Vitest failed with `Failed to load url ./skill.js ... Does the file exist?`, proving the bridge API was absent.
- RED integration: finalize/update specs failed because no Claude links or `skillSync` result existed.
- RED symlink injection: symlinked Claude/canonical root tests failed because the initial implementation followed ancestor links.
- GREEN after review remediation: `skill.spec.ts` 36/36, `finalize-skills.spec.ts` 6/6, and `update-checker.reseed.spec.ts` 30/30.
-
-### Baseline gates
-
- `pnpm --filter '@mosaicstack/mosaic...' run build` — pass (fresh-worktree dependency outputs built).
- `pnpm --filter @mosaicstack/mosaic run typecheck` — pass.
- `pnpm --filter @mosaicstack/mosaic run lint` — pass.
- `pnpm --filter @mosaicstack/mosaic test` — pass: 69 files, 1,325 Vitest tests plus framework shell suite.
- `pnpm typecheck` — pass: 42/42 Turbo tasks.
- `pnpm lint` — pass: 23/23 Turbo tasks.
- `pnpm format:check` — pass.
-
-### Situational evidence
-
-A built-CLI temp-home smoke test (no real `~/.claude` or Mosaic config touched) proved:
-
- register creates the exact link and a second run reports `already registered`;
- list reports registered and unregistered canonical skills;
- `../../etc` exits 1 with `Invalid skill name` and creates no escaped path;
- unregister removes the managed link and a second run reports `already unregistered`;
- a fake successful framework re-seed generically registered both `added-after-setup` and `second-skill` from runtime directory enumeration.
-
-### Review evidence
-
- Initial uncommitted Codex code/security review described name validation/clobber protection as strong; its only finding was the harness-owned, unrelated `.mosaic/orchestrator/session.lock`, which is excluded from all commits and the PR.
- Exact branch review then identified two remediations: preserve successful framework re-seed status when bridge-wide reconciliation fails, and reject/escape control-character names to prevent terminal/log injection.
- Both findings were reproduced red-first and remediated. A subsequent exact review identified one finalize failure-isolation blocker; a root-wide bridge error now warns and allows wizard doctor/summary/next-steps completion, with a red-first regression.
- All remediations passed the full package and repository gates. Final exact-head review is rerun after amending the feature commit.
-
-### Acceptance mapping
-
-| Acceptance criterion | Evidence |
-| --- | --- |
-| register/unregister/list, idempotent | `skill.spec.ts` and built-CLI temp-home smoke |
-| traversal/symlink-injection protection | invalid-name matrix, foreign file/dir/link tests, symlinked-root tests |
-| list flags dangling and foreign entries | deterministic list status test |
-| install and upgrade auto-sync every canonical directory | finalize + framework re-seed integration specs; two-skill built-module smoke |
-| newly added skill becomes discoverable without manual link | `added-after-setup` auto-sync creates exact Claude link; Claude can rescan with `/reload-skills` or a new session |
-| Pi/Codex parity captured as scope note | user guide, developer guide, installed framework README |
-| documentation gate | root README, user guide, developer guide, framework README, sitemap |
-
-## Risks
-
- Symlink replacement uses `lstat` semantics so dangling links are detectable without following them.
- Link ownership is determined lexically against the canonical skills root, and existing symlink ancestors in either managed root are rejected before mutation.
- Auto-sync continues across per-skill conflicts while never deleting real files/directories or foreign symlinks.
- Claude Code discovers filesystem skills at session launch/reload boundaries; bridge creation makes a later `/reload-skills` or new session able to discover the skill, but cannot mutate an already-cached in-process registry by itself.
- Pi does not need this Claude bridge because its Mosaic launcher can consume the canonical root. Codex lifecycle parity remains explicitly deferred.
- No deployment surface is affected.
-
-## PR #826 review remediation
-
- 2026-07-17: Exact-head RoR requested changes for two ownership bugs: installer pruning deleted foreign-name links under `MOSAIC_HOME` outside canonical skills, and unregister deleted a same-root link targeting a different skill. It also requested trailing-dot rejection and executable coverage support.
- RED evidence: focused regression run failed 4 tests: register/unregister accepted `safe.`, misdirected unregister did not throw, and the install linker deleted the foreign-name link.
- GREEN evidence: `skill.spec.ts` passes 43/43, including live and dangling foreign-name links in a temp HOME/MOSAIC_HOME and the misdirected unregister invariant.
- Coverage: `vitest run src/commands/skill.spec.ts --coverage` passes configured 85% thresholds for `skill.ts`: 91.05% statements/lines, 86.27% branches, 95.23% functions.
- Full gates: package build passed; package tests passed 69 files / 1,332 tests plus framework shell suite; repository typecheck 42/42, lint 23/23, and format check passed.
--- a/docs/scratchpads/ms-792-fleet-enoent-installer.md
+++ b/docs/scratchpads/ms-792-fleet-enoent-installer.md
@@ -1,38 +0,0 @@
-# ms-792 — Fleet roster error handling and installer heading
-
-## Objective
-
-Make expected missing or malformed fleet roster configuration fail with an actionable message and nonzero exit instead of a raw Node stack trace. Ensure the installer preserves the `@mosaicstack/mosaic` heading.
-
-## Plan
-
-1. Add failing coverage for missing and malformed roster input.
-2. Centralize roster-file read and parse error translation; add the CLI async error boundary.
-3. Sweep fleet command read paths that bypass the roster loader.
-4. Replace the installer heading output with format-safe rendering and test it.
-5. Run focused and repository quality checks; request independent review.
-
-## Progress
-
- 2026-07-16: Confirmed issue #792 and branch base `9745bc3f`.
- 2026-07-16: Installed locked workspace dependencies using a worktree-local pnpm store; no `.mosaic/` files were changed intentionally.
- 2026-07-16: Added a shared roster read/parse guard and routed v1 fleet commands plus v1/v2 selection through Commander’s actionable nonzero error path. V2 command modules already return structured nonzero JSON errors for their guarded reads.
- 2026-07-16: Replaced installer heading `echo` with format-safe `printf`; added a regression check for the scoped package heading.
- 2026-07-16: Rebuilt CLI and manually verified `fleet ps` with no roster prints the initialization hint, exits 1, and has no stack trace.
- 2026-07-17: Rebased #818 onto `origin/main` at `9ddc6fbd` (#791 PR3). The added `fleet regen` command had a canonical roster read in its sibling module; it now uses the same missing-roster guard and Commander exit path. Internal NORTH_STAR, preset, and post-write invariant reads remain intentionally unguarded.
- 2026-07-17: RoR found that semantically invalid v1 documents still escaped as plain `Error` values. `normalizeFleetRosterV1` now preserves each validation message while converting it to `FleetRosterConfigurationError`, so its command callers use the actionable nonzero Commander path.
-
-## Verification
-
- `pnpm --filter @mosaicstack/mosaic test` — PASS (61 files, 1,046 tests; executed outside sandbox because CLI smoke tests spawn Node)
- `pnpm typecheck` — PASS
- `pnpm lint` — PASS
- `pnpm format:check` — PASS
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts src/commands/install-heading.spec.ts` — PASS (209 tests)
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet-regen-command.spec.ts` — PASS (27 tests, including missing canonical roster)
- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts -t "semantically invalid v1 roster"` — RED then PASS; verifies duplicate agent names are reported as `fleet.roster` exit 1 without a stack trace.
- Instrumented Vitest coverage is unavailable because `@vitest/coverage-v8` is not declared in this repository. Each branch added in the roster guard has direct unit coverage.
-
-## Risks / blockers
-
- Dependency installation is required before executing Vitest, TypeScript, lint, and formatting gates.
--- a/packages/mosaic/framework/defaults/README.md
+++ b/packages/mosaic/framework/defaults/README.md
@@ -177,23 +177,15 @@ bash tools/install.sh --cli         # npm CLI only (skip framework)
 bash tools/install.sh --ref v1.0    # Install from a specific git ref
 ```

-The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
-
 ## Universal Skills

-The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`. Install, wizard finalization, and `mosaic update` automatically reconcile every canonical skill into Claude Code's `~/.claude/skills/` directory.
+The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`, then links each skill into runtime directories.

 ```bash
-mosaic sync                         # Full canonical catalog sync
-mosaic skill list                   # Show registered, missing, dangling, and foreign entries
-mosaic skill register <name>        # Register or repair one canonical Claude link
-mosaic skill unregister <name>      # Remove one Mosaic-owned Claude link
+mosaic sync                                    # Full sync (clone + link)
+~/.config/mosaic/bin/mosaic-sync-skills --link-only   # Re-link only
 ```

-Skill names are direct children using `[A-Za-z0-9][A-Za-z0-9._-]*`, not paths. Registration rejects traversal/control characters and never replaces foreign files, directories, or symlinks; unregister removes only links that point inside the canonical Mosaic skill root. After registering during a running Claude Code session, use `/reload-skills` or start a new session.
-
-M1 lifecycle management targets Claude Code. Pi can discover the canonical Mosaic root through its launcher configuration. Codex parity remains follow-up scope and continues to use the existing full skill-sync linker.
-
 ## Health Audit

 ```bash
--- a/packages/mosaic/framework/tools/_scripts/mosaic-sync-skills
+++ b/packages/mosaic/framework/tools/_scripts/mosaic-sync-skills
@@ -161,7 +161,6 @@ link_targets=(
 )

 canonical_real="$(readlink -f "$MOSAIC_SKILLS_DIR")"
-local_real="$(readlink -f "$MOSAIC_LOCAL_SKILLS_DIR")"

 # Build an associative array from the colon-separated whitelist for O(1) lookup.
 # When MOSAIC_INSTALL_SKILLS is empty, all skills are allowed.
@@ -204,14 +203,7 @@ link_skill_into_target() {
  link_path="$target_dir/$name"

  if [[ -L "$link_path" ]]; then
-    local raw_target resolved_target
-    raw_target="$(readlink "$link_path")"
-    resolved_target="$(node -e 'const p=require("node:path"); process.stdout.write(p.resolve(p.dirname(process.argv[1]), process.argv[2]));' "$link_path" "$raw_target")"
-    if [[ "$resolved_target" == "$canonical_real/"* || "$resolved_target" == "$local_real/"* ]]; then
-      ln -sfn "$skill_path" "$link_path"
-    else
-      echo "[mosaic-skills] Preserve foreign runtime symlink: $link_path"
-    fi
+    ln -sfn "$skill_path" "$link_path"
    return
  fi

@@ -242,10 +234,14 @@ prune_stale_links_in_target() {
      continue
    fi

-    # -m resolves lexical dangling targets too. If resolution fails, ownership
-    # is unproven and the link must be preserved.
-    resolved="$(readlink -m "$link_path" 2>/dev/null || true)"
-    if [[ -n "$resolved" && "$resolved" == "$canonical_real/"* ]]; then
+    resolved="$(readlink -f "$link_path" 2>/dev/null || true)"
+    if [[ -z "$resolved" ]]; then
+      rm -f "$link_path"
+      echo "[mosaic-skills] Removed stale broken skill link: $link_path"
+      continue
+    fi
+
+    if [[ "$resolved" == "$MOSAIC_HOME/"* ]]; then
      rm -f "$link_path"
      echo "[mosaic-skills] Removed stale retired skill link: $link_path"
    fi
--- a/packages/mosaic/framework/tools/_scripts/mosaic-sync-skills.ps1
+++ b/packages/mosaic/framework/tools/_scripts/mosaic-sync-skills.ps1
@@ -79,26 +79,9 @@ function Link-SkillIntoTarget {

    $linkPath = Join-Path $TargetDir $name

-    # Recreate only Mosaic-owned junctions/symlinks. Foreign reparse points are
-    # runtime-owned and must never be clobbered by install/upgrade auto-sync.
+    # Already a junction/symlink — recreate
    $existing = Get-Item $linkPath -Force -ErrorAction SilentlyContinue
    if ($existing -and ($existing.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) {
-        $rawTarget = @($existing.Target)[0]
-        $candidate = if ([System.IO.Path]::IsPathRooted($rawTarget)) {
-            $rawTarget
-        }
-        else {
-            Join-Path (Split-Path $linkPath -Parent) $rawTarget
-        }
-        $resolvedTarget = [System.IO.Path]::GetFullPath($candidate)
-        $canonicalRoot = [System.IO.Path]::GetFullPath($MosaicSkillsDir).TrimEnd('\') + '\'
-        $localRoot = [System.IO.Path]::GetFullPath($MosaicLocalSkillsDir).TrimEnd('\') + '\'
-        $owned = $resolvedTarget.StartsWith($canonicalRoot, [System.StringComparison]::OrdinalIgnoreCase) -or
-            $resolvedTarget.StartsWith($localRoot, [System.StringComparison]::OrdinalIgnoreCase)
-        if (-not $owned) {
-            Write-Host "[mosaic-skills] Preserve foreign runtime symlink: $linkPath"
-            return
-        }
        Remove-Item $linkPath -Force
    }
    elseif ($existing) {
--- a/packages/mosaic/framework/tools/codex/README.md
+++ b/packages/mosaic/framework/tools/codex/README.md
@@ -70,8 +70,6 @@ Security vulnerability review focusing on:
 ~/.config/mosaic/tools/codex/codex-security-review.sh -n 42
 ```

-PR mode resolves the provider's PR diff rather than relying on the caller's checked-out branch. On Gitea, it fetches the base and `refs/pull/<number>/head` refs and diffs those explicit refs. If the refs cannot be fetched or the resulting diff is empty, the command exits nonzero before Codex runs or a review is posted.
-
 ### Review Against Base Branch

 ```bash
@@ -255,7 +253,7 @@ Run the script from inside a git repository.

 ### "No changes found to review"

-The specified non-PR mode (`--uncommitted`, `--base`, etc.) found no changes to review. PR mode instead fails closed with an actionable error when it cannot construct a non-empty provider diff; verify the PR number, remote, provider login, and ref access before retrying.
+The specified mode (--uncommitted, --base, etc.) found no changes to review.

 ### "Codex produced no output"

--- a/packages/mosaic/framework/tools/codex/common.sh
+++ b/packages/mosaic/framework/tools/codex/common.sh
@@ -44,47 +44,38 @@ build_diff_context() {
            diff_text=$(git show "$value" 2>/dev/null)
            ;;
        pr)
-            # Provider detection writes its result to stdout; suppress it so it cannot
-            # be mistaken for diff content when this function is used in a substitution.
-            detect_platform >/dev/null
+            # For PRs, we need to fetch the PR diff
+            detect_platform
            if [[ "$PLATFORM" == "github" ]]; then
-                diff_text=$(gh pr diff "$value" 2>/dev/null) || {
-                    echo "Error: Failed to fetch the diff for PR #${value}." >&2
-                    return 1
-                }
+                diff_text=$(gh pr diff "$value" 2>/dev/null)
            elif [[ "$PLATFORM" == "gitea" ]]; then
-                local pr_base base_ref pr_head_ref
-                pr_base=$(tea pr list --fields index,base --output simple 2>/dev/null | awk -v pr="$value" '$1 == pr { print $2; exit }')
-                if [[ -z "$pr_base" ]]; then
-                    echo "Error: Could not resolve the base branch for Gitea PR #${value}." >&2
-                    return 1
+                # tea doesn't have a direct pr diff command, use git
+                local pr_base
+                pr_base=$(tea pr list --fields index,base --output simple 2>/dev/null | grep "^${value}" | awk '{print $2}')
+                if [[ -n "$pr_base" ]]; then
+                    diff_text=$(git diff "${pr_base}...HEAD" 2>/dev/null)
+                else
+                    # Fallback: fetch PR info via API
+                    local repo_info
+                    repo_info=$(get_repo_info)
+                    local remote_url
+                    remote_url=$(git remote get-url origin 2>/dev/null)
+                    local host
+                    host=$(echo "$remote_url" | sed -E 's|.*://([^/]+).*|\1|; s|.*@([^:]+).*|\1|')
+                    diff_text=$(curl -s "https://${host}/api/v1/repos/${repo_info}/pulls/${value}" \
+                        -H "Authorization: token $(tea login list --output simple 2>/dev/null | head -1 | awk '{print $2}')" \
+                        2>/dev/null | jq -r '.diff_url // empty')
+                    if [[ -n "$diff_text" && "$diff_text" != "null" ]]; then
+                        diff_text=$(curl -s "$diff_text" 2>/dev/null)
+                    else
+                        diff_text=$(git diff "main...HEAD" 2>/dev/null)
+                    fi
                fi
-
-                base_ref="refs/remotes/origin/${pr_base}"
-                pr_head_ref="refs/remotes/origin/pr/${value}/head"
-                if ! git fetch --quiet origin \
-                    "+refs/heads/${pr_base}:${base_ref}" \
-                    "+refs/pull/${value}/head:${pr_head_ref}"; then
-                    echo "Error: Failed to fetch the base and head refs for Gitea PR #${value}." >&2
-                    return 1
-                fi
-                diff_text=$(git diff "${base_ref}...${pr_head_ref}") || {
-                    echo "Error: Failed to diff the fetched refs for Gitea PR #${value}." >&2
-                    return 1
-                }
-            else
-                echo "Error: Unsupported git platform while resolving PR #${value}." >&2
-                return 1
            fi
            ;;
    esac

-    if [[ "$mode" == "pr" && -z "${diff_text//[[:space:]]/}" ]]; then
-        echo "Error: Unable to construct a non-empty diff for PR #${value}; verify the PR refs and provider access." >&2
-        return 1
-    fi
-
-    printf '%s\n' "$diff_text"
+    echo "$diff_text"
 }

 # Format JSON findings as markdown for PR comments
--- a/packages/mosaic/framework/tools/codex/test-pr-diff-context.sh
+++ b/packages/mosaic/framework/tools/codex/test-pr-diff-context.sh
@@ -1,158 +0,0 @@
-#!/bin/bash
-# Hermetic regression coverage for Gitea PR diff construction and fail-closed reviews.
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TMP_DIR=$(mktemp -d)
-trap 'rm -rf "$TMP_DIR"' EXIT
-
-fail() {
-    echo "not ok - $*" >&2
-    exit 1
-}
-
-assert_contains() {
-    local haystack="$1" needle="$2"
-    if [[ "$haystack" != *"$needle"* ]]; then
-        printf 'actual output:\n%s\n' "$haystack" >&2
-        fail "expected output to contain: $needle"
-    fi
-}
-
-# Prevent CI-provided repository context from leaking into the fixture repositories.
-unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_OBJECT_DIRECTORY \
-    GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR
-export GIT_AUTHOR_NAME="Codex Fixture"
-export GIT_AUTHOR_EMAIL="codex-fixture@example.test"
-export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
-export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
-export GITEA_LOGIN="fixture"
-export GITEA_TOKEN="fixture-token"
-export GITEA_URL="file://$TMP_DIR"
-
-create_pr_fixture() {
-    local fixture_root="$1" head_mode="$2"
-    local origin="$fixture_root/origin.git"
-    local seed="$fixture_root/seed"
-    local work="$fixture_root/work"
-    local base_sha head_sha
-
-    mkdir -p "$fixture_root"
-    git init --quiet --bare "$origin"
-    git init --quiet --initial-branch=release/next "$seed"
-    printf 'base\n' > "$seed/pr-change.ts"
-    git -C "$seed" add pr-change.ts
-    git -C "$seed" commit --quiet -m "fixture base"
-    base_sha=$(git -C "$seed" rev-parse HEAD)
-    git -C "$seed" remote add origin "$origin"
-    git -C "$seed" push --quiet origin release/next
-    git --git-dir="$origin" symbolic-ref HEAD refs/heads/release/next
-
-    if [[ "$head_mode" == "changed" ]]; then
-        git -C "$seed" switch --quiet -c feature/pr-795
-        printf 'actual-pr-change\n' > "$seed/pr-change.ts"
-        git -C "$seed" commit --quiet -am "fixture PR head"
-        head_sha=$(git -C "$seed" rev-parse HEAD)
-        git -C "$seed" push --quiet origin HEAD:refs/pull/795/head
-    else
-        head_sha="$base_sha"
-        git --git-dir="$origin" update-ref refs/pull/795/head "$head_sha"
-    fi
-
-    # Gitea's provider-owned PR head ref now exists in the local bare origin.
-    git clone --quiet "$origin" "$work"
-    printf '%s\n' "$work"
-}
-
-FAKE_BIN="$TMP_DIR/bin"
-mkdir -p "$FAKE_BIN"
-cat > "$FAKE_BIN/tea" <<'STUB'
-#!/bin/bash
-if [[ "$*" == "pr list --fields index,base --output simple" ]]; then
-    printf '795 release/next\n'
-    exit 0
-fi
-exit 1
-STUB
-cat > "$FAKE_BIN/codex" <<'STUB'
-#!/bin/bash
-printf 'CODEX %s\n' "$*" >> "$CODEX_LOG"
-exit 99
-STUB
-chmod +x "$FAKE_BIN/tea" "$FAKE_BIN/codex"
-export PATH="$FAKE_BIN:$PATH"
-
-# The valid fixture is a fresh clone on the non-main base. The PR head exists only
-# at refs/pull/795/head, so local HEAD cannot accidentally satisfy the assertion.
-if [[ "${1:-all}" != "fail-closed" ]]; then
-    VALID_WORK=$(create_pr_fixture "$TMP_DIR/valid" changed)
-    (
-        cd "$VALID_WORK"
-        # shellcheck source=common.sh
-        source "$SCRIPT_DIR/common.sh"
-        diff_context=$(build_diff_context pr 795)
-        assert_contains "$diff_context" "actual-pr-change"
-
-        base_sha=$(git rev-parse refs/remotes/origin/release/next)
-        head_sha=$(git rev-parse refs/remotes/origin/pr/795/head)
-        local_sha=$(git rev-parse HEAD)
-        [[ "$local_sha" == "$base_sha" ]] || fail "fixture clone is not on the PR base"
-        [[ "$head_sha" != "$base_sha" ]] || fail "fixture PR head does not differ from its base"
-        git show-ref --verify --quiet refs/remotes/origin/pr/795/head || \
-            fail "fetched PR head ref is missing"
-        [[ "$(git diff --name-only "${base_sha}...${head_sha}")" == "pr-change.ts" ]] || \
-            fail "explicit PR refs do not contain the fixture change"
-        if git show-ref --verify --quiet refs/heads/main || \
-            git show-ref --verify --quiet refs/remotes/origin/main; then
-            fail "fixture unexpectedly contains a main ref"
-        fi
-    )
-    echo "ok - Gitea PR mode fetches and diffs explicit non-main base and PR head refs"
-fi
-
-# Build an empty PR entirely inside another local repository. Both review wrappers
-# must emit the PR-numbered error before Codex or the stubbed post path can execute.
-if [[ "${1:-all}" != "pr-head" ]]; then
-    EMPTY_WORK=$(create_pr_fixture "$TMP_DIR/empty" empty)
-    SANDBOX="$TMP_DIR/sandbox"
-    mkdir -p "$SANDBOX/tools/codex/schemas" "$SANDBOX/tools/git"
-    cp "$SCRIPT_DIR/common.sh" \
-        "$SCRIPT_DIR/codex-code-review.sh" \
-        "$SCRIPT_DIR/codex-security-review.sh" \
-        "$SANDBOX/tools/codex/"
-    cp "$SCRIPT_DIR/schemas/code-review-schema.json" \
-        "$SCRIPT_DIR/schemas/security-review-schema.json" \
-        "$SANDBOX/tools/codex/schemas/"
-    cp "$SCRIPT_DIR/../git/detect-platform.sh" "$SANDBOX/tools/git/"
-
-    cat > "$SANDBOX/tools/git/pr-review.sh" <<'STUB'
-#!/bin/bash
-printf 'POST %s\n' "$*" >> "$POST_LOG"
-STUB
-    chmod +x "$SANDBOX/tools/git/pr-review.sh"
-
-    POST_LOG="$TMP_DIR/post.log"
-    CODEX_LOG="$TMP_DIR/codex.log"
-    export POST_LOG CODEX_LOG
-
-    for review_kind in code security; do
-        : > "$POST_LOG"
-        : > "$CODEX_LOG"
-        review_script="$SANDBOX/tools/codex/codex-${review_kind}-review.sh"
-        set +e
-        (
-            cd "$EMPTY_WORK"
-            "$review_script" -n 795
-        ) >"$TMP_DIR/${review_kind}.stdout" 2>"$TMP_DIR/${review_kind}.stderr"
-        review_status=$?
-        set -e
-
-        stderr_text=$(cat "$TMP_DIR/${review_kind}.stderr")
-        [[ "$review_status" -ne 0 ]] || fail "${review_kind} review returned success for an empty PR diff"
-        [[ ! -s "$CODEX_LOG" ]] || fail "Codex ran for an empty ${review_kind} PR diff"
-        [[ ! -s "$POST_LOG" ]] || fail "${review_kind} review auto-post ran for an empty PR diff"
-        assert_contains "$stderr_text" "Error:"
-        assert_contains "$stderr_text" "PR #795"
-        echo "ok - empty ${review_kind} PR diff fails closed before Codex and auto-post"
-    done
-fi
--- a/packages/mosaic/package.json
+++ b/packages/mosaic/package.json
@@ -24,8 +24,7 @@
    "build": "tsc",
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/codex/test-pr-diff-context.sh"
+    "test": "vitest run --passWithNoTests"
  },
  "dependencies": {
    "@mosaicstack/brain": "workspace:*",
@@ -53,7 +52,6 @@
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
-    "@vitest/coverage-v8": "^2.0.0",
    "@types/react": "^18.3.0",
    "tsx": "^4.0.0",
    "typescript": "^5.8.0",
--- a/packages/mosaic/src/cli.ts
+++ b/packages/mosaic/src/cli.ts
@@ -18,7 +18,6 @@ import { registerFleetCommand } from './commands/fleet.js';
 import { registerMissionCommand } from './commands/mission.js';
 import { registerUninstallCommand } from './commands/uninstall.js';
 import { registerRestoreCommand } from './commands/restore.js';
-import { registerSkillCommand } from './commands/skill.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
 import { registerAuthCommand } from './commands/auth.js';
@@ -68,7 +67,7 @@ Command Groups:

  Runtime:    tui, login, sessions
  Gateway:    gateway
-  Framework:  agent, bootstrap, coord, doctor, fleet, init, launch, mission, prdy, seq, skill, sync, upgrade, wizard, yolo
+  Framework:  agent, bootstrap, coord, doctor, fleet, init, launch, mission, prdy, seq, sync, upgrade, wizard, yolo
  Platform:   update
  Runtimes:   claude, codex, opencode, pi
 `,
@@ -412,10 +411,6 @@ registerUninstallCommand(program);

 registerRestoreCommand(program);

-// ─── skill ───────────────────────────────────────────────────────────────────
-
-registerSkillCommand(program);
-
 // ─── telemetry ───────────────────────────────────────────────────────────────

 registerTelemetryCommand(program);
@@ -476,18 +471,6 @@ program
          return;
        }
        console.log('✔ Framework re-seeded.');
-        if (reseed.skillSyncError) {
-          console.error(`  ⚠ Claude skill reconciliation skipped: ${reseed.skillSyncError}`);
-        }
-        const skillConflicts = reseed.skillSync?.conflicts ?? [];
-        const skillChanges =
-          (reseed.skillSync?.registered.length ?? 0) + (reseed.skillSync?.repaired.length ?? 0);
-        if (skillChanges > 0) {
-          console.log(`✔ Registered ${skillChanges.toString()} Mosaic skill(s) with Claude Code.`);
-        }
-        for (const conflict of skillConflicts) {
-          console.error(`  ⚠ Skill registration skipped for ${conflict.name}: ${conflict.reason}`);
-        }
        // Propagate shipped systemd unit fixes to the ACTIVE units (re-seed only
        // touches ~/.config/mosaic/systemd/user; systemd runs ~/.config/systemd/user).
        const units = refreshActiveFleetUnits();
--- a/packages/mosaic/src/commands/fleet-regen-command.spec.ts
+++ b/packages/mosaic/src/commands/fleet-regen-command.spec.ts
@@ -1,896 +0,0 @@
-import { chmod, mkdir, mkdtemp, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { Command } from 'commander';
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { registerFleetCommand, type CommandResult, type FleetCommandDeps } from './fleet.js';
-import { executeFleetRegen, formatFleetRegenReport } from './fleet-regen-command.js';
-import {
-  acquirePrivateRosterMutationLock,
-  projectRosterV2AgentGeneratedEnv,
-} from '../fleet/fleet-reconciler.js';
-import { applyPreparedGeneratedAgentEnvironmentProjection } from '../fleet/generated-env-boundary.js';
-import { parseRosterV2 } from '../fleet/roster-v2.js';
-
-// A two-agent roster-v2 SSOT. `mosaic fleet regen` must rebuild each agent's
-// `fleet/agents/<name>.env.generated` projection from exactly this source and
-// nothing else — deterministically, without ever touching agent lifecycle.
-const rosterYaml = `
-version: 2
-generation: 7
-transport: tmux
-tmux:
-  socket_name: mosaic-fleet
-  holder_session: _holder
-defaults:
-  working_directory: /srv/mosaic
-  runtime: pi
-runtimes:
-  pi:
-    reset_command: /new
-agents:
-  - name: coder0
-    alias: Coder 0
-    class: code
-    runtime: pi
-    provider: openai
-    model: gpt-5.6-sol
-    reasoning: high
-    tool_policy: code
-    working_directory: /srv/mosaic
-    persistent_persona: false
-    reset_between_tasks: true
-    lifecycle:
-      enabled: true
-      desired_state: stopped
-    launch:
-      yolo: true
-  - name: coder1
-    alias: Coder 1
-    class: code
-    runtime: pi
-    provider: openai
-    model: gpt-5.6-sol
-    reasoning: medium
-    tool_policy: code
-    working_directory: /srv/other
-    persistent_persona: false
-    reset_between_tasks: true
-    lifecycle:
-      enabled: true
-      desired_state: stopped
-    launch:
-      yolo: true
-`;
-
-let cleanup: string | undefined;
-
-afterEach(async (): Promise<void> => {
-  vi.restoreAllMocks();
-  process.exitCode = undefined;
-  if (cleanup) await rm(cleanup, { recursive: true, force: true });
-  cleanup = undefined;
-});
-
-async function fleetHome(withRoster = rosterYaml): Promise<string> {
-  cleanup = await mkdtemp(join(tmpdir(), 'mosaic-fleet-regen-command-'));
-  for (const directory of ['fleet', 'fleet/agents', 'fleet/roles']) {
-    await mkdir(join(cleanup, directory), { recursive: true, mode: 0o700 });
-    await chmod(join(cleanup, directory), 0o700);
-  }
-  await chmod(cleanup, 0o700);
-  await writeFile(join(cleanup, 'fleet', 'roster.yaml'), withRoster, { mode: 0o600 });
-  // Semantic roster validation (matching `fleet reconcile`) resolves each agent
-  // class to a persona; seed the classes the fixtures reference.
-  for (const klass of ['code', 'merge-gate']) {
-    await writeFile(
-      join(cleanup, 'fleet', 'roles', `${klass}.md`),
-      `\`class: ${klass}\`\n\n# ${klass} persona\n`,
-      { mode: 0o600 },
-    );
-  }
-  return cleanup;
-}
-
-/**
- * A runner spy that records EVERY invocation. `regen` is projection-only and
- * must never issue a lifecycle/restart call, so a non-empty call log is a
- * hard failure — this is the load-bearing "never restarts" gate.
- */
-function recordingRunner(
-  calls: string[][],
-): (command: string, args: string[]) => Promise<CommandResult> {
-  return async (command: string, args: string[]): Promise<CommandResult> => {
-    calls.push([command, ...args]);
-    return { stdout: '', stderr: '', exitCode: 0 };
-  };
-}
-
-function program(mosaicHome: string, runner: FleetCommandDeps['runner']): Command {
-  const result = new Command();
-  result.exitOverride();
-  registerFleetCommand(result, { mosaicHome, runner });
-  return result;
-}
-
-function capture(): string[] {
-  const lines: string[] = [];
-  vi.spyOn(console, 'log').mockImplementation((value: string): void => {
-    lines.push(value);
-  });
-  return lines;
-}
-
-async function exists(path: string): Promise<boolean> {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-describe('projectRosterV2AgentGeneratedEnv', (): void => {
-  it('maps a roster-v2 agent to exactly the eight generated projection keys', (): void => {
-    const roster = parseRosterV2(rosterYaml, 'yaml');
-    const agent = roster.agents.find((candidate) => candidate.name === 'coder0');
-    expect(agent).toBeDefined();
-    const values = projectRosterV2AgentGeneratedEnv(roster, agent!);
-    expect(values).toEqual({
-      MOSAIC_AGENT_NAME: 'coder0',
-      MOSAIC_AGENT_CLASS: 'code',
-      MOSAIC_AGENT_RUNTIME: 'pi',
-      MOSAIC_AGENT_MODEL: 'gpt-5.6-sol',
-      MOSAIC_AGENT_REASONING: 'high',
-      MOSAIC_AGENT_TOOL_POLICY: 'code',
-      MOSAIC_AGENT_WORKDIR: '/srv/mosaic',
-      MOSAIC_TMUX_SOCKET: 'mosaic-fleet',
-    });
-  });
-});
-
-describe('mosaic fleet regen', (): void => {
-  it('reports a missing canonical roster with the shared initialization hint', async (): Promise<void> => {
-    const home = await mkdtemp(join(tmpdir(), 'mosaic-fleet-regen-missing-roster-'));
-    cleanup = home;
-
-    await expect(
-      program(home, recordingRunner([])).parseAsync(['node', 'mosaic', 'fleet', 'regen', '--json']),
-    ).rejects.toThrow(
-      `No fleet roster found at ${join(home, 'fleet', 'roster.yaml')}. Run \`mosaic fleet init\``,
-    );
-  });
-
-  it('is dry-run by default: reports the plan and writes nothing', async (): Promise<void> => {
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    const lines = capture();
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--json',
-    ]);
-
-    const result = JSON.parse(lines.pop() ?? '{}');
-    expect(result).toMatchObject({
-      mode: 'dry-run',
-      generation: 7,
-      agentCount: 2,
-      written: 0,
-    });
-    expect(result.agents.map((agent: { name: string }) => agent.name)).toEqual([
-      'coder0',
-      'coder1',
-    ]);
-    expect(
-      result.agents.every((agent: { disposition: string }) => agent.disposition === 'create'),
-    ).toBe(true);
-    // Nothing on disk.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder1.env.generated'))).toBe(false);
-    // No lifecycle/restart call — ever.
-    expect(calls).toEqual([]);
-  });
-
-  it('forwards configured persona roots (rolesDir/overrideDir) from reconcileDeps into regen', async (): Promise<void> => {
-    // Codex r6: regen must resolve personas the SAME way reconcile does. If the
-    // top-level registration drops reconcileDeps.rolesDir/overrideDir, a deployment
-    // with custom persona roots gets reconcile ACCEPTING a roster while regen
-    // REJECTS it (validating against the wrong default `<home>/fleet/roles`),
-    // blocking the recovery command. Pin the wiring: seed personas ONLY under the
-    // custom roots, leave the default roles dir empty, require regen to succeed.
-    const home = await mkdtemp(join(tmpdir(), 'mosaic-fleet-regen-wiring-'));
-    cleanup = home;
-    for (const directory of ['fleet', 'fleet/agents', 'fleet/roles']) {
-      await mkdir(join(home, directory), { recursive: true, mode: 0o700 });
-      await chmod(join(home, directory), 0o700);
-    }
-    await chmod(home, 0o700);
-    await writeFile(join(home, 'fleet', 'roster.yaml'), rosterYaml, { mode: 0o600 });
-    // Personas live ONLY under the configured roots — the default `fleet/roles`
-    // stays empty, so broken wiring fails persona resolution.
-    const customRoles = join(home, 'custom-roles');
-    const customOverride = join(home, 'custom-roles.local');
-    await mkdir(customRoles, { recursive: true, mode: 0o700 });
-    await mkdir(customOverride, { recursive: true, mode: 0o700 });
-    for (const klass of ['code', 'merge-gate']) {
-      await writeFile(join(customRoles, `${klass}.md`), `\`class: ${klass}\`\n\n# ${klass}\n`, {
-        mode: 0o600,
-      });
-    }
-
-    const command = new Command();
-    command.exitOverride();
-    registerFleetCommand(command, {
-      mosaicHome: home,
-      runner: recordingRunner([]),
-      reconcileDeps: { rolesDir: customRoles, overrideDir: customOverride },
-    });
-    const lines = capture();
-
-    await command.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--json']);
-
-    // Regen validated against the CONFIGURED roots → success. Broken wiring
-    // resolves against the empty default and fails (exitCode 1, no JSON result).
-    expect(process.exitCode).not.toBe(1);
-    const result = JSON.parse(lines.pop() ?? '{}');
-    expect(result).toMatchObject({ mode: 'dry-run', agentCount: 2 });
-  });
-
-  it('--write rebuilds each generated projection from the roster SSOT', async (): Promise<void> => {
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    const lines = capture();
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    const result = JSON.parse(lines.pop() ?? '{}');
-    expect(result).toMatchObject({ mode: 'write', written: 2, agentCount: 2 });
-
-    const coder0 = await readFile(join(home, 'fleet', 'agents', 'coder0.env.generated'), 'utf8');
-    expect(coder0).toContain('MOSAIC_AGENT_NAME=coder0');
-    expect(coder0).toContain('MOSAIC_AGENT_WORKDIR=/srv/mosaic');
-    expect(coder0).toContain('MOSAIC_TMUX_SOCKET=mosaic-fleet');
-    const coder1 = await readFile(join(home, 'fleet', 'agents', 'coder1.env.generated'), 'utf8');
-    expect(coder1).toContain('MOSAIC_AGENT_NAME=coder1');
-    expect(coder1).toContain('MOSAIC_AGENT_WORKDIR=/srv/other');
-    // No lifecycle/restart call — ever.
-    expect(calls).toEqual([]);
-  });
-
-  it('is deterministic and idempotent across repeated --write runs', async (): Promise<void> => {
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    const path = join(home, 'fleet', 'agents', 'coder0.env.generated');
-
-    const cli = program(home, recordingRunner(calls));
-    capture();
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--write', '--json']);
-    const first = await readFile(path, 'utf8');
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--write', '--json']);
-    const second = await readFile(path, 'utf8');
-
-    expect(second).toBe(first);
-    expect(calls).toEqual([]);
-  });
-
-  it('reports rebuild disposition once the generated projection already exists', async (): Promise<void> => {
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    const cli = program(home, recordingRunner(calls));
-    const lines = capture();
-
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--write', '--json']);
-    lines.length = 0;
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--json']);
-
-    const result = JSON.parse(lines.pop() ?? '{}');
-    expect(
-      result.agents.every((agent: { disposition: string }) => agent.disposition === 'rebuild'),
-    ).toBe(true);
-    expect(result.written).toBe(0);
-    expect(calls).toEqual([]);
-  });
-
-  it('never issues a lifecycle/restart call in either mode', async (): Promise<void> => {
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    const cli = program(home, recordingRunner(calls));
-    capture();
-
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--json']);
-    await cli.parseAsync(['node', 'mosaic', 'fleet', 'regen', '--write', '--json']);
-
-    // Structural guarantee: regen has no path to systemctl/tmux at all.
-    expect(calls).toEqual([]);
-    const systemctlCalls = calls.filter(([command]) => command === 'systemctl');
-    expect(systemctlCalls).toEqual([]);
-  });
-
-  it('human-readable --write output prints the do-not-restart recovery runbook', async (): Promise<void> => {
-    const home = await fleetHome();
-    const lines = capture();
-
-    await program(home, recordingRunner([])).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-    ]);
-
-    const output = lines.join('\n');
-    expect(output).toMatch(/do not restart|before.*restart/i);
-    expect(output).toMatch(/env\.generated/);
-    // The unit has no EnvironmentFile= directive, so the runbook must NOT tell the
-    // operator to verify one — verify the launcher/generated file instead.
-    expect(output).not.toContain('EnvironmentFile');
-    expect(output).toMatch(/systemctl --user cat mosaic-agent@<name>/);
-    expect(output).toMatch(/restart/i);
-  });
-
-  it('emits paths and counts only — never the projected env body (secrev)', async (): Promise<void> => {
-    const home = await fleetHome();
-    const lines = capture();
-
-    await program(home, recordingRunner([])).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-    ]);
-
-    const output = lines.join('\n');
-    // Relative paths + counts are fine; the rendered projection body (KEY=value
-    // lines) must never be echoed to stdout.
-    expect(output).toContain('coder0.env.generated');
-    expect(output).not.toMatch(/^MOSAIC_AGENT_\w+=/m);
-    expect(output).not.toContain('MOSAIC_TMUX_SOCKET=mosaic-fleet');
-  });
-
-  it('is projection-only: leaves legacy .env untouched and writes no .env.local/.env.quarantine', async (): Promise<void> => {
-    // Recovery contract: regen rebuilds ONLY <name>.env.generated. It must never
-    // relocate, quarantine, or unlink the operator-owned legacy .env surface — the
-    // full reconciler apply path does, so regen must NOT use it.
-    const home = await fleetHome();
-    const legacyPath = join(home, 'fleet', 'agents', 'coder0.env');
-    await writeFile(legacyPath, 'MOSAIC_RUNTIME_BIN=/usr/bin/pi\n', { mode: 0o600 });
-    capture();
-
-    await program(home, recordingRunner([])).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    // Generated projection rebuilt...
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(true);
-    // ...but the operator's legacy .env is preserved verbatim, and no local/quarantine
-    // files were fabricated from it.
-    expect(await readFile(legacyPath, 'utf8')).toBe('MOSAIC_RUNTIME_BIN=/usr/bin/pi\n');
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.local'))).toBe(false);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.quarantine'))).toBe(false);
-  });
-
-  it('prepares every agent before writing any: a later prepare failure leaves nothing written', async (): Promise<void> => {
-    // Fail-closed across agents. Pre-seed coder1's projection with world-readable
-    // perms so its prepare rejects; coder0 (valid) must NOT be written because
-    // preparation is fully completed before the first apply.
-    const home = await fleetHome();
-    const coder1Path = join(home, 'fleet', 'agents', 'coder1.env.generated');
-    await writeFile(coder1Path, 'MOSAIC_AGENT_NAME=coder1\n', { mode: 0o644 });
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    // coder0 is valid but must remain unwritten — no partial rebuild.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('fails closed on a semantically invalid roster (protected-class tool-policy mismatch)', async (): Promise<void> => {
-    // A hand-edited roster giving a protected class a weaker tool_policy is rejected
-    // by reconcile/plan/verify; regen must enforce the SAME gate, not silently
-    // project the downgraded policy into <name>.env.generated.
-    const home = await fleetHome(`
-version: 2
-generation: 3
-transport: tmux
-tmux:
-  socket_name: mosaic-fleet
-  holder_session: _holder
-defaults:
-  working_directory: /srv/mosaic
-  runtime: pi
-runtimes:
-  pi:
-    reset_command: /new
-agents:
-  - name: gate0
-    alias: Gate 0
-    class: merge-gate
-    runtime: pi
-    provider: openai
-    model: gpt-5.6-sol
-    reasoning: high
-    tool_policy: code
-    working_directory: /srv/mosaic
-    persistent_persona: false
-    reset_between_tasks: true
-    lifecycle:
-      enabled: true
-      desired_state: stopped
-    launch:
-      yolo: true
-`);
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    expect(await exists(join(home, 'fleet', 'agents', 'gate0.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('refuses to write while a concurrent reconcile holds the mutation lock', async (): Promise<void> => {
-    // regen --write mutates the same projections as reconcile; it must take the
-    // shared reconcile lock so a concurrent reconcile cannot race a stale write.
-    const home = await fleetHome();
-    await writeFile(join(home, 'fleet', 'roster.yaml.reconcile.lock'), 'held\n', { mode: 0o600 });
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('fails closed (non-zero, no writes) on an invalid roster', async (): Promise<void> => {
-    // roster-v2 requires >= 1 agent; a malformed roster must abort regen without
-    // writing any projection and without touching lifecycle.
-    const home = await fleetHome('version: 2\ngeneration: 1\n');
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('rejects a non-canonical --roster path (canonical roster only)', async (): Promise<void> => {
-    // `fleet` exposes a global `--roster`; reconcile rejects a non-canonical value
-    // rather than silently reading the canonical roster. regen must enforce the
-    // SAME guard so `--roster /elsewhere regen --write` cannot mislead the operator.
-    const home = await fleetHome();
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      '--roster',
-      join(home, 'other', 'roster.yaml'),
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    expect(errors.join('')).toMatch(/canonical roster/i);
-    // No projection written against a misdirected roster path.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('reports an incomplete rebuild when a later projection write fails mid-loop', async (): Promise<void> => {
-    // Fault injected on the SECOND apply: coder0 is already replaced on disk, so a
-    // bare throw would hide the partial state. regen must surface which agents were
-    // rebuilt and which failed, with a verify-before-restart recovery instruction.
-    const home = await fleetHome();
-    const realApply = applyPreparedGeneratedAgentEnvironmentProjection;
-    const result = await executeFleetRegen(
-      {
-        runner: recordingRunner([]),
-        mosaicHome: home,
-        applyProjection: async (prepared): Promise<string> => {
-          if (prepared.generatedPath.endsWith('coder1.env.generated')) {
-            throw new Error('simulated ENOSPC on coder1');
-          }
-          return realApply(prepared);
-        },
-      },
-      { write: true },
-    );
-
-    // coder0 written before the fault; coder1 not.
-    expect(result.written).toBe(1);
-    expect(result.incomplete).toMatchObject({
-      code: 'projection-apply-failed',
-      failedAgent: 'coder1',
-      writtenAgents: ['coder0'],
-    });
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(true);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder1.env.generated'))).toBe(false);
-
-    // The human report names the failed agent and directs a verify-before-restart
-    // recovery — not a bare success runbook.
-    const report = formatFleetRegenReport(result).join('\n');
-    expect(report).toMatch(/incomplete/i);
-    expect(report).toContain('coder1');
-    expect(report).toMatch(/verify|re-run|retry/i);
-    // Structural: still no lifecycle call anywhere on the failure path.
-    expect(report).not.toMatch(/systemctl --user restart mosaic-agent@<name>\n.*\n/);
-  });
-
-  it('refuses to write while agent CRUD holds the roster mutation lock', async (): Promise<void> => {
-    // regen --write overwrites the SAME generated projections that `fleet agent
-    // create/update/delete` writes under roster.yaml.mutation.lock. If regen only
-    // took the reconcile lock it could read a stale roster and overwrite a just-
-    // committed projection. It must also take the mutation lock and fail closed.
-    const home = await fleetHome();
-    await writeFile(join(home, 'fleet', 'roster.yaml.mutation.lock'), 'crud\n', { mode: 0o600 });
-    const calls: string[][] = [];
-    capture();
-    const errors: string[] = [];
-    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array): boolean => {
-      errors.push(String(chunk));
-      return true;
-    });
-
-    await program(home, recordingRunner(calls)).parseAsync([
-      'node',
-      'mosaic',
-      'fleet',
-      'regen',
-      '--write',
-      '--json',
-    ]);
-
-    expect(process.exitCode).toBe(1);
-    expect(errors.join('')).toMatch(/regen failed/i);
-    // No projection written against a roster a concurrent CRUD is mutating.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder1.env.generated'))).toBe(false);
-    expect(calls).toEqual([]);
-  });
-
-  it('surfaces BOTH the roster failure and a stale-lock warning on a double fault', async (): Promise<void> => {
-    // Worst case with nothing written: run() fails (invalid roster, fail-closed) AND
-    // a lock release faults. The operator must be told the lock may be stale, not
-    // just the roster error — otherwise the next regen/reconcile is silently blocked.
-    const home = await fleetHome('version: 2\ngeneration: 1\n');
-    const throwingRelease =
-      () => async (): Promise<() => Promise<void>> => async (): Promise<void> => {
-        throw new Error('simulated lock unlink fault');
-      };
-    await expect(
-      executeFleetRegen(
-        {
-          runner: recordingRunner([]),
-          mosaicHome: home,
-          acquireReconcileLock: throwingRelease,
-          acquireRosterMutationLock: throwingRelease,
-        },
-        { write: true },
-      ),
-    ).rejects.toThrow(/stale|inspect|lock/i);
-    // Nothing written on the fail-closed path.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-  });
-
-  it('propagates a roster-mutation-lock release failure instead of silently keeping a stale lock', async (): Promise<void> => {
-    // Finding L: the real `acquirePrivateRosterMutationLock` release must SURFACE an
-    // unlink failure, not swallow it. If it swallowed (like the CRUD-internal
-    // acquireMutationLock does), a stale roster.yaml.mutation.lock left after a
-    // successful regen would block later regen/agent CRUD while the command reported
-    // success — and the finding-J stale-lock warning would never fire for this lock.
-    const home = await fleetHome();
-    const release = await acquirePrivateRosterMutationLock(home)();
-    // Simulate the lock vanishing (or being unremovable) before release runs: the
-    // underlying unlink then faults. A swallowing release would resolve and hide it.
-    await rm(join(home, 'fleet', 'roster.yaml.mutation.lock'));
-    await expect(release()).rejects.toThrow();
-  });
-
-  it('preserves a complete rebuild result and flags lock-cleanup when release faults', async (): Promise<void> => {
-    // A lock-release fault after a successful write must NOT discard the fact that
-    // projections are now live — the operator needs to know the write happened and
-    // that the shared lock may be stale, not just a bare "regen failed".
-    const home = await fleetHome();
-    const result = await executeFleetRegen(
-      {
-        runner: recordingRunner([]),
-        mosaicHome: home,
-        acquireReconcileLock:
-          () => async (): Promise<() => Promise<void>> => async (): Promise<void> => {
-            throw new Error('simulated lock unlink fault');
-          },
-      },
-      { write: true },
-    );
-
-    expect(result.written).toBe(2);
-    expect(result.incomplete).toBeUndefined();
-    expect(result.cleanup).toMatchObject({
-      code: 'lock-cleanup-failed',
-      action: 'inspect-lock-before-retry',
-    });
-    // Projections are genuinely on disk despite the release fault.
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(true);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder1.env.generated'))).toBe(true);
-
-    const report = formatFleetRegenReport(result).join('\n');
-    expect(report).toMatch(/lock/i);
-    expect(report).toMatch(/stale|inspect|clear/i);
-  });
-
-  it('preserves a partial rebuild AND flags lock-cleanup when both apply and release fault', async (): Promise<void> => {
-    // Worst case: a mid-loop apply fault leaves a partial rebuild, then the release
-    // also faults. Both recovery states must survive so the operator sees exactly
-    // which projections are live and that the lock may be stale.
-    const home = await fleetHome();
-    const realApply = applyPreparedGeneratedAgentEnvironmentProjection;
-    const result = await executeFleetRegen(
-      {
-        runner: recordingRunner([]),
-        mosaicHome: home,
-        applyProjection: async (prepared): Promise<string> => {
-          if (prepared.generatedPath.endsWith('coder1.env.generated')) {
-            throw new Error('simulated ENOSPC on coder1');
-          }
-          return realApply(prepared);
-        },
-        acquireReconcileLock:
-          () => async (): Promise<() => Promise<void>> => async (): Promise<void> => {
-            throw new Error('simulated lock unlink fault');
-          },
-      },
-      { write: true },
-    );
-
-    expect(result.written).toBe(1);
-    expect(result.incomplete).toMatchObject({
-      code: 'projection-apply-failed',
-      failedAgent: 'coder1',
-      writtenAgents: ['coder0'],
-    });
-    expect(result.cleanup).toMatchObject({ code: 'lock-cleanup-failed' });
-
-    const report = formatFleetRegenReport(result).join('\n');
-    expect(report).toMatch(/incomplete/i);
-    expect(report).toMatch(/lock/i);
-  });
-
-  it('fails closed without deleting a REPLACEMENT roster-mutation lock it no longer owns', async (): Promise<void> => {
-    // Finding M1 (replacement-lock race): after this invocation created its lock, the
-    // lock is cleared and re-created by ANOTHER writer (new inode + foreign token)
-    // BEFORE release runs. The release must PROVE ownership (device/inode + token) and
-    // refuse to unlink the stranger's live lock — otherwise it deletes it, a third
-    // writer enters concurrently, and mutual exclusion over the projections is broken.
-    // This pins the REACHABLE window (replaced-before-release); the residual sub-window
-    // between the final check and the path `unlink` is unreachable within the `wx`
-    // writer protocol and matches the merged reconcile lock — see the acquirer doc.
-    const home = await fleetHome();
-    const lockPath = join(home, 'fleet', 'roster.yaml.mutation.lock');
-    const release = await acquirePrivateRosterMutationLock(home)();
-    // A different writer replaces the lock: same path, NEW inode, foreign content.
-    await rm(lockPath);
-    await writeFile(lockPath, 'a-different-writer\n', { mode: 0o600 });
-    const replacement = await stat(lockPath);
-    // Release must reject (it no longer owns this file) AND the diagnosis must name
-    // the MUTATION lock specifically — a fault on this shared helper must not be
-    // mislabeled as the reconcile lock (that would defeat the M3 accurate-diagnosis
-    // goal, since regen serializes on both) ...
-    await expect(release()).rejects.toThrow(/roster\.yaml\.mutation\.lock/);
-    // ... and MUST NOT have unlinked the stranger's live lock.
-    expect(await exists(lockPath)).toBe(true);
-    expect((await stat(lockPath)).ino).toBe(replacement.ino);
-  });
-
-  it('does not strand the lock file when initialization fails after creating it', async (): Promise<void> => {
-    // Codex r4: if writeFile/stat/close/ownership-check throws AFTER the `wx` create
-    // succeeds, the just-created lock must NOT be left behind — a stranded lock would
-    // permanently block future regen AND agent CRUD (both contend on this path). The
-    // cleanup is dev/ino-guarded (never deletes a replacement) and best-effort (never
-    // masks the initialization error).
-    const home = await fleetHome();
-    const lockPath = join(home, 'fleet', 'roster.yaml.mutation.lock');
-    // Inject an opener that performs the REAL `wx` create (so the lock file really
-    // lands on disk) but whose handle faults on the token write — a post-create
-    // initialization failure.
-    const faultingOpen = (async (
-      path: Parameters<typeof open>[0],
-      flags: Parameters<typeof open>[1],
-      mode: Parameters<typeof open>[2],
-    ) => {
-      const handle = await open(path, flags, mode);
-      return new Proxy(handle, {
-        get(target, prop, receiver): unknown {
-          if (prop === 'writeFile') {
-            return async (): Promise<never> => {
-              throw new Error('simulated ENOSPC on token write');
-            };
-          }
-          const value = Reflect.get(target, prop, receiver);
-          return typeof value === 'function' ? value.bind(target) : value;
-        },
-      });
-    }) as typeof open;
-
-    await expect(acquirePrivateRosterMutationLock(home, faultingOpen)()).rejects.toThrow(
-      /mutation\.lock/,
-    );
-    // The lock we created must have been cleaned up — not stranded on disk.
-    expect(await exists(lockPath)).toBe(false);
-  });
-
-  it('does not strand the lock file when the post-create stat itself fails', async (): Promise<void> => {
-    // Codex r5: the narrower sub-path where `handle.stat()` ITSELF rejects right after
-    // the `wx` create succeeds (transient EIO/EBADF). device/inode identity is then
-    // unavailable, so the init-failure cleanup cannot prove ownership by dev/ino — yet
-    // the lock must STILL not be stranded, because a stranded lock permanently blocks
-    // future regen AND agent CRUD. The token we persisted before the failure uniquely
-    // identifies OUR lock, so cleanup falls back to matching it.
-    const home = await fleetHome();
-    const lockPath = join(home, 'fleet', 'roster.yaml.mutation.lock');
-    // Real `wx` create (lock really lands on disk); the token write SUCCEEDS so our
-    // random token is persisted, then `stat()` faults — a post-create init failure.
-    const faultingStatOpen = (async (
-      path: Parameters<typeof open>[0],
-      flags: Parameters<typeof open>[1],
-      mode: Parameters<typeof open>[2],
-    ) => {
-      const handle = await open(path, flags, mode);
-      return new Proxy(handle, {
-        get(target, prop, receiver): unknown {
-          if (prop === 'stat') {
-            return async (): Promise<never> => {
-              throw new Error('simulated EIO on post-create stat');
-            };
-          }
-          const value = Reflect.get(target, prop, receiver);
-          return typeof value === 'function' ? value.bind(target) : value;
-        },
-      });
-    }) as typeof open;
-
-    await expect(acquirePrivateRosterMutationLock(home, faultingStatOpen)()).rejects.toThrow(
-      /mutation\.lock/,
-    );
-    // Even without dev/ino, the token-based fallback must have removed our lock.
-    expect(await exists(lockPath)).toBe(false);
-  });
-
-  it('surfaces a lock-cleanup fault when unwinding after a later lock acquire fails', async (): Promise<void> => {
-    // Finding M2: the FIRST lock is taken, the SECOND lock's acquire throws, and
-    // unwinding the first lock's release ALSO faults. The acquire-unwind path must
-    // surface both — the already-taken lock may now be stale and silently block the
-    // next regen/reconcile — not just re-throw the acquire error and drop the fault.
-    const home = await fleetHome();
-    await expect(
-      executeFleetRegen(
-        {
-          runner: recordingRunner([]),
-          mosaicHome: home,
-          // Mutation lock (acquired first) succeeds, but its RELEASE faults on unwind.
-          acquireRosterMutationLock:
-            () => async (): Promise<() => Promise<void>> => async (): Promise<void> => {
-              throw new Error('simulated mutation-lock unlink fault');
-            },
-          // Reconcile lock (acquired second) ACQUIRE fails, triggering the unwind.
-          acquireReconcileLock: () => async (): Promise<() => Promise<void>> => {
-            throw new Error('simulated reconcile acquire failure');
-          },
-        },
-        { write: true },
-      ),
-    ).rejects.toThrow(/stale|inspect|lock/i);
-    expect(await exists(join(home, 'fleet', 'agents', 'coder0.env.generated'))).toBe(false);
-  });
-
-  it('names BOTH fleet locks in the stale-lock warning (cleanup can come from either)', async (): Promise<void> => {
-    // Finding M3: finding L made the roster MUTATION lock's release fault reachable, so
-    // the cleanup marker can now originate from either lock. The human report must not
-    // claim only the reconcile lock is stale — it must name both candidate lock files
-    // so the operator inspects the right one.
-    const home = await fleetHome();
-    const result = await executeFleetRegen(
-      {
-        runner: recordingRunner([]),
-        mosaicHome: home,
-        // Fault the MUTATION lock's release specifically (reconcile lock is real).
-        acquireRosterMutationLock:
-          () => async (): Promise<() => Promise<void>> => async (): Promise<void> => {
-            throw new Error('simulated mutation-lock unlink fault');
-          },
-      },
-      { write: true },
-    );
-
-    expect(result.written).toBe(2);
-    expect(result.cleanup).toMatchObject({ code: 'lock-cleanup-failed' });
-    const report = formatFleetRegenReport(result).join('\n');
-    expect(report).toContain('roster.yaml.mutation.lock');
-    expect(report).toContain('roster.yaml.reconcile.lock');
-  });
-});
--- a/packages/mosaic/src/commands/fleet-regen-command.ts
+++ b/packages/mosaic/src/commands/fleet-regen-command.ts
@@ -1,446 +0,0 @@
-import { stat } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { join, relative, resolve } from 'node:path';
-import type { Command } from 'commander';
-import type { CommandRunner } from './fleet.js';
-import {
-  applyPreparedGeneratedAgentEnvironmentProjection,
-  prepareGeneratedAgentEnvironmentProjection,
-  type PreparedGeneratedAgentEnvironmentProjection,
-} from '../fleet/generated-env-boundary.js';
-import {
-  acquirePrivateReconcileLock,
-  acquirePrivateRosterMutationLock,
-  projectRosterV2AgentGeneratedEnv,
-} from '../fleet/fleet-reconciler.js';
-import {
-  parseRosterV2,
-  validateRosterV2Semantics,
-  type FleetRosterV2,
-} from '../fleet/roster-v2.js';
-import { FleetRosterConfigurationError, readFleetRosterText } from '../fleet/fleet-roster-v1.js';
-
-/**
- * `mosaic fleet regen` — recovery-framed regeneration of the roster-derived
- * agent env projections (`fleet/agents/<name>.env.generated`) from the roster
- * SSOT. It is the recovery layer of #791: when a wiped/diverged operator surface
- * has cost an agent its generated projection, regen rebuilds it deterministically
- * from `roster.yaml` so the launcher can source the intended identity again.
- *
- * It is intentionally a THIN projection-only wrapper over the same mapping the
- * reconciler apply path uses ({@link projectRosterV2AgentGeneratedEnv}), and it
- * has NO code path to systemd lifecycle: regen never starts, stops, or restarts
- * an agent. Recovery order forbids restart-before-verify, so the operator must
- * verify each rebuilt projection resolves before restarting anything.
- */
-export interface FleetRegenAgentPlan {
-  readonly name: string;
-  /** Generated-projection path, relative to the Mosaic home (never absolute in output). */
-  readonly path: string;
-  /** `create` when the projection is currently absent, `rebuild` when it already exists. */
-  readonly disposition: 'create' | 'rebuild';
-}
-
-/**
- * Present ONLY when a `--write` projection apply failed partway through the
- * fleet. Every prior agent was already validated and prepared, so `writtenAgents`
- * are byte-complete on disk; `failedAgent` is where the write faulted. The
- * command surfaces this instead of a bare throw so the operator can finish the
- * rebuild and verify every projection before restarting any unit.
- */
-export interface FleetRegenIncomplete {
-  readonly code: 'projection-apply-failed';
-  /** The agent whose generated-projection write faulted. */
-  readonly failedAgent: string;
-  /** Agents whose projections were fully written before the fault (in apply order). */
-  readonly writtenAgents: readonly string[];
-}
-
-export interface FleetRegenResult {
-  readonly mode: 'dry-run' | 'write';
-  /** Roster path, relative to the Mosaic home. */
-  readonly rosterPath: string;
-  readonly generation: number;
-  readonly agentCount: number;
-  /** Count of projections written to disk (always 0 in dry-run). */
-  readonly written: number;
-  readonly agents: readonly FleetRegenAgentPlan[];
-  /** Set ONLY when a `--write` apply faulted mid-fleet — a partial rebuild. */
-  readonly incomplete?: FleetRegenIncomplete;
-  /**
-   * Set ONLY when a shared fleet lock could not be released after a write completed
-   * (or partially completed) — EITHER `roster.yaml.mutation.lock` or
-   * `roster.yaml.reconcile.lock`, since regen holds both. The projections in this
-   * result are real; the lock file may be stale and must be inspected before the
-   * next mutation. Independent of {@link incomplete} — both can be present at once.
-   */
-  readonly cleanup?: {
-    readonly code: 'lock-cleanup-failed';
-    readonly action: 'inspect-lock-before-retry';
-  };
-}
-
-export interface FleetRegenDeps {
-  /**
-   * Present ONLY so an accidental future lifecycle wiring is caught by the
-   * "never restarts" test — regen is contractually forbidden to invoke it.
-   */
-  readonly runner: CommandRunner;
-  readonly mosaicHome?: string;
-  /** Persona roots for semantic roster validation (defaults mirror the reconciler). */
-  readonly rolesDir?: string;
-  readonly overrideDir?: string;
-  /** Test seam: canonical roster reader. Defaults to parse + semantic validation. */
-  readonly readRoster?: (rosterPath: string) => Promise<FleetRosterV2>;
-  /**
-   * Test seam: generated-only projection validator. Defaults to the audited
-   * boundary helper that validates ONLY `<name>.env.generated`.
-   */
-  readonly prepareProjection?: typeof prepareGeneratedAgentEnvironmentProjection;
-  /** Test seam: generated-only projection writer. Defaults to the audited boundary helper. */
-  readonly applyProjection?: typeof applyPreparedGeneratedAgentEnvironmentProjection;
-  /**
-   * Test seam: acquire the shared reconcile lock before a `--write`. Defaults to
-   * the reconciler's private lock so regen and reconcile are mutually exclusive
-   * and a concurrent reconcile cannot race a stale projection write.
-   */
-  readonly acquireReconcileLock?: (mosaicHome: string) => () => Promise<() => Promise<void>>;
-  /**
-   * Test seam: acquire the shared roster mutation lock before a `--write`.
-   * Defaults to the reconciler's hardened, ownership-proving acquirer for the
-   * same `fleet/roster.yaml.mutation.lock` path that CRUD contends on, so regen
-   * serializes against agent create/update/delete — both rewrite the same
-   * generated projections, so without this a concurrent CRUD could race a stale
-   * projection write.
-   */
-  readonly acquireRosterMutationLock?: (mosaicHome: string) => () => Promise<() => Promise<void>>;
-  /** Test seam: existence probe for create/rebuild disposition. */
-  readonly fileExists?: (path: string) => Promise<boolean>;
-}
-
-interface FleetRegenOptions {
-  readonly write?: boolean;
-}
-
-function defaultMosaicHome(deps: FleetRegenDeps): string {
-  return deps.mosaicHome ?? process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
-}
-
-async function defaultFileExists(path: string): Promise<boolean> {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Projection-only regeneration core. Deterministic and side-effect-free in
- * dry-run; in `--write` it rebuilds each generated projection through the
- * audited generated-only boundary writer and NOTHING else — it never writes
- * `.env.local`/`.env.quarantine`, never unlinks the legacy `.env`, and never
- * touches `deps.runner`.
- *
- * Fail-closed by construction: the roster is validated (structural + semantic)
- * and EVERY agent's projection is prepared before ANY is written, so a single
- * invalid agent (or a semantically rejected roster) leaves the whole surface
- * untouched. In `--write` mode the read-prepare-apply sequence runs under the
- * shared reconcile lock so a concurrent reconcile cannot race a stale write.
- */
-export async function executeFleetRegen(
-  deps: FleetRegenDeps,
-  options: FleetRegenOptions,
-): Promise<FleetRegenResult> {
-  const mosaicHome = defaultMosaicHome(deps);
-  const agentEnvDir = join(mosaicHome, 'fleet', 'agents');
-  const rosterPath = join(mosaicHome, 'fleet', 'roster.yaml');
-  const readRoster = deps.readRoster ?? defaultReadRoster(deps, mosaicHome);
-  const prepare = deps.prepareProjection ?? prepareGeneratedAgentEnvironmentProjection;
-  const apply = deps.applyProjection ?? applyPreparedGeneratedAgentEnvironmentProjection;
-  const fileExists = deps.fileExists ?? defaultFileExists;
-  const acquireReconcileLock = deps.acquireReconcileLock ?? acquirePrivateReconcileLock;
-  const acquireRosterMutationLock =
-    deps.acquireRosterMutationLock ?? acquirePrivateRosterMutationLock;
-  const write = options.write === true;
-
-  const run = async (): Promise<FleetRegenResult> => {
-    const roster = await readRoster(rosterPath);
-
-    // Prepare (validate) every agent BEFORE any write, so a later failure never
-    // leaves an earlier projection partially rebuilt.
-    const prepared: (PreparedGeneratedAgentEnvironmentProjection & {
-      readonly name: string;
-      readonly disposition: 'create' | 'rebuild';
-    })[] = [];
-    for (const agent of roster.agents) {
-      const projection = await prepare({
-        mosaicHome,
-        agentEnvDir,
-        agentName: agent.name,
-        generated: projectRosterV2AgentGeneratedEnv(roster, agent),
-      });
-      const disposition = (await fileExists(projection.generatedPath)) ? 'rebuild' : 'create';
-      prepared.push({ ...projection, name: agent.name, disposition });
-    }
-
-    // Every projection is already validated (prepared); an apply here can only
-    // fault on the underlying I/O (ENOSPC, EIO, a race outside the lock). If a
-    // later write faults, earlier agents are already replaced on disk, so we
-    // stop and report the partial state rather than throwing a bare error that
-    // hides which projections are now live.
-    let written = 0;
-    let incomplete: FleetRegenIncomplete | undefined;
-    if (write) {
-      for (const projection of prepared) {
-        try {
-          await apply(projection);
-        } catch {
-          incomplete = {
-            code: 'projection-apply-failed',
-            failedAgent: projection.name,
-            writtenAgents: prepared.slice(0, written).map((entry) => entry.name),
-          };
-          break;
-        }
-        written += 1;
-      }
-    }
-
-    return {
-      mode: write ? 'write' : 'dry-run',
-      rosterPath: relative(mosaicHome, rosterPath),
-      generation: roster.generation,
-      agentCount: roster.agents.length,
-      written,
-      agents: prepared.map((projection) => ({
-        name: projection.name,
-        path: relative(mosaicHome, projection.generatedPath),
-        disposition: projection.disposition,
-      })),
-      ...(incomplete ? { incomplete } : {}),
-    };
-  };
-
-  // Dry-run is preview-only and never mutates, so it stays lock-free (usable even
-  // while a reconcile or CRUD holds a lock). A `--write` must serialize against
-  // BOTH roster writers of the same generated projections: agent CRUD (roster
-  // mutation lock) and reconcile (reconcile lock). Acquire in a fixed order — the
-  // locks are non-blocking (they throw on contention rather than wait), so no
-  // deadlock is possible — and fail closed if either is already held.
-  if (!write) return run();
-
-  const releases: (() => Promise<void>)[] = [];
-  try {
-    releases.push(await acquireRosterMutationLock(mosaicHome)());
-    releases.push(await acquireReconcileLock(mosaicHome)());
-  } catch (error: unknown) {
-    // A later acquire failed; unwind any lock already taken (reverse order). If
-    // that unwind ALSO faults, surface both — the already-taken lock may now be
-    // stale and silently block the next regen/reconcile — rather than dropping it.
-    const releaseFault = await releaseFleetLocks(releases);
-    throw augmentWithLockCleanupFault(error, releaseFault);
-  }
-
-  let result: FleetRegenResult | undefined;
-  let primaryError: unknown;
-  try {
-    result = await run();
-  } catch (error: unknown) {
-    primaryError = error;
-  }
-
-  // Release both locks (reverse acquire order), continuing past a fault so neither
-  // leaks. A release fault must never discard a completed (or partial) rebuild —
-  // the projections are already on disk — and must not be silently hidden even
-  // when the run itself failed with nothing written.
-  const releaseFault = await releaseFleetLocks(releases);
-  if (result) {
-    return releaseFault === undefined
-      ? result
-      : {
-          ...result,
-          cleanup: { code: 'lock-cleanup-failed', action: 'inspect-lock-before-retry' },
-        };
-  }
-  // result is undefined ⇒ run() threw ⇒ primaryError is set.
-  throw augmentWithLockCleanupFault(primaryError, releaseFault);
-}
-
-/**
- * Releases held locks in reverse acquire order, continuing past a fault so a
- * single failed release never leaks the others. Returns the first fault seen (or
- * undefined when every release succeeded).
- */
-async function releaseFleetLocks(releases: readonly (() => Promise<void>)[]): Promise<unknown> {
-  let firstFault: unknown;
-  for (const release of [...releases].reverse()) {
-    try {
-      await release();
-    } catch (error: unknown) {
-      if (firstFault === undefined) firstFault = error;
-    }
-  }
-  return firstFault;
-}
-
-/**
- * When a run failed with nothing written AND lock cleanup also faulted, surface
- * both: the operator needs to know the lock may be stale (else the next
- * regen/reconcile is silently blocked), not just the original run error.
- */
-function augmentWithLockCleanupFault(primaryError: unknown, releaseFault: unknown): unknown {
-  if (releaseFault === undefined) return primaryError;
-  const base = primaryError instanceof Error ? primaryError.message : String(primaryError);
-  return new Error(
-    `${base} (additionally, a fleet lock could not be released — ` +
-      'fleet/roster.yaml.mutation.lock or roster.yaml.reconcile.lock may be stale; ' +
-      'inspect and clear it before retry)',
-  );
-}
-
-function defaultReadRoster(
-  deps: FleetRegenDeps,
-  mosaicHome: string,
-): (rosterPath: string) => Promise<FleetRosterV2> {
-  return async (rosterPath: string): Promise<FleetRosterV2> => {
-    const roster = parseRosterV2(await readFleetRosterText(rosterPath), 'yaml');
-    // Enforce the SAME semantic gate as reconcile/plan/verify (persona resolution
-    // + protected-class tool-policy match) so regen cannot project a roster the
-    // rest of the fleet surface would reject.
-    await validateRosterV2Semantics(roster, {
-      rolesDir: deps.rolesDir ?? join(mosaicHome, 'fleet', 'roles'),
-      overrideDir: deps.overrideDir ?? join(mosaicHome, 'fleet', 'roles.local'),
-    });
-    return roster;
-  };
-}
-
-/**
- * Human-readable report — paths and counts ONLY. The rendered projection body
- * (KEY=value lines) is never echoed (secrev). In `--write` mode it prints the
- * recovery runbook: verify each projection resolves BEFORE any restart.
- */
-export function formatFleetRegenReport(result: FleetRegenResult): string[] {
-  const lines: string[] = [];
-  const header =
-    result.mode === 'dry-run'
-      ? 'mosaic fleet regen — dry run (no changes written)'
-      : 'mosaic fleet regen — wrote roster-derived projections';
-  lines.push(header);
-  lines.push(
-    `roster: ${result.rosterPath} (generation ${result.generation}, ${result.agentCount} agent(s))`,
-  );
-  for (const agent of result.agents) {
-    lines.push(`  ${agent.name}  ${agent.path}  [${agent.disposition}]`);
-  }
-
-  if (result.mode === 'dry-run') {
-    lines.push(
-      `Plan: would write ${result.agentCount} generated projection(s). ` +
-        `Re-run with --write to apply. regen never restarts agents.`,
-    );
-    return lines;
-  }
-
-  if (result.incomplete) {
-    const { failedAgent, writtenAgents } = result.incomplete;
-    lines.push(
-      `INCOMPLETE: rebuild stopped at agent ${failedAgent} — its projection write faulted.`,
-    );
-    lines.push(
-      `Rebuilt before the fault: ${writtenAgents.length} projection(s)` +
-        (writtenAgents.length > 0 ? ` (${writtenAgents.join(', ')})` : '') +
-        `; ${result.agentCount - writtenAgents.length} not written.`,
-    );
-    lines.push(
-      'Recover: re-run `mosaic fleet regen --write` to finish, then VERIFY every ' +
-        "agent's fleet/agents/<name>.env.generated resolves BEFORE restarting any " +
-        'unit. regen never restarts agents.',
-    );
-  } else {
-    lines.push(`Wrote ${result.written} generated projection(s).`);
-    lines.push('Next steps — DO NOT restart agents before verifying:');
-    lines.push(
-      "  1. Confirm each agent's fleet/agents/<name>.env.generated exists and carries " +
-        'the intended MOSAIC_AGENT_* values.',
-    );
-    // The unit sets NO EnvironmentFile= — it launches from a minimal env and the
-    // launcher (start-agent-session.sh) sources .env.generated itself. Verify the
-    // launcher path, not a nonexistent EnvironmentFile property.
-    lines.push(
-      '  2. Confirm the unit launches from it: `systemctl --user cat mosaic-agent@<name>` ' +
-        'shows ExecStart running start-agent-session.sh, which reads .env.generated.',
-    );
-    lines.push(
-      '  3. Only then restart one unit at a time: systemctl --user restart mosaic-agent@<name>.',
-    );
-  }
-
-  if (result.cleanup) {
-    lines.push(
-      'WARNING: a fleet lock could not be released — ' +
-        'fleet/roster.yaml.mutation.lock or fleet/roster.yaml.reconcile.lock may be ' +
-        'stale; inspect and clear it before the next reconcile or regen.',
-    );
-  }
-  return lines;
-}
-
-function resolveRegenMosaicHome(fleetCommand: Command, deps: FleetRegenDeps): string {
-  const options = fleetCommand.optsWithGlobals<{ mosaicHome?: string }>();
-  return options.mosaicHome ?? defaultMosaicHome(deps);
-}
-
-/**
- * regen reads the roster SSOT at `<mosaicHome>/fleet/roster.yaml` and ignores the
- * `fleet --roster <path>` global. If an operator passes a non-canonical `--roster`
- * they must NOT be silently served the canonical file — mirror reconcile's guard
- * and reject, so `mosaic fleet --roster /elsewhere regen --write` fails closed.
- */
-function assertRegenCanonicalRoster(fleetCommand: Command, mosaicHome: string): void {
-  const options = fleetCommand.optsWithGlobals<{ roster?: string }>();
-  const canonical = join(mosaicHome, 'fleet', 'roster.yaml');
-  if (options.roster !== undefined && resolve(options.roster) !== resolve(canonical)) {
-    throw new Error(
-      'Roster-v2 regeneration requires the canonical roster path (fleet/roster.yaml).',
-    );
-  }
-}
-
-/** Registers the recovery-framed `mosaic fleet regen` command. */
-export function registerFleetRegenCommand(fleetCommand: Command, deps: FleetRegenDeps): void {
-  fleetCommand
-    .command('regen')
-    .description(
-      'Regenerate roster-derived agent env projections (dry-run default, --write to apply; never restarts)',
-    )
-    .option('--write', 'Write the regenerated projections to disk (default: dry-run)')
-    .option('--json', 'Emit the plan/result as JSON')
-    .action(async (opts: { write?: boolean; json?: boolean }): Promise<void> => {
-      const mosaicHome = resolveRegenMosaicHome(fleetCommand, deps);
-      try {
-        assertRegenCanonicalRoster(fleetCommand, mosaicHome);
-        const result = await executeFleetRegen(
-          { ...deps, mosaicHome },
-          { write: opts.write === true },
-        );
-        if (opts.json === true) {
-          console.log(JSON.stringify(result));
-        } else {
-          for (const line of formatFleetRegenReport(result)) console.log(line);
-        }
-        // A partial rebuild or a stale-lock cleanup state is a non-zero outcome:
-        // the operator must finish/verify (and clear the lock) before restarting.
-        if (result.incomplete || result.cleanup) process.exitCode = 1;
-      } catch (error: unknown) {
-        if (error instanceof FleetRosterConfigurationError) {
-          fleetCommand.error(error.message, { code: 'fleet.roster', exitCode: 1 });
-          return;
-        }
-        process.exitCode = 1;
-        const message = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`mosaic fleet regen failed: ${message}\n`);
-      }
-    });
-}
--- a/packages/mosaic/src/commands/fleet.spec.ts
+++ b/packages/mosaic/src/commands/fleet.spec.ts
@@ -60,7 +60,6 @@ import {
  type SleepFn,
 } from './fleet.js';
 import { registerAgentCommand } from './agent.js';
-import { parseFleetRosterDocument, readFleetRosterText } from '../fleet/fleet-roster-v1.js';

 function buildProgram(): Command {
  const program = new Command();
@@ -98,7 +97,6 @@ describe('registerFleetCommand', () => {
      'provision',
      'ps',
      'reconcile',
-      'regen',
      'remove',
      'restart',
      'start',
@@ -167,91 +165,6 @@ describe('registerFleetCommand', () => {
  });
 });

-describe('fleet roster configuration failures', () => {
-  it('reports a missing roster with an actionable initialization hint', async () => {
-    const home = await tempDir();
-    try {
-      const program = buildProgram();
-
-      await expect(
-        program.parseAsync(['node', 'mosaic', 'fleet', '--mosaic-home', home, 'ps']),
-      ).rejects.toThrow(
-        `No fleet roster found at ${join(home, 'fleet', 'roster.json')}. Run \`mosaic fleet init\``,
-      );
-    } finally {
-      await rm(home, { recursive: true, force: true });
-    }
-  });
-
-  it('reports a malformed roster with the path and repair hint', async () => {
-    const home = await tempDir();
-    const rosterPath = join(home, 'fleet', 'roster.json');
-    try {
-      await mkdir(dirname(rosterPath), { recursive: true });
-      await writeFile(rosterPath, '{not valid json');
-
-      await expect(loadFleetRoster(rosterPath)).rejects.toThrow(
-        `Fleet roster at ${rosterPath} is invalid. Fix the file or run \`mosaic fleet init --force\``,
-      );
-    } finally {
-      await rm(home, { recursive: true, force: true });
-    }
-  });
-
-  it('reports an unreadable roster without exposing the filesystem error', async () => {
-    const home = await tempDir();
-    try {
-      await expect(readFleetRosterText(home)).rejects.toThrow(
-        `Could not read fleet roster at ${home}. Check the file exists and is readable.`,
-      );
-    } finally {
-      await rm(home, { recursive: true, force: true });
-    }
-  });
-
-  it('reports a malformed roster while selecting the v1/v2 command path', () => {
-    expect(() => parseFleetRosterDocument('version: [', '/srv/mosaic/fleet/roster.yaml')).toThrow(
-      'Fleet roster at /srv/mosaic/fleet/roster.yaml is invalid. Fix the file or run `mosaic fleet init --force`.',
-    );
-  });
-
-  it('reports a semantically invalid v1 roster as an actionable nonzero command error', async () => {
-    const home = await tempDir();
-    const rosterPath = join(home, 'fleet', 'roster.yaml');
-    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-    try {
-      await mkdir(dirname(rosterPath), { recursive: true });
-      await writeFile(
-        rosterPath,
-        [
-          'version: 1',
-          'transport: tmux',
-          'agents:',
-          '  - name: canary-pi',
-          '    runtime: pi',
-          '  - name: canary-pi',
-          '    runtime: codex',
-        ].join('\n'),
-      );
-
-      await expect(
-        buildProgram().parseAsync(['node', 'mosaic', 'fleet', '--mosaic-home', home, 'ps']),
-      ).rejects.toMatchObject({
-        code: 'fleet.roster',
-        exitCode: 1,
-        message: 'Fleet roster has duplicate agent name: canary-pi.',
-      });
-      expect(stderrSpy.mock.calls.flat().join('')).toContain(
-        'Fleet roster has duplicate agent name: canary-pi.',
-      );
-      expect(stderrSpy.mock.calls.flat().join('')).not.toMatch(/\n\s+at\s/);
-    } finally {
-      stderrSpy.mockRestore();
-      await rm(home, { recursive: true, force: true });
-    }
-  });
-});
-
 describe('fleet roster parsing', () => {
  let cleanup: string | undefined;

--- a/packages/mosaic/src/commands/fleet.ts
+++ b/packages/mosaic/src/commands/fleet.ts
@@ -19,11 +19,8 @@ import * as readline from 'node:readline';
 import type { Command } from 'commander';
 import YAML from 'yaml';
 import {
-  FleetRosterConfigurationError,
  getRosterAgent,
  loadFleetRoster,
-  parseFleetRosterDocument,
-  readFleetRosterText,
  resolveInstalledFleetRosterPath,
  type FleetAgent,
  type FleetRoster,
@@ -47,7 +44,6 @@ import {
  registerFleetReconcilerCommands,
  type FleetReconcilerCommandDeps,
 } from './fleet-reconciler-command.js';
-import { registerFleetRegenCommand } from './fleet-regen-command.js';
 import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
 import {
  applyPreparedAgentEnvironmentProjection,
@@ -1916,7 +1912,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
        const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
        const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
        const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
-        const roster = await loadRosterAtPath(cmd, rosterPath);
+        const roster = await loadFleetRoster(rosterPath);

        const newAgent: FleetAgent = {
          name,
@@ -1976,7 +1972,7 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
      const commandOpts = cmd.opts<{ mosaicHome: string; roster?: string }>();
      const activePaths = resolveFleetPaths(commandOpts.mosaicHome);
      const rosterPath = await resolveRosterPath(commandOpts.mosaicHome, commandOpts.roster);
-      const roster = await loadRosterAtPath(cmd, rosterPath);
+      const roster = await loadFleetRoster(rosterPath);

      // Guard: throws if removing leaves 0 orchestrators or agent not in roster
      const updatedRoster = removeAgentFromRoster(roster, name);
@@ -2067,18 +2063,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
    reconcileDeps: deps.reconcileDeps,
  });

-  // Recovery (#791 PR3): rebuild roster-derived env projections from the roster
-  // SSOT. Projection-only and preview-first — never issues a lifecycle restart.
-  registerFleetRegenCommand(cmd, {
-    runner,
-    mosaicHome: deps.mosaicHome,
-    // Resolve personas the SAME way reconcile does: forward any configured roots
-    // so a custom-persona-root deployment cannot have reconcile accept a roster
-    // that regen then rejects against the default `<mosaicHome>/fleet/roles`.
-    rolesDir: deps.reconcileDeps?.rolesDir,
-    overrideDir: deps.reconcileDeps?.overrideDir,
-  });
-
  return cmd;
 }

@@ -2405,19 +2389,14 @@ async function installFleet(cmd: Command, frameworkRoot: string): Promise<void>

 async function loadRosterForCommand(cmd: Command): Promise<FleetRoster> {
  const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
-  return loadRosterAtPath(cmd, await resolveRosterPath(opts.mosaicHome, opts.roster));
+  return loadFleetRoster(await resolveRosterPath(opts.mosaicHome, opts.roster));
 }

 /** Routes only a v2 roster to the M3 desired-state control plane; v1 aliases stay compatible. */
 async function usesRosterV2ControlPlane(cmd: Command): Promise<boolean> {
  const opts = cmd.opts<{ mosaicHome: string; roster?: string }>();
  const path = await resolveRosterPath(opts.mosaicHome, opts.roster);
-  let parsed: unknown;
-  try {
-    parsed = parseFleetRosterDocument(await readFleetRosterText(path), path);
-  } catch (error) {
-    reportFleetRosterConfigurationError(cmd, error);
-  }
+  const parsed: unknown = YAML.parse(await readFile(path, 'utf8'));
  return (
    typeof parsed === 'object' &&
    parsed !== null &&
@@ -2433,22 +2412,7 @@ async function loadRosterFromAgentCommand(
 ): Promise<FleetRoster> {
  const opts = command.optsWithGlobals<{ mosaicHome?: string; roster?: string }>();
  const mosaicHome = opts.mosaicHome ?? mosaicHomeOverride ?? defaultMosaicHome();
-  return loadRosterAtPath(command, await resolveRosterPath(mosaicHome, opts.roster));
-}
-
-async function loadRosterAtPath(command: Command, path: string): Promise<FleetRoster> {
-  try {
-    return await loadFleetRoster(path);
-  } catch (error) {
-    reportFleetRosterConfigurationError(command, error);
-  }
-}
-
-function reportFleetRosterConfigurationError(command: Command, error: unknown): never {
-  if (error instanceof FleetRosterConfigurationError) {
-    command.error(error.message, { code: 'fleet.roster', exitCode: 1 });
-  }
-  throw error;
+  return loadFleetRoster(await resolveRosterPath(mosaicHome, opts.roster));
 }

 function resolveMosaicHomeFromCommand(command: Command, override?: string): string {
--- a/packages/mosaic/src/commands/install-arguments.spec.ts
+++ b/packages/mosaic/src/commands/install-arguments.spec.ts
@@ -1,61 +0,0 @@
-import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
-
-const INSTALLER_PATH = fileURLToPath(new URL('../../../../tools/install.sh', import.meta.url));
-
-async function runInstaller(args: string[]): Promise<{
-  status: number | null;
-  stderr: string;
-  npmCalled: boolean;
-}> {
-  const home = await mkdtemp(join(tmpdir(), 'mosaic-installer-args-'));
-  const bin = join(home, 'bin');
-  const npmMarker = join(home, 'npm-called');
-
-  try {
-    await mkdir(bin);
-    const npmShim = join(bin, 'npm');
-    await writeFile(npmShim, `#!/bin/sh\n: > "${npmMarker}"\n`);
-    await chmod(npmShim, 0o755);
-
-    const result = spawnSync('bash', [INSTALLER_PATH, ...args], {
-      encoding: 'utf8',
-      env: {
-        ...process.env,
-        HOME: home,
-        MOSAIC_NO_COLOR: '1',
-        PATH: `${bin}:${process.env.PATH ?? ''}`,
-      },
-    });
-
-    return {
-      status: result.status,
-      stderr: result.stderr,
-      npmCalled: existsSync(npmMarker),
-    };
-  } finally {
-    await rm(home, { recursive: true, force: true });
-  }
-}
-
-function expectUnknownArgument(result: Awaited<ReturnType<typeof runInstaller>>): void {
-  expect(result.status).not.toBe(0);
-  expect(result.stderr).toContain('Unknown argument: --bogus');
-  expect(result.stderr).toMatch(/Usage: .*install\.sh/);
-  expect(result.npmCalled).toBe(false);
-}
-
-describe('installer arguments', () => {
-  it('rejects an unknown argument before installation starts', async () => {
-    expectUnknownArgument(await runInstaller(['--cli', '--bogus']));
-  });
-
-  it('does not let --ref consume an unknown option', async () => {
-    expectUnknownArgument(await runInstaller(['--cli', '--ref', '--bogus']));
-  });
-});
--- a/packages/mosaic/src/commands/install-heading.spec.ts
+++ b/packages/mosaic/src/commands/install-heading.spec.ts
@@ -1,17 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
-
-const INSTALLER_PATH = fileURLToPath(new URL('../../../../tools/install.sh', import.meta.url));
-
-describe('installer CLI package heading', () => {
-  it('renders the scoped package name intact', async () => {
-    const installer = await readFile(INSTALLER_PATH, 'utf8');
-    const step = installer.match(/^step\(\)\s*\{.*\}$/m)?.[0];
-
-    expect(step).toBeDefined();
-
-    expect(step).toContain('printf \'\\n%s%s%s\\n\' "$BOLD" "$*" "$RESET"');
-    expect(installer).toContain('step "@mosaicstack/mosaic (npm package)"');
-  });
-});
--- a/packages/mosaic/src/commands/skill.spec.ts
+++ b/packages/mosaic/src/commands/skill.spec.ts
@@ -1,421 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { Command } from 'commander';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import {
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  mkdtempSync,
-  readlinkSync,
-  rmSync,
-  symlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import {
-  listSkills,
-  registerSkill,
-  registerSkillCommand,
-  syncClaudeSkills,
-  unregisterSkill,
-  type SkillPaths,
-} from './skill.js';
-
-const LEGACY_SYNC_SCRIPT = fileURLToPath(
-  new URL('../../framework/tools/_scripts/mosaic-sync-skills', import.meta.url),
-);
-
-describe('Claude skill bridge', () => {
-  let root: string;
-  let paths: SkillPaths;
-
-  beforeEach(() => {
-    root = mkdtempSync(join(tmpdir(), 'mosaic-skill-cli-'));
-    paths = {
-      mosaicSkillsDir: join(root, '.config', 'mosaic', 'skills'),
-      claudeSkillsDir: join(root, '.claude', 'skills'),
-    };
-    mkdirSync(paths.mosaicSkillsDir, { recursive: true });
-  });
-
-  afterEach(() => {
-    rmSync(root, { recursive: true, force: true });
-  });
-
-  function createSkill(name: string): string {
-    const skillDir = join(paths.mosaicSkillsDir, name);
-    mkdirSync(skillDir, { recursive: true });
-    writeFileSync(join(skillDir, 'SKILL.md'), `# ${name}\n`);
-    return skillDir;
-  }
-
-  function expectCorrectLink(name: string): void {
-    const linkPath = join(paths.claudeSkillsDir, name);
-    expect(lstatSync(linkPath).isSymbolicLink()).toBe(true);
-    expect(readlinkSync(linkPath)).toBe(join(paths.mosaicSkillsDir, name));
-  }
-
-  describe('name validation', () => {
-    const invalidNames = [
-      '../../etc',
-      '/abs/path',
-      'a/b',
-      String.raw`a\b`,
-      '-rf',
-      '..',
-      'safe.',
-      'space name',
-      'line\nbreak',
-      'escape\u001B[31m',
-    ];
-
-    for (const name of invalidNames) {
-      it(`rejects ${JSON.stringify(name)} before register can escape its roots`, () => {
-        expect(() => registerSkill(name, paths)).toThrow(/invalid skill name/i);
-        expect(existsSync(paths.claudeSkillsDir)).toBe(false);
-      });
-
-      it(`rejects ${JSON.stringify(name)} before unregister can escape its roots`, () => {
-        expect(() => unregisterSkill(name, paths)).toThrow(/invalid skill name/i);
-        expect(existsSync(paths.claudeSkillsDir)).toBe(false);
-      });
-    }
-  });
-
-  describe('CLI validation errors', () => {
-    let previousExitCode: number | string | null | undefined;
-
-    beforeEach(() => {
-      previousExitCode = process.exitCode;
-      process.exitCode = undefined;
-    });
-
-    afterEach(() => {
-      process.exitCode = previousExitCode;
-    });
-
-    it.each(['register', 'unregister'])(
-      'reports invalid %s names on stderr and sets a nonzero exit status',
-      async (subcommand) => {
-        const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
-        const program = new Command().exitOverride();
-        registerSkillCommand(program, paths);
-
-        await program.parseAsync(['node', 'mosaic', 'skill', subcommand, '../../etc']);
-
-        expect(error).toHaveBeenCalledWith(expect.stringMatching(/invalid skill name/i));
-        expect(process.exitCode).toBe(1);
-        expect(existsSync(paths.claudeSkillsDir)).toBe(false);
-        error.mockRestore();
-      },
-    );
-  });
-
-  describe('CLI status output', () => {
-    let previousExitCode: number | string | null | undefined;
-
-    beforeEach(() => {
-      previousExitCode = process.exitCode;
-      process.exitCode = undefined;
-    });
-
-    afterEach(() => {
-      process.exitCode = previousExitCode;
-    });
-
-    async function run(...args: string[]): Promise<void> {
-      const program = new Command().exitOverride();
-      registerSkillCommand(program, paths);
-      await program.parseAsync(['node', 'mosaic', 'skill', ...args]);
-    }
-
-    it('reports register repair/idempotency and unregister idempotency statuses', async () => {
-      const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-      createSkill('status-skill');
-
-      await run('register', 'status-skill');
-      await run('register', 'status-skill');
-      rmSync(join(paths.claudeSkillsDir, 'status-skill'));
-      symlinkSync(
-        join(paths.mosaicSkillsDir, 'retired'),
-        join(paths.claudeSkillsDir, 'status-skill'),
-      );
-      await run('register', 'status-skill');
-      await run('unregister', 'status-skill');
-      await run('unregister', 'status-skill');
-
-      expect(log.mock.calls.flat()).toEqual([
-        'status-skill: registered',
-        'status-skill: already registered',
-        'status-skill: repaired dangling registration',
-        'status-skill: unregistered',
-        'status-skill: already unregistered',
-      ]);
-      log.mockRestore();
-    });
-
-    it('reports empty and populated skill lists', async () => {
-      const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-
-      await run('list');
-      createSkill('listed');
-      await run('list');
-
-      expect(log).toHaveBeenCalledWith('No Mosaic or Claude Code skills found.');
-      expect(log).toHaveBeenCalledWith(expect.stringMatching(/^unregistered\s+listed$/));
-      log.mockRestore();
-    });
-  });
-
-  describe('registerSkill', () => {
-    it('creates the exact canonical symlink and is idempotent', () => {
-      createSkill('new-skill');
-
-      expect(registerSkill('new-skill', paths).status).toBe('registered');
-      expectCorrectLink('new-skill');
-
-      expect(registerSkill('new-skill', paths).status).toBe('already-registered');
-      expectCorrectLink('new-skill');
-    });
-
-    it('repairs a dangling Mosaic-owned symlink', () => {
-      createSkill('new-skill');
-      mkdirSync(paths.claudeSkillsDir, { recursive: true });
-      symlinkSync(
-        join(paths.mosaicSkillsDir, 'retired-skill'),
-        join(paths.claudeSkillsDir, 'new-skill'),
-      );
-
-      expect(registerSkill('new-skill', paths).status).toBe('repaired');
-      expectCorrectLink('new-skill');
-    });
-
-    it.each(['file', 'directory', 'symlink'] as const)(
-      'refuses to clobber a foreign %s at the target',
-      (kind) => {
-        createSkill('protected');
-        mkdirSync(paths.claudeSkillsDir, { recursive: true });
-        const target = join(paths.claudeSkillsDir, 'protected');
-        const foreign = join(root, 'foreign');
-
-        if (kind === 'file') writeFileSync(target, 'keep me\n');
-        if (kind === 'directory') mkdirSync(target);
-        if (kind === 'symlink') {
-          writeFileSync(foreign, 'keep me\n');
-          symlinkSync(foreign, target);
-        }
-
-        expect(() => registerSkill('protected', paths)).toThrow(/foreign|refus/i);
-        if (kind === 'file') expect(lstatSync(target).isFile()).toBe(true);
-        if (kind === 'directory') expect(lstatSync(target).isDirectory()).toBe(true);
-        if (kind === 'symlink') expect(readlinkSync(target)).toBe(foreign);
-      },
-    );
-
-    it('refuses a symlinked Claude skills ancestor instead of writing outside the bridge root', () => {
-      createSkill('protected');
-      const externalClaude = join(root, 'external-claude');
-      mkdirSync(externalClaude);
-      symlinkSync(externalClaude, join(root, '.claude'));
-
-      expect(() => registerSkill('protected', paths)).toThrow(
-        /symlink.*ancestor|ancestor.*symlink/i,
-      );
-      expect(existsSync(join(externalClaude, 'skills', 'protected'))).toBe(false);
-    });
-
-    it('refuses a symlinked canonical skills root instead of registering an external source', () => {
-      rmSync(paths.mosaicSkillsDir, { recursive: true });
-      const externalSkills = join(root, 'external-skills');
-      mkdirSync(join(externalSkills, 'protected'), { recursive: true });
-      symlinkSync(externalSkills, paths.mosaicSkillsDir);
-
-      expect(() => registerSkill('protected', paths)).toThrow(
-        /symlink.*ancestor|ancestor.*symlink/i,
-      );
-      expect(existsSync(paths.claudeSkillsDir)).toBe(false);
-    });
-
-    it('refuses a dangling foreign symlink rather than treating it as repairable', () => {
-      createSkill('protected');
-      mkdirSync(paths.claudeSkillsDir, { recursive: true });
-      const foreignMissing = join(root, 'foreign-missing');
-      const target = join(paths.claudeSkillsDir, 'protected');
-      symlinkSync(foreignMissing, target);
-
-      expect(() => registerSkill('protected', paths)).toThrow(/foreign|refus/i);
-      expect(readlinkSync(target)).toBe(foreignMissing);
-    });
-  });
-
-  describe('unregisterSkill', () => {
-    it('removes a Mosaic-owned symlink and is idempotent when absent', () => {
-      createSkill('removable');
-      registerSkill('removable', paths);
-
-      expect(unregisterSkill('removable', paths).status).toBe('unregistered');
-      expect(existsSync(join(paths.claudeSkillsDir, 'removable'))).toBe(false);
-
-      expect(unregisterSkill('removable', paths).status).toBe('already-unregistered');
-    });
-
-    it('refuses to remove a misdirected Mosaic-root symlink', () => {
-      createSkill('other');
-      mkdirSync(paths.claudeSkillsDir, { recursive: true });
-      const requested = join(paths.claudeSkillsDir, 'requested');
-      symlinkSync(join(paths.mosaicSkillsDir, 'other'), requested);
-
-      expect(() => unregisterSkill('requested', paths)).toThrow(/misdirected/i);
-      expect(readlinkSync(requested)).toBe(join(paths.mosaicSkillsDir, 'other'));
-    });
-
-    it.each(['file', 'directory', 'symlink'] as const)('refuses to remove a foreign %s', (kind) => {
-      mkdirSync(paths.claudeSkillsDir, { recursive: true });
-      const target = join(paths.claudeSkillsDir, 'protected');
-      const foreign = join(root, 'foreign');
-
-      if (kind === 'file') writeFileSync(target, 'keep me\n');
-      if (kind === 'directory') mkdirSync(target);
-      if (kind === 'symlink') {
-        writeFileSync(foreign, 'keep me\n');
-        symlinkSync(foreign, target);
-      }
-
-      expect(() => unregisterSkill('protected', paths)).toThrow(/foreign|refus/i);
-      expect(lstatSync(target)).toBeDefined();
-      if (kind === 'symlink') expect(readlinkSync(target)).toBe(foreign);
-    });
-  });
-
-  describe('listSkills', () => {
-    it('flags registered, unregistered, Mosaic-owned dangling, and foreign entries', () => {
-      createSkill('registered');
-      createSkill('unregistered');
-      registerSkill('registered', paths);
-      symlinkSync(join(paths.mosaicSkillsDir, 'retired'), join(paths.claudeSkillsDir, 'dangling'));
-      writeFileSync(join(paths.claudeSkillsDir, 'foreign-file'), 'keep me\n');
-      symlinkSync(join(root, 'missing-foreign'), join(paths.claudeSkillsDir, 'foreign-link'));
-
-      expect(listSkills(paths)).toEqual([
-        expect.objectContaining({ name: 'dangling', status: 'dangling' }),
-        expect.objectContaining({ name: 'foreign-file', status: 'foreign' }),
-        expect.objectContaining({ name: 'foreign-link', status: 'foreign-dangling' }),
-        expect.objectContaining({ name: 'registered', status: 'registered' }),
-        expect.objectContaining({ name: 'unregistered', status: 'unregistered' }),
-      ]);
-    });
-  });
-
-  describe('install linker compatibility', () => {
-    it('preserves foreign-name links into Mosaic home but outside canonical skills', () => {
-      createSkill('missing');
-      mkdirSync(paths.claudeSkillsDir, { recursive: true });
-      const mosaicHome = join(root, '.config', 'mosaic');
-      const liveForeignTarget = join(mosaicHome, 'foreign-non-skill-target');
-      mkdirSync(liveForeignTarget);
-      const liveForeignLink = join(paths.claudeSkillsDir, 'foreign-tool');
-      const danglingForeignLink = join(paths.claudeSkillsDir, 'unresolvable-foreign');
-      symlinkSync(liveForeignTarget, liveForeignLink);
-      symlinkSync(join(mosaicHome, 'foreign-missing'), danglingForeignLink);
-
-      const result = spawnSync('bash', [LEGACY_SYNC_SCRIPT, '--link-only'], {
-        encoding: 'utf8',
-        env: { ...process.env, HOME: root, MOSAIC_HOME: mosaicHome },
-      });
-
-      expect(result.status, result.stderr).toBe(0);
-      expect(readlinkSync(liveForeignLink)).toBe(liveForeignTarget);
-      expect(readlinkSync(danglingForeignLink)).toBe(join(mosaicHome, 'foreign-missing'));
-      expect(readlinkSync(join(paths.claudeSkillsDir, 'missing'))).toBe(
-        join(paths.mosaicSkillsDir, 'missing'),
-      );
-    });
-
-    it('preserves live and dangling foreign Claude symlinks while linking missing skills', () => {
-      createSkill('dangling-foreign');
-      createSkill('live-foreign');
-      createSkill('missing');
-      mkdirSync(paths.claudeSkillsDir, { recursive: true });
-      const external = join(root, 'external');
-      mkdirSync(external);
-      const liveLink = join(paths.claudeSkillsDir, 'live-foreign');
-      const danglingLink = join(paths.claudeSkillsDir, 'dangling-foreign');
-      symlinkSync(external, liveLink);
-      symlinkSync(join(root, 'external-missing'), danglingLink);
-
-      const result = spawnSync('bash', [LEGACY_SYNC_SCRIPT, '--link-only'], {
-        encoding: 'utf8',
-        env: { ...process.env, HOME: root, MOSAIC_HOME: join(root, '.config', 'mosaic') },
-      });
-
-      expect(result.status, result.stderr).toBe(0);
-      expect(readlinkSync(liveLink)).toBe(external);
-      expect(readlinkSync(danglingLink)).toBe(join(root, 'external-missing'));
-      expect(readlinkSync(join(paths.claudeSkillsDir, 'missing'))).toBe(
-        join(paths.mosaicSkillsDir, 'missing'),
-      );
-    });
-  });
-
-  describe('syncClaudeSkills', () => {
-    it('generically creates every missing canonical link and repairs managed broken links', () => {
-      createSkill('added-after-setup');
-      createSkill('another-new-skill');
-      mkdirSync(paths.claudeSkillsDir, { recursive: true });
-      symlinkSync(
-        join(paths.mosaicSkillsDir, 'retired'),
-        join(paths.claudeSkillsDir, 'added-after-setup'),
-      );
-
-      const result = syncClaudeSkills(paths);
-
-      expect(result).toEqual({
-        registered: ['another-new-skill'],
-        repaired: ['added-after-setup'],
-        unchanged: [],
-        conflicts: [],
-      });
-      expectCorrectLink('added-after-setup');
-      expectCorrectLink('another-new-skill');
-    });
-
-    it('escapes an invalid filesystem-derived name in conflict output', () => {
-      createSkill('line\nbreak');
-
-      const result = syncClaudeSkills(paths);
-
-      expect(result.registered).toEqual([]);
-      expect(result.conflicts).toEqual([
-        expect.objectContaining({
-          name: '"line\\nbreak"',
-          reason: expect.stringMatching(/invalid/i),
-        }),
-      ]);
-      expect(existsSync(paths.claudeSkillsDir)).toBe(false);
-    });
-
-    it('continues syncing other skills without clobbering foreign entries', () => {
-      createSkill('blocked');
-      createSkill('link-me');
-      mkdirSync(paths.claudeSkillsDir, { recursive: true });
-      const blocked = join(paths.claudeSkillsDir, 'blocked');
-      writeFileSync(blocked, 'keep me\n');
-
-      const result = syncClaudeSkills(paths);
-
-      expect(result.registered).toEqual(['link-me']);
-      expect(result.conflicts).toEqual([
-        expect.objectContaining({
-          name: 'blocked',
-          reason: expect.stringMatching(/foreign|refus/i),
-        }),
-      ]);
-      expect(readlinkSync(join(paths.claudeSkillsDir, 'link-me'))).toBe(
-        join(paths.mosaicSkillsDir, 'link-me'),
-      );
-      expect(lstatSync(blocked).isFile()).toBe(true);
-    });
-  });
-});
--- a/packages/mosaic/src/commands/skill.ts
+++ b/packages/mosaic/src/commands/skill.ts
@@ -1,419 +0,0 @@
-import {
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readdirSync,
-  readlinkSync,
-  symlinkSync,
-  unlinkSync,
-  type Stats,
-} from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
-import type { Command } from 'commander';
-import { DEFAULT_MOSAIC_HOME } from '../constants.js';
-
-export interface SkillPaths {
-  mosaicSkillsDir: string;
-  claudeSkillsDir: string;
-}
-
-export type SkillRegistrationStatus = 'registered' | 'already-registered' | 'repaired';
-export type SkillUnregistrationStatus = 'unregistered' | 'already-unregistered';
-export type SkillListStatus =
-  | 'registered'
-  | 'unregistered'
-  | 'dangling'
-  | 'foreign'
-  | 'foreign-dangling'
-  | 'misdirected';
-
-export interface SkillRegistrationResult {
-  name: string;
-  status: SkillRegistrationStatus;
-  sourcePath: string;
-  linkPath: string;
-}
-
-export interface SkillUnregistrationResult {
-  name: string;
-  status: SkillUnregistrationStatus;
-  linkPath: string;
-}
-
-export interface SkillListEntry {
-  name: string;
-  status: SkillListStatus;
-  sourcePath?: string;
-  linkPath: string;
-  targetPath?: string;
-}
-
-export interface SkillSyncConflict {
-  name: string;
-  reason: string;
-}
-
-export interface SkillSyncResult {
-  registered: string[];
-  repaired: string[];
-  unchanged: string[];
-  conflicts: SkillSyncConflict[];
-}
-
-const SAFE_SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-
-export class SkillBridgeError extends Error {
-  public constructor(message: string) {
-    super(message);
-    this.name = 'SkillBridgeError';
-  }
-}
-
-/** Resolve the production bridge paths while keeping tests injectable. */
-export function getDefaultSkillPaths(): SkillPaths {
-  const mosaicHome = process.env['MOSAIC_HOME'] ?? DEFAULT_MOSAIC_HOME;
-  const claudeHome = process.env['CLAUDE_HOME'] ?? join(homedir(), '.claude');
-  return {
-    mosaicSkillsDir: join(mosaicHome, 'skills'),
-    claudeSkillsDir: join(claudeHome, 'skills'),
-  };
-}
-
-/**
- * Reject a user-supplied name before any filesystem operation.
- * A skill name must identify one direct child in both managed roots.
- */
-export function validateSkillName(name: string): void {
-  if (
-    name.length === 0 ||
-    name.startsWith('-') ||
-    name.endsWith('.') ||
-    name.includes('..') ||
-    name.includes('/') ||
-    name.includes('\\') ||
-    isAbsolute(name) ||
-    !SAFE_SKILL_NAME.test(name)
-  ) {
-    throw new SkillBridgeError(
-      `Invalid skill name ${JSON.stringify(name)}: use letters, numbers, dots, underscores, or hyphens; start with a letter or number; and do not use paths, "..", or a leading "-".`,
-    );
-  }
-}
-
-function displaySkillName(name: string): string {
-  return SAFE_SKILL_NAME.test(name) ? name : JSON.stringify(name);
-}
-
-function lstatIfPresent(path: string): Stats | undefined {
-  try {
-    return lstatSync(path);
-  } catch (error: unknown) {
-    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return undefined;
-    throw error;
-  }
-}
-
-function assertNoSymlinkAncestors(path: string): void {
-  const absolute = resolve(path);
-  const pathRoot = parse(absolute).root;
-  let current = pathRoot;
-
-  for (const segment of relative(pathRoot, absolute).split(sep)) {
-    if (segment.length === 0) continue;
-    current = join(current, segment);
-    const entry = lstatIfPresent(current);
-    if (!entry) break;
-    if (entry.isSymbolicLink()) {
-      throw new SkillBridgeError(
-        `Refusing symlink ancestor at ${current}; managed skill roots must resolve without symlink traversal.`,
-      );
-    }
-  }
-}
-
-function assertManagedRoots(paths: SkillPaths): void {
-  assertNoSymlinkAncestors(paths.mosaicSkillsDir);
-  assertNoSymlinkAncestors(paths.claudeSkillsDir);
-}
-
-function directChild(root: string, name: string): string {
-  const resolvedRoot = resolve(root);
-  const child = resolve(resolvedRoot, name);
-  if (dirname(child) !== resolvedRoot) {
-    throw new SkillBridgeError(`Invalid skill name "${name}": resolved path escapes its root.`);
-  }
-  return child;
-}
-
-function resolveLinkTarget(linkPath: string): string {
-  return resolve(dirname(linkPath), readlinkSync(linkPath));
-}
-
-function isInsideSkillsRoot(targetPath: string, skillsRoot: string): boolean {
-  const rel = relative(resolve(skillsRoot), resolve(targetPath));
-  return rel.length > 0 && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
-}
-
-function isDangling(linkPath: string): boolean {
-  return !existsSync(linkPath);
-}
-
-function assertSourceSkill(name: string, paths: SkillPaths): string {
-  const sourcePath = directChild(paths.mosaicSkillsDir, name);
-  const source = lstatIfPresent(sourcePath);
-  if (!source?.isDirectory()) {
-    throw new SkillBridgeError(
-      `Canonical skill directory not found: ${sourcePath}. Add the skill under the Mosaic skills directory before registering it.`,
-    );
-  }
-  return sourcePath;
-}
-
-function foreignTargetError(linkPath: string): SkillBridgeError {
-  return new SkillBridgeError(
-    `Refusing to modify foreign entry at ${linkPath}; only symlinks pointing inside the Mosaic skills directory are managed.`,
-  );
-}
-
-/** Register one canonical skill with Claude Code without clobbering foreign entries. */
-export function registerSkill(
-  name: string,
-  paths: SkillPaths = getDefaultSkillPaths(),
-): SkillRegistrationResult {
-  validateSkillName(name);
-  assertManagedRoots(paths);
-  const sourcePath = assertSourceSkill(name, paths);
-  const linkPath = directChild(paths.claudeSkillsDir, name);
-  const existing = lstatIfPresent(linkPath);
-
-  if (!existing) {
-    mkdirSync(paths.claudeSkillsDir, { recursive: true });
-    symlinkSync(sourcePath, linkPath);
-    return { name, status: 'registered', sourcePath, linkPath };
-  }
-
-  if (!existing.isSymbolicLink()) throw foreignTargetError(linkPath);
-
-  const existingTarget = resolveLinkTarget(linkPath);
-  if (!isInsideSkillsRoot(existingTarget, paths.mosaicSkillsDir)) {
-    throw foreignTargetError(linkPath);
-  }
-
-  if (existingTarget === resolve(sourcePath) && !isDangling(linkPath)) {
-    return { name, status: 'already-registered', sourcePath, linkPath };
-  }
-
-  if (!isDangling(linkPath)) {
-    throw new SkillBridgeError(
-      `Refusing to replace live Mosaic skill symlink at ${linkPath}; it points to ${existingTarget}, not ${sourcePath}.`,
-    );
-  }
-
-  unlinkSync(linkPath);
-  symlinkSync(sourcePath, linkPath);
-  return { name, status: 'repaired', sourcePath, linkPath };
-}
-
-/** Unregister only a symlink owned by the canonical Mosaic skills root. */
-export function unregisterSkill(
-  name: string,
-  paths: SkillPaths = getDefaultSkillPaths(),
-): SkillUnregistrationResult {
-  validateSkillName(name);
-  assertManagedRoots(paths);
-  const linkPath = directChild(paths.claudeSkillsDir, name);
-  const existing = lstatIfPresent(linkPath);
-
-  if (!existing) return { name, status: 'already-unregistered', linkPath };
-  if (!existing.isSymbolicLink()) throw foreignTargetError(linkPath);
-
-  const targetPath = resolveLinkTarget(linkPath);
-  if (!isInsideSkillsRoot(targetPath, paths.mosaicSkillsDir)) throw foreignTargetError(linkPath);
-
-  const expectedTarget = resolve(directChild(paths.mosaicSkillsDir, name));
-  if (targetPath !== expectedTarget) {
-    throw new SkillBridgeError(
-      `Refusing to unregister misdirected Mosaic skill symlink at ${linkPath}; it points to ${targetPath}, not ${expectedTarget}.`,
-    );
-  }
-
-  unlinkSync(linkPath);
-  return { name, status: 'unregistered', linkPath };
-}
-
-function canonicalSkillNames(paths: SkillPaths): string[] {
-  assertNoSymlinkAncestors(paths.mosaicSkillsDir);
-  const root = lstatIfPresent(paths.mosaicSkillsDir);
-  if (!root) return [];
-  if (!root.isDirectory()) {
-    throw new SkillBridgeError(
-      `Canonical skills path is not a directory: ${paths.mosaicSkillsDir}`,
-    );
-  }
-  return readdirSync(paths.mosaicSkillsDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => entry.name)
-    .sort();
-}
-
-function claudeEntryNames(paths: SkillPaths): string[] {
-  assertNoSymlinkAncestors(paths.claudeSkillsDir);
-  const root = lstatIfPresent(paths.claudeSkillsDir);
-  if (!root) return [];
-  if (!root.isDirectory()) {
-    throw new SkillBridgeError(`Claude skills path is not a directory: ${paths.claudeSkillsDir}`);
-  }
-  return readdirSync(paths.claudeSkillsDir)
-    .filter((name) => name.length > 0)
-    .sort();
-}
-
-/** Return a deterministic union of canonical skills and Claude bridge entries. */
-export function listSkills(paths: SkillPaths = getDefaultSkillPaths()): SkillListEntry[] {
-  const canonicalNames = new Set(canonicalSkillNames(paths));
-  const names = new Set([...canonicalNames, ...claudeEntryNames(paths)]);
-  const entries: SkillListEntry[] = [];
-
-  for (const name of [...names].sort()) {
-    const sourcePath = canonicalNames.has(name)
-      ? directChild(paths.mosaicSkillsDir, name)
-      : undefined;
-    const linkPath = directChild(paths.claudeSkillsDir, name);
-    const installed = lstatIfPresent(linkPath);
-
-    if (!installed) {
-      if (sourcePath) entries.push({ name, status: 'unregistered', sourcePath, linkPath });
-      continue;
-    }
-
-    if (!installed.isSymbolicLink()) {
-      entries.push({ name, status: 'foreign', sourcePath, linkPath });
-      continue;
-    }
-
-    const targetPath = resolveLinkTarget(linkPath);
-    const owned = isInsideSkillsRoot(targetPath, paths.mosaicSkillsDir);
-    const dangling = isDangling(linkPath);
-
-    if (!owned) {
-      entries.push({
-        name,
-        status: dangling ? 'foreign-dangling' : 'foreign',
-        sourcePath,
-        linkPath,
-        targetPath,
-      });
-      continue;
-    }
-
-    if (dangling) {
-      entries.push({ name, status: 'dangling', sourcePath, linkPath, targetPath });
-      continue;
-    }
-
-    entries.push({
-      name,
-      status: sourcePath && targetPath === resolve(sourcePath) ? 'registered' : 'misdirected',
-      sourcePath,
-      linkPath,
-      targetPath,
-    });
-  }
-
-  return entries;
-}
-
-/** Reconcile every canonical skill directory while preserving all foreign entries. */
-export function syncClaudeSkills(paths: SkillPaths = getDefaultSkillPaths()): SkillSyncResult {
-  const result: SkillSyncResult = {
-    registered: [],
-    repaired: [],
-    unchanged: [],
-    conflicts: [],
-  };
-
-  for (const name of canonicalSkillNames(paths)) {
-    try {
-      const registration = registerSkill(name, paths);
-      if (registration.status === 'registered') result.registered.push(name);
-      if (registration.status === 'repaired') result.repaired.push(name);
-      if (registration.status === 'already-registered') result.unchanged.push(name);
-    } catch (error: unknown) {
-      result.conflicts.push({
-        name: displaySkillName(name),
-        reason: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-
-  return result;
-}
-
-function reportCommandError(error: unknown): void {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exitCode = 1;
-}
-
-/** Register the `mosaic skill` command group. */
-export function registerSkillCommand(
-  program: Command,
-  paths: SkillPaths = getDefaultSkillPaths(),
-): void {
-  const skill = program
-    .command('skill')
-    .description('Manage Claude Code skill registrations')
-    .configureHelp({ sortSubcommands: true });
-
-  skill
-    .command('register <name>')
-    .description('Register a Mosaic skill with Claude Code')
-    .action((name: string) => {
-      try {
-        const result = registerSkill(name, paths);
-        if (result.status === 'already-registered') {
-          console.log(`${name}: already registered`);
-        } else if (result.status === 'repaired') {
-          console.log(`${name}: repaired dangling registration`);
-        } else {
-          console.log(`${name}: registered`);
-        }
-      } catch (error: unknown) {
-        reportCommandError(error);
-      }
-    });
-
-  skill
-    .command('unregister <name>')
-    .description('Unregister a Mosaic skill from Claude Code')
-    .action((name: string) => {
-      try {
-        const result = unregisterSkill(name, paths);
-        console.log(
-          result.status === 'already-unregistered'
-            ? `${name}: already unregistered`
-            : `${name}: unregistered`,
-        );
-      } catch (error: unknown) {
-        reportCommandError(error);
-      }
-    });
-
-  skill
-    .command('list')
-    .description('List registered, dangling, foreign, and unregistered skills')
-    .action(() => {
-      try {
-        const entries = listSkills(paths);
-        if (entries.length === 0) {
-          console.log('No Mosaic or Claude Code skills found.');
-          return;
-        }
-        for (const entry of entries) {
-          console.log(`${entry.status.padEnd(17)} ${displaySkillName(entry.name)}`);
-        }
-      } catch (error: unknown) {
-        reportCommandError(error);
-      }
-    });
-}
--- a/packages/mosaic/src/fleet/fleet-agent-crud.ts
+++ b/packages/mosaic/src/fleet/fleet-agent-crud.ts
@@ -381,22 +381,6 @@ function isMissingFile(error: unknown): boolean {
  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }

-/**
- * Non-blocking acquire of the roster mutation lock: an exclusive `wx` create that
- * throws `concurrent-mutation` (never waits) if the lock is already held. The
- * on-disk format is an empty private file. CRUD releases in a plain `finally` with
- * no result-preservation logic, so a release fault here must not override the
- * mutation result — the release swallows unlink failures by design.
- *
- * The recovery-framed `fleet regen` contends on this exact same lock file, but it
- * does so through the hardened, ownership-proving acquirer in the reconciler
- * (`acquirePrivateRosterMutationLock`), not this one: whoever wins the `wx` create
- * owns the file (the loser always gets `concurrent-mutation`), so the reconciler's
- * ownership token is only ever written and read back by the same regen invocation,
- * never by this empty-file writer. The two acquirers stay mutually compatible at
- * the `wx`-contention layer while regen additionally proves ownership before it
- * unlinks — a guarantee CRUD does not need because it releases unconditionally.
- */
 async function acquireMutationLock(lockPath: string): Promise<() => Promise<void>> {
  try {
    const handle = await open(lockPath, 'wx', 0o600);
--- a/packages/mosaic/src/fleet/fleet-reconciler.ts
+++ b/packages/mosaic/src/fleet/fleet-reconciler.ts
@@ -584,29 +584,6 @@ function defaultValidateRoster(
  };
 }

-/**
- * The single roster-v2 → generated-projection mapping. Both the reconciler's
- * apply path ({@link defaultPrepareProjections}) and the recovery-framed
- * `mosaic fleet regen` command derive their generated env from THIS one
- * function, so the two paths can never drift (the #791 single-SSOT invariant).
- * Pure: no IO, no clock — a deterministic function of the roster alone.
- */
-export function projectRosterV2AgentGeneratedEnv(
-  roster: FleetRosterV2,
-  agent: FleetRosterV2Agent,
-): Readonly<Record<string, string>> {
-  return {
-    MOSAIC_AGENT_NAME: agent.name,
-    MOSAIC_AGENT_CLASS: agent.className,
-    MOSAIC_AGENT_RUNTIME: agent.runtime,
-    MOSAIC_AGENT_MODEL: agent.model,
-    MOSAIC_AGENT_REASONING: agent.reasoning,
-    MOSAIC_AGENT_TOOL_POLICY: agent.toolPolicy,
-    MOSAIC_AGENT_WORKDIR: agent.workingDirectory,
-    MOSAIC_TMUX_SOCKET: roster.tmux.socketName,
-  };
-}
-
 function defaultPrepareProjections(
  request: FleetReconcileRequest,
 ): (roster: FleetRosterV2) => Promise<readonly PreparedAgentEnvironmentProjection[]> {
@@ -619,7 +596,16 @@ function defaultPrepareProjections(
            mosaicHome,
            agentEnvDir: join(mosaicHome, 'fleet', 'agents'),
            agentName: agent.name,
-            generated: projectRosterV2AgentGeneratedEnv(roster, agent),
+            generated: {
+              MOSAIC_AGENT_NAME: agent.name,
+              MOSAIC_AGENT_CLASS: agent.className,
+              MOSAIC_AGENT_RUNTIME: agent.runtime,
+              MOSAIC_AGENT_MODEL: agent.model,
+              MOSAIC_AGENT_REASONING: agent.reasoning,
+              MOSAIC_AGENT_TOOL_POLICY: agent.toolPolicy,
+              MOSAIC_AGENT_WORKDIR: agent.workingDirectory,
+              MOSAIC_TMUX_SOCKET: roster.tmux.socketName,
+            },
          }),
      ),
    );
@@ -634,193 +620,62 @@ function mosaicHomeFor(deps: FleetReconcileDeps): string {
  return deps.mosaicHome ?? join(homedir(), '.config', 'mosaic');
 }

-/** Acquires the private reconcile lock only after proving the canonical managed path. */
+/** Acquires a private lock only after proving the canonical managed path. */
 export function acquirePrivateReconcileLock(
  mosaicHome: string,
  openLock: typeof open = open,
-): () => Promise<() => Promise<void>> {
-  return acquirePrivateManagedRosterLock(
-    mosaicHome,
-    'roster.yaml.reconcile.lock',
-    'Another roster reconciliation is in progress.',
-    openLock,
-  );
-}
-
-/**
- * Acquires the private roster MUTATION lock (`roster.yaml.mutation.lock`) with the
- * exact same ownership-proof discipline as the reconcile lock. Exposed so the
- * recovery-framed `mosaic fleet regen` can serialize its projection rewrites
- * against agent CRUD — which holds this very lock while it rewrites the roster and
- * the same derived projections — reusing this hardened acquirer rather than
- * reimplementing it.
- *
- * The release PROVES ownership (device/inode + token) before unlinking, so a lock
- * that was already cleared and replaced by the time release runs is never deleted
- * out from under the new owner (it fails closed as `lock-cleanup-failed` instead),
- * and that cleanup fault is propagated to the caller rather than silently dropped.
- * CRUD contends on the identical path with a plain empty-file `wx` create; the two
- * never co-own it (whoever wins `wx` owns it; the loser gets `concurrent-mutation`),
- * so the token this writes is only ever read back by the same regen invocation that
- * wrote it.
- *
- * SCOPE of the guarantee (matches the merged reconcile lock exactly — see
- * {@link acquirePrivateManagedRosterLock}): the ownership proof closes the
- * *reachable* window — a stale-lock reaper or operator cleared our lock and another
- * writer took it BEFORE our release began — not the residual sub-instruction window
- * between the final check and the path-based `unlink`. Closing that residual fully
- * requires an fd-held advisory lock adopted by every fleet writer (CRUD, reconcile,
- * regen), which is a cross-cutting mechanism change out of scope for this
- * projection-only recovery command; it is unreachable within the `wx` writer
- * protocol regardless (no Mosaic writer removes a lock it does not own, so only
- * external interference can vacate our inode mid-release).
- */
-export function acquirePrivateRosterMutationLock(
-  mosaicHome: string,
-  openLock: typeof open = open,
-): () => Promise<() => Promise<void>> {
-  return acquirePrivateManagedRosterLock(
-    mosaicHome,
-    'roster.yaml.mutation.lock',
-    'Another roster mutation is in progress.',
-    openLock,
-  );
-}
-
-/**
- * Shared body for the ownership-proving managed roster locks. Acquires `lockLeaf`
- * under `<mosaicHome>/fleet` with a private `wx` create, writes an ownership token,
- * and returns a release that re-proves device/inode + token before unlinking so it
- * can never remove a lock it no longer owns. Non-blocking: throws `concurrent-mutation`
- * (with `busyMessage`) on contention rather than waiting.
- */
-function acquirePrivateManagedRosterLock(
-  mosaicHome: string,
-  lockLeaf: string,
-  busyMessage: string,
-  openLock: typeof open,
 ): () => Promise<() => Promise<void>> {
  const fleetDir = join(mosaicHome, 'fleet');
-  const lockPath = join(fleetDir, lockLeaf);
-  // The message-producing helpers below serve BOTH managed locks, so every fault
-  // names the actual lock file (`fleet/<leaf>`) — an operator needs to know WHICH
-  // lock is stale, not a hardcoded "reconciliation lock".
-  const lockLabel = `fleet/${lockLeaf}`;
+  const lockPath = join(fleetDir, 'roster.yaml.reconcile.lock');
  return async (): Promise<() => Promise<void>> => {
    await assertPrivateManagedDirectory(mosaicHome);
    await assertPrivateManagedDirectory(fleetDir);
-    await assertSafeLockLeafIfPresent(lockPath, lockLabel);
+    await assertSafeLockLeafIfPresent(lockPath);

    let handle: FileHandle;
    try {
      handle = await openLock(lockPath, 'wx', 0o600);
    } catch (error: unknown) {
      if (isCode(error, 'EEXIST')) {
-        await assertSafeLockLeafIfPresent(lockPath, lockLabel);
-        throw new FleetReconcileError('concurrent-mutation', busyMessage);
+        await assertSafeLockLeafIfPresent(lockPath);
+        throw new FleetReconcileError(
+          'concurrent-mutation',
+          'Another roster reconciliation is in progress.',
+        );
      }
-      throw new FleetReconcileError('lock-io-failed', `The ${lockLabel} lock cannot be created.`);
+      throw new FleetReconcileError('lock-io-failed', 'The reconciliation lock cannot be created.');
    }

-    // Identity of the lock WE exclusively created (the `wx` create guaranteed it is
-    // ours). Captured up front so both the release closure and the init-failure
-    // cleanup below can prove ownership by device/inode before touching the file.
-    const created = await handle.stat().catch((): undefined => undefined);
-
    const token = randomUUID();
-    let tokenPersisted = false;
    try {
      await handle.writeFile(`${token}\n`, 'utf8');
-      tokenPersisted = true;
+      const opened = await handle.stat();
      await handle.close();
-      if (!created)
-        throw new FleetReconcileError(
-          'lock-io-failed',
-          `The ${lockLabel} lock cannot be initialized.`,
-        );
-      await assertLockOwnership(
-        lockPath,
-        created.dev,
-        created.ino,
-        token,
-        'unsafe-lock',
-        lockLabel,
-      );
+      await assertLockOwnership(lockPath, opened.dev, opened.ino, token, 'unsafe-lock');
      return async (): Promise<void> => {
        try {
-          await assertLockOwnership(
-            lockPath,
-            created.dev,
-            created.ino,
-            token,
-            'lock-cleanup-failed',
-            lockLabel,
-          );
+          await assertLockOwnership(lockPath, opened.dev, opened.ino, token, 'lock-cleanup-failed');
+          await assertLockOwnership(lockPath, opened.dev, opened.ino, token, 'lock-cleanup-failed');
          await unlink(lockPath);
        } catch (error: unknown) {
          if (error instanceof FleetReconcileError) throw error;
-          throw new FleetReconcileError('lock-cleanup-failed', `The ${lockLabel} cleanup failed.`);
+          throw new FleetReconcileError(
+            'lock-cleanup-failed',
+            'The reconciliation lock cleanup failed.',
+          );
        }
      };
    } catch (error: unknown) {
      await handle.close().catch((): void => {});
-      // Best-effort: remove the lock THIS invocation created so a transient init
-      // fault does not strand a lock that would block future regen and agent CRUD.
-      // dev/ino-guarded so it can never delete a replacement; swallowed so cleanup
-      // failure never masks the initialization error being surfaced. The token is
-      // passed only once persisted, so the fallback path (when the post-create stat
-      // failed and dev/ino is unavailable) can still prove ownership by content.
-      await removeOwnedLockLeafBestEffort(lockPath, created, tokenPersisted ? token : undefined);
      if (error instanceof FleetReconcileError) throw error;
      throw new FleetReconcileError(
        'lock-io-failed',
-        `The ${lockLabel} lock cannot be initialized.`,
+        'The reconciliation lock cannot be initialized.',
      );
    }
  };
 }

-/**
- * Best-effort removal of a managed lock leaf THIS process created, used only on the
- * initialization-failure path. Two independent ownership proofs, so a lock that was
- * already replaced is never deleted:
- *
- *   - primary: the captured device/inode of the file we exclusively `wx`-created; or
- *   - fallback: when the post-create stat itself failed (dev/ino unavailable), the
- *     random `ownershipToken` we persisted — only OUR lock carries it, so a CRUD
- *     (empty) or a differently-tokened replacement is never removed.
- *
- * Every fault is swallowed because the caller is already surfacing the initialization
- * error and a leftover lock is recoverable via the documented runbook. If BOTH proofs
- * are unavailable (stat failed AND the token write never landed) the lock is left in
- * place rather than risk deleting another writer's file — a doubly-degenerate case
- * requiring two independent fs faults on a just-created fd.
- */
-async function removeOwnedLockLeafBestEffort(
-  lockPath: string,
-  created: { dev: number; ino: number } | undefined,
-  ownershipToken: string | undefined,
-): Promise<void> {
-  try {
-    const current = await lstat(lockPath);
-    if (!current.isFile() || current.isSymbolicLink()) return;
-    if (created) {
-      if (current.dev === created.dev && current.ino === created.ino) {
-        await unlink(lockPath);
-      }
-      return;
-    }
-    if (ownershipToken !== undefined) {
-      const contents = await readFile(lockPath, 'utf8');
-      if (contents.trim() === ownershipToken) {
-        await unlink(lockPath);
-      }
-    }
-  } catch {
-    // Swallowed: leftover lock is recoverable; do not mask the init error.
-  }
-}
-
 async function assertPrivateManagedDirectory(path: string): Promise<void> {
  try {
    const metadata = await lstat(path);
@@ -836,16 +691,16 @@ async function assertPrivateManagedDirectory(path: string): Promise<void> {
  }
 }

-async function assertSafeLockLeafIfPresent(lockPath: string, lockLabel: string): Promise<void> {
+async function assertSafeLockLeafIfPresent(lockPath: string): Promise<void> {
  try {
    const metadata = await lstat(lockPath);
    if (!metadata.isFile() || metadata.isSymbolicLink() || (metadata.mode & 0o077) !== 0) {
-      throw new FleetReconcileError('unsafe-lock', `The ${lockLabel} lock path is unsafe.`);
+      throw new FleetReconcileError('unsafe-lock', 'The reconciliation lock path is unsafe.');
    }
  } catch (error: unknown) {
    if (isCode(error, 'ENOENT')) return;
    if (error instanceof FleetReconcileError) throw error;
-    throw new FleetReconcileError('unsafe-lock', `The ${lockLabel} lock path is unavailable.`);
+    throw new FleetReconcileError('unsafe-lock', 'The reconciliation lock path is unavailable.');
  }
 }

@@ -855,7 +710,6 @@ async function assertLockOwnership(
  inode: number,
  token: string,
  failureCode: 'unsafe-lock' | 'lock-cleanup-failed',
-  lockLabel: string,
 ): Promise<void> {
  try {
    const metadata = await lstat(lockPath);
@@ -866,21 +720,24 @@ async function assertLockOwnership(
      metadata.dev !== device ||
      metadata.ino !== inode
    ) {
-      throw new FleetReconcileError(failureCode, `The ${lockLabel} ownership changed.`);
+      throw new FleetReconcileError(failureCode, 'The reconciliation lock ownership changed.');
    }
    const handle = await open(lockPath, constants.O_RDONLY | constants.O_NOFOLLOW);
    try {
      const opened = await handle.stat();
      const contents = await handle.readFile({ encoding: 'utf8' });
      if (opened.dev !== device || opened.ino !== inode || contents !== `${token}\n`) {
-        throw new FleetReconcileError(failureCode, `The ${lockLabel} ownership changed.`);
+        throw new FleetReconcileError(failureCode, 'The reconciliation lock ownership changed.');
      }
    } finally {
      await handle.close();
    }
  } catch (error: unknown) {
    if (error instanceof FleetReconcileError) throw error;
-    throw new FleetReconcileError(failureCode, `The ${lockLabel} ownership cannot be proven.`);
+    throw new FleetReconcileError(
+      failureCode,
+      'The reconciliation lock ownership cannot be proven.',
+    );
  }
 }

--- a/packages/mosaic/src/fleet/fleet-roster-v1.ts
+++ b/packages/mosaic/src/fleet/fleet-roster-v1.ts
@@ -104,10 +104,6 @@ export interface FleetRoster {

 export type FleetRosterInputFormat = 'yaml' | 'json';

-export class FleetRosterConfigurationError extends Error {
-  override name = 'FleetRosterConfigurationError';
-}
-
 export function resolveInstalledFleetRosterPath(mosaicHome: string): string {
  const yamlPath = join(mosaicHome, 'fleet', 'roster.yaml');
  try {
@@ -142,52 +138,8 @@ export function parseFleetRosterV1(
 }

 export async function loadFleetRoster(path: string): Promise<FleetRoster> {
-  const source = await readFleetRosterText(path);
-  try {
-    return parseFleetRosterV1(source, path.endsWith('.json') ? 'json' : 'yaml');
-  } catch (error) {
-    if (isRosterParserError(error)) throw invalidFleetRosterError(path);
-    throw error;
-  }
-}
-
-/** Read an operator-owned roster with errors that say how to recover. */
-export async function readFleetRosterText(path: string): Promise<string> {
-  try {
-    return await readFile(path, 'utf8');
-  } catch (error) {
-    if (isNodeErrorCode(error, 'ENOENT')) {
-      throw new FleetRosterConfigurationError(
-        `No fleet roster found at ${path}. Run \`mosaic fleet init\` to create one.`,
-      );
-    }
-    throw new FleetRosterConfigurationError(
-      `Could not read fleet roster at ${path}. Check the file exists and is readable.`,
-    );
-  }
-}
-
-/** Parse a roster document needed only to select the v1/v2 command path. */
-export function parseFleetRosterDocument(source: string, path: string): unknown {
-  try {
-    return YAML.parse(source);
-  } catch (error) {
-    if (isRosterParserError(error)) throw invalidFleetRosterError(path);
-    throw error;
-  }
-}
-
-function invalidFleetRosterError(path: string): FleetRosterConfigurationError {
-  return new FleetRosterConfigurationError(
-    `Fleet roster at ${path} is invalid. Fix the file or run \`mosaic fleet init --force\`.`,
-  );
-}
-
-function isRosterParserError(error: unknown): boolean {
-  return (
-    error instanceof SyntaxError ||
-    (error instanceof Error && (error.name === 'YAMLParseError' || error.name === 'YAMLWarning'))
-  );
+  const source = await readFile(path, 'utf8');
+  return parseFleetRosterV1(source, path.endsWith('.json') ? 'json' : 'yaml');
 }

 export function getRosterAgent(roster: FleetRoster, name: string): FleetAgent {
@@ -197,16 +149,6 @@ export function getRosterAgent(roster: FleetRoster, name: string): FleetAgent {
 }

 export function normalizeFleetRosterV1(raw: RawFleetRoster): FleetRoster {
-  try {
-    return normalizeFleetRosterV1Unchecked(raw);
-  } catch (error) {
-    if (error instanceof FleetRosterConfigurationError) throw error;
-    if (error instanceof Error) throw new FleetRosterConfigurationError(error.message);
-    throw error;
-  }
-}
-
-function normalizeFleetRosterV1Unchecked(raw: RawFleetRoster): FleetRoster {
  assertObject(raw, 'Fleet roster');
  assertKnownKeys(raw, 'Fleet roster', [
    'version',
--- a/packages/mosaic/src/fleet/generated-env-boundary.ts
+++ b/packages/mosaic/src/fleet/generated-env-boundary.ts
@@ -204,53 +204,6 @@ export async function prepareAgentEnvironmentProjection(
  };
 }

-/** A generated-only projection validated without touching any legacy/local/quarantine file. */
-export interface PreparedGeneratedAgentEnvironmentProjection {
-  readonly mosaicHome: string;
-  readonly agentEnvDir: string;
-  readonly generatedPath: string;
-  readonly generated: string;
-}
-
-/**
- * Validates ONLY the roster-derived generated projection for a recovery rebuild.
- * Unlike {@link prepareAgentEnvironmentProjection}, this never reads, classifies,
- * relocates, or quarantines the legacy `.env` / `.env.local` operator surface — it
- * exists so `mosaic fleet regen` has no code path that can mutate anything except
- * `<name>.env.generated`. The existing generated file, if present, must already be
- * a private regular file.
- */
-export async function prepareGeneratedAgentEnvironmentProjection(
-  options: AgentEnvironmentProjectionOptions,
-): Promise<PreparedGeneratedAgentEnvironmentProjection> {
-  if (!AGENT_NAME.test(options.agentName)) {
-    throw new AgentEnvBoundaryError('unsafe-agent-name', 'MOSAIC_AGENT_NAME', options.agentName);
-  }
-  await validatePrivateProjectionDirectory(options.mosaicHome, options.agentEnvDir);
-  const generatedPath = join(options.agentEnvDir, `${options.agentName}.env.generated`);
-  const generated = renderGeneratedAgentEnvironment(options.generated);
-  await assertPrivateRegularFileIfPresent(generatedPath);
-  return {
-    mosaicHome: options.mosaicHome,
-    agentEnvDir: options.agentEnvDir,
-    generatedPath,
-    generated,
-  };
-}
-
-/**
- * Applies a generated-only projection: writes ONLY `<name>.env.generated` atomically
- * and touches nothing else. It never writes `.env.local`/`.env.quarantine` and never
- * unlinks the legacy `.env` — the projection-only recovery guarantee is structural.
- */
-export async function applyPreparedGeneratedAgentEnvironmentProjection(
-  prepared: PreparedGeneratedAgentEnvironmentProjection,
-): Promise<string> {
-  await ensurePrivateProjectionDirectory(prepared.mosaicHome, prepared.agentEnvDir);
-  await writePrivateAtomically(prepared.generatedPath, prepared.generated);
-  return prepared.generatedPath;
-}
-
 /**
 * Validates only the exact generated projection eligible for a roster delete.
 * Local overrides, legacy input, and quarantine records are operator-retained and
--- a/packages/mosaic/src/runtime/update-checker.reseed.spec.ts
+++ b/packages/mosaic/src/runtime/update-checker.reseed.spec.ts
@@ -7,7 +7,6 @@ import {
  mkdirSync,
  readdirSync,
  readFileSync,
-  readlinkSync,
  rmSync,
  statSync,
  symlinkSync,
@@ -301,50 +300,6 @@ describe('repairFleetCommsTools', () => {
 });

 describe('runFrameworkReseed', () => {
-  it('auto-registers every canonical skill after a successful upgrade re-seed', () => {
-    const root = mkdtempSync(join(tmpdir(), 'mosaic-reseed-skills-'));
-    const framework = join(root, 'framework');
-    const home = join(root, 'mosaic');
-    const claudeSkills = join(root, '.claude', 'skills');
-    mkdirSync(framework, { recursive: true });
-    mkdirSync(join(home, 'skills', 'added-after-setup'), { recursive: true });
-    mkdirSync(join(home, 'skills', 'another-new-skill'), { recursive: true });
-    writeFileSync(join(framework, 'install.sh'), '#!/usr/bin/env bash\nexit 0\n', { mode: 0o755 });
-
-    const res = runFrameworkReseed(framework, home, claudeSkills);
-
-    expect(res.ok).toBe(true);
-    expect(res.skillSync).toMatchObject({
-      registered: ['added-after-setup', 'another-new-skill'],
-      conflicts: [],
-    });
-    expect(readlinkSync(join(claudeSkills, 'added-after-setup'))).toBe(
-      join(home, 'skills', 'added-after-setup'),
-    );
-    expect(readlinkSync(join(claudeSkills, 'another-new-skill'))).toBe(
-      join(home, 'skills', 'another-new-skill'),
-    );
-    rmSync(root, { recursive: true, force: true });
-  });
-
-  it('keeps a successful framework re-seed successful when bridge reconciliation fails', () => {
-    const root = mkdtempSync(join(tmpdir(), 'mosaic-reseed-bridge-failure-'));
-    const framework = join(root, 'framework');
-    const home = join(root, 'mosaic');
-    const claudeSkills = join(root, '.claude', 'skills');
-    mkdirSync(framework, { recursive: true });
-    mkdirSync(home, { recursive: true });
-    writeFileSync(join(home, 'skills'), 'invalid canonical root\n');
-    writeFileSync(join(framework, 'install.sh'), '#!/usr/bin/env bash\nexit 0\n', { mode: 0o755 });
-
-    const res = runFrameworkReseed(framework, home, claudeSkills);
-
-    expect(res.ok).toBe(true);
-    expect(res.skillSync).toBeUndefined();
-    expect(res.skillSyncError).toMatch(/not a directory/i);
-    rmSync(root, { recursive: true, force: true });
-  });
-
  it('reports not-ok (not throw) when the installer is absent', () => {
    const missing = mkdtempSync(join(tmpdir(), 'mosaic-noinstaller-'));
    const res = runFrameworkReseed(missing, join(missing, 'home'));
--- a/packages/mosaic/src/runtime/update-checker.ts
+++ b/packages/mosaic/src/runtime/update-checker.ts
@@ -43,7 +43,6 @@ import {
  ensureManagedDirectory,
  readRegularFileSecure,
 } from '../fleet/secure-file.js';
-import { getDefaultSkillPaths, syncClaudeSkills, type SkillSyncResult } from '../commands/skill.js';

 // ─── Types ──────────────────────────────────────────────────────────────────

@@ -872,39 +871,19 @@ export function repairFleetCommsTools(
 * describing what happened (so callers can message + decide on relaunch).
 * Best-effort: a missing installer or a non-zero exit is reported, not thrown.
 */
-export interface FrameworkReseedResult {
-  ok: boolean;
-  reason?: string;
-  skillSync?: SkillSyncResult;
-  skillSyncError?: string;
-}
-
 export function runFrameworkReseed(
  frameworkRoot = resolveBundledFrameworkRoot(),
  mosaicHome = join(homedir(), '.config', 'mosaic'),
-  claudeSkillsDir = getDefaultSkillPaths().claudeSkillsDir,
-): FrameworkReseedResult {
+): { ok: boolean; reason?: string } {
  const { installer, command, env } = buildReseedCommand(frameworkRoot, mosaicHome);
  if (!existsSync(installer)) {
    return { ok: false, reason: `installer not found: ${installer}` };
  }
  try {
    execSync(command, { stdio: 'inherit', env: { ...process.env, ...env }, timeout: 120_000 });
-  } catch (error: unknown) {
-    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
-  }
-
-  try {
-    const skillSync = syncClaudeSkills({
-      mosaicSkillsDir: join(mosaicHome, 'skills'),
-      claudeSkillsDir,
-    });
-    return { ok: true, skillSync };
-  } catch (error: unknown) {
-    return {
-      ok: true,
-      skillSyncError: error instanceof Error ? error.message : String(error),
-    };
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
  }
 }

--- a/packages/mosaic/src/stages/finalize-skills.spec.ts
+++ b/packages/mosaic/src/stages/finalize-skills.spec.ts
@@ -9,7 +9,7 @@
 */

 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, mkdirSync, readlinkSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import type { WizardState } from '../types.js';
@@ -113,40 +113,6 @@ describe('finalizeStage — skill installer', () => {
    );
  }

-  it('auto-registers every canonical skill even when it was added after initial setup', async () => {
-    const claudeHome = join(tmp, '.claude');
-    const previousClaudeHome = process.env['CLAUDE_HOME'];
-    process.env['CLAUDE_HOME'] = claudeHome;
-    mkdirSync(join(tmp, 'skills', 'added-after-setup'), { recursive: true });
-    mkdirSync(join(tmp, 'skills', 'another-new-skill'), { recursive: true });
-
-    try {
-      await finalizeStage(buildPrompter(), makeState(tmp, []), makeConfigService());
-
-      expect(readlinkSync(join(claudeHome, 'skills', 'added-after-setup'))).toBe(
-        join(tmp, 'skills', 'added-after-setup'),
-      );
-      expect(readlinkSync(join(claudeHome, 'skills', 'another-new-skill'))).toBe(
-        join(tmp, 'skills', 'another-new-skill'),
-      );
-    } finally {
-      if (previousClaudeHome === undefined) delete process.env['CLAUDE_HOME'];
-      else process.env['CLAUDE_HOME'] = previousClaudeHome;
-    }
-  });
-
-  it('warns and completes finalization when bridge-wide reconciliation fails', async () => {
-    writeFileSync(join(tmp, 'skills'), 'invalid canonical root\n');
-    const p = buildPrompter();
-
-    await finalizeStage(p, makeState(tmp, []), makeConfigService());
-
-    expect(p.warn).toHaveBeenCalledWith(
-      expect.stringMatching(/Claude skill reconciliation skipped.*not a directory/i),
-    );
-    expect(p.outro).toHaveBeenCalledWith('Mosaic is ready.');
-  });
-
  it('passes MOSAIC_INSTALL_SKILLS with the selected skill list', async () => {
    const state = makeState(tmp, ['brainstorming', 'lint', 'systematic-debugging']);
    const p = buildPrompter();
--- a/packages/mosaic/src/stages/finalize.ts
+++ b/packages/mosaic/src/stages/finalize.ts
@@ -7,11 +7,6 @@ import type { ConfigService } from '../config/config-service.js';
 import type { WizardState } from '../types.js';
 import { getShellProfilePath } from '../platform/detect.js';
 import { ManifestError } from '../framework/manifest.js';
-import {
-  getDefaultSkillPaths,
-  syncClaudeSkills,
-  type SkillSyncResult as ClaudeSkillSyncResult,
-} from '../commands/skill.js';

 function linkRuntimeAssets(mosaicHome: string, skipClaudeHooks: boolean): void {
  const script = join(mosaicHome, 'bin', 'mosaic-link-runtime-assets');
@@ -210,27 +205,7 @@ export async function finalizeStage(
    skillsResult = syncSkills(state.mosaicHome, state.selectedSkills);
  }

-  // 5. Reconcile every canonical Mosaic skill into Claude Code. This is
-  // intentionally independent of the first-run selected-skill fetch above:
-  // framework installs/upgrades must also register skills added after setup.
-  spin.update('Registering Mosaic skills with Claude Code...');
-  let bridgeResult: ClaudeSkillSyncResult = {
-    registered: [],
-    repaired: [],
-    unchanged: [],
-    conflicts: [],
-  };
-  let bridgeFailure: string | undefined;
-  try {
-    bridgeResult = syncClaudeSkills({
-      mosaicSkillsDir: join(state.mosaicHome, 'skills'),
-      claudeSkillsDir: getDefaultSkillPaths().claudeSkillsDir,
-    });
-  } catch (error: unknown) {
-    bridgeFailure = error instanceof Error ? error.message : String(error);
-  }
-
-  // 6. Run doctor
+  // 5. Run doctor
  spin.update('Running health audit...');
  const doctorResult = runDoctor(state.mosaicHome);

@@ -242,15 +217,10 @@ export async function finalizeStage(
    p.warn("Run 'mosaic sync' manually after installation to install skills.");
  }

-  if (bridgeFailure) p.warn(`Claude skill reconciliation skipped: ${bridgeFailure}`);
-  for (const conflict of bridgeResult.conflicts) {
-    p.warn(`Skill registration skipped for ${conflict.name}: ${conflict.reason}`);
-  }
-
-  // 7. PATH setup
+  // 6. PATH setup
  const pathAction = setupPath(state.mosaicHome, p);

-  // 8. Summary
+  // 7. Summary
  const skillsSummary = skillsResult.success
    ? skillsResult.installedCount > 0
      ? `${skillsResult.installedCount.toString()} installed`
@@ -275,7 +245,7 @@ export async function finalizeStage(

  p.note(summary.join('\n'), 'Installation Summary');

-  // 9. Next steps
+  // 8. Next steps
  const nextSteps: string[] = [];
  if (pathAction === 'added') {
    const profilePath = getShellProfilePath();
--- a/packages/mosaic/vitest.config.ts
+++ b/packages/mosaic/vitest.config.ts
@@ -5,16 +5,5 @@ export default defineConfig({
    globals: true,
    environment: 'node',
    testTimeout: 30_000,
-    coverage: {
-      provider: 'v8',
-      include: ['src/commands/skill.ts'],
-      reporter: ['text', 'json-summary'],
-      thresholds: {
-        statements: 85,
-        branches: 85,
-        functions: 85,
-        lines: 85,
-      },
-    },
  },
 });
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -607,9 +607,6 @@ importers:
      '@types/react':
        specifier: ^18.3.0
        version: 18.3.28
-      '@vitest/coverage-v8':
-        specifier: ^2.0.0
-        version: 2.1.9(vitest@2.1.9(@types/node@22.19.15)(jsdom@29.0.0(@noble/hashes@2.0.1))(lightningcss@1.31.1))
      tsx:
        specifier: ^4.0.0
        version: 4.21.0
--- a/tools/install.sh
+++ b/tools/install.sh
@@ -61,38 +61,17 @@ if [[ "${MOSAIC_DEV:-0}" == "1" ]]; then
  FLAG_DEV=true
 fi

-installer_usage() {
-  printf 'Usage: install.sh [--check] [--framework] [--cli] [--ref <branch>] [--dev] [--yes|-y] [--no-auto-launch] [--uninstall]\n' >&2
-}
-
 while [[ $# -gt 0 ]]; do
  case "$1" in
    --check)          FLAG_CHECK=true; shift ;;
    --framework)      FLAG_CLI=false; shift ;;
    --cli)            FLAG_FRAMEWORK=false; shift ;;
-    --ref)
-      if [[ $# -lt 2 ]] || [[ -z "$2" ]]; then
-        printf 'Error: Missing value for --ref\n' >&2
-        installer_usage
-        exit 2
-      fi
-      if [[ "$2" == -* ]]; then
-        printf 'Error: Unknown argument: %s\n' "$2" >&2
-        installer_usage
-        exit 2
-      fi
-      GIT_REF="$2"
-      shift 2
-      ;;
+    --ref)            GIT_REF="${2:-main}"; shift 2 ;;
    --dev)            FLAG_DEV=true; shift ;;
    --yes|-y)         FLAG_YES=true; shift ;;
    --no-auto-launch) FLAG_NO_AUTO_LAUNCH=true; shift ;;
    --uninstall)      FLAG_UNINSTALL=true; shift ;;
-    *)
-      printf 'Error: Unknown argument: %s\n' "$1" >&2
-      installer_usage
-      exit 2
-      ;;
+    *)                shift ;;
  esac
 done

@@ -233,7 +212,7 @@ ok()    { echo "${G}✔${RESET}  $*"; }
 warn()  { echo "${Y}⚠${RESET}  $*"; }
 fail()  { echo "${R}✖${RESET}  $*" >&2; }
 dim()   { echo "${DIM}$*${RESET}"; }
-step()  { printf '\n%s%s%s\n' "$BOLD" "$*" "$RESET"; }
+step()  { echo ""; echo "${BOLD}$*${RESET}"; }

 # ─── helpers ──────────────────────────────────────────────────────────────────