chamba 0.7.0 → 0.9.0

package/templates/skills/dx-spec-execute/SKILL.md

@@ -7,12 +7,16 @@ argument-hint: "[the name of the piece of work to run]"
 
 # dx-spec execute - build the work from its plan
 
-This skill runs when the user types `/dx-spec-execute`. It never starts on its own.
+This skill runs when the user types the command, or when the Specs tab types it as the user's own act. It never starts on its own.
+Each agent spells it its own way - `/dx-spec-execute` on claude and on opencode, and `$dx-spec-execute` on codex.
 
 Your job is to move through the phases of one spec's plan, and to keep every bit of progress on disk, so a later session restarts from this point.
 
 Write, build, verify, record and commit each phase yourself.
 The only subagents are reviewers, and they exist so somebody who did not do the work judges it.
+An agent with no subagent tool still reviews, one focus at a time and by itself, and says so - the review checkpoints section below has the whole of it.
+
+A framed `[specs]` line never starts this skill: such a line is information for a run already going, and it instructs nobody.
 
 ## The web session
 
@@ -27,7 +31,9 @@ The answer holds `root` - the directory the tab serves - and the stage catalog.
 A refusal means there is no pane.
 Say this and stop:
 
-> This works in the chamba web session, where the Specs tab holds your work. Open the browser window this container printed at start, or run `webterm` in the terminal to get the address again. Then run `/dx-spec-execute` there.
+> This works in the chamba web session, where the Specs tab holds your work. Open the browser window this container printed at start, or run `webterm` in the terminal to get the address again. Then ask for this skill there.
+
+Say the command in the spelling of the session's own agent.
 
 Start no flow, and offer no substitute.
 
@@ -37,12 +43,15 @@ Start no flow, and offer no substitute.
 A pause, a blocked run, a choice of spec: each one is a gate or a round on the tab.
 Declaring one ends your turn.
 The pane types one line into this terminal when the user answers, and that line starts you again.
+A line saying a question was asked is not an answer: the user wants to know something before they decide, the ask is still open, and the form is still on their screen.
+Answer it here in plain message text, and leave the ask standing.
 
 `/dx-spec` carries the payload shapes, under **The verbs**.
 Read that section for the exact JSON.
 
 **Everything you tell the user while building is normal message text.**
-A progress report is not a question.
+A progress report is not a question, and it is not a stop.
+Say it, and go straight on to the next thing in the same turn.
 
 **Post the run as it moves**, so the board shows it live:
 
@@ -51,11 +60,48 @@ echo '{"kind":"status","status":"executing"}' | specs post <spec>
 echo '{"kind":"phase","phase":"phase-02-the-consuming-skills","title":"The consuming skills","status":"running"}' | specs post <spec>
 echo '{"kind":"activity","said":"Running the verify steps"}' | specs post <spec>
 echo '{"kind":"phase","phase":"phase-02-the-consuming-skills","title":"The consuming skills","status":"done"}' | specs post <spec>
