fix(runtime): join PTY finalization after a racing persist

[1625567290]

Summary

joins finalization when a real PTY exits before a queued control cut failed on CI with expected completed, got running even though #3075 did not touch runtime. Re-running the same commit passed.

writeStdin asked persistObservation whether to join finalization at call time. A real PTY can exit while that persist is still in flight, so the control returned the running snapshot. After persist, if driverExit / finalizeOnce is set, join the terminal record.

The test no longer assumes that first snapshot is already terminal: if it is still running, it waits with waitForTerminalShellRun (15s) before asserting completed.

Fixes#3077

Verification

• npm --workspace @maka/core run build
• npm --workspace @maka/runtime run build
• node --test --test-name-pattern 'joins finalization when a real PTY exits before a queued control cut' packages/runtime/dist/__tests__/shell-run-manager.test.js — 5/5 repeats
• Nearby queued-control cases — 3/3
• Full shell-run-manager.test.js — 57 pass, 3 skip (Windows PowerShell)
• biome check on the two files — clean

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope:

Grok authored the implementation, tests, and this PR description.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7be63958-f9a8-4f80-9f40-2e13e1eeab49

📥 Commits

Reviewing files that changed from the base of the PR and between 63f2702 and c562830.

📒 Files selected for processing (1)

• packages/runtime/src/__tests__/shell-run-manager.test.ts

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

Problem solved

writeStdin could return a stale running snapshot when the PTY exited while persistObservation was in flight. The change re-joins finalization when driverExit or finalizeOnce indicates that finalization has started. This allows writeStdin to return the terminal record.

The test now waits for a terminal shell-run snapshot before it asserts completed, output dimensions, and revision consistency. It also covers PTY finalization during persistence, including resize, driver disposal, and cleanup.

Design assessment

The change extends the existing PTY finalization and durable observation flow. It does not create a parallel source of truth or change a public contract.

The production fix is small and located at the race point. The test synchronization and added regression coverage are necessary to verify asynchronous finalization. No deletion or simplification is evident without weakening coverage.

Validation and risks

Reported validation includes successful builds, targeted and full test passes, and clean Biome checks. Direct evidence of the current required-check status is unavailable, so that status remains unverified.

The main behavioral risk is that writeStdin can now wait for terminal finalization instead of returning an intermediate running snapshot when PTY exit or finalization has begun. The added wait could affect timing under those conditions. The regression tests cover this race and related cleanup behavior.

Review-relevant risks

No protected-area effect was identified in the current diff. The person performing the merge reviews the final diff, and a maintainer makes the final determination.

Walkthrough

writeStdin now joins PTY finalization when exit or finalization begins after persistence. The tests wait for the terminal snapshot before checking completion, dimensions, durable revision, and cleanup.

Changes

PTY finalization synchronization

Layer / File(s)	Summary
Join finalization and validate terminal state packages/runtime/src/shell-run-manager.ts, packages/runtime/src/__tests__/shell-run-manager.test.ts	writeStdin now waits for live.finished, marks the terminal record observed, and returns it. The tests cover terminal snapshots, PTY disposal, resize, final dimensions, and durable revision.

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

Merge Risk:⚪ Minimal · up to c5628

This localized runtime change ensures PTY runs reach their terminal record after a racing persist; no actionable merge-blocking risk remains after normal checks.

Suggested reviewers:m4n5ter, astro-han, jackwener

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the PTY finalization race fix.
Description check	✅ Passed	The description includes the problem, issue reference, implementation, verification results, AI disclosure, and completed checklist items.
Linked Issues check	✅ Passed	The implementation and tests address issue #3077 by joining PTY finalization after persistence races and waiting for terminal state.
Out of Scope Changes check	✅ Passed	All changes are limited to PTY finalization behavior and tests required by issue #3077.
Ai Use Disclosure	✅ Passed	The PR selects generative tooling and names Grok with scope; both introduced commits have standalone Generated-by: Grok trailers.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d3a6126-a1e6-4364-bf74-587d6dd3c61b

📥 Commits

Reviewing files that changed from the base of the PR and between 62cded2 and 63f2702.

📒 Files selected for processing (2)

• packages/runtime/src/__tests__/shell-run-manager.test.ts
• packages/runtime/src/shell-run-manager.ts

