open-research-protocol 0.4.28 → 0.4.29

package/CHANGELOG.md

@@ -6,6 +6,28 @@ There was no prior in-repo changelog file, so the first formal entry starts
 with the currently shipped `v0.4.4` release and summarizes the full release
 delta reflected in this repo.
 
+## v0.4.29 - 2026-04-25
+
+This release adds ORP-managed Codex session tracking so starting a Codex thread
+from a repo can automatically refresh the saved workspace session for that
+directory.
+
+### Added
+
+- Added `orp codex` as the default tracked Codex launcher: it resolves the repo
+  root, starts Codex there, watches local session metadata, and saves the new
+  Codex resume id into workspace `main`.
+- Added `orp codex status` and `orp codex reconcile` for checking stale saved
+  Codex sessions and refreshing tracked workspace tabs from recent local Codex
+  session metadata.
+- Added safeguards that ignore delegated/subagent sessions by default and refuse
+  broad roots or artifact-output repos unless explicitly overridden.
+
+### Changed
+
+- Documented the ORP/Codex compatibility workflow and exposed the new wrapper
+  command in the npm CLI help surface.
+
 ## v0.4.28 - 2026-04-22
 
 This release tightens the ORP project-startup and research-spend loops, then

package/README.md

@@ -459,6 +459,9 @@ orp workspace add-tab main --path /absolute/path/to/project --remote-url git@git
 orp workspace add-tab main --path /absolute/path/to/project --title "second active thread" --resume-tool claude --resume-session-id <id> --append
 orp workspace remove-tab main --path /absolute/path/to/project
 orp workspace sync main
+orp codex status
+orp codex reconcile --dry-run
+orp codex --search
 orp secrets list --json
 orp secrets ensure --alias openai-primary --provider openai --current-project --json
 orp secrets keychain-add --alias openai-primary --provider openai --env-var-name OPENAI_API_KEY --value-stdin --json