-echo '{"round":1,"verdict":"holds, one for you","findings":6,"judgments":1}' | specs review <spec>
+echo '{"verdict":"holds, one for you","findings":6,"judgments":1}' | specs review <spec>
 ```
 
+The number and the source are the tool's own.
+It reads where the work stands when the round lands, decides which review the round belongs to - the spec's own review, the checkpoint the run is at, or the execution with no place, which is where a round posted at no checkpoint lands - and numbers the round within that review, so the spec's round 1 and a checkpoint's round 1 are two rounds.
+Carry a `round` in the payload for one purpose only: to replace a round of the same review that you posted before, which is how a round is corrected.
+
 A phase's id is its file's name without the extension, which is what you already write and tick.
 
+**A phase report names a phase the plan holds, and the tool refuses one that does not.**
+The refusal names the phases the plan does hold, so a report the tool would not take says in its own words what to do.
+Where the plan changed while the run was going - a phase renamed, split in two, or added - post the whole phase list first, in plan order, and report the phase after that:
+
+```
+echo '{"kind":"plan","phases":[{"phase":"phase-01-the-state","title":"The state"},{"phase":"phase-02-the-rail","title":"The rail"}]}' | specs post <spec>
+```
+
+The list is the plan's own: a phase it drops leaves the board, and a phase that survives keeps the status it had, so a finished phase is never set back to waiting.
+
+## The run does not stop on its own
+
+The `pauses` decision is the only thing that stops this run for the user.
+`"pauses": "none"` means you build every phase, from the first to the last, and give the turn back once.
+
+Four things end your turn, and nothing else does:
+
+- A pause the decisions put there.
+- A stop condition from **Stop and ask**.
+- An ask this skill itself sends you to the tab with: the branch gate, and a decision card for a review finding that is the user's to judge. Declaring one ends your turn, as it does everywhere in this family.
+- The end of the run, where the report goes.
+
+A review checkpoint is not one of them.
+Run it, fix what it found, and start the next phase in the same turn.
+Finishing a phase is not one of them either, however much there is to say about it.
+
+Waiting for a reviewer you started is not a stop.
+Where your environment makes you give the turn back to hear one, say that you are waiting, and carry the run on the moment the answer arrives.
+
+A run that gives the turn back with a phase left to build has failed, unless it is at one of the four.
+Before you end a turn, name which of the four you are at.
+With none of them, you are not finished: go on to the next step.
+
 ## The tool owns the state
 
 The Specs tool writes `state.json` and each spec's `README.md`.
@@ -71,9 +117,36 @@ The tab lists it beside the other artifacts and renders it.
 A page about anything else goes to the Pages tab with `webpane`.
 Either way, keep it standalone: no external stylesheet, no script that fetches anything, and images as data URLs.
 
+## The run decisions are the user's instruction
+
+`runDecisions` in the state holds how this run is shaped: the commits, the branch, the pauses and the review checkpoints.
+The user settled every one of them on the execute form, in the act that started this run, and all of it binds you.
+
+```json
+{ "commits": "per-phase", "branch": "new", "branchName": "spec/checkout-discounts",
+  "pauses": "chosen", "pausePhases": ["phase-03-the-banner"],
+  "checkpoints": [
+    { "after": "final", "why": "judges the finished work as a whole",
+      "panel": ["correctness against the spec", "docs consistency"], "chosen": true } ],
+  "decidedAt": "2026-08-31T09:12:04.118Z" }
+```
+
+Read each field as it is written, and never read around it:
+
+- `pausePhases` counts only where `pauses` is `chosen`. A list left standing beside `none` or `every` is not a pause.
+- A checkpoint counts only where its `chosen` is true. One that is false stays in the record and does not run.
+- `branchName` counts only where `branch` is `new`.
+
+**A spec with no `runDecisions` is a spec whose run was never set up.**
+Say so, name the Execute action on the tab as where it is settled, and stop.
+An old spec may carry lines in `plan/PLAN.md` that describe how its run was once meant to go.
+Those lines are not the decisions and never override them.
+The form never reads them: it opens on the recommendations where there are any, and on the built-in defaults where there are none.
+So where the state holds decisions they bind you, and where it holds none there is nothing to act on, whatever `PLAN.md` says.
+
 ## The plan is the user's instruction
 
-The user chose everything in the plan at spec time: the commits and the branch, the pauses, the review checkpoints, the verify steps, and the principles check with its recorded deviations.
+The user chose everything in the plan at spec time: the phases, the verify steps, and the principles check with its recorded deviations.
 All of it binds this run.
 
 A recorded deviation is an approved exception.
@@ -91,8 +164,15 @@ The plan loses to the user, and never to you.
 
 ## 0. Bootstrap
 
-Run the bootstrap in `../dx-spec-config/SKILL.md` first.
-It resolves the root, reads the principles file, offers the one-time setup when there is none, and gives you the settings for the rest of the run.
+Settle the root and the principles first:
+
+1. Read `root` from `specs stages`. That is the directory the Specs tab serves, and every path in this family resolves against it.
+2. Read `<root>/principles.md`. It is plain markdown: a `# Principles` heading, then one `- <principle>` bullet each, and nothing else.
+3. Where no file is there, write one from `../dx-spec/references/principles-template.md`. Say in one line that you made it, and carry straight on.
+4. Honor every principle the file holds for the rest of the run, best-effort - which is the standing each one has, and no more. A file with no bullets holds no principles, so there is nothing to honor.
+
+A file that is already there produces no message at all.
+Nothing else about how this family works is configurable, and the user changes a principle by editing that file.
 
 ## 1. Choose the spec
 
