feat(run): basou run codex launcher with pre-spawn orientation channel

Wrap the Codex CLI as a Basou-tracked session, the twin of `basou run
claude-code`. Two grips beyond plain tracking: inject `-c
shell_environment_policy.inherit=all` so Codex tool calls can reach `basou` on
PATH, and re-render THIS workspace's orientation into ~/.codex/AGENTS.md just
before spawn so the interactive Codex auto-loads the current position (correcting
the global channel's last-refreshed-workspace semantics). The pre-spawn render is
best-effort and surfaces the last-refreshed orientation without re-importing.

Generalizes runClaudeCode's lifecycle into a shared runTrackedTool(args, options,
ctx, adapter) parametrized by per-tool seams (command resolver, source metadata,
arg transform, pre-spawn hook); runClaudeCode / runCodex are thin wrappers, and
the run-group subcommand dispatch is shared. Adds the codex-adapter session-source
kind (regenerated published JSON Schema) plus codexAdapterMetadata /
resolveCodexCommand in core. Claude-code run tests are unchanged and pass; a
RunContext.codexChannelPath seam keeps the suite off the real home-global file.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: takashi-matsuyama

CHANGELOG.md

@@ -7,6 +7,17 @@ All notable changes to **basou** are recorded here. The project follows
 
 ### Added
 
+- `basou run codex` — wrap the Codex CLI as a Basou-tracked session, the twin of
+  `basou run claude-code`. Two grips beyond plain tracking: it injects
+  `-c shell_environment_policy.inherit=all` so Codex's own tool calls can reach
+  `basou` on PATH, and just before spawn it re-renders THIS workspace's
+  orientation into the Codex context face (`~/.codex/AGENTS.md`) so the
+  about-to-start interactive Codex auto-loads the current position even when the
+  global channel last reflected a different workspace. The pre-spawn render is
+  best-effort (a failure never blocks the launch) and surfaces the
+  last-refreshed orientation without re-importing. The session is attributed to
+  the new `codex-adapter` source kind.
+
 - Codex context channel — `basou refresh` now renders the regenerated
   orientation into `~/.codex/AGENTS.md` (a marker-delimited `BASOU:ORIENTATION`
   block), the file Codex auto-loads at startup. Codex exposes no SessionStart
@@ -42,6 +53,15 @@ All notable changes to **basou** are recorded here. The project follows
 
 ### Internal
 
