@@ -0,0 +1,15 @@
+---
+'@objectstack/scenarios': patch
+---
+
+feat(scenarios): the scenario runner drives the Codex CLI (`--driver codex`) and any command that speaks a stdin/stdout driver contract (`--driver external:COMMAND`), and each gallery app page names the driver that ran it
+
+Clause-②: yes
+Metadata-protocol: none
+
+The same scenario card can now measure another agent tool. Additive: nothing is removed or renamed.
+
+- **`--driver codex`** (`CodexDriver`): `codex exec --json` on your own ChatGPT plan login. It refuses to start while `OPENAI_API_KEY` or `CODEX_API_KEY` is set or `codex login status` reports anything but a ChatGPT login, and passes `-c forced_login_method="chatgpt"` on every turn. The persona's API key reaches the CLI only in a 0600 profile file under `$CODEX_HOME`, deleted when the turn returns. `--model`, `--author-model`, `--ask-model` and `--author-timeout` apply; `codex exec` has no turn cap, so `--author-max-turns` and `--ask-max-turns` are refused with it.
+- **`--driver external:COMMAND`** (`ExternalDriver`, contract `objectstack-scenario-driver/1`): one process per call, the call as JSON on stdin (`info`, `author`, `ask`), the turn as JSON on stdout. A non-zero exit or an answer of another shape is a failed turn with a named reason (`no-result(exit N)`, `invalid-output(…)`). The persona's key is only in a 0600 file whose path the `ask` call names, never on argv, in the environment or on stdin. The package README states the contract.
+- **The driver on record**: `DriverInfo` gains `replayOf`, so a replay (`--driver recorded:F`) names the driver and version of the recording it replays. Each exported gallery app page carries a `- Driver:` line with the driver's name and version (`driverText`).
+- `ApiBillingRefusedError` takes an optional second argument naming the agent tool and its login command; its default message is unchanged.
@@ -138,6 +138,8 @@ pnpm --filter @objectstack/scenarios run-scenarios                       # every
 pnpm --filter @objectstack/scenarios run-scenarios --only service_desk --modes scratch
 pnpm --filter @objectstack/scenarios run-scenarios --record /tmp/rec.json  # also save every turn
 pnpm --filter @objectstack/scenarios run-scenarios --driver recorded:/tmp/rec.json  # replay, no model
+pnpm --filter @objectstack/scenarios run-scenarios --driver codex           # the Codex CLI on your ChatGPT plan
+pnpm --filter @objectstack/scenarios run-scenarios --driver external:./my-agent.mjs  # any command on the driver contract
 pnpm --filter @objectstack/scenarios run-scenarios --author-timeout 90       # minutes per authoring turn (default 60)
 pnpm --filter @objectstack/scenarios run-scenarios --author-max-turns 400    # turns per authoring turn, every card (default by tier)
 pnpm --filter @objectstack/scenarios run-scenarios --ask-max-turns 20        # turns per question or operation turn (default 12)
