agentbox-app 0.1.13 → 0.1.16

package/shared/cloud-kit.mjs

@@ -0,0 +1,341 @@
+// A THREAD'S NEXT TURN, READY FOR THE CLOUD TO START WITH THE COMPUTER SHUT
+// (docs/cloud/PHONE-PLAN.md step 2, docs/cloud/PLAN.md "Next" step 4).
+//
+// After each turn of a thread that is on the phone, the computer leaves a kit
+// in the person's cloud storage: everything a cloud start needs (the folder's
+// bundle, the files a run takes, the arguments, the sign-in by name) except
+// the reply and the run's own links. A reply the computer has not claimed
+// within CLOUD_TAKES_AFTER_MS is started from the kit by the cloud server
+// (cloud/gateway/phone.mjs), which claims the command `cloud:<run id>`; the
+// computer, waking, joins that run as it joins one it left going
+// (main/cloud/run.mjs `joining`) and brings its work home.
+//
+// Shared by the computer (main/cloud/kit.mjs), the server and the phone, so
+// all three agree on the names. Pure: no file, no network.
+
+export const KIT_VERSION = 1;
+
+// Where the reply goes in the turn's prompt. Characters no prompt carries, so
+// it is found once or not at all.
+export const REPLY_MARK = '⁣AGENTBOX-REPLY⁣';
+
+// A computer that is awake claims a phone command within seconds; one left
+// this long is the cloud's to start.
+export const CLOUD_TAKES_AFTER_MS = 60_000;
+// And one older than this is left to the computer: the phone said it long ago.
+export const CLOUD_TAKES_UNTIL_MS = 24 * 60 * 60_000;
+// Inside the bucket's seven-day expiry of `runs/`, with a day's room.
+export const KIT_FRESH_MS = 6 * 24 * 60 * 60_000;
+const KIT_BYTES = 2 * 1024 * 1024;
+
+const CLAIM = /^cloud:([A-Za-z0-9._-]{1,120})$/;
+export const cloudClaim = (runId) => `cloud:${runId}`;
+export const runOfClaim = (claimedBy) => (typeof claimedBy === 'string' && CLAIM.test(claimedBy) ? claimedBy.match(CLAIM)[1] : null);
+
+// The same name main/cloud/run.mjs gives a run it starts, so a computer
+// joining a run the server started asks for it by the name it would have used.
+export const cloudSessionId = (item, runId) => `agentbox-${String(item || 'run').replace(/[^a-zA-Z0-9-]/g, '')}-${runId}`;
+
+const seg = (s) => String(s ?? '').replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '_').slice(0, 120) || '_';
+/** Where a thread's kit lives in the person's own storage. */
+export const kitKey = (device, project, item) => `runs/kits/${seg(device)}/${seg(project)}/${seg(item)}.json`;
+/** What the server keeps about a run it started, for the moment it ends. */
+export const serverRunKey = (runId) => `runs/server/${seg(runId)}.json`;
+/** Written by a computer that has joined a run the server started: the server feeds and closes it no more. */
+export const serverJoinedKey = (runId) => `runs/server/${seg(runId)}.joined.json`;
+/** The objects a run writes as it ends, named as main/cloud/run.mjs names them. */
+export const runKey = (runId, name) => `runs/${runId}/${name}`;
+
+/** The text either side of the reply, or null when the prompt has no one place for it. */
+export function replyFrame(prompt) {
+  const text = String(prompt ?? '');
+  const at = text.indexOf(REPLY_MARK);
+  if (at < 0 || text.indexOf(REPLY_MARK, at + 1) >= 0) return null;
+  return { before: text.slice(0, at), after: text.slice(at + REPLY_MARK.length) };
+}
+
+export const replyPrompt = (frame, reply) => `${frame.before}${String(reply ?? '')}${frame.after}`;
+
+// The first line on the agent's input, as the computer writes one
+// (main/claude-input.mjs), with the cloud's note at its top the way
+// main/cloud/run.mjs `claudeLineForTheCloud` puts it on a resumed run.
+export function cloudUserLine(text, { note = null, uuid } = {}) {
+  const content = note ? `${note}\n\n${text}` : String(text);
+  return `${JSON.stringify({ type: 'user', uuid, message: { role: 'user', content }, parent_tool_use_id: null, session_id: '' })}\n`;
+}
+
+const isKey = (k) => typeof k === 'string' && /^runs\/[A-Za-z0-9._@+=/-]+$/.test(k) && !k.includes('..');
+const isLoginKey = (k) => typeof k === 'string' && /^logins\/[A-Za-z0-9._@+=/-]+$/.test(k) && !k.includes('..');
+const isPath = (p) => typeof p === 'string' && p.startsWith('/') && !p.includes('\0');
+const strings = (a) => Array.isArray(a) && a.every((s) => typeof s === 'string');
+
+/** Why a kit cannot be started from, or null. Read by the server before it trusts one. */
+export function checkKit(kit, { now = Date.now() } = {}) {
+  if (!kit || typeof kit !== 'object') return 'not a kit';
+  if (kit.v !== KIT_VERSION) return 'another version of kit';
+  if (kit.engine !== 'claude' && kit.engine !== 'codex') return 'only Claude Code and Codex threads carry on in the cloud';
+  if (kit.engine === 'codex') { const p = codexKitProblem(kit.codex); if (p) return p; }
+  if (!(now - Number(kit.madeAt) < KIT_FRESH_MS)) return 'the kit is too old';
+  if (!isPath(kit.cwd)) return 'no folder';
+  if (!strings(kit.argv) || !kit.argv.length) return 'no command';
+  if (!kit.frame || typeof kit.frame.before !== 'string' || typeof kit.frame.after !== 'string') return 'no place for the reply';
+  if (!kit.login || kit.login.engine !== kit.engine || !isLoginKey(kit.login.key)) return 'no sign-in';
+  if (kit.env && (typeof kit.env !== 'object' || !Object.values(kit.env).every((v) => typeof v === 'string'))) return 'bad environment';
+  if (!kit.plain && typeof kit.branch !== 'string') return 'no branch';
+  if (kit.bundleKey !== undefined && kit.bundleKey !== null && !isKey(kit.bundleKey)) return 'bad bundle';
+  if (kit.base && (!isKey(kit.base.key) || typeof kit.base.sha !== 'string')) return 'bad base';
+  if (!kit.plain && !kit.bundleKey && !kit.base) return 'no copy of the folder';
+  for (const f of kit.files ?? []) if (!isPath(f?.path) || !isKey(f.key) || (f.untar !== undefined && !isPath(f.untar))) return 'bad file';
+  for (const f of kit.homeFiles ?? []) if (typeof f?.rel !== 'string' || f.rel.startsWith('/') || f.rel.includes('..') || !isKey(f.key)) return 'bad home file';
+  for (const b of kit.bringDirs ?? []) if (typeof b?.name !== 'string' || !/^[a-z.]+$/.test(b.name) || !isPath(b.dir)) return 'bad folder to bring home';
+  if (!kit.bringDirs?.length) return 'nothing to bring home';
+  if (kit.hold !== undefined && !(Array.isArray(kit.hold) && kit.hold.every((s) => typeof s === 'string'))) return 'bad held servers';
+  if (kit.handshakes !== undefined && (!kit.handshakes || typeof kit.handshakes !== 'object' || Array.isArray(kit.handshakes))) return 'bad handshakes';
+  if (JSON.stringify(kit).length > KIT_BYTES) return 'the kit is too large';
+  return null;
+}
+
+/**
+ * The sandbox's `start` for a run from this kit (cloud/sandbox/server.mjs),
+ * built as main/cloud/run.mjs builds one. `getUrl(key)` and `putUrl(key)` make
+ * links; the sign-in goes by name (`loginName(key)`) for the server to swap.
+ */
+export async function startPayload(kit, { runId, getUrl, putUrl, loginName, offlineAfterMs = 90_000, kept = null, endTurn = 'claude-stream-json', refs = null, away = false }) {
+  const results = {
+    bundleUrl: await putUrl(runKey(runId, 'out.bundle')),
+    changesUrl: await putUrl(runKey(runId, 'changes.bundle')),
+    docsUrl: await putUrl(runKey(runId, 'docs.tgz')),
+    eventsUrl: await putUrl(runKey(runId, 'events.jsonl')),
+    doneUrl: await putUrl(runKey(runId, 'done.json')),
+    bring: await Promise.all(kit.bringDirs.map(async (b) => ({ dir: b.dir, url: await putUrl(runKey(runId, b.name)) }))),
+  };
+  const files = await Promise.all((kit.files ?? []).map(async (f) => ({ path: f.path, url: await getUrl(f.key), ...(f.untar ? { untar: f.untar } : {}) })));
+  const homeFiles = await Promise.all((kit.homeFiles ?? []).map(async (f) => ({ rel: f.rel, url: await getUrl(f.key) })));
+  return {
+    action: 'start', runId, cwd: kit.cwd, branch: kit.branch ?? null,
+    ...(kit.bundleKey ? { bundleUrl: await getUrl(kit.bundleKey) } : {}),
+    ...(kit.plain ? { plain: true } : {}),
+    ...(kit.base ? { base: { url: await getUrl(kit.base.key), sha: kit.base.sha }, refs: refs ? { ...(kit.refs ?? {}), ...refs } : (kit.refs ?? null) } : {}),
+    // A new thread's branch, made at the main its kit saw (`fillNewThreadKit`).
+    ...(!kit.base && refs ? { refs } : {}),
+    argv: kit.argv, env: kit.env ?? {}, files,
+    ...(kit.changesRef ? { changesRef: kit.changesRef } : {}),
+    ...(kit.remote ? { remote: kit.remote } : {}),
+    ...(kit.docs ? { docs: kit.docs } : {}),
+    ...(homeFiles.length ? { homeFiles } : {}),
+    login: { engine: kit.login.engine, id: kit.login.id ?? null, url: loginName(kit.login.key) },
+    results,
+    tails: true,
+    // Null keeps the agent's input open while the computer is away, for a run
+    // the server feeds more replies to (cloud/gateway/phone.mjs).
+    offline: { afterMs: offlineAfterMs, endTurn, kept, ...heldFor(kit), ...(away ? { away: true } : {}) },
+  };
+}
+
+// PERMISSION REQUESTS WITH THE COMPUTER AWAY. A kit for a run that asks names
+// the app's approvals server as held (cloud/sandbox/server.mjs): its calls
+// wait for an answer instead of being refused, and its handshake is the
+// computer's own, carried in the kit. `away`: the server starts it, so the
+// computer is not there from its first moment.
+const heldFor = (kit) => (Array.isArray(kit.hold) && kit.hold.length
+  ? { hold: kit.hold, ...(kit.handshakes && typeof kit.handshakes === 'object' ? { handshakes: kit.handshakes } : {}) }
+  : {});
+
+/** The app's approvals server, by the name a run's tools give it (`mcp__zero-approvals__approval_prompt`). */
+export const APPROVALS_SERVER = 'zero-approvals';
+
+/** A held request's card id: one the phone may send back (`^[\w-]{1,80}$`), and marked as the cloud's. */
+export const askId = (runId, conn, id) => `cloud-${String(runId)}-${String(conn)}-${String(id)}`.replace(/[^\w-]/g, '_').slice(0, 80);
+/** Whether a card's id is one the cloud put on the phone, so its answer is the cloud's to give. */
+export const cloudCard = (approval) => typeof approval === 'string' && approval.startsWith('cloud-');
+
+// What the app's approvals server answers (main/approval-prompt-core.mjs).
+export const DECLINED = 'The founder declined this action. Work with what you are already allowed to do, or park the remainder as a review.';
+/** The answer to a held approval_prompt call, as the app's own server would write it. */
+export function approvalAnswerLine(id, { allow, note = null, input = {} } = {}) {
+  const said = allow ? { behavior: 'allow', updatedInput: input ?? {} } : { behavior: 'deny', message: note || DECLINED };
+  return JSON.stringify({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: JSON.stringify(said) }] } });
+}
+
+/** Each of Claude Code's `result` lines, in order, off a run's event log. */
+export function answersIn(eventsText) {
+  let out = '';
+  for (const raw of String(eventsText ?? '').split('\n')) {
+    if (!raw.trim()) continue;
+    let e;
+    try { e = JSON.parse(raw); } catch { continue; }
+    if (e?.kind === 'stdout' && typeof e.data === 'string') out += Buffer.from(e.data, 'base64').toString('utf8');
+  }
+  return resultsInLines(out.split('\n'));
+}
+
+/** The `result`s among stream-json lines: { text, isError } each. */
+export function resultsInLines(lines) {
+  const found = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    if (msg?.type === 'result') found.push({ text: String(msg.result ?? ''), isError: msg.is_error === true });
+  }
+  return found;
+}
+
+// WHAT THE AGENT LAST SAID, off a run's event log (one JSON event a line, its
+// output in base64): the text of Claude Code's last `result`, and whether it
+// was an error. Null when the run never got that far.
+export function lastAnswerIn(eventsText) {
+  let out = '';
+  for (const raw of String(eventsText ?? '').split('\n')) {
+    if (!raw.trim()) continue;
+    let e;
+    try { e = JSON.parse(raw); } catch { continue; }
+    if (e?.kind === 'stdout' && typeof e.data === 'string') out += Buffer.from(e.data, 'base64').toString('utf8');
+  }
+  let answer = null;
+  for (const line of out.split('\n')) {
+    if (!line.trim()) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    if (msg?.type === 'result') answer = { text: String(msg.result ?? ''), isError: msg.is_error === true };
+  }
+  return answer;
+}
+
+// A CODEX KIT'S THREAD (main/codex-app-server.mjs). A Codex run is
+// `codex app-server` spoken to in JSON-RPC, so the kit holds the lines the
+// computer's own client would send to open the thread in the cloud
+// (initialize, initialized, thread/resume rewritten as main/cloud/run.mjs
+// rewrites them) and the turn's settings; her reply goes into a `turn/start`
+// whose input is the turn's prompt. Request ids are fixed: `resumeId` names
+// the resume's answer, and turns go from `firstTurnId` on.
+// A new thread's Codex kit starts its thread (`startId`, the `thread/start`'s
+// own id) instead, and learns the thread's id from that answer.
+function codexKitProblem(c) {
+  if (!c || !strings(c.open) || c.open.length < 3) return 'a Codex kit with no lines to open its thread';
+  const opens = Number.isInteger(c.startId) ? c.startId : c.resumeId;
+  if (!Number.isInteger(opens) || !Number.isInteger(c.firstTurnId) || c.firstTurnId <= opens) return 'a Codex kit with no request ids';
+  if (!c.turn || typeof c.turn !== 'object') return 'a Codex kit with no turn';
+  if (Number.isInteger(c.startId)) return c.turn.threadId === undefined ? null : 'a Codex kit that starts a thread and resumes one';
+  if (typeof c.turn.threadId !== 'string' || !c.turn.threadId) return 'a Codex kit with no thread to resume';
+  return null;
+}
+
+/** What opens a Codex kit's thread in the cloud, as one input. */
+export const codexOpenLines = (kit) => kit.codex.open.map((l) => (l.endsWith('\n') ? l : `${l}\n`)).join('');
+
+/** Her reply as one turn of the kit's thread, with request id `id`. */
+// `raw` is a new thread's first turn, its brief as it stands; `threadId` the
+// id a new thread's start answered with.
+export function codexTurnLines(kit, reply, { id, raw = null, threadId: named = null }) {
+  const { threadId: kept, ...settings } = kit.codex.turn;
+  const text = typeof raw === 'string' ? raw : replyPrompt(kit.frame, reply);
+  return `${JSON.stringify({ jsonrpc: '2.0', id, method: 'turn/start', params: { threadId: named ?? kept, ...settings, input: [{ type: 'text', text }] } })}\n`;
+}
+
+// WHAT A CODEX RUN SAID, read as main/codex.mjs `captureCodexEvent` reads it:
+// a turn's answer is its `agentMessage` with `phase: "final_answer"` (one with
+// no phase still counts, a `commentary` never does), or the final answer in
+// `turn.items`; a failed turn says why. `state` carries a turn across reads
+// and is told the resume's answer (`resumed`: true, or why it was refused);
+// a refused `turn/start` (one of `turnIds`) is a failed turn of its own.
+export function codexReadLines(lines, state = {}) {
+  const answers = [];
+  for (const raw of lines) {
+    if (!raw || !raw.trim()) continue;
+    let msg;
+    try { msg = JSON.parse(raw); } catch { continue; }
+    if (!msg || typeof msg !== 'object') continue;
+    if (msg.id !== undefined && msg.method === undefined) {
+      const why = msg.error ? String(msg.error.message ?? 'refused') : null;
+      if (msg.id === state.resumeId) {
+        state.resumed = why ?? true;
+        if (!why && typeof msg.result?.thread?.id === 'string') state.threadId = msg.result.thread.id;
+      }
+      else if (why && (state.turnIds ?? []).includes(msg.id)) answers.push({ text: why, isError: true });
+      continue;
+    }
+    const p = msg.params ?? {};
+    if (msg.method === 'item/completed') {
+      const item = p.item ?? {};
+      if (item.type !== 'agentMessage') continue;
+      const phase = typeof item.phase === 'string' ? item.phase : null;
+      if (phase === 'commentary' || (state.final && phase !== 'final_answer')) continue;
+      state.result = String(item.text ?? '');
+      if (phase === 'final_answer') state.final = true;
+      continue;
+    }
+    if (msg.method === 'turn/completed' || msg.method === 'turn/failed') {
+      const turn = p.turn ?? {};
+      const status = typeof turn.status === 'string' ? turn.status : msg.method === 'turn/failed' ? 'failed' : 'completed';
+      if (status === 'completed') {
+        const kept = Array.isArray(turn.items) ? [...turn.items].reverse().find((i) => i?.type === 'agentMessage' && i.phase === 'final_answer') : null;
+        const text = state.result ?? (kept ? String(kept.text ?? '') : null);
+        answers.push(text == null ? { text: '', isError: true } : { text, isError: false });
+      } else {
+        const why = String(turn.error?.message ?? '').trim() || (status === 'interrupted' ? 'the turn was interrupted' : `the turn ${status}`);
+        answers.push({ text: why, isError: true });
+      }
+      state.result = null;
+      state.final = false;
+    }
+  }
+  return answers;
+}
+
+const stdoutOf = (eventsText) => {
+  let out = '';
+  for (const raw of String(eventsText ?? '').split('\n')) {
+    if (!raw.trim()) continue;
+    let e;
+    try { e = JSON.parse(raw); } catch { continue; }
+    if (e?.kind === 'stdout' && typeof e.data === 'string') out += Buffer.from(e.data, 'base64').toString('utf8');
+  }
+  return out;
+};
+
+/** Each Codex turn's answer, in order, off a run's event log. */
+export const codexAnswersIn = (eventsText, state = {}) => codexReadLines(stdoutOf(eventsText).split('\n'), state);
+
+/** A Codex run's last answer off its event log, or null. */
+export function codexAnswerIn(eventsText) {
+  const all = codexAnswersIn(eventsText);
+  return all.length ? all[all.length - 1] : null;
+}
+
+// A NEW THREAD FROM THE PHONE WITH THE COMPUTER SHUT. Each project on the
+// phone keeps a kit for a fresh thread beside its threads' kits, built for a
+// stand-in item whose id, title and body are these marks and packed from
+// main (main/cloud/run.mjs, Supervisor#_leaveNewThreadKit). The item's mark
+// is plain letters, so a folder name made from a path that holds it
+// (Claude Code's transcripts) holds it unchanged too.
+export const NEW_THREAD = '_new';
+export const NEW_ITEM_MARK = 'xagentboxnewitemx';
+export const NEW_TITLE_MARK = '⁣AGENTBOX-NEW-TITLE⁣';
+export const NEW_BODY_MARK = '⁣AGENTBOX-NEW-BODY⁣';
+// A Codex one, when the computer has a Codex sign-in for the cloud, beside it.
+export const NEW_THREAD_CODEX = '_new-codex';
+export const newThreadKitKey = (device, project, engine = 'claude') => kitKey(device, project, engine === 'codex' ? NEW_THREAD_CODEX : NEW_THREAD);
+
+const ID = /^[A-Za-z0-9_-]{1,64}$/;
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const WORDS = new RegExp(`${esc(NEW_TITLE_MARK)}|${esc(NEW_BODY_MARK)}`, 'g');
+
+/**
+ * A project's new-thread kit made the kit of thread `itemId`, the id the
+ * computer gives a thread the phone started (madeHere): every mark of the
+ * item put in, her title and body in its first prompt, and the branch to make
+ * at the main the kit saw. Null for a kit that is not one, or an id no folder
+ * may have.
+ */
+export function fillNewThreadKit(kit, { itemId, title = '', body = '' }) {
+  const n = kit?.newThread;
+  if (!n || typeof n.brief !== 'string' || typeof n.mainSha !== 'string' || !ID.test(String(itemId ?? ''))) return null;
+  const swap = (v) => (typeof v === 'string' ? v.split(NEW_ITEM_MARK).join(itemId)
+    : Array.isArray(v) ? v.map(swap)
+      : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, swap(x)])) : v);
+  const { newThread: _n, ...rest } = kit;
+  const filled = { ...swap(rest), item: itemId };
+  const prompt = swap(n.brief).replace(WORDS, (m) => (m === NEW_TITLE_MARK ? String(title) : String(body)));
+  return { kit: filled, prompt, refs: { [`refs/heads/${filled.branch}`]: n.mainSha }, mainSha: n.mainSha };
+}

