GeezerVison

First slice of the planned v4.0 breaking CLI cleanup.

What changed

unlock subcommand removed — folded into repair

repair now deletes the leftover .socket/apply.lock as its final housekeeping step, on every completion path including repair_failed — after releasing its own guard, skipped under --dry-run. A live holder still makes repair refuse up front with lock_held / exit 1: it never steals a lock.

Why the fold is safe: a leftover lock file from a crashed run never blocked acquisition in the first place — the kernel releases a dead process's advisory lock along with its file handle, so Held always means a live process. unlock's inspect path had no recovery scenario, and its --release deletion is now automatic. Gone with it: SOCKET_UNLOCK_RELEASE, Command::Unlock in the JSON envelope, and the patch_unlocked/patch_unlock_failed telemetry events. socket-patch unlock now exits 2 (unknown command), pinned by unlock_subcommand_is_removed.

Global --break-lock / SOCKET_BREAK_LOCK removed

It never stole a live holder's lock (deliberately — that defeats mutual exclusion), and stale files never contend, so its only effect was a lock_broken audit event for a reclaim that plain acquisition performs anyway.

• acquire_or_emit returns the core LockGuard directly (no LockAcquired/broke_lock, no unused silent param); the lock_broken event and record_lock_broken helper are gone.
• The lock_held human hint is now: "Wait for it to finish, or retry with --lock-timeout to wait for the lock." It deliberately doesn't point at repair (which also refuses live holders) or at stale files (which never block).
• rollback's JSON warnings[] stays present in the shape (consumer contract) but is now always empty.
• The never-unlink-while-live invariant survives, stress-pinned by the repurposed acquire_or_emit_preserves_mutual_exclusion hammer test; acquire_or_emit_reclaims_stale_leftover_file pins the kernel-releases-dead-locks fact that justified the removal.

--help reordered to workflow-first

scan, apply, vex, vendor, setup, then rollback, get, list, remove, repair — mirrored in the dispatch match, envelope Command enum, CLI_CONTRACT.md table, and the README command sections.

Migration

• unlock --release → repair
• "is anything holding the lock?" probe → run the mutating command (optionally with --lock-timeout) and branch on errorCode: lock_held
• SOCKET_BREAK_LOCK=… / --break-lock → delete; stale locks self-heal

Docs & versioning

README, CLI_CONTRACT.md (subcommand table, global/local arg tables, env-var tables, envelope union, dry-run & exit-code prose) and CHANGELOG [Unreleased] updated with the breaking notes. The scripts/version-sync.sh 4.0.0 bump is deferred so it can be batched with the remaining planned breaking changes.

Verification

• Full workspace suite green (~2200 tests), including 5 new repair_invariants.rs lock-cleanup tests (leftover deleted on success/failure, probe-created file cleaned, --dry-run preserves, live holder refused + file kept) and a no-.socket-conjured guard.
• One unrelated flake: crawler_npm_e2e::read_package_json_rejects_fifo_without_hanging failed once on mkfifo spawn under full-suite parallelism; passes in isolation and on its full binary.
• cargo clippy --workspace --all-targets: no new warnings (one pre-existing single_match in untouched vendor test code).
• Smoke: --help renders the new order; socket-patch unlock → InvalidSubcommand, exit 2.

🤖 Generated with Claude Code