@@ -196,7 +198,9 @@ npx @objectstack/scenarios help                                      # the comma
   is logged in with an API key (the cost ruling on cloud#3600), and the record states the driver, the login, the
   authoring timeout and the turn caps. Every turn records its process: elapsed time, the turn cap it ran under
   (`--max-turns`), and for a turn that did not finish its exit code or signal, whether the runner's timeout killed it,
-  and the end of its stderr. `RecordedDriver` replays a recording, and refuses the live-driver limits and models below.
+  and the end of its stderr. `RecordedDriver` replays a recording, and refuses the live-driver limits and models below;
+  its record keeps the driver of the recording (`replayOf`). For Codex and any other agent tool, see
+  [Other agent tools](#other-agent-tools--codex-and-the-external-driver-contract).
 - **Model** (`driver.ts`): `--model M` passes `claude --model M` on every turn, an alias (`sonnet`) or a name
   (`claude-sonnet-4-5`); `--author-model` sets the authoring turns (build and iterate) and `--ask-model` the question
   and operation turns apart, each in place of `--model`. With none, a turn takes the login's default model. Every turn
@@ -255,3 +259,69 @@ npx @objectstack/scenarios help                                      # the comma
   states its change's rows the same way: the new objects (with the card's field minimum), lookups, option fields,
   dashboards and nav targets. `test/runner/prompt-trace.test.ts` reads the checks off the scorer itself and holds every
   card to it.
+
+## Other agent tools — Codex and the external driver contract
+
+The same card can measure another agent tool. Every record (`env.driver`) and every gallery app page (`- Driver:`)
+names the driver and its version; a replay (`--driver recorded:F`) names the driver of the recording it replays
+(`replayOf`), never the recording's path.
+
+### `--driver codex`
+
+`drivers/codex.ts` runs the OpenAI Codex CLI in non-interactive mode, on your own ChatGPT plan. What it reads of the
+CLI was measured on `codex-cli 0.167.0`:
+
+- **Login**: the ChatGPT plan only. It refuses to start while `OPENAI_API_KEY` or `CODEX_API_KEY` is set, or when
+  `codex login status` reports anything but `Logged in using ChatGPT` (an API key, no login, an access token); every
+  turn passes `-c forced_login_method="chatgpt"`, and both variables are removed from its environment.
+- **A turn**: `codex exec --json --ephemeral --skip-git-repo-check -c approval_policy="never" -p PROFILE … -`, the
+  prompt on stdin. An authoring turn runs `-s workspace-write -c sandbox_workspace_write.network_access=true -C
+  <project>`; a question or operation runs `-s read-only` in an empty temp directory.
+- **MCP**: the app is served under the name `app` from a profile layer, `$CODEX_HOME/scenario-runner-<random>.config.toml`
+  (0600, deleted when the turn returns), that holds the persona's key as an `http_headers` `Authorization` header and
+  turns off every MCP server of your own config (`enabled = false`). A server of your own named `app` is refused.
+- **Flags**: `--model`, `--author-model` and `--ask-model` pass `-m`; `--author-timeout` is the runner's own clock.
+  `codex exec` has no cap on its agentic turns, so `--author-max-turns` and `--ask-max-turns` are refused. Its JSONL
+  names no model, so the scorecard shows `model not reported (asked for …)`.
+
+### `--driver external:COMMAND` — the contract
+
+`drivers/external.ts` runs any command that speaks the driver seam as a process contract. `COMMAND` is split on
+whitespace (no shell, no quoting); a word that starts `./` or `../`, and a first word holding a `/`, is resolved against
+the directory you run from. For anything more, write a wrapper script.
+
+- **One process per call.** The call is one JSON object on stdin; the answer is one JSON object on stdout; logs go to
+  stderr (the record keeps its last 2,000 characters). Every input starts with `"contract":
+  "objectstack-scenario-driver/1"`; a command should refuse a contract it does not know.
+- **`info`**, once, before any card runs: `{"contract":…,"kind":"info"}` → `{"name":"my-agent","version":"1.4.2"}`.
+  The record's driver is `external:my-agent`, its version `1.4.2`. A command that cannot answer it is refused.
+- **`author`**: build or iterate the app in `cwd` with shell and file tools; the call runs in `cwd`.
+  `{"contract":…,"kind":"author","step":{"card","mode","phase","step"},"prompt":"…","cwd":"/abs/project","tier":"starter","limits":{…}}`
+- **`ask`**: answer one data question or write operation as a persona, over the app's MCP endpoint; the call runs in
+  the directory of `mcp.configFile`.
+  `{"contract":…,"kind":"ask","step":{"card","mode","phase","step","persona"},"prompt":"…","mcp":{"url":"…","configFile":"/tmp/…/mcp.json"},"limits":{…}}`
+- **The answer** to `author` and `ask`, strict (an unknown key is refused):
+  `{"replyText":"every text the agent said, joined","toolCalls":[{"name":"query_records","input":{…},"output":"…","isError":false}],"model":"…","numTurns":3}`.
+  `model` and `numTurns` are optional; an MCP tool may be named bare or `mcp__<server>__<tool>`; a call that never
+  answered leaves `output` out.
+- **Exit codes**: 0 with an answer of that shape is the turn. Any other end is a failed turn with a named reason,
+  never an empty pass: a non-zero exit or a signal is `no-result(exit N)`, stdout that is not one JSON object of that
+  shape is `invalid-output(…)`. A failed authoring turn leaves its Build half not measured; a failed persona turn is
+  graded as the empty answer it is.
+- **Timeout**: `limits.timeoutMs` — `--author-timeout` for `author` (default 60 min), 5 min for `ask`. The runner kills
+  a call still running then (SIGTERM).
+- **Limits**: `limits` carries `timeoutMs`, and `maxTurns` (`--author-max-turns` / `--ask-max-turns`) and `model`
+  (`--model`, `--author-model`, `--ask-model`) when given. The command may ignore them; the record states them.
+- ⛔ **The key**: the persona's API key is only in `mcp.configFile`, a 0600 file in the shape of Claude Code's
+  `--mcp-config` (`{"mcpServers":{"app":{"type":"http","url":…,"headers":{"Authorization":"Bearer …"}}}}`), deleted
+  when the call returns. It is never on argv, in the environment or on stdin, and so never in a run record, a
+  scorecard or a gallery export. A command must not print it.
+- **Cost**: the runner cannot see an external command's login, so the record's login reads `not verified`; the cost
+  ruling still applies, and the runner removes `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `OPENAI_API_KEY` and
+  `CODEX_API_KEY` from the command's environment.
+
+`test/runner/fixtures/fake-external-driver.mjs` is a complete command in about a hundred lines.
+
+**WorkBuddy** (checked 2026-11-07): Tencent's WorkBuddy is a desktop app; no headless mode with structured output
+and an MCP client was found for it, so it is not wired here. A tool that has both rides `--driver external:` with a
+wrapper, with no change to the runner.
@@ -20,7 +20,7 @@
  * and then swapped in, so a re-export first deletes the old directory and
  * nothing stale survives (see {@link APP_LAYOUT}):
  *
- *   apps/<id>/README.md               what the app is, its scorecard, the files
+ *   apps/<id>/README.md               what the app is, the driver that ran it ({@link driverText}), its scorecard, the files
  *   apps/<id>/source/…                the authored metadata source (`source.ts`)
  *   apps/<id>/run-record.json         the run record, the work directories redacted (`workDirsOf`)
  *   apps/<id>/scorecard.json|.md      the per-half scorecard
@@ -54,7 +54,7 @@ import { renderScorecard, type CardScorecard } from '../runner/scorecard.js';
 import { GALLERY_GUARD, type GalleryGuard } from './generic.js';
 import { parseIndex, serializeIndex, type GalleryApp, type GalleryIndex } from './manifest.js';
 import { judgeRecord, type PassJudgement } from './pass.js';
-import { readRunRecords, redactWorkDir, unpublishedRunRefusal, type RecordFile } from './record.js';
+import { readRunRecords, redactWorkDir, unpublishedRunRefusal, type RecordFile, type ScenarioRunRecord } from './record.js';
 import type { CaptureScreenshots, PlannedShot, SkippedShot } from './screenshots.js';
 import { projectFrameworkVersion, readAuthoredSource } from './source.js';
 import { buildTranscript, mergeRecordings, renderTranscript } from './transcript.js';
@@ -124,7 +124,20 @@ class Refused extends Error {
 
 const json = (v: unknown) => `${JSON.stringify(v, null, 2)}\n`;
 
-function appReadme(scenario: LoadedScenario, entry: GalleryApp, judgement: PassJudgement, scorecard: CardScorecard, shots: PlannedShot[], skipped: SkippedShot[]): string {
+/**
+ * The page's driver line: the agent tool whose turns the app was built and
+ * graded on, with its version. A replay names the driver of the recording it
+ * replayed, never the recording's path; a replay whose record does not name
+ * that driver says so.
+ */
+export function driverText(driver: ScenarioRunRecord['env']['driver']): string {
+  const named = (d: { driver: string; version?: string | undefined }) => `${d.driver}${d.version ? ` ${d.version}` : ''}`;
+  if (driver.replayOf) return `${named(driver.replayOf)} (re-graded from a recording of that run)`;
+  if (driver.driver === 'recorded') return 'a recording (the record does not name the driver that made it)';
+  return named(driver);
+}
+
+function appReadme(scenario: LoadedScenario, record: ScenarioRunRecord, entry: GalleryApp, judgement: PassJudgement, scorecard: CardScorecard, shots: PlannedShot[], skipped: SkippedShot[]): string {
   const c = scenario.card;
   const lines = [
     `# ${c.title.en}`,
@@ -135,6 +148,7 @@ function appReadme(scenario: LoadedScenario, entry: GalleryApp, judgement: PassJ
     '',
     `- Scenario: \`${c.id}\` · business functions ${c.businessFunctions.map((f) => `\`${f}\``).join(', ')} · namespace \`${entry.namespace}\``,
     `- Framework: @objectstack/spec ${entry.framework.version} (runner checkout ${entry.framework.runner}) · run ${entry.run} on ${entry.runDate}`,
