feat(observability): investigate numeric logging verbosity

[elezar]

Problem Statement\n\nOpenShell exposes incompatible logging controls: the openshell CLI uses repeated -v, while gateway, sandbox, and credential-driver processes use named log_level values and RUST_LOG directives. Operators who use cloud-native tools such as kubectl expect numeric verbosity, but numeric detail does not map one-to-one to Rust's five severity levels.\n\n## Technical Context\n\nOpenShell already standardizes on the Rust tracing ecosystem. Its structured events and spans are retained through tracing_subscriber EnvFilter. The CLI maps -v counts to warn/info/debug/trace; service executables accept named strings and allow RUST_LOG to override their configured defaults. Sandbox launch specifications propagate a named log_level from the gateway.\n\n## Affected Components\n\n| Component | Key files | Role |\n|---|---|---|\n| CLI | crates/openshell-cli/src/main.rs; src/ssh.rs | Parses -v, installs subscriber, maps verbosity to OpenSSH. |\n| Gateway | crates/openshell-server/src/cli.rs; config_file.rs; tracing_setup.rs | Owns config precedence, OTLP, and in-process driver tracing. |\n| Sandbox | crates/openshell-sandbox/src/main.rs | Configures stderr/file/OCSF/log-push layers. |\n| Sandbox API | crates/openshell-server/src/grpc/{sandbox,validation}.rs; proto/ | Carries and validates SandboxSpec.log_level. |\n| Credential drivers | crates/openshell-driver-{vault,kubernetes-secrets}/src/main.rs | Independently consume OPENSHELL_LOG_LEVEL. |\n| Docs/tests | docs/reference/gateway-config.mdx and logging tests | Document current behaviour. |\n\n## Technical Investigation\n\n### Current behavior\n\n- Cli::verbose is a global Clap ArgAction::Count field at crates/openshell-cli/src/main.rs:467. Startup maps 0/1/2/3+ to warn/info/debug/trace at lines 2401-2418; explicit RUST_LOG wins.\n- The same count controls OpenSSH: ERROR at 0, INFO at 1, DEBUG at 2+ (main.rs:2420-2437; ssh.rs:168-176).\n- Gateway --log-level and OPENSHELL_LOG_LEVEL accept named levels (crates/openshell-server/src/cli.rs:80-82); TOML sets the value only when the CLI argument is defaulted (lines 695-699). Its subscriber uses RUST_LOG first, then configured log_level (lines 520-527).\n- Sandbox --log-level defaults to warn and accepts named levels (crates/openshell-sandbox/src/main.rs:157-159); RUST_LOG also wins (lines 572-573). The file layer has an independent fixed info filter (line 609), while OCSF JSONL and log-push are separate layers.\n- Gateway configuration documents named log_level = info values (docs/reference/gateway-config.mdx:79). Vault and Kubernetes-Secrets credential drivers independently expose the named environment variable.\n\n### Proposed direction\n\nKeep tracing and its native severity levels as the internal event model. Add one documented numeric verbosity contract at OpenShell process boundaries, modelled after Kubernetes -v=N: increasing values enable more normal diagnostic detail while warnings/errors remain visible. Retain RUST_LOG as the highest-precedence expert escape hatch for target-level filtering.\n\nDefine semantics before implementation: whether to support -v=N only, retain repeated -vv as an alias, and whether persistent config/environment variables receive a numeric replacement or accept both forms during a transition. State how a selected value affects stderr, files, OCSF JSONL, streamed logs, OTLP, and OpenSSH child processes.\n\n### Alternatives\n\n1. Keep the current CLI-only count and document it: low risk, but inconsistent controls remain.\n2. Make numeric values simple aliases for warn/info/debug/trace: easy, but not truly kubectl-like.\n3. Define application diagnostic bands (recommended): severity remains meaningful and additional detail is emitted/selected at numeric bands. This requires auditing event placement and layers.\n4. Adopt klog/logr or slog: not recommended because tracing is already used throughout OpenShell for structured spans and OpenTelemetry.\n\n## Scope Assessment\n\n- Complexity: High\n- Confidence: Medium\n- Estimated files to change: 20+ across CLI, gateway, sandbox, proto/config, child drivers, tests, and docs.\n- Issue type: feat\n\n## Risks & Open Questions\n\n- Decide the public numeric contract. Kubernetes uses -v=0 for normal operation and increasing diagnostic verbosity; Rust only has five standard severities.\n- Decide whether all binaries and remote sandbox workloads participate initially or whether the work starts with CLI/gateway.\n- Preserve compatibility for named log_level config, OPENSHELL_LOG_LEVEL, and SandboxSpec.log_level.\n- Ensure sandbox file, OCSF JSONL, and pushed-log layers do not silently diverge from the public numeric setting.\n- Do not invent a Kubernetes-style per-file vmodule initially: RUST_LOG=target=level is idiomatic Rust target filtering.\n- No LSM-sensitive path is involved; this is filtering/configuration only.\n\n## Test Considerations\n\n- Cover -v=N, repeated -vv compatibility if retained, defaults, invalid values, and RUST_LOG precedence.\n- Cover gateway CLI/environment/TOML precedence and sandbox-spec propagation.\n- Integration-test stderr, file, OCSF, and pushed-log filters.\n- Update docs/reference/gateway-config.mdx for any changed TOML field/default and update CLI/sandbox operational docs.\n\n## Disposition Readiness\n\n- State: state:validated\n- Assessment: The codebase and compatibility boundaries are understood well enough for a human accept/decline decision.\n- Missing evidence: None for disposition; the semantic choices above require human direction during planning.\n\n---\nCreated by spike investigation. A human should accept, decline, or roadmap this issue before implementation.