PR 022 P3: Clarify hardening cleanup contract

[LogicDuke]

Quarantined stacked validation PR beneath PR #22

This is a quarantined stacked validation PR created beneath PR #22. It targets the PR #22 repair branch (repair/pr010-cr1-contract-clarification) and not main and not the PR #10 feature branch (pr-010/commander-claude-bridge).

Finding

• Finding ID: PR22-CODEX-P3-CLEANUP-CLAIM
• Classification: CURRENT
• Severity: P3
• Original title: Describe the partial hardening cleanup accurately

The finding was independently reproduced against PR #22 HEAD 5ae74353289b936a2d1c609633c03d54b9e8c65d.

Scope of the repair

The repair is documentation/JSDoc only.

• Executable runtime behavior is unchanged.
• Tests are unchanged.
• child.stdin behavior is unchanged.
• Spawn-failure absorber behavior is unchanged.
• Termination behavior is unchanged.
• No termination-success guarantee is introduced.
• No descendant-termination guarantee is introduced.

Change surface

Exactly two files changed:

• docs/architecture/010-commander-claude-bridge.md

• src/adapters/process-transport.ts

• Child commit: 87fc6b8acb0199399bfa248338fce71c228a872a

• Validated patch SHA-256: 0D4A582C3F4F32B5D1B498132F82EC4F48B51AA3B9EE1F0CD4EB12A2A6CA34AF

Validation performed locally

Fresh independent validation passed. All of the following passed prior to commit:

• Focused hardening tests passed.
• Complete process transport tests passed.
• Full npm test passed.
• Typecheck passed.
• Lint passed.
• Build passed.
• git diff --check passed.

Not yet performed: CodeRabbit and Codex have not reviewed this child PR yet, and CI on this PR has not been observed passing yet. Those are separate later gates.

Architecture and authority

• Frozen architecture is unchanged.
• V1 authority remains unchanged.

Integration constraints

• PR PR 010 CR-1: Clarify process transport contract #22 must remain untouched until this child passes GitHub review and CI.
• Human merge authority is required.
• Merge method must be create a merge commit only.
• After child integration, PR PR 010 CR-1: Clarify process transport contract #22 must be re-audited at its new HEAD.

Summary by CodeRabbit

• Bug Fixes
  • Improved handling when a spawned process fails during post-launch setup.
  • Processes are now terminated within a bounded timeframe using platform-appropriate behavior.
  • Local output streams are cleaned up reliably, preventing lingering resources and event handling.
  • Standard input remains unchanged during failure cleanup.
  • Operational failures continue to be reported through the appropriate rejection and outcome mechanisms.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6aa9a9a0-65e0-4d20-b4c4-cbd1be1fbab9

📥 Commits

Reviewing files that changed from the base of the PR and between 5ae7435 and 87fc6b8.

📒 Files selected for processing (2)

• docs/architecture/010-commander-claude-bridge.md
• src/adapters/process-transport.ts

Included review availability: Your plan includes up to 1 review per rolling hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The post-spawn hardening failure path now uses bounded termination, destroys local stdout and stderr streams, clears listeners, re-arms spawn-failure handling, preserves stdin, and rejects. The rejection remains separate from SPAWN_FAILED.

Changes

Post-spawn hardening cleanup

Layer / File(s)	Summary
Hardening-failure cleanup behavior src/adapters/process-transport.ts, docs/architecture/010-commander-claude-bridge.md	The documented failure path performs qualified termination, destroys stdout and stderr, clears listeners, re-arms the spawn-failure absorber, preserves stdin, and rejects. It retains defined-failure catch semantics and distinguishes the rejection from SPAWN_FAILED.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 87fc6

This PR only clarifies the hardening cleanup contract without changing runtime behavior, tests, or termination guarantees; no actionable merge-blocking risk remains beyond normal checks and review.

Poem

I’m a rabbit with tidy pipes,
Closing streams on failing nights.
Stdin stays, listeners clear,
Spawn alarms return near.
Then rejection hops away.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: clarifying the hardening cleanup contract in documentation and JSDoc.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch repair/pr022-hardening-cleanup-claim

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[LogicDuke]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[LogicDuke]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Swish!

Reviewed commit: 87fc6b8acb

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