Handle headless signals as graceful cancellation

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Compatibility
+
+- **NDJSON v1 terminal reasons are an open set** — `session_error.reason` now includes `interrupted` for `SIGINT` and `terminated` for `SIGTERM`, and `code` may contain the conventional signal-derived exit code (`130` or `143`). Schema v1 consumers should treat unknown event types, fields, and enum-like string values as forward-compatible additions.
+
 ## 0.3.2 (2026-04-11)
 
 ### Fixes

EVENTS.md

@@ -155,7 +155,7 @@ Emitted once when the session ends (success or failure).
 
 > **Deprecated in v1.** Prefer the structured `session_error` event for new consumers. `session_complete.error` remains populated for back-compat and will be removed in a future schema version.
 >
-> Note: `session_error` is only emitted when the session terminates abnormally (provider/auth/rate-limit/timeout/OOM). Non-fatal errors that accumulate during an otherwise-successful run surface as individual `error` events and may also appear concatenated in `session_complete.error` without a preceding `session_error`. Alerting logic should key on `session_error`, not on `session_complete.error`.
+> Note: `session_error` is only emitted when the session terminates abnormally (provider/auth/rate-limit/timeout/OOM/interruption/termination). Non-fatal errors that accumulate during an otherwise-successful run surface as individual `error` events and may also appear concatenated in `session_complete.error` without a preceding `session_error`. Alerting logic should key on `session_error`, not on `session_complete.error`.
 
 ### `session_error`
 