+    `- Driver: ${driverText(record.env.driver)}`,
     `- 问数: ${entry.qa.questions} questions, ${entry.qa.turns} persona turns · ${entry.operations} write operations`,
     '',
     '## The requirement',
@@ -324,7 +338,7 @@ async function exportOne(
     [APP_LAYOUT.scorecardMd, `${renderScorecard(scorecard)}\n`],
     [APP_LAYOUT.transcriptJson, json(transcript)],
     [APP_LAYOUT.transcriptMd, renderTranscript(transcript, card.title.en)],
-    [APP_LAYOUT.readme, redact(appReadme(scenario, entry, judgement, scorecard, shots, skipped))],
+    [APP_LAYOUT.readme, redact(appReadme(scenario, record, entry, judgement, scorecard, shots, skipped))],
   ]);
   return { entry, shots, skipped };
 }
@@ -56,7 +56,12 @@ export const ScenarioRunRecordSchema = z.looseObject({
     framework: z.string().min(1),
     /** `runner/packages.ts` `PackageSource`; judged by {@link unpublishedRunRefusal}, so a record without it still reads. */
     packages: z.unknown().optional(),
-    driver: z.looseObject({ driver: z.string().min(1) }),
+    /** `runner/driver.ts` `DriverInfo`: what ran the turns; a replay names the driver of its recording (`replayOf`). */
+    driver: z.looseObject({
+      driver: z.string().min(1),
+      version: z.string().optional(),
+      replayOf: z.looseObject({ driver: z.string().min(1), version: z.string().optional() }).optional(),
+    }),
   }),
   evidenceDir: z.string().min(1),
   results: z.array(z.looseObject({ id: z.string().min(1), verdict: VerdictSchema })),
 
