docs(codex): pivot first-class-integration design to CLI-native channels

[namastex888]

Summary

Rewrites .genie/brainstorms/codex-first-class-integration/DESIGN.md to reflect the settled architectural framing from the 2026-04-27 codex+channels brainstorm. Supersedes the morning version that proposed an @openai/codex-sdk driver — Felipe rejected the SDK-primary path in favor of CLI-native primitives.

Key shifts

• CLI-first: Claude Code never loads MCP servers as plugins.
• Channels semantics yes, transport no: adopt the structured envelope (<channel source="X" meta_k=v>body</channel>); reject the MCP wire.
• Genie owns the channel-server role externally: external integrations (omni/whatsapp, telegram, webhook, discord) live as genie subcommands. They write to the same native inbox file (~/.claude/teams/<team>/inboxes/<agent>.json) and the same PG mailbox that peer agents use.
• No tmux send-keys for runtime delivery: spawn-time send-keys (terminal init, cd + launch, TUI keybindings) stays; mid-turn injection is migrated to native paths.
• Codex hook bridge is the receive pipe: PR feat(codex): hook bridge — codex events route through 'genie hook dispatch' #1424 (already shipped in 4.260427.9) wires ~/.codex/config.toml to genie hook dispatch. The missing handler (PR B in the ladder) reads PG mailbox on UserPromptSubmit and returns additionalContext.

PR ladder captured in the design

PR	Goal	Depends on
A	Channel-shaped envelope on mailbox.send + NativeInboxMessage; genie inbox list source rendering	none
B	Codex UserPromptSubmit handler reads PG mailbox, returns additionalContext	A
C	Migrate claude-code.ts:deliver (omni→claude) from tmux send-keys to native inbox + source='whatsapp'	A
D	Migrate claude-code.ts:injectNudge from tmux send-keys to native inbox + source='system'	A
E	Remove protocol-router.ts:injectToTmuxPane after metric confirms zero traffic	A–D
F+	First external channel adapter as genie subcommand (later, optional)	A–D

PR A is in-flight on feat/channel-envelope-inbox in parallel with this docs PR.

Empirical proof preserved in the doc

The 2026-04-27 hookbridge-test session demonstrated end-to-end native delivery (genie send → PG mailbox → codex inbox-list → genie send pong reply) with zero tmux send-keys and zero MCP. The doc cites it as the validation that the substrate already works for source='agent'; PRs A–F generalize that to all source kinds.

Test plan

This is docs-only.

• No code changed; CI lint should pass without behavior tests.
• Linter (scripts/wishes-lint.ts) accepts _No brainstorm — direct wish_ stub for any wish that won't have a brainstorm; this PR doesn't change the linter, only refreshes a brainstorm.
• DESIGN.md preserved at the same path the prior version occupied; supersedes-note in the doc itself flags the rewrite.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 357aa31d-a0e8-4520-8565-217aa33afda3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/codex-channels-pivot

---

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 and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces a design for integrating Codex into Genie using CLI-native channels and a hook-based delivery substrate, replacing legacy tmux-based methods. The proposed architecture utilizes a structured XML-like envelope for message attribution across different sources and outlines a multi-wave implementation plan. Feedback on the design suggests updating the delivery diagrams to reflect signature changes, implementing body escaping for the channel envelope to prevent parsing breakages, and ensuring that pending messages are not marked as read if a delivery hook times out.

[gemini-code-assist]

The diagram for PATH 2 shows the legacy mailbox.send signature. It should be updated to include the source and meta parameters introduced in PR A to maintain consistency with the architectural changes described later in the document.

Suggested change

	│ mailbox.send(repo, from, to, body) │
	│ mailbox.send(repo, from, to, body, {source, meta}) │

[gemini-code-assist]

The proposed XML-like envelope lacks a specification for escaping the body content. Without escaping (e.g., using CDATA or entity encoding), a message body containing the string will break the envelope structure and potentially confuse the agent's parser. Consider adding a note about escaping the body.

Suggested change

	| **Channel envelope** = `<channel source="X" from="Y" k="v">body</channel>` rendered into the message text on delivery | Captures provenance without schema churn for downstream consumers. Claude/codex agents see human-readable XML-ish text and can choose to react to specific sources. Round-trippable for debugging. |
	| **Channel envelope** = <channel source="X" from="Y" k="v">body</channel> (with body escaped) rendered into the message text on delivery | Captures provenance without schema churn for downstream consumers. Claude/codex agents see human-readable XML-ish text and can choose to react to specific sources. Round-trippable for debugging. |

[gemini-code-assist]

In the timeout mitigation for the Codex hook, it is important to clarify that if the handler bails and returns an empty additionalContext, the pending messages must not be marked as read. This ensures they are preserved for the next turn rather than being lost.

Suggested change

	| Codex hook can timeout if mailbox query is slow | Low | Hook timeout is 15s (PR #1424). PG queries on `mailbox WHERE to_worker = X AND read = false` are sub-millisecond. Still: budget the hook to ≤500ms; bail with empty additionalContext on timeout. |
	| Codex hook can timeout if mailbox query is slow | Low | Hook timeout is 15s (PR #1424). PG queries on mailbox WHERE to_worker = X AND read = false are sub-millisecond. Still: budget the hook to ≤500ms; bail with empty additionalContext on timeout (do not mark messages as read). |