[M4n5ter]

LGTM

[1625567290]

Summary

joins finalization when a real PTY exits before a queued control cut failed on CI with expected completed, got running even though #3075 did not touch runtime. Re-running the same commit passed.

writeStdin asked persistObservation whether to join finalization at call time. A real PTY can exit while that persist is still in flight, so the control returned the running snapshot. After persist, if driverExit / finalizeOnce is set, join the terminal record.

The test no longer assumes that first snapshot is already terminal: if it is still running, it waits with waitForTerminalShellRun (15s) before asserting completed.

Fixes#3077

Verification

• npm --workspace @maka/core run build
• npm --workspace @maka/runtime run build
• node --test --test-name-pattern 'joins finalization when a real PTY exits before a queued control cut' packages/runtime/dist/__tests__/shell-run-manager.test.js — 5/5 repeats
• Nearby queued-control cases — 3/3
• Full shell-run-manager.test.js — 57 pass, 3 skip (Windows PowerShell)
• biome check on the two files — clean

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope:

Grok authored the implementation, tests, and this PR description.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7be63958-f9a8-4f80-9f40-2e13e1eeab49

📥 Commits

Reviewing files that changed from the base of the PR and between 63f2702 and c562830.

📒 Files selected for processing (1)

• packages/runtime/src/__tests__/shell-run-manager.test.ts

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

Problem solved

writeStdin could return a stale running snapshot when the PTY exited while persistObservation was in flight. The change re-joins finalization when driverExit or finalizeOnce indicates that finalization has started. This allows writeStdin to return the terminal record.

The test now waits for a terminal shell-run snapshot before it asserts completed, output dimensions, and revision consistency. It also covers PTY finalization during persistence, including resize, driver disposal, and cleanup.

Design assessment

The change extends the existing PTY finalization and durable observation flow. It does not create a parallel source of truth or change a public contract.

The production fix is small and located at the race point. The test synchronization and added regression coverage are necessary to verify asynchronous finalization. No deletion or simplification is evident without weakening coverage.

Validation and risks

Reported validation includes successful builds, targeted and full test passes, and clean Biome checks. Direct evidence of the current required-check status is unavailable, so that status remains unverified.

The main behavioral risk is that writeStdin can now wait for terminal finalization instead of returning an intermediate running snapshot when PTY exit or finalization has begun. The added wait could affect timing under those conditions. The regression tests cover this race and related cleanup behavior.

Review-relevant risks

No protected-area effect was identified in the current diff. The person performing the merge reviews the final diff, and a maintainer makes the final determination.

Walkthrough

writeStdin now joins PTY finalization when exit or finalization begins after persistence. The tests wait for the terminal snapshot before checking completion, dimensions, durable revision, and cleanup.

Changes

PTY finalization synchronization

Layer / File(s)	Summary
Join finalization and validate terminal state packages/runtime/src/shell-run-manager.ts, packages/runtime/src/__tests__/shell-run-manager.test.ts	writeStdin now waits for live.finished, marks the terminal record observed, and returns it. The tests cover terminal snapshots, PTY disposal, resize, final dimensions, and durable revision.

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

Merge Risk:⚪ Minimal · up to c5628

This localized runtime change ensures PTY runs reach their terminal record after a racing persist; no actionable merge-blocking risk remains after normal checks.

Suggested reviewers:m4n5ter, astro-han, jackwener

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the PTY finalization race fix.
Description check	✅ Passed	The description includes the problem, issue reference, implementation, verification results, AI disclosure, and completed checklist items.
Linked Issues check	✅ Passed	The implementation and tests address issue #3077 by joining PTY finalization after persistence races and waiting for terminal state.
Out of Scope Changes check	✅ Passed	All changes are limited to PTY finalization behavior and tests required by issue #3077.
Ai Use Disclosure	✅ Passed	The PR selects generative tooling and names Grok with scope; both introduced commits have standalone Generated-by: Grok trailers.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d3a6126-a1e6-4364-bf74-587d6dd3c61b

📥 Commits

Reviewing files that changed from the base of the PR and between 62cded2 and 63f2702.

📒 Files selected for processing (2)

• packages/runtime/src/__tests__/shell-run-manager.test.ts
• packages/runtime/src/shell-run-manager.ts

