git:20260824.0549249 to git:20260831.a99450d

# packages/pty

`@earendil-works/pi-pty` is the TypeScript PTY facade: native loader, sessions, detached registry, headless screen, and non-PTY pipe fallback.

## STRUCTURE

```text

src/index.ts Public barrel; ".", "./screen", "./registry", "./native" exports

src/loader.ts, native-loader.ts Native prebuild discovery and ABI checks

src/session.ts Public session lifecycle

src/session-native.ts Native backend adapter

src/pipe-fallback.ts child_process fallback when native is absent

src/session-exit.ts Exit settlement helpers

src/registry*.ts Session registry and detached ownership

src/screen.ts Headless terminal screen state

src/quarantine.ts macOS quarantine detection for prebuilds

native/prebuilds/ Shipped platform binaries

native/check-prebuild-fresh.mjs Prebuild freshness gate

test/fixtures/*.mjs Native-addon child processes for callback/worker races

```

## INVARIANTS

- The native ABI constant is intentionally independent of package CalVer. Keep it aligned with `crates/senpi-pty` exports.

- macOS quarantine is probed via `xattr -p` before loading a prebuild. Detection must never clear the attribute; an unreadable attribute is non-rejecting.

- Unsupported or missing native bindings select the pipe fallback with a diagnostic; fallback behavior must never be presented as a real PTY.

- Exit notification settles exactly once across native exit, child exit, startup failure, kill, and disposal races.

- `kill()` is idempotent and detached-child cleanup owns the full process tree.

- Bound retained raw output/tails; persistent sessions must not grow memory without limit.

- Registry IDs, detached process metadata, stop, and removal remain explicit. The current registry has no caller-authorization model; do not claim owner isolation without adding one.

## WHERE TO LOOK

| Task | Path |

|---|---|

| Public API / subpath exports | `src/index.ts` |

| Native loading/ABI | `src/loader.ts`, `src/native-loader.ts` |

| Session lifecycle | `src/session.ts`, `src/session-exit.ts` |

| Fallback process behavior | `src/pipe-fallback.ts` |

| Detached sessions | `src/registry.ts`, `src/registry-detached.ts` |

| Screen parsing | `src/screen.ts` |

| Native implementation | `crates/senpi-pty/` |

## VALIDATION

- Lifecycle changes need focused race tests for exactly-once exit, idempotent kill, and process-tree cleanup.