+- Added the `codex-adapter` session-source kind to `SessionSourceKindSchema`
+  (and the regenerated published JSON Schema) for live `basou run codex`
+  sessions — distinct from the after-the-fact `codex-import`. Added
+  `codexAdapterMetadata` / `resolveCodexCommand` to the core codex adapter, and
+  generalized `runClaudeCode`'s lifecycle into a shared `runTrackedTool(args,
+  options, ctx, adapter)` parametrized by per-tool seams (command resolver,
+  source metadata, arg transform, pre-spawn hook); `runClaudeCode` / `runCodex`
+  are thin wrappers. Claude-code behavior is preserved (its run tests are
+  unchanged and pass).
 - Added `ORIENTATION_START` / `ORIENTATION_END` markers to core and a shared
   `context-channel` lib (`syncMarkerBlock` / `removeMarkerBlock` /
   `assertNoMarkerLine`) that owns the symlink guard, append/replace, one-time

packages/cli/src/commands/refresh.ts

@@ -1,12 +1,6 @@
-import {
-  assertBasouRootSafe,
-  type BasouPaths,
-  basouPaths,
-  findErrorCode,
-  readMarkdownFile,
-} from "@basou/core";
+import { assertBasouRootSafe, type BasouPaths, basouPaths, findErrorCode } from "@basou/core";
 import { type Command, InvalidArgumentError } from "commander";
-import { syncOrientationChannel } from "../lib/context-channel.js";
+import { renderOrientationToCodexChannel } from "../lib/context-channel.js";
 import { isVerbose, renderCliError } from "../lib/error-render.js";
 import { loadPortfolioConfig } from "../lib/portfolio-config.js";
 import { type ImportOutcome, type RefreshResult, refreshAll } from "../lib/provenance-actions.js";
@@ -320,13 +314,11 @@ async function syncCodexOrientationChannel(
   channelPath?: string,
 ): Promise<string | null> {
   try {
-    const body = await readMarkdownFile(paths.files.orientation);
-    if (body === null) return null;
-    const { action } = await syncOrientationChannel({
-      body,
-      ...(channelPath !== undefined ? { target: channelPath } : {}),
+    const rendered = await renderOrientationToCodexChannel({
+      orientationPath: paths.files.orientation,
+      ...(channelPath !== undefined ? { channelPath } : {}),
     });
-    return `codex channel: orientation ${action} in ${channelPath ?? "~/.codex/AGENTS.md"}`;
+    return rendered === null ? null : rendered.line;
   } catch (error: unknown) {
     return `codex channel skipped: ${error instanceof Error ? error.message : String(error)}`;
   }

packages/cli/src/commands/run.test.ts

@@ -16,7 +16,7 @@ import {
 } from "@basou/core";
 import { Command } from "commander";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { type RunContext, registerRunCommand, runClaudeCode } from "./run.js";
+import { type RunContext, registerRunCommand, runClaudeCode, runCodex } from "./run.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -693,3 +693,84 @@ describe("runClaudeCode", () => {
     expect(yaml).toContain("dirty-untracked.txt");
   });
 });
+
+describe("runCodex", () => {
+  const codexResolve = async (): Promise<{ command: string }> => ({ command: "codex" });
+
+  // codexChannelPath is ALWAYS overridden in these tests so the pre-spawn
+  // channel render never touches the real ~/.codex/AGENTS.md.
+  it("records a codex-adapter session and injects the env-policy flag into the child argv", async () => {
+    const repo = await setupInitedRepo();
+    const runner = makeFakeRunner({ exit_code: 0 });
+    const exitCode = await runCodex(
+      ["resume"],
+      { cwd: repo, snapshot: false },
+      {
+        runner,
+        now: () => FIXED_DATE,
+        resolveCodexCommand: codexResolve,
+        codexChannelPath: join(repo, "codex-AGENTS.md"),
+      },
+    );
+    expect(exitCode).toBe(0);
+    // The env-policy flag is prepended to whatever the user passed.
+    expect(runner.lastArgs).toEqual(["-c", "shell_environment_policy.inherit=all", "resume"]);
+    const sessionId = await findOnlySessionId(repo);
+    const lines = await readEventsLines(repo, sessionId);
+    expect(JSON.parse(lines[0] ?? "{}").source).toBe("codex-adapter");
+    // The recorded invocation reflects what actually ran (flag included).
+    const yaml = await readFile(join(basouPaths(repo).sessions, sessionId, "session.yaml"), "utf8");
+    expect(yaml).toContain("shell_environment_policy.inherit=all");
+    expect(yaml).toContain("codex-adapter");
+  });
+
+  it("renders this workspace's orientation into the overridden codex channel before spawn", async () => {
+    const repo = await setupInitedRepo();
+    // The launcher surfaces the LAST-rendered orientation (it does not refresh);
+    // seed one so the pre-spawn render has something to push.
+    await writeFile(basouPaths(repo).files.orientation, "# Orientation\n\nyou are right here\n");
+    const channelPath = join(repo, "codex-AGENTS.md");
+    const runner = makeFakeRunner({ exit_code: 0 });
+    await runCodex(
+      [],
+      { cwd: repo, snapshot: false },
+      {
+        runner,
+        now: () => FIXED_DATE,
+        resolveCodexCommand: codexResolve,
+        codexChannelPath: channelPath,
+      },
+    );
+    const channel = await readFile(channelPath, "utf8");
+    expect(channel).toContain("BASOU:ORIENTATION:START");
+    expect(channel).toContain("you are right here");
+  });
+
+  it("launches even when there is no orientation to render (best-effort channel)", async () => {
+    const repo = await setupInitedRepo();
+    // No orientation.md written → the pre-spawn render is a no-op, but the
+    // launch must still proceed and the channel file is never created.
+    const channelPath = join(repo, "codex-AGENTS.md");
+    const runner = makeFakeRunner({ exit_code: 0 });
+    const exitCode = await runCodex(
+      [],
+      { cwd: repo, snapshot: false },
+      {
+        runner,
+        now: () => FIXED_DATE,
+        resolveCodexCommand: codexResolve,
+        codexChannelPath: channelPath,
+      },
+    );
+    expect(exitCode).toBe(0);
+    await expect(access(channelPath)).rejects.toThrow();
+  });
+
+  it("registers a `codex` subcommand under `run`", () => {
+    const program = new Command();
+    registerRunCommand(program);
+    const run = program.commands.find((c) => c.name() === "run");
+    const subs = run?.commands.map((c) => c.name()) ?? [];
+    expect(subs).toEqual(expect.arrayContaining(["claude-code", "codex"]));
+  });
+});