@1agh/maude 1.0.9 → 1.2.0

package/apps/studio/sync/status.ts

@@ -14,6 +14,7 @@
 
 import type { AssetPushProgress } from './asset-push.ts';
 import type { SyncStatusSnapshot } from './connection-state.ts';
+import type { SeedProgress } from './seed-progress.ts';
 
 // `cold-start-hub-wins` stays in the union for OLD payload readers (additive
 // evolution — the NoSyncablePayload discriminator pattern); new conflicts are
@@ -41,6 +42,11 @@ export interface SyncStatusPayload extends SyncStatusSnapshot {
   canvases: number;
   /** Recent conflict notifications (most-recent-last, capped). */
   conflicts: SyncConflict[];
+  /**
+   * When the ConnectionMonitor last spoke, as distinct from when this payload
+   * was built (`updatedAt`). Additive — see the note in `payload()`.
+   */
+  connectionUpdatedAt?: number;
   /**
    * Phase 9.2 (DDR-064) — true when the unified single-shared-doc model is
    * active (MAUDE_SHARED_DOC). Lets `maude design status` + the browser banner
@@ -112,6 +118,25 @@ export interface FilePlaneStatus {
     /** One sentence, in the user's terms, about what is waiting and why. */
     detail: string;
   }[];
+  /**
+   * Files this lane could NOT move on the last pass — issue #109.
+   *
+   * `held` covers the breakers, which are deliberate refusals this machine
+   * made. This covers the other half: a transfer the hub refused, or a write
+   * that failed. It had no field at all, so ~200 refused assets rendered as a
+   * status bar reading `synced` and a person seeing broken images with no
+   * cause anywhere but a terminal they never open. Same disease `held` was
+   * added to cure, one lane over.
+   */
+  failed?: number;
+  /**
+   * The hub asked us to slow down and the WHOLE LANE is paused until `until`.
+   *
+   * Distinguished from `failed` because the answer is different: nothing is
+   * wrong, nothing is lost, and there is nothing to do but wait — which is
+   * exactly what a person cannot infer from a count of failures.
+   */
+  rateLimited?: { until: number; waiting: number };
   /**
    * THE DORUČENKA (DDR-226 §7) — per-path delivery state.
    *
@@ -126,6 +151,26 @@ export interface FilePlaneStatus {
    * as the thing to disagree with.
    */
   delivery?: Record<string, string>;
