[bug] mcodex resume hangs with runtime rotation, and helper can prevent exit

[LeonardoPaccianiMori]

Summary

With runtime rotation enabled, mcodex resume hangs on a blank screen after printing the multi-auth status line, while the equivalent official codex resume command works normally.

Using CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0 mcodex resume ... also works, but disables automatic runtime account rotation and therefore is not an acceptable permanent workaround.

The problem was diagnosed and locally fixed with OpenAI GPT-5.6-sol. The validated diagnosis is that resume and fork are interactive TUI entry points but are routed through the ephemeral shadow-home request path instead
of the canonical-home TUI helper path.

A second related problem was found: after an interrupted/nonzero Codex exit, the rotation helper can remain referenced after its graceful-shutdown timeout, preventing mcodex from returning to the shell.

Reproduction

1. Install the current stable package:

   npm install -g codex-multi-auth

2. Add multiple accounts and enable runtime rotation.

3. Confirm that the session resumes through the official CLI:

   codex resume <session-id>

   This works normally.

4. Attempt the same resume through the wrapper:

   mcodex resume <session-id>

5. The multi-auth status line appears, but the resumed TUI remains blank and never becomes usable.

6. Disable the runtime proxy for only that invocation:

   CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0 mcodex resume <session-id>

   The session opens normally, confirming that the failure is specific to the runtime-rotation path.

7. After routing resume through the canonical-home helper locally, resume works. However, an interrupted/nonzero exit can leave the wrapper stuck after Codex prints its final “To continue this session...” message. The
   shell prompt does not return.

Expected Behavior

mcodex resume [session-id] and mcodex fork [session-id] should behave like the equivalent official Codex TUI commands while retaining automatic account rotation.

After /exit, interruption, or another Codex termination, the wrapper should always return control to the shell within a bounded amount of time.

Actual Behavior

Two related failures occur:

1. resume/fork are classified as request commands and use an ephemeral shadow CODEX_HOME. The shadow SQLite state can be incomplete, causing resume to hang even though the session rollout file exists.
2. If the detached rotation helper does not terminate during its two-second graceful shutdown window, the wrapper stops waiting but leaves the child process/streams referenced. The Node wrapper then remains alive
   indefinitely.

Environment

• codex --version: codex-cli 0.146.0
• codex-multi-auth --version: 2.8.0
• npm ls -g codex-multi-auth: codex-multi-auth@2.8.0
• Runtime rotation: enabled
• Accounts: 2
• Storage health: healthy
• OS: Pop!_OS 24.04 LTS
• Kernel: Linux 7.0.11-76070011-generic x86_64
• Node.js: v24.17.0
• npm: 12.0.0

Diagnostic Evidence

• codex-multi-auth check reported both accounts as signed in and available.
• codex-multi-auth rotation status reported:
• runtime rotation proxy enabled
• stored setting enabled
• no environment override
• codex resume <session-id> worked.
• mcodex resume <session-id> hung.
• CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0 mcodex resume <session-id> worked.
• The normal sessions directory was correctly symlinked into the generated shadow homes.
• The canonical state_5.sqlite contained 257 indexed threads and the requested thread.
• The two shadow databases created by the failed launches contained only 126 and 128 threads and did not contain the requested thread.
• No ~/.codex/multi-auth/logs/codex-plugin/ directory was created.
• After the exit hang, Bash showed the wrapper as a stopped job when Ctrl+Z was used.

Account emails, account IDs, OAuth data, and the real session UUID have intentionally been omitted.

Diagnosis

In scripts/codex.js, isCodexInteractiveTuiCommand only recognizes an invocation with no forwarded command:

function isCodexInteractiveTuiCommand(rawArgs) {
    return findForwardedCommand(rawArgs) === null;
}

However, resume and fork are also interactive TUI entry points. They are included in requestCommands, so they take the ephemeral proxy/shadow-home path.

Treating resume and fork as interactive TUI commands makes them use the canonical-home app-helper path already used by normal mcodex.

This local patch fixed resume while keeping runtime account rotation enabled:

function isCodexInteractiveTuiCommand(rawArgs) {
-    return findForwardedCommand(rawArgs) === null;
+    const command = findForwardedCommand(rawArgs);
+    return (
+        command === null ||
+        command.command === "resume" ||
+        command.command === "fork"
+    );
}

