Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(chat): codex joins CHAT_CAPABLE, local and over SSH

review0ec751341a1d
diff --git a/src/core/codex-chat.locate.test.ts b/src/core/codex-chat.locate.test.ts
index 51f77d6ef..e37af7f76 100644
--- a/src/core/codex-chat.locate.test.ts
+++ b/src/core/codex-chat.locate.test.ts
@@ -81,7 +81,9 @@ describe('locateCodexRollout', () => {
it('reads a MANAGED account\'s own home, never the system one', async () => {
const acct = 'acct-1'
- const managed = path.join(codexHomeForAccount(f.userDataDir, acct, path.join(home, '.nodeterm', 'cx')), 'sessions')
+ // os.homedir() is mocked, so the managed short root lands inside this test's temp home.
+ const managed = path.join(codexHomeForAccount(f.userDataDir, acct), 'sessions')
+ expect(managed.startsWith(home)).toBe(true)
put(sessions(), `2026/09/24/rollout-2026-09-24T09-00-00-${ID}.jsonl`) // the system home's copy
expect(await locateCodexRollout({ sessionId: ID, accountId: acct })).toBeUndefined()
const mine = put(managed, `2026/09/24/rollout-2026-09-24T09-00-00-${ID}.jsonl`)
diff --git a/src/core/codex-chat.test.ts b/src/core/codex-chat.test.ts
index 286dea8ed..0b520b057 100644
--- a/src/core/codex-chat.test.ts
+++ b/src/core/codex-chat.test.ts
@@ -59,7 +59,7 @@ const records = (text: string): Array<{ raw: string; offset: number }> => {
}
const parsePaged = (text: string) => parseCodexChatRecords(records(text), true)
const texts = (msgs: ReturnType<typeof chatMessagesFromCodex>) =>
- msgs.map((m) => `${m.role}:${m.parts.map((p) => (p.kind === 'text' ? p.text : `[${p.name}] ${p.arg}`)).join('|')}`)
+ msgs.map((m) => `${m.role}:${m.parts.map((p) => (p.kind === 'text' ? p.text : p.kind === 'tool' ? `[${p.name}] ${p.arg}` : `<${p.kind}>`)).join('|')}`)
describe('user turns', () => {
it('reads the TYPED prompt from the UI record, never the model-side copy or the injected context (paginated)', () => {
diff --git a/src/main/codex-chat-wiring.test.ts b/src/main/codex-chat-wiring.test.ts
new file mode 100644
index 000000000..c1466409e
--- /dev/null
+++ b/src/main/codex-chat-wiring.test.ts
@@ -0,0 +1,26 @@
+// The codex ⌘M reader's two shell legs are OPTIONAL deps of `registerTranscriptIpc`
+// (`codexPathFor`, `readRemoteCodexPage`), so dropping either compiles and passes every unit test
+// while the feature degrades in silence: without the remote leg every SSH codex node answers
+// "Couldn't read the transcript."; without the hint a relocated `CODEX_HOME` finds nothing. The
+// closures live in the shells, so this pins them at source level — the remedy this repo uses for
+// that class of hole (host-chat-wiring.test.ts, hook-verified-parity.test.ts).
+import { describe, expect, it } from 'vitest'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const read = (rel: string): string => fs.readFileSync(path.join(__dirname, '..', rel), 'utf8').replace(/\r\n/g, '\n')
+
+describe('codex chat reader is wired in both shells', () => {
+ it('the desktop passes codex\'s own hint and remote leg, through the SAME resolvers as its remote meter', () => {
+ const src = read('main/index.ts')
+ expect(src).toMatch(/codexPathFor: \(sessionId\) => codexContextTail\.pathFor\(sessionId\)/)
+ expect(src).toMatch(/readRemoteCodexPage: createReadRemoteCodexPage\(\{\n\s*targetFor: remoteCodexTargetFor,\n\s*knownAccount: knownRemoteCodexAccount,\n\s*run: runRemoteCodex,/)
+ // …and the context meter reads through those very functions, so the two cannot disagree.
+ expect(src).toMatch(/createRemoteCodexContext\(\{\n\s*targetFor: remoteCodexTargetFor,\n\s*knownAccount: knownRemoteCodexAccount,\n\s*run: runRemoteCodex,/)
+ // One deps object serves ⌘M AND the phone's chat.page.
+ expect(src).toMatch(/registerTranscriptIpc\(transcriptIpcDeps\)/)
+ })
+ it('the Server Edition passes codex\'s hint (it runs on the host, so it needs no remote leg)', () => {
+ expect(read('server/index.ts')).toMatch(/codexPathFor: \(sessionId\) => codexContextTail\.pathFor\(sessionId\)/)
+ })
+})
diff --git a/src/main/index.ts b/src/main/index.ts
index baa1cb1db..6eda68441 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1,6 +1,6 @@
import { createRemoteContextEnsure } from '../core/remote-context-ensure'
import { isKnownRemoteCodexAccount } from '../core/remote-ssh/codex-home'
-import { createRemoteCodexContext } from '../core/remote-ssh/codex-context'
+import { createRemoteCodexContext, type RemoteCodexContextTarget } from '../core/remote-ssh/codex-context'
import { subagentReplay } from '../core/subagent-replay'
import { grokHomeDir, grokSessionDir, grokSessionsDir } from '../core/agents/grok-paths'
import { join, resolve, posix } from 'path'
@@ -244,6 +244,7 @@ import {
type RemoteRefLookup,
type RemoteTranscriptRefCache
} from './remote-transcript-page'
+import { createReadRemoteCodexPage } from './remote-codex-chat-page'
import { createRemoteContextTail } from './remote-context-tail'
import { createRemoteSubagentTail } from './remote-subagent-tail'
import { RemoteFile, type RemoteFileRef } from './remote-ssh/remote-file'
@@ -2444,23 +2445,30 @@ app.whenReady().then(async () => {
if (scoped) pushContextUpdate(scoped)
}, remoteFile, { parse: codexContextParse, parseModel: codexContextModel })
// Persisted SSH ownership remains remote while the master is down or before PTY co-attach.
- const remoteCodexContext = createRemoteCodexContext({
- targetFor: (nodeId) => {
- const projectId = workspaceStore.sshProjectIdForNode(nodeId)
- const live = ptyManager.sshRemoteForNode(nodeId)
- if (!projectId && !live) return undefined
- const rt = live ?? (projectId ? sshProjectManager?.refForProject(projectId) : undefined)
- const node = workspaceStore.getNode(nodeId)
- if (!rt || !node) return null
- return { conn: rt.conn, controlPath: rt.controlPath,
- remoteHome: sshProjectManager?.remoteHomeForControlPath(rt.controlPath), accountId: node.accountId,
- connectionKey: sshProjectManager?.connectionKeyForControlPath(rt.controlPath) }
- },
- knownAccount: (id, target) => isKnownRemoteCodexAccount(
- settingsStore.get().codexAccounts ?? [], id, sshHostKey(target.conn)),
- run: (target, command) => sshProjectManager
+ // Named (not inline) because the codex ⌘M reader (`readRemoteCodexPage` below) resolves a node's
+ // host, account and master through the SAME three functions: the meter and the chat can never
+ // disagree about where a codex node's rollout lives.
+ const remoteCodexTargetFor = (nodeId: string): RemoteCodexContextTarget | null | undefined => {
+ const projectId = workspaceStore.sshProjectIdForNode(nodeId)
+ const live = ptyManager.sshRemoteForNode(nodeId)
+ if (!projectId && !live) return undefined
+ const rt = live ?? (projectId ? sshProjectManager?.refForProject(projectId) : undefined)
+ const node = workspaceStore.getNode(nodeId)
+ if (!rt || !node) return null
+ return { conn: rt.conn, controlPath: rt.controlPath,
+ remoteHome: sshProjectManager?.remoteHomeForControlPath(rt.controlPath), accountId: node.accountId,
+ connectionKey: sshProjectManager?.connectionKeyForControlPath(rt.controlPath) }
+ }
+ const knownRemoteCodexAccount = (id: string, target: RemoteCodexContextTarget): boolean =>
+ isKnownRemoteCodexAccount(settingsStore.get().codexAccounts ?? [], id, sshHostKey(target.conn))
+ const runRemoteCodex = (target: RemoteCodexContextTarget, command: string): Promise<{ code: number; stdout: string }> =>
+ sshProjectManager
? sshProjectManager.sshRun(childArgs(target.conn, target.controlPath, command))
- : Promise.resolve({ code: 1, stdout: '' }),
+ : Promise.resolve({ code: 1, stdout: '' })
+ const remoteCodexContext = createRemoteCodexContext({
+ targetFor: remoteCodexTargetFor,
+ knownAccount: knownRemoteCodexAccount,
+ run: runRemoteCodex,
tail: remoteCodexContextTail,
onTrack: (nodeId, sessionId) => { nodeContextSession.set(nodeId, sessionId) },
onClear: (nodeId, sessionId) => {
@@ -2663,6 +2671,16 @@ app.whenReady().then(async () => {
refFor: (q) => locateRemoteRef(q, sshTargetForNode),
readPage: (ref, before, maxBytes) => remoteFile.readTranscriptPage(ref, before, maxBytes)
}),
+ // CODEX's own two legs (`readChatTranscript` routes a codex node here, never through claude's
+ // `pathFor` / `readRemotePage` above): the hint its context tail learned from a hook, and the
+ // remote page — located on the host through the same resolvers as its remote context meter.
+ codexPathFor: (sessionId) => codexContextTail.pathFor(sessionId),
+ readRemoteCodexPage: createReadRemoteCodexPage({
+ targetFor: remoteCodexTargetFor,
+ knownAccount: knownRemoteCodexAccount,
+ run: runRemoteCodex,
+ readPage: (ref, before, maxBytes) => remoteFile.readTranscriptPage(ref, before, maxBytes)
+ }),
remoteExists: async ({ sessionId, accountId, nodeId }) =>
sessionId ? await remoteTranscriptPresence(sessionId, accountId, nodeId) : null,
// Remoteness from THIS shell's records (live pty or SSH project), so every read channel refuses
diff --git a/src/main/remote-codex-chat-page.test.ts b/src/main/remote-codex-chat-page.test.ts
new file mode 100644
index 000000000..f1481328c
--- /dev/null
+++ b/src/main/remote-codex-chat-page.test.ts
@@ -0,0 +1,131 @@
+// The desktop's remote leg of a codex ⌘M page: locate the rollout ON the host (the account-scoped,
+// symlink-refusing locator the context meter already uses), then the same ranged read claude's
+// remote leg uses. Every failure is terminal — a remote node is never read from this machine.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { createReadRemoteCodexPage } from './remote-codex-chat-page'
+import type { RemoteCodexContextTarget } from '../core/remote-ssh/codex-context'
+import type { TranscriptPage } from '../core/remote-ssh/transcript-window'
+import type { TranscriptQuery } from '../core/transcript-ipc'
+
+const SID = '01a0c9f4-2b7e-7c31-9d52-5e8a1f3b6c20'
+const conn = { host: 'box', user: 'u', port: 22 } as RemoteCodexContextTarget['conn']
+const target: RemoteCodexContextTarget = { conn, controlPath: '/tmp/cm', remoteHome: '/home/u' }
+const q: TranscriptQuery = { sessionId: SID, cwd: '/srv', accountId: undefined, nodeId: 'n1' }
+const PAGE = { before: null, maxBytes: 262144 }
+const FILE = `/home/u/.codex/sessions/2026/09/24/rollout-2026-09-24T09-00-00-${SID}.jsonl`
+
+function harness(over: Partial<Parameters<typeof createReadRemoteCodexPage>[0]> = {}) {
+ const run = vi.fn(async () => ({ code: 0, stdout: `/home/u/.codex/sessions\n${FILE}\n` }))
+ const readPage = vi.fn(async (): Promise<TranscriptPage> => ({ data: Buffer.from('{}\n'), start: 0, end: 3, size: 3 }))
+ const deps = {
+ targetFor: vi.fn((): RemoteCodexContextTarget | null | undefined => target),
+ knownAccount: vi.fn(() => true),
+ run,
+ readPage,
+ ...over
+ }
+ return { deps, read: createReadRemoteCodexPage(deps) }
+}
+
+describe('createReadRemoteCodexPage', () => {
+ it('a local node is not its business (null ⇒ take the local path)', async () => {
+ const h = harness({ targetFor: vi.fn(() => undefined) })
+ expect(await h.read(q, PAGE)).toBeNull()
+ expect(await h.read({ ...q, nodeId: undefined }, PAGE)).toBeNull()
+ expect(h.deps.run).not.toHaveBeenCalled()
+ })
+
+ it('locates on the host, then reads the page over the same master', async () => {
+ const h = harness()
+ expect(await h.read(q, PAGE)).toEqual({ ok: true, data: Buffer.from('{}\n'), start: 0 })
+ expect(h.deps.readPage).toHaveBeenCalledWith({ conn, controlPath: '/tmp/cm', path: FILE }, null, 262144)
+ // The located path is remembered: the next page costs one round trip, not two.
+ await h.read(q, { before: 100, maxBytes: 524288 })
+ expect(h.deps.run).toHaveBeenCalledTimes(1)
+ })
+
+ it('a remote node with no master / no record is UNREADABLE', async () => {
+ expect(await harness({ targetFor: vi.fn(() => null) }).read(q, PAGE)).toEqual({ ok: false })
+ })
+
+ it('no id, or one that is not a whole thread uuid, is a clean miss — nothing is run', async () => {
+ const h = harness()
+ for (const sessionId of [undefined, '5e8a1f3b6c20', '../x']) {
+ expect(await h.read({ ...q, sessionId }, PAGE)).toEqual({ ok: false, absent: true })
+ }
+ expect(h.deps.run).not.toHaveBeenCalled()
+ })
+
+ it('a managed account the host does not know is refused before any command', async () => {
+ const h = harness({ targetFor: vi.fn(() => ({ ...target, accountId: 'acct' })), knownAccount: vi.fn(() => false) })
+ expect(await h.read(q, PAGE)).toEqual({ ok: false })
+ expect(h.deps.run).not.toHaveBeenCalled()
+ })
+
+ it('an unsafe remote home for a managed account is unreadable, not a throw', async () => {
+ const h = harness({ targetFor: vi.fn(() => ({ ...target, remoteHome: undefined, accountId: 'acct' })) })
+ expect(await h.read(q, PAGE)).toEqual({ ok: false })
+ })
+
+ it('the host LOOKED and found nothing (exit 0, empty) = absent; a failed ask or a malformed answer = unreadable', async () => {
+ expect(await harness({ run: vi.fn(async () => ({ code: 0, stdout: '' })) }).read(q, PAGE)).toEqual({ ok: false, absent: true })
+ expect(await harness({ run: vi.fn(async () => ({ code: 255, stdout: '' })) }).read(q, PAGE)).toEqual({ ok: false })
+ expect(await harness({ run: vi.fn(async () => { throw new Error('ssh') }) }).read(q, PAGE)).toEqual({ ok: false })
+ // A path outside the sessions root the host itself reported is refused by the jail.
+ const escape = { code: 0, stdout: `/home/u/.codex/sessions\n/etc/rollout-x-${SID}.jsonl\n` }
+ expect(await harness({ run: vi.fn(async () => escape) }).read(q, PAGE)).toEqual({ ok: false })
+ })
+
+ it('a failed page read is unreadable AND forgets the located path, so a retry locates again', async () => {
+ const h = harness()
+ vi.mocked(h.deps.readPage).mockRejectedValueOnce(new Error('master died'))
+ expect(await h.read(q, PAGE)).toEqual({ ok: false })
+ expect(await h.read(q, PAGE)).toMatchObject({ ok: true })
+ expect(h.deps.run).toHaveBeenCalledTimes(2)
+ })
+
+ it('the remembered path is per node, target and session — never shared across hosts', async () => {
+ const h = harness()
+ await h.read(q, PAGE)
+ vi.mocked(h.deps.targetFor).mockReturnValue({ ...target, controlPath: '/tmp/other-host' })
+ await h.read(q, PAGE)
+ await h.read({ ...q, nodeId: 'n2' }, PAGE)
+ expect(h.deps.run).toHaveBeenCalledTimes(3)
+ })
+})
+
+describe.skipIf(process.platform === 'win32')('createReadRemoteCodexPage against a real /bin/sh host tree', () => {
+ let dir: string | undefined
+ afterEach(() => {
+ if (dir) rmSync(dir, { recursive: true, force: true })
+ })
+ it('the generated locate command finds exactly this thread under the host CODEX_HOME', async () => {
+ dir = mkdtempSync(path.join(tmpdir(), 'codex-chat-remote-'))
+ const codexHome = path.join(dir, 'codex home')
+ const folder = path.join(codexHome, 'sessions', '2026', '09', '24')
+ mkdirSync(folder, { recursive: true })
+ const mine = path.join(folder, `rollout-2026-09-24T09-00-00-${SID}.jsonl`)
+ writeFileSync(mine, '{"type":"x"}\n')
+ writeFileSync(path.join(folder, 'rollout-2026-09-24T09-00-00-01a0c9f4-2b7e-7c31-9d52-5e8a1f3b6c99.jsonl'), 'OTHER\n')
+ const read = createReadRemoteCodexPage({
+ targetFor: () => ({ ...target, remoteHome: dir }),
+ knownAccount: () => true,
+ run: async (_t, command) => ({
+ code: 0,
+ stdout: execFileSync('/bin/sh', ['-c', command], {
+ encoding: 'utf8',
+ env: { PATH: process.env.PATH, SHELL: '/bin/sh', CODEX_HOME: codexHome }
+ })
+ }),
+ readPage: async (ref) => {
+ const data = readFileSync(ref.path)
+ return { data, start: 0, end: data.length, size: data.length }
+ }
+ })
+ expect(await read(q, PAGE)).toEqual({ ok: true, data: Buffer.from('{"type":"x"}\n'), start: 0 })
+ })
+})
diff --git a/src/main/remote-codex-chat-page.ts b/src/main/remote-codex-chat-page.ts
new file mode 100644
index 000000000..dc85cb849
--- /dev/null
+++ b/src/main/remote-codex-chat-page.ts
@@ -0,0 +1,88 @@
+// The desktop's remote leg of a CODEX ⌘M page (`TranscriptIpcDeps.readRemoteCodexPage`), pulled out
+// of `src/main/index.ts` so its rules are testable without booting the shell.
+//
+// It is claude's remote leg (`createReadRemotePage`) with codex's locator in place of claude's: the
+// rollout is found ON the host by `remoteCodexTranscriptCommand` — the account-scoped, symlink-
+// refusing locate the context meter already runs (`core/remote-ssh/codex-context.ts`) — and read
+// with the same ranged page read. Its answers follow `RemoteTranscriptPage`:
+// null → not a remote node (take the local path)
+// {ok:false} → remote, and we could not ask — TERMINAL, never this machine's disk
+// {ok:false, absent:true} → the host looked and has no such rollout (or no id to look for)
+import type { RemoteTranscriptPage, TranscriptQuery } from '../core/transcript-ipc'
+import type { ChatTranscriptPage } from '../shared/chat-page'
+import type { TranscriptPage } from '../core/remote-ssh/transcript-window'
+import type { RemoteFileRef } from './remote-ssh/remote-file'
+import {
+ parseRemoteCodexTranscript,
+ remoteCodexTranscriptCommand,
+ type RemoteCodexContextTarget
+} from '../core/remote-ssh/codex-context'
+import { CODEX_THREAD_ID_RE } from '../core/codex-chat'
+
+/** Located paths kept at most (per node × host × account × thread); oldest dropped first. */
+const LOCATED_MAX = 500
+
+export interface RemoteCodexChatPageDeps {
+ /** `undefined` = a local node; `null` = an SSH node whose master / record is unavailable. The same
+ * resolver the remote codex context meter uses, so the two can never disagree on where a node is. */
+ targetFor(nodeId: string): RemoteCodexContextTarget | null | undefined
+ /** A managed account is read only when it is a saved, non-pending account for this host. */
+ knownAccount(accountId: string, target: RemoteCodexContextTarget): boolean
+ run(target: RemoteCodexContextTarget, command: string): Promise<{ code: number; stdout: string }>
+ /** Strict ranged read (`RemoteFile.readTranscriptPage`): throws on any failure. */
+ readPage(ref: RemoteFileRef, before: number | null, maxBytes: number): Promise<TranscriptPage>
+}
+
+export function createReadRemoteCodexPage(
+ deps: RemoteCodexChatPageDeps
+): (q: TranscriptQuery, page: ChatTranscriptPage) => Promise<RemoteTranscriptPage | null> {
+ // A LOCATED path, keyed by everything that could make it wrong: another node, another host or
+ // master, another home, another account, another thread. Forgotten on a failed read, so a Retry
+ // locates afresh instead of replaying a dead path.
+ const located = new Map<string, string>()
+ return async (q, page) => {
+ if (!q.nodeId) return null
+ const target = deps.targetFor(q.nodeId)
+ if (target === undefined) return null
+ if (target === null) return { ok: false }
+ // The locate command already refuses an id outside claude's looser alphabet; the WHOLE-uuid
+ // check is codex's own (a uuid's last group would otherwise match another thread's file name).
+ if (!q.sessionId || !CODEX_THREAD_ID_RE.test(q.sessionId)) return { ok: false, absent: true }
+ if (target.accountId && !deps.knownAccount(target.accountId, target)) return { ok: false }
+ const key = JSON.stringify([q.nodeId, target.controlPath, target.remoteHome ?? null, target.accountId ?? null, q.sessionId])
+ let file = located.get(key)
+ if (!file) {
+ let command: string | undefined
+ try {
+ command = remoteCodexTranscriptCommand(target, q.sessionId)
+ } catch {
+ // A managed account's home needs the host's resolved $HOME; without a safe one there is
+ // nothing we may ask for.
+ return { ok: false }
+ }
+ if (!command) return { ok: false, absent: true }
+ let stdout: string
+ try {
+ const r = await deps.run(target, command)
+ if (r.code !== 0) return { ok: false }
+ stdout = r.stdout
+ } catch {
+ return { ok: false }
+ }
+ // The locate exits 0 with NO output on a clean miss — an answer, not a failed ssh.
+ if (!stdout.trim()) return { ok: false, absent: true }
+ // Anything else must be the two jailed lines; a malformed or escaping answer is a failure.
+ file = parseRemoteCodexTranscript(stdout, q.sessionId)
+ if (!file) return { ok: false }
+ located.set(key, file)
+ if (located.size > LOCATED_MAX) located.delete(located.keys().next().value!)
+ }
+ try {
+ const w = await deps.readPage({ conn: target.conn, controlPath: target.controlPath, path: file }, page.before, page.maxBytes)
+ return { ok: true, data: w.data, start: w.start }
+ } catch {
+ located.delete(key)
+ return { ok: false }
+ }
+ }
+}
diff --git a/src/main/remote/host-chat.test.ts b/src/main/remote/host-chat.test.ts
index e1221089b..aa1b20a6e 100644
--- a/src/main/remote/host-chat.test.ts
+++ b/src/main/remote/host-chat.test.ts
@@ -67,7 +67,7 @@ describe('host-chat page', () => {
await expect(createHostChat(d).page('n1', {})).rejects.toThrow()
})
it('serves only chat-capable agents (resolved through the base harness), and reads nothing otherwise', async () => {
- for (const agentId of ['codex', 'gemini', undefined]) {
+ for (const agentId of ['gemini', undefined]) {
const d = deps({ lookupNode: () => ({ agentId, sessionId: 'sid-1' }) })
expect(await createHostChat(d).page('n1', {})).toBe('unsupported')
expect(d.readTranscript).not.toHaveBeenCalled()
@@ -80,6 +80,11 @@ describe('host-chat page', () => {
setCustomAgentBaseResolver(null)
}
})
+ it('serves a codex node, passing its own agent id so core routes it to the codex reader', async () => {
+ const d = deps({ lookupNode: () => ({ cwd: '/srv/app', agentId: 'codex', sessionId: 'sid-1', remote: true }) })
+ expect(await createHostChat(d).page('n1', {})).toMatchObject({ version: 1 })
+ expect(d.readTranscript).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'codex', remoteOnly: true }), {})
+ })
it('an absent page is the default paged tail, not the legacy read', async () => {
const d = deps()
await createHostChat(d).page('n1', undefined)
diff --git a/src/server/index.ts b/src/server/index.ts
index 2b71c4896..484c631a8 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -489,7 +489,11 @@ export async function startServer(
// of the handlers because the hook-fed path authority is the tail created just above. No remote
// leg: the Server Edition runs ON the host whose transcripts it reads, so local resolution is
// the complete answer (an SSH-project node is a desktop-only concept here).
- registerTranscriptIpc({ pathFor: (sessionId) => contextTail.pathFor(sessionId) })
+ registerTranscriptIpc({
+ pathFor: (sessionId) => contextTail.pathFor(sessionId),
+ // Codex's ⌘M reader takes ITS tail's hook path (claude's `pathFor` must never answer a codex id).
+ codexPathFor: (sessionId) => codexContextTail.pathFor(sessionId)
+ })
// The context meter's mount-time rehydration, registered beside the read channels and for the
// same reason: the tails it feeds are the ones created just above. Until this landed the Server
// Edition had NO handler for `context:ensure` at all — the browser cast it and nothing received
diff --git a/src/shared/agents/config.chat-codex.test.ts b/src/shared/agents/config.chat-codex.test.ts
new file mode 100644
index 000000000..2788465d3
--- /dev/null
+++ b/src/shared/agents/config.chat-codex.test.ts
@@ -0,0 +1,22 @@
+// Codex joins the ⌘M chat view (CHAT_CAPABLE) through its OWN reader (core/codex-chat.ts), and the
+// pair invariant grok established holds for it too: rendering a codex conversation ourselves says
+// nothing about claude's resolver being able to find it.
+import { afterEach, describe, expect, it } from 'vitest'
+import { canChat, readsClaudeShapedTranscript, setCustomAgentBaseResolver } from './config'
+
+afterEach(() => setCustomAgentBaseResolver(null))
+
+describe('codex chat capability', () => {
+ it('is CHAT_CAPABLE and NOT readable by claude\'s resolver', () => {
+ expect(canChat('codex')).toBe(true)
+ // A codex thread id never resolves under ~/.claude/projects, so claude's cwd fallback would
+ // answer with the newest CLAUDE session in the directory — a stranger's conversation.
+ expect(readsClaudeShapedTranscript('codex')).toBe(false)
+ })
+
+ it('a custom agent on the codex harness inherits the chat view', () => {
+ setCustomAgentBaseResolver((id) => (id === 'custom:cx' ? 'codex' : undefined))
+ expect(canChat('custom:cx')).toBe(true)
+ expect(readsClaudeShapedTranscript('custom:cx')).toBe(false)
+ })
+})
diff --git a/src/shared/agents/config.ts b/src/shared/agents/config.ts
index d58ae0867..70905b7d8 100644
--- a/src/shared/agents/config.ts
+++ b/src/shared/agents/config.ts
@@ -293,7 +293,9 @@ export const USAGE_CAPABLE = ['claude', 'codex', 'gemini', 'grok'] as const
// newest CLAUDE transcript for that cwd. A grok node in this list would therefore show a stranger's
// conversation in its find bar and rehydrate its meter from it. That exact bug already happened once
// with codex and gemini; transcriptGates.ts documents it.
-export const CHAT_CAPABLE = ['claude', 'grok'] as const
+// codex joined 2026-09-28 with its own reader (core/codex-chat.ts: the rollout's UI stream for what
+// the user typed, the model stream for answers and tools), local and over SSH.
+export const CHAT_CAPABLE = ['claude', 'grok', 'codex'] as const
// Agents whose transcript CLAUDE's own resolver can locate and parse — the gate for everything that
// goes through `resolveTranscript` (the find bar's index, the meter's mount-time rehydration).
//