[M4n5ter]

LGTM

[1625567290]

Summary

joins finalization when a real PTY exits before a queued control cut failed on CI with expected completed, got running even though #3075 did not touch runtime. Re-running the same commit passed.

writeStdin asked persistObservation whether to join finalization at call time. A real PTY can exit while that persist is still in flight, so the control returned the running snapshot. After persist, if driverExit / finalizeOnce is set, join the terminal record.

The test no longer assumes that first snapshot is already terminal: if it is still running, it waits with waitForTerminalShellRun (15s) before asserting completed.

Fixes#3077

Verification

• npm --workspace @maka/core run build
• npm --workspace @maka/runtime run build
• node --test --test-name-pattern 'joins finalization when a real PTY exits before a queued control cut' packages/runtime/dist/__tests__/shell-run-manager.test.js — 5/5 repeats
• Nearby queued-control cases — 3/3
• Full shell-run-manager.test.js — 57 pass, 3 skip (Windows PowerShell)
• biome check on the two files — clean

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope:

Grok authored the implementation, tests, and this PR description.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7be63958-f9a8-4f80-9f40-2e13e1eeab49

📥 Commits

Reviewing files that changed from the base of the PR and between 63f2702 and c562830.

📒 Files selected for processing (1)

• packages/runtime/src/__tests__/shell-run-manager.test.ts

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

Problem solved

writeStdin could return a stale running snapshot when the PTY exited while persistObservation was in flight. The change re-joins finalization when driverExit or finalizeOnce indicates that finalization has started. This allows writeStdin to return the terminal record.

The test now waits for a terminal shell-run snapshot before it asserts completed, output dimensions, and revision consistency. It also covers PTY finalization during persistence, including resize, driver disposal, and cleanup.

Design assessment

The change extends the existing PTY finalization and durable observation flow. It does not create a parallel source of truth or change a public contract.

The production fix is small and located at the race point. The test synchronization and added regression coverage are necessary to verify asynchronous finalization. No deletion or simplification is evident without weakening coverage.

Validation and risks

Reported validation includes successful builds, targeted and full test passes, and clean Biome checks. Direct evidence of the current required-check status is unavailable, so that status remains unverified.

The main behavioral risk is that writeStdin can now wait for terminal finalization instead of returning an intermediate running snapshot when PTY exit or finalization has begun. The added wait could affect timing under those conditions. The regression tests cover this race and related cleanup behavior.

Review-relevant risks

No protected-area effect was identified in the current diff. The person performing the merge reviews the final diff, and a maintainer makes the final determination.

Walkthrough

writeStdin now joins PTY finalization when exit or finalization begins after persistence. The tests wait for the terminal snapshot before checking completion, dimensions, durable revision, and cleanup.

Changes

PTY finalization synchronization

Layer / File(s)	Summary
Join finalization and validate terminal state packages/runtime/src/shell-run-manager.ts, packages/runtime/src/__tests__/shell-run-manager.test.ts	writeStdin now waits for live.finished, marks the terminal record observed, and returns it. The tests cover terminal snapshots, PTY disposal, resize, final dimensions, and durable revision.

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

Merge Risk:⚪ Minimal · up to c5628

This localized runtime change ensures PTY runs reach their terminal record after a racing persist; no actionable merge-blocking risk remains after normal checks.

Suggested reviewers:m4n5ter, astro-han, jackwener

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the PTY finalization race fix.
Description check	✅ Passed	The description includes the problem, issue reference, implementation, verification results, AI disclosure, and completed checklist items.
Linked Issues check	✅ Passed	The implementation and tests address issue #3077 by joining PTY finalization after persistence races and waiting for terminal state.
Out of Scope Changes check	✅ Passed	All changes are limited to PTY finalization behavior and tests required by issue #3077.
Ai Use Disclosure	✅ Passed	The PR selects generative tooling and names Grok with scope; both introduced commits have standalone Generated-by: Grok trailers.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d3a6126-a1e6-4364-bf74-587d6dd3c61b

📥 Commits

Reviewing files that changed from the base of the PR and between 62cded2 and 63f2702.

📒 Files selected for processing (2)

• packages/runtime/src/__tests__/shell-run-manager.test.ts
• packages/runtime/src/shell-run-manager.ts