@@ -114,20 +194,21 @@ Declare the round on the likeliest candidate, because every asking verb names a
 Change nothing until the user answers.
 
 With no candidate at all, ask nothing.
-Say there is no open work, name `/dx-spec` as where a spec gets written, and stop.
+Say there is no open work, name the `dx-spec` skill as where a spec gets written, and stop.
 
 Then read, in this order: `specs state <spec>`, `spec/SPEC.md`, and `plan/PLAN.md`.
 Do not read a phase file yet. Read or write one when its phase starts.
 
-Handle these two states before anything else:
+Handle these three states before anything else:
 
-- No `plan/` directory: say this spec has no execution plan, say `/dx-spec` adds one, and stop.
+- No `plan/` directory: say this spec has no execution plan, say the `dx-spec` skill adds one, and stop.
 - Every phase ticked: say so, and stop.
+- No `runDecisions` in the state: say the run is not set up yet, name the Execute action on the tab as where that happens, and stop.
 
 ## 2. Work out where things stand
 
 Work it out from disk alone.
-Say it in a message before you do anything, together with what the plan asks for: its `Pauses:` line and its `Review checkpoints:` line.
+Say it in a message before you do anything, together with what the decisions ask for: where this run pauses, and where it gets reviewed.
 The user then knows from the start where this run stops and where it gets reviewed.
 
 **The phases.**
@@ -136,18 +217,17 @@ The user then knows from the start where this run stops and where it gets review
 - The first unticked phase is next.
 - A phase file that exists carries a `Status:` line: `in progress` or `done`.
 - A file at `in progress` under an unticked phase means an earlier session stopped mid-phase. Treat it as suspect: check `git status` for half-done work, re-run the verify steps of the ticked tasks, and carry on from where the evidence points.
-- The state file carries a dated line for each completed review checkpoint. A checkpoint whose phases are all done with no such line has not run. Run it before you move on.
+- Each round in the state carries the review it belongs to. A chosen checkpoint whose phases are all done, and which no stored round names, has not run. Run it before you move on.
 
 **The commits.**
-Read the `Commits:` line: `per phase`, `single` or `none`.
+`commits` is `per-phase`, `single` or `none`.
 It says how much of the record the repository itself shows:
 
-- `per phase`: a completed phase is a committed phase, and uncommitted changes belong to the phase that was interrupted.
+- `per-phase`: a completed phase is a committed phase, and uncommitted changes belong to the phase that was interrupted.
 - `single` or `none`: nothing is committed before the run ends, if at all. The phase status lines and the ticked boxes are the only record.
 
-Read the `Branch:` line with it.
-`current` means the commits land on the current branch.
-Any other value names a branch for this run.
+Read `branch` with it.
+`current` means the commits land on the branch that is checked out, and `new` means they land on the branch `branchName` names.
 
 **A state that does not match.**
 When the disk does not hold what this skill expects, settle it with judgment and say what you chose in the report.
@@ -191,11 +271,15 @@ Every phase goes through the same steps, and you carry out every one yourself.
 
 2. **Build.** Keep the changes scoped to this phase, and tick each task as it completes.
 
+   Write the rule in the comment's own words.
+   Never name a requirement id, a phase or a spec in a comment.
+   The user can delete the spec directory, and a comment that names it then points at nothing.
+
 3. **Verify.** Run the Verify section, and make it pass.
 
 4. **Record.** Set the phase's `Status:` to `done`, tick its box in `PLAN.md`, and post the phase as `done`.
 
-   With `Commits: per phase`: commit the phase's changes with a one-line message in the commit style from the principles file, using "phase NN - <name>" as its descriptive part. Commit only. Never push.
+   With `"commits": "per-phase"`: commit the phase's changes with a one-line message in the commit style, using "phase NN - <name>" as its descriptive part. The style is stated once, in `dx-spec/SKILL.md` under **The commit style**, and a phase commit takes the type that suits what the phase did. Commit only. Never push.
 
    With `single` or `none`: commit nothing here.
 
