​

Title: Codex Terminal Persona Label — use app-server thread names for in-terminal identity, not title-bar chrome

​

Version

0.1

​

Status

draft

​

Problem

Prism needs a Codex-visible persona marker comparable to the Claude Code statusline. The existing coder launcher already writes the persona and project into the terminal/window title via OSC escape sequences, but that is terminal chrome, not content inside the Codex terminal UI. The operator explicitly asked for the persona name within the Codex terminal, not the window title bar, and noted that a related path worked before the SPEC-054 port/regression work. The working distinction is:

• Title-bar watcher: outer terminal chrome, useful but insufficient.
• Codex app-server thread name: Codex-native, user-facing thread label rendered by the Codex TUI/app surfaces.
• Codex app-server turn/steer / turn/start: inline dynamic notices in the conversation flow, suitable for signals and statusline simulation events.

​

Research Notes

Research was performed against installed codex-cli 0.125.0 on 2026-05-01. Findings:

1. codex --help exposes --remote, --no-alt-screen, and app-server controls, but no documented --statusline or footer customization flag.
2. Prism bin/coder.sh and bin/coder.ps1 already set terminal/window title using OSC title escape sequences. That is not the requested in-terminal surface.
3. codex app-server generate-json-schema exposes thread/name/set with params { threadId, name }.
4. The generated schema describes thread name as an optional user-facing thread title.
5. A live app-server test against ws://127.0.0.1:45650 successfully set current thread 019de107-4e85-7760-94cf-252a3b426fe0 from name=null to name="Texi · prism"; thread/read confirmed the result.

​

Goal

On Codex bootstrap, if an app-server URL and loaded thread are available, set the Codex thread name to a concise persona/project label: <PRISM_AGENT_IDENTITY> · <PRISM_PROJECT_NAME> Example: Texi · prism This gives operators an in-terminal Codex identity label without relying on window-title chrome.

​

Non-Goals

• Do not remove the existing terminal-title watcher; it remains useful for OS/window/tab discrimination.
• Do not claim a general Codex footer/statusline API exists unless Codex exposes one.
• Do not put dynamic signal counts into the static thread name in v0.1.
• Do not route Prism FastAPI directly to Codex app-server.
• Do not expose Codex app-server off loopback.

​

Design

Extend AppServerInjectStrategy with a non-fatal setThreadName(name) method. Behavior:

1. Discover thread id from PRISM_CODEX_THREAD_ID, CODEX_THREAD_ID, or thread/loaded/list, following the existing strategy discovery path.
2. Call app-server method thread/name/set with { threadId, name }.
3. Treat failure as non-fatal and keep Codex delivery on piggyback/app-server signal paths.
4. Run this from CodexSurface.onBootstrap after strategy construction.

Label construction:

• Identity comes from bootstrap context agentIdentity or PRISM_AGENT_IDENTITY.
• Project name comes from PRISM_PROJECT_NAME.
• Fallback label is identity alone when project is missing.
• Empty or Bot identities should not overwrite a useful existing thread name unless explicitly launched that way.

​

Operator-Visible Effect

After prism_start in a Codex session with app-server enabled, the Codex terminal/app thread label shows the Prism runtime identity and project, for example Texi · prism. This is distinct from the terminal title bar. Dynamic Prism signals still appear inline through turn/steer during active turns or turn/start when idle.

​

Acceptance Tests

1. Fake app-server smoke: Codex bootstrap label path calls thread/name/set with the current thread id and expected name.
2. Fake app-server smoke: missing/no loaded thread is non-fatal and does not throw out of surface bootstrap.
3. npm run build in mcp-node succeeds.
4. Live manual test: with Codex app-server running, thread/read reports thread.name = "Texi · prism" after bootstrap.

​

Open Questions

1. Whether signal counts should later update the thread name, or remain only in inline signal messages and/or title chrome.
2. Whether Codex will expose a first-class terminal footer/statusline API later; if so, that should replace or supplement the thread-name approach.
3. Whether thread naming should be reset on wrap or left as useful session history.