[M4n5ter]

LGTM

[1625567290]

Summary

joins finalization when a real PTY exits before a queued control cut failed on CI with expected completed, got running even though #3075 did not touch runtime. Re-running the same commit passed.

writeStdin asked persistObservation whether to join finalization at call time. A real PTY can exit while that persist is still in flight, so the control returned the running snapshot. After persist, if driverExit / finalizeOnce is set, join the terminal record.

The test no longer assumes that first snapshot is already terminal: if it is still running, it waits with waitForTerminalShellRun (15s) before asserting completed.

Fixes#3077

Verification

• npm --workspace @maka/core run build
• npm --workspace @maka/runtime run build
• node --test --test-name-pattern 'joins finalization when a real PTY exits before a queued control cut' packages/runtime/dist/__tests__/shell-run-manager.test.js — 5/5 repeats
• Nearby queued-control cases — 3/3
• Full shell-run-manager.test.js — 57 pass, 3 skip (Windows PowerShell)
• biome check on the two files — clean

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope:

Grok authored the implementation, tests, and this PR description.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7be63958-f9a8-4f80-9f40-2e13e1eeab49

📥 Commits

Reviewing files that changed from the base of the PR and between 63f2702 and c562830.

📒 Files selected for processing (1)

• packages/runtime/src/__tests__/shell-run-manager.test.ts

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

Problem solved

writeStdin could return a stale running snapshot when the PTY exited while persistObservation was in flight. The change re-joins finalization when driverExit or finalizeOnce indicates that finalization has started. This allows writeStdin to return the terminal record.

The test now waits for a terminal shell-run snapshot before it asserts completed, output dimensions, and revision consistency. It also covers PTY finalization during persistence, including resize, driver disposal, and cleanup.

Design assessment

The change extends the existing PTY finalization and durable observation flow. It does not create a parallel source of truth or change a public contract.

The production fix is small and located at the race point. The test synchronization and added regression coverage are necessary to verify asynchronous finalization. No deletion or simplification is evident without weakening coverage.

Validation and risks

Reported validation includes successful builds, targeted and full test passes, and clean Biome checks. Direct evidence of the current required-check status is unavailable, so that status remains unverified.

The main behavioral risk is that writeStdin can now wait for terminal finalization instead of returning an intermediate running snapshot when PTY exit or finalization has begun. The added wait could affect timing under those conditions. The regression tests cover this race and related cleanup behavior.

Review-relevant risks

No protected-area effect was identified in the current diff. The person performing the merge reviews the final diff, and a maintainer makes the final determination.

Walkthrough

writeStdin now joins PTY finalization when exit or finalization begins after persistence. The tests wait for the terminal snapshot before checking completion, dimensions, durable revision, and cleanup.

Changes

PTY finalization synchronization

Layer / File(s)	Summary
Join finalization and validate terminal state packages/runtime/src/shell-run-manager.ts, packages/runtime/src/__tests__/shell-run-manager.test.ts	writeStdin now waits for live.finished, marks the terminal record observed, and returns it. The tests cover terminal snapshots, PTY disposal, resize, final dimensions, and durable revision.

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

Merge Risk:⚪ Minimal · up to c5628

This localized runtime change ensures PTY runs reach their terminal record after a racing persist; no actionable merge-blocking risk remains after normal checks.

Suggested reviewers:m4n5ter, astro-han, jackwener

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the PTY finalization race fix.
Description check	✅ Passed	The description includes the problem, issue reference, implementation, verification results, AI disclosure, and completed checklist items.
Linked Issues check	✅ Passed	The implementation and tests address issue #3077 by joining PTY finalization after persistence races and waiting for terminal state.
Out of Scope Changes check	✅ Passed	All changes are limited to PTY finalization behavior and tests required by issue #3077.
Ai Use Disclosure	✅ Passed	The PR selects generative tooling and names Grok with scope; both introduced commits have standalone Generated-by: Grok trailers.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d3a6126-a1e6-4364-bf74-587d6dd3c61b

📥 Commits

Reviewing files that changed from the base of the PR and between 62cded2 and 63f2702.

📒 Files selected for processing (2)

• packages/runtime/src/__tests__/shell-run-manager.test.ts
• packages/runtime/src/shell-run-manager.ts

