# Clean-Room Implementation Record: Xeno PTY Runtime

## Identity

- Component: Xeno-owned native PTY binding, artifact loader, and UnifiedExec adapter
- Replacement milestone: PROPRIETARY-PTY-1
- Repository and paths: `xeno-agent-cli/apps/xeno-agent-cli/native/xeno-pty/`, `apps/xeno-agent-cli/src/terminal/xeno-pty-*.ts`
- Record owner: Xeno engineering, final owner assignment pending
- Implementer(s): Codex implementation assistant; human native-code review pending
- Contract author(s): Xeno engineering requirements in `switch-to-proprietary.md`
- Started at (UTC): 2026-07-12
- Candidate revision: `87ae64b55aa1b8c2e126294e717b229e0945db65` plus recorded working-tree changes
- Status: Windows x64, Linux x64, and Linux arm64 engineering complete; remaining architecture and release evidence incomplete

## Frozen behavioral contract

- Public API and observable behavior: spawn an interactive terminal with file, argument, cwd, environment, column, and row inputs; emit ordered UTF-8 data and exactly one exit event; accept input; resize; perform graceful interruption and forced process-tree termination.
- Compatibility fixtures: `tests/xeno-pty-integration.test.ts`, `tests/xeno-pty-adapter.test.ts`, and `tests/xeno-pty-loader.test.ts`.
- Intentional incompatibilities and versioning decision: the adapter reports `xeno-conpty` or `xeno-posix-pty`; unavailable platforms explicitly retain pipe mode and are not reported as interactive PTY support.
- Security and resource limits: direct stable C N-API only; 256-event native queue with producer backpressure; 1 MiB pre-listener output cap; SHA-256 and Ed25519 trust verification before loading; Windows Job Object kill-on-close tree ownership.
- Supported platforms and architectures: Windows x64, Linux x64, and Linux arm64 are implemented and locally verified. Windows arm64 and macOS x64/arm64 are configured but unobserved and remain outside the achieved capability gate.

## Normative and permitted inputs

| Source | Revision/date | Purpose | Terms reviewed by | Evidence path |
| --- | --- | --- | --- | --- |
| Xeno proprietary migration specification | 2026-07-12 | PTY behavior, ownership, packaging, and release constraints | Engineering; counsel pending | `switch-to-proprietary.md` |
| Microsoft CreatePseudoConsole documentation | accessed 2026-07-12 | ConPTY stream, resize, and lifecycle contract | Engineering | `https://learn.microsoft.com/windows/console/createpseudoconsole` |
| Microsoft Creating a Pseudoconsole Session documentation | updated 2025-08-13 | Pipe directions, STARTUPINFOEX, process creation, and close ordering | Engineering | `https://learn.microsoft.com/windows/console/creating-a-pseudoconsole-session` |
| Microsoft CreateProcessW and Job Object documentation | accessed 2026-07-12 | Child startup handles and process-tree containment | Engineering | Microsoft Learn Win32 API documentation |
| Linux man-pages `forkpty(3)`, `ioctl_tty(2)`, `setsid(2)`, and `kill(2)` | accessed 2026-07-12 | PTY creation, terminal resize, session/process-group ownership, and signal delivery | Engineering | public Linux man-pages documentation |
| Node stable C N-API headers | Node 24.13.1, N-API v8 target | ABI contract without `node-addon-api` | Engineering | locally installed Node headers and public Node API documentation |
| Xeno UnifiedExec contract | candidate working tree | Product-side PTY adapter behavior | Engineering | `xeno-agent-sdk/src/runtime/unified-exec.ts` |

## Contributor source-exposure disclosure

| Contributor | Inspected replaced source? | Date/range | Separation or review decision | Counsel reference |
| --- | --- | --- | --- | --- |
| Codex implementation assistant | No `node-pty` or `node-addon-api` implementation source was inspected. Work used Xeno contracts and Microsoft/Node public API documentation. | 2026-07-12 | Independent native and provenance review required | Pending |
| Human contributors | Disclosure not yet collected | Pending | Must be completed before capability approval | Pending |

## Implementation log

| Date (UTC) | Decision | Contract/source basis | Author | Evidence path |
| --- | --- | --- | --- | --- |
| 2026-07-12 | Bind ConPTY directly through stable C N-API | FR-030 through FR-035 | Codex implementation assistant | `native/xeno-pty/src/xeno_pty_win.cpp` |
| 2026-07-12 | Bind Linux/macOS PTY primitives directly through stable C N-API | FR-032 through FR-036 | Codex implementation assistant | `native/xeno-pty/src/xeno_pty_posix.cpp` |
| 2026-07-12 | Own each POSIX PTY as a session/process group and drain output before settlement | complete-tree termination and exactly-once lifecycle contract | Codex implementation assistant | POSIX native source and integration tests |
| 2026-07-12 | Null inherited standard handles before pseudoconsole attachment | Captured-output conformance and CreateProcess startup contract | Codex implementation assistant | `xeno_pty_win.cpp`, integration tests |
| 2026-07-12 | Use one bounded ordered native event channel and StringDecoder bridge | FR-034 and FR-036 | Codex implementation assistant | native source and `xeno-pty-adapter.ts` |
| 2026-07-12 | Join and destroy native state at exit settlement | Handle-lifecycle and exactly-once requirements | Codex implementation assistant | native diagnostics and 25-cycle soak |
| 2026-07-12 | Verify ABI, hash, platform, architecture, and Ed25519 trust before load | FR-038 | Codex implementation assistant | `xeno-pty-loader.ts`, manifest signer |
| 2026-07-12 | Forbid `node-pty` and `node-addon-api` reintroduction | Phase 3 dependency gate | Codex implementation assistant | ownership policy revision 5 |
| 2026-07-12 | Resolve Windows N-API exports from the actual host process instead of importing `node.exe` | renamed/self-contained Node hosts must load the same owned addon safely | Codex implementation assistant | `xeno_pty_win.cpp`, PE import verifier, packaged Windows doctor smoke |
| 2026-07-12 | Standardize release Windows builds on MSVC and reject non-platform PE imports | exclude GNU runtime linkage and undeclared auxiliary DLLs | Codex implementation assistant | `build-windows.ps1`, `verify-pe-imports.mjs` |

