cawdev-cli 1.0.3-beta → 1.0.5-beta

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
@@ -662,9 +856,115 @@ files at all. R47 removes the need for this by giving each run a workspace.
 8. **Reports the lifecycle back** and, if the session dies without saying
    anything, ends the run rather than leaving it `RUNNING` forever.
 
+   **What each stage used, and what the run used** (R76, R305). Every `result`
+   event the CLI prints carries the process's cumulative token counts, and the
+   daemon files two absolute readings off each: the *stage's* (`POST
+   …/stages/{stage}/usage` — the stage's own processes, across its attempts,
+   so a stage re-run after a refused gate keeps adding to the first attempt's
+   total) and the *run's* (`POST …/usage`). Each stage is its own process
+   counting from zero, so the daemon keeps the run's running total itself and
+   adds each child's figure to it: **the run's total is the sum of its stages'
+   processes**, and a resumed run starts from whatever the claim already
+   carried. The platform keeps the larger reading on both, so a lost report is
+   healed by the next one. Tokens, never money, and cache reads are not
+   counted — `tools/lib/usage.mjs` says why. A daemon older than R305 reports
+   the run and never a stage, and every stage after the first on a staged run
+   was ignored as a reading that went backwards; restart the daemon to get
+   the per-stage figures and the summed total.
+
 Cancelling a run reaches the daemon on its next poll and takes down the child's
 whole process group — an agent that started a build should not leave it running.
 
+### Scanning every branch (R300)
+
+A project with a `quality` block has its branch scanned with SonarQube
+**after a coding run's TEST stage settles and before the next stage begins**,
+on the tree the tests just ran against:
+
+```json
+"cawdev": {
+  "workspaces": ["/Users/you/code/cawdev"],
+  "quality": { "command": "sonar-scanner", "tokenEnv": "SONAR_TOKEN" }
+}
+```
+
+Both keys have those defaults, so `"quality": {}` is enough. `cawdev config
+quality on <slug>` writes the block (and `off` removes it), as does the
+`c` screen inside the attached terminal. The block is read once at boot
+like the rest of `projects`, so **restart the daemon** after adding or
+changing it — the daemon says so itself when it is signalled.
+
+**It is the daemon that scans, not the session.** The scanner is a subprocess
+this process starts and nothing the spawned agent can call — a session that
+reported its own gate could lie about it. It runs in the run's checkout with
+the project's key and the branch's name from the claim
+(`-Dsonar.projectKey=`, `-Dsonar.branch.name=`), the repository's own
+`sonar-project.properties` for everything else, and a working directory in the
+daemon's temp dir rather than `.scannerwork/` inside the checkout, which the
+next reset would otherwise clean and the working-copy watcher report. Then it
+waits for the server to finish the analysis, reads the branch's quality gate
+and its new-code measures, and tells the platform:
+`POST /api/runners/{id}/quality/{slug}`, on the machine's `runner:operate`
+token, the same door as the git survey. The run page and the development
+board show the result — *Quality gate: failed · 3 new problems · Open in
+SonarQube* — found by the branch's name.
+
+**The token stays on this machine.** `tokenEnv` names the environment variable
+the daemon reads the scanner token from — export it where the daemon runs;
+it is never written to the config file, never sent to the platform, and goes
+to the scanner in its environment, never on its command line. It is **not**
+the token the project's owner entered under the project's Settings →
+SonarQube: that one is the platform's reader credential and never leaves the
+platform. Two credentials, two custodians. The scanner has to read
+`SONAR_TOKEN` from its environment, which `sonar-scanner` does from 4.7 on;
+older scanners want `-Dsonar.login`, which would put the token in `ps`, so
+this daemon does not offer it. The block may also name `url`, for a machine
+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 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
+scanned` and reports nothing. Everything after that reports *something*: no
+scanner on this machine, no token exported, no server, a server that refused —
+each is an `error` reading with the sentence on it, so the run page says the
+scan could not run rather than showing a branch nobody looked at, and the
+run goes on to its next stage exactly as it would have. Only a staged run
+with a TEST stage is scanned: a lifecycle without one, an unstaged run, a run
+whose gate refused TEST twice or one that reported done inside TEST has no
+settled TEST stage to scan after. The log line is
+`quality: <branch> gate OK · 0 new problems`, or `quality: could not scan
+<branch>: <why>`.
+
 ## What a project's rules can ask of it (R40)
 
 A project may decide that a finished run **pushes its branch**, **opens a pull
@@ -674,11 +974,18 @@ with the claim, and the daemon logs them when it takes a run, so you find out
 what is going to happen before it happens rather than afterwards. `auto_merge`
 gets a shouted line of its own.
 
-The daemon does not decide any of this. The platform queues `PUSH`, `OPEN_PR`
-and `MERGE` on the same `run_action` queue the console's *Commit* button uses,
+The daemon does not decide any of this. The platform queues `PUSH` and
+`OPEN_PR` on the same `run_action` queue the console's *Commit* button uses,
 and the daemon performs them in `settleActions` — one pass right after the
 session ends, because the working-copy watcher stopped with the child and the
-rules queue their work at exactly that moment.
+rules queue their work at exactly that moment. `auto_merge` is asked for
+later, when the branch reaches Done on the development board (R306): the
+platform queues a `MERGE` **workspace request** attributed to the rule —
+`requestedByRule: "auto_merge"` on the claim — to the machine that wrote the
+branch, and the daemon logs `MERGING <branch> — by auto_merge, nobody is
+reading this diff` when it takes it. It is the same `gh pr merge` the board's
+button runs. (A platform older than R306 still queues a `MERGE` run action,
+and the daemon still performs it.)
 
 **cawdev still holds no git-host credential.** This machine does, which is why
 the work happens here and why R19 and R25's division is unchanged. All that is
@@ -693,6 +1000,11 @@ What it actually runs:
   conflict — the rule wanted one to exist and one does.
 - `gh pr merge <url> --squash --delete-branch`, and only if a real pull request
   is found. A `/compare/` URL is not one, and it refuses rather than guessing.
+  Before merging it asks `gh pr view --json mergeable,mergeStateStatus` and,
+  while the host answers `UNKNOWN` — mergeability is computed lazily, and a
+  merge seconds after `gh pr create` used to fail for no reason a person could
+  act on — waits up to six times five seconds (R306). Any other answer merges
+  at once; the merge is what says whether it could.
 
 Every one of them reports a result or a reason, and a machine with no `gh`, no
 remote or no credentials simply says so. **A rule is a request, not a grant** —
@@ -1000,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`.