[M4n5ter]

LGTM

[1625567290]

Summary

joins finalization when a real PTY exits before a queued control cut failed on CI with expected completed, got running even though #3075 did not touch runtime. Re-running the same commit passed.

writeStdin asked persistObservation whether to join finalization at call time. A real PTY can exit while that persist is still in flight, so the control returned the running snapshot. After persist, if driverExit / finalizeOnce is set, join the terminal record.

The test no longer assumes that first snapshot is already terminal: if it is still running, it waits with waitForTerminalShellRun (15s) before asserting completed.

Fixes#3077

Verification

• npm --workspace @maka/core run build
• npm --workspace @maka/runtime run build
• node --test --test-name-pattern 'joins finalization when a real PTY exits before a queued control cut' packages/runtime/dist/__tests__/shell-run-manager.test.js — 5/5 repeats
• Nearby queued-control cases — 3/3
• Full shell-run-manager.test.js — 57 pass, 3 skip (Windows PowerShell)
• biome check on the two files — clean

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope:

Grok authored the implementation, tests, and this PR description.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7be63958-f9a8-4f80-9f40-2e13e1eeab49

📥 Commits

Reviewing files that changed from the base of the PR and between 63f2702 and c562830.

📒 Files selected for processing (1)

• packages/runtime/src/__tests__/shell-run-manager.test.ts

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

Problem solved

writeStdin could return a stale running snapshot when the PTY exited while persistObservation was in flight. The change re-joins finalization when driverExit or finalizeOnce indicates that finalization has started. This allows writeStdin to return the terminal record.

The test now waits for a terminal shell-run snapshot before it asserts completed, output dimensions, and revision consistency. It also covers PTY finalization during persistence, including resize, driver disposal, and cleanup.

Design assessment

The change extends the existing PTY finalization and durable observation flow. It does not create a parallel source of truth or change a public contract.

The production fix is small and located at the race point. The test synchronization and added regression coverage are necessary to verify asynchronous finalization. No deletion or simplification is evident without weakening coverage.

Validation and risks

Reported validation includes successful builds, targeted and full test passes, and clean Biome checks. Direct evidence of the current required-check status is unavailable, so that status remains unverified.

The main behavioral risk is that writeStdin can now wait for terminal finalization instead of returning an intermediate running snapshot when PTY exit or finalization has begun. The added wait could affect timing under those conditions. The regression tests cover this race and related cleanup behavior.

Review-relevant risks

No protected-area effect was identified in the current diff. The person performing the merge reviews the final diff, and a maintainer makes the final determination.

Walkthrough

writeStdin now joins PTY finalization when exit or finalization begins after persistence. The tests wait for the terminal snapshot before checking completion, dimensions, durable revision, and cleanup.

Changes

PTY finalization synchronization

Layer / File(s)	Summary
Join finalization and validate terminal state packages/runtime/src/shell-run-manager.ts, packages/runtime/src/__tests__/shell-run-manager.test.ts	writeStdin now waits for live.finished, marks the terminal record observed, and returns it. The tests cover terminal snapshots, PTY disposal, resize, final dimensions, and durable revision.

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

Merge Risk:⚪ Minimal · up to c5628

This localized runtime change ensures PTY runs reach their terminal record after a racing persist; no actionable merge-blocking risk remains after normal checks.

Suggested reviewers:m4n5ter, astro-han, jackwener

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the PTY finalization race fix.
Description check	✅ Passed	The description includes the problem, issue reference, implementation, verification results, AI disclosure, and completed checklist items.
Linked Issues check	✅ Passed	The implementation and tests address issue #3077 by joining PTY finalization after persistence races and waiting for terminal state.
Out of Scope Changes check	✅ Passed	All changes are limited to PTY finalization behavior and tests required by issue #3077.
Ai Use Disclosure	✅ Passed	The PR selects generative tooling and names Grok with scope; both introduced commits have standalone Generated-by: Grok trailers.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d3a6126-a1e6-4364-bf74-587d6dd3c61b

📥 Commits

Reviewing files that changed from the base of the PR and between 62cded2 and 63f2702.

📒 Files selected for processing (2)

• packages/runtime/src/__tests__/shell-run-manager.test.ts
• packages/runtime/src/shell-run-manager.ts

[M4n5ter]

