Map Ctrl-C to exit code 130 (cancel) instead of 0 (#202)

## Summary

This change establishes a consistent exit code convention for user
interrupts (Ctrl-C / SIGTERM) across all interactive and streaming
commands. Previously, Ctrl-C was treated as a clean success (exit 0),
which made it impossible for callers to distinguish between a normal
completion and an interrupt. Now all Ctrl-C paths exit with code 130
(the conventional Unix "cancelled by SIGINT" code), while maintaining
clean shutdown behavior.

## Key Changes

- **Core interrupt handling**: Added `CANCELLED_EXIT_CODE = 130`
constant in `aai_cli/core/errors.py` as the single source of truth for
cancel exit codes.

- **Telemetry tracking**: Updated `aai_cli/core/telemetry.py` to:
- Map exit code 130 to "cancelled" outcome (distinct from generic
"error")
- Treat raw `KeyboardInterrupt` exceptions as "cancelled" rather than
"internal_error"
  - Preserve the distinction so interrupts don't inflate crash metrics

- **Command execution**: Refactored `aai_cli/app/context.py` to:
  - Extract telemetry/update-check wrapping into `_run_body()` helper
- Catch `KeyboardInterrupt` in `run_command()` and map it to
`typer.Exit(code=130)`
  - Preserve the existing deferred-config path that skips telemetry

- **Interactive commands**: Updated all interactive/streaming commands
to raise `typer.Exit(code=130)` on Ctrl-C instead of returning cleanly:
  - `aai_cli/commands/llm/_exec.py` (follow mode)
  - `aai_cli/commands/dictate/_exec.py`
  - `aai_cli/commands/agent/_exec.py`
  - `aai_cli/commands/agent_cascade/_exec.py`
  - `aai_cli/commands/share/_exec.py`
  - `aai_cli/commands/webhooks/_listen.py`
  - `aai_cli/streaming/session.py` (batch streaming)
  - `aai_cli/init/runner.py` (dev server)

- **Tests**: Updated all test expectations to verify exit code 130 on
Ctrl-C, with clarified comments explaining the cancel semantics.

## Implementation Details

- The change preserves all existing cleanup behavior (renderer closes,
tunnels tear down, etc.) — only the exit code changes.
- Commands with no interactive handler (raw `KeyboardInterrupt` reaching
`run_command`) now exit 130 instead of Click's default exit 1.
- Telemetry correctly identifies 130 as "cancelled" so it doesn't count
toward crash rates.
- The `config path` command (which tolerates unreadable config)
continues to skip telemetry/update-check wrappers as before.
- Callers can now reliably use exit code 130 to detect interrupts in
shell scripts: `assembly stream && next_command` will not run
`next_command` if the user pressed Ctrl-C.

https://claude.ai/code/session_01BRiB7KpAgb833DkxHh5ntc

Co-authored-by: Claude <noreply@anthropic.com>

Author: alexkroman

aai_cli/app/context.py

@@ -7,7 +7,7 @@
 import keyring.errors
 import typer
 
-from aai_cli.core import config, debuglog, env, environments, stdio, telemetry
+from aai_cli.core import config, debuglog, env, environments, errors, stdio, telemetry
 from aai_cli.core.environments import Environment
 from aai_cli.core.errors import APIError, CLIError, NotAuthenticated
 from aai_cli.ui import output, update_check
@@ -196,6 +196,30 @@ def _auto_login_and_exit(state: AppState, *, json_mode: bool) -> NoReturn:
     )
 
 
