cawdev-cli 1.0.5-beta → 1.0.7-beta

package/runner/README.md

@@ -68,6 +68,13 @@ page and waits for you to approve a code; after that it is remembered, and
 `/login` does it again on demand. No password is ever typed into the terminal —
 that belongs on a page your browser has told you the origin of.
 
+When the platform stops honouring that session — it expired, you signed out in
+the console, or your account went — the first request answered 401 says so
+once, the footer pins `session expired — /login to sign in again`, and the
+terminal drops to watching only until `/login` succeeds. The polls pick up again
+on their own after it. In advanced mode `/login` stays in advanced mode: the URL
+and the code are printed in the prompt window.
+
 ```
 cawdev                    the runner here, starting one if there is none
 cawdev --runner <name>    when this machine runs more than one
@@ -101,8 +108,8 @@ 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 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
+claude", "Enable codex"), the console-rules switch, **Stop serving** each
+project, 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
 carries `configPath` since R288), so an older daemon is told to restart rather
@@ -126,6 +133,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 remove-project <slug>    stop serving a project; its checkouts stay on disk
 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
@@ -221,7 +229,10 @@ move through the command list while one is open.
 | `/quit` | leave |
 
 **Typing `/` filters that list as you go**, each row with its description; arrows
-and `enter` pick one and `tab` completes as far as the matches agree. Guessing a
+and `enter` pick one and `tab` completes as far as the matches agree — then
+moves down the list, so `/lo` `tab` `tab` reaches `/login` past `/log`. A name
+typed in full is the first row, so `/log` `enter` runs `/log`. Advanced mode
+draws the same list above its prompt, six rows at a time. Guessing a
 command name and being told `no such command` is a step, and it is the step this
 removes.
 
@@ -230,7 +241,8 @@ removes.
 `/logout` forgets it along with the session.
 
 **A paste stays one line.** Paste four hundred lines and the input shows
-`[pasted, 342 lines]`; all of it is sent. A paste that scrolled the transcript
+`[pasted, 342 lines]`; all of it is sent — into a prompt or into a command alike
+(`/new plan <paste>`, `/card <paste>`), its line breaks kept (`commandWords`). A paste that scrolled the transcript
 away would bury the thing this program exists to keep.
 
 Under `NO_COLOR` it is the same terminal without the colour: the picker still
@@ -359,8 +371,17 @@ 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.
+machine and on the card's own branch — except on a finished plan's window, where
+it is that plan's `/develop` (below) with no list; `/new dev` with nothing after it does the
+same anywhere, and `/new dev R3` goes straight to one. A full-width rule
+under the strip separates the board from the session windows; it comes out of
+the strip's own rows, never the windows'.
+
+**`/refresh`** reads the cards again now rather than on the next tick, and
+says what it found per project — `saasng: 5 considering · 2 planned · 1 in
+development` — and which project could not be read, and why. A project that
+cannot be read keeps its last cards and no other's: one unreadable slug used
+to leave every column of every project at 0, silently.
 
 **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
@@ -371,8 +392,15 @@ 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).
+- **`d`** or **`/develop`** on a finished plan — the window says `d develops R2
+  here, in place of this plan` — starts the development of its card, on
+  this machine (the branch is the card's own). `/develop R30` names another
+  card, `@slug` its project, and `--codex`/`--claude`/`--agy` the agent —
+  otherwise the agent that PLANNED the card when its finished plan has a
+  window here, else `/agent`'s choice, exactly as `/new dev R30` does, because
+  it IS that command. Once the development has started the plan's window
+  closes, and the development's window takes its focus when this machine
+  takes the run; a start the platform refused leaves the plan's window up.
 - **`/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
@@ -395,7 +423,18 @@ done next:
   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.