package/shared/cloud-login-name.mjs

@@ -0,0 +1,4 @@
+// How a Mac on the managed cloud names a sign-in it may not read: in place of
+// a link, this prefix and the sign-in's key. The cloud server swaps it for a
+// real link only inside a call to the sandbox (cloud/gateway/gateway.mjs).
+export const LOGIN_NAME = 'agentbox-login:';

package/shared/cloud-start.mjs

@@ -0,0 +1,17 @@
+// THE LINE A CLOUD RUN PRINTS ONCE THE CLOUD HAS ACCEPTED ITS START
+// (main/cloud/run.mjs), with how long this Mac took to pack and send it and
+// the cloud took to take it. From then on the run holds nothing on this Mac,
+// so it stops counting against the starts allowed at once
+// (Supervisor#_cloudStarting). Not `agentbox cloud:`, which is what a run
+// says about why it failed (Supervisor#_noteCloudOutcome).
+export const CLOUD_SENT = 'agentbox cloud-sent:';
+
+export function sentLine({ packMs, startMs }) {
+  return `${CLOUD_SENT} packed ${Math.round(packMs)} started ${Math.round(startMs)}\n`;
+}
+
+/** `{ packMs, startMs }` from any text holding the line, else null. */
+export function readSent(text) {
+  const m = new RegExp(`${CLOUD_SENT} packed (\\d+) started (\\d+)`).exec(String(text ?? ''));
+  return m ? { packMs: Number(m[1]), startMs: Number(m[2]) } : null;
+}