+  /**
+   * How many delivery rows were dropped from `delivery` by its cap.
+   *
+   * The map used to be unbounded — one entry per ledger row, so 2 961 keys for
+   * a real project, re-serialized into `_sync.json` AND broadcast over the
+   * WebSocket on EVERY status change, including 200 ms-throttled asset-progress
+   * emits. Same bounding shape `items`/`itemsTruncated` already uses.
+   */
+  deliveryTruncated?: number;
+  /**
+   * THE DENOMINATOR (feature-large-project-seed).
+   *
+   * Derived from the LEDGER rather than from per-pass results — see
+   * `seed-progress.ts` for why the per-pass counters read zero for twenty
+   * minutes while 2 961 rows changed underneath them. The raw counters above
+   * stay beside it deliberately: a panel derived from the same source it
+   * displays cannot be cross-checked, and DDR-214's lesson is that a status
+   * surface has to be falsifiable.
+   */
+  progress?: SeedProgress;
 }
 
 export interface SyncStatusStoreOptions {
@@ -139,6 +184,8 @@ export interface SyncStatusStoreOptions {
   broadcast?: (payload: SyncStatusPayload) => void;
   /** Max conflict notifications retained. Default 20. */
   maxConflicts?: number;
+  /** Floor between two writes/broadcasts. 0 disables coalescing (tests). */
+  flushIntervalMs?: number;
   now?: () => number;
 }
 
@@ -164,9 +211,17 @@ export interface SyncStatusStore {
 
 const DEFAULT_MAX_CONFLICTS = 20;
 
+/** Floor between two status writes/broadcasts. Matches `asset-push.ts`'s own
+ *  `PROGRESS_INTERVAL_MS` — the lane that emits fastest sets the pace. */
+export const STATUS_FLUSH_MS = 200;
+
+/** Delivery rows one payload carries, actionable-first. See `deliveryTruncated`. */
+export const MAX_DELIVERY_ROWS = 300;
+
 export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusStore {
   const now = opts.now ?? Date.now;
   const maxConflicts = opts.maxConflicts ?? DEFAULT_MAX_CONFLICTS;
+  const flushIntervalMs = opts.flushIntervalMs ?? STATUS_FLUSH_MS;
   const conflicts: SyncConflict[] = [];
 
   let snapshot: SyncStatusSnapshot = {
@@ -188,6 +243,18 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
   function payload(): SyncStatusPayload {
     return {
       ...snapshot,
+      // WHEN THIS PAYLOAD WAS BUILT, not when the connection monitor last
+      // spoke. `updatedAt` arrived here by spreading the monitor's snapshot,
+      // which only `update()` refreshes — so `updateFiles()` and
+      // `updateAssets()` flushed payloads carrying a stale timestamp ABOUT
+      // THEMSELVES. Measured at 130 s stale against a ledger that was current
+      // to within a second, on a file being rewritten continuously. A
+      // freshness stamp that lies is worse than none: it is what a person (and
+      // `maude design status`) uses to decide whether sync is alive at all.
+      updatedAt: now(),
+      // The monitor's own stamp, preserved under a name that says what it is,
+      // so nothing that depended on the old meaning silently changes meaning.
+      connectionUpdatedAt: snapshot.updatedAt,
       url: opts.url,
       canvases: opts.canvases,
       conflicts: conflicts.slice(),
@@ -198,7 +265,23 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
     };
   }
 
-  function flush(): void {
+  /**
+   * Write + broadcast, COALESCED.
+   *
+   * Every emit used to re-serialize the whole payload — including an unbounded
+   * per-path delivery map — to disk and to every open tab. During a seed the
+   * asset lane alone emits every 200 ms, and the file lane emits per pass, so
+   * the cost was paid continuously for a payload nobody could read that fast.
+   *
+   * `immediate` is not an optimisation escape hatch: conflicts, notices and
+   * terminal transitions are the events a person is waiting on, and delaying
+   * those by even a debounce window is the class of lie this file exists to
+   * avoid.
+   */
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  let pendingFlush = false;
+
+  function emit(): void {
     const p = payload();
     try {
       opts.write(p);
@@ -212,15 +295,47 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
     }
   }
 
+  function flush(immediate = false): void {
+    if (flushIntervalMs <= 0) {
+      emit();
+      return;
+    }
+    if (!immediate && flushTimer !== null) {
+      pendingFlush = true;
+      return;
+    }
+    // An immediate flush jumps the queue but still OPENS the window — without
+    // that, every urgent write was followed by a free un-coalesced one, so a
+    // conflict during a seed re-admitted the whole burst it was jumping ahead of.
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    pendingFlush = false;
+    emit();
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      // Only if something arrived while we were waiting — an idle store must
+      // not keep a timer alive forever.
+      if (pendingFlush) {
+        pendingFlush = false;
+        flush();
+      }
+    }, flushIntervalMs);
+    flushTimer.unref?.();
+  }
+
   return {
     update(next) {
+      const changed = snapshot.state !== next.state;
       snapshot = next;
-      flush();
+      // A connection state CHANGE is the headline; a heartbeat is not.
+      flush(changed);
     },
     addConflict(conflict) {
       conflicts.push({ ...conflict, at: now() });
       if (conflicts.length > maxConflicts) conflicts.splice(0, conflicts.length - maxConflicts);
-      flush();
+      flush(true);
     },
     updateAssets(progress) {
       assets = progress;
@@ -228,12 +343,14 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
     },
     updateFiles(next) {
       files = next;
-      flush();
+      // A finished or stalled seed is what a person is waiting to see; a
+      // mid-seed tick is not.
+      flush(next.progress?.phase === 'converged' || next.progress?.phase === 'blocked');
     },
     notice(next) {
       if (notices.some((n) => n.id === next.id)) return;
       notices.push({ ...next, at: now() });
-      flush();
+      flush(true);
     },
     get: payload,
   };

package/apps/studio/sync/transport-error.ts

@@ -0,0 +1,111 @@
+// What a THROWN fetch error means, in words a person can act on.
+//
+// THE BUG THIS EXISTS TO FIX. Every `catch` in `file-plane.ts` stored
+// `(err as Error).message` directly into the per-path delivery reason a person
+// reads in the Sync panel. Those messages come from Bun's runtime, not from us:
+//
+//     $ bun -e "try{await fetch('http://127.0.0.1:1/x')}catch(e){console.log(e.message)}"
+//     Unable to connect. Is the computer able to access the url?
+//
+// On 2026-09-03, 484 of 803 undelivered files in an 8.8 GB project carried
+// exactly those two Bun strings — because the cell they were being pushed to
+// was restarting in a loop. So a person looking for "why is my project not
+// syncing" was told, 135 times, to check their URL for a typo. It also cost a
+// debugging session: the strings appear nowhere in this repo, so grepping for
+// them found nothing and the reason class looked like a mystery.
+//
+// `failureReason()` in `retry-after.ts` is the sibling for RESPONSE refusals —
+// a request that arrived and was declined. This module is for the requests that
+// never arrived at all.
+
+/** What kind of transport failure this was. */
+export type TransportErrorClass = 'unreachable' | 'timeout' | 'aborted' | 'other';
+
+export interface ClassifiedTransportError {
+  class: TransportErrorClass;
+  /** What a person reads. Ours, never the runtime's. */
+  text: string;
+  /** The runtime's own words — for the console and `detail` fields ONLY. */
+  raw: string;
+}
+
+/** How much of a raw message we keep. Bounded: it reaches logs, and a hostile
+ *  peer can influence some of what a fetch throws. */
+const MAX_RAW_CHARS = 200;
+
+/**
+ * Bun's connect-failure wording, as of Bun 1.x.
+ *
+ * MATCHED AS A FALLBACK, NOT AS THE PRIMARY SIGNAL. Error *names* are stable
+ * API; these sentences are not, and a Bun upgrade that rewords them must
+ * degrade this to `other` with a neutral sentence rather than start leaking the
+ * new wording. That is why `other` has a real message of its own instead of
+ * falling through to `raw`.
+ */
+const BUN_CONNECT_HINTS = [
+  'unable to connect',
+  'was there a typo in the url or port',
+  'connectionrefused',
+  'connection refused',
+  'failed to connect',
+  'econnrefused',
+  'enotfound',
+  'eai_again',
+  'dns',
+  'socket connection was closed unexpectedly',
+];
+
+const BUN_TIMEOUT_HINTS = ['timeout', 'timed out', 'etimedout'];
+
+/**
+ * Classify a caught `fetch` rejection.
+ *
+ * Total: every input produces a class and a sentence, including a non-Error
+ * throw. A classifier that can return "nothing" would just reintroduce the
+ * `err.message` fall-through it replaces.
+ */
+export function classifyTransportError(err: unknown): ClassifiedTransportError {
+  const raw = rawTextOf(err).slice(0, MAX_RAW_CHARS);
+  const name = typeof (err as { name?: unknown })?.name === 'string' ? (err as Error).name : '';
+  const haystack = `${name} ${raw}`.toLowerCase();
+
+  // Names first — they are the stable half of the contract.
+  if (name === 'TimeoutError' || (name === 'AbortError' && haystack.includes('timeout'))) {
+    return {
+      class: 'timeout',
+      text: 'The workspace took too long to answer',
+      raw,
+    };
+  }
+  if (name === 'AbortError') {
+    return { class: 'aborted', text: 'Stopped before it finished', raw };
+  }
+  if (BUN_TIMEOUT_HINTS.some((h) => haystack.includes(h))) {
+    return { class: 'timeout', text: 'The workspace took too long to answer', raw };
+  }
+  if (BUN_CONNECT_HINTS.some((h) => haystack.includes(h))) {
+    return { class: 'unreachable', text: 'Could not reach the workspace', raw };
+  }
+  // NEUTRAL, never the raw string. An unrecognised failure is still a failure
+  // we own the wording of.
+  return { class: 'other', text: 'The transfer did not complete', raw };
+}
+
+/**
+ * The user-facing sentence alone — the common call site, since almost every
+ * `catch` wants exactly this and nothing else.
+ */
+export function transportErrorText(err: unknown): string {
+  return classifyTransportError(err).text;
+}
+
+function rawTextOf(err: unknown): string {
+  if (typeof err === 'string') return err;
+  const message = (err as { message?: unknown })?.message;
+  if (typeof message === 'string') return message;
+  try {
+    return String(err);
+  } catch {
+    return 'unknown error';
+  }
+}

package/apps/studio/whats-new.json

@@ -1,6 +1,97 @@
 {
   "$schema": "./whats-new.schema.json",
   "entries": [
+    {
+      "id": "pdf-export-print-safe-text",
+      "version": "1.2.0",
+      "date": "2026-09-04",
+      "kind": "feature",
+      "title": "PDF exports a print shop will actually accept",
+      "summary": "A colour font or a faux-italic could come out of a PDF export in a form printers reject — the file looked perfect on screen, and you only found out when the print shop refused it. Maude now checks the fonts on every PDF export and warns you, by name, when one of them would fail preflight. Under Text you can also ask it to verify the fonts are properly embedded, or convert all text to curves so there is nothing left to break — bleed, crop marks and photo resolution all come through untouched.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "seed-progress-you-can-watch",
+      "version": "1.2.0",
+      "date": "2026-09-04",
+      "kind": "improvement",
+      "title": "You can watch a large project sync",
+      "summary": "Linking a big project used to be a black box: the Sync panel counted files it had moved but never how many there were, so \"1 412\" looked the same whether it was a quarter done or finished — and `maude design status` reported only canvases, so a project with hundreds of files still on their way could read as fully synced. Now every surface shows the same thing: how many of how many have arrived, what is waiting, and what is stuck and why. The panel has a progress bar, `maude design status` has a files line (and a `--watch` mode), and the desktop app puts the count in the window title and tells you once when it finishes. Files the workspace will never take — something over its size limit, or an hourly upload allowance that is used up — now say so by name instead of retrying forever.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "images-arrive-again",
+      "version": "1.2.0",
+      "date": "2026-09-04",
+      "kind": "fix",
+      "title": "Images arrive again on linked projects",
+      "summary": "On a project synced with a workspace, images and other project files could quietly never arrive — broken placeholders on the canvas while the Sync panel still said everything was synced. When a workspace asks Maude to slow down, it now waits as long as it was asked instead of retrying straight into the same wall, and the Sync panel says so in plain words: syncing is paused for a moment, nothing is lost, the rest arrives when the pause lifts.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "comments-stop-disappearing",
+      "version": "1.2.0",
+      "date": "2026-09-04",
+      "kind": "fix",
+      "title": "Comments stop disappearing",
+      "summary": "On a project linked to a hub, a comment you had just added could vanish a few seconds later, leaving only the first one on the canvas — with nothing to undo and no sign anything had gone wrong. A new comment now reaches the shared project before it is written to disk, and Maude will not overwrite a comment it has not seen yet, so what you write stays put.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "comments-stop-duplicating",
+      "version": "1.2.0",
+      "date": "2026-09-04",
+      "kind": "fix",
+      "title": "Comments stop duplicating, and resolve works",
+      "summary": "On a project linked to a hub, a comment could come back two, four, then eight times, and clicking resolve appeared to do nothing — every copy had to be dealt with separately, and new ones kept arriving. Maude now recognises the copies as one comment, so they collapse back to a single pin, and resolving or deleting one clears all of it. A project that already filled up with duplicates repairs itself the next time you open it.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "synced-canvases-stop-duplicating",
+      "version": "1.2.0",
+      "date": "2026-09-04",
+      "kind": "fix",
+      "title": "Synced canvases stop duplicating themselves",
+      "summary": "On a project linked to a hub, a canvas could come back with its whole contents pasted onto itself — twice, sometimes more — which broke the build and left the canvas unopenable. It happened when two people (or your machine and the hub) first picked up the same canvas at the same moment. Maude now recognises that exact shape and collapses it back to one copy, on the styles as well as the body. Moving a canvas into another folder also fixes up its imports instead of breaking them.",
+      "surface": "design-ui"
+    },
+    {
+      "date": "2026-09-04",
+      "id": "sync-recovers-after-the-workspace-sleeps",
+      "kind": "fix",
+      "summary": "If you left Maude alone for a while, your cloud workspace went to sleep and syncing quietly stopped — the indicator still said it was connected, and only pressing Resync got it moving again. Maude now notices when the connection has gone quiet, brings it back on its own, and only reports canvases as synced once they really are.",
+      "surface": "design-ui",
+      "title": "Sync comes back on its own",
+      "version": "1.2.0"
+    },
+    {
+      "date": "2026-09-04",
+      "id": "long-chats-no-longer-freeze",
+      "kind": "fix",
+      "summary": "In a project with a long chat history, Maude could slow to a crawl and stop responding for many minutes while using enormous amounts of memory — often needing a force-quit. Screenshots the agent took were being stored inside the chat history at full size, and every chat you opened re-read all of it. Chats now stay small and are read in fixed-size pieces, so a long history costs the same as a short one.",
+      "surface": "design-ui",
+      "title": "Long chats no longer freeze Maude",
+      "version": "1.2.0"
+    },
+    {
+      "id": "canvas-media-plays-on-linux",
+      "version": "1.0.10",
+      "date": "2026-08-26",
+      "kind": "fix",
+      "title": "Canvas video and audio work on Linux",
+      "summary": "Opening a canvas with video or audio on Linux could take the whole view down with no message — once because the GStreamer plugins it needs are optional on most distros, and again because the GPU video path faults on AMD graphics. The .deb now pulls those plugins in, Maude steers around the AMD fault by itself, and if the plugins are missing anyway it tells you, with the exact install command for your distro.",
+      "learnMore": "https://maude.sh/docs/desktop#media-playback-on-linux",
+      "surface": "design-ui"
+    },
+    {
+      "id": "a-stopped-server-says-so",
+      "version": "1.0.10",
+      "date": "2026-08-26",
+      "kind": "fix",
+      "title": "A stopped server now says so",
+      "summary": "If the server behind your project stopped for good, Maude used to leave the window sitting there — nothing loading, nothing saving, and no reason given. Now it tells you which project stopped, confirms your files on disk are untouched, and offers Try again. A one-off crash hours into a session also no longer counts against the give-up limit the way a genuine restart loop does.",
+      "surface": "design-ui"
+    },
     {
       "id": "exports-match-what-you-see",
       "version": "1.0.8",

package/cli/bin/maude.mjs

@@ -14,6 +14,7 @@ const COMMANDS = {
   init: () => import('../commands/init.mjs'),
   config: () => import('../commands/config.mjs'),
   cache: () => import('../commands/cache.mjs'),
+  codex: () => import('../commands/codex.mjs'),
   preflight: () => import('../commands/preflight.mjs'),
   design: () => import('../commands/design.mjs'),
   'scenario-report': () => import('../commands/scenario-report.mjs'),
@@ -21,6 +22,7 @@ const COMMANDS = {
   kg: () => import('../commands/kg.mjs'),
   help: () => import('../commands/help.mjs'),
   hub: () => import('../commands/hub.mjs'),
+  harness: () => import('../commands/harness.mjs'),
   version: () => import('../commands/version.mjs'),
 };
 

package/cli/commands/codex.mjs

@@ -0,0 +1,191 @@
+import { spawnSync } from 'node:child_process';
+import { access, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { delimiter, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+import { parseArgs } from '../lib/argv.mjs';
+import { assertCodexPermissionAuthority, syncCodexRuntime } from '../lib/harness/codex-runtime.mjs';
+
+export async function run({ args, io = defaultIo() }) {
+  const syncOnly = args[0] === 'sync';
+  const { flags } = syncOnly ? parseArgs(args.slice(1), { booleans: ['json'] }) : { flags: {} };
+  const launchArgs = [...args];
+  if (!syncOnly) assertLocalCodexTarget(launchArgs);
+  let explicitExecutable = flags.real;
+  if (!syncOnly && launchArgs[0] === '--real') {
+    if (!launchArgs[1]) throw new Error('--real requires an executable path');
+    explicitExecutable = launchArgs[1];
+    launchArgs.splice(0, 2);
+  }
+  if (process.env.MAUDE_CODEX_BRIDGE_ACTIVE === '1') {
+    throw new Error(
+      'refusing recursive maude codex launch; set MAUDE_CODEX_REAL to the real binary'
+    );
+  }
+  process.env.MAUDE_CODEX_BRIDGE_ACTIVE = '1';
+  const home = resolve(process.env.HOME || homedir());
+  const projectRoot = await realpath(
+    resolve(flags.project || codexProjectDirectory(launchArgs) || process.cwd())
+  );
+  const requestedCodexHome = resolve(process.env.CODEX_HOME || join(home, '.codex'));
+  if (isContained(requestedCodexHome, projectRoot)) {
+    throw new Error('CODEX_HOME must be outside the current project for maude codex');
+  }
+  const codexHome = await realpath(requestedCodexHome);
+  if (isContained(codexHome, projectRoot)) {
+    throw new Error('CODEX_HOME must resolve outside the current project for maude codex');
+  }
+  const executable = await resolveCodexExecutable(explicitExecutable);
+  const synced = await syncCodexRuntime({
+    codexExecutable: executable,
+    codexHome,
+    home,
+    projectRoot,
+  });
+  if (syncOnly) {
+    if (flags.json) io.stdout.write(`${JSON.stringify(synced.summary, null, 2)}\n`);
+    return synced.summary;
+  }
+  if (synced.permissionMode && hasCodexPermissionOverride(launchArgs)) {
+    throw new Error('refusing a Codex sandbox override that could disable projected Claude denies');
+  }
+  const canonicalLaunchArgs = canonicalizeCodexProjectArguments(launchArgs, projectRoot);
+  if (synced.permissionMode) {
+    await assertCodexPermissionAuthority({ codexHome, projectRoot });
+  }
+  const result = spawnSync(executable, [...synced.launchArguments, ...canonicalLaunchArgs], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      ...synced.launchEnvironment,
+      CODEX_HOME: codexHome,
+      MAUDE_CODEX_BRIDGE_ACTIVE: process.env.MAUDE_CODEX_BRIDGE_ACTIVE,
+    },
+    stdio: 'inherit',
+  });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+  return { ...synced.summary, exitCode: process.exitCode };
+}
+
+export function codexProjectDirectory(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--') return null;
+    if (argument === '-C' || argument === '--cd') return args[index + 1] ?? null;
+    if (argument.startsWith('-C')) return argument.slice(2) || null;
+    if (argument.startsWith('--cd=')) return argument.slice('--cd='.length) || null;
+  }
+  return null;
+}
+
+export function hasCodexRemoteTarget(args) {
+  for (const argument of args) {
+    if (argument === '--') return false;
+    if (argument === '--remote' || argument.startsWith('--remote=')) return true;
+    if (argument === 'cloud') return true;
+  }
+  return false;
+}
+
+export function assertLocalCodexTarget(args) {
+  if (hasCodexRemoteTarget(args)) {
+    throw new Error('refusing to synchronize local Claude state into a remote Codex session');
+  }
+}
+
+export function canonicalizeCodexProjectArguments(args, projectRoot) {
+  const output = [];
+  let found = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--')
+      return [...(found ? ['-C', projectRoot] : []), ...output, ...args.slice(index)];
+    if (argument === '-C' || argument === '--cd') {
+      if (found) throw new Error('multiple Codex working-directory overrides are not supported');
+      if (args[index + 1] === undefined) throw new Error(`${argument} requires a directory`);
+      found = true;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith('-C')) {
+      if (found) throw new Error('multiple Codex working-directory overrides are not supported');
+      if (!argument.slice(2)) throw new Error('-C requires a directory');
+      found = true;
+      continue;
+    }
+    if (argument.startsWith('--cd=')) {
+      if (found) throw new Error('multiple Codex working-directory overrides are not supported');
+      if (!argument.slice('--cd='.length)) throw new Error('--cd requires a directory');
+      found = true;
+      continue;
+    }
+    output.push(argument);
+  }
+  return [...(found ? ['-C', projectRoot] : []), ...output];
+}
+
+export function hasCodexPermissionOverride(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--') return false;
+    if (
+      argument === '-s' ||
+      /^-s.+/.test(argument) ||
+      argument === '--sandbox' ||
+      argument.startsWith('--sandbox=') ||
+      argument === '--dangerously-bypass-approvals-and-sandbox' ||
+      argument === '--yolo' ||
+      argument === '--approve-for-me' ||
+      argument === '-p' ||
+      /^-p.+/.test(argument) ||
+      argument === '--profile' ||
+      argument.startsWith('--profile=') ||
+      argument === '-P' ||
+      /^-P.+/.test(argument) ||
+      argument === '--permission-profile' ||
+      argument.startsWith('--permission-profile=')
+    ) {
+      return true;
+    }
+    if (
+      argument === '-c' ||
+      /^-c.+/.test(argument) ||
+      argument === '--config' ||
+      argument.startsWith('--config=')
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isContained(path, root) {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+
+async function resolveCodexExecutable(explicit) {
+  if (explicit) return await canonicalExecutable(explicit);
+  if (process.env.MAUDE_CODEX_REAL) return await canonicalExecutable(process.env.MAUDE_CODEX_REAL);
+  for (const root of String(process.env.PATH || '').split(delimiter)) {
+    if (!root) continue;
+    const candidate = join(root, 'codex');
+    try {
+      await access(candidate);
+      return await realpath(candidate);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  throw new Error('Codex executable not found; pass --real <path>');
+}
+
+async function canonicalExecutable(path) {
+  await access(path);
+  return await realpath(path);
+}
+
+function defaultIo() {
+  return { stderr: process.stderr, stdout: process.stdout };
+}