Use durable Codex startup instructions

[TraderSamwise]

Summary

• pass Codex standing startup guidance through developer_instructions instead of prompt injection
• merge aimux guidance into managed AGENTS.md blocks without overwriting user content
• move Codex fork/migration continuity into durable instructions and remove detached kickoff delivery
• add a Codex instruction-channel verifier and update docs

Verification

• yarn verify
• yarn verify:codex-instructions
• yarn build

Summary by CodeRabbit

• New Features

  • Added developer instructions configuration key for enhanced tool startup control.
  • Added verification command to validate developer instructions setup.

• Bug Fixes

  • Fork/migrate operations now preserve existing user content in instruction files by merging instead of overwriting.
  • Improved Codex startup behavior to inject developer instructions via configuration.

• Documentation

  • Updated configuration guides with developer instructions settings and startup behavior details.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors Codex instruction delivery from detached tmux prompt injection to durable config-injected developer instructions. It introduces managed instruction file blocks that preserve user content, implements preamble config injection via -c developer_instructions=..., and replaces kickoff prompts with continuity preambles for fork/migrate operations while removing the old delivery automation.

Changes

Codex Developer Instructions Configuration & Delivery

Layer / File(s)	Summary
Configuration Schema & Verification Tooling src/config.ts, package.json, scripts/verify-codex-developer-instructions.sh, README.md, docs/tool-integration.md	ToolConfig extends with developerInstructionsConfigKey field (defaults to "developer_instructions" for Codex); new verify:codex-instructions npm script runs Bash verification that confirms Codex CLI injects developer instructions into prompt-input correctly; documentation updated to describe managed instruction file merging and Codex startup via developer config.
Managed Instruction File Block Merging src/multiplexer/runtime-lifecycle-methods.ts, src/multiplexer/runtime-lifecycle-methods.test.ts	Constants and helpers wrap generated instructions in BEGIN/END markers and merge into existing files without overwriting user content. writeInstructionFiles now reads existing content and merges the managed block; removeInstructionFiles strips only the managed block. Tests verify merge preservation, cleanup isolation, and file deletion when empty.
Developer Instructions Injection & Session Launch src/multiplexer/session-launch.ts, src/multiplexer/session-launch.test.ts	firstCodexPositionalArgIndex scanner finds insertion point for config args, respecting options and -- terminator. injectCodexDeveloperInstructions splices -c developer_instructions=<json> at that index. createSession integrates injection when preamble not suppressed and config key present. Comprehensive test updates verify config injection, disabled instructions, explicit subcommands, and resume/teammate paths.
Continuity Preambles for Fork & Migrate src/session-bootstrap.ts, src/multiplexer/index.ts, src/multiplexer/session-launch.ts, src/multiplexer/session-launch.test.ts	buildCodexForkContinuityPreamble and buildCodexMigrationContinuityPreamble replace kickoff builders, emphasizing carried-over context files and prior activity with optional instruction/summary. forkSessionFromSource and migrateAgent use continuity preambles instead of detached kickoff delivery. Tests updated to assert continuity preamble injection.
Remove Detached Kickoff Delivery Mechanism src/session-bootstrap.ts, src/session-bootstrap.test.ts	Removes buildInitialKickoffPrompt, deliverDetachedCodexKickoffPrompt, waitForDetachedCodexInputReady, paneLooksLikeCodexInputReady, and deliverTmuxPrompt import. Eliminates tmux polling for input readiness and detached prompt submission. Test suite cleanup removes related fixtures.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 A rabbit hops through Codex lands,
Where prompts now whisper through config commands,
No more tmux polls or detached kicks,
Just managed blocks and continuity tricks. 🎯
Fork and migrate dance on, context preserved,
Clean instructions injected—exactly deserved! ✨

🚥 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Use durable Codex startup instructions' directly and clearly summarizes the main change: replacing prompt injection with a durable developer_instructions mechanism for Codex startup guidance.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 phase/codex-durable-startup

---

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

[coderabbitai]

🧹 Nitpick comments (2)

