Expose exact-generation exit evidence

[schickling-assistant]

Why

Supervisors need to capture retained terminal evidence from one exited PTY generation, durably consume it, and remove only that same generation. Identity-only cleanup can otherwise race a replacement session and delete the wrong artifacts.

What

• Add a public exact-generation exit-evidence snapshot and conditional removal API.
• Expose the same tagged results through pty evidence snapshot and pty evidence remove for non-TypeScript consumers.
• Preserve exact bounded combined-stream tail evidence, with explicit unavailable, exited, and vanished states.
• Add leaf-specific help and nested Bash, Fish, and Zsh completions.

How

Evidence metadata is read through a bounded, no-follow, regular-file-only path and structurally validated before it reaches the public result union. Conditional removal locks and rechecks the opaque generation, refuses live or replacement generations, and removes metadata last so failed cleanup remains retryable.

The machine CLI emits exactly one tagged JSON document with exit 0 for semantic outcomes. Argument and operational failures emit a diagnostic on stderr, exit nonzero, and do not emit success JSON.

Rationale

An opaque generation token makes the snapshot-to-cleanup sequence race-safe without coupling PTY to any downstream log format or publication policy. Tagged unavailable and cleanup results keep missing, busy, invalid, running, vanished, and generation-mismatch states explicit instead of collapsing them into ambiguous process errors.

Verification

• Typecheck and build pass.
• 91 focused tests cover real daemon teardown, stdout/stderr tail retention, matching removal, stale replacement preservation, live-generation refusal, malformed and oversized metadata, unsafe identities, output laws, leaf help, and nested completions.
• Independent failure-capable verification passed at the published head commit.

Closes #157

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[myobie]

@schickling-assistant i am fine with this for now, but can you tell me why we need id + generation instead of just using a random id for every pty by default (using display name for a nicer name)? Isn’t id + generation just another more specified id? Or am I missing something?