LGTM

[1625567290]

Summary

joins finalization when a real PTY exits before a queued control cut failed on CI with expected completed, got running even though #3075 did not touch runtime. Re-running the same commit passed.

writeStdin asked persistObservation whether to join finalization at call time. A real PTY can exit while that persist is still in flight, so the control returned the running snapshot. After persist, if driverExit / finalizeOnce is set, join the terminal record.

The test no longer assumes that first snapshot is already terminal: if it is still running, it waits with waitForTerminalShellRun (15s) before asserting completed.

Fixes#3077

Verification

• npm --workspace @maka/core run build
• npm --workspace @maka/runtime run build
• node --test --test-name-pattern 'joins finalization when a real PTY exits before a queued control cut' packages/runtime/dist/__tests__/shell-run-manager.test.js — 5/5 repeats
• Nearby queued-control cases — 3/3
• Full shell-run-manager.test.js — 57 pass, 3 skip (Windows PowerShell)
• biome check on the two files — clean

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope:

Grok authored the implementation, tests, and this PR description.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7be63958-f9a8-4f80-9f40-2e13e1eeab49

📥 Commits

Reviewing files that changed from the base of the PR and between 63f2702 and c562830.

📒 Files selected for processing (1)

• packages/runtime/src/__tests__/shell-run-manager.test.ts

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

Problem solved

writeStdin could return a stale running snapshot when the PTY exited while persistObservation was in flight. The change re-joins finalization when driverExit or finalizeOnce indicates that finalization has started. This allows writeStdin to return the terminal record.

The test now waits for a terminal shell-run snapshot before it asserts completed, output dimensions, and revision consistency. It also covers PTY finalization during persistence, including resize, driver disposal, and cleanup.

Design assessment

The change extends the existing PTY finalization and durable observation flow. It does not create a parallel source of truth or change a public contract.

The production fix is small and located at the race point. The test synchronization and added regression coverage are necessary to verify asynchronous finalization. No deletion or simplification is evident without weakening coverage.

Validation and risks

Reported validation includes successful builds, targeted and full test passes, and clean Biome checks. Direct evidence of the current required-check status is unavailable, so that status remains unverified.

The main behavioral risk is that writeStdin can now wait for terminal finalization instead of returning an intermediate running snapshot when PTY exit or finalization has begun. The added wait could affect timing under those conditions. The regression tests cover this race and related cleanup behavior.

Review-relevant risks

No protected-area effect was identified in the current diff. The person performing the merge reviews the final diff, and a maintainer makes the final determination.

Walkthrough

writeStdin now joins PTY finalization when exit or finalization begins after persistence. The tests wait for the terminal snapshot before checking completion, dimensions, durable revision, and cleanup.

Changes

PTY finalization synchronization

Layer / File(s)	Summary
Join finalization and validate terminal state packages/runtime/src/shell-run-manager.ts, packages/runtime/src/__tests__/shell-run-manager.test.ts	writeStdin now waits for live.finished, marks the terminal record observed, and returns it. The tests cover terminal snapshots, PTY disposal, resize, final dimensions, and durable revision.

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

Merge Risk:⚪ Minimal · up to c5628

This localized runtime change ensures PTY runs reach their terminal record after a racing persist; no actionable merge-blocking risk remains after normal checks.

Suggested reviewers:m4n5ter, astro-han, jackwener

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the PTY finalization race fix.
Description check	✅ Passed	The description includes the problem, issue reference, implementation, verification results, AI disclosure, and completed checklist items.
Linked Issues check	✅ Passed	The implementation and tests address issue #3077 by joining PTY finalization after persistence races and waiting for terminal state.
Out of Scope Changes check	✅ Passed	All changes are limited to PTY finalization behavior and tests required by issue #3077.
Ai Use Disclosure	✅ Passed	The PR selects generative tooling and names Grok with scope; both introduced commits have standalone Generated-by: Grok trailers.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d3a6126-a1e6-4364-bf74-587d6dd3c61b

📥 Commits

Reviewing files that changed from the base of the PR and between 62cded2 and 63f2702.

📒 Files selected for processing (2)

• packages/runtime/src/__tests__/shell-run-manager.test.ts
• packages/runtime/src/shell-run-manager.ts

[M4n5ter]

