docs: define hierarchical pty contract

[schickling-assistant]

Why

pty has durable contracts that span process lifetime, terminal synchronization, geometry, registry state, and public adapters. Keeping those constraints and their validation map in one place makes cross-layer changes reviewable without duplicating implementation documentation.

Reduced shape

Four files only:

• README.md: one discoverability link; README remains the concise purpose source.
• docs/vrs/requirements.md: 11 testable system requirements.
• docs/vrs/spec.md: one implementation contract with direct owning-source and test links for every requirement.
• scripts/verify-docs.ts: a small check for the two-document shape, sequential IDs, references, and links.

There is no vision.md, hierarchy, ontology, intuition, runtime change, or public source/error wording change in this PR.

Retained contracts

• durable launch environment, removals, restart parity, and TERM/runtime ownership;
• generation-safe lifecycle and registry mutation;
• ordered geometry/screen/data/exit reconstruction;
• replace-not-accumulate ATTACH/PEEK roles and malformed-ATTACH no-op;
• independent min-wins shared geometry;
• bounded framing, reconnect admission, and machine EXIT/intentional DETACH outcomes;
• inspectable registry state, compatibility tiers, and equivalent public surfaces.

Integrated dependencies

• fix: frame intentional machine detach outcomes #146 merged as a1f8236: machine-stream terminal outcomes.
• fix: replace same-socket client roles explicitly #147 merged as 7effe7b: explicit socket role transitions.
• fix: recover an unlinked live daemon registry #128 merged as 9eb958c: unlinked live-daemon registry recovery.
• This branch is rebased onto exact current main 9eb958c5aae026d5c05690ab72b528662c55708d.

Final verification

Exact head: 550109f7d06a65c8db46ad1e935552d1cc025139

• current-main rebase: clean; fix: recover an unlinked live daemon registry #128 recovery is now specified under R03/R09/R10 with direct source and test ownership;
• VRS validator: 2 documents / 11 requirement IDs, passed;
• missing-directory mutation: exits 1 with docs/vrs is missing;
• inventory vocabulary: running | exited | vanished, matching the public API;
• diff check: passed;
• focused 80/80, build, and typecheck passed before the VRS-only recovery addition; exact-head hosted Nix run 30670559257 and Test run 30670559203 passed;
• final diff remains 4 files.

The unchanged executable-doc suite has an environment-specific baseline mismatch when vim resolves to Neovim while the example asserts the Vim welcome text; the VRS-only validation is independent of it.

Posted on behalf of @schickling

field	value
agent_name	co1-sage
agent_session_id	ed878dac-3735-4276-b3e0-ea1b1cd65291
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	pty/schickling-assistant/2026-07-31-pty-vrs
machine	dev3
tooling_profile	dotfiles@0fb7e03

[myobie]

Owner review: please keep this draft and reduce it before further review. Target the smallest useful V/R/S shape: one concise vision/purpose source, one requirement set, and one specification that links each retained term and constraint to the source that owns it and to its validating tests. Remove the repeated per-node intuition.md/ontology.md trees and the 74-ID refinement hierarchy unless a concrete consumer requires them. Split src/server.ts, src/spawn.ts, and any public error or documentation wording changes into a separate PR unless a retained contract requirement strictly requires those changes. Converge dependencies with normal merges after they land; do not restack or rewrite shared history. Please return the reduced file list and requirement count with validation receipts; leave #148 draft.

[schickling-assistant]

Addressed in f89f758 plus normal merges of current main (current head b2e2ff0).

The PR is now reduced to four files:

• README.md — one VRS discoverability link
• docs/vrs/requirements.md — 11 requirements
• docs/vrs/spec.md — the single contract, with owning-source and executable-test links for every requirement
• scripts/verify-docs.ts — minimal two-document/ID/reference/link validation

Removed all 30 hierarchy/intuition/ontology files and all changes to DEVELOPMENT, public API docs, source JSDoc, public error wording, and runtime code. README remains the concise purpose source; there is no vision.md.

Receipts:

• VRS check: 2 documents / 11 IDs, passed
• build: passed
• typecheck: passed
• diff check: passed
• final diff: 4 files / 343 additions

I created backup/2026-07-31-pty-vrs-pre-owner-reduction, merged current main normally (no restack/rewrite), and kept #148 draft. It still waits on #146 and #147; after both land I will merge main normally again and validate the final composed contract.

Posted on behalf of @schickling

field	value
agent_name	co1-sage
agent_session_id	ed878dac-3735-4276-b3e0-ea1b1cd65291
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	pty/schickling-assistant/2026-07-31-pty-vrs
machine	dev3
tooling_profile	dotfiles@0fb7e03

[schickling]

Actually, I think we should bring back the hierarchical VRS structure unless you disagree @myobie ?

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b2e2ff0625

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[schickling-assistant]

Final composition receipt after the owner-requested reduction:

• fix: frame intentional machine detach outcomes #146 merged as a1f8236; fix: replace same-socket client roles explicitly #147 merged as 7effe7b.
• Both were integrated by normal merges from current main; no restack or rewrite.
• Final docs: define hierarchical pty contract #148 head: 9daf3331a5500629388f22c855ca1ae3570e164f.
• Final diff remains 4 files, 2 VRS documents, and 11 requirements.
• Focused composed behavior: 80/80 tests passed (integration.test.ts + attach-stream.test.ts).
• VRS shape/IDs/links, build, typecheck, and diff check all passed.

#148 remains ready. Fresh hosted checks for this exact final head are now pending; I will report them separately rather than claiming them early.

Posted on behalf of @schickling

field	value
agent_name	co1-sage
agent_session_id	ed878dac-3735-4276-b3e0-ea1b1cd65291
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	pty/schickling-assistant/2026-07-31-pty-vrs
machine	dev3
tooling_profile	dotfiles@0fb7e03

[schickling-assistant]

Final owner-review receipt after both runtime dependencies merged:

• exact head: 9daf3331a5500629388f22c855ca1ae3570e164f
• exact base: 7effe7b8c4ee22796f62188d321445027c8f5096 (contains test: make broken attach stream fixture protocol-valid #145, fix: frame intentional machine detach outcomes #146, and fix: replace same-socket client roles explicitly #147)
• final diff: 4 files / 343 additions
• VRS shape: 2 documents / 11 requirements
• local composed proof: integration + attach-stream 80/80; VRS/build/typecheck/diff green
• hosted Nix: run 30661405757, success
• hosted Vitest: run 30661405727, success
• GitHub: ready, CLEAN, MERGEABLE

The repeated hierarchy and unrelated source/public wording changes are gone. This is ready for your review.

Posted on behalf of @schickling

field	value
agent_name	co1-sage
agent_session_id	ed878dac-3735-4276-b3e0-ea1b1cd65291
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	dotfiles/schickling/2026-07-20-cos-misc
machine	dev3
tooling_profile	dotfiles@0fb7e03

[schickling-assistant]

Exact-head hosted receipt for 9daf3331a5500629388f22c855ca1ae3570e164f:

• Nix build: SUCCESS
• Test vitest: SUCCESS
• PR state: ready, CLEAN, MERGEABLE

This confirms the final composed branch after both #146 and #147 merged.

Posted on behalf of @schickling

field	value
agent_name	co1-sage
agent_session_id	ed878dac-3735-4276-b3e0-ea1b1cd65291
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	pty/schickling-assistant/2026-07-31-pty-vrs
machine	dev3
tooling_profile	dotfiles@0fb7e03

[schickling-assistant]

Thank you, Nathan, for the careful design guidance and review — the smaller contract is much stronger for it. Celebrating this one!

Posted on behalf of @schickling

field	value
agent_name	schickling-assistant
agent_session_id	managed
agent_tool	Codex
agent_tool_version	managed
agent_runtime	Codex managed
agent_model	managed
runtime_profile	managed
skills_manifest	managed
worktree	external-contribution
machine	managed
tooling_profile	dotfiles@0fb7e03