agentbox-app 0.1.11 → 0.1.13

package/main/engine-setup.mjs

@@ -1,3 +1,4 @@
+import { harnessFor } from './harnesses.mjs';
 // SETTING UP SOMEBODY'S PLAN FOR THEM (w-9f6975906c, picked 2026-10-05).
 //
 // A person with a Claude or ChatGPT plan and no Claude Code or Codex used to
@@ -23,29 +24,18 @@
 
 import { spawn as nodeSpawn } from 'node:child_process';
 import { terminalEnv } from './task-terminals.mjs';
+import { codexLaunchEnv } from './codex-launch-env.mjs';
 
-const INSTALLERS = {
-  claude: { shell: '/bin/bash', url: 'https://claude.ai/install.sh', pipe: 'bash' },
-  codex: { shell: '/bin/sh', url: 'https://chatgpt.com/codex/install.sh', pipe: 'sh' },
-};
-
-export function installCommand(engine) {
-  const i = INSTALLERS[engine];
-  return { file: i.shell, args: ['-c', `curl -fsSL ${i.url} | ${i.pipe}`] };
-}
+export function installCommand(engine) { return harnessFor(engine).install(); }
 
 /** The plan, never the API console: `--claudeai` is Claude Code's own name for it. */
 export function signInCommand(engine, bin) {
-  return engine === 'claude'
-    ? { file: bin, args: ['auth', 'login', '--claudeai'] }
-    : { file: bin, args: ['login'] };
+  return harnessFor(engine).signIn(bin);
 }
 
 /** Exit 0 is signed in and 1 is not, for both (measured 2026-10-05). */
 export function statusCommand(engine, bin) {
-  return engine === 'claude'
-    ? { file: bin, args: ['auth', 'status', '--json'] }
-    : { file: bin, args: ['login', 'status'] };
+  return harnessFor(engine).signInStatus(bin);
 }
 
 const LOG_LIMIT = 64 * 1024;
