Add NDJSON invocation lifecycle events before session creation

[byapparov]

Context

session_start is emitted only after validation, bootstrap, subscription, and session creation. Invalid files/directories, empty input, bootstrap failures, and stalled stdin can therefore leave JSON consumers with no stdout event.

A truthful session_start cannot be emitted before a real session ID exists.

Problem / Goal

Give accepted JSON run executions a structured lifecycle from invocation start through pre-session failure without inventing a session ID or changing the meaning of session_start.

Approach

Add a run-scoped invocation envelope owned by the parsed RunCommand handler:

• invocation_start with schemaVersion and a generated invocationID;
• invocation_error for known validation, stdin, bootstrap, and session-creation failures;
• invocation_complete exactly once for the wrapped run;
• invocationID on later session events once a real session exists.

The lifecycle uses the shared serialized stdout writer and does not add entrypoint hooks, argv sniffing, global singleton state, or a second writer.

Acceptance Criteria

• The first line of the parsed RunCommand handler creates the lifecycle when args.format === "json".
• invocation_start is emitted before reading piped stdin and before run validation/bootstrap.
• Invocation events use invocationID, not a fabricated sessionID.
• Once created, the real session is linked to the invocation and session events carry invocationID.
• Invalid --dir, missing --file, empty input, invalid --fork, bootstrap failure, and session-create failure produce sanitized structured invocation errors.
• Every started invocation covered by the run execution wrapper emits exactly one invocation_complete.
• Existing session_start retains its current meaning and real session ID.
• A real subprocess test observes invocation_start before piped stdin closes.
• Schema documentation and contract tests are updated.

Out of Scope

• Argument-parser failures before the run handler is accepted.
• Non-run commands.
• Process-global uncaught exceptions and unhandled rejections.
• Signal and timeout policy.
• Fabricating sessions solely to report validation failures.

Roadmap Alignment

• Pillar: EXEC
• Quarter: Q3 2026
• Priority: P1
• Theme fit: Execution telemetry and pilot-quality executor reliability.
• Decision gate impact: Indirect, by making failed automation diagnosable.

References

• Parent: Epic: Make headless NDJSON lifecycle and usage telemetry reliable #89
• Related schema work: NDJSON event schema gaps for downstream observability consumers #63
• Shared stdout delivery: Fix NDJSON backpressure and shutdown flushing #91 / fix(cli): flush NDJSON before forced exit #95
• Terminal telemetry provenance: Preserve unknown usage on failed headless turns #93 / fix(run): preserve terminal usage provenance #97
• packages/cli/src/cli/cmd/run.ts

Upstream OpenCode References

• anomalyco/opencode#27559 — auto-closed after inactivity, not resolved; a missing session exits 0 with empty JSON stdout and the report explicitly requests a structured JSON failure event.
• anomalyco/opencode#30100 — open; a JSON command spawned from Node.js/Electron on Windows exits successfully with empty stdout.

These reports demonstrate pre-session and command-start failures that are invisible to JSON-only consumers. Neither defines a general invocation lifecycle independent of a real session ID.