fix(orchestration): file mail from terminals in no Run under an unbound Run

[Jinwoo-H]

	Files	Added	Deleted	Net
Test	4	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​63	$\color{#cf222e}{\Huge{\mathbf{−}}}$​35	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​28
Prod	3	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​20	$\color{#cf222e}{\Huge{\mathbf{−}}}$​4	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​16

ELI5

Two plain Orca terminals, neither started by orchestration. Run orca orchestration send --to <other handle> --subject hi. In v1.4.198 that delivered. After #19542 it fails with a bare Run is required and no recovery hint, and agents retry the same command until they give up. This is the first thing the orchestration guide teaches, and it is what today's field report was about (send breaks, nothing else does, same CLI).

Why #19542 broke it

#19542 deleted the fallback that filed such mail under run_legacy_local. That deletion was needed: a live row under the legacy Run makes the schema-skew probe read the database as pre-Runs and replay a destructive adoption on the next open. But the fallback had callers beyond federation, and I did not enumerate them. Point-to-point and group send from an unbound sender both reached it.

Fix

Unbound mail files under run_unbound, a Run id the probe never matches. The row is created on first use inside insertMessage, so a user who never sends unbound mail never sees it in run list (eager seeding failed five listing-count tests). Group send flows through the same insert. No wire change, no schema version change, no migration: the runs table already accepts the row.

Net: -3 lines in the writer, +1 constant, +1 lazy insert.

Tests

• Real orchestration.send then orchestration.check between two terminals in no Run: message files under run_unbound, check returns it.
• Reopen probe: a database whose only mail is unbound survives a close/reopen with no legacy_adoptions row and the mail still unread.
• Writer test flipped from "rejects" to "files under unbound".
• e2e orchestration-idle-mail-delivery restored to the v1.4.198 contract (durable, not pushed) with the run id pinned. test(orchestration): pin the Run-required contract for unbound direct mail #19684's refusal assertion is gone.
• Mutation: refiling under run_legacy_local fails all three unit cases.

Suites: runtime, cli, shared, rpc: 1527 files / 16172 tests green. tc:node, tc:cli, both changed-code gates, ratchet, oxfmt clean.

Release

Regression from #19542, which is on release/adhoc-1.4.199-daily-202609081832-cherrypicks and unshipped. Cherry-pick this alongside #19689 before the daily. With both, every caller #19542 cut off is restored: remote attach from old desktops and pre-upgrade worker mailboxes (#19689), and unbound terminal mail (this).

Compatibility

Host-only. A v1.4.198 client sees v1.4.198 behavior. A v1.4.198 host reading a v1.4.199 database sees an ordinary non-legacy Run row.

Checklist

• Small and focused
• ELI5 and rationale
• N/A screenshots (RPC + DB)
• Self-reviewed
• SSH/remote: same DB layer on every host
• Automated tests added

[pullfrog]

• Checkout PR fix(orchestration): file mail from terminals in no Run under an unbound Run #19696 and read diff
• Read learnings file relevant sections
• Triage PR and read surrounding code
• Dispatch reviewfrog specialists if needed
• Draft and submit review
• Update PR summary snapshot

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 11832419-3d52-47f2-83cb-df1fd7c05f11

📥 Commits

Reviewing files that changed from the base of the PR and between 14d2628a2a5974f3b40381f10a070478c46f0ba1 and 5bbd2bf.

📒 Files selected for processing (1)

• src/main/runtime/orchestration/db/messages/message-insert.ts

---

📝 Walkthrough

Walkthrough

Messages sent from terminals outside a Run now use the dedicated run_unbound identifier. The database creates a non-legacy unbound Run when needed and stores the message under it. Unbound messages remain available after database reopening without triggering legacy adoption. RPC and end-to-end tests verify durable delivery, unread retrieval, and the absence of unsafe check pointers.

Fixed issue severity: <fixed_issue_severity>Medium</fixed_issue_severity>

Merge Risk: 🔵 Low · up to 14d26

Unbound mail is now stored durably under a dedicated Run, but an invalid empty Run ID can leave an unused unbound Run record after the message fails. This is a bounded data-cleanliness issue that should be corrected before merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 7 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: filing mail from terminals without a Run under an unbound Run.
Description check	✅ Passed	The description is detailed and on-topic. It explains the regression, fix, rationale, compatibility impact, and testing. Some template sections are omitted, including an explicit Linked Issue entry, V…
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.

• Fix all pre-merge checks with AI

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: ec6069f7-4687-497e-9b08-2db468daa838

📥 Commits

Reviewing files that changed from the base of the PR and between 7197593 and 14d2628a2a5974f3b40381f10a070478c46f0ba1.

📒 Files selected for processing (7)

• src/main/runtime/orchestration/db/contract-constants.ts
• src/main/runtime/orchestration/db/messages/message-insert.ts
• src/main/runtime/orchestration/db/writer-run-required.test.ts
• src/main/runtime/orchestration/orchestration-federated-legacy-probe.test.ts
• src/main/runtime/rpc/methods/orchestration/messaging/send-unbound-terminals.test.ts
• src/shared/orchestration-rpc-contract.ts
• tests/e2e/orchestration-idle-mail-delivery.spec.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.