src/session-bootstrap.test.ts (1)

1-92: ⚖️ Poor tradeoff

Consider adding test coverage for new continuity preamble methods.

The new buildCodexForkContinuityPreamble and buildCodexMigrationContinuityPreamble methods in SessionBootstrapService don't have direct unit tests in this file. The integration is tested via session-launch.test.ts, but unit tests would help verify the preamble content directly.

🤖 Prompt for 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.

In `@src/session-bootstrap.test.ts` around lines 1 - 92, Add unit tests in this
file for SessionBootstrapService.buildCodexForkContinuityPreamble and
buildCodexMigrationContinuityPreamble: instantiate SessionBootstrapService with
the existing deps, call each method with representative args (sessionId,
parent/target info, any team/role flags), and assert the returned preamble
contains expected key phrases (e.g., session IDs, migration/fork guidance,
teammate/continuity warnings) and does not contain disallowed strings; reference
the method names buildCodexForkContinuityPreamble and
buildCodexMigrationContinuityPreamble to locate where to add the tests.

src/session-bootstrap.ts (1)

335-359: 💤 Low value

Inconsistent instruction formatting between fork and migration preambles.

In buildCodexForkContinuityPreamble (line 328), the instruction is prefixed with "Instruction: ", but here in buildCodexMigrationContinuityPreamble (line 354), the instruction is added raw without the prefix.

Suggested fix for consistency

       activitySummary ? `Recent session activity: ${activitySummary}` : undefined,
-      instruction?.trim(),
+      instruction?.trim() ? `Instruction: ${instruction.trim()}` : undefined,
       "After reading them, briefly summarize what we were doing in the new worktree and continue from that context.",

🤖 Prompt for 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.

In `@src/session-bootstrap.ts` around lines 335 - 359, The migration preamble
built by buildCodexMigrationContinuityPreamble appends instruction?.trim()
without the "Instruction: " prefix used in buildCodexForkContinuityPreamble,
causing inconsistent UX; update buildCodexMigrationContinuityPreamble so that
when instruction is present it is prefixed the same way (e.g., `Instruction:
${instruction.trim()}`) before filtering and joining, referencing the function
buildCodexMigrationContinuityPreamble and the instruction variable to locate the
change.

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

Nitpick comments:
In `@src/session-bootstrap.test.ts`:
- Around line 1-92: Add unit tests in this file for
SessionBootstrapService.buildCodexForkContinuityPreamble and
buildCodexMigrationContinuityPreamble: instantiate SessionBootstrapService with
the existing deps, call each method with representative args (sessionId,
parent/target info, any team/role flags), and assert the returned preamble
contains expected key phrases (e.g., session IDs, migration/fork guidance,
teammate/continuity warnings) and does not contain disallowed strings; reference
the method names buildCodexForkContinuityPreamble and
buildCodexMigrationContinuityPreamble to locate where to add the tests.

In `@src/session-bootstrap.ts`:
- Around line 335-359: The migration preamble built by
buildCodexMigrationContinuityPreamble appends instruction?.trim() without the
"Instruction: " prefix used in buildCodexForkContinuityPreamble, causing
inconsistent UX; update buildCodexMigrationContinuityPreamble so that when
instruction is present it is prefixed the same way (e.g., `Instruction:
${instruction.trim()}`) before filtering and joining, referencing the function
buildCodexMigrationContinuityPreamble and the instruction variable to locate the
change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f0200a7f-0e8d-404e-8368-0df821d872db

📥 Commits

Reviewing files that changed from the base of the PR and between fc2fb4f and e1fe490.

📒 Files selected for processing (12)

• README.md
• docs/tool-integration.md
• package.json
• scripts/verify-codex-developer-instructions.sh
• src/config.ts
• src/multiplexer/index.ts
• src/multiplexer/runtime-lifecycle-methods.test.ts
• src/multiplexer/runtime-lifecycle-methods.ts
• src/multiplexer/session-launch.test.ts
• src/multiplexer/session-launch.ts
• src/session-bootstrap.test.ts
• src/session-bootstrap.ts