@@ -11,6 +11,13 @@
  *   --only ID[,ID]       run only these cards
  *   --modes M[,M]        scratch, template (default: both)
  *   --driver claude      the local Claude Code CLI on your own login (default)
+ *   --driver codex       the local OpenAI Codex CLI on your own ChatGPT plan
+ *                        login (`drivers/codex.ts`); it has no turn cap, so the
+ *                        two --*-max-turns flags are refused with it
+ *   --driver external:C  any command C that speaks the driver contract (one
+ *                        process per call, JSON in on stdin, JSON out on stdout;
+ *                        `drivers/external.ts` and the package README); every
+ *                        flag below reaches it in the call's `limits`
  *   --driver recorded:F  replay the recording F (no model, no network to a model)
  *   --record F           also save every live turn to F, for later replay
  *   --author-timeout MIN the live driver's budget per authoring turn, build and
@@ -56,6 +63,8 @@ import { fileURLToPath } from 'node:url';
 import { formatRefusal, libraryOf, loadScenarios, readCapabilityAreas } from '../loader.js';
 import { HttpApp } from './app.js';
 import { ClaudeCodeDriver, RecordedDriver, RecordingDriver, type AgentDriver } from './driver.js';
+import { CodexDriver } from './drivers/codex.js';
+import { ExternalDriver } from './drivers/external.js';
 import { CAPABILITY_AREAS_DIR, locateLibraryRoot } from './library.js';
 import { minutesText, runCard, type ProjectOps } from './orchestrate.js';
 import { installedSpecVersion, PACKAGES_MODES, prepareWorkspacePackages, settleWorkspaceProject, workspaceScaffolder, type PackageSource, type PackagesMode } from './packages.js';
@@ -189,7 +198,29 @@ export function makeDriver(spec: string, opts: DriverLimits & DriverModels = {})
     if (given.length) throw new Error(`${given.join(', ')} ${given.length === 1 ? 'applies' : 'apply'} to the live driver only: a replay re-reads each turn as it was recorded`);
     return RecordedDriver.fromFile(spec.slice('recorded:'.length));
   }
-  throw new Error(`unknown driver \`${spec}\` (claude, recorded:FILE)`);
+  if (spec === 'codex') {
+    // Measured on codex-cli 0.167.0: `codex exec` takes no cap on its agentic turns (`drivers/codex.ts`).
+    const capped = (['authorMaxTurns', 'askMaxTurns'] as const).filter((k) => opts[k] !== undefined).map((k) => LIVE_FLAGS.find(([key]) => key === k)![1]);
+    if (capped.length) throw new Error(`${capped.join(', ')} ${capped.length === 1 ? 'has' : 'have'} no equivalent in the Codex CLI: \`codex exec\` takes no turn cap`);
+    return new CodexDriver({
+      ...(opts.authorTimeoutMin !== undefined ? { authorTimeoutMs: opts.authorTimeoutMin * 60_000 } : {}),
+      ...(opts.model !== undefined ? { model: opts.model } : {}),
+      ...(opts.authorModel !== undefined ? { authorModel: opts.authorModel } : {}),
+      ...(opts.askModel !== undefined ? { askModel: opts.askModel } : {}),
+    });
+  }
+  if (spec.startsWith('external:')) {
+    return new ExternalDriver({
+      command: spec.slice('external:'.length),
+      ...(opts.authorTimeoutMin !== undefined ? { authorTimeoutMs: opts.authorTimeoutMin * 60_000 } : {}),
+      ...(opts.authorMaxTurns !== undefined ? { authorMaxTurns: opts.authorMaxTurns } : {}),
+      ...(opts.askMaxTurns !== undefined ? { askMaxTurns: opts.askMaxTurns } : {}),
+      ...(opts.model !== undefined ? { model: opts.model } : {}),
+      ...(opts.authorModel !== undefined ? { authorModel: opts.authorModel } : {}),
+      ...(opts.askModel !== undefined ? { askModel: opts.askModel } : {}),
+    });
+  }
+  throw new Error(`unknown driver \`${spec}\` (claude, codex, external:COMMAND, recorded:FILE)`);
 }
 
 export async function main(argv: readonly string[]): Promise<number> {