+- **Finished, having built nothing** — a dev session that ended FINISHED
+  with no commit (IMPLEMENT stopped on a plan it would not follow, say) —
+  reads `finished · nothing built`, in amber rather than green, offers no
+  `/pr` but the re-plan instead, and its window shows its summary, where it
+  said why (`builtNothing`; the terminal reads the run's commits once it
+  ends, and claims nothing until it has).
+- **`/open`** opens the pull request in your browser. It reads the run again
+  first — the runner records the link after the run is FINISHED, so the copy
+  taken at that moment has none — and falls back to the card's work item.
+  On a finished PLAN, which opens no pull request, it opens the card on cawdev
+  instead — `roadmap/R2?show=plan` (`issues/…` for an issue) — with the plan
+  of record unfolded and scrolled to: that plan is what the session produced.
 - **`/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
@@ -424,6 +463,21 @@ 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.
 
+**The prompt says which window it acts on.** In advanced mode the line at the
+bottom leads with the focused window's number — `[2] cawdev ▸ /pr`, `[2]
+enter prompts “…”` — and a command's answer keeps the number of the window it
+was about (`[2] A session on … is running`), so a note left on screen after
+the focus moved still says whose it was.
+
+**A project deleted in the console is not offered.** The config on this
+machine still names it, and nothing on the platform can change that file, so
+the terminal asks: a served project whose roadmap read answers 404 — deleted,
+or your access went — is left out of the picker, the strip, `/new` and `/card`,
+and one line says so, once, after the mode is on screen. `c` → **Stop serving
+ngsign** (`cawdev config remove-project ngsign`) takes it out of the config;
+the checkouts stay where they are, and the daemon stops polling for it at its
+next restart, because `projects` is read at boot.
+
 **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
@@ -432,16 +486,73 @@ projects ticked are drawn: their windows, their roadmap on top, and the ones
 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.
 
+**↑ is history, as in a shell.** On a line nothing has been typed on yet —
+empty, or the bare `/` a command line opens with — ↑ and ↓ walk what was
+typed before (kept across launches, `history.mjs`); a command line walks only
+the commands. Once something is typed, the arrows move in the list of
+commands instead, and enter sends a recalled line as it is. Outside advanced
+mode ↑ with no line open recalls the last entry onto the line it belongs to;
+in advanced mode the wheel arrives as arrows, so there it is `/` or enter,
+then ↑.
+
+**`/view`** opens the focused session's page on cawdev — transcript, stages,
+card — in the browser, on the console this terminal signed in to.
+
+**`/view R29`** prints a card here instead: its status, section, tags, branch,
+work item and pull request, who is coding or reviewing it, what it is related
+to, its page on the web, and the first thirty lines of its body (`cardLines`,
+pure). `/view <words>` finds it by its title among the cards of the projects on
+screen and offers a list when several match; `@slug` names the project;
+**`/view card`** is the focused session's own card.
+
+**Which agent `/new` asks for.** `--claude`, `--codex` or `--agy` on a `/new`
+names that session's agent (`/new dev R12 --codex`); `/agent codex` makes it
+the terminal's choice for every `/new` after it, kept across launches
+(`prefs.mjs`, `~/.cawdev/terminal.json`) and shown in advanced mode's prompt
+title; `/agent default` hands the choice back to the project. A flag beats
+`/agent`, and with neither nothing is named — the project's default decides,
+as it always has. A name no runner spawns is refused, by `/agent` and by the
+platform alike, rather than spawned as Claude Code; `/agent codex` on a
+machine that does not list codex says so (`c` → Enable codex). The window's
+`Codex · GPT-5-codex` line says which one actually ran.
+
+**A stage asks rather than stops.** A decision that is the person's — a scope
+the card leaves open, a plan the code has moved away from — is asked with
+`ask_user`, and the stage carries on with the answer; PLAN asks before it
+writes, so a plan never hands IMPLEMENT an open question, and IMPLEMENT asks
+when its plan is wrong or incomplete instead of stopping (`ASK_DONT_STOP`).
+Codex is given the time to: cawdev's MCP server gets `tool_timeout_sec` 660 on
+its side, longer than `ask_user`'s ten-minute wait — Codex's own default of
+60 s cut every question off before anybody could answer it.
+
+**Codex and Antigravity write only on a machine that allows everything.**
+Neither has per-command permissions — Codex's sandbox is read-only, blocks the
+network (no push) or is off — so a session of theirs that writes is refused,
+unspawned, until the machine accepts console rules AND "Allow everything" is
+ticked on it. The refusal says so in steps, for this machine
+(`needsEverything`, lib/agents.mjs): which of the two is done, the Runners page
+on this console, the command to start it again — and it is written on the
+run's transcript as well as its summary, so the window shows it; a failed
+window prints its run's summary (`sayWhyItFailed`) rather than just "failed".
+
+**`/card <the idea in words>`** writes a card in **Considering** and starts
+nothing — no session, no branch, nothing spent: the roadmap's first column
+is where an idea waits to be decided on, and writing one down does not need
+a model. Titled by its words (`cardTitleFor`), the whole text in its body;
+the project chosen exactly as `/new` chooses it (`@project`, else advanced
+mode narrowed to one, else asked).
+
 **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
+serves as a small board — Considering, Planned and In development side by
+side, one line per card, `●` on a card with a session running now; Merged,
+Shipped and Declined — work that is over, and only grows — are counts beside
+the project's name (`1 merged · 2 shipped`), as the console's board folds its
+own last columns. 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.
+go first when the width does, then whole columns (Considering, then Planned —
+In development stays longest), named in the header as `considering 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
@@ -451,16 +562,25 @@ 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.
+**A window's project has a line of its own**, the second, under the title
+(`subtitleFor`) — at the end of the title a long card name pushed it out of
+sight. **A dev window adds where it is working**: the project and the absolute
+path of the checkout — 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.
 
