agentbox-app 0.1.13 → 0.1.16

package/shared/engines.mjs

@@ -1,65 +1,23 @@
 import { HARNESS_DEFINITIONS } from './harness-definitions.mjs';
-// WHICH CODING AGENT A TASK IS HANDED TO.
+// Which coding agent a task is handed to.
 //
-// AND THE PREMISE SHE GAVE FOR IT DID NOT HOLD. Measured head to head on her
-// Mac the same day, identical task, four fresh repos each: Codex 16.8 / 45.3 /
-// 96.9 / 18.6 seconds, Claude Code 19.0 / 19.8 / 19.8 / 21.2. Both correct
-// every run. Codex is NOT faster; it is slower on median and it wanders. That
-// is written here rather than in a report because it is the reason this file
-// must never make Codex the default for anybody, including her. Claude Code is
-// the default and stays the default until she says otherwise. What this file
-// buys is a SECOND ENGINE on a second subscription, which is the thing that
-// actually went wrong for her, and a choice she makes per task.
+// Claude Code is the default. Codex measured slower on median and wandered on
+// the same tasks, so do not make it the default for anybody.
 //
-// THIS FILE WAS DELETED AND IS COMING BACK IN STAGES, WHICH IS WHY IT NOW HAS
-// A GATE. Her own message on that commit says thirteen; the number here is the
-// one the tree can be asked for.
+// Old rows may still carry `engine: "codex"`, because the work-item fold keeps
+// every field it was given. So `engineFor` answers Claude Code unless the
+// caller hands it `ENGINE_CHOICE_ENABLED`, and a caller that passes nothing
+// gets the safe answer.
 //
-// `engine` DID NOT GO. It is still a live name on the work-item contract
-// (`WORK_ITEM_FIELDS`, shared/work-items.mjs:95, accepted by the patch
-// validator at :290, stored as a free string and validated against nothing,
-// because "nothing here reads them"). The fold has no migration and drops
-// nothing, so a row marked between 08-25 and 08-27 still carries
-// `engine: "codex"` UNLESS a later line overwrote that one field — which is
-// possible: the fold lets an equal-or-stronger write replace a field held by
-// an earlier one (`beats`, the authority comparison near shared/work-items.mjs
-// :494). Nothing has ever been written to clear it on purpose, so the honest
-// statement is "probably still there", not "always will be".
-//
-// HOW MANY SUCH ROWS A STORE ACTUALLY HAS IS AN OPEN QUESTION, AND IT IS NOT
-// ZERO UNTIL SOMEBODY LOOKS. It could not be measured from the machine this was
-// written on: there is no ~/Zero there at all. On a real store it is one command,
-// `grep -rho '"engine":"[a-z]*"' ~/Zero | sort | uniq -c`, and the answer
-// belongs in this paragraph when someone runs it. The gate below costs nothing
-// if the count turns out to be zero, and is the whole story if it is not.
-//
-// So the 08-25 resolver, restored unchanged, would have been a silent reversal
-// of the decision to withhold Codex: those rows would start choosing Codex again the moment this
-// module landed, with no picker, nothing in Settings, and no approval path
-// built. The resolver is therefore CLOSED unless the caller hands it
-// `ENGINE_CHOICE_ENABLED` below. A caller that passes nothing gets Claude
-// Code, because the safe answer is the one that has to be the accident.
-//
-// This module holds the names and the one rule. Everything Codex-shaped —
-// arguments, its event stream, where it writes its transcript — belongs in
-// main/codex.mjs when that comes back, because the renderer must never import
-// spawn code.
+// This module holds the names and the one rule. Codex arguments and its event
+// stream live in main/codex.mjs, because the renderer imports this file and
+// must never import spawn code.
 
 /**
- * The engines, in the order the picker draws them.
- *
- * ADMITTED ONES ONLY, and that word is doing real work as of 2026-10-07. A
- * harness being integrated and a harness being offered are two different
- * decisions, and this list is the second one. OpenCode is registered in
- * main/harnesses.mjs, its transport is measured and tested, and it is
- * deliberately absent from here -- so `ENGINE_IDS`, `isEngine`, `engineFor`,
- * the composer's picker, the Settings row and the byline all behave as if it
- * were not there, while `harnessFor('opencode')` works for anything that asks
- * for it by name. Without this filter, adding the definition alone would have
- * put a third word in front of every user the moment it landed.
- *
- * docs/harnesses.md holds the bar a harness clears before `admitted` goes
- * true, and the product review that turning it on requires.
+ * The engines, in the order the picker draws them. Admitted harnesses only: a
+ * registered harness (OpenCode, say) still works through `harnessFor` by name
+ * but is not offered anywhere until it is admitted. The bar for admission is in
+ * docs/harnesses.md.
  */
 export const ENGINES = HARNESS_DEFINITIONS
   .filter(({ admitted }) => admitted !== false)
