CLI Incident Toggle Contract (CLI-OBS-12-001)

Audience: CLI developers and operators who run Stella Ops during an incident. Scope: The deterministic CLI flag and configuration surface used to enter and exit incident mode, and the telemetry behaviour that mode changes.

Incident mode temporarily raises telemetry fidelity (full sampling, an incident=true tag, faster flushes) so operators capture maximal evidence while a problem is live. This contract defines how the mode is toggled, persisted, and expired so the behaviour stays predictable across hosts and offline deployments.

Flags and config

CLI flag: --incident-mode (bool). Defaults to false.
Config keys: Telemetry:Incident:Enabled (bool) and Telemetry:Incident:TTL (TimeSpan).
When both the flag and config are specified, the flag wins. The toggle is opt-in only: if config enables incident mode and the flag is present, the flag cannot disable it.

Effects when enabled

Raise the sampling-rate ceiling to 100% for telemetry within the process.
Add the tag incident=true to logs, metrics, and traces.
Shorten the exporter/reporting flush interval to 5s; disable external exporters when Sealed=true.
Emit the activation audit event telemetry.incident.activated with fields {tenant, actor, source, expires_at}.

Persistence

The incident flag’s runtime value is stored in the local state file ~/.stellaops/incident-mode.json, with fields {enabled, set_at, expires_at, actor}, so the mode survives restarts in offline deployments.
The file is tenant-scoped, with permissions 0600.

Expiry / TTL

Default TTL: 30 minutes, unless Telemetry:Incident:TTL is provided.
On expiry, emit the telemetry.incident.expired audit event.

Validation expectations

The CLI refuses --incident-mode when --sealed is set and external exporters are configured; exporters must be dropped first.
Unit tests cover precedence (flag over config), TTL expiry, state-file permissions, and audit emissions.