+**A question says which window it came from.** With four sessions on screen,
+"waiting for an answer" is not enough to know whose. A question or a
+permission request names its session (`sessionTag`) — `2 · dev · R3 Client
+mail… — saasng`: the window's number, its kind, its card and its project — in
+the line announcing it, in the title of the picker that answers it, and above
+the banner. The card is cut to 32 columns so the question itself still fits.
+
 ### Checkouts made on demand: `autoWorkspaces`
 
 `"autoWorkspaces": 3` in the machine's config lets the daemon CLONE up to three
@@ -853,6 +973,19 @@ files at all. R47 removes the need for this by giving each run a workspace.
    writes to git: no merging, no branch deletion, no pushing. (A project's own
    rules can ask for all three — see below — but that is a queued action with a
    name on it, not something the survey does in passing.)
+7b. **A stage is not done while its commands are still running.** A stage is
+   one turn, closed the moment the turn ends, so a test suite started with
+   `run_in_background` and never waited for is a result lost. The daemon
+   follows the session's background shells (`lib/background-shells.mjs`:
+   `Bash` with `run_in_background`, `BashOutput`, `KillShell`); a stage whose
+   turn ends with one still running, or finished and never read, is reported
+   FAILED with the commands named, and the run fails with it — keeping its
+   checkout and its session (R80), so **`/continue` picks it up**. Where it
+   resumes is the platform's (R263: the claim's lifecycle starts at the first
+   stage not DONE, with what the DONE ones said); what the daemon adds is WHY
+   the stage stopped — the re-run is handed that and told to run its commands
+   in the foreground. IMPLEMENT and TEST are also told up front to
+   wait for every command, and TEST to commit — no stage after it writes code.
 8. **Reports the lifecycle back** and, if the session dies without saying
    anything, ends the run rather than leaving it `RUNNING` forever.
 
@@ -1077,6 +1210,39 @@ A run **`WAITING_ON_USER` is never swept.** That is the one state where nothing
 happening is correct: it is stalled on a person, who may reasonably take a day.
 Nor is a `PAUSED` or `USAGE_LIMITED` one (below) — there is no process to lose.
 
+### When the daemon itself was killed (R339)
+
+A daemon that dies and is restarted — by systemd, by `cawdev`, by hand — comes
+back with nothing in its hands, and the platform could only infer that five
+minutes later, as "its runner is alive but stopped driving it". So the daemon
+keeps a note of the runs it is driving (`~/.cawdev/driving/<runner id>.json`,
+rewritten when the set changes), and on boot the next one reads it: every run
+the dead daemon was driving that the platform still believes in is failed **at
+once** as `DAEMON_RESTARTED`, with the old and new pids and where to look for the
+cause. A session the old daemon left running is stopped first — only when its
+pid still runs the command it was spawned with. The workspace is held exactly as
+for a vanished runner, and a machine with **auto-resume** on carries such a run
+on by itself **once**; a second restart on the same run waits for a person,
+because a test suite that killed the daemon twice will kill it a third time.
+
+The usual cause on a small Linux box is memory: the session runs a test suite,
+the kernel's OOM killer picks the biggest process, and that is sometimes the
+daemon. `journalctl -k | grep -i "killed process"` says so. Two fixes, both on
+the machine:
+
+- **`"sessionMemoryMax": "6G"`** in `runner.config.json` spawns each agent
+  session under `systemd-run --scope -p MemoryMax=…` (a size systemd reads —
+  `6G`, `512M`, `75%`). A session that blows through it is killed on its own,
+  the ordinary "agent was terminated" failure, and the daemon stays up. Linux
+  only, and it needs a systemd manager for the user (`loginctl enable-linger
+  <user>` on a box with nobody logged in) or a daemon running as root; the
+  daemon probes once at boot and says in its log whether it applied. Needs a
+  restart to change.
+- **Protect the daemon and give the box room**: in the daemon's systemd unit,
+  `OOMScoreAdjust=-800` makes the kernel pick a test worker over the daemon;
+  and add swap (`fallocate -l 4G /swapfile && chmod 600 /swapfile && mkswap
+  /swapfile && swapon /swapfile`, plus its `/etc/fstab` line).
+
 ## When the usage limit hits (R73)
 
 Claude Code stops with a message naming the window — the five-hour one or the
@@ -1186,8 +1352,11 @@ your inbox and on the run, and waits for an answer. Allow it once, or allow it
 always here — which writes a rule on the project that every runner serving it
 inherits.
 
-Nobody answering is a decision too: after fifteen minutes the request expires
-and the session is told to report blocked rather than wait for ever.
+Nobody answering is a decision too: after the project's wait — fifteen minutes
+unless its Rules page says otherwise, and possibly never (R339) — the request
+expires and the session is told to carry on without it. Allowing it later still
+works: the grant lasts the rest of the run and the session is sent a message to
+try again. A stage gate never expires.
 
 You can still say in advance what a project may do, and for anything a session
 needs on every run that is the better answer — with `allowedTools`, which