fix(levelcode-ai): correct the group card's live state, aggregate order and labels

Four defects found by re-reading the reference transcript against what the
grouping actually did:

1. The aggregate read its clauses backwards ("Ran 2 commands, read and edited
   PLAN.md"). Files lead, commands trail; a lone command is "a command", not
   "1 command".

2. Groups were created collapsed, which hid the output of the step the header
   claims to be running — the opposite of the fixed-footprint behavior it was
   meant to give. The group body now stays open and each member collapses to a
   one-line row as it finishes (collapseMember), so only finished work folds.
   A failing step re-opens its own row and the group; the single-member unwrap
   hands the card back expanded.

3. read_file and search derived their labels from arguments ("Read src/x.js")
   where the reference shows the model's own sentence. Both now take a required
   explanation, same as run_command; it titles the row and the raw tool text
   drops to the tooltip.

4. None of the DOM behavior was executed by a test — only the pure grammar
   functions and a syntax compile, which is why 2 shipped. test/groupReducer.js
   extracts the real reducer functions and drives them through a fake DOM:
   live header, member collapse, failure re-open, user-stop-is-not-failure,
   unwrap, late background exit, idempotent close, grouping-off, label/tooltip.

Full extension gate green (20 suites).

Author: ndemianc

docs/CALM-TRANSCRIPT.md

@@ -1,9 +1,13 @@
 # LevelCode — Calm narrative transcript (voice + grouped activity) — scope & plan
 
 The goal, in one sentence: make an agent run read like a colleague narrating their work — short
-prose between actions, and consecutive actions folded into one collapsed, expandable card whose
-header shows the *live* step while running and a past-tense aggregate ("Ran 2 commands, read and
-edited PLAN.md +56 −0") when done — instead of a flat scroll of chips and cards.
+prose between actions, and consecutive actions folded into one expandable card whose header shows
+the *live* step while running and a past-tense aggregate ("Read and edited PLAN.md +56 −0, ran 2
+commands") when done — instead of a flat scroll of chips and cards.
+
+The group card itself is never collapsed while it runs: its *members* collapse to one-line rows as
+they finish, so the live step's output stays readable at a fixed vertical footprint. Clause order
+in the aggregate is files first, commands last, matching the reference transcript.
 
 Reference behavior: Claude Code's transcript (screenshots in the design discussion, 2026-07-23).
 Two halves, shipped as separate slices: the **voice** (system prompt) and the **grouping** (webview).
@@ -77,17 +81,19 @@ rebase-safe, and revertable (one function + CSS).
 
 ### D5 — Two header states, exactly like the reference.
 While the group is open (agent still acting, no closing event yet): header = the **live** step's
-label in present-progressive + the working spinner; completed members are folded away — fixed
-vertical footprint while running. When the group closes: header flips to the past-tense
-**aggregate**: verb-category counts, same-file read+edit merged ("read and edited PLAN.md"),
-summed diffstat, fallback "N steps" when the sentence would get awkward. A single-member group
-renders the member bare — no group chrome.
-
-### D6 — Labels: derived for file ops, model-written for commands.
-File ops derive labels from args + result ("Read PLAN.md", "Edited PLAN.md +56 −0"). For
-commands, `explanation` becomes effectively mandatory: schema text specifies "5–10 words, active
+label in present-progressive + the working spinner. The *members* fold: each finished step
+collapses to a one-line row while the running one keeps its body open, so the footprint stays
+fixed without hiding the output the user is watching. The group card itself is never born
+collapsed. When the group closes: header flips to the past-tense **aggregate** — file clauses
+first, then searches, then commands ("Read and edited PLAN.md, ran 2 commands"), same-file
+read+edit merged, summed diffstat, fallback "N steps" when the sentence would get awkward. A
+single-member group unwraps and hands the card back **expanded** — no group chrome.
+
+### D6 — Labels: model-written, for every tool that has a story to tell.
+`run_command`, `read_file` and `search` all take a required `explanation`: "5–10 words, active
 voice, what it does — e.g. 'Find the insertion point in section 10'", and the voice rules require
-it. UI falls back to the first command segment when absent (older transcripts, weaker models).
+it. That sentence titles the row; the raw tool text (`read src/agent.js`) becomes the tooltip. UI
+falls back to deriving a label from the arguments when absent (older transcripts, weaker models).
 Tense: a small verb map (Run/Ran/Running, Read, Edit, Verify, Search, Create, Delete, Install,
 Check ~a dozen) converts imperative → progressive/past; unknown verbs render as-is. No grammar
 engine.
@@ -110,18 +116,19 @@ Rewrite `SYSTEM_BASE`'s communication rules in `agent.js`:
   change it — never a decision buried in prose.
 - Finish: a `Done:` line followed by a short structured wrap-up (what landed / how verified /
   what's next) for substantial runs; one line stays enough for trivial ones.
-- `run_command` MUST carry `explanation` (D6 wording).
+- `run_command`, `read_file` and `search` MUST carry `explanation` (D6 wording).
 Keep verbatim: decisiveness, words-are-not-edits, same-turn action, skills/plan/multi-root/
-autopilot blocks. Update `run_command`'s schema `explanation` description (D6).
+autopilot blocks. Update those three schemas' `explanation` descriptions (D6).
 *Test:* existing suites green (prompt text is data); manual acceptance below.
 
 **S2 — The group reducer (webview).** *(M)*
-In `chat.html`: `openGroup()/routeToGroup(el, meta)/closeGroup()`; route `addAgentLine`,
+In `chat.html`: `openGroup()/groupAppend(el, step)/closeGroup()`; route `addAgentLine`,
 `addTermRun`, `addEditCard`, verify cards through it; close on text bubble / approval / questions
 / error / `agentDone`. Group DOM: `.tl.tl-group` → header (chevron · label · Σdiffstat · state) +
-body (existing cards unchanged). D4 rules (breakout + auto-expand-on-failure). CSS for header +
-collapsed body.
-*Test:* extraction-pattern unit tests for the routing decisions where practical; manual.
+body (existing cards unchanged, each collapsed to a row by `collapseMember` once finished).
+D4 rules (breakout + auto-expand-on-failure). CSS for header + collapsed member rows.
+*Test:* `test/groupReducer.test.js` drives the real reducer functions against a zero-dep fake DOM —
+header states, member collapse, failure re-open, unwrap, late background exit, grouping-off.
 
 **S3 — Labels, aggregate, tense (pure functions + wiring).** *(M)*
 `stepLabel(meta)`, `groupAggregate(steps)`, `verbForms(label)` as extractable pure functions in
@@ -152,10 +159,11 @@ detail); single-member degenerate case; a settings escape hatch
 
 Run the acceptance task on a real repo (Claude model, agent mode, autopilot on):
 "add a section to docs/X.md, verify the edit landed cleanly, and check repo state".
-Pass when the transcript reads: short narration → **one collapsed card** titled with the live step
-while running ("Verifying the edit and checking repo state ⟳"), flipping on completion to
-"Ran 2 commands, read and edited X.md +N −0" → narration continues → a `Done:` wrap-up — and
-expanding the card shows the individual rows (semantic command labels, per-file diffstat), with
+Pass when the transcript reads: short narration → **one card** titled with the live step while
+running ("Verifying the edit and checking repo state ⟳"), its finished members folded to one-line
+rows beneath it while the running step's output stays visible, flipping on completion to
+"Read and edited X.md +N −0, ran 2 commands" → narration continues → a `Done:` wrap-up — and
+expanding a folded row shows its full output (semantic labels, per-file diffstat), with
 any approval card rendered outside the group and any failing step auto-expanded.
 Then re-run with grouping toggled off and confirm the flat timeline is unchanged.
 

extensions/levelcode-ai/agent.js

@@ -31,7 +31,7 @@ const SYSTEM_BASE = [
 	'- Use delete_file to remove an existing file (e.g. during a refactor). To RENAME/move a file, write_file the new path then delete_file the old one. Deletions are reviewable (Keep/Undo) and restorable from the per-turn checkpoint.',
 	'- Your file edits are APPLIED IMMEDIATELY and the user reviews them afterward in the editor with Keep/Undo — do NOT wait for approval, and do NOT re-edit a file you just edited. Only run_command still needs approval; if the user skips a command, adapt or stop.',
 	'- Commands that do NOT exit on their own (dev servers, file watchers, tail -f) MUST be run with run_command background:true — it returns immediately so you keep working instead of hanging. After starting one, call read_command_output with the returned id to watch for a readiness/port line (e.g. "listening on :3000") before you test against it. Use a normal foreground run_command for things that finish (builds, installs, tests, git, curl). This pairs with verification: bring the app up in the background, confirm it serves, fix, repeat.',
-	'- EVERY run_command MUST include "explanation": 5-10 words, active voice, imperative, saying what the command does ("Run the extension unit tests", "Find the insertion point in section 10"). It becomes this action\'s label in the user\'s activity view — never omit it.',
+	'- EVERY run_command, read_file and search MUST include "explanation": 3-10 words, active voice, imperative, saying what you are doing and why ("Run the extension unit tests", "Find the insertion point in section 10", "Read the runAgent call site"). It becomes that action\'s label in the user\'s activity view — never omit it.',
 	'- Paths are relative to the workspace root. In a MULTI-ROOT workspace (several top-level folders), paths from list_files/search are prefixed with the folder name (e.g. "thin.ly/app/models/link.rb") — use them exactly as shown; an unprefixed path resolves against the first folder. To create a file in a specific folder, prefix its name. run_command accepts an optional "folder" to pick which folder it runs in.',
 	'- For a multi-step goal, call update_plan FIRST with a short checklist (3-8 short items, all "pending"), then call it again to set an item "in_progress" when you start it and "done" when finished. Skip the plan for trivial single-step goals.',
 	'- If the goal truly depends on a decision only the user can make (tech stack, scope, where to create files, must-have features), call ask_user ONCE with concise multiple-choice questions (a short header + 2-4 concrete options each) INSTEAD of writing the questions as prose. Put your RECOMMENDED option FIRST and use its description to say why — and, when it matters, what would change your mind. Then act on their answers and do not ask again. Do NOT ask about things you can reasonably decide yourself — prefer a sensible default and proceed.',
@@ -42,8 +42,8 @@ const SYSTEM_BASE = [
 
 const TOOLS = [
 	{ name: 'list_files', description: 'List workspace files (optional glob like "**/*.js"). Excludes node_modules/.git/build dirs.', input_schema: { type: 'object', properties: { glob: { type: 'string' } } } },
-	{ name: 'read_file', description: 'Read a workspace file (path relative to the workspace root; in a multi-root workspace use the folder-name prefix exactly as list_files shows it).', input_schema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] } },
-	{ name: 'search', description: 'Search file contents for a literal string. Returns file:line snippets.', input_schema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] } },
+	{ name: 'read_file', description: 'Read a workspace file (path relative to the workspace root; in a multi-root workspace use the folder-name prefix exactly as list_files shows it).', input_schema: { type: 'object', properties: { path: { type: 'string' }, explanation: { type: 'string', description: 'ALWAYS provide: 3-8 words, active voice, imperative — WHY you are reading this ("Read the runAgent call site", "Read agent.js tool definitions"). Shown to the user as this action\'s label.' } }, required: ['path'] } },
+	{ name: 'search', description: 'Search file contents for a literal string. Returns file:line snippets.', input_schema: { type: 'object', properties: { query: { type: 'string' }, explanation: { type: 'string', description: 'ALWAYS provide: 3-8 words, active voice, imperative — what you are looking for ("Find every postMessage call site"). Shown to the user as this action\'s label.' } }, required: ['query'] } },
 	{ name: 'update_plan', description: 'Declare or update your task checklist for a multi-step goal. Pass the FULL list each time, each item with a status. Call it once up front (all pending), then again to mark an item in_progress when you start it and done when finished. Skip for trivial single-step goals.', input_schema: { type: 'object', properties: { todos: { type: 'array', items: { type: 'object', properties: { title: { type: 'string' }, status: { type: 'string', enum: ['pending', 'in_progress', 'done'] } }, required: ['title', 'status'] } } }, required: ['todos'] } },
 	{ name: 'edit_file', description: 'Make a targeted edit to an EXISTING file: replace an exact, unique snippet (old_str) with new_str. Applied immediately; the user reviews it with Keep/Undo. old_str must appear exactly once — include enough surrounding context to be unique.', input_schema: { type: 'object', properties: { path: { type: 'string' }, old_str: { type: 'string' }, new_str: { type: 'string' } }, required: ['path', 'old_str', 'new_str'] } },
 	{ name: 'write_file', description: 'Create a new file (or fully overwrite a short one) with the COMPLETE content. For edits to existing files, prefer edit_file. Applied immediately; the user reviews it with Keep/Undo.', input_schema: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] } },
