feat(t3layer): phase 6 control operations and review closures

[EtanHey]

Summary

• add stock-only interrupt, approval response, user-input response, and session stop operations with typed receipts, terminal no-ops, bounded confirmation, and one byte-identical ambiguity retry
• close the Phase 6 M1/M2/M3 and F2/F3 review debts, plus the optional future stock input-field preservation closure
• harden control projection alignment, receipt evidence, immutable retry inputs, terminal-capacity reactivation, pending reservations, and stale-observation fencing through local and PR review rounds

Verification

• exact toolchain: Bun 1.3.11, SHA-256 1d77af7bfd811aebb7d37bec496a5eed14fe227ded3ab7866d2f39786e8107b6
• targeted gate: 100 pass, 0 fail, 308 expect() calls, 5 files
• typecheck: tsc --noEmit exit 0
• full gate: 320 pass, 2 skip, 0 fail, 1055 expect() calls, 322 tests across 24 files
• reconstructed RED evidence for all six scope items by temporarily reverting each production hunk, observing its named regression fail, restoring it, and rerunning GREEN
• reverified stock command citations at pinned t3code commit d3037064

Review status

• three local CodeRabbit rounds completed; all six actionable findings fixed with regressions
• PR CodeRabbit posted eight actionables; all eight received fixes/coverage and explicit addressed confirmations
• Macroscope correctness findings were fixed except terminal-record pruning, which is design-cited WONT_FIX because the binding F2 decision requires terminal records to remain listable while not consuming maxWorkers
• latest Macroscope correctness check passes; final CodeRabbit scan is rate-limited with no new inline findings
• source/test ownership remains exactly the seven goal-authorized files
• this PR is intentionally ready for review and must not be merged as part of this task

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_5c23db43-bb55-4f12-bd0d-136373dbf654)

[EtanHey]

@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.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds interrupt, stop, approval, and user-input operations to the native runtime and facade. It tracks terminal workers in overlay capacity checks, preserves spawn fields, reports spawn results in errors, and validates policy scopes and deadlines.

Changes

Runtime control operations

Layer / File(s)	Summary
Control contracts and runtime operations src/nativeRuntime.ts, test/control-operations.test.ts	The runtime adds control-operation contracts, validation, dispatch retries, snapshot reconciliation, confirmation polling, and control methods. Tests cover dispatch, no-ops, retries, timeouts, validation, and command safety.
Terminal-aware overlay capacity src/overlay.ts, test/facade.stock-http.test.ts	The overlay excludes terminal workers from capacity counts and validates terminal-worker reactivation. Tests cover replacement workers, blocked reactivation, rollback, and wait-error capacity release.
Facade lifecycle and public API integration src/facade.ts, test/facade.stock-http.test.ts	The facade exposes control types and methods, preserves unknown spawn fields, includes spawn results in commit errors, and updates terminal state across send, wait, interrupt, stop, and observe.
Policy input normalization and fan-out scheduling src/policy.ts, test/policy.test.ts	Policy dispatch validates normalized scope IDs and deadlines. Fan-out schedules dispatches asynchronously and reports selector failures without orphaning sibling work.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• EtanHey/t3layer#2: Extends the same native runtime and facade APIs with control operations.
• EtanHey/t3layer#4: Modifies the same stock runtime with control operations and terminal-state tracking.
• EtanHey/t3layer#5: Extends the same overlay functionality with terminal-state capacity behavior.

Poem

A rabbit checks the worker state,
Then frees a slot before too late.
Interrupt, stop, approve, reply,
Snapshots keep the truth nearby.
The overlay hops, capacities fly.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 4.76% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 Phase 6 control operations, which are the primary changes in the pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/phase6-control-ops

---

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.}

[coderabbitai]

