Epic: Make headless NDJSON lifecycle and usage telemetry reliable

[byapparov]

Goal

Make headless NDJSON output durable, complete, and semantically explicit across successful runs, provider failures, validation failures, cancellation, and shutdown.

This tracker replaces the original combined diagnosis. The original report identified several valid reliability gaps, but local testing did not reproduce the claim that small fast-failure output is commonly lost by immediate process.exit(): Bun 1.3.10 preserved piped writes through 64 KiB in repeated tests and truncated a 1 MiB immediate-exit write at 64 KiB. Output flushing is still required, but its share of production null telemetry remains unproven.

The live z.ai test also established that thinking mode returns standard OpenAI-shaped usage and is not a source of missing usage.

Workstreams

• Fix NDJSON backpressure and shutdown flushing #91 — NDJSON backpressure and shutdown flushing
• Handle SIGTERM and SIGINT as graceful headless cancellation #94 — Graceful SIGTERM/SIGINT cancellation
• Add NDJSON invocation lifecycle events before session creation #90 — Invocation lifecycle before session creation
• Preserve unknown usage on failed headless turns #93 — Explicit missing/partial usage on terminal turns
• bug: duplicate message_complete events in NDJSON output (--format json) #45 — Deduplicate message_complete and use stable message identity
• Add model stream idle-timeout handling #80 — Add deliberate provider stream idle-timeout handling

Explicitly Rejected Assumptions

• Forced exit is not currently proven to explain the majority of empty production streams.
• SIGTERM must not automatically be labeled as a timeout.
• session_start must not be emitted before a real session exists.
• Tokens must not be blindly accumulated across finish-step events without a reproduction proving that multiple events belong to one assistant message.
• Missing usage must not be represented as a known zero.

Completion Criteria

• Every supported headless lifecycle has an explicit event contract.
• Output accepted by the NDJSON writer is flushed during controlled shutdown.
• Message terminal events are unique and scoped to the intended session.
• Reported zero usage is distinguishable from missing or estimated usage.
• Signals, executor timeouts, and provider idle timeouts have distinct semantics.
• Contract and real subprocess tests cover the failure paths.

Roadmap Alignment

• Pillar: EXEC
• Quarter: Q3 2026
• Priority: P0
• Theme fit: Pilot-ready executor reliability and trustworthy execution telemetry.

Upstream OpenCode Prior Art

The aictrl CLI retains behavior inherited from OpenCode, and its backlog contains closely related reports:

• Output durability and missing event delivery: #30831, #29866, #31435, #31482
• Signal cleanup: #24658, #32932
• Invisible pre-session failures: #27559, #30100
• Unknown/zero usage semantics: #25899, #30118, #21913, #26170

In particular, OpenCode #31435 documents an event-ordering race that produces empty JSON independently of stdout flushing. The workstreams in this tracker must keep output transport, event delivery, lifecycle semantics, and usage semantics independently testable.

[byapparov]

Update: the thinking-shape hypothesis is REFUTED (live-verified against the real z.ai coding endpoint)

Ran a faithful streaming probe against https://api.z.ai/api/coding/paas/v4/chat/completions (model: glm-5.2, stream:true, stream_options.include_usage:true), both with and without the injected thinking:{type:"enabled",clear_thinking:false}. Both return usage in the standard OpenAI shape in the final pre-[DONE] chunk:

WITH thinking:    "usage":{"prompt_tokens":20,"completion_tokens":128,"total_tokens":148,
                  "prompt_tokens_details":{"cached_tokens":0},
                  "completion_tokens_details":{"reasoning_tokens":128}}
WITHOUT thinking: "usage":{"prompt_tokens":20,"completion_tokens":127,...,"reasoning_tokens":124}

Reasoning content arrives on reasoning_content; reasoning tokens on completion_tokens_details.reasoning_tokens — all fields the @ai-sdk/openai-compatible reader already parses. Enabling thinking does NOT change the usage shape and does NOT suppress usage. So per-turn usage capture is correct; the zero/undercount is not a thinking-mode issue.

This leaves the real bugs unchanged and better-focused:

• Truly-NULL (dominant): B1 (no stdout flush before forced process.exit() on a pipe) + B2 (no SIGTERM handler) + B3 (fail-before-session_start) — empty stream.
• Zero-valued: M1 (message_complete only on clean finish-step).
• Undercount: M2 (multi-step tokens= overwrite vs cost+= accumulate). M3 (silent ?? 0) rarely fires in practice since usage is reliably present per turn — but keep it as a fail-fast guard for the cases that do go empty.