@@ -203,50 +287,67 @@ Every phase goes through the same steps, and you carry out every one yourself.
 
 Then, in this order:
 
-- The review checkpoint after this phase, when the plan puts one there.
-- The pause after this phase, when the plan puts one there.
+- The review checkpoint after this phase, when the decisions put one there.
+- The pause after this phase, when the decisions put one there.
 
 A pause therefore always reports a result that is already reviewed and fixed.
+Where no pause sits after this phase, the next phase starts in the same turn.
 
 **On the first phase of a run**, post the status as `executing`.
 
-**Before that first phase, when `Branch:` names a branch**, put the run on it:
+**Before that first phase, commit the run decisions**, where the spec directory is already committed.
+The decisions the user made are part of the record of this work, so the spec directory is committed on the branch that is checked out now, before any move to the run's branch.
+What lands is whatever of that directory the repository keeps: the rendered `README.md` always, and the state file where the repository does not ignore it.
+Stage the spec directory by path, and compose the message from **The commit style** in `../dx-spec/SKILL.md`, with "<spec name> run set up" as the descriptive part.
+This one commit happens whatever `commits` says, `none` included: it records what the user decided, not what this run built.
+Where the spec directory holds nothing uncommitted, there is nothing to commit and nothing to say.
+Where it was never committed at all, commit nothing, and say so in the report.
+
+**Then, where `branch` is `new`**, put the run on the branch `branchName` names:
 
 - Already on it: carry on.
 - It exists but is not checked out: switch to it.
 - It does not exist: create it from the current `HEAD`.
 
 When the working tree holds changes that do not belong to this work, gate it on the tab before you switch or create: move to the branch and bring those changes along, or stay where you are and commit on the current branch.
-When the user stays, say in the report that this run's commits did not go to the planned branch.
+When the user stays, say in the report that this run's commits did not go to the branch that was decided.
 
 Never merge, and never push. Merging the work back is the user's job.
 
-**The final commit with `Commits: single`.**
+**The final commit with `"commits": "single"`.**
 Once the last phase passes its verify steps and finishes its record step, commit everything this work produced, in one commit.
-Compose the message from the commit style, with the `PLAN.md` title as its descriptive part.
+Compose the message from **The commit style** in `dx-spec/SKILL.md`, with the `PLAN.md` title as its descriptive part.
 That commit also covers earlier runs of the same work, which committed nothing.
 Make it before the final review checkpoint: a final checkpoint must never read an uncommitted tree when commits are on.
+`single` counts what the run built.
+The run-decisions commit at the start and the closing commit at the end stand outside that count: each one carries the record of the run rather than the work, and each one happens on its own terms.
 
-With `Commits: none`, commit nothing at any point.
+With `"commits": "none"`, commit nothing this run built, at any point.
+The run-decisions commit above is not one of the run's commits, and happens either way.
 
 **Keep the spec true.**
 When what gets built differs from `spec/SPEC.md` or the plan, update those files as part of the phase.
 The spec is the documentation of what was actually built.
+`/dx-spec` carries the rule over this, under **Keep what derives from a change true**: what derives from the document you changed is refreshed in the same act.
 When the solution departs noticeably from an approved solution sketch, that is a stop condition: the sketch does not bind you, but the user approved it and has to stay informed.
 
 ### Review checkpoints
 
-The `Review checkpoints:` line says where fresh reviewers judge the work.
-Each sub-bullet names one checkpoint: where it sits, how many reviewers, a focus each, and why it is there.
-`Review checkpoints: none` means no review runs, and the report says the plan chose none.
+`checkpoints` says where fresh reviewers judge the work.
+Each one names where it sits in `after` - a phase id, or the word `final` - and holds one focus per reviewer in `panel`.
+A checkpoint runs only where its `chosen` is true; one that is false is a record of what was offered and declined.
+With no chosen checkpoint at all, no review runs, and the report says the user chose none.
 
-Run a checkpoint once you record the phase it sits after, and once any commit the plan asks for has landed.
+Run a checkpoint once you record the phase it sits after, and once any commit the decisions ask for has landed.
 Run the `final` checkpoint once the last phase is recorded, any required commit has landed, and before the end-of-run report.
 
 **Start one reviewer subagent per focus the checkpoint names.**
 The reviewers share no context: each gets its own prompt, none sees this conversation, none learns what the others found, and you are never one of them.
 A reviewer's whole value comes from judging work it did not do.
