Feature proposal: opt-in fresh-session handoff after repeated compactions #22641

Proposal

Add an opt-in automatic fresh-session handoff for long-running TUI sessions after repeated live context compactions, with a children-only mode for roots that are coordinating live thread-spawn subagents.

The motivation is to keep long sessions moving after compaction has preserved continuity a few times, while avoiding a disruptive root-session replacement when the root is actively managing child agents.

Behavior

• auto_new_session_after_compactions = N enables the feature. Unset or 0 keeps current behavior.
• After N live context compactions, Codex asks the current thread to prepare a handoff prompt, starts a replacement thread, and submits that prompt as the replacement thread's first user input.
• Internal sessions do not trigger automatic handoff.
• Replacement root sessions preserve the active persisted goal snapshot.
• Replacement thread-spawn subagents preserve parent linkage, depth, nickname, agent path, role, environment selections, and the active persisted goal snapshot.
• auto_new_session_after_compactions_children_only_with_subagents = true keeps a root session active while it has live thread-spawn subagents. Child subagents can still hand off to replacement child threads.

This keeps the default behavior unchanged while giving users a way to recover cleaner context in long-running and multi-agent workflows.

Proof of concept

A tested implementation exists on a fork branch:

• Branch: https://github.com/Woptope/codex/tree/auto-new-session-after-compactions
• Compare view: main...Woptope:codex:auto-new-session-after-compactions
• Head commit at time of posting: c37239d33

I tried to open a PR from the fork, but GitHub returned:

GraphQL: Woptope does not have the correct permissions to execute `CreatePullRequest`

I also noticed docs/contributing.md says external code contributions are by invitation only, so I am opening this issue first as the requested proposal/discussion artifact rather than asking for unsolicited PR review.

Documentation included in the fork

The branch documents the behavior in:

• docs/auto-fresh-session-handoff.md
• docs/config.md
• docs/example-config.md
• generated config schema descriptions

Validation run

• just write-config-schema
• just write-app-server-schema
• just fmt
• cargo test -p codex-app-server auto_handoff
• cargo test -p codex-core auto_new_session_after_compactions
• cargo test -p codex-core auto_handoff_children_only_with_subagents
• cargo test -p codex-state insert_thread_goal_snapshot
• cargo test -p codex-app-server-protocol
• cargo test -p codex-tui auto_handoff
• git diff --check

Maintainer ask

• Is this behavior aligned with the direction for long-running Codex sessions and subagents?
• Is the config surface acceptable, or should this be exposed differently?
• If the approach is useful, what is the preferred path for review given the current external contribution policy?