@@ -68,164 +26,58 @@ export const ENGINES = HARNESS_DEFINITIONS
 export const ENGINE_IDS = ENGINES.map((e) => e.id);
 
 /**
- * What a task runs on when nobody has chosen.
- *
- * Not a setting and not a coin flip. See the measurement above: Claude Code is
- * faster on median and never wandered, and it is the only one of the two that
- * is WIRED to stop and ask her for permission mid-run.
- *
- * That second clause used to say Codex CANNOT ask, and it is now wrong twice
- * over. It was true of `codex exec`, which is what the removed 08-25 build
- * drove and what the sentence was written about. `codex app-server` raises real
- * approval requests, measured 2026-09-04, main/codex-app-server.mjs answers
- * them, main/codex-approvals.mjs draws them as the card she already knows, and
- * the spool they land in is the one the other engine uses. This paragraph went
- * on listing all four of those as missing for a whole slice after two of them
- * had been built.
- *
- * THE PICKER IS BUILT NOW TOO, 2026-09-04: a word in the composer's sentence
- * ("With Codex."), a row in Settings, and the engine named in the byline --
- * every one of them drawn only where `Supervisor#engineChoices` says this Mac
- * really offers a choice, which means the gate is open and the binary is there.
- * That paragraph used to say the missing picker was why the default had not
- * moved, and it was the last of four such claims to stop being true.
- *
- * SO THE DEFAULT IS HELD BY THE MEASUREMENT AT THE TOP OF THIS FILE AND BY
- * NOTHING ELSE. Codex is slower on median and it wanders; Claude Code stays the
- * default until she says otherwise, and now that there is a picker that is a
- * decision rather than a consequence.
+ * What a task runs on when nobody has chosen. It is Claude Code for the speed
+ * reason at the top of this file, not because Codex lacks approvals or a
+ * picker: both exist now.
  */
 export const DEFAULT_ENGINE = 'claude';
 
 /**
- * THE CAPABILITY GATE: an explicit code opt-in, saying that whoever wrote this
- * call site knew there was a second engine and meant to allow it.
- *
- * BE PRECISE ABOUT WHAT IT PROVES, because a gate believed to be stronger than
- * it is, is worse than no gate. It is a hard barrier against SERIALIZED DATA:
- * nothing that arrives as a ledger line, a config file or an IPC message can
- * open it, ever. It is NOT proof that the approval path she needs was actually
- * built, and it is not a defence against our own code — any module in this repo
- * can import the token. It moves the decision from data to source, and that is
- * all it does. It is the second half, the picker and her consent, that makes
- * the choice real.
- *
- * It is a Symbol, and that shape is the whole design:
- *
- * - A SYMBOL CANNOT ARRIVE FROM OUTSIDE THE PROCESS. Every input that could
- *   carry a stale `codex` is serialized: the ledger line off disk and
- *   `zero.config.json` are JSON, which has no way to spell a Symbol and drops
- *   it in silence, and an Electron IPC payload goes through the structured
- *   clone algorithm, which does not drop a Symbol but THROWS DataCloneError on
- *   one. Neither can express the gate. The louder of the two failures is the
- *   better one and we get it where it matters least; the point is that the
- *   untrusted data and the permission live in different type systems.
- * - IT IS `Symbol`, NEVER `Symbol.for`. The global registry would let any code
- *   anywhere mint an equal one out of a string. This one exists only where
- *   somebody imported this module and named it.
- * - IT IS NOT A BOOLEAN. `enabled: true` is the kind of thing a caller spreads
- *   in by accident from some other options object. This is not.
+ * The capability gate: passing this to `engineFor` says the call site meant to
+ * allow a second engine. It blocks serialized data only. Any module here can
+ * import it.
+ *
+ * It is a Symbol because nothing from outside the process can carry one: JSON
+ * drops it, and Electron's structured clone throws DataCloneError on it. It
+ * uses `Symbol`, not `Symbol.for`, so no string can mint an equal one, and it
+ * is not a boolean, so a spread options object cannot open it by accident.
  */
 export const ENGINE_CHOICE_ENABLED = Symbol('the second engine is wired up in this build');
 