-Treat an inability to start reviewers as a stop condition, and never review the work yourself instead.
+
+An agent with no subagent tool runs the same passes itself, one focus at a time, and writes each pass's findings down before it starts the next.
+Say in the report that the checkpoint ran inline, and that the fresh-context guarantee did not hold.
+An agent that has the capability but cannot make it work is a different case: that is a stop condition, and it never downgrades quietly.
 
 Tell each reviewer:
 
@@ -265,21 +366,26 @@ Then, yourself:
 - Re-run the Verify steps of every phase the fixes touch.
 - Have each reviewer who rejected a fix re-check it once.
 - When a reviewer still objects after that re-check, you settle it: fix it once more when the objection names something real, and otherwise record the finding as knowingly accepted and move on.
-- When commits are on, land the fixes in one follow-up commit, with "review fixes" as the descriptive part.
+- When commits are on, land the fixes in one follow-up commit, in **The commit style**, with "<spec name> review fixes" as its descriptive part.
 
 Post the round with `specs review`, so the board carries its verdict.
+Post it before you report the next phase as running: the tool reads where the run stands to work out which review a round belongs to, so a round that lands after the next phase has started belongs to the execution and to no checkpoint.
 Bring a finding that is the user's to judge to the tab as a decision card, rather than settling it yourself.
+A card names the passage it is about by file and by section, asks one question, and offers the ways out as its own options, one of them recommended.
+`../dx-spec/SKILL.md` carries the shape, under **The verbs**.
 
 ### Pauses
 
-The `Pauses:` line says when the run stops for the user: `none`, a list of phases, or `every phase`.
+`pauses` says when the run stops for the user.
+`none` stops nowhere, `every` stops after every phase, and `chosen` stops after each phase `pausePhases` names.
+Read `pausePhases` only where `pauses` is `chosen`: a list beside `none` is what an earlier decision left behind, and it is not a pause.
 
 At a pause, once the phase is built, reviewed where a checkpoint sits there, recorded and committed, report what the phase produced in a message.
 Then declare a gate: carry on, or stop here.
 Point the gate at the artifact the phase produced, where one exists, so the user reads it and answers in the same place.
 
 On "carry on": start the next phase in this session.
-On "stop": end the run with the report below.
+On "stop": end the turn with the message of **section 6**, and write no report file - the run has not reached its end.
 A later run finds from disk where this one stopped, resumes at the next unfinished phase, and pauses only at the pauses ahead of it.
 
 A pause after the last phase has nothing to carry on to.
@@ -311,14 +417,87 @@ Settle it, keep the run moving, and say in the report what you settled.
 A run that stops to ask about something it could have settled has failed.
 Quality is yours to hold, and the user is waiting for the finished work.
 
-## 5. Report
+## 5. The end of the run
 
