> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SPEC-062 v0.1: Codex Terminal Persona Label — use app-server thread names for in-terminal identity, not title-bar chrome

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

<Info>**Status:** `draft` · **Version** `0.1` · Filed 2026-05-01</Info>

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