-/**
- * WHEN SHE OPENED THE GATE, read off `zero.config.json`, or null. This is the
- * one value in the app that can cause the Symbol above to be handed over
- * (main/supervisor.mjs `_engineFor`, the only holder of it).
- *
- * THE OPT-IN IS A MOMENT AND NOT A FLAG, and that is the whole design of it.
- *
- * `engine` survived the 2026-08-27 removal on the work-item contract and the
- * fold drops nothing, so her store may still hold rows marked `codex` between
- * 08-25 and 08-27. How many is unknown; on her Mac it is one command,
- * `grep -rho '"engine":"[a-z]*"' ~/Zero | sort | uniq -c`, and the answer
- * belongs here when somebody runs it. A boolean opt-in would mean "every row
- * that ever said codex is live from now on", and the first thing it would do is
- * route an unknown number of those onto a second engine she had marked before
- * there was any way to choose. That is the exact hazard the gate was built for,
- * so an opt-in that walks into it is not one worth having. The picker built on
- * 2026-09-04 does not soften this: an August row is still not a choice she is
- * making now, and the byline draws it as the engine that will really run it.
- *
- * THOSE TWO MEANINGS ARE SEPARABLE, AND THE LEDGER ALREADY HOLDS WHAT
- * SEPARATES THEM. The fold records `wrote[field] = { ts, source }` per field
- * and stopped deleting it on the way out precisely because readers needed it
- * (shared/work-items.mjs:324; shared/answers.mjs reads `wrote.answer.ts` the
- * same way). So "Codex may be chosen FROM NOW ON" is a checkable statement
- * rather than a hope, and `engineChoiceOnRowIsStale` below is the check.
- *
- * WHY NOT A BOOLEAN PLUS A REMEMBERED "first seen at". Because that would live
- * in the app's own state rather than in her file: a fresh install, a state file
- * she deleted, or a second Mac would each invent a different moment, and the
- * one thing this value must be is the same on every machine reading the same
- * store. A date the user typed is a fact about their decision; a date we noticed is a
- * fact about a process.
- *
- * THE WORKSPACE DEFAULT (`config.engine`) IS TIME-SCOPED TOO, SINCE 2026-09-05,
- * AND THIS PARAGRAPH USED TO SAY IT COULD NOT BE. Its words were: "JSON has no
- * per-key write times, and `engine` sits in the same file as this, so opening
- * that file to write the moment is the same act as reading the line above it."
- * The first clause is true of JSON and irrelevant: the APP has write times, one
- * module writes that key (`setWorkspaceSetting`, main/settings.mjs), and
- * `saveConfig` takes a patch of several keys, so `engineAt` rides in the same
- * write. Without it, closing the gate and reopening it with a NEWER moment
- * re-armed a workspace default set weeks earlier -- every row that names
- * nothing went straight back to Codex without her saying so again, which is the
- * exact claim this value is supposed to make impossible, and the rollback
- * lifecycle is the thing the gate is FOR.
- *
- * AND THE SECOND CLAUSE, READ CORRECTLY, IS WHY AN ABSENT STAMP MEANS HONOURED.
- * `engineChoice` is hand-written into this file; a hand-written `engine` on the
- * line above it was put there by the same hand in the same act, so the two ARE
- * contemporaneous and there is nothing to be stale against. Only a default the
- * app wrote can carry a stamp, and only a stamped default can go stale — which
- * is also what keeps every config that exists today behaving exactly as it did.
- * `engineDefaultIsStale` below is the check.
- *
- * IT IS PARSED STRICTLY, WHICH IS NOT THE SAME AS PARSED. `Date.parse` reads
- * "1", "2026", "Sep 4 2026" and "2026/09/04" as real dates, so a bare parse
- * would let `"engineChoice": "1"` open the second engine. The shape is checked
- * first and everything else is off, because the safe answer is the one that has
- * to be the accident.
- */
+// The shape of a date somebody wrote down. `Date.parse` alone would accept "1"
+// or "2026", and `"engineChoice": "1"` must not open the second engine.
 const A_MOMENT = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
 