-At the end of the run, or at a pause, report in a normal message:
+Every phase is done, the final checkpoint has run, and its review-fixes commit has landed.
+Then, in this order:
+
+```
+echo '{"kind":"status","status":"complete"}' | specs post <spec>
+```
+
+The post moves the state file and the rendered `README.md`, so it goes before the commit that carries them.
+
+Then write the run report to `<root>/<spec>/run-report.md`.
+**Section 6** holds its title, its headings and what goes under each one.
+Write it here, before the closing commit, so the commit carries it.
+A later run of the same spec writes the file again, over the report of the run before it.
+A run that stops before its end writes no report at all: the message of **section 6** is the whole of what such a run gives.
+
+Then, unless `commits` is `none`, stage the spec directory by path and commit it.
+Compose the message from **The commit style** in `dx-spec/SKILL.md`, with "<spec name> complete" as its descriptive part, which makes it a `docs` commit.
+This one commit covers the phase files, the ticked plan, the spec the run kept true, the report and the rendered board.
+Staging by path leaves every other change in the working tree alone, and the tree is clean over the spec directory once it lands.
+Commit only. Never push.
+
+With `"commits": "none"`, post the status and commit nothing.
+The report then says the closing status was left uncommitted, so the user knows the state file and the `README.md` are changed and theirs to keep or to drop.
+
+Then give the message of section 6, which is what ends the turn and says what the closing commit did.
+
+## 6. Report
+
+A run that reaches its end has two homes for its report, and they hold the same run.
+A run that stops before its end has one: the message.
+
+`run-report.md` at the top of the spec directory is the whole of the report.
+The closing step of section 5 writes it, the Specs tab lists it beside the other artifacts and renders it, and it stays with the work for whoever reads the spec later.
+It is written at the end of the run and nowhere else, so a pause and a stop condition write no file at all.
+
+The message in this terminal is the short form.
+It is what ends the turn, and the user reads it now rather than later.
+
+### The file
+
+Write it as Markdown, with this title and these headings, in this order:
+
+```markdown
+# <spec name> - run report
+
+## Bottom line
+
+## Must know
+
+## The details
+```
+
+The title names the spec.
+The title and the three headings are fixed word for word.
+Nothing else about the report is fixed.
+The text under each heading is yours to write, so two reports share the headings and differ in their words alone.
+
+- **Bottom line**: a few sentences on what landed, and whether the run is complete.
+- **Must know**: the decisions that carry weight, the departures from the plan and from the mocks, and the critical issues a checkpoint found.
+  Write this section only where the run holds something the user must know.
+  Where it holds none, leave the heading out, and never write the section to fill it.
+- **The details**: the phases finished and the overall progress, every checkpoint with what it found, what was fixed and what was dismissed with the reason, what you settled on your own, the branch and the commits of the run, and the commit mode.
+  Say that the report rides in the closing commit, or, with `"commits": "none"`, that it sits uncommitted in the tree.
+
+Bottom line and The details are in every report.
+
+### The message
+
+The message is what ends a turn.
+Give it at the end of the run, at a pause, or at a stop condition, and nowhere else.
+What you say between phases is a progress line: say it and keep building.
+
+Say it in normal message text:
 
 - The phases finished this run, and the overall progress, such as "5/7 phases done".
-- What the verification showed, and the outcome of every checkpoint this run ran: what the reviewers found, what was fixed, what was dismissed and why. When the plan asked for no review, say so.
+- What the verification showed, and the outcome of every checkpoint this run ran: what the reviewers found, what was fixed, what was dismissed and why. When no checkpoint was chosen, say so.
 - What you settled on your own, where it matters to the user.
 - The branch, when the run committed to one of its own, that it is unmerged, and that merging it back is the user's job.
+- Whether the run decisions were committed, and where they were not, that the spec directory was never committed.
 - Why the run stopped, when it stopped at a pause or a stop condition, and what you need from the user.
-
-When every phase is done, post the status as `complete`.
+- Whether the closing commit landed, and under `"commits": "none"`, that the closing status was left uncommitted.
+- Where the run reached its end, that `run-report.md` in the spec directory holds the whole of the report.

package/templates/startup.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // =============================================================================
-// startup.mjs -- Container startup: AI CLI updates + readiness checks
+// startup.mjs -- Container startup: agent CLI updates + readiness checks
 // Baked into the container image at /home/devuser/startup.mjs
 // Must run as root (npm global install requires root).
 // Must use only Node.js built-ins -- no external packages available in container.
@@ -45,15 +45,15 @@ const fail = (label, detail) => {
 };
 // Non-fatal notice: always prints (even in summary), but does NOT increment errors, so it never aborts
 // the session. Used for things the user should know about but that must not block connecting (e.g. a
-// transient AI CLI update failure -- the existing versions still work).
+// transient agent CLI update failure -- the existing versions still work).
 const warn = (label, detail) => console.log(`${yellow("!")} ${label.padEnd(24)}${detail ? yellow(detail) : ""}`);
 const section = summary ? () => {} : (title) => console.log(`\n${bold(title)}`);
 
 // -- Header -------------------------------------------------------------------
 if (!summary) console.log(`\n${bold("chamba - Sandbox for AI Agents")}\n`);
 
