omp-multi-harness 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmad Bakhshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# omp-multi-harness
+
+An [OMP](https://github.com/can1357/oh-my-pi) extension that turns OMP into a **supervisor**
+delegating work to two coding agents you already have:
+
+- **Codex CLI** — `codex`
+- **Claude Code CLI** — `claude`
+
+It drives their real binaries through their real non-interactive entry points, using the
+logins you already did. **No API keys. No token extraction. No reimplementation of either
+agent.**
+
+```text
+                  OMP  (supervisor)
+                        │
+        ┌───────────────┼───────────────┐
+        ▼               ▼               ▼
+   ask_codex       ask_claude       /sessions
+        │               │           (watch, switch,
+        ▼               ▼            cancel runs)
+    codex CLI       claude CLI
+        │               │
+  your Codex      your Claude
+    login            login
+```
+
+> **Status — Phases 0–5 of 6 complete, Phase 6 substantially done.** Everything in the
+> tables below is implemented: delegation, routing, parallel runs, `/sessions`, session
+> continuation, and the background (`--bg`) path. Claude delegation is verified end-to-end
+> against the real CLI; **Codex passes its fake-CLI suite but has never been verified live**,
+> because that account is out of credits — treat it as unproven against the real binary.
+> Model-based `auto` routing is likewise unverified live: OMP itself has no authenticated
+> model here, so it silently falls back to the rule table (which is tested).
+> Progress: [`_plan/PROGRESS.md`](_plan/PROGRESS.md).
+
+---
+
+## Setup
+
+### 1. Install the three CLIs
+
+| | install | check |
+|---|---|---|
+| OMP | `bun add -g @oh-my-pi/pi-coding-agent` | `omp --version` |
+| Codex | `brew install --cask codex` · `npm i -g @openai/codex` | `codex --version` |
+| Claude Code | `npm i -g @anthropic-ai/claude-code` | `claude --version` |
+
+OMP loads extensions with [Bun](https://bun.sh), so Bun is required
+(`curl -fsSL https://bun.sh/install | bash`).
+
+### 2. Log in to each — three separate, non-transferable logins
+
+```bash
+omp                  # then /login   — OMP's own model (supervisor turns + auto routing)
+codex login          #               — everything ask_codex does
+claude auth login    #               — everything ask_claude does
+```
+
+This is not redundancy. Claude Code will not accept credentials supplied by another tool,
+so each CLI keeps its own login and this extension never touches any of them — it only
+reads `codex login status` and `claude auth status`, which print no secrets.
+
+If OMP itself is not logged in, delegation still works; only OMP's own turns and
+model-based `auto` routing are affected (routing falls back to rules).
+
+### 3. Install the extension
+
+OMP discovers extensions from its **agent dir** (`<agentDir>/extensions/`) and from a
+project's `.omp/extensions/`, resolving each directory through that directory's
+`package.json` → `omp.extensions`. It does **not** scan `node_modules`. So installing from
+npm is two steps: install the package, then register it. The bundled CLI does step two.
+
+#### From npm — global, for every project (recommended)
+
+```bash
+npm install -g omp-multi-harness
+omp-multi-harness link
+```
+
+`link` symlinks the installed package into `<agentDir>/extensions/multi-harness`. It only
+ever manages its own symlink: it refuses to replace anything that is not a symlink it
+created, and it never edits your OMP config, logs you in, or installs a CLI.
+
+#### From npm — one project only
+
+```bash
+npm install --save-dev omp-multi-harness
+npx omp-multi-harness link --project
+```
+
+That links into `./.omp/extensions/multi-harness`, so the extension loads for this
+repository and nowhere else.
+
+#### Using a profile
+
+```bash
+omp-multi-harness link --profile work      # ~/.omp/profiles/work/agent/extensions/
+```
+
+`PI_CODING_AGENT_DIR` overrides both the default and `--profile`, and is honored by the CLI
+and by the extension at runtime — nothing hard-codes `~/.omp/agent`.
+
+#### Check, and undo
+
+```bash
+omp-multi-harness status     # where it is linked, globally and for this project
+omp-multi-harness unlink     # remove the symlink (add --project for the project one)
+omp-multi-harness doctor     # the full setup check
+```
+
+#### From source
+
+```bash
+git clone https://github.com/abdevts/omp-multi-harness.git
+cd omp-multi-harness
+bun install
+bun scripts/cli.ts link          # same linking, straight from the checkout
+```
+
+Or skip installation entirely and load it per run:
+
+```bash
+omp -e /path/to/omp-multi-harness/src/index.ts
+```
+
+> **No build step.** OMP loads TypeScript directly, so the package ships its sources and
+> `omp.extensions` points at `./src/index.ts`. There is nothing to compile.
+
+### Using it from VS Code
+
+The extension lives inside `omp`, not inside VS Code — so "using it in VS Code" means
+running `omp` in VS Code's integrated terminal with the extension registered. Once
+`omp-multi-harness link` has been run, every terminal session picks it up automatically.
+
+This repository ships `.vscode/` with the loop already wired:
+
+| file | what it gives you |
+|---|---|
+| `tasks.json` | **Terminal → Run Task** for `doctor`, `test`, and `typecheck` |
+| `launch.json` | debug `omp` with the extension loaded via `-e` |
+| `settings.json` | formatting and TypeScript settings matching this codebase |
+| `extensions.json` | the editor extensions this project expects |
+
+For a project that merely *consumes* the package, you do not need any of that — install,
+link, and open a terminal:
+
+```bash
+npm install --save-dev omp-multi-harness
+npx omp-multi-harness link --project
+omp                    # in VS Code's integrated terminal
+```
+
+Then `/agents` inside OMP confirms it loaded. If you keep a workspace-local agent dir, set
+`PI_CODING_AGENT_DIR` in VS Code's terminal environment (`terminal.integrated.env.osx`,
+`.linux`, or `.windows`) and both the CLI and the extension will follow it.
+
+### 4. Verify
+
+```bash
+bun run doctor     # 14 checks: tools, all three logins, router model, install, config
+```
+
+```text
+Codex
+  ✔ Codex CLI                    codex-cli 0.155.0 (/opt/homebrew/bin/codex)
+  ✔ Codex authentication         Logged in using ChatGPT
+```
+
+`bun scripts/setup.ts fix` applies the safe repairs (symlink, config block, dependencies).
+Installs and logins are printed for you to run — never executed automatically.
+
+Inside OMP, `/agents` and `/harness-setup` report the same thing.
+
+### 5. Configure (optional — the defaults are sensible)
+
+Add to `~/.omp/agent/config.yml`, or `<project>/.omp/config.yml` to override per project:
+
+```yaml
+multiHarness:
+  enabled: true
+
+  codex:
+    enabled: true
+    model: null          # null → your ~/.codex/config.toml decides
+    timeoutMs: 1800000
+
+  claude:
+    enabled: true
+    model: null          # null → your Claude Code config decides
+    acceptEdits: false
+
+  routing:
+    mode: model          # model | rules — how `auto` picks an agent
+    model: "@smol"       # router model: role alias, provider/id, or bare id
+    modeMap:
+      plan: claude
+      review: claude
+      implement: codex
+      debug: codex
+
+  concurrency:
+    maxConcurrentRuns: 4
+    allowParallelWrites: false   # two agents never write one tree at once
+
+  debug: false
+```
+
+Every option: [`_spec/09-config.md`](_spec/09-config.md).
+
+---
+
+## Usage
+
+Flags for `/codex` and `/claude`: `--read-only`, `--write`, `--new`, `--bg`,
+`--mode <mode>`, `--model <id>`.
+
+`--bg` returns a run id immediately and keeps working in the background; track it with
+`/sessions`. Many runs can be alive at once — see [Parallel runs](#parallel-runs).
+
+### Commands
+
+| command | status | what it does |
+|---|---|---|
+| `/agents` | ✅ | Availability, version, auth, and readiness for both agents |
+| `/agents auth [codex\|claude]` | ✅ | Auth status plus the exact login command |
+| `/harness-setup` | ✅ | The setup checklist, inside a session |
+| `/codex <task>` | ✅ | Delegate straight to Codex |
+| `/claude <task>` | ✅ | Delegate straight to Claude Code |
+| `/sessions` | ✅ | List, watch, switch focus between, and cancel running delegations |
+
+### Tools the supervisor calls on its own
+
+| tool | status | typical use |
+|---|---|---|
+| `ask_codex` | ✅ | implementation, debugging, refactors, tests |
+| `ask_claude` | ✅ | architecture, planning, design review, second opinions |
+| `delegate` | ✅ | `agent: "auto"` routing |
+| `agent_runs` | ✅ | fan several runs out, then join them |
+
+### Parallel runs
+
+Every delegation — whether from a slash command or a tool — becomes a *run* in a
+session-scoped registry. Runs execute concurrently; `/sessions` is the view over them.
+
+```text
+/claude --bg review the auth architecture
+/codex  --bg --read-only summarize the test suite
+/sessions                      # both listed, elapsed ticking
+/sessions attach r7c1          # stream that run's output into the widget
+/sessions cancel r7c2          # stops just that run
+```
+
+Attaching changes only what you are shown. It never pauses, throttles, or reorders a run —
+unfocused runs keep executing and keep filling their own output buffers.
+
+What may run at once:
+
+| situation | parallel? |
+|---|---|
+| N read-only runs, same repo | yes |
+| read-only + writer, same repo | yes — the reader may observe a moving tree, and the result says so |
+| two writers, same repo | no — serialized by a FIFO workspace write lock |
+| two writers, different repos | yes |
+
+`concurrency.maxConcurrentRuns` (default 4) caps live child processes; the rest wait in
+`queued`. Quitting OMP cancels every live run and waits for it to die — no child or
+grandchild outlives the session.
+
+> `/sessions` covers **delegated runs only**. OMP's own `/resume` already lists and switches
+> OMP sessions, including `/resume @claude` and `/resume @codex` to import a worker session,
+> so this extension does not duplicate it.
+
+### Session continuation
+
+Each `(OMP session, repo)` pair remembers the worker session it was talking to, so a second
+`/codex` continues the first one's thread rather than starting cold. `--new` forces a fresh
+one. If a resume fails, the run retries **once** with a compact handoff summary rather than
+replaying history, and says so in the result. Two parallel runs against the same agent and
+repo cannot share one worker session: the second forks (Claude) or starts fresh (Codex).
+
+The mapping holds ids, paths, and timestamps only — never task text, tokens, or
+environment — in `0600` files under a `0700` directory in the active agent dir (honoring
+`--profile` and `PI_CODING_AGENT_DIR`).
+
+### Model selection
+
+Three independent choices:
+
+- **Worker models** stay yours. Set nothing and no `-m`/`--model` is passed at all — each
+  CLI's own config decides. Override per agent (`codex.model`) or per call (`--model`).
+- **Router model** (`routing.model`, default `@smol`) resolves `agent: "auto"` with one
+  small classification call. Any failure falls back to the rule table, so it can never
+  block a delegation. `routing.mode: rules` turns it off entirely.
+
+---
+
+## Troubleshooting
+
+| symptom | cause and fix |
+|---|---|
+| `/agents` says *not authenticated* for Codex | `codex login`. (Note `codex login status` prints to stderr — tools that read only stdout get this wrong.) |
+| `/agents` says *not authenticated* for Claude | `claude auth login` |
+| `auto` always picks by rules | OMP has no authenticated model — `omp` → `/login`, or set `routing.model` |
+| `unavailable — \`codex\` not found on PATH` | install it, or set `multiHarness.codex.executable` to the full path |
+| `PROVIDER_LIMIT: … out of credits` | the provider account, not the task — top up or switch accounts. Retrying will not help. |
+| doctor shows *repo-local copy shadowing your global omp* | harmless: `bun run` puts `node_modules/.bin` first, and the dev dependency ships an `omp` |
+| Extension not loading | confirm the symlink target, or run `omp -e ./src/index.ts` directly |
+
+---
+
+## Security posture
+
+- Never reads OAuth or token files; auth state comes only from each CLI's own status command.
+- Never prints credentials. `claude auth status --json` returns your email and org — only
+  `loggedIn` and `authMethod` are read.
+- Never forwards one provider's credentials to the other.
+- No `shell: true`, ever. Arguments are arrays; prompts go over **stdin**, so task text
+  never lands in `ps` or shell history.
+- Permission-bypass flags (`--dangerously-bypass-approvals-and-sandbox`,
+  `--dangerously-skip-permissions`) are never passed, and no config option enables them.
+- Working directories are realpath-validated; a run cannot silently target another repo.
+- Two write-capable agents never touch the same working tree at once.
+- `readOnlyEnforced` reports what the adapter's **argv actually enforced**, not what the
+  caller requested. An adapter that cannot prove enforcement reports `false`.
+- Every CLI-derived string embedded in an error is redacted first (API keys, tokens, JWTs,
+  PEM blocks, `KEY=value` assignments), so a credential a worker echoes back cannot reach
+  an error message or a log. Environment views are allowlist-based — a denylist fails open.
+
+Details: [`_spec/10-errors-and-security.md`](_spec/10-errors-and-security.md).
+
+---
+
+## Development
+
+```bash
+bun install
+bun test           # 110 tests, no live provider calls
+MULTI_HARNESS_LIVE_TESTS=1 bun test test/live.test.ts   # opt-in, calls the real CLIs
+bun run typecheck
+bun run dev        # omp --no-extensions -e ./src/index.ts
+bun run doctor
+```
+
+VS Code config ships in `.vscode/` (tasks for doctor/typecheck/test, launch configs, and
+recommended extensions).
+
+- [`_spec/`](_spec/README.md) — the normative specification, 15 documents
+- [`_plan/`](_plan/README.md) — phased plan, decision log, and the task tracker
+
+Built and verified against `omp 18.2.6` · `codex-cli 0.155.0` · `claude 2.1.274` · `bun 1.4.2`
+([`_spec/01-environment-findings.md`](_spec/01-environment-findings.md)).

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "omp-multi-harness",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OMP extension that delegates work to the Codex and Claude Code CLIs \u2014 parallel runs, /sessions, and automatic routing, using each CLI's own login",
+  "license": "MIT",
+  "author": "Ahmad Bakhshi",
+  "homepage": "https://github.com/abdevts/omp-multi-harness#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abdevts/omp-multi-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/abdevts/omp-multi-harness/issues"
+  },
+  "keywords": [
+    "omp",
+    "omp-extension",
+    "pi-coding-agent",
+    "codex",
+    "claude-code",
+    "ai",
+    "agent",
+    "cli",
+    "delegation"
+  ],
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "omp": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "bin": {
+    "omp-multi-harness": "scripts/cli.ts"
+  },
+  "files": [
+    "src",
+    "scripts/cli.ts",
+    "scripts/setup",
+    "scripts/setup.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "scripts": {
+    "setup": "bun scripts/setup.ts",
+    "doctor": "bun scripts/setup.ts check",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "dev": "omp --no-extensions -e ./src/index.ts",
+    "link-extension": "bun scripts/cli.ts link",
+    "prepublishOnly": "bun run typecheck && bun test"
+  },
+  "peerDependencies": {
+    "@oh-my-pi/pi-coding-agent": ">=18.2.6"
+  },
+  "peerDependenciesMeta": {
+    "@oh-my-pi/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@oh-my-pi/pi-coding-agent": "^18.2.6",
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/cli.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env bun
+/**
+ * `omp-multi-harness` CLI — registers this package with OMP.
+ *
+ * Installing from npm puts the package in node_modules, which OMP does **not** scan. OMP
+ * discovers extensions from its agent dir (`<agentDir>/extensions/`) and from a project's
+ * `.omp/extensions/`, resolving each directory through its `package.json` `omp.extensions`
+ * manifest. So the install step is a symlink from one of those directories to this package.
+ *
+ * Symlinks only — this never edits your OMP config, never logs in, and never installs a CLI.
+ */
+import { existsSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LINK_NAME = "multi-harness";
+
+/** This package's root — the directory containing its package.json. */
+function packageRoot(): string {
+	return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+/**
+ * The active OMP agent dir, resolved the same way OMP resolves it: `PI_CODING_AGENT_DIR`
+ * wins, then `--profile <name>`, then the default. Never hard-coded to `~/.omp/agent`.
+ */
+function agentDir(profile?: string): string {
+	const fromEnv = process.env.PI_CODING_AGENT_DIR;
+	if (fromEnv) return resolve(fromEnv);
+	if (profile) return join(homedir(), ".omp", "profiles", profile, "agent");
+	return join(homedir(), ".omp", "agent");
+}
+
+function targetDir(scope: "global" | "project", profile?: string, cwd = process.cwd()): string {
+	return scope === "global" ? join(agentDir(profile), "extensions") : join(resolve(cwd), ".omp", "extensions");
+}
+
+/** Where this package is (or would be) linked from. */
+function linkPath(scope: "global" | "project", profile?: string): string {
+	return join(targetDir(scope, profile), LINK_NAME);
+}
+
+function describeExisting(path: string): { kind: "absent" | "symlink" | "other"; target?: string } {
+	if (!existsSync(path) && !isDanglingSymlink(path)) return { kind: "absent" };
+	try {
+		if (lstatSync(path).isSymbolicLink()) return { kind: "symlink", target: readlinkSync(path) };
+	} catch {
+		// fall through — treat an unreadable entry as "other" so we never clobber it
+	}
+	return { kind: "other" };
+}
+
+/** `existsSync` follows symlinks, so a broken link reads as absent without this. */
+function isDanglingSymlink(path: string): boolean {
+	try {
+		return lstatSync(path).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+
+function link(scope: "global" | "project", profile?: string): number {
+	const root = packageRoot();
+	const dir = targetDir(scope, profile);
+	const dest = linkPath(scope, profile);
+	const existing = describeExisting(dest);
+
+	if (existing.kind === "other") {
+		console.error(`Refusing to replace ${dest} — it exists and is not a symlink.`);
+		console.error("Move it aside yourself, then re-run. This tool only ever manages its own symlink.");
+		return 1;
+	}
+	if (existing.kind === "symlink" && resolve(dirname(dest), existing.target ?? "") === root) {
+		console.log(`Already linked: ${dest} -> ${root}`);
+		return 0;
+	}
+
+	mkdirSync(dir, { recursive: true });
+	if (existing.kind === "symlink") rmSync(dest);
+	symlinkSync(root, dest, "dir");
+
+	console.log(`Linked: ${dest} -> ${root}`);
+	console.log("Start `omp` and run /agents to confirm it loaded.");
+	return 0;
+}
+
+function unlink(scope: "global" | "project", profile?: string): number {
+	const dest = linkPath(scope, profile);
+	const existing = describeExisting(dest);
+
+	if (existing.kind === "absent") {
+		console.log(`Nothing to remove at ${dest}.`);
+		return 0;
+	}
+	if (existing.kind === "other") {
+		console.error(`Refusing to remove ${dest} — it is not a symlink.`);
+		return 1;
+	}
+	rmSync(dest);
+	console.log(`Unlinked: ${dest}`);
+	return 0;
+}
+
+function status(profile?: string): number {
+	for (const scope of ["global", "project"] as const) {
+		const dest = linkPath(scope, profile);
+		const existing = describeExisting(dest);
+		const state =
+			existing.kind === "absent"
+				? "not linked"
+				: existing.kind === "other"
+					? "occupied by a non-symlink"
+					: `-> ${existing.target}`;
+		console.log(`${scope.padEnd(8)} ${dest}\n         ${state}`);
+	}
+	return 0;
+}
+
+const USAGE = `omp-multi-harness — register this OMP extension
+
+Usage:
+  omp-multi-harness link     [--project] [--profile <name>]   symlink into OMP's extensions dir
+  omp-multi-harness unlink   [--project] [--profile <name>]   remove that symlink
+  omp-multi-harness status   [--profile <name>]               show where it is linked
+  omp-multi-harness doctor                                    run the full setup check
+
+--project links into ./.omp/extensions (this repo only) instead of the agent dir.
+--profile <name> targets ~/.omp/profiles/<name>/agent. PI_CODING_AGENT_DIR overrides both.`;
+
+const args = process.argv.slice(2);
+const command = args[0] ?? "help";
+const scope: "global" | "project" = args.includes("--project") ? "project" : "global";
+const profileIndex = args.indexOf("--profile");
+const profile = profileIndex >= 0 ? args[profileIndex + 1] : undefined;
+
+if (profileIndex >= 0 && !profile) {
+	console.error("--profile needs a name");
+	process.exit(1);
+}
+
+switch (command) {
+	case "link":
+		process.exit(link(scope, profile));
+		break;
+	case "unlink":
+		process.exit(unlink(scope, profile));
+		break;
+	case "status":
+		process.exit(status(profile));
+		break;
+	case "doctor": {
+		// setup.ts runs its checks on import via its own entrypoint, and does not export a
+		// callable main — so spawn it rather than pretending it has an API it does not.
+		const proc = Bun.spawn(["bun", join(packageRoot(), "scripts", "setup.ts"), "check"], {
+			stdio: ["inherit", "inherit", "inherit"],
+		});
+		process.exit(await proc.exited);
+		break;
+	}
+	default:
+		console.log(USAGE);
+		process.exit(command === "help" || command === "--help" || command === "-h" ? 0 : 1);
+}

package/scripts/setup/claude.ts

@@ -0,0 +1,41 @@
+/** Claude Code CLI setup: presence + authentication. Mirrors src/agents/claude.ts. */
+import { type SetupGroup, executableStep, sh, which } from "./types.ts";
+
+export const claudeSetup: SetupGroup = {
+	id: "claude",
+	title: "Claude Code",
+	steps: [
+		executableStep({
+			id: "claude-cli",
+			title: "Claude Code CLI",
+			bin: "claude",
+			install: {
+				description: "Install Claude Code",
+				command: "npm install -g @anthropic-ai/claude-code",
+			},
+		}),
+		{
+			id: "claude-auth",
+			title: "Claude Code authentication",
+			run() {
+				if (!which("claude")) return { status: "skip", detail: "claude not installed" };
+				const r = sh("claude", ["auth", "status", "--json"], 20_000);
+				if (r.ok) {
+					try {
+						// The payload also carries email, org id and org name — deliberately
+						// read only these two fields, and never persist or print the rest.
+						const j = JSON.parse(r.out) as { loggedIn?: boolean; authMethod?: string };
+						if (j.loggedIn) return { status: "ok", detail: `logged in via ${j.authMethod ?? "unknown method"}` };
+					} catch {
+						return { status: "warn", detail: "unexpected `claude auth status` output" };
+					}
+				}
+				return {
+					status: "fail",
+					detail: "not authenticated",
+					fix: { description: "Complete Claude Code's own login flow", command: "claude auth login" },
+				};
+			},
+		},
+	],
+};

package/scripts/setup/codex.ts

@@ -0,0 +1,35 @@
+/** Codex CLI setup: presence + authentication. Mirrors src/agents/codex.ts. */
+import { IS_MAC, type SetupGroup, executableStep, sh, which } from "./types.ts";
+
+export const codexSetup: SetupGroup = {
+	id: "codex",
+	title: "Codex",
+	steps: [
+		executableStep({
+			id: "codex-cli",
+			title: "Codex CLI",
+			bin: "codex",
+			install: {
+				description: "Install the Codex CLI",
+				command: IS_MAC ? "brew install --cask codex" : "npm install -g @openai/codex",
+			},
+		}),
+		{
+			id: "codex-auth",
+			title: "Codex authentication",
+			run() {
+				if (!which("codex")) return { status: "skip", detail: "codex not installed" };
+				const r = sh("codex", ["login", "status"], 20_000);
+				// `codex login status` prints to STDERR, not stdout — read both (_spec/14).
+				// Only the CLI's own status line is read; no credential file is ever touched.
+				const line = [r.out, r.err].join("\n").split("\n").find((l) => /logged in/i.test(l));
+				if (r.ok && line) return { status: "ok", detail: line.trim() };
+				return {
+					status: "fail",
+					detail: "not authenticated",
+					fix: { description: "Complete Codex's own login flow", command: "codex login" },
+				};
+			},
+		},
+	],
+};