LGTM

[1625567290]

Summary

joins finalization when a real PTY exits before a queued control cut failed on CI with expected completed, got running even though #3075 did not touch runtime. Re-running the same commit passed.

writeStdin asked persistObservation whether to join finalization at call time. A real PTY can exit while that persist is still in flight, so the control returned the running snapshot. After persist, if driverExit / finalizeOnce is set, join the terminal record.

The test no longer assumes that first snapshot is already terminal: if it is still running, it waits with waitForTerminalShellRun (15s) before asserting completed.

Fixes#3077

Verification

• npm --workspace @maka/core run build
• npm --workspace @maka/runtime run build
• node --test --test-name-pattern 'joins finalization when a real PTY exits before a queued control cut' packages/runtime/dist/__tests__/shell-run-manager.test.js — 5/5 repeats
• Nearby queued-control cases — 3/3
• Full shell-run-manager.test.js — 57 pass, 3 skip (Windows PowerShell)
• biome check on the two files — clean

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope:

Grok authored the implementation, tests, and this PR description.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7be63958-f9a8-4f80-9f40-2e13e1eeab49

📥 Commits

Reviewing files that changed from the base of the PR and between 63f2702 and c562830.

📒 Files selected for processing (1)

• packages/runtime/src/__tests__/shell-run-manager.test.ts

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

Problem solved

writeStdin could return a stale running snapshot when the PTY exited while persistObservation was in flight. The change re-joins finalization when driverExit or finalizeOnce indicates that finalization has started. This allows writeStdin to return the terminal record.

The test now waits for a terminal shell-run snapshot before it asserts completed, output dimensions, and revision consistency. It also covers PTY finalization during persistence, including resize, driver disposal, and cleanup.

Design assessment

The change extends the existing PTY finalization and durable observation flow. It does not create a parallel source of truth or change a public contract.

The production fix is small and located at the race point. The test synchronization and added regression coverage are necessary to verify asynchronous finalization. No deletion or simplification is evident without weakening coverage.

Validation and risks

Reported validation includes successful builds, targeted and full test passes, and clean Biome checks. Direct evidence of the current required-check status is unavailable, so that status remains unverified.

The main behavioral risk is that writeStdin can now wait for terminal finalization instead of returning an intermediate running snapshot when PTY exit or finalization has begun. The added wait could affect timing under those conditions. The regression tests cover this race and related cleanup behavior.

Review-relevant risks

No protected-area effect was identified in the current diff. The person performing the merge reviews the final diff, and a maintainer makes the final determination.

Walkthrough

writeStdin now joins PTY finalization when exit or finalization begins after persistence. The tests wait for the terminal snapshot before checking completion, dimensions, durable revision, and cleanup.

Changes

PTY finalization synchronization

Layer / File(s)	Summary
Join finalization and validate terminal state packages/runtime/src/shell-run-manager.ts, packages/runtime/src/__tests__/shell-run-manager.test.ts	writeStdin now waits for live.finished, marks the terminal record observed, and returns it. The tests cover terminal snapshots, PTY disposal, resize, final dimensions, and durable revision.

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

Merge Risk:⚪ Minimal · up to c5628

This localized runtime change ensures PTY runs reach their terminal record after a racing persist; no actionable merge-blocking risk remains after normal checks.

Suggested reviewers:m4n5ter, astro-han, jackwener

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the PTY finalization race fix.
Description check	✅ Passed	The description includes the problem, issue reference, implementation, verification results, AI disclosure, and completed checklist items.
Linked Issues check	✅ Passed	The implementation and tests address issue #3077 by joining PTY finalization after persistence races and waiting for terminal state.
Out of Scope Changes check	✅ Passed	All changes are limited to PTY finalization behavior and tests required by issue #3077.
Ai Use Disclosure	✅ Passed	The PR selects generative tooling and names Grok with scope; both introduced commits have standalone Generated-by: Grok trailers.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d3a6126-a1e6-4364-bf74-587d6dd3c61b

📥 Commits

Reviewing files that changed from the base of the PR and between 62cded2 and 63f2702.

📒 Files selected for processing (2)

• packages/runtime/src/__tests__/shell-run-manager.test.ts
• packages/runtime/src/shell-run-manager.ts

[M4n5ter]

