Fail the Session when its hosted Environment fails to provision

[SaladDay]

When an openai_hosted Environment fails to provision, clients now see the failure the way the official service reports it. Core used to leave the Session idle with no error and keep the stream open. Command, package-manager and file output is never exposed. The pinned baseline is unchanged (SDK 3.13.0 / d7c41ef / agents=v1).

Behavior

• Failure record (one transaction):
  • The Environment is marked failed, and Core records three events: agent.session.environment.failed, error and agent.session.failed.
  • The Session snapshot has status failed, error set to the safe reason, required_actions: [] and last_active_at.
  • Retrieve, list and events agree. Pending input settles as before.
• Payloads:
  • environment.failed carries {type: environment_error, code: environment_connection_failed, message: "The environment failed to connect."}.
  • The error event carries {type: environment_error, code: sandbox_error, message: <reason>, param: null}.
• Reason: for example Failed to provision environment: script "setup_commands[0]" failed with exit code 3, or script "Python package installation" failed with exit code 1.
  • The Runtime initializer reports only an integer exit code for a failed sandboxed step, never output. Core builds the reason from a fixed label, the step index and that integer.
  • npm, system package, file, Skill and Plugin labels are documented as unverified.
  • Timeouts, unknown-effect failures and old Runtime images get initialization did not complete.
• Streams: the GET events stream and the creation stream end after agent.session.failed.
• Input: events.create on that Session returns 409 conflict_error/conflict_error, "the hosted environment failed to provision". Expired Environments keep their previous response.
• Delete: a failed Session is deletable (200). Deleting during provisioning is unchanged; that remains a pending decision (HI-05).
• Storage: migration 000062 adds nullable environments.failure_reason and failed_at.
  • A check constraint ties them to status = failed and at most 256 characters.
  • Rolling back refuses when any failure reason is recorded, following the repository's pattern.
• Compatibility:
  • Core's own stream_interrupted frames keep their {code,type,message} shape for released clients.
  • The TS client delivers Session error events to onEvent.
  • Old Runtime images keep working, with the generic reason.
  • The Codex, Claude and MiniMax Code Runtime images must be rebuilt to report exit codes.

Evidence

• HI-01..04 (campaign scan 6: two owned openai_hosted Sessions without Turns, both deleted; raw frames recorded).
• Recorded in environment-templates.md, history-events-usage.md, official-semantics-alignment.md, operation-evidence.md (register HF) and the READMEs.

Validation

• Live acceptance on Core-managed Docker openai_hosted with Codex. Images, including each tree's initializer, were built from each tree and hash-checked. There was a fresh database per phase and no model Turns.

  Case	main	candidate
  Setup exit 3: retrieve/list	idle, no error	failed, step and exit-code reason, last_active_at
  Setup exit 3: stream	only environment.failed (generic), stayed open	environment.failed, error, session.failed, then closed
  Setup exit 3: input	409 environment_unavailable	409 conflict_error official message
  Nonexistent Python package	same failures as above	failed with the Python label and exit code 1; same stream and 409
  Delete / tenant B	200 / 404	200 / 404
  Canary and pip output	–	absent from 78 responses and all stream bytes

  All events and reads pass the pinned SDK's strict parse. Cleanup and secret scans passed.

• Tests:

  • Initializer receipt tests.
  • Execution tests for receipt edge cases, including stderr, other statuses, out-of-range, null, string and fractional exit codes, and duplicate keys.
  • PostgreSQL store tests for the transaction, event order, stream end, 409, delete, tenant B, old receipts, unknown effects and a canary that is checked against logs.
  • A migration test covering upgrade, constraint and both rollback outcomes.
  • API, contracts and TS client tests.

• Server gate on this head: all make check targets, plus Web typecheck, core-doctor, unit tests and build, pass. The Playwright browser cases were not run on the server (no Google Chrome; the user approved the skip). make openapi and make sqlc-generate are byte-identical.

• Independent blind review by a fresh Claude Code subagent (the user-approved replacement for GPT-6 Astra). It found no leak path, race or behavior blocker. Its follow-ups are fixed in the last commits:

  • the rollback guard;
  • the stream documentation;
  • stream_interrupted compatibility;
  • precise receipt wording;
  • the missing tests, and a canary assertion that can actually fail.

  They were verified by focused tests and the gate without a new review, per the user's rule. The optional official turn_id: null on Environment events is deferred, because released clients accept only four fields there.

Deferred decisions: HI-05 (delete during provisioning) and HI-06 (long setup steps). No full protocol compatibility is claimed.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}