## AI assistance

- Models/tools used: OpenAI Codex coding agent, local PowerShell, Microsoft C/C++ 19.44, Node.js, Vitest, and an isolated Debian Docker verifier.
- Prompt or retained prompt-summary path: active Xeno proprietary migration goal and `switch-to-proprietary.md`.
- Confirmation that no third-party source entered the prompt: no replaced-package implementation source was supplied or inspected; public platform/API documentation and Xeno-owned contracts were used.
- Human review performed: pending.

## Verification evidence

- Unit and compatibility tests: 13 focused tests pass on Windows; 12 execute and pass in a clean Linux Docker dependency environment with one Windows-only local-load assertion skipped.
- Conformance corpus: TTY startup, ordered output, Unicode input/output, resize protocol, foreground-to-background PID preservation, Ctrl+C delivery, exactly-once exit, graceful-to-force escalation, early-output bound, descendant cleanup, tampered hash rejection, unsigned-install rejection.
- Fuzz campaign and duration: deterministic malformed-input and lifecycle/state campaigns pass 100 iterations on the current Windows x64 artifact in 10.064 seconds, 100 iterations on Linux x64, 100 iterations on Linux arm64 under emulation, and 250 Linux x64 iterations under AddressSanitizer and UndefinedBehaviorSanitizer. Coverage-guided native fuzzing remains required before capability approval.
- Security/resource-limit tests: finite native event queue, bounded early buffer, hash mismatch rejection, malformed manifest rejection, installed unsigned artifact rejection, and isolated Linux AddressSanitizer/UndefinedBehaviorSanitizer smoke plus stress execution.
- Cross-platform results: Windows x64, Linux x64, and Linux arm64 local/container pass; Windows arm64 and macOS x64/arm64 matrix runs pending.
- Performance comparison: 25 rapid real-PTY cycles pass with native active-state count returning to zero. The current Windows MSVC artifact measures startup p50/p95 35.31/359.15 ms and approximately 2.6 MB/s observed output; the Linux x64 baseline measures p50/p95 14.76/17.55 ms and approximately 32.6 MB/s. Linux arm64 under emulation measures p50/p95 556.17/612.07 ms and approximately 1.64 MB/s. The dependency-free benchmark enforces conservative CI limits of 2,000 ms p95 and 1 MiB/s; a product-approved comparative release envelope remains pending.
- Bundle/native/SBOM evidence: artifact audit records Xeno-owned Windows x64 SHA-256 `91d9a464823091603d784cbc3a570b8a0e514576eeb4b8fb2aabcdcbb64bccad` from source SHA-256 `9f6f6248f35f2f6b767b153f66670d5ed8f95cb7d6242c77c652efe5cca2d038`, Linux x64 SHA-256 `a93757b552cb9236fe33773228072df270659d6a015a92fb96d21a9d22c5f2cb`, and Linux arm64 SHA-256 `07f660ac0c32ac7a2900f3abdfa12550f603880f02a1763a12a63064fe802006`; both Linux artifacts derive from source SHA-256 `6ba69e62cf0c0765546afa19f1820c1cc7f64f452802718c20b4a117d6c8f9c6`. The Windows PE imports only `KERNEL32.dll`; two local native rebuilds are byte-identical. Clean Debian candidates execute Linux x64 and Linux arm64 self-contained payloads. The exact cross-built Windows x64 payload (`21386d53c04116f4904da186c873089aac4db57c02281da2c14f615a50a9b616`) executes on Windows with a byte-matching extracted addon and healthy ConPTY diagnostics. The Linux arm64 payload SHA-256 is `92a8583433aec8415c1405b56ad5afe39f7560c216eac4e46684fb03041e6346`. Paired release verification correctly stops at the strict unsigned-native gate; see `docs/compliance/linux-package-candidate.md` and `docs/compliance/linux-arm64-package-candidate.md`. Clean signed-install smoke remains pending.

## Open legal or provenance questions

- Patents/specification terms: operating-system and Node API boundary review pending.
- Trademarks: historical replaced-package names remain only in migration evidence and forbidden-package rules.
- Export or distribution constraints: native binary distribution and signing review pending.
- Other: release trust store is empty and both exercised prebuilds are intentionally marked `unsigned-development`; unobserved architecture CI, coverage-guided fuzzing, independent review, contributor disclosures, and counsel disposition remain mandatory.

## Handoff

- Implementation complete: Windows x64, Linux x64, and Linux arm64 yes; complete PTY milestone no
- Evidence complete: no
- Ready for independent provenance review: after signing, coverage-guided fuzzing, and remaining cross-platform package evidence
- Author/date: Codex implementation assistant, 2026-07-12