Document how app-server clients can discover and attach to the active Codex Desktop thread

[bakemocho]

What feature would you like to see?

I would like a supported, documented app-server path for a local external client
to discover and attach to the currently active Codex Desktop thread/turn.

The goal is not to change model behavior. The goal is to let a local integration
safely answer:

• which thread is the active Desktop UI session?
• is there an in-flight turn?
• can the client subscribe to that thread's live events?
• can the client steer or interrupt that in-flight turn through a supported API?
• if this is unsupported, how should clients detect that instead of guessing?

Problem

The documented app-server primitives work well for threads that the client
creates through app-server: a client can start a thread, start a turn, observe
events, and call turn/interrupt against a turn it owns.

The unclear case is an already-running Codex Desktop UI session. In local
experiments, an external client could see stored thread history, but could not
reliably bind that persisted thread to a loaded, controllable Desktop UI turn.

Observed shape:

• thread/list can show stored threads.
• thread/read with includeTurns:false can read a selected stored thread.
• thread/loaded/list can return zero loaded threads from the client-visible
  app-server surface.
• a turn/interrupt attempt against the selected active-thread candidate
  returned thread not found.
• direct stdio against the active Desktop-bundled codex app-server can return
  inventory, but still did not expose a loaded UI thread to control.

That leaves external clients with unsafe options: infer the current thread from
local session files, update times, or UI-visible labels, then try a control
method that may be targeting a persisted-but-not-loaded thread or the wrong
app-server process.

Environment from one local probe

• Platform: macOS / Darwin arm64
• Codex Desktop bundle: 26.527.60818 / build 3437
• Desktop-bundled codex: codex-cli 0.136.0-alpha.2
• Standalone current codex: codex-cli 0.135.0

Why this matters

This blocks safe local orchestration around Codex Desktop sessions.

Examples:

• a local supervisor wants to notify or steer a long-running Desktop session;
• a recovery tool wants to tell whether a Desktop turn is still running, lost,
  interrupted, or only persisted;
• a multi-agent/local automation layer wants to coordinate with a user-visible
  Desktop session instead of creating detached hidden workers;
• a client wants to avoid scraping local session files or guessing from file
  modification times.

Without an official current-Desktop-thread discovery/attachment contract, a
client can prove that app-server control works for threads it created, but not
that it can safely control the existing Desktop UI thread the user is looking at.

Desired outcome

Any of these would address the gap:

1. A documented API to read the current Desktop UI thread id and active turn id
   for the local app instance.
2. A documented way to attach/subscribe an external app-server client to an
   already-loaded Desktop UI thread.
3. A documented way to resume or load a persisted thread into a controllable
   app-server process without starting a new unrelated UI session.
4. Clear errors that distinguish:
   • unknown thread id,
   • persisted but not loaded,
   • loaded in another app-server process,
   • no active turn,
   • unsupported existing-UI-session control.
5. Documentation stating that existing Desktop UI session control is not
   supported, plus the recommended integration pattern.

Related issues

Related but not the same:

• Clarify app-server turn lifecycle semantics for external clients #20943 asks for clearer app-server turn lifecycle semantics for external
  clients. This issue is about identifying and attaching to the active Desktop
  thread before lifecycle handling begins.
• Support inbound MCP notifications routed into an active Codex CLI session #15299 asks for inbound notifications into an active CLI session. This issue
  is about app-server clients and Codex Desktop.
• Support remote app-server threads in Desktop thread orchestration #25482 asks for remote app-server threads in Desktop thread orchestration.
  This issue is about the local active Desktop UI thread.
• Codex Desktop meta-bug: unbounded session/turn state causes freezes, context bloat, and lost active-turn control #25779 is a broader Desktop/session active-turn reliability meta issue. This
  issue is narrower and asks for a supported external-client contract.
• TUI turn interrupt failure can lose session context #24518 covers a TUI turn/interrupt failure path.
• codex app-server proxy hangs on WebSocket-framed initialize while direct Unix socket succeeds #25846 covers codex app-server proxy transport behavior; this request is
  about active Desktop thread discovery/attachment, not proxy framing.

Additional notes

I am intentionally not including raw thread ids, turn ids, local session file
paths, or transcript text here. The public observation is the control-surface
shape: persisted thread visibility does not currently imply that an external
client has a supported loaded-turn target for the current Desktop UI session.

[bakemocho]

Update: After filing this, I found the 2026-05-29 Codex app 26.527 changelog
and the app docs for thread coordination/worktrees. I had not seen that feature
when I opened this issue; if I had, I may not have filed it in this exact form.

The remaining gap I meant to ask about is narrower: I still do not see a
documented app-server / external-client contract for discovering or attaching to
the thread/turn that is currently active in the Codex Desktop UI. So I think
this issue is better scoped as a request to document that boundary, not as a
request for general thread/worktree coordination.

One practical caveat: I am close to my current Codex quota limit, so I cannot
immediately verify the new Desktop thread-coordination behavior myself. For now
I am effectively blocked from testing the workflow end to end until quota is
available again.

[bakemocho]

I have a more precise update after testing the app-server control path again.

The large-history part is no longer the main blocker in my local repro. With a
detached local app-server process, I can resume the current Desktop thread in a
low-payload shape and verify that the bounded first page
matches the active-turn candidate I found locally. That part did not hit the
2 MB reader limit.

The remaining gap is live-turn ownership or attachment:

• In the detached app-server process, the current Desktop thread can be loaded
  and resumed, but turn/steer for the discovered active turn returns
  no active turn to steer.
• Talking directly to the daemon control socket over WebSocket also works for
  initialize, thread/loaded/list, and thread/resume with excludeTurns.
  The selected Desktop thread is visible as loaded there too, but the same
  turn/steer request still returns no active turn to steer.
• Separately, codex app-server proxy --sock ... still times out for a minimal
  WebSocket-framed initialize, while the raw socket route succeeds. I think
  that is a different proxy/transport issue from the active-turn attachment
  question here.

So the request I would find most useful is documentation for this boundary:

Can an external local app-server client attach to the live active turn that is
currently running in the Codex Desktop UI, or can it only load/read/resume the
persisted thread record in its own control context? If the latter is intended,
an explicit unsupported-boundary note and the supported alternative would be
enough.