cawdev-cli 1.0.4-beta → 1.0.5-beta

package/lib/agents.mjs

@@ -0,0 +1,27 @@
+/**
+ * The coding agents a machine can spawn, spelled once.
+ *
+ * <p>Three CLIs, each a command on the PATH: Claude Code, Antigravity and
+ * Codex. The setup walk, `cawdev config agent`, the config screen and the
+ * daemon all ask "which agent is this command" and "what is it called", and
+ * the answer was a `=== 'agy' ? … : 'Claude Code'` in five places — right for
+ * two agents and silently wrong for a third.
+ */
+
+/** Every agent, in the order they are offered. */
+export const KNOWN_AGENTS = ['claude', 'agy', 'codex'];
+
+const LABELS = { claude: 'Claude Code', agy: 'Antigravity CLI', codex: 'Codex CLI' };
+
+/** Which agent a configured command is — by its name, the rule `agentCommands` always used. */
+export function agentOfCommand(command) {
+  const name = String(command ?? '').split('/').pop();
+  if (name.endsWith('agy')) return 'agy';
+  if (name.endsWith('codex')) return 'codex';
+  return 'claude';
+}
+
+/** What a person calls the agent behind a command. */
+export function agentLabel(command) {
+  return LABELS[agentOfCommand(command)];
+}

package/lib/ansi.mjs