+def _run_body(
+    ctx: typer.Context,
+    fn: Callable[[AppState, bool], None],
+    *,
+    json_mode: bool,
+    has_deferred: bool,
+) -> None:
+    """Run the command body, wrapped (or not) by the telemetry/update-check machinery.
+
+    Called inside ``run_command``'s ``try`` so telemetry sees the raw CLIError (and its
+    error_type) before it's folded into a ``typer.Exit``. ``config path`` opts into
+    ``has_deferred`` (a corrupt config.toml): it reports a contents-independent location,
+    so it runs just the body and skips the telemetry/update-check wrappers that would
+    re-parse the broken config.
+    """
+    state: AppState = ctx.obj
+    if has_deferred:
+        fn(state, json_mode)
+        return
+    with telemetry.track(ctx.command_path):
+        fn(state, json_mode)
+    update_check.maybe_notify(json_mode=json_mode)
+
+
 def run_command(
     ctx: typer.Context,
     fn: Callable[[AppState, bool], None],
@@ -219,23 +243,20 @@ def run_command(
         # exit, without telemetry/update-check, both of which would just re-parse it.
         _fail(deferred, json_mode=json_mode)
     try:
-        if deferred is not None:
-            # `config path` opted in (tolerate_unreadable_config): it reports a
-            # contents-independent location, so run just the body and skip the
-            # telemetry/update-check wrappers that re-parse the broken config.
-            fn(state, json_mode)
-        else:
-            # Inside the try so telemetry sees the raw CLIError (and its error_type)
-            # before it's folded into a typer.Exit below.
-            with telemetry.track(ctx.command_path):
-                fn(state, json_mode)
-            update_check.maybe_notify(json_mode=json_mode)
+        _run_body(ctx, fn, json_mode=json_mode, has_deferred=deferred is not None)
     except NotAuthenticated as err:
         if not auto_login or not _should_auto_login(err):
             _fail(err, json_mode=json_mode)
         _auto_login_and_exit(state, json_mode=json_mode)
     except CLIError as err:
         _fail(err, json_mode=json_mode)
+    except KeyboardInterrupt:
+        # Ctrl-C (and the SIGTERM that core.signals routes through the same path) is a
+        # cancel, not a crash: exit 130 so `assembly … && next` composes correctly,
+        # instead of the bare "Aborted!" / exit 1 Click would otherwise produce. The
+        # interactive commands print their own "Stopped." before re-raising; this is the
+        # single place the cancel maps to its exit code.
+        raise typer.Exit(code=errors.CANCELLED_EXIT_CODE) from None
     except (typer.Exit, typer.Abort, BrokenPipeError):
         # Deliberate control flow (and the closed-pipe contract handled in main.run);
         # these must reach Click/the entry point untouched.

aai_cli/commands/agent/_exec.py

@@ -22,7 +22,7 @@
 from aai_cli.agent.voices import VOICE_NAMES
 from aai_cli.app.agent_shared import resolve_system_prompt as _resolve_system_prompt
 from aai_cli.app.context import AppState
-from aai_cli.core import choices, client, signals
+from aai_cli.core import choices, client, errors, signals
 from aai_cli.core.errors import UsageError
 from aai_cli.streaming.session import resolve_output_modes
 from aai_cli.streaming.sources import FileSource
@@ -135,7 +135,10 @@ def run_agent(opts: AgentOptions, state: AppState, *, json_mode: bool) -> None:
         with signals.terminate_as_interrupt():
             run_session(api_key, renderer=renderer, player=player, mic=audio, config=run_config)
     except KeyboardInterrupt:
+        # Ctrl-C (or a supervisor's SIGTERM) ends the session cleanly, then exits 130
+        # (cancel) so the interrupt isn't reported to a caller as success.
         renderer.stopped()
+        raise typer.Exit(code=errors.CANCELLED_EXIT_CODE) from None
     except BrokenPipeError as exc:
         # Downstream consumer (e.g. `| head`) closed the pipe; stop quietly.
         raise typer.Exit(code=0) from exc

aai_cli/commands/agent_cascade/_exec.py

@@ -22,7 +22,7 @@
 from aai_cli.agent_cascade.config import DEFAULT_MAX_HISTORY, CascadeConfig
 from aai_cli.app.agent_shared import resolve_system_prompt as _resolve_system_prompt
 from aai_cli.app.context import AppState
-from aai_cli.core import choices, client, config_builder, llm, signals
+from aai_cli.core import choices, client, config_builder, errors, llm, signals
 from aai_cli.core.errors import UsageError
 from aai_cli.streaming import turn_presets
 from aai_cli.streaming.session import resolve_output_modes
@@ -218,7 +218,10 @@ def run_agent_cascade(opts: AgentCascadeOptions, state: AppState, *, json_mode:
         with signals.terminate_as_interrupt():
             engine.run_cascade(renderer=renderer, player=player, config=config, deps=deps)
     except KeyboardInterrupt:
+        # Ctrl-C (or a supervisor's SIGTERM) ends the cascade cleanly, then exits 130
+        # (cancel) so the interrupt isn't reported to a caller as success.
         renderer.stopped()
+        raise typer.Exit(code=errors.CANCELLED_EXIT_CODE) from None
     except BrokenPipeError as exc:
         # Downstream consumer (e.g. `| head`) closed the pipe; stop quietly.
         raise typer.Exit(code=0) from exc

aai_cli/commands/dictate/_exec.py

@@ -12,8 +12,10 @@
 
 from dataclasses import dataclass
 
+import typer
+
 from aai_cli.app.context import AppState
-from aai_cli.core import choices, stdio, sync_stt
+from aai_cli.core import choices, errors, stdio, sync_stt
 from aai_cli.core.config_builder import split_csv
 from aai_cli.core.hotkey import CTRL_C, CTRL_D, ESC, TerminalKeys
 from aai_cli.core.microphone import MicrophoneSource
@@ -222,5 +224,7 @@ def run_dictate(opts: DictateOptions, state: AppState, *, json_mode: bool) -> No
                 )
             _session(keys, api_key, opts, state, json_mode=json_mode, single=single)
     except KeyboardInterrupt:
-        # Ctrl-C is the normal "done dictating" signal: end cleanly, not as an error.
-        return
+        # Ctrl-C cancels dictation, so it exits 130 (cancel) — distinct from `q`, which
+        # ends the session normally (exit 0). The with-block above already restored the
+        # terminal on the way out.
+        raise typer.Exit(code=errors.CANCELLED_EXIT_CODE) from None

aai_cli/commands/llm/_exec.py

@@ -12,10 +12,11 @@
 from dataclasses import dataclass
 from pathlib import Path
 
+import typer
 from rich.markup import escape
 
 from aai_cli.app.context import AppState
-from aai_cli.core import choices, client, stdio
+from aai_cli.core import choices, client, errors, stdio
 from aai_cli.core import llm as gateway
 from aai_cli.core.errors import UsageError
 from aai_cli.ui import output
@@ -161,16 +162,16 @@ def ask(transcript_text: str) -> str:
         return gateway.content_of(response)
 
     transcript: list[str] = []
-    interrupted = False
     with FollowRenderer(json_mode=json_mode) as render:
-        # Ctrl-C is the normal "stop watching" signal -> exit cleanly (code 0).
+        # Ctrl-C is the normal "stop watching" signal: exit 130 (cancel) rather than
+        # masquerading as a clean finish — the renderer's panel closes on the way out.
         try:
             for turn in stdio.iter_piped_stdin_lines():
                 transcript.append(turn)
                 render(ask("\n".join(transcript)), len(transcript))
         except KeyboardInterrupt:
-            interrupted = True
-    if not transcript and not interrupted:
+            raise typer.Exit(code=errors.CANCELLED_EXIT_CODE) from None
+    if not transcript:
         # An empty pipe (`assembly llm -f "…" </dev/null`) would otherwise exit 0
         # silently, having asked nothing.
         raise UsageError(_FOLLOW_STDIN_MESSAGE)

aai_cli/commands/share/_exec.py

@@ -16,6 +16,7 @@
 
 from aai_cli.app.context import AppState
 from aai_cli.core import env as os_env
+from aai_cli.core import errors
 from aai_cli.core.errors import CLIError
 from aai_cli.init import devserver, procfile, runner, tunnel
 from aai_cli.ui import output, steps
@@ -86,9 +87,9 @@ def run_share(opts: ShareOptions, state: AppState, *, json_mode: bool) -> None:
         output.emit(payload, _render_share, json_mode=json_mode)
         server.wait()
     except KeyboardInterrupt:
-        # Ctrl-C is the expected way to stop a foreground share; the finally
-        # block below tears down the tunnel and server.
-        pass
+        # Ctrl-C is the expected way to stop a foreground share: tear down (finally,
+        # below) then exit 130 (cancel) so it isn't reported to a caller as success.
+        raise typer.Exit(code=errors.CANCELLED_EXIT_CODE) from None
     finally:
         tunnel.terminate(proxy)
         tunnel.terminate(server)

aai_cli/commands/webhooks/_listen.py

@@ -10,7 +10,6 @@
 
 from __future__ import annotations
 
-import contextlib
 import json
 import threading
 from collections.abc import Callable
@@ -180,9 +179,10 @@ def run_listen(opts: ListenOptions, *, json_mode: bool) -> None:
                     "check it for errors.",
                 )
         _announce(public_url, port, json_mode=json_mode)
-        # Ctrl-C is the expected way to stop a foreground listener.
-        with contextlib.suppress(KeyboardInterrupt):
-            server.serve_forever()
+        # Ctrl-C is the expected way to stop a foreground listener; let it propagate so
+        # the command exits 130 (cancel). The finally below still closes the socket and
+        # tears down the tunnel.
+        server.serve_forever()
     finally:
         # Close here, not via `with server:` — a tunnel failure raises before the
         # serve block, and the bound listening socket must not outlive the command.

aai_cli/core/errors.py

@@ -21,6 +21,12 @@
 
 from aai_cli.core import jsonshape
 
+# The conventional Unix "cancelled by Ctrl-C" code (128 + SIGINT). Not a CLIError
+# exit_code — a cancel isn't a failure with a machine-readable error type — but the
+# single source of truth scripts can rely on for "the user (or a supervisor's SIGTERM,
+# routed through the same clean-stop path) interrupted the command".
+CANCELLED_EXIT_CODE = 130
+
 
 class CLIError(Exception):
     """Base error carrying an exit code, a machine-readable type, and an optional

aai_cli/core/signals.py

@@ -2,8 +2,8 @@
 
 `stream` (and the other realtime commands) treat Ctrl-C as a clean "user stopped"
 signal: SIGINT arrives as a ``KeyboardInterrupt`` that the streaming lifecycle catches
-to flush its closing state and exit 0. This module lets an *external* stop reach that
-same path — see ``terminate_as_interrupt``.
+to flush its closing state and exit 130 (the cancel code). This module lets an
+*external* stop reach that same path — see ``terminate_as_interrupt``.
 """
 
 from __future__ import annotations

aai_cli/core/telemetry.py

@@ -26,7 +26,7 @@
 import typer
 
 from aai_cli import __version__
-from aai_cli.core import argscan, config, env, procs
+from aai_cli.core import argscan, config, env, errors, procs
 from aai_cli.core.errors import CLIError
 
 ENV_DISABLED = "AAI_TELEMETRY_DISABLED"
@@ -236,14 +236,25 @@ def _safe_dispatch(
         return
 
 
+def _exit_outcome(code: int) -> str:
+    """Map a ``typer.Exit`` code to a telemetry outcome: 0 succeeds, 130 is a cancel
+    (the Ctrl-C path that exits via ``typer.Exit``), anything else is an error."""
+    if code == 0:
+        return "success"
+    if code == errors.CANCELLED_EXIT_CODE:
+        return "cancelled"
+    return "error"
+
+
 @contextmanager
 def track(command: str) -> Generator[None]:
     """Record one command run, deriving the outcome from whatever escapes the body.
 
     CLIErrors keep their machine-readable ``error_type`` as the outcome; a
-    deliberate ``typer.Exit`` maps through its code; anything else is the
-    catch-all ``internal_error``. The body's exception always re-raises —
-    tracking observes control flow, never alters it.
+    deliberate ``typer.Exit`` maps through its code (a 130 reads as ``cancelled``);
+    a Ctrl-C is ``cancelled``; anything else is the catch-all ``internal_error``.
+    The body's exception always re-raises — tracking observes control flow, never
+    alters it.
     """
     if not is_enabled():
         yield
@@ -263,8 +274,13 @@ def track(command: str) -> Generator[None]:
         raise
     except typer.Exit as exc:
         code = exc.exit_code
-        outcome = "success" if code == 0 else "error"
-        _safe_dispatch(command, started, outcome=outcome, exit_code=code)
+        _safe_dispatch(command, started, outcome=_exit_outcome(code), exit_code=code)
+        raise
+    except KeyboardInterrupt:
+        # A Ctrl-C that reached here (a command with no interactive handler) is a
+        # cancel, not an internal_error — record it as such so it doesn't inflate the
+        # crash rate, then let run_command map it to exit 130.
+        _safe_dispatch(command, started, outcome="cancelled", exit_code=errors.CANCELLED_EXIT_CODE)
         raise
     except BaseException as exc:
         _safe_dispatch(