Support `codex` as an architect

[mohidmakhdoomi]

⚠️ Rescoped 2026-06-16 — codex-only architect support (gemini retiring, see #778)

Final scope: bring codex to parity with claude as a Codev architect, and remove gemini from architect support (the Gemini CLI is retired 2026-06-18, #778 — GEMINI_HARNESS stays for builders only). Conversation resume remains Claude-main-only.

Why not agy here: the Antigravity CLI (agy) was evaluated as the gemini successor for the architect role, but it has no system-prompt / model-instructions channel — the architect role can only ride in agy's first user turn (--prompt-interactive), a weaker, visible, less-durable injection than claude/codex/gemini's out-of-band mechanisms. Rather than ship a degraded architect, agy-as-architect is split into a follow-up: #1063. (agy users still get project context for free — agy reads AGENTS.md natively.)

Delivered on builder/pir-929 (PR #1059)

• Harness-agnostic resume crash-loop fix (HarnessProvider.buildResume seam) — engine-neutral.
• codex architect parity (role via -c model_instructions_file=; fresh-launch + reconnect paths).

Remaining delta (codex-only revision)

• Remove gemini from architect support: doctor no longer affirms gemini as an architect (builder-only); remove the now-dead gemini getArchitectFiles + .gemini/settings.json gitignore entry, and any architect context-file seam left with no remaining consumer.
• Tests + docs reflect claude + codex architects (drop gemini-architect cases; keep gemini builder tests).
• Push to the same branch (PR Support codex and gemini CLIs as architects (PIR #929) #1059 auto-updates); re-CMAP at the PR; do not self-merge.

The original request below is retained for history; its gemini-architect (and any agy) specifics are superseded by the codex-only scope above.

---

Feature Request

Allow the OpenAI codex CLI and Google gemini CLI to run as Codev architects (the primary interactive agent that spawns and reviews builders), at parity with the default claude architect. Selectable via shell.architect / shell.architectHarness in .codev/config.json — exactly the config-driven mechanism builders already use to pick their CLI.

Why / Current State

The harness abstraction (#591) already encapsulates per-CLI system-prompt injection, and builders already run codex/gemini through the same harness + PTY + afx send + shellper-restart machinery (config-driven; bench.ts benchmarks all three engines). Every architect launch path already routes role injection through the harness except one — so codex/gemini architects are close, but not yet correct or proven:

• ✅ Role injection: claude --append-system-prompt, codex -c model_instructions_file=, gemini GEMINI_SYSTEM_MD (agent-farm/utils/harness.ts).
• ✅ No-Tower afx architect, sibling add-architect, and reconnect/auto-restart all rebuild harness-correctly via buildArchitectArgs.
• ❌ A latent resume crash-loop for non-Claude harnesses — the one broken main-architect launch path (below), plus the same root-cause bug in the builder --resume path.
• ⚠️ Message-submit timing is tuned to Claude's TUI; needs validation on codex/gemini TUIs.
• doctor already bars only OpenCode as architect — implying codex/gemini are intended to be supported.

🐞 Critical bug to fix (must-have) — two sites, one root cause

Architect path: agent-farm/servers/tower-instances.ts:500-509 (main architect, first workspace start) calls findLatestSessionId() — which reads only ~/.claude/projects/<encoded-cwd>/*.jsonl — without gating on the configured harness, then builds <cmd> --resume <uuid>.

If shell.architect is codex/gemini and any prior Claude session exists for that workspace dir (true for anyone who has used Claude Code there, including this repo), afx workspace start launches e.g. codex --resume <claude-uuid> → invalid invocation → shellper restart-loops (maxRestarts: 50) to death. The code comment even reads "if a prior Claude session exists."

Builder path (same root cause): afx spawn <id> --resume carries the identical Claude-only assumption — agent-farm/commands/spawn.ts:77-90 (discoverResumeSession()) and agent-farm/commands/spawn-worktree.ts:699-711 (the restart loop's ${baseCmd} --resume "${id}"), with workspace-recover.ts inheriting it. A resumed codex/gemini builder crash-loops the same way. Fresh builders never hit this branch — so "builders already prove the path" doesn't cover it — and architects routinely revive builders, so it's MVP scope.

Fix direction: move session-discovery + resume-arg construction behind the HarnessProvider interface (claude returns the resume invocation; codex/gemini return null → fresh launch via buildArchitectArgs). Apply the one resume seam to both sites (keeping the existing buildResumeNotice prompt for fresh-launched builders). Siblings + reconnect already use buildArchitectArgs.

Scope

Must-have (MVP "supported"):

1. Fix the resume mis-fire at both sites — architect launch and builder --resume (above).
2. Empirically validate codex & gemini across the architect lifecycle (see Acceptance Criteria).
3. If validation shows flaky multi-line/interrupt delivery, add a per-harness submit strategy (custom pacing or bracketed-paste) to HarnessProvider (agent-farm/servers/message-write.ts).
4. Architect-path tests for codex/gemini (arg construction, resume-skip, reconnect) — current af-architect.test.ts is Claude-only.
5. doctor/docs: affirm codex/gemini architect support; document "conversation resume is Claude-main-only" and that .codev/config.json (not TOWER_ARCHITECT_CMD/--architect-cmd) is the supported way to select the architect harness.

Nice-to-have:

• Generalize the hardcoded CLAUDECODE env-strip (6 sites) behind a provider env-cleanup hook; add codex/gemini equivalents if they expose nesting-detection env.
• Make the dashboard ESC[3J scrollback-block claude-conditional (packages/dashboard/src/components/Terminal.tsx:342).
• Main-architect conversation resume for codex/gemini — provider-specific session discovery (codex ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl; gemini ~/.gemini/tmp/<project>/chats/session-*.jsonl via --list-sessions/--resume).
• True per-architect resume parity (main + siblings + identity) — blocked on Multi-architect conversation resume: disambiguate via per-architect session UUID #832.
• Command-aware harness resolution: make buildArchitectArgs honor TOWER_ARCHITECT_CMD/--architect-cmd when resolving the harness (today it reads only .codev/config.json, so an env/CLI override with no matching config injects Claude's flags into codex/gemini) — tower-instances.ts:440,921, tower-utils.ts:176, cli.ts:60-71.
• Guidance parity: the injected architect role reaches all three harnesses, but codex/gemini also support their own skill mechanisms (codex ~/.codex/skills, gemini skills) that Codev doesn't package — scaffold.ts copies only .claude/skills. Generalize skill copying to be provider-aware, and give gemini project context via .gemini/settings.json context.fileName → AGENTS.md (it ships no GEMINI.md). Parity/effectiveness, not a launch blocker.

Acceptance Criteria

For both codex and gemini:

• afx architect (no-Tower) launches with role injected.
• afx workspace start main architect launches on a clean cwd.
• afx workspace start main architect launches when a stale Claude .jsonl is present (regression target for the bug above).
• afx workspace add-architect sibling launches.
• afx send delivers + submits single-line, multi-line (>3 lines, no swallowed Enter), --interrupt, and while the TUI is streaming output.
• Tower stop→start reconnect and shellper auto-restart both relaunch the architect.
• A builder spawned by a codex/gemini architect preserves CODEV_ARCHITECT_NAME affinity.
• afx spawn <id> --resume on a non-Claude builder → fresh launch + resume notice (not --resume <claude-id>).
• Dashboard web-terminal scrollback survives heavy TUI redraw.

Key files

• agent-farm/utils/harness.ts — provider definitions / resume seam
• agent-farm/servers/tower-instances.ts:500-509 — architect resume bug
• agent-farm/commands/spawn.ts:77-90, spawn-worktree.ts:699-711 — builder resume bug (same root cause); workspace-recover.ts inherits it
• agent-farm/servers/message-write.ts — submit pacing
• agent-farm/servers/tower-terminals.ts, tower-routes.ts — CLAUDECODE strip sites
• packages/dashboard/src/components/Terminal.tsx:342 — ESC[3J block
• commands/doctor.ts — support affirmation

Effort

~4–6 engineer days for MVP (validation + the two-site resume fix + tests); +2–4 days for codex/gemini main-architect conversation resume; +1–2 weeks for full resume parity (#832).

References

• af workspace failure with codex #591 — agent harness abstraction (origin of codex/gemini support)
• Multi-architect conversation resume: disambiguate via per-architect session UUID #832 — multi-architect resume via per-architect session UUID (blocker for full parity)
• Full deep-dive analysis available locally at architect-analysis.md (repo root)

[mohidmakhdoomi]

📎 Full deep-dive analysis attached as architect-analysis.md below.

TL;DR: codex/gemini already launch as architects via the existing harness (#591); MVP support is ~4–6 engineer days, dominated by empirical validation plus a small but two-site fix to a latent resume crash-loop. The resume path isn't gated on the harness, so a non-Claude architect — or a resumed non-Claude builder — builds <cmd> --resume <claude-uuid> and restart-loops. It hits both architect launch (agent-farm/servers/tower-instances.ts:500-509) and builder launch (spawn.ts / spawn-worktree.ts, reached via afx spawn --resume); the fix is to route both through one HarnessProvider resume capability (Claude resumes; codex/gemini fall back to fresh launch). See the attached file for the full gap table, risk register, and acceptance-test matrix.

architect-analysis.md

[mohidmakhdoomi]

On it! Working on this with the PIR protocol (plan + dev-approval gates before PR).