phase2-migrate-mode-switch: azureclaw migrate mode-switch CLI (Phase 2 S9.1)

[Pal Lakatos-Toth (pallakatos)]

Operator-facing tool to flip a ClawSandbox between the four upstream-compatibility modes that S8 (#57) shipped on the controller side. Drives the day-zero adoption story: take an existing upstream sigs.k8s.io/agent-sandbox Sandbox and bolt AzureClaw governance on without rewriting the YAML.

Real workflow this unlocks

# operator already has an upstream Sandbox CR called 'legacy-agent';
# wraps it with AzureClaw governance:
$ azureclaw migrate to-overlay legacy --upstream-ref legacy-agent
  legacy: native → overlay (upstream sandbox 'legacy-agent')
  ✓ patched

# later: drop the upstream, return to native AzureClaw
$ azureclaw migrate from-overlay legacy
  legacy: overlay → native
  ✓ patched

Subcommands

Command	Effect
migrate to-overlay <name> --upstream-ref <upstream>	OverlayMode (governance overlay only; upstream owns Pod)
migrate from-overlay <name>	Revert to native (controller resumes Pod ownership)
migrate to-translate <name>	SandboxClaim translate mode
migrate to-observe <name>	Status-mirror mode
migrate to-native <name>	Alias for native (off)

All five accept --namespace, --dry-run, --format human|json.

Reuse-first (§0.2 #11)

• No new CRD field, no controller change. OverlayMode reconciler logic shipped in S8 (phase2-overlaymode: sigs/agent-sandbox OverlayMode reconciler branch #57); this is the operator-facing tool that drives it.
• Pure helpers (validateMode, buildModePatch, readCurrentMode, summariseTransition, modeDisplay) — unit-testable without a cluster.
• JSON merge patch (RFC 7396) with explicit null for upstreamSandboxRef removal — matches Option<...>::skip_serializing_if round-trip on the controller side. Asserted directly in tests.

Exit codes (CI-friendly)

• 0 — success or no-op (already in target state)
• 1 — kubectl failure (RBAC, network, missing CR)
• 2 — validation failure (operator typo: missing --upstream-ref, ref on wrong subcommand, etc.)

Pre-flight transition summary

Before applying, the orchestrator runs kubectl get clawsandbox <name> and prints current → target. If already in the target state, it skips the patch as a no-op (JSON: { noop: true }).

Out of scope (S9.2 — follow-up PR)

• azureclaw migrate from-kagent (Solo.io kagent CR → ClawSandbox translator)
• Real azureclaw convert YAML translator (currently exit-3 skeleton)
• migrate verify <name> (consistency check against upstream Sandbox CR)

Verification

• cd cli && npx tsc --noEmit ✅
• cd cli && npm test — 337 passed | 2 skipped (was 315+2; +22 from this slice) ✅
• cd cli && npm run lint ✅ (preexisting warnings only)
• BASE_REF=origin/dev bash ci/no-stubs.sh ✅
• BASE_REF=origin/dev bash ci/no-custom-crypto.sh ✅
• BASE_REF=origin/dev bash ci/check-loc.sh ✅
• End-to-end smoke: node dist/index.js migrate to-overlay demo --upstream-ref legacy --dry-run prints the expected JSON merge patch.

Phase 2 progress on dev after merge: ✅ S1 #51, S2 #52, S3 #53, S4 #54, S5 #55, S6 #56, S8 #57, S11 #59, S11.1 #61, S9.1 (this PR) — 10 of ~14 slices.