LGTM

[1625567290]

Summary

joins finalization when a real PTY exits before a queued control cut failed on CI with expected completed, got running even though #3075 did not touch runtime. Re-running the same commit passed.

writeStdin asked persistObservation whether to join finalization at call time. A real PTY can exit while that persist is still in flight, so the control returned the running snapshot. After persist, if driverExit / finalizeOnce is set, join the terminal record.

The test no longer assumes that first snapshot is already terminal: if it is still running, it waits with waitForTerminalShellRun (15s) before asserting completed.

Fixes#3077

Verification

• npm --workspace @maka/core run build
• npm --workspace @maka/runtime run build
• node --test --test-name-pattern 'joins finalization when a real PTY exits before a queued control cut' packages/runtime/dist/__tests__/shell-run-manager.test.js — 5/5 repeats
• Nearby queued-control cases — 3/3
• Full shell-run-manager.test.js — 57 pass, 3 skip (Windows PowerShell)
• biome check on the two files — clean

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope:

Grok authored the implementation, tests, and this PR description.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7be63958-f9a8-4f80-9f40-2e13e1eeab49

📥 Commits

Reviewing files that changed from the base of the PR and between 63f2702 and c562830.

📒 Files selected for processing (1)

• packages/runtime/src/__tests__/shell-run-manager.test.ts

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

Problem solved

writeStdin could return a stale running snapshot when the PTY exited while persistObservation was in flight. The change re-joins finalization when driverExit or finalizeOnce indicates that finalization has started. This allows writeStdin to return the terminal record.

The test now waits for a terminal shell-run snapshot before it asserts completed, output dimensions, and revision consistency. It also covers PTY finalization during persistence, including resize, driver disposal, and cleanup.

Design assessment

The change extends the existing PTY finalization and durable observation flow. It does not create a parallel source of truth or change a public contract.

The production fix is small and located at the race point. The test synchronization and added regression coverage are necessary to verify asynchronous finalization. No deletion or simplification is evident without weakening coverage.

Validation and risks

Reported validation includes successful builds, targeted and full test passes, and clean Biome checks. Direct evidence of the current required-check status is unavailable, so that status remains unverified.

The main behavioral risk is that writeStdin can now wait for terminal finalization instead of returning an intermediate running snapshot when PTY exit or finalization has begun. The added wait could affect timing under those conditions. The regression tests cover this race and related cleanup behavior.

Review-relevant risks

No protected-area effect was identified in the current diff. The person performing the merge reviews the final diff, and a maintainer makes the final determination.

Walkthrough

writeStdin now joins PTY finalization when exit or finalization begins after persistence. The tests wait for the terminal snapshot before checking completion, dimensions, durable revision, and cleanup.

Changes

PTY finalization synchronization

Layer / File(s)	Summary
Join finalization and validate terminal state packages/runtime/src/shell-run-manager.ts, packages/runtime/src/__tests__/shell-run-manager.test.ts	writeStdin now waits for live.finished, marks the terminal record observed, and returns it. The tests cover terminal snapshots, PTY disposal, resize, final dimensions, and durable revision.

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

Merge Risk:⚪ Minimal · up to c5628

This localized runtime change ensures PTY runs reach their terminal record after a racing persist; no actionable merge-blocking risk remains after normal checks.

Suggested reviewers:m4n5ter, astro-han, jackwener

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the PTY finalization race fix.
Description check	✅ Passed	The description includes the problem, issue reference, implementation, verification results, AI disclosure, and completed checklist items.
Linked Issues check	✅ Passed	The implementation and tests address issue #3077 by joining PTY finalization after persistence races and waiting for terminal state.
Out of Scope Changes check	✅ Passed	All changes are limited to PTY finalization behavior and tests required by issue #3077.
Ai Use Disclosure	✅ Passed	The PR selects generative tooling and names Grok with scope; both introduced commits have standalone Generated-by: Grok trailers.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d3a6126-a1e6-4364-bf74-587d6dd3c61b

📥 Commits

Reviewing files that changed from the base of the PR and between 62cded2 and 63f2702.

📒 Files selected for processing (2)

• packages/runtime/src/__tests__/shell-run-manager.test.ts
• packages/runtime/src/shell-run-manager.ts

[M4n5ter]

LGTM