package/shared/cloud-versions.mjs

@@ -0,0 +1,23 @@
+// THE CLOUD IMAGE'S CLAUDE CODE AND CODEX AGAINST THIS MAC'S.
+//
+// scripts/cloud-setup.mjs pins the image to the versions this Mac ran when it
+// was built and writes them into cloud.json. A thread moves between the two,
+// so a gap in major.minor is worth a rebuild, and a gap in major is a known
+// break: that engine's threads stay on this Mac until the image is rebuilt.
+
+const minor = (v) => {
+  const m = /^(\d+)\.(\d+)\.\d+/.exec(String(v ?? '').trim());
+  return m ? { major: Number(m[1]), text: `${m[1]}.${m[2]}` } : null;
+};
+
+/** `cloud` and `mac` are `{ claude, codex }` version strings; one entry per engine that differs. */
+export function cloudVersionGaps({ cloud = {}, mac = {} } = {}) {
+  const out = [];
+  for (const engine of ['claude', 'codex']) {
+    const there = minor(cloud[engine]);
+    const here = minor(mac[engine]);
+    if (!there || !here || there.text === here.text) continue;
+    out.push({ engine, cloud: there.text, mac: here.text, blocks: there.major !== here.major });
+  }
+  return out;
+}

package/shared/codex-import.mjs