-/**
- * One strict parse, used by both moments in this file, so the two cannot come
- *  to disagree about what counts as a date somebody wrote down. */
 function momentIn(written) {
   if (typeof written !== 'string' || !A_MOMENT.test(written)) return null;
   const at = Date.parse(written);
   return Number.isFinite(at) ? at : null;
 }
 
+/**
+ * When the user opened the gate (`engineChoice` in zero.config.json), or null.
+ * It is a moment, not a flag, so an engine written on a row or as the default
+ * before it is not a choice made now and is ignored. It lives in the config
+ * rather than app state so every machine reading the same store agrees.
+ * main/supervisor.mjs `_engineFor` is the only place that turns it into the token.
+ */
 export function engineChoiceSince(config = {}) {
   return momentIn(config?.engineChoice);
 }
 
 /**
- * WHEN THE WORKSPACE DEFAULT WAS SET, read off `zero.config.json`, or null.
- *
- * Null means no stamp, and no stamp means a hand-written default — see the long
- * note above `engineChoiceSince`. It is the same strict parse for the same
- * reason: a claim that cannot be read is not a claim, so it reads as no stamp,
- * which is the hand-written case.
+ * When the app last wrote the workspace default (`engineAt`, written beside
+ * `engine` by `setWorkspaceSetting`), or null. Null means the default was typed
+ * into the file by hand, in the same act as `engineChoice`, so it is never stale.
  */
 export function engineDefaultSince(config = {}) {
   return momentIn(config?.engineAt);
 }
 
 /**
- * Whether the workspace default is one she set BEFORE the gate's current
- * moment: a setting from the build before the rollback, rather than a decision
- * she is making now.
- *
- * False when nobody has opted in, because there is no moment to be stale
- * against. False when the default is Claude Code, which asks for nothing the
- * gate withholds — the same rule `engineChoiceOnRowIsStale` follows below, and
- * for the same reason: discarding it could only ever move work TO the second
- * engine, which is the one direction the gate exists to prevent. False when
- * there is no stamp, which is a default typed beside the moment itself.
+ * Whether the workspace default was set before the gate's current moment.
+ * Never true for Claude Code: discarding that default could only move work onto
+ * the second engine.
  */
 export function engineDefaultIsStale(config = {}) {
   const since = engineChoiceSince(config);
@@ -236,33 +88,13 @@ export function engineDefaultIsStale(config = {}) {
 }
 
 /**
- * Whether the engine named on this row is one picked BEFORE she opened the
- * gate: an August row, rather than a decision she is making now.
- *
- * False when nobody has opted in, because there is no moment to be stale
- * against and the gate itself is what refuses then. False when the row names no
- * engine, or names one nothing recognises, because neither is asking for
- * anything and a warning on an ordinary row is noise on every row. True when
- * the row names an engine and there is no `wrote.engine.ts` at or after the
- * moment — which also covers an imported session and an old line with no
- * `wrote` map at all, where there is simply no evidence she chose anything.
- *
- * AND FALSE FOR A ROW THAT NAMES CLAUDE CODE, WHICH THIS ASKED WITH `isEngine`
- * AND GOT BACKWARDS. A row saying `engine: "claude"`, written before the moment,
- * was discarded as stale — and `engineFor` then fell through to `config.engine`,
- * which may be `codex`. So her explicit "run this on Claude Code" was read as no
- * choice at all and answered with the second engine, which is the precise
- * opposite of what staleness is for. `enginePicked` is the fix and it is the
- * whole of it: naming the DEFAULT asks for nothing the gate withholds, so there
- * is nothing to be stale about, and discarding it could only ever move work onto
- * the engine the gate was built to hold back.
+ * Whether the engine named on this row was written before the gate's moment.
+ * A row with no `wrote.engine.ts` counts as stale, since there is no evidence
+ * of a choice. A row naming Claude Code is never stale: discarding it would let
+ * `engineFor` fall through to a Codex workspace default.
  *
- * `wrote.engine.source` is deliberately NOT consulted. would be the stronger
- * rule, but CLAUDE.md is explicit that a ledger line names its own author as a
- * plain string and nothing checks it, so a source check would guard against an
- * accident and never against a hostile worker, while silently refusing whatever
- * a future picker happens to write. Who may write `engine` at all belongs to
- * the slice that draws one.
+ * `wrote.engine.source` is not consulted, because a ledger line names its own
+ * author as an unchecked string.
  */
 export function engineChoiceOnRowIsStale(item, config = {}) {
   const since = engineChoiceSince(config);
@@ -281,34 +113,14 @@ export function engineLabel(id) {
 }
 
 /**
- * Which engines this Mac can actually run, given what the finders found.
- *
- * `found` is a map of id to boolean. An engine whose binary is not on the
- * machine is not offered, because a picker that offers something that cannot
- * run is a picker that hands her a session that dies on arrival. Claude Code
- * is in the list even when it was not found, UNLESS Codex was: a Mac with only
- * Codex is offered only Codex (`homeEngine` below). With neither, the app
- * refuses to open an inbox and says so in its own words.
- *
- * UNGATED, AND THE INVARIANT IS THEREFORE SCOPED TO ROUTING. Say it plainly,
- * because the file must not claim more than the code delivers: this function,
- * `engineChoiceExists` and `enginePicked` will all happily describe a two-engine
- * Mac without anyone holding the token. A future renderer could draw a picker
- * out of them, and the gate would not stop it — she would be offered a choice
- * that `engineFor` then refuses, which is its own kind of lie.
- *
- * That is a deliberate trade and not an oversight. These three answer "what is
- * on this Mac" and "what did she pick"; they spawn nothing, and requiring a
- * capability token to answer a question about the filesystem buys nothing real.
- *
- * AND THE SLICE THAT DREW A PICKER ANSWERED FOR IT, 2026-09-04. There is
- * exactly one caller, `Supervisor#engineChoices`, and it asks
- * `engineChoiceSince` FIRST -- the same expression `_engineFor` derives the gate
- * token from -- so the offer and the routing are refused by the same fact and
- * cannot come apart. A Mac with Codex installed and no moment written answers
- * one engine here and Claude Code there. The renderer calls none of these: it
- * is handed the list on the snapshot. tests/a-codex-row-from-august-still-runs-on-claude.test.mjs
- * holds the caller list exactly, so the next one has to argue for itself here.
+ * Which engines this Mac can run, given `found` (id to boolean from the
+ * finders). Claude Code is listed even when not found, unless Codex was.
+ *
+ * This is ungated, like `engineChoiceExists` and `enginePicked`. Its one caller
+ * is `Supervisor#engineChoices`, which asks `engineChoiceSince` first, so the
+ * offer and the routing cannot disagree. The renderer gets the list on the
+ * snapshot. tests/a-codex-row-from-august-still-runs-on-claude.test.mjs pins the
+ * caller list.
  */
 export function availableEngines(found = {}) {
   const home = homeEngine(found);
@@ -316,13 +128,9 @@ export function availableEngines(found = {}) {
 }
 
 /**
- * WHAT RUNS WHEN NOBODY HAS CHOSEN, ON THIS MAC. Claude Code, unless this Mac
- * has said for certain that Claude Code is not here and Codex is. The app needs
- * one of the two, not both, so a Mac with only Codex runs everything on Codex.
- *
- * `found.claude` has to be an explicit `false`. A caller that never asked
- * (every call written before this, and every test config) leaves it undefined,
- * and that reads as Claude Code being here, which is what it always meant.
+ * What runs on this Mac when nobody has chosen: Codex only when `found.claude`
+ * is explicitly false and Codex was found. Undefined means a caller that never
+ * asked, and reads as Claude Code being here.
  */
 export function homeEngine(found = {}) {
   return found.claude === false && found.codex ? 'codex' : DEFAULT_ENGINE;
@@ -334,37 +142,13 @@ export function engineChoiceExists(found = {}) {
 }
 
 /**
- * THE RULE. Which engine one work item runs on, and it is deliberately narrow.
- *
- * The gate answers first: without `enabled: ENGINE_CHOICE_ENABLED` this is
- * Claude Code, whatever the row says and whatever the workspace says. That is
- * what holds the August rows described at the top of this file, and it means
- * the honest answer for any caller that has not been taught about the second
- * engine — including every caller written before it comes back — is the engine
- * she is running.
- *
- * Then her choice on the task, over the workspace default, which is hers to
- * set in Settings, over Claude Code. An engine named on a row whose binary is
- * not on this Mac falls back rather than dying: she may have chosen Codex on
- * her laptop and be reading the row on a machine without it, and a session
- * that never starts tells her nothing about why. That fallback is unchanged
- * and the gate is IN ADDITION to it, not instead of it — the binary is a fact
- * about this Mac, the gate is a fact about this build, and either one missing
- * is enough to answer Claude Code.
- *
- * AND A CHOICE FROM BEFORE SHE OPENED THE GATE IS NOT A CHOICE SHE IS MAKING.
- * When the config names the moment she opted in, a row whose `engine` predates
- * it reads as no choice at all and the workspace default answers instead. That
- * is `engineChoiceOnRowIsStale` above, and it is the whole of what makes the
- * opt-in mean "Codex may be chosen from now on" rather than "every row that
- * ever said codex is live". A caller that passes no such moment gets the old
- * rule unchanged, which is why every assertion written before this one still
- * holds -- but the single caller in the app that can open the gate derives the
- * token FROM that same value, so in her app the two cannot come apart.
+ * Which engine one work item runs on. A Mac with only Codex runs Codex.
+ * Otherwise, without `enabled: ENGINE_CHOICE_ENABLED` it is Claude Code. With
+ * it, the row's engine wins over the workspace default, each ignored if written
+ * before the gate's moment. An engine whose binary is not on this Mac falls back
+ * to Claude Code, since the row may have been chosen on another machine.
  */
 export function engineFor(item, { config = {}, found = {}, enabled } = {}) {
-  // ONE ENGINE ON THE MAC IS NOT A CHOICE, so the gate has nothing to guard.
-  // Without Claude Code, a row marked `claude` would only die on arrival.
   if (homeEngine(found) !== DEFAULT_ENGINE) return homeEngine(found);
   if (enabled !== ENGINE_CHOICE_ENABLED) return DEFAULT_ENGINE;
   const wanted = isEngine(item?.engine) && !engineChoiceOnRowIsStale(item, config) ? item.engine : null;
@@ -375,43 +159,20 @@ export function engineFor(item, { config = {}, found = {}, enabled } = {}) {
 }
 
 /**
- * Whether the engine on this row is one she chose, as opposed to the one it
- * would run on anyway. What makes the composer's footer stay open, the same
- * rule the level and the model follow (renderer/src/compose-footer.ts).
+ * Whether the row names an engine other than the default. The composer's footer
+ * stays open on it, like the level and the model (renderer/src/compose-footer.ts).
  */
 export function enginePicked(id) {
   return isEngine(id) && id !== DEFAULT_ENGINE;
 }
 
 /**
- * THE MODEL ON THIS ROW, OR NULL BECAUSE IT BELONGS TO THE OTHER HARNESS.
- *
- * THE MIRROR OF `codexModelRefusal`, WHICH ONLY EVER GUARDED ONE DIRECTION.
- * That one stops a Claude alias reaching a Codex run. Nothing stopped the
- * reverse, and the reverse happens BY ITSELF: `engineFor` above falls back to
- * Claude Code when Codex is not on this Mac -- which is correct and stays --
- * and `spawnPlan` then applied `item.model` without asking which engine wrote
- * it. Measured 2026-09-05 by reading the resolved plan: a row saying `engine:
- * "codex", model: "gpt-5.6-sol"` -- the slug her own config.toml names --
- * produced `claude -p <brief> --model gpt-5.6-sol`, which Claude Code has never
- * heard of. It dies on arrival and dies again on every retry.
- *
- * THE TWO FIELDS ARE ONE CHOICE AND THIS IS WHY. The composer's model list is
- * scoped to the engine (`engineModelChoices`, renderer/src/models.ts) because
- * the two vocabularies do not overlap at all: `opus` is an alias Claude Code
- * resolves, `gpt-5.6-sol` is an exact slug Codex takes. So a model word means
- * nothing without the engine beside it, and a row whose engine has changed
- * under it has no model, rather than one that reads across.
- *
- * NULL IS NOT A STAND-IN AND THE CALLER MUST NOT TREAT IT AS ONE. This says
- * "there is no model on this row for this run"; whether that means running on
- * the workspace's own model or refusing the run outright is the caller's
- * decision, and main/supervisor.mjs makes it -- it refuses, and says so on the
- * row, for the reason `codexModelRefusal` gives on the other side.
- *
- * A ROW THAT NAMES NO ENGINE IS UNTOUCHED, which is every row she has ever
- * written: there is no other harness in the sentence, so the model rides
- * exactly as it did.
+ * The row's model for a run on `engine`, or null when the row names a different
+ * engine. Claude and Codex model names do not overlap, so a Codex slug must not
+ * reach `claude --model` when `engineFor` falls back to Claude Code. This is the
+ * mirror of `codexModelRefusal`. Null means "no model for this run", and
+ * main/supervisor.mjs decides what to do with it. A row naming no engine keeps
+ * its model.
  */
 export function modelForEngine(item, engine) {
   const model = typeof item?.model === 'string' && item.model ? item.model : null;

package/shared/feedback.d.mts

@@ -12,3 +12,10 @@ export function feedbackPayload(p?: {
   files?: { name: string; type: string; data: string }[];
   app?: { version?: string; os?: string };
 }): { text: string; files: { name: string; type: string; data: string }[]; app: { version: string; os: string } };
+
+export function sendFeedback(p: {
+  url: string | null | undefined;
+  payload: { text: string; files: { name: string; type: string; data: string }[]; app?: { version: string; os: string } };
+  fetchImpl?: (url: string, init: RequestInit) => Promise<{ ok: boolean }>;
+  timeoutMs?: number;
+}): Promise<{ ok: boolean; error?: string }>;

package/shared/feedback.mjs

@@ -5,6 +5,7 @@
 //
 // Words, files, or both, and never nothing. The size limit keeps one request
 // well inside what the mail provider takes as attachments.
+import { Name } from './product-name.mjs';
 
 export const FEEDBACK_LIMITS = Object.freeze({
   text: 20_000,
@@ -42,3 +43,27 @@ export function feedbackPayload({ text = '', files = [], app = {} } = {}) {
     app: { version: String(app.version ?? ''), os: String(app.os ?? '') },
   };
 }
+
+// Answers { ok: true } or { ok: false, error } with the error as a sentence.
+// It never throws, so the card always has something to say. The Mac sends
+// through it (main/feedback.mjs) and so does the phone website (cloud-bridge.ts).
+export async function sendFeedback({ url, payload, fetchImpl = globalThis.fetch, timeoutMs = 60_000 }) {
+  if (!url) return { ok: false, error: `Feedback is not set up in this copy of ${Name}.` };
+  // Checked again here, off the bytes that would actually travel, since the
+  // card is not the last word on what leaves the device.
+  const sized = (payload?.files ?? []).map((f) => ({ size: Math.floor((String(f?.data ?? '').length * 3) / 4) }));
+  const check = checkFeedback({ text: payload?.text, files: sized });
+  if (!check.ok) return { ok: false, error: check.reason };
+  try {
+    const res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (res?.ok) return { ok: true };
+    return { ok: false, error: 'It did not send. Try again in a moment.' };
+  } catch {
+    return { ok: false, error: 'It did not send. Check your connection and try again.' };
+  }
+}

package/shared/first-run-practice.mjs

@@ -267,47 +267,40 @@ export const PRACTICE_ROWS = [
  *  off the screen by `walkRows` until the tour. Each `state` is the column it
  *  lands in, read off the row by the app's own rules and not by this file:
  *
- *  * `needs`: an agent finished, or stopped on a question. Needs you. Only on
- *    the board, never in the tour, because the tour opens on "Your inbox is
- *    now empty" and these would make that untrue.
  *  * `working`: sent and not finished. In progress.
  *  * `scheduled`: set for tomorrow morning. Scheduled.
  *
  *  None is finished, so "Everything you finished is kept here" stays true of
- *  the Closed tab. */
+ *  the Closed tab.
+ *
+ *  AND NOT ONE OF THEM MAY EVER NEED YOU (2026-10-24). Two were `needs`, held
+ *  back from the tour and let through from the board on, so pressing B put two
+ *  rows into a Needs you the tour had just called empty. The same two pieces of
+ *  work are still here in states that ask nothing of anybody, which keeps both
+ *  rules: something in every column, and the inbox stays at zero. */
 export const PRACTICE_BACKDROP = [
   {
-    state: 'needs',
+    state: 'working',
     kind: 'task',
-    title: 'Booked the train for the offsite.',
+    title: 'Book the train for the offsite.',
     body: 'Book train tickets for the team to the offsite on Thursday morning.',
     trace: [
       '[Read] Offsite plan.docx',
       '[Read] Team contacts.xlsx',
       'Twelve people, all leaving from the city on Thursday morning.',
-      '[Write] Train booking.pdf',
+      'Comparing the 8:10 and the 9:10, which is the last one that still gets everybody there in time.',
     ],
-    result: 'Twelve seats on the 8:10 on Thursday, all in one carriage. The tickets are in the offsite folder.',
     agoMs: 9 * 60_000,
   },
   {
-    state: 'needs',
-    kind: 'question',
-    title: 'Should the welcome pack go out Monday or Wednesday?',
-    body: 'Send the welcome pack to the two new starters, and check the day with me first.',
-    trace: [
-      '[Read] Welcome pack.docx',
-      '[Read] Team calendar.ics',
-      'One starter begins on Monday and the other on Wednesday.',
-    ],
-    result: [
-      'One new starter begins Monday and the other Wednesday. Sending both on Monday means nobody waits.',
-      '',
-      '## Options',
-      '1. Monday, for both (recommended)',
-      '2. On each person\'s first day',
-    ].join('\n'),
+    state: 'scheduled',
+    kind: 'task',
+    title: 'Send the welcome pack to the two new starters.',
+    body: 'Send the welcome pack to the two new starters on Monday, before either of them begins.',
+    trace: [],
     agoMs: 26 * 60_000,
+    // Monday morning, counted from when the practice project is made.
+    inMs: 66 * 3_600_000,
   },
   {
     state: 'working',

package/shared/harness-definitions.mjs

@@ -13,6 +13,14 @@ export const HARNESS_DEFINITIONS = freeze([
     installer: { shell: '/bin/bash', url: 'https://claude.ai/install.sh', pipe: 'bash' },
     loginArgs: ['auth', 'login', '--claudeai'], statusArgs: ['auth', 'status', '--json'],
     credentialFiles: ['.claude.json', '.credentials.json'],
+    // THE OLDEST CLAUDE CODE THE WORKER LINE BELOW RUNS ON. Measured 2026-10-15
+    // by running the app's own line against npm releases on a stand-in model:
+    // 2.1.71 (2026-03-06) is the first that takes `--permission-mode auto`,
+    // which every worker is started with; 2.1.70 and older die in under a
+    // second on it. Every other flag is older still (`--effort` arrived after
+    // 2.1.8, `--include-partial-messages` after 1.0.90). shared/spawn-trouble.mjs
+    // names it when an older one refuses the line.
+    minVersion: '2.1.71',
     // HOW A WORKER IS STARTED, AS DATA. This was six hardcoded flag names in
     // main/supervisor.mjs, which made the cheapest possible new engine — one
     // that speaks this same stream-json and differs by a binary and the