docs(opencode): record native cold-start failure evidence - #548

<!-- stamp:review:v1 -->
<sup><img
src="https://cdn.slock.ai/avatars/6aabf32c-20bc-4cba-b55a-2aa72b60999b/8ba4452ceb890f1930886ef4286fdb99.webp"
width="16" height="16" align="absmiddle" alt=""> <b>Otter</b> from
open-agent-runtime opened this pull request through
Stamp</sup><br><sup><a
href="https://stamp.build/review?receipt=prc_750fda30dd0b3568bf4c6f545c15c82e"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://stamp.build/assets/brand/stamp-glyph-dark.d907ffcadb44.svg"><img
src="https://stamp.build/assets/brand/stamp-glyph-light.58a2c10ed108.svg"
width="13" height="12" align="absmiddle" alt=""></picture> View in Stamp
→</a></sup>

---
<!-- /stamp:review:v1 -->

When process-table enumeration fails during shutdown, OAR currently
treats it as an empty tree. A root can exit after EOF while detached
descendants remain, with no indication that cleanup could not be
verified. Preserve the failed observation and expose that limitation
through the existing `exited.reason` and startup error paths.

- Distinguish a usable table from timeout, spawn/command failure,
invalid output and a missing live host. Retain source, elapsed time and
bounded native error fields; omit process names, arguments, environment
and command output.
- Skip and count permission-denied procfs entries and Windows entries
without creation times. Other readable identities remain usable;
malformed PIDs, structural errors and an unreadable host still fail.
Skipped counts remain in internal cleanup observations.
- Retry a failed capture once before EOF, preserving both observations.
Keep native shutdown hooks and normal escalation. If capture or later
identity validation remains unavailable, stop the owned root and report
unverified descendant cleanup. Reused identities and unrelated processes
are never selected from stale PIDs.
- Forward cleanup diagnostics through ACP, Codex, stream-json and Pi RPC
shutdown/startup paths without replacing native error class/cause. The
synchronous host-exit hook reports the failure and still stops other
owned roots.

The shared executable layer owns the change. Hosts can distinguish root
exit from verified descendant observation without a new public field.
The record-stream spec and regression tests preserve the contract. The
extra pre-EOF attempt uses the existing five-second ps/CIM budget;
installation deadlines, native hook grace, Windows resources and
shared-session release semantics are unchanged.

Validation on Linux x64:

- `CI=1 pnpm run check`: 2,545 tests and 18 mock behavior cases passed.
Real Node fixtures cover failed reads before EOF and after exit, retry
recovery, native EOF hooks, a surviving detached child with an explicit
diagnostic, and an unrelated live sentinel. Startup refusal
classification/cause and redaction are preserved.
- Explicit native versions passed behavior checks: Claude 2.1.314 (17),
Codex 0.165.0 (16), Qoder 1.1.81 (17), Kimi 2.4.0 (15), Qwen 0.26.4
(16), CodeBuddy 2.178.1 (16), OpenCode 1.19.5 (17) and 2.2.1 (15). Grok
1.0.70, Pi RPC/SDK/durable 1.4.0 and shared/isolated mock behavior also
passed.
- Pi RPC native vendor suite: 84 passed. A preliminary PATH-based run
exposed the existing OpenCode startup failure; current-version rechecks
passed. The separate documentation change is PR #548.
- The review regressions cover protected external entries while finding
and signalling only owned descendants. They failed before the reader
correction and pass after it.
- The initial Windows check found that the descendant fixture exited in
the two injected-failure cases. The revised fixture gives the tool an
independent console on Windows, waits for explicit tool readiness and
IPC disconnection, and asserts it is alive before shutdown. The original
cleanup assertions remain. Windows confirmation and macOS coverage are
pending CI.

Task #115, following Cindy's approved observable-unverified cleanup
policy. This does not claim the historical Windows observation failure
was a timeout, or that a successful cleanup observation proves every
descendant has stopped.

---------

Co-authored-by: Otter <[email protected]>