@@ -175,13 +175,13 @@ export function codexImportRow(thread, { projectName, now = Date.now() } = {}) {
 /**
  * THE ROW ONCE THE USER SAID YES. Their prompt is the body and Codex's last message
  *  is the result, so the thread reads You, then Codex, the way it did over
- *  there. The result carries the one line that says where replies go. */
+ *  there. A reply on it carries the work on here. */
 export function codexMirrorPatch(thread) {
   const prompt = plainQuote(thread?.prompt);
   const last = plainQuote(thread?.last);
   return {
     body: prompt || String(thread?.title ?? '').trim(),
-    result: last ? `${last}\n\nRead from Codex. Replies happen there.` : 'Codex has not answered yet.\n\nRead from Codex. Replies happen there.',
+    result: last || 'Codex has not answered yet.',
     kind: 'directive',
     labels: [CODEX_MIRROR_LABEL, codexLabel(thread?.id)],
   };

package/shared/codex-modes.d.mts

@@ -8,17 +8,18 @@ import type { CodexModeId } from '../renderer/src/types';
 
 /**
  * THE PAIR A MODE REALLY IS. `sandbox` and `approvalPolicy` go straight into
- *  Codex's `thread/start`; `approvalsReviewer` is set on `auto` alone, which is
- *  the only row with asks left to answer. They are plain strings rather than
- *  unions on purpose: the authority for what Codex accepts is Codex's own
- *  schema, quoted in the .mjs, and a union here would be a third copy of it
- *  that nothing checks.
+ *  Codex's `thread/start`. NO ROW CARRIES A REVIEWER any more: all three get
+ *  the same one and `codexPosture` supplies it, because a per-row value is how
+ *  the 2026-10-09 hole stayed open -- two of the three named none, fell through
+ *  to a config file, and behaved differently from the one that did. They are
+ *  plain strings rather than unions on purpose: the authority for what Codex
+ *  accepts is Codex's own schema, quoted in the .mjs, and a union here would be
+ *  a third copy of it that nothing checks.
  */
 export interface CodexMode {
   label: string;
   sandbox: string;
   approvalPolicy: string;
-  approvalsReviewer?: string;
   what: string;
 }
 
@@ -29,12 +30,24 @@ export declare const CODEX_MODE_COMMAND: Record<CodexModeId, string>;
 export declare const CODEX_MODE_HINT: Record<CodexModeId, string>;
 export declare const CODEX_MODE_STATUS: Record<CodexModeId, string>;
 
+export declare const CODEX_REVIEWERS: string[];
+export declare const ASKS_THE_PERSON: string;
+
 export declare function isCodexMode(word: unknown): boolean;
-/** The pair, falling back to the default's pair when the word is not one of ours. */
-export declare function codexPosture(mode: string | null | undefined): {
+/** The reviewer to send, falling back to the one that asks the person. */
+export declare function codexReviewer(asked?: string | null): string;
+/**
+ * The posture, falling back to the default's when the word is not one of ours.
+ *  `approvalsReviewer` is ALWAYS present: an absent field lets a Codex home's
+ *  own `approvals_reviewer` decide whether a worker may leave its sandbox.
+ */
+export declare function codexPosture(
+  mode: string | null | undefined,
+  options?: { reviewer?: string | null },
+): {
   sandbox: string;
   approvalPolicy: string;
-  approvalsReviewer?: string;
+  approvalsReviewer: string;
 };
 export declare function codexModeWords(mode: string | null | undefined): string;
 /**

package/shared/codex-modes.mjs

@@ -37,6 +37,57 @@ export const CODEX_MODE_ORDER = ['read-only', 'auto', 'full-access'];
 /** The one a worker runs in when nothing has been picked. */
 export const CODEX_DEFAULT_MODE = 'auto';
 
+/**
+ * WHO A SANDBOX ESCAPE IS ROUTED TO, in Codex's own three words. Read off
+ *  `codex app-server generate-json-schema` on codex-cli 0.160.0, 2026-10-09.
+ *  The schema's own description: "Configures who approval requests are routed to
+ *  for review. Examples include sandbox escapes, blocked network access, MCP
+ *  approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses
+ *  a carefully prompted subagent to gather relevant context and apply a
+ *  risk-based decision framework before approving or denying the request."
+ *
+ *  A value outside this list is not a near miss: `thread/start` refuses it and
+ *  the run is lost, so `codexReviewer` below falls back rather than passing one
+ *  through.
+ */
+export const CODEX_REVIEWERS = ['user', 'auto_review', 'guardian_subagent'];
+
+/**
+ * THE ONE THAT PUTS THE QUESTION IN FRONT OF A PERSON, which is the whole
+ *  reason this constant has a name instead of being a string in three places.
+ *  It is also the protocol's own default; Agentbox sends it explicitly anyway,
+ *  for the reason `codexReviewer` gives.
+ */
+export const ASKS_THE_PERSON = 'user';
+
+/**
+ * The reviewer to send, given whatever a caller asked for.
+ *
+ *  THE FIELD IS ALWAYS SENT, AND THAT IS THE POINT. It was absent before, so
+ *  the value came from a top-level `approvals_reviewer` in whichever Codex home
+ *  billed the run. Measured 2026-10-09 on codex-cli 0.160.0 against a real
+ *  app-server: with the field absent and that key set to `auto_review`, a
+ *  worker asked to write outside its workspace had the escalation APPROVED by
+ *  Codex's own subagent, wrote into the home directory, and reached three
+ *  external sites -- with ZERO approval cards raised and no server request on
+ *  the wire at all. The same run with `approvalsReviewer: 'user'` raised a card
+ *  reading "The sandbox blocked this write outside the workspace. Do you
+ *  approve...". The reproduction is `scripts/qa-codex-live.mjs approvals`.
+ *
+ *  So a file nobody in this app reads was deciding what a worker may do. Naming
+ *  the reviewer on every start takes that vote away, and `user` is the value,
+ *  because "ask" in a mode's own sentence has to mean asking the person.
+ *
+ *  THIS IS NOT A REVERSAL OF w-ca48e69535. That row put `auto_review` on `auto`
+ *  to stop two logins behaving differently -- a home with no config sent asks to
+ *  her inbox, a home with one did not. Naming the reviewer explicitly fixes that
+ *  same inconsistency and fixes it in the direction the mode already promised.
+ *  One mode, one behaviour, whichever account the run is on.
+ */
+export function codexReviewer(asked = null) {
+  return CODEX_REVIEWERS.includes(asked) ? asked : ASKS_THE_PERSON;
+}
+
 /**
  * THE PAIR EACH MODE REALLY IS. `sandbox` and `approvalPolicy` go straight into
  *  `thread/start`, so this table is the whole of the mapping and there is no
@@ -46,6 +97,11 @@ export const CODEX_DEFAULT_MODE = 'auto';
  *  the refusing, and `on-request` leaves the agent able to ASK to step outside
  *  rather than simply failing. On `full-access` there is nothing left to ask
  *  about, so it is `never`.
+ *
+ *  NO ROW NAMES A REVIEWER, because all three get the same one and a per-row
+ *  value is how the last hole stayed open: two of the three named none, fell
+ *  through to her config, and behaved differently from the one that did.
+ *  `codexPosture` supplies it, once, below.
  */
 export const CODEX_MODES = {
   'read-only': {
@@ -59,13 +115,7 @@ export const CODEX_MODES = {
     label: 'Auto',
     sandbox: 'workspace-write',
     approvalPolicy: 'on-request',
-    // WHO ANSWERS THOSE ASKS, SAID HERE RATHER THAN LEFT TO A FILE. This used
-    // to come only from `approvals_reviewer` in her `~/.codex/config.toml`, so
-    // a second login's home, which starts with no config at all, sent every ask
-    // to her inbox instead (2026-09-24, w-ca48e69535). One mode, one behaviour,
-    // whichever account the run is on.
-    approvalsReviewer: 'auto_review',
-    what: 'Works inside the project folder. Asks before going outside it or onto the network.',
+    what: 'Works inside the project folder. Asks you before going outside it or onto the network.',
   },
   'full-access': {
     label: 'Full access',
@@ -87,11 +137,17 @@ export function isCodexMode(word) {
  *  start one. The writers (main/settings.mjs) validate on the way IN, which is
  *  where a typo can still be reported to the person who made it.
  */
-export function codexPosture(mode) {
+export function codexPosture(mode, { reviewer = null } = {}) {
   const row = CODEX_MODES[mode] ?? CODEX_MODES[CODEX_DEFAULT_MODE];
-  const posture = { sandbox: row.sandbox, approvalPolicy: row.approvalPolicy };
-  if (row.approvalsReviewer) posture.approvalsReviewer = row.approvalsReviewer;
-  return posture;
+  // The reviewer is named on EVERY mode, `full-access` included. Its policy is
+  // `never` so it changes no behaviour there today, and that is exactly why it
+  // is named: one answer in the table rather than two, so a later change to the
+  // policy cannot silently hand the decision back to a config file.
+  return {
+    sandbox: row.sandbox,
+    approvalPolicy: row.approvalPolicy,
+    approvalsReviewer: codexReviewer(reviewer),
+  };
 }
 
 /** The label for a mode, for any surface that has to name one. */