@@ -170,8 +170,8 @@ Emitted immediately before `session_complete` when the session terminates abnorm
 }
 ```
 
-- `reason` (string, **required**) — one of `rate_limit`, `auth`, `timeout`, `oom`, `provider`, `unknown`.
-- `code` (string, optional) — provider HTTP status code or error code when available.
+- `reason` (string, **required**) — one of `rate_limit`, `auth`, `timeout`, `oom`, `provider`, `interrupted`, `terminated`, `unknown`. `SIGINT` produces `interrupted`; `SIGTERM` produces `terminated`. Signals are not inferred to be timeouts.
+- `code` (string, optional) — provider HTTP status code, error code, or conventional signal-derived exit code (`130` for `SIGINT`, `143` for `SIGTERM`) when available.
 - `message` (string, **required**) — human-readable error message.
 
 ## Message Events

packages/cli/src/cli/cmd/run.errors.ts

@@ -1,6 +1,14 @@
 export const SCHEMA_VERSION = "1"
 
-export type SessionErrorReason = "rate_limit" | "auth" | "timeout" | "oom" | "provider" | "unknown"
+export type SessionErrorReason =
+  | "rate_limit"
+  | "auth"
+  | "timeout"
+  | "oom"
+  | "provider"
+  | "interrupted"
+  | "terminated"
+  | "unknown"
 
 export type ClassifiedSessionError = {
   reason: SessionErrorReason

packages/cli/src/cli/cmd/run.terminal.ts

@@ -0,0 +1,21 @@
+type Emit = (type: string, data: Record<string, unknown>) => unknown
+
+export function terminal(emit: Emit) {
+  const state = {
+    complete: false,
+    error: false,
+  }
+
+  return {
+    complete(data: Record<string, unknown>) {
+      if (state.complete) return
+      state.complete = true
+      emit("session_complete", data)
+    },
+    error(data: Record<string, unknown>) {
+      if (state.complete || state.error) return
+      state.error = true
+      emit("session_error", data)
+    },
+  }
+}

packages/cli/src/cli/cmd/run.ts

@@ -4,6 +4,7 @@ import { pathToFileURL } from "bun"
 import { UI } from "../ui"
 import { cmd } from "./cmd"
 import { classifySessionError, SCHEMA_VERSION } from "./run.errors"
+import { terminal } from "./run.terminal"
 import { buildToolCatalogItems } from "./tool-catalog"
 import { withTimeout } from "../../util/timeout"
 import { Flag } from "../../flag/flag"
@@ -37,7 +38,10 @@ import { SkillTool } from "../../tool/skill"
 import { BashTool } from "../../tool/bash"
 import { TodoWriteTool } from "../../tool/todo"
 import { Locale } from "../../util/locale"
+import { Log } from "../../util/log"
+import { Shutdown } from "../shutdown"
 import { Stdout } from "../stdout"
+import { attempt, signals, type Signals } from "../signals"
 import { createRunInvocation } from "./run.invocation"
 
 type ToolProps<T extends Tool.Info> = {
@@ -534,11 +538,6 @@ export const RunCommand = cmd({
 
       const events = await sdk.event.subscribe()
       let error: string | undefined
-      // Guard: at most one session_error is emitted per run regardless of which
-      // failure path fires first (in-loop session.error handler, loopDone.catch,
-      // or promptResult rejection). Without this a mid-run session.error event
-      // can fire site 1 while promptResult/loop() also rejects and fires site 2/3.
-      let sessionErrorEmitted = false
       const startTime = Date.now()
       const childSessions = new Set<string>()
       const emitted = new Set<string>()
@@ -549,6 +548,20 @@ export const RunCommand = cmd({
         return n
       }
 
+      // Keep every failure path on one ordered, idempotent terminal lifecycle.
+      const output = terminal(emit)
+
+      function complete(message = error ?? null) {
+        output.complete({
+          durationMs: Date.now() - startTime,
+          error: message,
+        })
+      }
+
+      function report(reason: string, code: string | undefined, message: string) {
+        output.error({ reason, code, message })
+      }
+
       async function loop() {
         const toggles = new Map<string, boolean>()
 
@@ -695,22 +708,13 @@ export const RunCommand = cmd({
               // to a non-zero exit code so CI wrappers see the failure instead of a
               // spuriously-green job. process.exitCode (not process.exit) lets the
               // loop drain to session.status idle and emit session_complete first.
-              process.exitCode = 1
+              if (!control.current) process.exitCode = 1
               invocation.error(props.error)
-              if (!sessionErrorEmitted) {
-                sessionErrorEmitted = true
-                const classified = classifySessionError(props.error)
-                // Structured session_error (classified reason/code/message) is emitted for the
-                // primary session only. The generic "error" event below fires for both primary
-                // and child-session failures and carries the raw error object — these are
-                // intentionally distinct channels: session_error is for structured telemetry/CI
-                // consumers, "error" is the legacy observable for raw error pass-through.
-                emit("session_error", {
-                  reason: classified.reason,
-                  code: classified.code,
-                  message: classified.message,
-                })
-              }
+              const classified = classifySessionError(props.error)
+              // Structured session_error is the telemetry/CI channel for the
+              // primary session. The legacy "error" event below is the raw
+              // pass-through for both primary and child-session failures.
+              report(classified.reason, classified.code, classified.message)
             }
             if (emit("error", { error: props.error, sourceSessionID: props.sessionID })) continue
             UI.error(err)
@@ -845,6 +849,48 @@ export const RunCommand = cmd({
         permissions: PermissionNext.merge(agentInfo.permission, rules),
       })
 
+      let aborted = false
+      function abort() {
+        if (aborted) return
+        aborted = true
+        attempt(
+          () => sdk.session.abort({ sessionID }),
+          () => Log.Default.error("session abort failed"),
+        )
+      }
+
+      function interrupt(signal: Signals.Info) {
+        error ??= signal.message
+        invocation.error(signal.message)
+        report(signal.reason, String(signal.code), signal.message)
+        abort()
+      }
+
+      async function expire(signal: Signals.Info) {
+        complete(error ?? signal.message)
+        await invocation.abort(signal.message)
+        await Shutdown.flush()
+      }
+
+      using control = signals(interrupt, 5_000, expire)
+
+      function reject(cause: unknown) {
+        const classified = classifySessionError(cause)
+        error ??= classified.message
+        invocation.error(cause)
+        report(classified.reason, classified.code, classified.message)
+        complete(error)
+        if (control.current) {
+          Log.Default.error("run failed after signal", {
+            reason: classified.reason,
+            code: classified.code,
+          })
+          return
+        }
+        console.error(cause)
+        process.exitCode = 1
+      }
+
       // Emit the resolved tool catalog (builtin + MCP tools) and available
       // skills before the first model turn. Enables structural detection of
       // "tool was not exposed" failure modes (issue #85).
@@ -873,31 +919,13 @@ export const RunCommand = cmd({
           })
       }
 
-      const loopDone = loop()
-        .then(() => {
-          emit("session_complete", {
-            durationMs: Date.now() - startTime,
-            error: error ?? null,
-          })
-        })
-        .catch((e) => {
-          const classified = classifySessionError(e)
-          if (!sessionErrorEmitted) {
-            sessionErrorEmitted = true
-            emit("session_error", {
-              reason: classified.reason,
-              code: classified.code,
-              message: classified.message,
-            })
-          }
-          emit("session_complete", {
-            durationMs: Date.now() - startTime,
-            error: classified.message,
-          })
-          console.error(e)
-          process.exitCode = 1
-          invocation.error(e)
-        })
+      const loopDone = loop().then(() => complete(), reject)
+
+      if (control.current) {
+        await loopDone
+        await Shutdown.flush()
+        return
+      }
 
       if (args.command) {
         await sdk.session.command({
@@ -924,33 +952,8 @@ export const RunCommand = cmd({
       // (e.g., Session.get() fails, model not found), no session.status idle event
       // is emitted, so loopDone would hang forever. Racing ensures we surface
       // the error and exit.
-      await Promise.race([
-        loopDone,
-        promptResult.then(
-          // If prompt resolves normally, wait for the event loop to finish
-          () => loopDone,
-          // If prompt rejects, surface the error immediately
-          (e) => {
-            const classified = classifySessionError(e)
-            error = error ? error + EOL + classified.message : classified.message
-            if (!sessionErrorEmitted) {
-              sessionErrorEmitted = true
-              emit("session_error", {
-                reason: classified.reason,
-                code: classified.code,
-                message: classified.message,
-              })
-            }
-            emit("session_complete", {
-              durationMs: Date.now() - startTime,
-              error: classified.message,
-            })
-            console.error(e)
-            process.exitCode = 1
-            invocation.error(e)
-          },
-        ),
-      ])
+      await Promise.race([loopDone, promptResult.then(() => loopDone, reject)])
+      await Shutdown.flush()
     }
 
     invocation.phase("bootstrap")
@@ -983,6 +986,9 @@ export const RunCommand = cmd({
             const share = await Session.share(opts.sessionID)
             return { data: { share } }
           },
+          abort(opts: any) {
+            return SessionPrompt.cancel(opts.sessionID)
+          },
           async prompt(opts: any) {
             promptResult = SessionPrompt.prompt({
               sessionID: opts.sessionID,

packages/cli/src/cli/shutdown.ts

@@ -7,7 +7,7 @@ export namespace Shutdown {
       Log.Default.error("stdout flush failed", {
         error: error instanceof Error ? error.message : error,
       })
-      process.exitCode = 1
+      process.exitCode ||= 1
     })
   }
 }

packages/cli/src/cli/signals.ts

@@ -0,0 +1,83 @@
+export namespace Signals {
+  export type Info = {
+    name: "SIGINT" | "SIGTERM"
+    reason: "interrupted" | "terminated"
+    code: 130 | 143
+    message: string
+  }
+}
+
+const info = {
+  SIGINT: {
+    name: "SIGINT",
+    reason: "interrupted",
+    code: 130,
+    message: "Session interrupted by SIGINT",
+  },
+  SIGTERM: {
+    name: "SIGTERM",
+    reason: "terminated",
+    code: 143,
+    message: "Session terminated by SIGTERM",
+  },
+} as const satisfies Record<Signals.Info["name"], Signals.Info>
+
+export function attempt(run: () => unknown, fail: () => void) {
+  Promise.resolve().then(run).catch(fail)
+}
+
+export function signals(stop: (info: Signals.Info) => void, grace = 5_000, expire?: (info: Signals.Info) => unknown) {
+  const state: {
+    current?: Signals.Info
+    timer?: ReturnType<typeof setTimeout>
+    hard?: ReturnType<typeof setTimeout>
+    resolve?: (info: Signals.Info) => void
+  } = {}
+  const received = new Promise<Signals.Info>((resolve) => {
+    state.resolve = resolve
+  })
+
+  function handle(name: Signals.Info["name"]) {
+    const signal = info[name]
+    if (state.current) {
+      process.exit(state.current.code)
+    }
+    state.current = signal
+    process.exitCode = signal.code
+    state.timer = setTimeout(() => {
+      state.hard = setTimeout(() => process.exit(signal.code), 250)
+      Promise.resolve()
+        .then(() => expire?.(signal))
+        .then(
+          () => {
+            if (state.hard) clearTimeout(state.hard)
+            process.exit(signal.code)
+          },
+          () => process.exit(signal.code),
+        )
+    }, grace)
+    stop(signal)
+    state.resolve?.(signal)
+  }
+
+  const sigint = () => handle("SIGINT")
+  const sigterm = () => handle("SIGTERM")
+  process.on("SIGINT", sigint)
+  process.on("SIGTERM", sigterm)
+
+  const dispose = () => {
+    if (state.timer) clearTimeout(state.timer)
+    if (state.hard) clearTimeout(state.hard)
+    process.off("SIGINT", sigint)
+    process.off("SIGTERM", sigterm)
+  }
+
+  return {
+    received,
+    get current() {
+      return state.current
+    },
+    dispose,
+    [Symbol.dispose]: dispose,
+  }
+}

packages/cli/test/cli/fixture/stdout.ts

@@ -6,6 +6,7 @@ if (process.argv.includes("--shutdown-error")) {
   Stdout.write("")
   await Stdout.flush()
   process.stdout.emit("error", Object.assign(new Error("broken stdout"), { code: "EIO" }))
+  if (process.argv.includes("--signal-exit")) process.exitCode = 143
   await Shutdown.flush()
   const status = process.argv.find((arg) => arg.startsWith("--status="))?.slice("--status=".length)
   if (status) await Bun.write(status, String(process.exitCode))