@@ -102,6 +102,8 @@ export function painter(depth = colourDepth()) {
     text: ink([0xd4, 0xd0, 0xcc], 37),
 
     bold: wrap('\x1b[1m'),
+    /** Bold AND underlined — a fact the eye should find first (advanced mode's agent · model). */
+    strong: wrap('\x1b[1;4m'),
     dim: wrap('\x1b[2m'),
     reverse: wrap('\x1b[7m'),
     /** Plain, for a value that should not compete with the label beside it. */

package/lib/codex.mjs

@@ -0,0 +1,214 @@
+/**
+ * OpenAI's Codex CLI as a third agent — the arguments a spawn is given and the
+ * events it prints, and nothing that touches a process.
+ *
+ * In lib/ for `code-map.mjs`'s reason: the hard parts are a command line and a
+ * stream, both testable without a daemon, a platform or a model. The spawn
+ * itself is `spawnCodex` in runner.mjs, beside `spawnAntigravity`.
+ *
+ * <p>Every flag and field here was checked against the real CLI (0.155) by
+ * hand rather than read off documentation:
+ *
+ * <ul>
+ * <li>`codex exec --json` prints JSONL: `thread.started` (carries the id
+ *   `resume` takes), `item.started`/`item.completed` for `agent_message`,
+ *   `command_execution`, `mcp_tool_call`, `file_change`…, then
+ *   `turn.completed` with `usage` or `turn.failed` with `error`.
+ * <li>In `exec` the approval policy is NEVER, so an MCP call is refused
+ *   outright ("requires approval, but approval policy is never") unless its
+ *   server says `default_tools_approval_mode = "approve"`. With it, cawdev's
+ *   own server is reached even under `--sandbox read-only`, network included:
+ *   the sandbox is the SHELL's, not the MCP servers'.
+ * <li>`enabled_tools` really narrows a server — a tool left out is not offered
+ *   at all — and `disabled_tools` takes one away.
+ * <li>`env_vars` forwards named variables from Codex's own environment to a
+ *   server, which keeps the run's token off the command line, where `ps`
+ *   would show it to anybody on the machine.
+ * <li>`shell_environment_policy.set` blanks a variable for every command the
+ *   model runs — and `exclude` does NOT (tried: `echo $CAWDEV_TOKEN` still
+ *   printed it). The token reaches cawdev's server through `env_vars`, which
+ *   reads Codex's own environment and not the shell's, so blanking it for the
+ *   shell costs the server nothing.
+ * <li>`resume` takes the exec-level options BEFORE the subcommand:
+ *   `codex exec --json -s read-only resume <id> -`; after it, `-s` is refused.
+ * <li>`--strict-config` refuses a field it does not know, so a key misspelled
+ *   here fails the spawn out loud instead of being ignored.
+ * </ul>
+ */
+
+/** The `mcp__cawdev__` prefix off a Claude Code tool list, keeping cawdev's own names only. */
+export function cawdevToolNames(tools) {
+  const prefix = 'mcp__cawdev__';
+  return [...new Set((Array.isArray(tools) ? tools : [])
+    .filter((tool) => typeof tool === 'string' && tool.startsWith(prefix))
+    .map((tool) => tool.slice(prefix.length)))];
+}
+
+/**
+ * A value as TOML, which is what `-c key=value` parses.
+ *
+ * <p>A JSON string is a TOML basic string for everything JSON escapes; DEL is
+ * the one control character JSON leaves alone and TOML refuses.
+ */
+export function tomlValue(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(tomlValue).join(', ')}]`;
+  }
+  if (typeof value === 'boolean' || typeof value === 'number') {
+    return String(value);
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).map(([key, each]) => `${tomlKey(key)} = ${tomlValue(each)}`);
+    return `{ ${entries.join(', ')} }`;
+  }
+  return JSON.stringify(String(value ?? '')).replace(/\u007f/g, '\\u007f');
+}
+
+function tomlKey(key) {
+  return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlValue(String(key));
+}
+
+/**
+ * The command line for one Codex turn. The prompt goes on stdin (`-`).
+ *
+ * @param options.sandbox `read-only` — the OS refuses every write the shell
+ *   attempts — or `bypass`, which is `--dangerously-bypass-approvals-and-sandbox`
+ *   and is only ever passed where the machine has allowed everything.
+ * @param options.servers `[{ name, command, args, env, envVars, enabledTools,
+ *   disabledTools }]`, each approved, since nobody is there to approve a call.
+ * @param options.hideFromShell variables blanked for the model's own commands.
+ */
+export function codexArgs({
+  model = null, effort = null, sandbox, resumeId = null, servers = [], hideFromShell = [],
+}) {
+  if (sandbox !== 'read-only' && sandbox !== 'bypass') {
+    throw new Error(`codexArgs: sandbox must be read-only or bypass, not ${sandbox}`);
+  }
+  // `--ignore-user-config` is `--setting-sources ''` for this CLI: the
+  // operator's own ~/.codex/config.toml can add MCP servers, hooks and an
+  // approval reviewer, and none of that may widen what a run was given. The
+  // sign-in is untouched — it is read from CODEX_HOME either way.
+  const args = ['exec', '--json', '--strict-config', '--ignore-user-config'];
+  args.push(...(sandbox === 'bypass'
+    ? ['--dangerously-bypass-approvals-and-sandbox']
+    : ['--sandbox', 'read-only']));
+  if (model) {
+    args.push('--model', model);
+  }
+  if (effort) {
+    args.push('-c', `model_reasoning_effort=${tomlValue(effort)}`);
+  }
+  if (hideFromShell.length) {
+    args.push('-c', `shell_environment_policy.set=${tomlValue(
+      Object.fromEntries(hideFromShell.map((name) => [name, ''])))}`);
+  }
+  for (const server of servers) {
+    const key = `mcp_servers.${tomlKey(server.name)}`;
+    args.push('-c', `${key}.command=${tomlValue(server.command)}`);
+    if (server.args?.length) {
+      args.push('-c', `${key}.args=${tomlValue(server.args)}`);
+    }
+    if (server.env && Object.keys(server.env).length) {
+      args.push('-c', `${key}.env=${tomlValue(server.env)}`);
+    }
+    if (server.envVars?.length) {
+      args.push('-c', `${key}.env_vars=${tomlValue(server.envVars)}`);
+    }
+    if (server.enabledTools) {
+      args.push('-c', `${key}.enabled_tools=${tomlValue(server.enabledTools)}`);
+    }
+    if (server.disabledTools?.length) {
+      args.push('-c', `${key}.disabled_tools=${tomlValue(server.disabledTools)}`);
+    }
+    args.push('-c', `${key}.default_tools_approval_mode="approve"`);
+  }
+  if (resumeId) {
+    args.push('resume', resumeId);
+  }
+  args.push('-');
+  return args;
+}
+
+/** A tool result's text, whatever shape the MCP server gave it. */
+function resultText(result) {
+  const content = result?.content;
+  if (Array.isArray(content)) {
+    const text = content.map((each) => each?.text ?? '').filter(Boolean).join('\n');
+    if (text) return text;
+  }
+  return result == null ? '(no output)' : JSON.stringify(result);
+}
+
+/**
+ * One line of `codex exec --json`, as what the transcript and the run need.
+ *
+ * <p>Returns `{ sessionId?, lines: [{ kind, body }], usage?, failed?, error?, ended? }`.
+ * `ended` is true on `turn.completed` — the turn ending, which is the whole of
+ * what a stage is judged by. `failed` is `turn.failed`'s sentence; `error` a
+ * top-level error's, which may be passing. An event this version does not know
+ * yields nothing.
+ */
+export function translateCodexEvent(event) {
+  const out = { lines: [] };
+  const item = event?.item ?? {};
+  switch (event?.type) {
+    case 'thread.started':
+      out.sessionId = event.thread_id ?? null;
+      break;
+    case 'item.started':
+      if (item.type === 'command_execution') {
+        out.lines.push({ kind: 'TOOL', body: `Bash(${item.command ?? ''})` });
+      } else if (item.type === 'mcp_tool_call') {
+        out.lines.push({
+          kind: 'TOOL',
+          body: `mcp__${item.server}__${item.tool}(${JSON.stringify(item.arguments ?? {})})`,
+        });
+      }
+      break;
+    case 'item.completed':
+      if (item.type === 'agent_message' && item.text) {
+        out.lines.push({ kind: 'ASSISTANT', body: item.text });
+      } else if (item.type === 'command_execution') {
+        const output = String(item.aggregated_output ?? '').slice(0, 4000);
+        out.lines.push({
+          kind: 'TOOL_RESULT',
+          body: output || `(exit ${item.exit_code ?? '?'})`,
+        });
+      } else if (item.type === 'mcp_tool_call') {
+        out.lines.push({
+          kind: 'TOOL_RESULT',
+          body: item.error
+            ? `failed: ${item.error.message ?? JSON.stringify(item.error)}`
+            : resultText(item.result).slice(0, 4000),
+        });
+      } else if (item.type === 'file_change') {
+        const changes = (item.changes ?? [])
+          .map((each) => `${each.kind ?? 'update'} ${each.path ?? ''}`.trim());
+        out.lines.push({ kind: 'TOOL', body: `Edit(${changes.join(', ') || 'files'})` });
+      } else if (item.type === 'error' && item.message) {
+        out.lines.push({ kind: 'SYSTEM', body: item.message });
+      }
+      break;
+    case 'turn.completed':
+      out.ended = true;
+      out.usage = {
+        input: Number(event.usage?.input_tokens) || 0,
+        output: Number(event.usage?.output_tokens) || 0,
+      };
+      break;
+    case 'turn.failed':
+      out.failed = event.error?.message ?? 'Codex reported the turn failed.';
+      out.lines.push({ kind: 'SYSTEM', body: out.failed });
+      break;
+    case 'error':
+      // NOT `failed`: a top-level error is also how a retried stream says
+      // "Reconnecting… 2/5". Only `turn.failed` ends a turn badly; this is
+      // kept as the last thing it said, for when nothing better arrives.
+      out.error = event.message ?? 'Codex reported an error.';
+      out.lines.push({ kind: 'SYSTEM', body: out.error });
+      break;
+    default:
+      break;
+  }
+  return out;
+}

package/lib/harness-prompt.mjs

@@ -48,10 +48,13 @@ export function harnessPrompt({
   //
   // R161. A REQUIRED one is named FIRST and in its own block. Two lists rather
   // than one annotated list, because a `(required)` suffix on a line in a list
-  // of twelve is a detail; a heading is an instruction. The AS_NEEDED wording
-  // below is byte-for-byte what it was — when a project requires nothing, and
-  // that is every project until somebody says otherwise, this function returns
-  // exactly what it returned before the entry.
+  // of twelve is a detail; a heading is an instruction. When a project
+  // requires nothing at all — every project until somebody says otherwise —
+  // this function still returns exactly what it returned before the entry:
+  // the AS_NEEDED wording below has since been extended once, by i257, but a
+  // project with no `mustExperts`/`mustSkills`/`mustServers` never reaches
+  // either block, so the claim is about that project, not about the wording
+  // itself staying fixed forever.
   const reach = [];
   const requiredOf = (list) => (list ?? []).filter((each) => each.required);
   const optionalOf = (list) => (list ?? []).filter((each) => !each.required);
@@ -63,12 +66,17 @@ export function harnessPrompt({
   if (mustExperts.length) {
     reach.push('**Experts you MUST use** — this project requires each of these. Delegate '
       + 'with the `Agent` tool, `subagent_type` exactly as written, before this stage is '
-      + `finished.\n${lines(mustExperts)}`);
+      + 'finished. This stage is one process and ends when your turn does: a backgrounded '
+      + '`Agent` call that has not reported back by then is lost, and so is anything gated on '
+      + 'it. Pass `run_in_background: false` and wait for each of these in the same turn — do '
+      + 'not say "I\'ll report back" and stop.\n'
+      + `${lines(mustExperts)}`);
   }
   if (mayExperts.length) {
     reach.push('**Experts** — delegate with the `Agent` tool, `subagent_type` exactly as '
       + 'written. Use one whenever its description fits the step you are on; they were '
-      + 'chosen for this project.\n'
+      + 'chosen for this project. The same rule applies: a call backgrounded past the end of '
+      + 'your turn never comes back.\n'
       + lines(mayExperts));
   } else if (!mustExperts.length && cannotDelegate?.length) {
     reach.push(`**Experts** — ${cannotDelegate.join(' ')}`);

package/lib/runner-config.mjs

@@ -25,7 +25,8 @@
  * Adding a key that IS captured would make the daemon claim it applied
  * something it did not, which is worse than saying restart.
  */
-export const HOT_SWAPPABLE = Object.freeze(['agentCommands', 'grantable', 'acceptsRulesFromConsole']);
+export const HOT_SWAPPABLE = Object.freeze(['agentCommands', 'grantable', 'acceptsRulesFromConsole',
+  'autoWorkspaces']);
 
 /**
  * The legacy spelling of one key, read as the current one — so a config that
@@ -60,7 +61,7 @@ export function restartNeededFor(booted, file) {
   return [...keys]
     .filter((key) => !HOT_SWAPPABLE.includes(key))
     .filter((key) => canonical(before[key]) !== canonical(after[key]))
-    .sort();
+    .sort((a, b) => a.localeCompare(b));
 }
 
 /** Applied, or would be on a SIGHUP: the hot-swappable keys that differ. */

package/mcp/server.mjs

@@ -2011,6 +2011,9 @@ function formatQualityReading(reading, branch) {
         `new coverage ${percent(row.newCoverage)}`,
       ];
       if (row.analysedAs === 'MAIN') parts.push('analysed as the main branch, not under its own name');
+      if (row.analysedAs === 'PROJECT') {
+        parts.push('analysed as its own SonarQube project; new = on lines this branch changed; no gate');
+      }
       if (row.headSha) parts.push(`at ${row.headSha.slice(0, 7)}`);
       if (row.dashboardUrl) parts.push(row.dashboardUrl);
       lines.push(`Branch ${asked.branch}: ${parts.join(' · ')}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cawdev-cli",