Actionable comments posted: 8

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/facade.ts`:
- Around line 288-303: In src/facade.ts lines 288-303, update interrupt and stop
to reactivate the worker before invoking runtime.interrupt or runtime.stop, and
restore the prior terminal marker if either runtime call throws, following
send’s existing ordering. In src/facade.ts lines 314-320, update observe to
remove reactivation from the read path and call recordWorkerTerminalState only
when isTerminalSnapshot(snapshot) is true.
- Around line 165-172: Update isTerminalSnapshot to also return true when
snapshot.thread.latestTurn?.state is "interrupted", preserving the existing
completed, error, stopped, and session-error terminal conditions.

In `@src/nativeRuntime.ts`:
- Around line 2781-2788: Snapshot response.answers before constructing the
frozen command in respondToUserInput, ensuring the command owns a detached copy
rather than the caller’s mutable object. Preserve the existing command shape and
dispatchControl retry behavior so every retry reuses identical answer data.
- Around line 2734-2736: Update the decision validation in the response-handling
logic to derive its accepted values from the existing ApprovalDecision
declaration instead of duplicating the string literals. Ensure adding a new
ApprovalDecision value automatically updates both TypeScript typing and runtime
validation, while preserving the existing protocol_mismatch error for invalid
decisions.

In `@src/overlay.ts`:
- Around line 312-325: Update the reactivation capacity check in
setTerminalState to include pending.size alongside activeRecordCount() before
allowing a terminal record to become active. Preserve the existing capacity
error and terminal-record state transitions, ensuring reactivation is rejected
whenever active records plus pending reservations reaches maxWorkers.

In `@test/control-operations.test.ts`:
- Around line 691-727: Add a test covering the no-pending-request branches of
respondToApproval and respondToUserInput using a shellThread fixture with
pendingApproval and pendingInput disabled and client projections returning that
thread. Assert approval_not_pending and user_input_not_pending respectively, and
verify dispatches remains zero before closing the runtime.

In `@test/facade.stock-http.test.ts`:
- Around line 1230-1267: Add cleanup to the test “counts only non-terminal
overlay workers against capacity” by awaiting facade.close() after the
assertions. Ensure the real runtime’s adaptive poller and timers are released
before the test completes; leave the following plain-object-double tests
unchanged.

In `@test/policy.test.ts`:
- Around line 416-438: Add a direct test near the existing normalized-scope
capacity test for dispatching with a whitespace-only scopeId such as " ". Assert
that dispatch rejects with TypeError, the callback is not invoked, and the
policy reports zero active and queued work before cleanup.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3b6730a1-5a7b-4431-a00a-6d105886e829

📥 Commits

Reviewing files that changed from the base of the PR and between 22552e1 and f5b6212.

📒 Files selected for processing (7)

• src/facade.ts
• src/nativeRuntime.ts
• src/overlay.ts
• src/policy.ts
• test/control-operations.test.ts
• test/facade.stock-http.test.ts
• test/policy.test.ts

📜 Review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: Macroscope - Correctness Check

🔇 Additional comments (20)

src/policy.ts (2)

242-271: LGTM!

---

337-350: LGTM!

test/policy.test.ts (2)

391-414: LGTM!

---

466-503: LGTM!

src/nativeRuntime.ts (7)

146-192: LGTM!

Also applies to: 265-266

---

2253-2404: LGTM!

---

2406-2525: LGTM!

---

2527-2609: LGTM!

---

2611-2680: LGTM!

---

2682-2726: LGTM!

---

3119-3122: LGTM!

test/control-operations.test.ts (2)

19-136: LGTM!

---

139-689: LGTM!

Also applies to: 729-755

src/overlay.ts (2)

74-74: LGTM!

Also applies to: 143-151, 291-298, 370-377

---

247-249: LGTM!

test/facade.stock-http.test.ts (3)

8-8: LGTM!

Also applies to: 934-978, 1203-1219

---

1269-1315: LGTM!

Also applies to: 1317-1352, 1373-1381

---

1367-1372: 📐 Maintainability & Code Quality

No duplicate observe property to remove.

The runtime object at test/facade.stock-http.test.ts:1367 declares observe once before wait, with no literal duplicate property to remove.

src/facade.ts (2)

3-13: LGTM!

Also applies to: 22-38, 56-56, 101-102, 145-145, 154-154, 211-211, 236-236

---

267-287: LGTM!

Also applies to: 304-313

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_b0d26515-329e-49fe-a358-676c8b42d91b)

[EtanHey]

@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.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_09fbd0ca-850c-4823-98c1-d25435eb2d7e)

[EtanHey]

@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.