feat(contracts): add PtyHost interface (Plan-024 T-024-2-1) by Sawmonabo · Pull Request #45 · Sawmonabo/ai-sidekicks

Sawmonabo · 2026-05-11T07:17:21Z

Summary

Ships packages/contracts/src/pty-host.ts — the runtime-callable
PtyHost interface (spawn / resize / write / kill / close + onData /
onExit). Method signatures pinned per Plan-024 T-024-2-1. Imports SpawnRequest / SpawnResponse / PtySignal from sibling pty-host-protocol.ts (shipped in Plan-024 Phase 1 / PR #42).

This is NS-04 PR-A — the cross-plan contracts-pair carve-out from Plan-024 Phase 2, per cross-plan-dependencies.md §6 NS-04. T-024-2-2 (NodePtyHost) and T-024-2-3 (selector) are deferred to NS-05 because Plan-024 Phase 2's full precondition requires Plan-001 T5.4 (cwd-translator), which itself depends on this interface. Shipping the interface alone is structurally safe — NodePtyHost is what surfaces Windows ERROR_SHARING_VIOLATION without the translator, and the interface introduces no Windows code path.

Sequence:

NS-04 PR-A (this PR) — PtyHost interface in contracts.
NS-04 PR-B — Plan-001 T5.4 spawn-cwd-translator.ts consuming this interface.
NS-05 — Plan-024 Phase 2 remainder (T-024-2-2 NodePtyHost + T-024-2-3 selector) once T5.4 is at HEAD.

Test plan

pnpm --filter @ai-sidekicks/contracts typecheck green (tsc -b + tsconfig.test.json).
pnpm --filter @ai-sidekicks/contracts test — 148/148 green (no test changes; interface-only).
Root pnpm typecheck — 8/8 packages green; new export flows through index.ts barrel without breaking downstream consumers.
CI green (typecheck + lint + test + lychee + commitlint + gitleaks).
Codex external review (auto-trigger; eyes-poll → verdict-poll per plan-execution SKILL.md §D.5 step 3).

References

Plan-024 T-024-2-1 — task definition + pinned signatures
cross-plan-dependencies.md §6 NS-04 — cross-plan PR-pair entry
ADR-019 §Decision item 1 — sidecar binary on Windows; PtyHost contract authority
Plan-001 §CP-001-2 — cwd-translator obligation that PR-B will discharge

Refs: ADR-019, Plan-024, Plan-001

🤖 Generated with Claude Code

Adds `packages/contracts/src/pty-host.ts` with the runtime-callable `PtyHost` interface (spawn / resize / write / kill / close + onData / onExit). Pinned method signatures per Plan-024 audit finding 2-03. Imports `SpawnRequest`/`SpawnResponse`/`PtySignal` from sibling `pty-host-protocol.ts` (which already carries the wire-format DTOs). This is NS-04 PR-A — the cross-plan contracts-pair carve-out from Plan-024 Phase 2. T-024-2-2 (NodePtyHost) and T-024-2-3 (selector) are deferred to NS-05 because Plan-024 Phase 2's full precondition requires Plan-001 T5.4 cwd-translator (which itself depends on this interface). Shipping the interface alone is structurally safe — NodePtyHost is what surfaces Windows ERROR_SHARING_VIOLATION without the translator, and the interface introduces no Windows code path. Refs: ADR-019, Plan-024, Plan-001 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Sawmonabo · 2026-05-11T07:24:14Z

@codex review

chatgpt-codex-connector · 2026-05-11T07:25:49Z

Codex Review: Didn't find any major issues. Can't wait for the next one!

ℹ️ 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".

Phase E auto-housekeeping for Plan-024 T-024-2-1 (PR #45, ed71ee1) + maintenance follow-up PR #46 (e4520f2): Catalog (cross-plan-dependencies.md §6 NS-04): - Reclassify NS-04 Type from `code (cross-plan PR pair, internally a 3-step sequence)` to `code` (matches NS-01/NS-05/NS-07 precedent for substrate-level multi-PR work; the "3-step sequence" wording lives in Upstream prose, not the Type label). The old type triggered `type_signature_mismatch` against the script verifier on every NS-04 PR because each individual step ships code-only or governance-only, not docs+code together. - Extend References with the two target code paths (`packages/contracts/src/pty-host.ts` + `packages/runtime-daemon/src/session/spawn-cwd-translator.ts`) so `verifyFileOverlap` accepts code-only touched sets against the row. - Flip NS-04 Status `todo` → `in_progress` (last shipped: PR #45, 2026-05-11). PR-row (b) Plan-001 T5.4 still owed before NS-04 → `completed`; mermaid NS04 node stays `:::ready` (only flips to `:::completed` when all PR-rows ticked). - Tick `[ ] T-024-2-1` PR-row → `[x] T-024-2-1 (PR #45, merged 2026-05-11)`. - Re-derive §6 ready-set prose: NS-04 PR-A drops out → ready set shrinks from 6 to 5 (NS-03, NS-11, NS-13a, NS-14, NS-22). NS-05 + NS-07 remain gated on NS-04 completion (PR-row b T5.4); PR-row (a) shipping the interface alone is not transitively unblocking. Plan-024 Progress Log (shipment manifest): - Append PR #45 entry for T-024-2-1 (phase: 2, pr: 45, sha: ed71ee1) — runtime-callable PtyHost interface, Uint8Array byte payloads, ADR-019 §Decision item 1 coverage, no invariants (I-024-* land at the daemon ↔ sidecar boundary at Phase 3). - Append PR #46 entry as maintenance/refinement of T-024-2-1 (phase: 2, pr: 46, sha: e4520f2) — Buffer→Uint8Array contract fix + onExit JSDoc + Plan-024:89/296 plan amendment. Not a new task ship; documents the cleanup round-trip on the T-024-2-1 surface. Concerns (do not block merge): - `plan_checklist_not_found`: Plan-024 has only a whole-plan Done Checklist; defer ticks until Plan-024 completes end-to-end (matches PR #43 precedent for the NS-01 housekeeping pass). - NS-04 row type was authored before the actual PR-shape was known — reclassifying to `code` aligns it with NS-01 precedent. Refs: NS-04, Plan-024

Phase E auto-housekeeping for Plan-001 T5.4 (PR #48, de47f65) — second and final sub-task in the NS-04 multi-PR pair (T-024-2-1 PtyHost interface + T5.4 cwd-translator now closing together). Catalog (cross-plan-dependencies.md §6 NS-04): - Flip NS-04 Status `in_progress` (last shipped: PR #45) → `completed` (resolved 2026-05-11 via PR #48 — `spawn-cwd-translator.ts` consumes the `PtyHost` interface shipped in PR #45; both PR-rows ticked). - Mermaid: NS04 class `:::ready` → `:::completed`. - Tick PR-row (b) T5.4 with `(PR #48, merged 2026-05-11)` annotation. - Line-cite drift fix: NS-04 References `Plan-001:387-389` → `:389-391` (the T5.4 row sat at 387-389 when authored; post-Phase-5 plan growth shifted it to 389-391). Catalog (NS-05 promotion — derived from NS-04 completion): - NS-05 (Plan-024 Phase 2 NodePtyHost) promotes from `blocked` → `ready`. Its only two upstream NS-XX entries (NS-01 + NS-04) are both now `completed`. Mermaid: NS-05 moves from BLOCKED-section to the READY-section listing; class `:::blocked` → `:::ready`. - NS-07 (Plan-024 Phase 3 RustSidecarPtyHost) advances one upstream-dep closer but stays `blocked` on NS-05. No state-flip. Catalog (§6 'Recommended first wave' prose): - Re-derive ready set: 5 → 6 anchors. NS-04 drops out (now completed); NS-05 promotes in (newly unblocked). Set is NS-03, NS-05, NS-11, NS-13a, NS-14, NS-22. - Dispatch recommendation update: NS-03 + NS-05 as two independent code lanes (apps/desktop/ vs runtime-daemon/pty/); NS-13a + NS-14 + NS-11 + NS-22 as concurrent governance / audit / cleanup lanes. Plan-001 Shipment Manifest: - Append T5.4 entry (phase: 5, pr: 48, sha: de47f65, files: cwd- translator + tests + session/index.ts). No verifies_invariant or spec_coverage cells: T5.4 discharges contractual obligation CP-001-2 and verifies inherited Plan-024 I-024-5 by construction, not directly (no per-test invariant assertion line). - Notes block captures Lane B narrative: dual-strategy translator (cd-prefix + cwd-env), two wrapping shells (POSIX + windows-cmd), 3 Codex round-trips (P2 vacuous test, P2 cmd.exe metachars, P1 args- index drift), `/v:off` DelayedExpansion defense, NS-04/NS-05/NS-07 graph implications. Plan-001 path canonicalization (T5.4 Files line): - `session/test/spawn-cwd-translator.test.ts` → `session/__tests__/spawn-cwd-translator.test.ts`. Plan written pre-implementation with `test/` placeholder; actual delivery used Vitest's `__tests__/` convention for both unit and Windows-CI tests. Mirrors PR #46 Plan-024:89/296 path-canonicalization precedent. Concerns (do not block merge): - `plan_checklist_not_found`: Plan-001 has only a whole-plan Done Checklist; defer ticks until Plan-001 completes end-to-end. Matches PR #43 + PR #47 precedent for substrate-level multi-PR work. - docs/superpowers/specs/2026-05-03-plan-execution-housekeeper-design.md contains a frozen NS-04 reference snapshot (line 41-50, Status: `todo`, line cite :387-389) — intentionally NOT updated; that doc is a frozen design-time spec, not a live mirror of cross-plan-deps. Refs: NS-04, NS-05, Plan-001, Plan-024 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…49) Reverts 3b900a6 (`chore(repo): housekeeping for PR #48 — NS-04 PR-B (T5.4 cwd-translator)`), which was direct-pushed to `develop` instead of following the PR-precedent that prior housekeeping commits (#43, #47) used. The content was correct (NS-04 → completed, NS-05 promoted to ready, Plan-001 T5.4 shipment manifest entry, line-cite drift fix, path canonicalization) but the route bypassed Codex auto-review and the branch-protection PR gate (admin direct-push bypass, not force- push). This revert reopens the housekeeping for routing through a clean PR — a follow-up `chore/plan-001-pr48-housekeeping` branch will re-apply 3b900a6's content and Codex will review it. Net effect of this PR: roll develop back to the post-PR-#48 state (de47f65 content-wise). NS-04 returns to `in_progress (last shipped: PR #45, 2026-05-11)`, NS-05 returns to `blocked`, T5.4 shipment manifest entry removed from Plan-001, line cite reverts to `:387-389`, Plan-001 path returns to `session/test/...`. Re-applied immediately via the follow-up PR. Refs: NS-04, NS-05, Plan-001, Plan-024 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…r) (#50) Phase E auto-housekeeping for Plan-001 T5.4 (PR #48, de47f65) — second and final sub-task in the NS-04 multi-PR pair (T-024-2-1 PtyHost interface + T5.4 cwd-translator now closing together). Catalog (cross-plan-dependencies.md §6 NS-04): - Flip NS-04 Status `in_progress` (last shipped: PR #45) → `completed` (resolved 2026-05-11 via PR #48 — `spawn-cwd-translator.ts` consumes the `PtyHost` interface shipped in PR #45; both PR-rows ticked). - Mermaid: NS04 class `:::ready` → `:::completed`. - Tick PR-row (b) T5.4 with `(PR #48, merged 2026-05-11)` annotation. - Line-cite drift fix: NS-04 References `Plan-001:387-389` → `:389-391` (the T5.4 row sat at 387-389 when authored; post-Phase-5 plan growth shifted it to 389-391). Catalog (NS-05 promotion — derived from NS-04 completion): - NS-05 (Plan-024 Phase 2 NodePtyHost) promotes from `blocked` → `ready`. Its only two upstream NS-XX entries (NS-01 + NS-04) are both now `completed`. Mermaid: NS-05 moves from BLOCKED-section to the READY-section listing; class `:::blocked` → `:::ready`. - NS-07 (Plan-024 Phase 3 RustSidecarPtyHost) advances one upstream-dep closer but stays `blocked` on NS-05. No state-flip. Catalog (§6 'Recommended first wave' prose): - Re-derive ready set: 5 → 6 anchors. NS-04 drops out (now completed); NS-05 promotes in (newly unblocked). Set is NS-03, NS-05, NS-11, NS-13a, NS-14, NS-22. - Dispatch recommendation update: NS-03 + NS-05 as two independent code lanes (apps/desktop/ vs runtime-daemon/pty/); NS-13a + NS-14 + NS-11 + NS-22 as concurrent governance / audit / cleanup lanes. Plan-001 Shipment Manifest: - Append T5.4 entry (phase: 5, pr: 48, sha: de47f65, files: cwd- translator + tests + session/index.ts). No verifies_invariant or spec_coverage cells: T5.4 discharges contractual obligation CP-001-2 and verifies inherited Plan-024 I-024-5 by construction, not directly (no per-test invariant assertion line). - Notes block captures Lane B narrative: dual-strategy translator (cd-prefix + cwd-env), two wrapping shells (POSIX + windows-cmd), 3 Codex round-trips (P2 vacuous test, P2 cmd.exe metachars, P1 args- index drift), `/v:off` DelayedExpansion defense, NS-04/NS-05/NS-07 graph implications. Plan-001 path canonicalization (T5.4 Files line): - `session/test/spawn-cwd-translator.test.ts` → `session/__tests__/spawn-cwd-translator.test.ts`. Plan written pre-implementation with `test/` placeholder; actual delivery used Vitest's `__tests__/` convention for both unit and Windows-CI tests. Mirrors PR #46 Plan-024:89/296 path-canonicalization precedent. Concerns (do not block merge): - `plan_checklist_not_found`: Plan-001 has only a whole-plan Done Checklist; defer ticks until Plan-001 completes end-to-end. Matches PR #43 + PR #47 precedent for substrate-level multi-PR work. - docs/superpowers/specs/2026-05-03-plan-execution-housekeeper-design.md contains a frozen NS-04 reference snapshot (line 41-50, Status: `todo`, line cite :387-389) — intentionally NOT updated; that doc is a frozen design-time spec, not a live mirror of cross-plan-deps. Refs: NS-04, NS-05, Plan-001, Plan-024 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Phase E auto-housekeeping for Plan-024 Phase 2 closeout (PR #51, 1c4e75a) — T-024-2-2 (`NodePtyHost` + Windows kill-translation per I-024-1 + I-024-2) and T-024-2-3 (`PtyHostSelector` + `AIS_PTY_BACKEND` env-var grammar per F-024-2-07) shipped together; T-024-2-1 (`PtyHost` interface) shipped earlier in PR #45/#46. Catalog (cross-plan-dependencies.md §6 NS-05): - Flip NS-05 Status `ready` → `completed` (resolved 2026-05-11 via PR #51 — composed prose cites Test K1 + Test K3 satisfying I-024-1 + I-024-2 inside the node-pty code path, closes the F-024-2-05 test- side mirror gap, F-024-2-02 default-Node posture live, ADR-019 Tripwire 3 `useConptyDll: false` retained, and the NS-07 unblock). - Mermaid: NS-05 class `:::ready` → `:::completed`. Catalog (NS-07 promotion — derived from NS-05 completion): - NS-07 (Plan-024 Phase 3 RustSidecarPtyHost) promotes from `blocked` → `ready`. Its only upstream NS-XX entry (NS-05) is now `completed`. Mermaid: NS-07 moves from BLOCKED section to READY section; class `:::blocked` → `:::ready`. Edge wiring (`NS04 → NS07`, `NS05 → NS07`, `NS07 → NS08`, `NS07 → NS09`) untouched and remains semantically valid post-promotion. Catalog (§6 'Recommended first wave' prose): - Re-derive ready set: NS-05 drops out (now completed); NS-07 promotes in (newly unblocked). Set remains 6 items: NS-03, NS-07, NS-11, NS-13a, NS-14, NS-22. Dispatch recommendation updated from NS-03 + NS-05 to NS-03 + NS-07 with explicit RustSidecarPtyHost target paths. - Closing sentence rewrites the NS-04 → NS-05 → NS-07 cascade as exhausted on the Plan-024 critical path; names NS-09 + NS-10 (Plan-024 Phases 4 + 5) as the next downstream gates behind NS-07. Plan-024 Shipment Manifest: - Append PR #51 entry (phase: 2, task: [T-024-2-2, T-024-2-3], sha: 1c4e75a, files: 9 — node-pty-host.ts + pty-host-selector.ts + 4 test files + _fakes.ts + package.json/pnpm-workspace.yaml/pnpm-lock.yaml). - verifies_invariant: [I-024-1, I-024-2] (T-024-2-2's audit Tasks-row cites; T-024-2-3 verifies none per selector-is-config-layer audit notation). - spec_coverage: [ADR-019 §Decision item 1, ADR-019 §Failure Mode Analysis]. - Notes block captures: `koffi` FFI for `GenerateConsoleCtrlEvent`, `node-pty@^1.2.0-beta.12` pin + Tripwire 3 `useConptyDll: false`, `allowBuilds:` allowlist for `koffi` + `node-pty` postinstall per pnpm v10 strict-dep-builds policy, Phase D round-1 absorption (1 ACTIONABLE + 3 POLISH in 847ffd2 + rescued stashed T-024-2-3 R2 polish from lefthook), and Codex external-reviewer round-trip P1 + P2 fixes in 68e29c5 with the close-during-SIGTERM-escalation-race + SIGKILL non-blocking ordering-proof tests. Concerns (do not block merge): - `plan_checklist_not_found`: Plan-024 has only a whole-plan Done Checklist (the per-platform CI row + Windows-signing rows cannot flip until Phase 4); defer ticks until Plan-024 completes end-to-end. Matches PR #47 + PR #50 precedent for substrate-level multi-PR work (script exit code 3). - `orchestrator_applied_semantic_edits`: The `plan-execution-housekeeper` subagent was dispatched twice; both returns reported `RESULT: DONE` but with runtime `tool_uses: 0` — the subagent narrated tool calls as text without invoking them. The orchestrator applied the 3 semantic edits directly with user authorization (one-time deviation from the no-implementation hard rule). TaskList task #13 tracks the post-mortem. Refs: NS-05, NS-07, Plan-024 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…55) Two related fixes that unblock plan-execution-housekeeper and plan-execution-contract-author dispatches. YAML registration: Claude Code's session-start parser handled `tools: ["Read", ...]` flow-form inconsistently — same byte format parsed as a real array for some agents, as a literal string for these two, leaving zero tools registered ("No such tool available"). Switch to block-list YAML form so the parser registers the tool array reliably. Narration anti-pattern: agent bodies contained literal `Tool: <Name>` strings in failure-mode warnings and "do not output X" sections. Opus 4.7's literal instruction following caused the model to emit those tokens as text content instead of invoking the tool API (totalToolUseCount: 0 across PR #36 / #42 / #45 / #51 dispatches). Replace with positive-only action contracts; let the orchestrator's existing validator (check #13, narration_mode_detected) and auto-deviation fallback handle the defense-in-depth. Housekeeper cleanup: consolidate duplicate `## First action (mandatory)` into `## Manifest contents` so each heading has a single, distinct purpose. Validation: post-restart smoke tests exercise both agents end-to-end (housekeeper edits target.md + writes manifest preserving _script_stage; contract-author writes a Zod schema file). All 393 plan-execution skill tests pass (including the buildHousekeeperPrompt snapshot test that pins the orchestrator's runtime brief), all 411 package tests pass, typecheck and lint clean. Builds on the guardrails landed in #53. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Sawmonabo and others added 2 commits May 11, 2026 03:14

chore(repo): scaffold Plan-024 Phase 2 NS-04 PR-A (T-024-2-1)

10c4620

Sawmonabo marked this pull request as ready for review May 11, 2026 07:26

Sawmonabo merged commit ed71ee1 into develop May 11, 2026
8 checks passed

Sawmonabo deleted the feat/plan-024-phase-2-contracts branch May 11, 2026 07:26

github-actions Bot mentioned this pull request May 11, 2026

chore: release develop #7

Open

This was referenced May 11, 2026

refactor(contracts): clean PtyHost interface (Uint8Array + JSDoc) #46

Merged

chore(repo): housekeeping for PR #45 — NS-04 partial (T-024-2-1) #47

Merged

Sawmonabo mentioned this pull request May 11, 2026

feat(daemon): spawn-cwd-translator (Plan-001 T5.4) #48

Merged

3 tasks

Sawmonabo mentioned this pull request May 11, 2026

chore(repo): housekeeping for PR #48 — NS-04 PR-B (T5.4 cwd-translator) #50

Merged

4 tasks

Sawmonabo mentioned this pull request May 11, 2026

feat(daemon): NodePtyHost + PtyHostSelector (Plan-024 Phase 2) #51

Merged

6 tasks

This was referenced May 11, 2026

chore(repo): add plan-execution housekeeper narration-mode guardrails #53

Merged

chore(repo): resolve subagent narration + tool-registration failures #55

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(contracts): add PtyHost interface (Plan-024 T-024-2-1)#45

feat(contracts): add PtyHost interface (Plan-024 T-024-2-1)#45
Sawmonabo merged 2 commits into
developfrom
feat/plan-024-phase-2-contracts

Sawmonabo commented May 11, 2026

Uh oh!

Sawmonabo commented May 11, 2026

Uh oh!

chatgpt-codex-connector Bot commented May 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Sawmonabo commented May 11, 2026

Summary

Test plan

References

Uh oh!

Sawmonabo commented May 11, 2026

Uh oh!

chatgpt-codex-connector Bot commented May 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant