refactor(cli): standardize operational scripts on a shared command runner #237

Problem

Repository-owned operational commands use different patterns for argument handling, environment preflight, working-directory assumptions, signal handling, cleanup, and exit codes. The same failure can therefore behave differently depending on which script is invoked or where it is launched.

Goal

Create a small shared command runner and migrate every first-party operational script and CLI entrypoint to the same lifecycle contract.

Requirements

• Provide a reusable runCommand entrypoint that owns argument validation, environment preflight, cancellation signals, cleanup registration, error-to-exit-code mapping, and final process termination.
• Define stable exit-code categories for usage errors, configuration errors, dependency failures, interrupted execution, and unexpected failures.
• Support --help consistently without triggering network, filesystem, wallet, or contract side effects.
• Propagate one abort signal through asynchronous command work and run registered cleanup exactly once.
• Make repository commands independent of the caller working directory.
• Keep shell launchers thin, strict, path-safe, and responsible only for locating and executing their implementation.
• Migrate all first-party operational scripts, smoke commands, setup tools, checkers, and CLI entrypoints to the shared lifecycle.
• Preserve existing successful command behavior and required output contracts.
• Add tests for help, invalid arguments, missing configuration, interruption, cleanup ordering, exit-code mapping, and launch from an unrelated directory.
• Add a repository check that ensures executable entrypoints use the shared runner or a documented thin-shell pattern.

Acceptance criteria

• Operational commands follow one startup, cancellation, cleanup, and exit-code contract.
• Every command can show help without side effects.
• Commands work when launched outside the repository root.
• Interrupt handling leaves no child process, timer, or temporary resource behind.
• Existing happy-path workflows remain functional.
• New tests, script checks, affected workspace tests and typechecks pass.
• The PR contains no generated output or unrelated command redesign.

Suggested implementation prompt

Implement this issue end to end from the current main branch. Inventory every repository-owned operational script, checker, smoke command, setup tool, shell launcher, and CLI entrypoint. Record its arguments, configuration preflight, side effects, cleanup, signals, outputs, and exit behavior. Build a minimal shared command runner and thin-shell contract, migrate every inventoried entrypoint without changing successful workflows, make launches independent of the current directory, add lifecycle tests and a regression check, run all affected validation, and keep the diff focused.