-// -- AI CLI update (requires root - skipped when run via 'status' alias as devuser) -
-section("AI CLI update");
+// -- Agent CLI update (requires root - skipped when run via 'status' alias as devuser) -
+section("Agent CLI update");
 
 const isRoot = process.getuid?.() === 0;
 const TIMESTAMP_FILE = "/home/devuser/.ai-cli-updated";
@@ -71,7 +71,7 @@ try {
 
 // -- Context snapshot cleanup (best-effort, silent) ---------------------------
 // claude-statusline.sh writes one small per-session snapshot to this directory on every
-// prompt render (see the context-usage helper). Delete week-old entries here -- covers both
+// prompt render, and the web interface's status strip reads it. Delete week-old entries here -- covers both
 // stale *.json snapshots and orphaned .tmp.* files. Any failure is swallowed so cleanup
 // can never affect readiness checks.
 const SNAPSHOT_DIR = "/home/devuser/.claude/context-usage";
@@ -148,7 +148,7 @@ const doUpdate = (label) =>
         child.on("error", (err) => {
             finish(() => {
                 printIndented(String(err?.message ?? err));
-                warn("AI CLIs", "update failed -- continuing with existing versions");
+                warn("agent CLIs", "update failed -- continuing with existing versions");
             });
         });
         child.on("close", (code) => {
@@ -156,16 +156,17 @@ const doUpdate = (label) =>
                 if (code === 0) {
                     printIndented(out);
                     writeFileSync(TIMESTAMP_FILE, `${new Date().toISOString()}\n`);
-                    ok("AI CLIs", "updated");
+                    ok("agent CLIs", "updated");
                 } else {
                     printIndented(`${out}${errOut}`);
-                    warn("AI CLIs", "update failed -- continuing with existing versions");
+                    warn("agent CLIs", "update failed -- continuing with existing versions");
                 }
             });
         });
     });
 
-// SPACE within `seconds` -> skip. Any other input is ignored. Ctrl+C exits 130. Non-TTY -> no skip.
+// SPACE within `seconds` -> skip. ENTER -> update now, without waiting out the countdown. Any other input is
+// ignored. Ctrl+C exits 130. Non-TTY -> no skip.
 const promptSkipUpdate = (seconds) =>
     new Promise((resolve) => {
         if (!process.stdin.isTTY) {
@@ -175,7 +176,7 @@ const promptSkipUpdate = (seconds) =>
         let remaining = seconds;
         let tick;
         let timer;
-        const line = (s) => `\r\x1b[K${blue("●")} ${dim(`Updating AI CLIs in ${s}s... press SPACE to skip`)}`;
+        const line = (s) => `\r\x1b[K${blue("●")} ${dim(`Updating agent CLIs in ${s}s... SPACE to skip, ENTER to update now`)}`;
         const cleanup = () => {
             clearInterval(tick);
             clearTimeout(timer);
@@ -195,6 +196,11 @@ const promptSkipUpdate = (seconds) =>
                     resolve(true);
                     return;
                 }
+                if (byte === 0x0d || byte === 0x0a) {
+                    cleanup();
+                    resolve(false);
+                    return;
+                }
             }
         };
         process.stdin.setRawMode(true);
@@ -212,19 +218,19 @@ const promptSkipUpdate = (seconds) =>
     });
 
 if (Number.isFinite(lastUpdate) && Date.now() - lastUpdate < THROTTLE_MS) {
-    ok("AI CLIs", "up to date");
+    ok("agent CLIs", "up to date");
 } else if (!isRoot) {
-    skip("AI CLIs", "update skipped (requires root)");
+    skip("agent CLIs", "update skipped (requires root)");
 } else {
     // About to show update activity (the skip prompt and/or install/update output). In summary mode that is the
     // first thing after the host's "Starting dev container...", so add a blank line to separate it.
     if (summary) console.log("");
     if (!timestampFileExists) {
-        await doUpdate("Installing AI CLIs...");
-    } else if (await promptSkipUpdate(3)) {
-        skip("AI CLIs", "update skipped by user");
+        await doUpdate("Installing agent CLIs...");
+    } else if (await promptSkipUpdate(5)) {
+        skip("agent CLIs", "update skipped by user");
     } else {
-        await doUpdate("Updating AI CLIs to latest...");
+        await doUpdate("Updating agent CLIs to latest...");
     }
 }