@@ -276,7 +276,9 @@ async function runTool(tu, ctx) {
 			return uris.map((u) => vscode.workspace.asRelativePath(u)).join('\n') || '(no files)';
 		}
 		if (tu.name === 'read_file') {
-			ctx.post({ type: 'agentTool', icon: 'file', text: 'read ' + input.path });
+			// label/path ride alongside the legacy `text` so the chat can title this action with the
+			// model's own words ("Read the runAgent call site") and still attribute it to a file.
+			ctx.post({ type: 'agentTool', icon: 'file', text: 'read ' + input.path, label: input.explanation || '', path: input.path, kind: 'read' });
 			const abs = resolveWorkspacePath(input.path || '', { mustExist: true });
 			if (!abs) { return 'ERROR: file not found: ' + input.path + whereHint(); }
 			if (isBinaryFile(abs)) { return 'ERROR: ' + input.path + ' looks like a binary file — not reading it as text.'; }
@@ -285,7 +287,7 @@ async function runTool(tu, ctx) {
 			return body;
 		}
 		if (tu.name === 'search') {
-			ctx.post({ type: 'agentTool', icon: 'search', text: 'search "' + input.query + '"' });
+			ctx.post({ type: 'agentTool', icon: 'search', text: 'search "' + input.query + '"', label: input.explanation || '', kind: 'search' });
 			// Multi-root: search EVERY workspace folder, prefixing hits with the folder name so the
 			// model can hand the paths straight back to read_file/edit_file.
 			const folders = workspaceFolderList();