The helper shutdown code also has an unbounded process-lifetime failure. waitForRuntimeRotationAppHelperExit stops waiting after two seconds, but stopRuntimeRotationAppHelper can leave the helper and its streams
referenced if it has not actually exited.

This additional local patch fixed the shell-return problem:

-function stopRuntimeRotationAppHelper(helper) {
+async function stopRuntimeRotationAppHelper(helper) {
    if (!helper || helper.killed) {
-        return Promise.resolve();
+        return;
    }
    try {
        helper.kill("SIGTERM");
    } catch {
-        return Promise.resolve();
+        return;
+    }
+    await waitForRuntimeRotationAppHelperExit(helper);
+    if (helper.exitCode === null && helper.signalCode === null) {
+        try {
+            helper.kill("SIGKILL");
+        } catch {
+            // Best-effort force-stop after the graceful shutdown timeout.
+        }
    }
-    return waitForRuntimeRotationAppHelperExit(helper);
+    helper.stdout?.destroy();
+    helper.stderr?.destroy();
+    helper.unref();
}

Both patches were applied to the installed codex-multi-auth@2.8.0 wrapper, passed node --check, and were validated through a real terminal:

• mcodex resume <session-id> opened successfully with runtime rotation enabled.
• /exit returned to the Bash prompt normally.
• No Ctrl+Z workaround was required.

AI-Assisted Diagnosis Disclosure

This issue was investigated, diagnosed, patched, and interactively validated with OpenAI GPT-5.6-sol. GPT-5.6-sol inspected the installed package source and the generated shadow-home SQLite metadata, identified both code
paths above, produced the local patches, and guided the terminal validation. The user executed the real interactive Codex tests.

Compliance Confirmation

• I am using this project for personal development workflows.
• This report does not request policy bypasses or prohibited usage.
• I removed all secrets, tokens, account identifiers, emails, and session identifiers from this report.

[coderabbitai]

Coding Plan

Summary

• add a dedicated resume/fork predicate in scripts/codex.js:4374 and route it to the canonical-home app-helper branch at scripts/codex.js:4166. keep isCodexInteractiveTuiCommand and shouldUseRuntimeRoutingForForwardedArgs semantics intact.
• harden stopRuntimeRotationAppHelper (scripts/codex.js:4013) with a SIGKILL fallback and unconditional stream destroy()/unref(). stop the timeout listener leak in waitForRuntimeRotationAppHelperExit (scripts/codex.js:3998).
• close the missing regression coverage in test/codex-bin-wrapper.test.ts for both routing and shutdown, with explicit windows guards for the signal-based assertions.
• flag the canonical-home concurrency question (resume/fork session vs detached helper writing the shared session index) for review. the interactive tui already runs this way, so the blast radius is small.

Design Choices

Design Choice 1: how should resume/fork reach the canonical-home app-helper path?

Options Considered:

1. widen isCodexInteractiveTuiCommand (scripts/codex.js:4374) to also return true for resume/fork, exactly as the ticket patch does.
2. keep isCodexInteractiveTuiCommand meaning "no subcommand", add a separate predicate (for example isCodexInteractiveResumeCommand), and route both predicates to the app-helper branch in createRuntimeRotationProxyContextIfEnabled (scripts/codex.js:4166).

Chosen Option: 2

Rationale: a separate predicate keeps the existing name accurate, isolates the new behavior, and makes the branch and its regression test read clearly. the routing outcome matches the validated ticket patch.

Design Choice 2: should resume/fork use the same detachOnExit: true and useCanonicalHome: true options as the bare tui?

Options Considered:

1. pass { detachOnExit: true, useCanonicalHome: true }, identical to the bare tui branch.
2. pass { useCanonicalHome: true } only, and let the detachGraceMs heuristic in createRuntimeRotationAppHelperContext (scripts/codex.js:4120) decide.

Chosen Option: 1

Rationale: resume/fork open a persistent interactive tui exactly like the bare invocation, so they should inherit the same detach behavior the ticket validated end to end.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: route resume and fork through the canonical-home app-helper path

this phase fixes the hang. the goal is to make resume/fork use the canonical CODEX_HOME with proxy -c overrides, the same transport the bare interactive tui already uses, so the official cli sees the complete session index and sqlite state. do not touch shouldUseRuntimeRoutingForForwardedArgs. resume/fork must stay in requestCommands (scripts/codex.js:4391) so rotation stays enabled.

Task 1: add a dedicated predicate for interactive resume/fork

introduce a predicate that classifies resume/fork as interactive tui entry points, without changing the meaning of the existing bare-invocation predicate.

• add a new function near isCodexInteractiveTuiCommand (scripts/codex.js:4374) that returns true when findForwardedCommand(rawArgs)?.command is "resume" or "fork".
• keep isCodexInteractiveTuiCommand returning true only for the no-subcommand case, so its name stays accurate.
• reuse findForwardedCommand (scripts/codex.js:4306) so flag-skipping and -- handling stay consistent with the rest of the router.

Task 2: route the new predicate to the app-helper branch

send resume/fork to createRuntimeRotationAppHelperContext with canonical-home and detach-on-exit options.

• in createRuntimeRotationProxyContextIfEnabled (scripts/codex.js:4166), extend the branch that currently checks isCodexInteractiveTuiCommand so it also triggers for the new resume/fork predicate.
• pass { detachOnExit: true, useCanonicalHome: true }, matching the existing interactive tui branch (scripts/codex.js:4170).
• concurrency note: this branch spawns a detached helper via startRuntimeRotationAppHelper (scripts/codex.js:4025) that keeps CODEX_HOME canonical. confirm the resume/fork session and the helper do not both write the canonical session index at once. the interactive tui already runs this way, so the risk is the same, but call it out in the pr description.
• verify proxyAppServerAccountRead is not needed for resume/fork. it is only set on the shadow-path return, and isCodexAppServerCommand is false for resume/fork, so moving off the shadow path drops nothing.

🤖 Prompt for AI agents

implement the routing fix for `mcodex resume`/`mcodex fork` in
`scripts/codex.js`.

- add a new predicate function near `isCodexInteractiveTuiCommand`
(`scripts/codex.js:4374`) that returns true when
`findForwardedCommand(rawArgs)?.command` is `"resume"` or `"fork"`. reuse
`findForwardedCommand` (`scripts/codex.js:4306`) so flag-skipping and `--`
handling stay consistent with the rest of the router.
- do not change `isCodexInteractiveTuiCommand`. it must keep returning true only
for the no-subcommand case.
- in `createRuntimeRotationProxyContextIfEnabled` (`scripts/codex.js:4166`),
extend the existing `isCodexInteractiveTuiCommand` branch so it also triggers
for the new resume/fork predicate, routing both to
`createRuntimeRotationAppHelperContext` (`scripts/codex.js:4106`).
- pass `{ detachOnExit: true, useCanonicalHome: true }` for this branch,
matching the existing interactive tui branch at `scripts/codex.js:4170`.
- do not touch `shouldUseRuntimeRoutingForForwardedArgs`
(`scripts/codex.js:4378`). `resume`/`fork` must remain in its `requestCommands`
set (`scripts/codex.js:4391`) so rotation stays enabled.
- confirm `proxyAppServerAccountRead` does not need to be set for
`resume`/`fork`: it is only set on the shadow-path return, and
`isCodexAppServerCommand` is false for these commands, so nothing is lost by
moving off the shadow path.
- note the concurrency risk in the pr description: the detached helper writes
the canonical session index while a resume/fork session may write it too. this
mirrors existing interactive-tui behavior, so the risk is not new, but it must
be called out.

Phase 2: bound helper shutdown so the wrapper always returns to the shell

this phase fixes the exit hang. the goal is a deterministic teardown: send SIGTERM, wait the graceful window, force SIGKILL if the child is still alive, then destroy and unref the stdio streams so the parent event loop can drain.

Task 1: add a SIGKILL fallback and stream teardown to stopRuntimeRotationAppHelper

make stopRuntimeRotationAppHelper guarantee the helper and its pipes are released.

• convert stopRuntimeRotationAppHelper (scripts/codex.js:4013) to async and await waitForRuntimeRotationAppHelperExit(helper).
• after the wait, if helper.exitCode === null && helper.signalCode === null, send helper.kill("SIGKILL") inside a try/catch as a best-effort force-stop.
• always call helper.stdout?.destroy(), helper.stderr?.destroy(), and helper.unref() at the end, so the piped fds from stdio: ["ignore", "pipe", "pipe"] (scripts/codex.js:4040) stop referencing the event loop.
• this matches the ticket patch and mirrors the detach branch teardown already present in createRuntimeRotationAppHelperContext (scripts/codex.js:4124).

Task 2: stop leaking the close listener on timeout in waitForRuntimeRotationAppHelperExit

make the wait clean up its own listener so a timed-out helper does not keep a dangling reference to a live child.

• in waitForRuntimeRotationAppHelperExit (scripts/codex.js:3998), remove the helper.once("close", finish) listener inside finish() (use helper.off("close", finish) / removeListener).
• this prevents a retained listener on the still-alive child when the 2s timeout wins, complementing the SIGKILL fallback in task 2.1.
• windows note: SIGKILL and SIGTERM are emulated on windows, and the helper is spawned detached: true (scripts/codex.js:4041), so the signal may not reach the whole process group. the stream destroy()/unref() in task 2.1 is what actually lets the wrapper exit on windows. keep it unconditional and do not rely on the kill alone.

🤖 Prompt for AI agents

implement bounded helper shutdown in `scripts/codex.js` so the wrapper always
returns to the shell.

- convert `stopRuntimeRotationAppHelper` (`scripts/codex.js:4013`) to `async`
and await `waitForRuntimeRotationAppHelperExit(helper)`.
- after that wait, check `helper.exitCode === null && helper.signalCode ===
null`. if true, call `helper.kill("SIGKILL")` inside a try/catch as a
best-effort force-stop.
- unconditionally call `helper.stdout?.destroy()`, `helper.stderr?.destroy()`,
and `helper.unref()` at the end of `stopRuntimeRotationAppHelper`, so the piped
fds from `stdio: ["ignore", "pipe", "pipe"]` (`scripts/codex.js:4040`) stop
referencing the event loop. this must match the teardown already present in the
detach branch of `createRuntimeRotationAppHelperContext`
(`scripts/codex.js:4124`).
- in `waitForRuntimeRotationAppHelperExit` (`scripts/codex.js:3998`), fix the
listener leak: inside `finish()`, remove the `helper.once("close", finish)`
listener with `helper.off("close", finish)` (or `removeListener`), so a
timed-out helper does not retain a listener on a still-live child.
- windows edge case: `SIGKILL`/`SIGTERM` are emulated on windows, and the helper
is spawned with `detached: true` (`scripts/codex.js:4041`), so the signal may
not reach the full process group. do not rely on the kill alone to unblock exit
on windows. keep the stream `destroy()`/`unref()` calls unconditional, since
those are what actually let the wrapper exit there.

Phase 3: regression tests and docs

this phase closes the coverage gap the exploration flagged. there is currently no test that asserts resume/fork routing and no direct test of the helper stop/timeout path.

Task 1: add routing regression tests for resume and fork

prove resume/fork now take the canonical-home app-helper path.

• extend test/codex-bin-wrapper.test.ts using the existing fixtures createWrapperFixture, createRuntimeRotationProxyFixtureModule, and runWrapper (test/codex-bin-wrapper.test.ts:65, :303, :612).
• model the new cases on the "app" test and the bare-args interactive test (test/codex-bin-wrapper.test.ts:1111), asserting ["resume", ...] and ["fork", ...] spawn the detached app-helper (app-server-shims/helper-*, runtime-rotation-app-helper.json) and keep CODEX_HOME canonical, not a shadow directory.
• add a negative assertion that exec/review still take the shadow-home path, so the classification split stays covered.

Task 2: add a helper-shutdown regression test for the SIGKILL fallback

prove the wrapper returns even when the helper ignores SIGTERM.

• add a test modeled on the stopChild race pattern in test/codex-app-router.test.ts:89 and the existing helper-spawn test in test/codex-bin-wrapper.test.ts:2470.
• make the fake helper install a SIGTERM handler that ignores the signal, then assert the parent still exits within a bounded time and the helper is gone (via isProcessAlive(pid), test/codex-bin-wrapper.test.ts:627).
• follow the file convention of real subprocesses and real timers with short idle-timeout envs. do not introduce vi.mock("node:child_process"), which no test here uses.
• windows edge case: guard or adapt the ignore-SIGTERM assertion for windows, where the emulated signal semantics differ, so ci does not flake on win32.

Task 3: update architecture and release docs

record that resume/fork now use canonical-home.

• update the runtime rotation transport table and the interactive-branch rationale in docs/development/ARCHITECTURE.md:165 so resume/fork are listed under the canonical-home path, not the shadow path.
• align docs/development/CONFIG_FLOW.md §5-6 and add a changelog entry noting the resume/fork hang fix and the bounded helper-shutdown fix.

🤖 Prompt for AI agents

close the regression coverage gap for the resume/fork routing fix and the
helper-shutdown fix, and update related docs.

- in `test/codex-bin-wrapper.test.ts`, add routing regression tests using the
existing fixtures `createWrapperFixture`,
`createRuntimeRotationProxyFixtureModule`, and `runWrapper`
(`test/codex-bin-wrapper.test.ts:65`, `:303`, `:612`). model the new cases on
the `"app"` test and the bare-args interactive test
(`test/codex-bin-wrapper.test.ts:1111`). assert `["resume", ...]` and `["fork",
...]` spawn the detached app-helper (`app-server-shims/helper-*`,
`runtime-rotation-app-helper.json`) and keep `CODEX_HOME` canonical, not a
shadow directory. add a negative assertion that `exec`/`review` still take the
shadow-home path.
- add a helper-shutdown regression test proving the wrapper returns even when
the helper ignores `SIGTERM`. model it on the `stopChild` race pattern in
`test/codex-app-router.test.ts:89` and the existing helper-spawn test in
`test/codex-bin-wrapper.test.ts:2470`. make the fake helper install a `SIGTERM`
handler that ignores the signal, then assert the parent still exits within a
bounded time and the helper is gone, using `isProcessAlive(pid)`
(`test/codex-bin-wrapper.test.ts:627`). follow the file's existing convention of
real subprocesses and real timers with short idle-timeout envs. do not introduce
`vi.mock("node:child_process")`, since no test in this file uses it.
- windows edge case: guard or adapt the ignore-SIGTERM assertion for windows,
where emulated signal semantics differ, so ci does not flake on `win32`.
- update `docs/development/ARCHITECTURE.md:165`: the runtime rotation transport
table and the interactive-branch rationale must list `resume`/`fork` under the
canonical-home path, not the shadow path.
- align `docs/development/CONFIG_FLOW.md` §5-6 with the new routing, and add a
changelog entry noting both the resume/fork hang fix and the bounded
helper-shutdown fix.

Research

the wrapper lives in scripts/codex.js. it forwards args to the real codex binary and, when enabled, wires runtime rotation through a proxy.

two decisions matter here:

• shouldUseRuntimeRoutingForForwardedArgs (scripts/codex.js:4378) is the enable/disable gate. resume/fork are in its requestCommands set, so rotation stays on for them.
• createRuntimeRotationProxyContextIfEnabled (scripts/codex.js:4154) picks the transport. isCodexAppCommand and isCodexInteractiveTuiCommand (scripts/codex.js:4374) route to the canonical-home app-helper via createRuntimeRotationAppHelperContext (scripts/codex.js:4106). everything else falls through to the shadow-home proxy path (createRuntimeRotationProxyCodexHome).

helper lifecycle is managed by startRuntimeRotationAppHelper (scripts/codex.js:4025), stopRuntimeRotationAppHelper (scripts/codex.js:4013), and waitForRuntimeRotationAppHelperExit (scripts/codex.js:3998).

tests are behavioral and spawn real subprocesses. the main test file is test/codex-bin-wrapper.test.ts.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

implement the routing fix for `mcodex resume`/`mcodex fork` in
`scripts/codex.js`.

- add a new predicate function near `isCodexInteractiveTuiCommand`
(`scripts/codex.js:4374`) that returns true when
`findForwardedCommand(rawArgs)?.command` is `"resume"` or `"fork"`. reuse
`findForwardedCommand` (`scripts/codex.js:4306`) so flag-skipping and `--`
handling stay consistent with the rest of the router.
- do not change `isCodexInteractiveTuiCommand`. it must keep returning true only
for the no-subcommand case.
- in `createRuntimeRotationProxyContextIfEnabled` (`scripts/codex.js:4166`),
extend the existing `isCodexInteractiveTuiCommand` branch so it also triggers
for the new resume/fork predicate, routing both to
`createRuntimeRotationAppHelperContext` (`scripts/codex.js:4106`).
- pass `{ detachOnExit: true, useCanonicalHome: true }` for this branch,
matching the existing interactive tui branch at `scripts/codex.js:4170`.
- do not touch `shouldUseRuntimeRoutingForForwardedArgs`
(`scripts/codex.js:4378`). `resume`/`fork` must remain in its `requestCommands`
set (`scripts/codex.js:4391`) so rotation stays enabled.
- confirm `proxyAppServerAccountRead` does not need to be set for
`resume`/`fork`: it is only set on the shadow-path return, and
`isCodexAppServerCommand` is false for these commands, so nothing is lost by
moving off the shadow path.
- note the concurrency risk in the pr description: the detached helper writes
the canonical session index while a resume/fork session may write it too. this
mirrors existing interactive-tui behavior, so the risk is not new, but it must
be called out.
===============================================================================

Task: 2

implement bounded helper shutdown in `scripts/codex.js` so the wrapper always
returns to the shell.

- convert `stopRuntimeRotationAppHelper` (`scripts/codex.js:4013`) to `async`
and await `waitForRuntimeRotationAppHelperExit(helper)`.
- after that wait, check `helper.exitCode === null && helper.signalCode ===
null`. if true, call `helper.kill("SIGKILL")` inside a try/catch as a
best-effort force-stop.
- unconditionally call `helper.stdout?.destroy()`, `helper.stderr?.destroy()`,
and `helper.unref()` at the end of `stopRuntimeRotationAppHelper`, so the piped
fds from `stdio: ["ignore", "pipe", "pipe"]` (`scripts/codex.js:4040`) stop
referencing the event loop. this must match the teardown already present in the
detach branch of `createRuntimeRotationAppHelperContext`
(`scripts/codex.js:4124`).
- in `waitForRuntimeRotationAppHelperExit` (`scripts/codex.js:3998`), fix the
listener leak: inside `finish()`, remove the `helper.once("close", finish)`
listener with `helper.off("close", finish)` (or `removeListener`), so a
timed-out helper does not retain a listener on a still-live child.
- windows edge case: `SIGKILL`/`SIGTERM` are emulated on windows, and the helper
is spawned with `detached: true` (`scripts/codex.js:4041`), so the signal may
not reach the full process group. do not rely on the kill alone to unblock exit
on windows. keep the stream `destroy()`/`unref()` calls unconditional, since
those are what actually let the wrapper exit there.
===============================================================================

Task: 3

close the regression coverage gap for the resume/fork routing fix and the
helper-shutdown fix, and update related docs.

- in `test/codex-bin-wrapper.test.ts`, add routing regression tests using the
existing fixtures `createWrapperFixture`,
`createRuntimeRotationProxyFixtureModule`, and `runWrapper`
(`test/codex-bin-wrapper.test.ts:65`, `:303`, `:612`). model the new cases on
the `"app"` test and the bare-args interactive test
(`test/codex-bin-wrapper.test.ts:1111`). assert `["resume", ...]` and `["fork",
...]` spawn the detached app-helper (`app-server-shims/helper-*`,
`runtime-rotation-app-helper.json`) and keep `CODEX_HOME` canonical, not a
shadow directory. add a negative assertion that `exec`/`review` still take the
shadow-home path.
- add a helper-shutdown regression test proving the wrapper returns even when
the helper ignores `SIGTERM`. model it on the `stopChild` race pattern in
`test/codex-app-router.test.ts:89` and the existing helper-spawn test in
`test/codex-bin-wrapper.test.ts:2470`. make the fake helper install a `SIGTERM`
handler that ignores the signal, then assert the parent still exits within a
bounded time and the helper is gone, using `isProcessAlive(pid)`
(`test/codex-bin-wrapper.test.ts:627`). follow the file's existing convention of
real subprocesses and real timers with short idle-timeout envs. do not introduce
`vi.mock("node:child_process")`, since no test in this file uses it.
- windows edge case: guard or adapt the ignore-SIGTERM assertion for windows,
where emulated signal semantics differ, so ci does not flake on `win32`.
- update `docs/development/ARCHITECTURE.md:165`: the runtime rotation transport
table and the interactive-branch rationale must list `resume`/`fork` under the
canonical-home path, not the shadow path.
- align `docs/development/CONFIG_FLOW.md` §5-6 with the new routing, and add a
changelog entry noting both the resume/fork hang fix and the bounded
helper-shutdown fix.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

🔗 Related PRs

#462 - Fix Codex TUI goal proxy handling [merged]
#624 - feat(codex): force a specific account per invocation with --account (#623) [merged]
#632 - docs: rewrite product docs for current 2.6.1 architecture [merged]
#639 - fix(codex): avoid runtime shadow reindex on TUI startup [merged]
#642 - fix(codex-cli): pin the official CLI credential store to file on disk (#641) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!