@@ -466,6 +469,19 @@ orp secrets sync-keychain openai-primary --json
 orp schedule add codex --name morning-summary --prompt "Summarize this repo" --json
 ```
 
+`orp codex` is a local compatibility layer for keeping workspace `main`
+aligned with Codex sessions. `status` compares the current repo against the
+latest local Codex session metadata, `reconcile` refreshes stale saved sessions,
+and bare `orp codex` launches Codex from the repo root while watching for the new
+session id. Delegated/subagent sessions are ignored by default, and
+artifact-output repos should be left untracked when a separate lab repo is the
+source of truth. Use `--` before Codex args that conflict with ORP wrapper
+options. The manual fallback from inside Codex is still:
+
+```bash
+orp workspace add-tab main --here --current-codex
+```
+
 For secrets, the simplest plain-English rule is:
 
 - `orp secrets ensure ...` = use the saved key if it already exists, or ask for it and create it if it does not

package/bin/orp.js

@@ -9,6 +9,9 @@ const computeCliUrl = pathToFileURL(path.resolve(__dirname, "orp-compute.mjs")).
 const workspaceCliUrl = pathToFileURL(
   path.resolve(__dirname, "..", "packages", "orp-workspace-launcher", "src", "orp-command.js"),
 ).href;
+const codexCliUrl = pathToFileURL(
+  path.resolve(__dirname, "..", "packages", "orp-workspace-launcher", "src", "codex.js"),
+).href;
 const argv = process.argv.slice(2);
 
 const candidates = [];
@@ -36,6 +39,12 @@ async function runWorkspace(args) {
   process.exit(code == null ? 0 : code);
 }
 
+async function runCodex(args) {
+  const mod = await import(codexCliUrl);
+  const code = await mod.runOrpCodexCommand(args);
+  process.exit(code == null ? 0 : code);
+}
+
 function runPythonCli(args, { captureOutput }) {
   let lastErr = null;
 
@@ -58,7 +67,7 @@ function runPythonCli(args, { captureOutput }) {
           process.stderr.write(result.stderr);
         }
         if (result.status === 0) {
-          process.stdout.write("\nAdditional wrapper surface:\n  orp compute -h\n  orp workspace tabs -h\n  orp workspace hygiene --json\n");
+          process.stdout.write("\nAdditional wrapper surface:\n  orp compute -h\n  orp workspace tabs -h\n  orp workspace hygiene --json\n  orp codex status -h\n");
         }
       }
       process.exit(result.status == null ? 1 : result.status);
@@ -91,6 +100,10 @@ async function main() {
     await runWorkspace(argv.slice(1));
     return;
   }
+  if (argv[0] === "codex") {
+    await runCodex(argv.slice(1));
+    return;
+  }
 
   runPythonCli(argv, { captureOutput: isTopLevelHelp(argv) });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-research-protocol",
-  "version": "0.4.28",
+  "version": "0.4.29",
   "description": "ORP CLI (Open Research Protocol): workspace ledgers, secrets, scheduling, governed execution, and agent-friendly research workflows.",
   "license": "MIT",
   "author": "Fractal Research Group <cody@frg.earth>",

package/packages/orp-workspace-launcher/src/codex.js

@@ -0,0 +1,822 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { spawn, spawnSync } from "node:child_process";
+
+import { buildLaunchPlan, getResumeCommand, parseWorkspaceSource } from "./core-plan.js";
+import { applyWorkspaceAddTabOptions } from "./ledger.js";
+import { loadWorkspaceSource } from "./orp.js";
+
+const DEFAULT_WORKSPACE = "main";
+const DEFAULT_SCAN_DAYS = 30;
+const SESSION_READ_BYTES = 64 * 1024;
+const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function normalizeOptionalString(value) {
+  if (value == null) {
+    return null;
+  }
+  const trimmed = String(value).trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizePath(value) {
+  const normalized = normalizeOptionalString(value);
+  return normalized ? path.resolve(normalized) : null;
+}
+
+function pathContains(parent, child) {
+  const normalizedParent = normalizePath(parent);
+  const normalizedChild = normalizePath(child);
+  if (!normalizedParent || !normalizedChild) {
+    return false;
+  }
+  return normalizedChild === normalizedParent || normalizedChild.startsWith(`${normalizedParent}${path.sep}`);
+}
+
+function resolveCodexHome(options = {}) {
+  return (
+    normalizeOptionalString(options.codexHome) ||
+    normalizeOptionalString(process.env.CODEX_HOME) ||
+    path.join(os.homedir(), ".codex")
+  );
+}
+
+function defaultForbiddenRoots() {
+  return new Set(
+    [
+      path.parse(process.cwd()).root,
+      os.homedir(),
+      "/Volumes/Code_2TB/code",
+      normalizeOptionalString(process.env.ORP_CODE_ROOT),
+    ]
+      .map((entry) => (entry ? path.resolve(entry) : null))
+      .filter(Boolean),
+  );
+}
+
+function isArtifactOutputRepo(repoRoot) {
+  const base = path.basename(String(repoRoot || ""));
+  return /(^|-)artifacts?$/i.test(base) || /-artifacts?-/i.test(base);
+}
+
+export function isDelegatedCodexSession(session) {
+  const originator = normalizeOptionalString(session?.originator)?.toLowerCase();
+  if (originator === "clawdad" || originator?.includes("delegate")) {
+    return true;
+  }
+  const source = session?.source;
+  if (!source || typeof source !== "object" || Array.isArray(source)) {
+    return false;
+  }
+  if (source.subagent || source.delegate || source.delegated) {
+    return true;
+  }
+  const sourceText = JSON.stringify(source).toLowerCase();
+  return sourceText.includes("subagent") || sourceText.includes("delegate");
+}
+
+export function parseCodexSessionMetaLine(line, filePath, stat = {}) {
+  let row;
+  try {
+    row = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!row || row.type !== "session_meta" || !row.payload || typeof row.payload !== "object") {
+    return null;
+  }
+
+  const payload = row.payload;
+  const sessionId = normalizeOptionalString(payload.id);
+  const cwd = normalizeOptionalString(payload.cwd);
+  if (!sessionId || !SESSION_ID_PATTERN.test(sessionId) || !cwd) {
+    return null;
+  }
+
+  const timestamp = normalizeOptionalString(payload.timestamp) || normalizeOptionalString(row.timestamp);
+  const timestampMs = timestamp ? Date.parse(timestamp) : 0;
+  return {
+    sessionId,
+    cwd: path.resolve(cwd),
+    timestamp,
+    timestampMs: Number.isFinite(timestampMs) ? timestampMs : 0,
+    updatedMs: typeof stat.mtimeMs === "number" ? stat.mtimeMs : 0,
+    filePath,
+    originator: normalizeOptionalString(payload.originator),
+    cliVersion: normalizeOptionalString(payload.cli_version ?? payload.cliVersion),
+    source: payload.source && typeof payload.source === "object" && !Array.isArray(payload.source) ? payload.source : null,
+  };
+}
+
+async function readFirstSessionMetaLine(filePath) {
+  let handle;
+  try {
+    handle = await fs.open(filePath, "r");
+    const buffer = Buffer.alloc(SESSION_READ_BYTES);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    if (bytesRead <= 0) {
+      return "";
+    }
+    const chunk = buffer.subarray(0, bytesRead).toString("utf8");
+    for (const line of chunk.split("\n")) {
+      if (!line.trim()) {
+        continue;
+      }
+      let row;
+      try {
+        row = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (row?.type === "session_meta") {
+        return line;
+      }
+    }
+    return "";
+  } catch {
+    return "";
+  } finally {
+    if (handle) {
+      await handle.close().catch(() => {});
+    }
+  }
+}
+
+async function walkSessionFiles(rootDir, options = {}, files = []) {
+  let entries;
+  try {
+    entries = await fs.readdir(rootDir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    const entryPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      await walkSessionFiles(entryPath, options, files);
+      continue;
+    }
+    if (!entry.isFile() || !entry.name.endsWith(".jsonl") || !entry.name.startsWith("rollout-")) {
+      continue;
+    }
+    files.push(entryPath);
+  }
+  return files;
+}
+
+export async function scanCodexSessions(options = {}) {
+  const codexHome = resolveCodexHome(options);
+  const sessionsDir = path.join(codexHome, "sessions");
+  const sinceMs = typeof options.sinceMs === "number" ? options.sinceMs : 0;
+  const includeDelegated = Boolean(options.includeDelegated || options.includeSubagents);
+  const files = await walkSessionFiles(sessionsDir, options);
+  const sessions = [];
+
+  for (const filePath of files) {
+    let stat;
+    try {
+      stat = await fs.stat(filePath);
+    } catch {
+      continue;
+    }
+    if (sinceMs && stat.mtimeMs < sinceMs) {
+      continue;
+    }
+    const metaLine = await readFirstSessionMetaLine(filePath);
+    if (!metaLine) {
+      continue;
+    }
+    const session = parseCodexSessionMetaLine(metaLine, filePath, stat);
+    if (!session) {
+      continue;
+    }
+    if (!includeDelegated && isDelegatedCodexSession(session)) {
+      continue;
+    }
+    sessions.push(session);
+  }
+
+  return sessions.sort((left, right) => latestSessionMs(right) - latestSessionMs(left));
+}
+
+function latestSessionMs(session) {
+  return Math.max(Number(session?.updatedMs || 0), Number(session?.timestampMs || 0));
+}
+
+export function resolveRepoRoot(startPath = process.cwd(), options = {}) {
+  const cwd = path.resolve(startPath);
+  const git = spawnSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+  });
+  const repoRoot = git.status === 0 && git.stdout.trim() ? path.resolve(git.stdout.trim()) : cwd;
+  const forbiddenRoots = options.forbiddenRoots instanceof Set ? options.forbiddenRoots : defaultForbiddenRoots();
+  const isForbidden = forbiddenRoots.has(repoRoot);
+  const isArtifact = !options.includeArtifactRepos && isArtifactOutputRepo(repoRoot);
+
+  return {
+    inputPath: cwd,
+    repoRoot,
+    ok: !isForbidden && !isArtifact,
+    reason: isForbidden ? "broad_root" : isArtifact ? "artifact_output_repo" : null,
+  };
+}
+
+function latestSessionForPath(sessions, targetPath) {
+  const target = path.resolve(targetPath);
+  return (
+    sessions
+      .filter((session) => pathContains(target, session.cwd))
+      .sort((left, right) => latestSessionMs(right) - latestSessionMs(left))[0] || null
+  );
+}
+
+async function loadWorkspaceTabs(options = {}) {
+  const source = await loadWorkspaceSource({
+    ideaId: options.workspace || DEFAULT_WORKSPACE,
+    workspaceFile: options.workspaceFile,
+    hostedWorkspaceId: options.hostedWorkspaceId,
+    baseUrl: options.baseUrl,
+    orpCommand: options.orpCommand,
+  });
+  const parsed = parseWorkspaceSource(source);
+  const tabs = buildLaunchPlan(parsed.entries, {
+    tmux: false,
+    resume: true,
+  });
+  return {
+    source,
+    parsed,
+    tabs,
+  };
+}
+
+function codexTabsForPath(tabs, repoRoot) {
+  const target = path.resolve(repoRoot);
+  return tabs.filter((tab) => path.resolve(tab.path) === target && tab.resumeTool === "codex");
+}
+
+function anyTabsForPath(tabs, repoRoot) {
+  const target = path.resolve(repoRoot);
+  return tabs.filter((tab) => path.resolve(tab.path) === target);
+}
+
+function tabSummary(tab) {
+  if (!tab) {
+    return null;
+  }
+  return {
+    title: tab.title || null,
+    path: tab.path,
+    resumeCommand: getResumeCommand(tab),
+    resumeTool: tab.resumeTool || null,
+    resumeSessionId: tab.sessionId || null,
+    codexSessionId: tab.resumeTool === "codex" ? tab.sessionId || null : null,
+  };
+}
+
+function sessionSummary(session) {
+  if (!session) {
+    return null;
+  }
+  return {
+    sessionId: session.sessionId,
+    cwd: session.cwd,
+    timestamp: session.timestamp || null,
+    updatedAt: session.updatedMs ? new Date(session.updatedMs).toISOString() : null,
+    originator: session.originator || null,
+    cliVersion: session.cliVersion || null,
+    filePath: session.filePath || null,
+  };
+}
+
+function sinceMsFromOptions(options = {}) {
+  if (typeof options.sinceMs === "number") {
+    return options.sinceMs;
+  }
+  const sinceDays = Number.isFinite(options.sinceDays) ? options.sinceDays : DEFAULT_SCAN_DAYS;
+  return sinceDays > 0 ? Date.now() - sinceDays * 24 * 60 * 60 * 1000 : 0;
+}
+
+export async function buildCodexStatusReport(options = {}) {
+  const repo = resolveRepoRoot(options.path || process.cwd(), options);
+  const workspace = options.workspace || DEFAULT_WORKSPACE;
+  const [workspaceData, sessions] = await Promise.all([
+    loadWorkspaceTabs(options),
+    scanCodexSessions({
+      ...options,
+      sinceMs: sinceMsFromOptions(options),
+    }),
+  ]);
+  const trackedCodexTabs = repo.ok ? codexTabsForPath(workspaceData.tabs, repo.repoRoot) : [];
+  const trackedTabs = repo.ok ? anyTabsForPath(workspaceData.tabs, repo.repoRoot) : [];
+  const latestSession = repo.ok ? latestSessionForPath(sessions, repo.repoRoot) : null;
+  const primaryTab = trackedCodexTabs.length === 1 ? trackedCodexTabs[0] : trackedCodexTabs[0] || null;
+  const trackedSessionId = primaryTab?.sessionId || null;
+
+  let status = "unknown";
+  if (!repo.ok) {
+    status = repo.reason || "invalid_repo";
+  } else if (trackedCodexTabs.length > 1) {
+    status = "ambiguous";
+  } else if (trackedTabs.length === 0) {
+    status = "untracked";
+  } else if (!latestSession) {
+    status = "no_local_codex_session";
+  } else if (trackedSessionId === latestSession.sessionId) {
+    status = "current";
+  } else {
+    status = "stale";
+  }
+
+  return {
+    workspace,
+    sourceLabel: workspaceData.source.sourceLabel,
+    repoRoot: repo.repoRoot,
+    repoOk: repo.ok,
+    repoReason: repo.reason,
+    status,
+    stale: status === "stale",
+    trackedTab: tabSummary(primaryTab),
+    trackedTabs: trackedCodexTabs.map((tab) => tabSummary(tab)),
+    latestCodexSession: sessionSummary(latestSession),
+    updateCommand:
+      repo.ok && latestSession
+        ? `orp workspace add-tab ${workspace} --path '${repo.repoRoot}' --resume-tool codex --resume-session-id ${latestSession.sessionId}`
+        : null,
+  };
+}
+
+export function summarizeCodexStatus(report) {
+  const lines = [
+    `Workspace: ${report.workspace}`,
+    `Repo: ${report.repoRoot}`,
+    `Status: ${report.status}`,
+  ];
+  if (report.trackedTab) {
+    lines.push(`Tracked: ${report.trackedTab.resumeCommand || "path-only"}`);
+  }
+  if (report.latestCodexSession) {
+    lines.push(`Latest local Codex: codex resume ${report.latestCodexSession.sessionId}`);
+    lines.push(`Latest cwd: ${report.latestCodexSession.cwd}`);
+  }
+  if (report.updateCommand && report.stale) {
+    lines.push(`Refresh: ${report.updateCommand}`);
+  }
+  return lines.join("\n");
+}
+
+function buildWorkspaceOptions(options = {}) {
+  return Object.fromEntries(
+    Object.entries({
+      ideaId: options.workspace || DEFAULT_WORKSPACE,
+      workspaceFile: options.workspaceFile,
+      hostedWorkspaceId: options.hostedWorkspaceId,
+      baseUrl: options.baseUrl,
+      orpCommand: options.orpCommand,
+    }).filter(([, value]) => value != null),
+  );
+}
+
+function plannedMutationForTrackedPath(tabs, repoRoot, latestSession) {
+  const trackedTabs = anyTabsForPath(tabs, repoRoot);
+  if (trackedTabs.length === 0) {
+    return null;
+  }
+  const codexTabs = codexTabsForPath(tabs, repoRoot);
+  if (codexTabs.length > 1) {
+    return {
+      action: "skip",
+      reason: "ambiguous_codex_tabs",
+      repoRoot,
+      latestCodexSession: sessionSummary(latestSession),
+      trackedTabs: codexTabs.map((tab) => tabSummary(tab)),
+    };
+  }
+  const current = codexTabs[0] || null;
+  if (!latestSession) {
+    return {
+      action: "skip",
+      reason: "no_local_codex_session",
+      repoRoot,
+      trackedTab: tabSummary(current || trackedTabs[0]),
+    };
+  }
+  if (current?.sessionId === latestSession.sessionId) {
+    return {
+      action: "unchanged",
+      repoRoot,
+      trackedTab: tabSummary(current),
+      latestCodexSession: sessionSummary(latestSession),
+    };
+  }
+  return {
+    action: current ? "update" : "attach",
+    repoRoot,
+    title: current?.title || trackedTabs[0]?.title || undefined,
+    trackedTab: tabSummary(current || trackedTabs[0]),
+    latestCodexSession: sessionSummary(latestSession),
+  };
+}
+
+export async function buildCodexReconcilePlan(options = {}) {
+  const workspace = options.workspace || DEFAULT_WORKSPACE;
+  const [workspaceData, sessions] = await Promise.all([
+    loadWorkspaceTabs(options),
+    scanCodexSessions({
+      ...options,
+      sinceMs: sinceMsFromOptions(options),
+    }),
+  ]);
+  const trackedPaths = [...new Set(workspaceData.tabs.map((tab) => path.resolve(tab.path)))];
+  const actions = [];
+
+  for (const repoRoot of trackedPaths) {
+    if (!resolveRepoRoot(repoRoot, options).ok) {
+      actions.push({ action: "skip", reason: "refused_repo_root", repoRoot });
+      continue;
+    }
+    actions.push(plannedMutationForTrackedPath(workspaceData.tabs, repoRoot, latestSessionForPath(sessions, repoRoot)));
+  }
+
+  const trackedPathSet = new Set(trackedPaths);
+  const missingByRepo = new Map();
+  if (options.addMissing) {
+    for (const session of sessions) {
+      const repo = resolveRepoRoot(session.cwd, options);
+      if (!repo.ok || trackedPathSet.has(repo.repoRoot)) {
+        continue;
+      }
+      const current = missingByRepo.get(repo.repoRoot);
+      if (!current || latestSessionMs(session) > latestSessionMs(current)) {
+        missingByRepo.set(repo.repoRoot, session);
+      }
+    }
+    for (const [repoRoot, session] of missingByRepo.entries()) {
+      actions.push({
+        action: "add",
+        repoRoot,
+        title: path.basename(repoRoot),
+        latestCodexSession: sessionSummary(session),
+      });
+    }
+  }
+
+  return {
+    workspace,
+    sourceLabel: workspaceData.source.sourceLabel,
+    dryRun: Boolean(options.dryRun),
+    addMissing: Boolean(options.addMissing),
+    actionCount: actions.filter((action) => ["update", "attach", "add"].includes(action?.action)).length,
+    actions: actions.filter(Boolean),
+  };
+}
+
+async function applyReconcileAction(action, options = {}) {
+  if (!["update", "attach", "add"].includes(action.action)) {
+    return { ...action, applied: false };
+  }
+  const latest = action.latestCodexSession;
+  const result = await applyWorkspaceAddTabOptions({
+    ...buildWorkspaceOptions(options),
+    path: action.repoRoot,
+    title: action.action === "add" ? action.title : undefined,
+    resumeTool: "codex",
+    resumeSessionId: latest.sessionId,
+    append: Boolean(options.append),
+  });
+  return {
+    ...action,
+    applied: true,
+    mutation: result.mutation,
+    tab: result.tab,
+  };
+}
+
+export async function applyCodexReconcilePlan(plan, options = {}) {
+  const appliedActions = [];
+  for (const action of plan.actions) {
+    if (options.dryRun || !["update", "attach", "add"].includes(action.action)) {
+      appliedActions.push({ ...action, applied: false });
+      continue;
+    }
+    appliedActions.push(await applyReconcileAction(action, options));
+  }
+  return {
+    ...plan,
+    dryRun: Boolean(options.dryRun),
+    actions: appliedActions,
+  };
+}
+
+export function summarizeCodexReconcile(report) {
+  const lines = [
+    `Workspace: ${report.workspace}`,
+    `Source: ${report.sourceLabel}`,
+    `Mode: ${report.dryRun ? "dry-run" : "apply"}`,
+    `Actionable: ${report.actionCount}`,
+    "",
+  ];
+  for (const action of report.actions) {
+    const prefix = action.applied ? "applied" : action.action;
+    lines.push(`${prefix}: ${action.repoRoot}${action.reason ? ` (${action.reason})` : ""}`);
+    if (action.latestCodexSession) {
+      lines.push(`  latest: codex resume ${action.latestCodexSession.sessionId}`);
+    }
+  }
+  return lines.join("\n").trimEnd();
+}
+
+function parseCommonOptions(argv = [], defaults = {}, parseOptions = {}) {
+  const options = {
+    workspace: DEFAULT_WORKSPACE,
+    json: false,
+    sinceDays: DEFAULT_SCAN_DAYS,
+    ...defaults,
+  };
+  const rest = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === "--add-missing") {
+      options.addMissing = true;
+      continue;
+    }
+    if (arg === "--append") {
+      options.append = true;
+      continue;
+    }
+    if (arg === "--include-subagents" || arg === "--include-delegated") {
+      options.includeSubagents = true;
+      options.includeDelegated = true;
+      continue;
+    }
+    if (arg === "--include-artifacts") {
+      options.includeArtifactRepos = true;
+      continue;
+    }
+    if (arg === "--") {
+      rest.push(...argv.slice(index + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const next = argv[index + 1];
+      if (arg === "--workspace") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.workspace = next;
+      } else if (arg === "--workspace-file") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.workspaceFile = next;
+      } else if (arg === "--hosted-workspace-id") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.hostedWorkspaceId = next;
+      } else if (arg === "--base-url") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.baseUrl = next;
+      } else if (arg === "--orp-command") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.orpCommand = next;
+      } else if (arg === "--codex-home") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.codexHome = next;
+      } else if (arg === "--path") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.path = next;
+      } else if (arg === "--since-days") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.sinceDays = Number(next);
+      } else if (arg === "--title") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.title = next;
+      } else if (arg === "--codex-bin") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.codexBin = next;
+      } else if (arg === "--watch-timeout-ms") {
+        if (next == null || next.startsWith("--")) {
+          throw new Error(`missing value for ${arg}`);
+        }
+        options.watchTimeoutMs = Number(next);
+      } else {
+        if (parseOptions.passUnknownOptions) {
+          rest.push(...argv.slice(index));
+          break;
+        }
+        throw new Error(`unknown option: ${arg}`);
+      }
+      index += 1;
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { options, rest };
+}
+
+function printCodexHelp() {
+  console.log(`ORP Codex session tracking
+
+Usage:
+  orp codex [--workspace main] [--append] [--title <title>] [codex args...]
+  orp codex status [--workspace main] [--json]
+  orp codex reconcile [--workspace main] [--dry-run] [--add-missing] [--json]
+  orp codex start [--workspace main] [--append] [--title <title>] [-- <codex args...>]
+
+Commands:
+  status     Compare this repo's ORP tab with the latest local Codex session
+  reconcile  Scan recent local Codex sessions and refresh stale ORP workspace tabs
+  start      Launch Codex in the repo root and save the new session when metadata appears
+
+Notes:
+  - Delegated/subagent sessions are ignored by default.
+  - Broad roots and artifact-output repos are refused unless explicitly overridden.
+  - Use -- before Codex args that conflict with ORP wrapper options.
+  - Manual fallback inside Codex remains: orp workspace add-tab main --here --current-codex
+`);
+}
+
+function printStatusHelp() {
+  console.log(`ORP Codex status
+
+Usage:
+  orp codex status [--workspace main] [--path <repo-or-subdir>] [--codex-home <path>] [--json]
+`);
+}
+
+function printReconcileHelp() {
+  console.log(`ORP Codex reconcile
+
+Usage:
+  orp codex reconcile [--workspace main] [--dry-run] [--add-missing] [--since-days <n>] [--json]
+`);
+}
+
+function printStartHelp() {
+  console.log(`ORP Codex start
+
+Usage:
+  orp codex [--workspace main] [--append] [--title <title>] [codex args...]
+  orp codex start [--workspace main] [--append] [--title <title>] [--codex-bin <bin>] [--watch-timeout-ms <ms>] [-- <codex args...>]
+`);
+}
+
+async function runCodexStatus(argv) {
+  const { options } = parseCommonOptions(argv);
+  if (options.help) {
+    printStatusHelp();
+    return 0;
+  }
+  const report = await buildCodexStatusReport(options);
+  process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : `${summarizeCodexStatus(report)}\n`);
+  return 0;
+}
+
+async function runCodexReconcile(argv) {
+  const { options } = parseCommonOptions(argv);
+  if (options.help) {
+    printReconcileHelp();
+    return 0;
+  }
+  const plan = await buildCodexReconcilePlan(options);
+  const report = await applyCodexReconcilePlan(plan, options);
+  process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : `${summarizeCodexReconcile(report)}\n`);
+  return 0;
+}
+
+async function waitForMatchingSession(repoRoot, options = {}) {
+  const startedAtMs = options.startedAtMs || Date.now();
+  const timeoutMs = Number.isFinite(options.watchTimeoutMs) ? options.watchTimeoutMs : 30000;
+  const deadline = Date.now() + timeoutMs;
+  let latest = null;
+  while (Date.now() <= deadline) {
+    const sessions = await scanCodexSessions({
+      ...options,
+      sinceMs: startedAtMs - 1000,
+    });
+    latest = latestSessionForPath(sessions, repoRoot);
+    if (latest && latestSessionMs(latest) >= startedAtMs - 1000) {
+      return latest;
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, Math.min(500, remainingMs)));
+  }
+  return latest;
+}
+
+async function runCodexStart(argv) {
+  const { options, rest: codexArgs } = parseCommonOptions(argv, {
+    watchTimeoutMs: 30000,
+  }, { passUnknownOptions: true });
+  if (options.help) {
+    printStartHelp();
+    return 0;
+  }
+  const repo = resolveRepoRoot(options.path || process.cwd(), options);
+  if (!repo.ok) {
+    throw new Error(`Refusing to start Codex for ${repo.repoRoot}: ${repo.reason}`);
+  }
+
+  const startedAtMs = Date.now();
+  const codexBin = normalizeOptionalString(options.codexBin) || "codex";
+  const args = ["-C", repo.repoRoot, ...codexArgs];
+  const watcher = waitForMatchingSession(repo.repoRoot, {
+    ...options,
+    startedAtMs,
+  })
+    .then(async (session) => {
+      if (!session) {
+        return null;
+      }
+      const result = await applyWorkspaceAddTabOptions({
+        ...buildWorkspaceOptions(options),
+        path: repo.repoRoot,
+        title: options.append ? options.title : undefined,
+        resumeTool: "codex",
+        resumeSessionId: session.sessionId,
+        append: Boolean(options.append),
+      });
+      return { session, result };
+    })
+    .catch((error) => ({ error }));
+
+  const child = spawn(codexBin, args, {
+    cwd: repo.repoRoot,
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  const childExit = await new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("close", (code) => resolve(code == null ? 1 : code));
+  });
+  const watched = await watcher;
+  if (!watched || watched.error) {
+    process.stderr.write(
+      `ORP could not automatically save the Codex session. Fallback: orp workspace add-tab ${options.workspace || DEFAULT_WORKSPACE} --here --current-codex\n`,
+    );
+    if (watched?.error) {
+      process.stderr.write(`${watched.error instanceof Error ? watched.error.message : String(watched.error)}\n`);
+    }
+  } else if (options.json) {
+    process.stdout.write(`${JSON.stringify({ repoRoot: repo.repoRoot, session: sessionSummary(watched.session), mutation: watched.result.mutation }, null, 2)}\n`);
+  } else {
+    process.stderr.write(
+      `ORP saved Codex session for ${repo.repoRoot}: codex resume ${watched.session.sessionId}\n`,
+    );
+  }
+  return childExit;
+}
+
+export async function runOrpCodexCommand(argv = []) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "-h" || subcommand === "--help" || subcommand === "help") {
+    printCodexHelp();
+    return 0;
+  }
+  if (!subcommand) {
+    return runCodexStart([]);
+  }
+  if (subcommand === "status") {
+    return runCodexStatus(rest);
+  }
+  if (subcommand === "reconcile") {
+    return runCodexReconcile(rest);
+  }
+  if (subcommand === "start") {
+    return runCodexStart(rest);
+  }
+  return runCodexStart(argv);
+}

package/packages/orp-workspace-launcher/src/index.js

@@ -1,3 +1,13 @@
+export {
+  applyCodexReconcilePlan,
+  buildCodexReconcilePlan,
+  buildCodexStatusReport,
+  parseCodexSessionMetaLine,
+  runOrpCodexCommand,
+  scanCodexSessions,
+  summarizeCodexReconcile,
+  summarizeCodexStatus,
+} from "./codex.js";
 export {
   buildCloneCommand,
   buildDirectCommand,

package/packages/orp-workspace-launcher/src/ledger.js

@@ -945,7 +945,7 @@ function summarizeWorkspaceLedgerMutation(result) {
   return lines.join("\n");
 }
 
-async function runWorkspaceLedgerMutation(options, mutate, action) {
+async function applyWorkspaceLedgerMutation(options, mutate, action) {
   const source = await loadWorkspaceSource(options);
   const parsed = parseWorkspaceSource(source);
   const manifest = normalizeEditableManifest(source, parsed);
@@ -974,6 +974,12 @@ async function runWorkspaceLedgerMutation(options, mutate, action) {
     manifest: finalManifest,
   };
 
+  return result;
+}
+
+async function runWorkspaceLedgerMutation(options, mutate, action) {
+  const result = await applyWorkspaceLedgerMutation(options, mutate, action);
+
   if (options.json) {
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     return 0;
@@ -983,6 +989,10 @@ async function runWorkspaceLedgerMutation(options, mutate, action) {
   return 0;
 }
 
+export async function applyWorkspaceAddTabOptions(options = {}) {
+  return applyWorkspaceLedgerMutation(options, addTabToManifest, "add-tab");
+}
+
 export async function runWorkspaceAddTab(argv = process.argv.slice(2)) {
   const options = parseWorkspaceAddTabArgs(argv);
   if (options.help) {

package/packages/orp-workspace-launcher/test/codex.test.js

@@ -0,0 +1,309 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  applyCodexReconcilePlan,
+  buildCodexReconcilePlan,
+  buildCodexStatusReport,
+  parseCodexSessionMetaLine,
+  runOrpCodexCommand,
+  scanCodexSessions,
+} from "../src/index.js";
+
+async function makeTempDir() {
+  return fs.mkdtemp(path.join(os.tmpdir(), "orp-codex-"));
+}
+
+async function writeSession(codexHome, sessionId, cwd, timestamp, extraPayload = {}) {
+  const day = timestamp.slice(0, 10).split("-");
+  const sessionsDir = path.join(codexHome, "sessions", day[0], day[1], day[2]);
+  await fs.mkdir(sessionsDir, { recursive: true });
+  const filePath = path.join(sessionsDir, `rollout-${timestamp.replaceAll(":", "-")}-${sessionId}.jsonl`);
+  const row = {
+    timestamp,
+    type: "session_meta",
+    payload: {
+      id: sessionId,
+      timestamp,
+      cwd,
+      originator: "codex-tui",
+      cli_version: "0.125.0",
+      ...extraPayload,
+    },
+  };
+  await fs.writeFile(filePath, `${JSON.stringify(row)}\n`, "utf8");
+  const mtime = new Date(timestamp);
+  await fs.utimes(filePath, mtime, mtime);
+  return filePath;
+}
+
+async function writeSessionWithPrefix(codexHome, sessionId, cwd, timestamp) {
+  const filePath = await writeSession(codexHome, sessionId, cwd, timestamp);
+  const original = await fs.readFile(filePath, "utf8");
+  await fs.writeFile(filePath, `${JSON.stringify({ type: "response_item", payload: {} })}\n${original}`, "utf8");
+  const mtime = new Date(timestamp);
+  await fs.utimes(filePath, mtime, mtime);
+  return filePath;
+}
+
+async function writeWorkspaceManifest(filePath, tabs) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(
+    filePath,
+    `${JSON.stringify(
+      {
+        version: "1",
+        workspaceId: "orp-main",
+        title: "ORP Main",
+        tabs,
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+}
+
+test("parseCodexSessionMetaLine reads stable session metadata", () => {
+  const row = JSON.stringify({
+    timestamp: "2026-04-25T12:00:00Z",
+    type: "session_meta",
+    payload: {
+      id: "019dc2cb-d435-7072-bbfd-4ae4280474dd",
+      timestamp: "2026-04-25T12:00:00Z",
+      cwd: "/tmp/example",
+      originator: "codex-tui",
+      cli_version: "0.125.0",
+    },
+  });
+
+  const parsed = parseCodexSessionMetaLine(row, "/tmp/session.jsonl", { mtimeMs: 123 });
+  assert.equal(parsed.sessionId, "019dc2cb-d435-7072-bbfd-4ae4280474dd");
+  assert.equal(parsed.cwd, "/tmp/example");
+  assert.equal(parsed.cliVersion, "0.125.0");
+  assert.equal(parsed.updatedMs, 123);
+  assert.equal(parseCodexSessionMetaLine("not json", "/tmp/session.jsonl"), null);
+});
+
+test("scanCodexSessions ignores delegated sessions by default", async () => {
+  const tempDir = await makeTempDir();
+  const codexHome = path.join(tempDir, "codex-home");
+  await writeSession(
+    codexHome,
+    "019dc2cb-d435-7072-bbfd-4ae4280474aa",
+    path.join(tempDir, "repo"),
+    "2026-04-25T12:00:00Z",
+  );
+  await writeSession(
+    codexHome,
+    "019dc2cb-d435-7072-bbfd-4ae4280474bb",
+    path.join(tempDir, "repo"),
+    "2026-04-25T12:01:00Z",
+    { source: { subagent: { other: "guardian" } } },
+  );
+  await writeSession(
+    codexHome,
+    "019dc2cb-d435-7072-bbfd-4ae4280474cc",
+    path.join(tempDir, "repo"),
+    "2026-04-25T12:02:00Z",
+    { originator: "clawdad" },
+  );
+
+  const defaultSessions = await scanCodexSessions({ codexHome, sinceMs: 0 });
+  assert.deepEqual(
+    defaultSessions.map((session) => session.sessionId),
+    ["019dc2cb-d435-7072-bbfd-4ae4280474aa"],
+  );
+
+  const allSessions = await scanCodexSessions({ codexHome, sinceMs: 0, includeSubagents: true });
+  assert.deepEqual(
+    allSessions.map((session) => session.sessionId),
+    [
+      "019dc2cb-d435-7072-bbfd-4ae4280474cc",
+      "019dc2cb-d435-7072-bbfd-4ae4280474bb",
+      "019dc2cb-d435-7072-bbfd-4ae4280474aa",
+    ],
+  );
+});
+
+test("scanCodexSessions finds session metadata near the start of a rollout file", async () => {
+  const tempDir = await makeTempDir();
+  const codexHome = path.join(tempDir, "codex-home");
+  const repoRoot = path.join(tempDir, "repo");
+  await writeSessionWithPrefix(
+    codexHome,
+    "019dc2cb-d435-7072-bbfd-4ae4280474dd",
+    repoRoot,
+    "2026-04-25T12:00:00Z",
+  );
+
+  const sessions = await scanCodexSessions({ codexHome, sinceMs: 0 });
+  assert.equal(sessions.length, 1);
+  assert.equal(sessions[0].sessionId, "019dc2cb-d435-7072-bbfd-4ae4280474dd");
+});
+
+test("buildCodexStatusReport marks a tracked repo stale when local Codex metadata is newer", async () => {
+  const tempDir = await makeTempDir();
+  const repoRoot = path.join(tempDir, "repo");
+  const codexHome = path.join(tempDir, "codex-home");
+  const workspaceFile = path.join(tempDir, "workspace.json");
+  await fs.mkdir(repoRoot, { recursive: true });
+  await writeWorkspaceManifest(workspaceFile, [
+    {
+      title: "repo",
+      path: repoRoot,
+      resumeTool: "codex",
+      resumeSessionId: "019dc2cb-d435-7072-bbfd-4ae428047401",
+    },
+  ]);
+  await writeSession(codexHome, "019dc2cb-d435-7072-bbfd-4ae428047402", repoRoot, "2026-04-25T12:00:00Z");
+
+  const report = await buildCodexStatusReport({
+    workspaceFile,
+    codexHome,
+    path: repoRoot,
+    sinceDays: 0,
+  });
+
+  assert.equal(report.status, "stale");
+  assert.equal(report.trackedTab.codexSessionId, "019dc2cb-d435-7072-bbfd-4ae428047401");
+  assert.equal(report.latestCodexSession.sessionId, "019dc2cb-d435-7072-bbfd-4ae428047402");
+});
+
+test("Codex reconcile updates tracked workspace tabs without appending by default", async () => {
+  const tempDir = await makeTempDir();
+  const repoRoot = path.join(tempDir, "repo");
+  const codexHome = path.join(tempDir, "codex-home");
+  const workspaceFile = path.join(tempDir, "workspace.json");
+  await fs.mkdir(repoRoot, { recursive: true });
+  await writeWorkspaceManifest(workspaceFile, [
+    {
+      title: "repo",
+      path: repoRoot,
+      resumeTool: "codex",
+      resumeSessionId: "019dc2cb-d435-7072-bbfd-4ae428047411",
+    },
+  ]);
+  await writeSession(codexHome, "019dc2cb-d435-7072-bbfd-4ae428047412", repoRoot, "2026-04-25T12:00:00Z");
+
+  const plan = await buildCodexReconcilePlan({
+    workspaceFile,
+    codexHome,
+    sinceDays: 0,
+  });
+  assert.equal(plan.actionCount, 1);
+  assert.equal(plan.actions[0].action, "update");
+
+  const applied = await applyCodexReconcilePlan(plan, {
+    workspaceFile,
+    codexHome,
+  });
+  assert.equal(applied.actions[0].applied, true);
+
+  const manifest = JSON.parse(await fs.readFile(workspaceFile, "utf8"));
+  assert.equal(manifest.tabs.length, 1);
+  assert.equal(manifest.tabs[0].resumeSessionId, "019dc2cb-d435-7072-bbfd-4ae428047412");
+  assert.equal(manifest.tabs[0].codexSessionId, "019dc2cb-d435-7072-bbfd-4ae428047412");
+});
+
+test("bare orp codex routes to start", async () => {
+  const tempDir = await makeTempDir();
+  const codexHome = path.join(tempDir, "codex-home");
+  const fakeCodex = path.join(tempDir, "fake-codex");
+  await fs.writeFile(fakeCodex, "#!/bin/sh\nexit 0\n", "utf8");
+  await fs.chmod(fakeCodex, 0o755);
+
+  const originalWrite = process.stderr.write;
+  let stderr = "";
+  process.stderr.write = (chunk) => {
+    stderr += String(chunk);
+    return true;
+  };
+  try {
+    const code = await runOrpCodexCommand([
+      "--path",
+      tempDir,
+      "--codex-home",
+      codexHome,
+      "--codex-bin",
+      fakeCodex,
+      "--watch-timeout-ms",
+      "1",
+      "--search",
+    ]);
+    assert.equal(code, 0);
+    assert.match(stderr, /Fallback: orp workspace add-tab main --here --current-codex/);
+  } finally {
+    process.stderr.write = originalWrite;
+  }
+});
+
+test("bare orp codex saves the new session when Codex writes metadata", async () => {
+  const tempDir = await makeTempDir();
+  const repoRoot = path.join(tempDir, "repo");
+  const codexHome = path.join(tempDir, "codex-home");
+  const workspaceFile = path.join(tempDir, "workspace.json");
+  const fakeCodex = path.join(tempDir, "fake-codex.js");
+  const sessionId = "019dc2cb-d435-7072-bbfd-4ae4280474ee";
+  await fs.mkdir(repoRoot, { recursive: true });
+  await writeWorkspaceManifest(workspaceFile, []);
+  await fs.writeFile(
+    fakeCodex,
+    `#!/usr/bin/env node
+const fs = require("node:fs");
+const path = require("node:path");
+if (!process.argv.includes("--search")) process.exit(7);
+const codexHome = ${JSON.stringify(codexHome)};
+const repoRoot = ${JSON.stringify(repoRoot)};
+const sessionId = ${JSON.stringify(sessionId)};
+const timestamp = new Date().toISOString();
+const dir = path.join(codexHome, "sessions", "2026", "04", "25");
+fs.mkdirSync(dir, { recursive: true });
+fs.writeFileSync(
+  path.join(dir, "rollout-2026-04-25T12-00-00Z-" + sessionId + ".jsonl"),
+  JSON.stringify({
+    timestamp,
+    type: "session_meta",
+    payload: { id: sessionId, timestamp, cwd: repoRoot, originator: "codex-tui" },
+  }) + "\\n",
+);
+`,
+    "utf8",
+  );
+  await fs.chmod(fakeCodex, 0o755);
+
+  const originalWrite = process.stderr.write;
+  let stderr = "";
+  process.stderr.write = (chunk) => {
+    stderr += String(chunk);
+    return true;
+  };
+  try {
+    const code = await runOrpCodexCommand([
+      "--path",
+      repoRoot,
+      "--workspace-file",
+      workspaceFile,
+      "--codex-home",
+      codexHome,
+      "--codex-bin",
+      fakeCodex,
+      "--watch-timeout-ms",
+      "2000",
+      "--search",
+    ]);
+    assert.equal(code, 0);
+    assert.match(stderr, new RegExp(`ORP saved Codex session for .*: codex resume ${sessionId}`));
+  } finally {
+    process.stderr.write = originalWrite;
+  }
+
+  const manifest = JSON.parse(await fs.readFile(workspaceFile, "utf8"));
+  assert.equal(manifest.tabs.length, 1);
+  assert.equal(manifest.tabs[0].path, repoRoot);
+  assert.equal(manifest.tabs[0].resumeTool, "codex");
+  assert.equal(manifest.tabs[0].resumeSessionId, sessionId);
+});