@@ -57,7 +47,8 @@ function realSpawn(file, args, { env, onData, keepStdin = false } = {}) {
   let child;
   try {
     child = nodeSpawn(file, args, { env, stdio: [keepStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
-  } catch {
+  } catch (error) {
+    onData?.(`${error.message}\n`);
     return { exit: Promise.resolve(127), kill() {} };
   }
   const feed = (d) => onData?.(String(d));
@@ -65,7 +56,7 @@ function realSpawn(file, args, { env, onData, keepStdin = false } = {}) {
   child.stderr?.on('data', feed);
   const exit = new Promise((resolve) => {
     child.on('exit', (code) => resolve(code ?? 1));
-    child.on('error', () => resolve(127));
+    child.on('error', (error) => { onData?.(`${error.message}\n`); resolve(127); });
   });
   return { exit, kill: () => { try { child.kill('SIGTERM'); } catch { /* already gone */ } } };
 }
@@ -82,6 +73,7 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
  */
 export function createEngineSetup({ find, spawn = realSpawn, wait = sleep, env = process.env, poll = POLL, onSignIn = () => {} } = {}) {
   const runEnv = terminalEnv(env);
+  const toolEnv = (engine, bin) => engine === 'codex' ? codexLaunchEnv(bin, runEnv) : runEnv;
   const jobs = new Map();
 
   const fresh = (engine) => ({ engine, phase: 'idle', error: null, log: '', running: null, login: null, run: 0 });
@@ -91,20 +83,26 @@ export function createEngineSetup({ find, spawn = realSpawn, wait = sleep, env =
 
   async function signedIn(j, bin) {
     const { file, args } = statusCommand(j.engine, bin);
-    const p = spawn(file, args, { env: runEnv });
+    let output = '';
+    const p = spawn(file, args, { env: toolEnv(j.engine, bin), onData: (d) => { output = (output + String(d).replace(ANSI, '')).slice(-LOG_LIMIT); } });
     const TIMED_OUT = Symbol('no answer');
     const code = await Promise.race([p.exit, wait(STATUS_TIMEOUT).then(() => { p.kill(); return TIMED_OUT; })]);
     // TOLD TO THE APP, which routes on it (w-d5d632e503): a Claude Code that
     // is signed out beside a Codex that is signed in is a Mac that runs on
     // Codex. Only a real yes or no; a check that never answered says nothing.
     if (code === 0 || code === 1) onSignIn(j.engine, code === 0);
-    return code === 0;
+    if (code === 0 || code === 1) return code === 0;
+    if (output) say(j, output);
+    const name = j.engine === 'codex' ? 'Codex' : 'Claude Code';
+    throw new Error(code === TIMED_OUT
+      ? `${name} did not answer the sign-in check. Try again.`
+      : `${name} could not check sign-in: ${lastLine(output) || `exit ${code}`}`);
   }
 
   function startLogin(j, bin) {
     j.login?.kill();
     const { file, args } = signInCommand(j.engine, bin);
-    const login = spawn(file, args, { env: runEnv, keepStdin: true, onData: (d) => say(j, d) });
+    const login = spawn(file, args, { env: toolEnv(j.engine, bin), keepStdin: true, onData: (d) => say(j, d) });
     j.login = login;
     return login;
   }
@@ -130,18 +128,19 @@ export function createEngineSetup({ find, spawn = realSpawn, wait = sleep, env =
     if (!live()) return;
     j.phase = 'signing-in';
     let login = startLogin(j, hit.path);
-    let gaveUp = false;
-    login.exit.then((code) => { if (login === j.login && code !== 0) gaveUp = true; });
+    let ended = false;
+    const watchLogin = (loginProcess) => loginProcess.exit.then(() => { if (loginProcess === j.login) ended = true; });
+    watchLogin(login);
     for (;;) {
       await wait(poll);
       if (!live()) return;
       if (await signedIn(j, hit.path)) { if (live()) ready(j); return; }
       if (j.login !== login) {
         login = j.login;
-        gaveUp = false;
-        login.exit.then((code) => { if (login === j.login && code !== 0) gaveUp = true; });
+        ended = false;
+        watchLogin(login);
       }
-      if (gaveUp) return fail(j, 'The sign-in was closed before it finished.');
+      if (ended) return fail(j, `The sign-in was closed before it finished.${lastLine(j.log) ? ` ${lastLine(j.log)}` : ''}`);
     }
   }
 
@@ -182,12 +181,13 @@ export function createEngineSetup({ find, spawn = realSpawn, wait = sleep, env =
     async readiness(engine) {
       const hit = find(engine);
       if (!hit?.found) return { engine, found: false, signedIn: false };
-      return { engine, found: true, signedIn: await signedIn({ engine }, hit.path) };
+      try { return { engine, found: true, signedIn: await signedIn({ engine, log: '' }, hit.path) }; }
+      catch (error) { return { engine, found: true, signedIn: false, error: error.message }; }
     },
     /** The same question against a path already found, so asking it at
      *  launch does not search the Mac again. */
     signedInNow(engine, bin) {
-      return signedIn({ engine }, bin);
+      return signedIn({ engine, log: '' }, bin).catch(() => false);
     },
   };
 }

package/main/feedback.mjs

@@ -5,10 +5,13 @@
 // to as a secret (`FEEDBACK_TO`, cloud/supabase/functions/feedback), so the
 // address is in no file of this public repository and no install can show it.
 //
-// WHERE IT GOES IS BAKED IN, like the analytics key (main/analytics.mjs): the
-// release writes `bakedFeedbackUrl` into the packaged package.json, a copy run
-// from source carries none, and a `feedbackUrl` in zero.config.json outranks
-// both. A copy with nowhere to send says so in words rather than pretending.
+// WHERE IT GOES SHIPS IN THE CODE (w-58e758c81e, 2026-10-09). It used to be
+// baked only into the packaged Mac app, so the npm package and a git clone,
+// the two installs the README offers, told everyone who pressed Send that
+// feedback was not set up, and lost what they wrote. FEEDBACK_ADDRESS is the
+// server function, not an inbox. A `feedbackUrl` in zero.config.json, the
+// FEEDBACK_URL variable, or a `bakedFeedbackUrl` in a packaged package.json
+// still outrank it.
 //
 // It is not behind the diagnostics switch. That switch is about what Agentbox
 // sends on its own; this is something a person typed and pressed Send on.
@@ -16,11 +19,13 @@ import { createRequire } from 'node:module';
 import { checkFeedback } from '../shared/feedback.mjs';
 import { Name, readEnv } from '../shared/product-name.mjs';
 
+export const FEEDBACK_ADDRESS = 'https://lywvthwkhkfzhqivvond.supabase.co/functions/v1/feedback';
+
 function bakedUrl() {
   try {
-    return createRequire(import.meta.url)('../package.json')?.bakedFeedbackUrl ?? null;
+    return createRequire(import.meta.url)('../package.json')?.bakedFeedbackUrl ?? FEEDBACK_ADDRESS;
   } catch {
-    return null;
+    return FEEDBACK_ADDRESS;
   }
 }
 

package/main/fresh-user.mjs

@@ -96,7 +96,7 @@ export function openFreshUser({
   const notes = [];
   if (withTools && !prepared.claudeBin) notes.push('Claude Code is not at ~/.local/bin/claude, so agents will not run in it.');
   if (!prepared.keychain) notes.push('There is no ~/Library/Keychains here, so Claude Code will say it is not logged in.');
-  if (withAgents && !prepared.agents) notes.push('There is no ~/.claude on this Mac, so it will have no agents to offer.');
+  if (withAgents && !prepared.agents) notes.push('There is no ~/.claude on this computer, so it will have no agents to offer.');
 
   return { ok: true, home: prepared.home, agents: prepared.agents, notes, pid: child?.pid ?? null };
 }

package/main/git-change.mjs

@@ -42,7 +42,10 @@ const MAX_ROWS_PER_FILE = 20_000;
 const NOT_CODE = /(^|\/)(node_modules|\.git)\//;
 
 function git(cwd, args, { maxBuffer = 64 * 1024 * 1024 } = {}) {
-  return execFileSync('git', ['--no-pager', ...args], {
+  // A user's `diff.mnemonicPrefix` rewrites a/ and b/ into c/ i/ o/ w/.
+  // The reader below only knows one prefix. Turn the setting off for this
+  // process so a checkout reads the same on every machine.
+  return execFileSync('git', ['--no-pager', '-c', 'diff.mnemonicPrefix=false', ...args], {
     cwd,
     encoding: 'utf8',
     maxBuffer,
@@ -189,7 +192,10 @@ export function filesFromPatch(patch) {
   const nameOn = (line, side) => {
     const name = line.slice(4).trim();
     if (name === '/dev/null') return null;
-    return name.replace(side === 'old' ? /^a\// : /^b\//, '');
+    // a/ and b/ are the ordinary prefixes. c/ i/ o/ w/ are mnemonicPrefix,
+    // and 1/ 2/ are `git diff --no-index` under that same setting. One
+    // prefix comes off; a file that is itself named `b/foo` stays `b/foo`.
+    return name.replace(/^[abiowc12]\//, '');
   };
   for (const line of String(patch ?? '').split('\n')) {
     if (line.startsWith('diff --git ')) { closeHunk(); file = null; oldName = null; continue; }

package/main/harnesses/claude-stream.mjs

@@ -0,0 +1,208 @@
+import { hookFailure } from '../../shared/hook-failure.mjs';
+import { SAYING_CAP } from '../codex.mjs';
+
+// The stream's own metadata, kept on the session object: the session id (what
+// a personal reply resumes) and the final result message (what the founder
+// reads). Recorded for every session because it is one parse we are already
+// paying for; acted on where someone needs it.
+export function captureStream(session, line) {
+  try {
+    const obj = JSON.parse(line);
+    if (obj.session_id) session.sessionId = obj.session_id;
+    if (obj.type === 'result') {
+      session.result = String(obj.result ?? '');
+      session.resultIsError = !!obj.is_error;
+      // A run cannot end with helpers still out. Cleared here as well as on
+      // exit so the number can never outlive the thing it counts. Unless
+      // something is still out in the background: then this was a turn
+      // ending, not the run, and the session stays open for it.
+      if (!session.child?.waitingOn?.().length) session.helperIds?.clear();
+    }
+    noteClaimAnswer(session, obj);
+    countHelpers(session, obj);
+  } catch {}
+}
+
+// Whether this run was refused its own row, off the claim call and its reply.
+// `closingMessageIsTheAnswer` reads it: a refused worker is told to end saying
+// nothing, and whatever it does say must not land on a row someone else holds.
+// A later claim that succeeds clears it.
+function noteClaimAnswer(session, obj) {
+  const blocks = Array.isArray(obj?.message?.content) ? obj.message.content : [];
+  for (const b of blocks) {
+    if (obj.type === 'assistant' && b?.type === 'tool_use' && /claim_work_item$/.test(b.name ?? '')
+      && (!b.input?.id || b.input.id === session.itemId)) {
+      (session.claimCalls ??= new Set()).add(b.id);
+    }
+    if (obj.type === 'user' && b?.type === 'tool_result' && session.claimCalls?.has(b.tool_use_id)) {
+      const text = typeof b.content === 'string' ? b.content
+        : (b.content ?? []).map((c) => c?.text ?? '').join('');
+      if (/"claimed"\s*:\s*false/.test(text)) session.claimRefused = true;
+      else if (/"claimed"\s*:\s*true/.test(text)) session.claimRefused = false;
+    }
+  }
+}
+
+/**
+ * `--include-partial-messages` puts `stream_event` frames on the same stdout
+ * the finished messages come down. This keeps the CURRENT text block on the
+ * session as it grows, and nothing else: no thinking, no tool arguments, and
+ * nothing written to disk. It dies with the process, exactly like `tail`.
+ *
+ * ONE BLOCK AT A TIME, AND THAT IS THE POINT. A finished message becomes ONE
+ * trace line per text block (`traceStreamLine`), so holding exactly one block
+ * here means the live string and the traced string are the same string, and
+ * the thread can drop the live copy the moment the traced one arrives without
+ * guessing (`itemThread`, renderer/src/item-thread.ts).
+ *
+ * IT IS NOT CLEARED WHEN THE MESSAGE FINISHES, and that is deliberate. The
+ * trace is written on one channel and read on another, so clearing it here
+ * would blink the sentence off her screen for however long the read takes and
+ * then put it back. The renderer suppresses it the moment the thread has it,
+ * which is a comparison rather than a race.
+ *
+ * Returns true when the string moved, which is what earns a push.
+ */
+export function streamingText(session, line) {
+  try {
+    const obj = JSON.parse(line);
+    if (obj.type !== 'stream_event') return false;
+    const event = obj.event ?? {};
+    // A new message. Whatever the last one ended on is the last one's, and the
+    // trace has it by now.
+    if (event.type === 'message_start') {
+      session.saying = '';
+      session.sayingAt = 0;
+      return true;
+    }
+    if (event.type === 'content_block_start') {
+      // Only a text block resets it. A tool call or a thought starting means
+      // this message has moved on from prose, and the block already typed
+      // stays on screen until the trace delivers the same words.
+      if (event.content_block?.type !== 'text') return false;
+      session.saying = '';
+      session.sayingAt = Date.now();
+      return true;
+    }
+    if (event.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
+      const piece = String(event.delta.text ?? '');
+      if (!piece) return false;
+      if (!session.sayingAt) session.sayingAt = Date.now();
+      const next = (session.saying ?? '') + piece;
+      // Past the cap this stops being a sentence she is reading. Dropped
+      // rather than cut, because a cut string never matches the traced one and
+      // would sit under it on her screen forever.
+      session.saying = next.length > SAYING_CAP ? '' : next;
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// HOW MANY HELPERS THIS SESSION HAS OUT RIGHT NOW.
+//
+// THE ONLY TWO EVENTS THAT MATTER, and they bracket a helper exactly. Measured
+// on Claude Code 2.1.246 over a real four-helper run (the probe is written up
+// in decisions.md, 08-26): `task_started` carries a fresh `task_id`, and
+// `task_updated` carries a `patch.status` of `completed` for that same id. Four
+// starts, four completions, no id seen twice and none left open. So a set of
+// live ids, and its size is the number.
+//
+// A SET AND NOT A COUNTER, because a counter cannot survive a duplicate: the
+// stream is read line by line off a pipe, and one repeated line would leave the
+// page saying five helpers are working for the rest of the run with nothing
+// able to correct it. Adding an id twice is free.
+//
+// NESTED HELPERS ARE COUNTED THE SAME. `spawn_depth` says how deep a helper
+// sits, and this deliberately ignores it: a helper's helper is still a
+// subagent working on her task.
+//
+// THE LEAD IS NOT IN THIS NUMBER AND NEVER HAS BEEN, which is what the line
+// drawn off it was getting wrong until 2026-08-27. Only a `task_started` id is
+// ever added, and the lead has no `task_started` of its own.It is, so
+// `shortWord` in renderer/src/live-line.ts now says Subagents, unhyphenated on
+// her call of 2026-08-27 and on a count of the spelling in the Claude Code
+// build she runs. If this ever starts counting the lead as well, that word has
+// to move with it. DID THIS RUN LEAVE HER ANYTHING TO READ?
+//
+// The rule that divides the two writers, kept in one named place because
+// getting it wrong is silence, and silence is the failure that matters most:
+//
+//   - said nothing at all   -> the supervisor speaks for it (sayTheRunDied)
+//   - said something wrong  -> the supervisor speaks for it, in OUR words
+//   - said something real   -> it speaks for itself, untouched
+//
+// The middle line is the one that was missing. Both writers used to exclude an
+// error result: `speaksForTheSession` because raw CLI text must never reach her
+// row, and this one because it only looked for a result that was absent. Each
+// was right on its own and together they left the case that matters most with
+// no writer at all.
+export function saidNothingSheCanUse(session) {
+  return session?.result == null || !!session.resultIsError;
+}
+
+export function countHelpers(session, obj) {
+  if (obj?.type !== 'system') return;
+  if (obj.subtype === 'task_started' && obj.task_id) {
+    (session.helperIds ??= new Set()).add(obj.task_id);
+  } else if (obj.subtype === 'task_updated' && obj.task_id) {
+    // Anything that is not still running ends it. The measured value is
+    // `completed`, and a helper that fails or is cancelled has equally stopped
+    // working, so the test is what it is NOT rather than a list of endings we
+    // would have to keep in step with the CLI.
+    const status = obj.patch?.status;
+    if (status && status !== 'in_progress' && status !== 'running') session.helperIds?.delete(obj.task_id);
+  }
+}
+
+// The persisted trace line: fuller than the tail. Tool calls carry their key
+// input (the file written, the command run), because "tool: Bash" answers
+// nothing when the founder asks what a session actually did.
+export function traceStreamLine(line) {
+  try {
+    const obj = JSON.parse(line);
+    const at = new Date().toISOString().slice(11, 19);
+    const hook = hookFailure(obj);
+    if (hook) return `${at}  ${hook}`;
+    if (obj.type === 'assistant' && obj.message?.content) {
+      const parts = [];
+      for (const c of obj.message.content) {
+        if (c.type === 'text' && c.text?.trim()) parts.push(c.text.trim());
+        if (c.type === 'tool_use') {
+          const input = c.input ?? {};
+          const hint = input.file_path ?? input.path ?? input.command ?? input.title ?? input.description ?? input.id ?? '';
+          parts.push(`[${c.name}] ${String(hint).slice(0, 200)}`);
+        }
+      }
+      return parts.length ? parts.map((p) => `${at}  ${p}`).join('\n') : null;
+    }
+    if (obj.type === 'result') {
+      const flavor = `${obj.subtype ?? 'ok'}${obj.is_error ? ' ERROR' : ''} · ${obj.num_turns ?? '?'} turns`;
+      return `\n${at}  == RESULT (${flavor}) ==\n${String(obj.result ?? '').slice(0, 4000)}`;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// Stream-json lines are verbose; the In Progress tail wants the gist.
+export function summarizeStreamLine(line) {
+  try {
+    const obj = JSON.parse(line);
+    const hook = hookFailure(obj);
+    if (hook) return hook;
+    if (obj.type === 'assistant' && obj.message?.content) {
+      const text = obj.message.content.filter((c) => c.type === 'text').map((c) => c.text).join(' ');
+      const tools = obj.message.content.filter((c) => c.type === 'tool_use').map((c) => c.name);
+      if (tools.length) return `tool: ${tools.join(', ')}`;
+      if (text) return text.slice(0, 300);
+    }
+    if (obj.type === 'result') return `done: ${String(obj.result ?? '').slice(0, 200)}`;
+    return null;
+  } catch {
+    return line.slice(0, 200);
+  }
+}

package/main/harnesses/claude.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { harnessDefinition } from '../../shared/harness-definitions.mjs';
+import { EFFORT_LEVELS } from '../../shared/effort-levels.mjs';
+import { storeRootEnv } from '../store/home.mjs';
+import { resolveClaudeBin } from '../claude-bin.mjs';
+import { claudeModelRows } from '../claude-models.mjs';
+import { linkAccountTooling } from '../account-tooling.mjs';
+import { streamInputArgs, attachClaudeInput } from '../claude-input.mjs';
+import { claudeLaunchEnv } from '../claude-launch-env.mjs';
+import { claudeActivity } from '../agent-activity.mjs';
+import { captureStream, streamingText, summarizeStreamLine, traceStreamLine } from './claude-stream.mjs';
+import { definitionMethods, commonUpdatePlan } from './common.mjs';
+const definition = harnessDefinition('claude');
+
+export const claudeHarness = {
+  ...definitionMethods(definition),
+  discover: resolveClaudeBin,
+  launchEnv: claudeLaunchEnv,
+  models: ({ bin } = {}) => claudeModelRows({ bin: bin ?? null }).map(m => ({ id: m.alias, label: m.label })),
+  defaultModel: () => null,
+  workspaceModel: () => null,
+  profileHome: () => null,
+  effortLevels: () => EFFORT_LEVELS.map(e => e.id),
+  profiles: sup => sup._profiles(),
+  signedIn: () => true,
+  profileEnv: (env, profile) => profile === 'default' ? env : { ...env, [definition.homeEnv]: profile },
+  signInFiles({ folder, home }) {
+    if (folder) return definition.credentialFiles.map(file => path.join(folder, file));
+    const dir = path.join(home, '.claude');
+    return [path.join(home, '.claude.json'), ...definition.credentialFiles.map(file => path.join(dir, file))];
+  },
+  tooling: profile => linkAccountTooling(profile),
+  spawn(sup, plan, { cwd, item, profile, env }) {
+    // The binary is the one this definition names, not a field spelled out
+    // here: that is the last place an engine of this family needed code.
+    return spawn(sup.config[definition.binKey], streamInputArgs(definition.run, plan.args), {
+      cwd,
+      env: { ...claudeLaunchEnv(sup.config[definition.binKey], env), STORE_ACCOUNT_ID: sup.config.accountId, ...storeRootEnv(sup.config.storeRoot),
+        ...(profile !== 'default' ? { [definition.homeEnv]: profile } : {}),
+        ZERO_PRODUCT: item.product, ZERO_ITEM: item.id, ...sup.memoryGateEnv(item) },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  },
+  readers: () => ({ capture: captureStream, stream: streamingText, summarize: summarizeStreamLine, trace: traceStreamLine, activity: claudeActivity }),
+  subscribe(child, _session, absorb) {
+    let buffer = '';
+    child.stdout.on('data', data => {
+      buffer += data.toString();
+      let index;
+      while ((index = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+        if (line.trim()) absorb(line);
+      }
+    });
+  },
+  attachInput: child => attachClaudeInput(child),
+  transcript(sup, rec) {
+    if (!rec?.sessionId) return null;
+    const home = rec.profile && rec.profile !== 'default' ? rec.profile : path.join(os.homedir(), '.claude');
+    const projects = path.join(home, 'projects');
+    const slug = String(rec.cwd ?? '').replace(/[^a-zA-Z0-9]/g, '-');
+    const direct = path.join(projects, slug, `${rec.sessionId}.jsonl`);
+    if (fs.existsSync(direct)) return direct;
+    try { for (const dir of fs.readdirSync(projects)) {
+      const file = path.join(projects, dir, `${rec.sessionId}.jsonl`);
+      if (fs.existsSync(file)) return file;
+    } } catch {}
+    return null;
+  },
+  change: () => null,
+  release: () => {},
+  memoryGate: (sup, item) => sup.memoryGateEnv(item),
+  smallModelArgs: (prompt, model) => ['-p', prompt, '--model', model],
+  updateSettings: ({ home }) => {
+    try { return JSON.parse(fs.readFileSync(path.join(process.env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'), 'settings.json'), 'utf8')); }
+    catch { return {}; }
+  },
+  updatePlan: options => commonUpdatePlan(definition, options, ({ bin, real, home, channel, name }) =>
+    real.startsWith(path.join(home, '.local/share/claude/versions') + '/')
+      ? { name, file: bin, args: ['update'], feed: `https://downloads.claude.ai/claude-code-releases/${channel}`, format: 'text' } : null),
+};

package/main/harnesses/codex.mjs

@@ -0,0 +1,65 @@
+import path from 'node:path';
+import { harnessDefinition } from '../../shared/harness-definitions.mjs';
+import { resolveCodexBin } from '../codex-bin.mjs';
+import { codexLaunchEnv } from '../codex-launch-env.mjs';
+import { codexModels, codexDefaultModel, codexModelLevels } from '../codex-models.mjs';
+import { codexTranscriptFile, workerThreadParams } from '../codex-session.mjs';
+import { compactCodexThread } from '../codex-compaction.mjs';
+import { captureCodexEvent, codexStreamingText, summarizeCodexEvent, traceCodexEvent, rememberCodexChange, changeFromCodexTurn } from '../codex.mjs';
+import { codexActivity } from '../agent-activity.mjs';
+import { runCodexCommand } from '../provider-commands.mjs';
+import { definitionMethods, commonUpdatePlan } from './common.mjs';
+const definition = harnessDefinition('codex');
+
+export const codexHarness = {
+  ...definitionMethods(definition),
+  discover: resolveCodexBin,
+  launchEnv: codexLaunchEnv,
+  models: (options = {}) => codexModels(options),
+  defaultModel: (options = {}) => codexDefaultModel(options),
+  workspaceModel: sup => sup._codexWorkspaceModel(),
+  profileHome: (sup, profile) => sup._codexProfileHome(profile),
+  effortLevels: (model, options = {}) => codexModelLevels(model, options),
+  profiles: sup => sup._codexProfiles(),
+  signedIn: (sup, profile) => sup._codexSignedIn(profile),
+  profileEnv: (env, profile, sup) => ({ ...env, [definition.homeEnv]: sup._codexProfileHome(profile) }),
+  tooling: () => null,
+  // Codex carries the person's standing instructions as a thread's
+  // `developerInstructions`, so it needs neither a flag nor a file. It says so
+  // rather than inheriting the refusal meant for an engine that has nowhere to
+  // put them (main/harnesses/instructions-file.mjs).
+  instructions: () => ({ by: 'thread' }),
+  spawn: (sup, plan, context) => sup._spawnCodexWorker(plan, context),
+  readers: () => ({ capture: captureCodexEvent, stream: codexStreamingText, summarize: summarizeCodexEvent, trace: traceCodexEvent, activity: codexActivity }),
+  subscribe(child, session, absorb) {
+    child.on('event', (method, params) => { rememberCodexChange(session, method, params); absorb(method, params); });
+  },
+  attachInput: () => {},
+  transcript: (sup, rec) => rec?.sessionId ? codexTranscriptFile(rec.sessionId, { home: sup._codexProfileHome(rec.profile) }) : null,
+  change: (session, options) => changeFromCodexTurn(session.codexChange ?? [], options),
+  release: (sup, profile) => sup._releaseIdleCodex(profile),
+  usage: sup => sup.codexUsage(),
+  async compact(sup, rec, cwd) {
+    const { client, handshake } = sup._codexServer(sup._codexProfileHome(rec.profile ?? 'default'));
+    const mcpServers = await sup._codexIsolation(client, handshake);
+    const params = workerThreadParams({ cwd, mcpServers, storeServer: null });
+    return compactCodexThread({ server: client, threadId: rec.sessionId, threadParams: params });
+  },
+  settleApproval: (sup, ...args) => sup.settleCodexApproval(...args),
+  approvalChanged: (sup, ...args) => sup.codexCardChanged(...args),
+  memoryGate: sup => sup.codexMemoryGateEnv(),
+  async runCommand(sup, { home, ...operation }) {
+    const { client, handshake } = sup._codexServer(home);
+    await handshake;
+    return runCodexCommand({ server: client, ...operation });
+  },
+  updateSettings: () => ({}),
+  updatePlan: options => commonUpdatePlan(definition, options, ({ bin, real, name }) => {
+    const standalone = real.match(/^(.*)\/packages\/standalone\/(?:releases|current)\//);
+    return standalone ? { name, file: '/bin/bash',
+      args: ['-o', 'pipefail', '-c', '/usr/bin/curl -fsSL --connect-timeout 10 --max-time 60 https://chatgpt.com/codex/install.sh | /bin/sh'],
+      env: { CODEX_HOME: standalone[1], CODEX_INSTALL_DIR: path.dirname(bin) },
+      feed: 'https://releases.openai.com/codex/channels/latest', format: 'codex' } : null;
+  }),
+  smallModelArgs: prompt => ['exec', '--skip-git-repo-check', '--ephemeral', '--ignore-user-config', '--ignore-rules', '-s', 'read-only', '-c', 'model_reasoning_effort=low', prompt],
+};

package/main/harnesses/common.mjs

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import { instructionsFor } from './instructions-file.mjs';
+
+/**
+ * THE COMMAND LINE THAT STARTS A WORKER, BUILT FROM THE DEFINITION'S `run`.
+ *
+ * Every flag name here used to be a literal in main/supervisor.mjs, so the
+ * supervisor knew one engine's CLI by heart and a second one of the same family
+ * could not be added without editing it. The order is the order that shipped,
+ * and `tests/a-second-stream-json-engine-is-only-a-definition` holds it there,
+ * because flag order is the kind of thing a refactor silently rewrites.
+ *
+ * ABSENT MEANS CANNOT, not "default". An engine whose `run` has no `effort` is
+ * handed no effort word even when the task names one, which is how a harness
+ * says it lacks a capability without the call site asking who it is. `fork` is
+ * the one pair: a fork is a fork OF something, so it needs a resume as well.
+ */
+export function workerArgsFrom(run, { prompt, grants = [], effort = null, system = null, resumeId = null, fork = false } = {}) {
+  if (!run) return [];
+  const args = [];
+  if (run.print) args.push(run.print, prompt);
+  if (run.outputFormat) args.push(run.outputFormat.flag, run.outputFormat.value);
+  if (run.stream) args.push(...run.stream);
+  args.push(...grants);
+  if (run.effort && effort) args.push(run.effort, effort);
+  if (run.system && system) args.push(run.system, system);
+  if (run.resume && resumeId) args.push(run.resume, resumeId);
+  if (run.fork && fork && resumeId) args.push(run.fork);
+  return args;
+}
+
+export function definitionMethods(definition) {
+  const scrub = definition.scrubPatterns.map(pattern => new RegExp(pattern));
+  return {
+    ...definition,
+    binary: config => config?.[definition.binKey] ?? null,
+    workerArgs: options => workerArgsFrom(definition.run, options),
+    // WHERE THE PERSON'S STANDING INSTRUCTIONS GO on this engine. A flag for
+    // the one that has one, a file named in the definition for the ones that
+    // do not, and a refusal for an engine with neither — because that engine
+    // would answer against rules it was never given, and nothing on screen
+    // would say so.
+    instructions: context => instructionsFor(definition, context),
+    launchEnv: (_bin, env) => ({ ...env }),
+    install: () => ({ file: definition.installer.shell, args: ['-c', `curl -fsSL ${definition.installer.url} | ${definition.installer.pipe}`] }),
+    signIn: bin => ({ file: bin, args: [...definition.loginArgs] }),
+    signInStatus: bin => ({ file: bin, args: [...definition.statusArgs] }),
+    accountKey: profile => `${definition.accountPrefix}${profile}`,
+    workerEnv(input = process.env) {
+      const env = { ...input };
+      for (const key of Object.keys(env)) if (scrub.some(pattern => pattern.test(key))) delete env[key];
+      return env;
+    },
+    signInFiles: ({ folder }) => folder ? definition.credentialFiles.map(file => path.join(folder, file)) : [],
+  };
+}
+
+// Installation-specific work remains in each adapter. The common installers
+// use the same prefix and cask checks for every registered tool.
+export function commonUpdatePlan(definition, { bin, real, home, channel = 'latest' }, native) {
+  if (!path.isAbsolute(bin || '') || !real) return null;
+  const name = definition.label;
+  const brew = real.match(/^(\/opt\/homebrew|\/usr\/local)\/Caskroom\/([^/]+)\//);
+  if (brew && definition.casks.includes(brew[2])) return {
+    name, file: `${brew[1]}/bin/brew`, args: ['upgrade', '--cask', brew[2]],
+    feed: `https://formulae.brew.sh/api/cask/${brew[2]}.json`, format: 'brew',
+  };
+  const tail = `/lib/node_modules/${definition.package}/`;
+  const at = real.indexOf(tail);
+  if (at > 0) {
+    const prefix = real.slice(0, at);
+    return { name, file: path.join(prefix, 'bin/npm'),
+      args: ['install', '--global', '--prefix', prefix, `${definition.package}@${channel}`],
+      env: { PATH: `${prefix}/bin:${process.env.PATH || ''}` },
+      feed: `https://registry.npmjs.org/${definition.package}/${channel}`, format: 'npm' };
+  }
+  return native?.({ bin, real, home, channel, name }) ?? null;
+}