-  "version": "1.0.4-beta",
+  "version": "1.0.5-beta",
   "description": "cawdev's terminal client and runner daemon — zero dependencies, on purpose",
   "type": "module",
   "bin": {

package/runner/README.md

@@ -101,7 +101,7 @@ with the window — there `q` stops it, and asks first when sessions are live.
 machine is configured, most changes are smaller than that. **Inside the
 terminal, press `c`** (or type `/config`): a picker over what this machine does
 — add a project, add a workspace, each agent with its current state ("Disable
-claude", "Enable agy"), the console-rules switch, and the config itself with the
+claude", "Enable codex"), the console-rules switch, and the config itself with the
 token cut short. Every row is one of the shell commands below, driven through
 the terminal's own line editor and picker; `esc` anywhere in a step changes
 nothing. The screen edits the file the daemon says it booted from (the hello
@@ -126,7 +126,7 @@ is for scripts and for a machine with no daemon to attach to:
 cawdev config                          a menu, the same Select widget as everywhere else
 cawdev config add-project              serve one more project you can write to
 cawdev config add-workspace            another checkout for a project already served
-cawdev config agent enable|disable <claude|agy>
+cawdev config agent enable|disable <claude|agy|codex>
 cawdev config rules on|off             accept permission rules from the console — R126
 cawdev config show                     this machine's config, token redacted
 ```
@@ -331,6 +331,166 @@ browser anywhere and the terminal collects the session when you approve.
 error — it is what an expired session looks like, and the answer is the same as
 having none.
 
+### Advanced mode: one window per session
+
+`/advanced-mode` splits the terminal the way emacs does: **one window per
+session** this machine is running — or ran since you attached — above **the
+prompt, which stays at the bottom** the way a shell's does. Each window's title says what kind of
+session it is (`plan`, `dev`, `review`, `ask`…), where it stands, the card and
+the project, and its body is that session's output as it arrives. A frame's
+colour is its session's state — **red while it runs, green once it finished**
+(a plan planned, a dev developed), amber if it stopped any other way — and
+the focused window is drawn in heavy lines; `tab` and `shift+tab` move the focus, `1`–`9`
+jump to a window, and `enter` prompts the focused session exactly as it does
+outside the mode. `/advanced-mode` again (or `/advanced-mode off`) leaves.
+
+It is drawn on the terminal's **alternate screen**, like nano or emacs, and
+holds still the way they do: auto-wrap is off, so nothing ever scrolls the
+screen, and the wheel is sent to the program as arrow keys instead of sliding
+the terminal up. The normal screen and its scrollback are exactly as you left
+them — R81's reason
+for printing into the scrollback still holds, and this mode is something you
+ask for rather than the default. On the way out, what the watched session said
+meanwhile is laid into the scrollback, so nothing was lost by watching it here.
+
+**The PLANNED cards run across the top, grouped by project** — a line with
+each project's name over its cards and a rule between two projects, every
+project this machine serves included ("nothing planned" is an answer) — one
+small box each, titled with the card and its status — `R3 (Planned)` — the cards of
+every project this machine serves that are ready to be developed, read again
+every thirty seconds. **`d`** lists them and develops the one you pick, on this
+machine and on the card's own branch; `/new dev` with nothing after it does the
+same anywhere, and `/new dev R3` goes straight to one.
+
+**Four windows at most.** Past four, the rest are named on one line above the
+prompt — number, kind, state, card, in the state's colour — and `tab` (or the
+number) onto one brings it up in place of another. The focused session always
+has a window, then the ones still running, then the ended ones, each most
+recently looked at first.
+
+A window stays up when its session ends, and its last line says what can be
+done next:
+
+- **`/develop`** on a finished plan starts the development of its card, on
+  this machine (the branch is the card's own).
+- **`/pr`** on a finished session that wrote a branch opens its pull request
+  (`POST runs/{id}/pull-request` — through the card's work item, or from the
+  run itself for a session started from a sentence): this machine pushes the
+  branch if origin does not have it and runs `gh pr create` (so `gh` has to be
+  installed and signed in here). The POST answers with the workspace REQUEST,
+  and the terminal follows it (`GET /api/runners/{id}/workspace-requests/{id}`)
+  to its result: the URL — which the daemon confirms with `gh pr view` after
+  `gh pr create`, so "made" is the host's word and not gh's — or why there is
+  none, printed in full (no `gh` comes with its install line and the compare
+  link to open it by hand). It watched the run's `prUrl` before, which a
+  failure never writes, and said "asked for…" for as long as it was open.
+  A checkout cloned on demand is served like any other: the set of paths a
+  request may name is read per request, not taken at boot.
+- **`/continue`** on a failed or stopped session is the console's *Carry on*,
+  on this machine (`POST runs/{id}/carry-on` with this runner): the same run
+  re-queued, its window coming back to life when the daemon takes it. A
+  session that stopped BEFORE this terminal attached — the daemon forgets a
+  run as it ends, so after a restart nothing here knew of it — is found on
+  attach and on sign-in (`findStopped`: the first page of each served
+  project's runs, kept when `carriesOnHere` — yours, `canCarryOn`, and its
+  checkout on this machine or none), listed in the scrollback, and given a
+  window that opens on why it stopped.
+- **`/open`** opens the pull request in your browser.
+- **`/drop`** deletes the checkout the session was cloned into, when it was one
+  made on demand (below): asked first, naming the path, and refused while a
+  run is in it or holds it, with uncommitted files, or with a commit origin
+  does not have. The checkouts in the config are never offered — a project
+  always keeps them.
+- **`/close`** takes the window away.
+
+**`/new`** starts a session from the prompt, aimed at this machine so its
+window opens here: `/new plan R3`, `/new dev R3`, `/new ask <question>` — or a
+task in words with no card: `/new plan add a CSV export of the invoices` writes
+its card first and plans it (R150), and `/new dev fix the sort on the client
+list` writes its card too (`cardTitleFor`: the sentence, cut between words
+near a hundred characters, the whole text in the body) and then develops it
+exactly as `/new dev R12` would — a number, a work item on the development
+board, a branch of its own, and the card session's instruction to commit. It
+was a manual session on a `task-…` branch with no card, which never reached
+the board and was never told to commit. A card reference on its own is that card; anything
+else is the task in words. **The project is always asked** — a list of what
+this machine serves — unless the command names it with `@project`, or
+advanced mode is narrowed to ONE project (`/projects`), which is a choice
+already made rather than a guess. Never guessed from the focused window, nor
+from a machine serving just one, since a session on the wrong project is a
+card planned or a branch cut in the wrong repository. `/new dev` alone and `d` list the planned cards of every project,
+each with its own, so they ask nothing more. A usage window over this machine's threshold is refused in a
+sentence; `--anyway` starts it regardless, the same decision the console's
+panel asks for. All four commands need you signed in (`/login`), and they work
+outside advanced mode too, on the session you are watching.
+
+**Which projects it shows is yours to pick.** `/advanced-mode` on a machine
+serving several projects opens a picker with every one ticked — space (or a
+digit) ticks and unticks, `a` all or none, enter confirms — and only the
+projects ticked are drawn: their windows, their roadmap on top, and the ones
+`/new` asks between. `/advanced-mode @saasng @ngsign` names them and asks
+nothing; `/projects` asks again from inside the mode; `/reload` keeps the
+pick. A prompt never talks to a session of a project that is not shown.
+
+**Across the top, the roadmap** (`roadmapStrip`): every project this machine
+serves as a small board — Considering, Planned, In development, Merged side
+by side, one line per card, `●` on a card with a session running now;
+Shipped and Declined, which only grow, are counts beside the project's name,
+as on the console's board. As tall as the fullest column, never more than a
+third of the screen, and gone before the windows are on a short terminal.
+When the room runs out it is SAID: a column ends in `+N more`, empty columns
+go first when the width does, then whole columns (Merged, then Considering,
+then Planned — In development stays longest), named in the header as
+`merged 3 hidden`, then projects, counted as `+N projects`. Read every 30 s.
+
+**A window says which agent and which model** — `Claude · Opus 5.5`,
+`Codex · GPT-5-codex` — bold and underlined at the head of its second line
+(`agentModelFor`, `modelLabel`). A live session's is the daemon's word, what
+it actually spawned: the model asked for, replaced by the one Claude Code
+announces on `init`, and per STAGE on a walked run, since each stage is its
+own process. An ended one's is the platform's. No model named reads
+`default model` — the CLI's own choice — rather than a guess.
+
+**A dev window says where it is working**: its second line is the project and
+the absolute path of the checkout (`subtitleFor`) — on a machine with
+`saasng` and its `-auto-N` clones, the one directory to open. Cut from the
+left when narrow, so the end of the path survives.
+
+**The prompt shows what is open, not what was.** A question is the prompt's
+banner alone, whole and wrapped between words, and it goes the moment it is
+answered — here or in the console. A permission request's lines are tagged
+with it (`sayAbout`) and leave when it is decided.
+
+### Checkouts made on demand: `autoWorkspaces`
+
+`"autoWorkspaces": 3` in the machine's config lets the daemon CLONE up to three
+more checkouts of a project by itself, when a coding run would otherwise wait
+for "no free workspace" — so `/new dev R4` starts while R3 is still being
+developed. Absent or 0 is none, as it has always been. The clone sits beside
+the project's first checkout as `<first>-auto-2`, `-auto-3`…; it is a local
+clone of the first (no credential, no download) with `origin` put back to the
+project's remote. Nothing is written to the config: the daemon finds these by
+their name at boot and on SIGHUP, so deleting one — `/drop`, or by hand — is
+the whole of removing it. A clone and not a `git worktree`, on purpose: the
+daemon's reset checks the default branch out, which git refuses in a second
+worktree. Changed without a restart, like `agentCommands`.
+
+### `/reload`
+
+Quitting and starting again, in one word — for when the client's code changed
+on disk. The same command line runs again in a fresh process. When nothing is
+running here the runner is stopped first (as `q` does), so the relaunch starts
+it on the new code too; when sessions are live it is kept, and the terminal
+says so — restarting it would end them. Under `runner.mjs --attach` the runner
+is the terminal's own process, so `/reload` says to quit and start again.
+
+It comes back **as you left it**: advanced mode if it was on, the same window
+focused and the same session watched, the daemon's log shown or not, and the
+windows of sessions that had ended — with their `/develop` and `/pr` — except
+the ones you closed. The state travels to the new process in
+`CAWDEV_RELOAD_STATE`, which that process reads once and removes, so nothing it
+spawns inherits it.
+
 ### Where the socket is
 
 `~/.cawdev/run/<runner name>.sock`, in a `0700` directory, removed when the
@@ -370,6 +530,23 @@ How many coding runs go at once is `min(workspaces, maxSessions)`. A run that
 waits now says **"no free workspace in cawdev (2 here, all busy)"** instead of
 "that project already has a run here", which was a proxy for it.
 
+**A free checkout with uncommitted work in it is not preferred over a clean
+one** (R71/i258). A coding run with no pinned checkout and no free preferred
+one now takes the first free checkout whose tree reads clean, checking each
+free checkout in `workspaces` order until one does. It only falls back to a
+free checkout somebody stranded work in — and today's *Start anyway* flow —
+when every free checkout of that project is dirty; the log says so when it
+happens. A *preferred* checkout (R212) is still taken whether it is clean or
+not: it is the checkout the branch last ran in, so its uncommitted work is
+plausibly that branch's own.
+
+**Unless the run asked to wait for a clean one instead** (`waitForClean`,
+R270). Then a preferred checkout is taken only when it reads clean, and when
+nothing free reads clean the run is left queued — with a reason saying so —
+rather than falling back to the first free checkout regardless. See "Prepares
+the working copy" below for where that flag comes from and what the daemon
+says about knowing it.
+
 **This number caps coding and nothing else** (R70). `ASK`, `ROADMAP`, `AUDIT`
 and `SCOPE` runs take no workspace, so a project whose checkouts are all busy
 still starts a question, an entry-writing session, an audit and a scoping
@@ -599,7 +776,24 @@ files at all. R47 removes the need for this by giving each run a workspace.
    uncommitted before the run is started, and the decision arrives with the
    claim as `allowDirty`. Without it the runner still refuses, with the file
    list, and fails the run saying so: a run that arrives with no flag is one
-   nobody was warned about.
+   nobody was warned about. **Except when the dirt is the branch's own**: the
+   platform NAMED the checkout (a carried-on run's held workspace, R80, or a
+   pinned work item's next run, R86) and it is already on the run's branch.
+   Then the work is kept and not cleaned — refusing it made every *Carry on*
+   a second failure about work the run itself had written.
+
+   **Or the run may have said, before it got this far, to wait instead**
+   (`waitForClean`, R270) — the console's third way out of the dirty-checkout
+   panel, alongside *Start anyway* and *Cancel*. That is decided earlier, in
+   `pickWorkspace`, at poll time: with `waitForClean` set, the preferred
+   checkout is taken only when it reads clean, and when nothing free reads
+   clean the run is left queued with a reason rather than claimed at all — so
+   by the time a claim reaches this step, the checkout it names is already
+   clean and this whole paragraph does not apply. The daemon says
+   `waitForClean: true` in its capabilities, the same way it says
+   `baseBranches: true`, and an older daemon that does not is not offered such
+   a run — the platform tells it apart rather than letting it take a dirty
+   checkout the person explicitly asked it not to.
 
    With it, the edits are **carried onto the branch** — stashed, checked out,
    popped (R57). `git checkout` refuses outright when a locally modified file
@@ -729,12 +923,34 @@ that reaches the server by another name than the platform does (a LAN
 hostname), and `timeoutSeconds` (600) bounding the scan and the wait.
 
 **Community Edition.** A server that refuses `sonar.branch.name` — every
-Community Edition — is *skipped by default*: the reading carries an error
-saying so, and nothing is analysed. `"whenBranchesRefused": "main"` in the
-block opts into the fallback, which analyses the branch as the project's
-**main** analysis and marks the reading `MAIN` with a warning. Understand what
-that trades: the project's own dashboard, and the platform's project reading
-with it, then describe whichever branch scanned last. Nothing opts in for you.
+Community Edition without the plugin below — is *skipped by default*: the
+reading carries an error saying so, and nothing is analysed.
+`"whenBranchesRefused"` in the block opts into one of two fallbacks; `skip`
+stays the default and nothing opts in for you.
+
+- `"main"` re-scans the branch as the project's **main** analysis and marks
+  the reading `MAIN` with a warning. Understand what that trades: the
+  project's own dashboard, and the platform's project reading with it, then
+  describe whichever branch scanned last.
+- `"project"` scans the branch as its **own scratch SonarQube project**
+  instead — `<key>:branch:<branch>-<hash>`, overwritten on each run of the
+  branch, and never touching the project's own dashboard. A fresh project has
+  no new-code period, so "new" is redefined as *on a line this branch
+  changed*; the reading is marked `PROJECT`, its gate is always `NONE`
+  (nothing to gate a scratch project on), and there is no new-code coverage.
+  This needs the scanner's token to hold **Create Projects** on the server —
+  check its default project visibility too, since *public* would publish the
+  code. cawdev never deletes these scratch projects; cleaning them up is the
+  operator's own housekeeping.
+
+The project itself can say which of these it needs: its Settings →
+SonarQube card offers *Developer Edition or above (or Community with the
+[sonarqube-community-branch-plugin](https://github.com/mc1arke/sonarqube-community-branch-plugin)
+installed)*, *Community Edition*, or *Not sure — find out on the first scan*.
+Set correctly, the daemon skips the doomed branch attempt and goes straight
+to the chosen fallback; left at "not sure", behaviour is exactly as above.
+**Restart the daemon after upgrading it to use `"project"`**: an older
+runner does not know the value and refuses to boot with it in its config.
 
 **A failed scan never fails a run.** A machine with no block scans nothing and
 says nothing. A machine with a block and a project with no key logs `not
@@ -1096,3 +1312,42 @@ the prompt.
 The prompt deliberately teaches the **method**, not the task. The task is in the
 roadmap entry, which the agent reads for itself with `task_current` — putting it
 in the prompt too would be a second copy that can disagree with the entry.
+
+### Codex CLI
+
+`codex` in `agentCommands` (`cawdev config agent enable codex`) lets a run name
+`codex` as its agent. It is spawned by `spawnCodex`, one `codex exec --json`
+per turn like Antigravity, and every flag it is given is in
+`../lib/codex.mjs` with what was checked against the real CLI (0.155). Sign in
+once with `codex login`; the run uses that sign-in and **not** your
+`~/.codex/config.toml` (`--ignore-user-config`, this CLI's `--setting-sources
+''`), so a model or MCP server you configured for yourself does not reach it.
+
+Codex has a sandbox the operating system enforces, and that decides what it
+may do:
+
+- **A run that must change nothing** — ASK, AUDIT, SCOPE, REVIEW, PLAN, and the
+  PLAN, VERIFY and MEMORY stages of any run — gets `--sandbox read-only`. Its
+  shell reads and cannot write, and it needs nothing from the machine. Only
+  cawdev's server is attached, narrowed with `enabled_tools` to the list Claude
+  Code would be handed, and no stage ever holds `report`.
+- **A run that writes** — CODE, INTERVIEW, MERGE, RELEASE and their IMPLEMENT
+  and TEST — must commit and push, which the sandbox refuses, and Codex has no
+  allow-list for its shell. So it runs with
+  `--dangerously-bypass-approvals-and-sandbox`, and **only on a machine that
+  allows everything** (R126); anywhere else the run fails before anything is
+  spawned, saying so.
+
+Every MCP server is marked `default_tools_approval_mode = "approve"` — in `exec`
+the approval policy is *never*, and without it every call to cawdev is refused.
+The run's token reaches cawdev's server through `env_vars`, never the command
+line, and is blanked for the model's own commands
+(`shell_environment_policy.set`).
+
+Not reached on Codex: experts (the session is told it cannot delegate), a
+project's tool rules and R51's permission prompt (both are Claude Code's
+`--allowedTools` grammar and its `approve` handler), the command half of R110's
+shield (the transcript half — secrets taken out of a result — runs in the daemon
+and applies), and live prompting (the process ends with its turn; a follow-up is
+`codex exec resume`). Skills are inlined whole, as for Antigravity. No usage
+windows are read: Codex has no `-p /usage`.