cool-workflow 0.1.90 → 0.1.92

package/docs/project-index.md

@@ -5,11 +5,11 @@ Generated from the current repository code on 2026-06-21 by `npm run sync:projec
 ## Snapshot
 
 - Package: `cool-workflow`
-- Version: `0.1.90`
-- Source modules: `67`
+- Version: `0.1.92`
+- Source modules: `68`
 - Workflow apps: `7`
 - Docs: `53`
-- Smoke tests: `136`
+- Smoke tests: `139`
 - Repository: https://github.com/coo1white/cool-workflow
 
 ## Architecture
@@ -104,6 +104,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [onramp.ts](../src/onramp.ts)
 - [reclamation.ts](../src/reclamation.ts)
 - [remote-source.ts](../src/remote-source.ts)
+- [reporter.ts](../src/reporter.ts)
 - [result-normalize.ts](../src/result-normalize.ts)
 - [run-export.ts](../src/run-export.ts)
 - [run-registry.ts](../src/run-registry.ts)
@@ -212,6 +213,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [cli-mcp-parity-smoke.js](../test/cli-mcp-parity-smoke.js)
 - [cli-progress-summary-smoke.js](../test/cli-progress-summary-smoke.js)
 - [cli-recoverable-errors-smoke.js](../test/cli-recoverable-errors-smoke.js)
+- [cli-render-smoke.js](../test/cli-render-smoke.js)
 - [clones-gc-smoke.js](../test/clones-gc-smoke.js)
 - [codex-agent-wrapper-smoke.js](../test/codex-agent-wrapper-smoke.js)
 - [concurrency-default-smoke.js](../test/concurrency-default-smoke.js)
@@ -270,9 +272,11 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [project-index-sync-smoke.js](../test/project-index-sync-smoke.js)
 - [quickstart-bundle-smoke.js](../test/quickstart-bundle-smoke.js)
 - [quickstart-check-smoke.js](../test/quickstart-check-smoke.js)
+- [quickstart-corpus-smoke.js](../test/quickstart-corpus-smoke.js)
 - [quickstart-no-agent-smoke.js](../test/quickstart-no-agent-smoke.js)
 - [quickstart-readme-path-smoke.js](../test/quickstart-readme-path-smoke.js)
 - [quickstart-smoke.js](../test/quickstart-smoke.js)
+- [readme-sync-smoke.js](../test/readme-sync-smoke.js)
 - [readme-trust-claim-smoke.js](../test/readme-trust-claim-smoke.js)
 - [real-execution-backends-smoke.js](../test/real-execution-backends-smoke.js)
 - [registry-corrupt-fail-closed-smoke.js](../test/registry-corrupt-fail-closed-smoke.js)

package/docs/real-execution-backends.7.md

@@ -175,3 +175,7 @@ _No behavioral change in v0.1.88 (the container/remote/ci delegating integration
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/release-and-migration.7.md

@@ -315,3 +315,7 @@ _No behavioral change in v0.1.88 (`release:check` and the durable run-state comp
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/release-tooling.7.md

@@ -62,6 +62,15 @@ keeps full coverage while cutting the doubled wall time. The steps that stay
 are the ones NOT covered by `npm test`: build, type check, `npm test`,
 canonical-apps, golden-path, parity, vendor-manifest drift, and `version:sync`.
 
+The drift gates `index:check` (`docs/project-index.md`) and `readme:check`
+(`plugins/cool-workflow/README.md`) also run here. The npm package README is
+GENERATED from the repo-root `README.md` by `scripts/sync-readme.js` — it changes
+only the relative image/link URLs npm cannot render (`docs/assets/*` to
+`raw.githubusercontent.com`, `](LICENSE)`/`](plugins/...)` to `.../blob/main/...`),
+so the npm page and the GitHub page stay identical. Edit the GitHub `README.md`,
+then run `npm run sync:readme`; `readme:check` fails the gate if they drift. The
+teeth live in `test/readme-sync-smoke.js`.
+
 For timing work, the smoke runner can write a JSON timing report without changing
 the normal output:
 
@@ -253,3 +262,7 @@ The release flow now captures the reviewer's verdict from agent stdout (`release
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/run-registry-control-plane.7.md

@@ -436,3 +436,7 @@ Security: archive import now refuses path-traversal run ids (`..`/absolute/separ
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/run-retention-reclamation.7.md

@@ -226,3 +226,7 @@ _No behavioral change in v0.1.88 (the tiered, append-only, cryptographically-ver
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/state-explosion-management.7.md

@@ -304,3 +304,7 @@ _No behavioral change in v0.1.88 (the summarization/compaction layer and its fai
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/team-collaboration.7.md

@@ -240,3 +240,7 @@ _No behavioral change in v0.1.88 (the host-attested actor, append-only approvals
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/web-desktop-workbench.7.md

@@ -248,3 +248,7 @@ _No behavioral change in v0.1.88 (the five operator surfaces and the registry cr
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/manifest/plugin.manifest.json

@@ -2,7 +2,7 @@
   "_comment": "SINGLE SOURCE OF TRUTH for every vendor manifest. Edit THIS file, then run `npm run gen:manifests`. Do NOT hand-edit the generated vendor manifests (.claude-plugin/, .codex-plugin/, .agents/, .mcp.json) — `npm run gen:manifests -- --check` (run by release:check) will fail if they drift from this source.",
   "identity": {
     "name": "cool-workflow",
-    "version": "0.1.90",
+    "version": "0.1.92",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.90",
+  "version": "0.1.92",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"
@@ -49,6 +49,8 @@
     "fixture-compat": "node test/run-fixture-compat-smoke.js",
     "sync:project-index": "node scripts/sync-project-index.js",
     "index:check": "node scripts/sync-project-index.js --check",
+    "sync:readme": "node scripts/sync-readme.js",
+    "readme:check": "node scripts/sync-readme.js --check",
     "bump:version": "node scripts/bump-version.js",
     "new:feature": "node scripts/new-feature.js",
     "forward-ref": "node scripts/forward-ref-docs.js",

package/scripts/agents/agent-adapter-core.js

@@ -51,6 +51,233 @@ function trace(line, env = process.env, stderr = process.stderr) {
   stderr.write(`${line}\n`);
 }
 
+// ---- live renderer (zero-dep, hand-rolled — kept self-contained so this wrapper stays a
+//      copyable "config", not a build-coupled dependency) -----------------------------------
+
+// The live "thinking" glyph cycles a sparkle (Claude-Code feel), not a generic braille spinner.
+const SPARKLE = ["✶", "✸", "✹", "✺", "✹", "✸"];
+const ANSI = { reset: "\x1b[0m", dim: "\x1b[2m", green: "\x1b[32m", red: "\x1b[31m", cyan: "\x1b[36m", hideCursor: "\x1b[?25l", showCursor: "\x1b[?25h", clearLine: "\r\x1b[2K" };
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function colorOn(env, stderr) {
+  if ((env.NO_COLOR ?? "") !== "" || (env.CW_NO_COLOR ?? "") !== "") return false;
+  if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0") return true;
+  return Boolean(stderr.isTTY);
+}
+// Behaviorally IDENTICAL to src/term.ts truncate() — the two copies exist only because the wrapper
+// is a self-contained plain-JS "config" (no import of the TS build). cli-render-smoke cross-checks
+// them on shared cases so this invariant cannot silently drift: maxWidth<=0 → ""; a string that fits
+// returns the ORIGINAL text (ANSI intact); otherwise stripped + sliced + "…".
+function truncate(text, max) {
+  if (max <= 0) return "";
+  const chars = [...String(text).replace(ANSI_RE, "")];
+  if (chars.length <= max) return String(text);
+  return max <= 1 ? "…" : `${chars.slice(0, max - 1).join("")}…`;
+}
+function fmtElapsed(ms) {
+  const s = ms / 1000;
+  return s < 60 ? `${s.toFixed(1)}s` : `${Math.floor(s / 60)}m${String(Math.round(s % 60)).padStart(2, "0")}s`;
+}
+
+/** A calm, FOLDING live view (interactive) or append-only lines (non-TTY), plus an always-on
+ *  transcript buffer. Interactive: a rolling window redrawn IN PLACE — the current action (spinner)
+ *  plus the last WINDOW completed tools (dimmed). Older tools fold away (the full trail is always in
+ *  the transcript), so the region stays a few rows and never grows into a wall; at the end it
+ *  collapses to ONE summary line. `action(label)` commits the PREVIOUS action then makes `label` the
+ *  current spinning action — vendor-neutral folding without needing reliable start/end pairing. */
+function createRenderer(opts = {}) {
+  const env = opts.env || process.env;
+  const stderr = opts.stderr || process.stderr;
+  const label = String(opts.label || "agent"); // provider name, only for the end-of-run summary line
+  const interactive = streamEnabled(env) && Boolean(stderr.isTTY);
+  // Non-TTY default stays SILENT (CW's Rule of Silence). Plain append-only logging in non-TTY
+  // is an explicit opt-in for CI debuggability — `CW_AGENT_STREAM=1`, mirroring CW_DRIVE_PROGRESS=1.
+  const plain = streamEnabled(env) && !stderr.isTTY && env.CW_AGENT_STREAM === "1";
+  const verbose = env.CW_VERBOSE === "1" || env.CW_VERBOSE === "true" || env.CW_OUTPUT === "full";
+  const color = colorOn(env, stderr);
+  const paint = (code, text) => (color ? `${code}${text}${ANSI.reset}` : text);
+
+  // How many completed tools stay visible above the spinner (the rolling window). Env-tunable.
+  const WINDOW = Math.max(0, Math.min(20, Number(env.CW_LIVE_ROWS) || 4));
+  const INDENT = "  ";
+  const cols = () => Math.max(20, Math.min(200, Number(stderr.columns) || 80));
+
+  const transcript = [];
+  const recent = [];    // [{ label, ms, failed }] — last WINDOW completed actions (interactive)
+  let blockRows = 0;    // terminal rows the live block occupied last frame (for in-place erase)
+  let steps = 0;        // total completed actions (for the summary line)
+  const runStart = Date.now();
+  let timer = null;
+  let frame = 0;
+  let cursorHidden = false;
+  let current = null;   // { label, startedAt, failed }
+
+  const restoreCursor = () => {
+    if (cursorHidden) { try { stderr.write(ANSI.showCursor); } catch { /* noop */ } cursorHidden = false; }
+  };
+  // Cursor hygiene: ALWAYS restore on exit / Ctrl-C / kill, even on crash.
+  const onSignal = (sig) => { stop(); process.exit(sig === "SIGINT" ? 130 : 143); };
+  if (interactive) {
+    process.once("exit", restoreCursor);
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+  }
+
+  // One completed-tool row, Claude-tree style: `  ● Read(foo.ts)` — the bullet is green (red on
+  // failure), the tool name bold + its (arg) dimmed; no per-tool duration. Width-truncated.
+  const styledLabel = (label, width) => {
+    const text = truncate(label, width - 4);
+    const m = /^(\w+)\((.*)\)$/.exec(text);
+    if (m) return `${m[1]}${paint(ANSI.dim, `(${m[2]})`)}`;
+    return text;
+  };
+  const doneLine = (item, width) => {
+    const bullet = paint(item.failed ? ANSI.red : ANSI.green, "●");
+    return `${INDENT}${bullet} ${styledLabel(item.label, width)}`;
+  };
+  // The live "thinking" row, Claude-tree style: `  ✶ Reading foo.ts… (4s)` — a sparkle + a
+  // tool-derived verb phrase + dim elapsed. A non-tool status label is shown as-is (sans trailing …).
+  const livePhrase = () => {
+    const m = /^(\w+)\((.*)\)$/.exec(current.label);
+    if (m) return `${verbFor(m[1])} ${m[2]}`;
+    return current.label.replace(/…+$/, "");
+  };
+  const liveLine = (width) => {
+    const elapsed = `(${fmtElapsed(Date.now() - current.startedAt)})`;
+    const el = paint(ANSI.dim, elapsed);
+    const sp = paint(ANSI.cyan, SPARKLE[frame % SPARKLE.length]);
+    // Reserve EXACT room for the fixed decorations + the VARIABLE elapsed string (which grows from 6
+    // chars `(4.0s)` to 9 `(100m00s)`): indent(2) + sparkle+space(2) + ellipsis+space(2) + elapsed,
+    // minus 1 column of margin. A fixed `width - N` budget overflowed past 1 minute and wrapped.
+    const budget = width - 6 - elapsed.length - 1;
+    return `${INDENT}${sp} ${truncate(livePhrase(), budget)}${paint(ANSI.dim, "…")} ${el}`;
+  };
+
+  // Erase the previously-drawn block in place: go to its first row, clear to end of screen.
+  const eraseBlock = () => {
+    if (!interactive || blockRows <= 0) return;
+    stderr.write("\r");
+    if (blockRows > 1) stderr.write(`\x1b[${blockRows - 1}A`);
+    stderr.write("\x1b[0J");
+    blockRows = 0;
+  };
+
+  // The `⎿ result` tree line under a completed tool (dimmed), e.g. `    ⎿ 245 lines`.
+  const resultLine = (result, width) => `${INDENT}  ${paint(ANSI.dim, `⎿ ${truncate(result, width - 6)}`)}`;
+
+  // Redraw the rolling window (recent ● rows + their ⎿ results + the live spinner) in place.
+  const renderBlock = () => {
+    if (!interactive) return;
+    if (!cursorHidden) { stderr.write(ANSI.hideCursor); cursorHidden = true; }
+    eraseBlock();
+    const width = cols();
+    const lines = [];
+    for (const item of recent.slice(-WINDOW)) {
+      lines.push(doneLine(item, width));
+      if (item.result) lines.push(resultLine(item.result, width));
+    }
+    if (current) lines.push(liveLine(width));
+    if (!lines.length) return;
+    // HARD GUARD: cap EVERY emitted line to the terminal width so none can wrap to a 2nd physical
+    // row. A wrapped row would make blockRows (logical count) under-count the real cursor movement,
+    // so eraseBlock's cursor-up would land a row short and corrupt/creep the block. This also closes
+    // the resize path: each frame caps to the CURRENT width, so a narrowed terminal can't desync.
+    const safe = lines.map((l) => truncate(l, width));
+    stderr.write(safe.join("\n"));
+    blockRows = safe.length;
+  };
+
+  const ensureTimer = () => {
+    if (interactive && !timer) timer = setInterval(() => { frame++; renderBlock(); }, 90);
+  };
+
+  // Commit the current action: record it to the transcript + roll it into the window (interactive)
+  // or append a plain line (CI). The interactive REDRAW happens in the caller (action/stop), so a
+  // commit never leaves a permanent per-tool line — that was the 0.1.91 "wall".
+  const commit = () => {
+    if (!current) return;
+    const ms = Date.now() - current.startedAt;
+    transcript.push(`- ${current.failed ? "✗" : "✓"} ${current.label} (${fmtElapsed(ms)})`);
+    steps += 1;
+    if (interactive) {
+      recent.push({ label: current.label, id: current.id, result: current.result, failed: current.failed });
+      while (recent.length > WINDOW) recent.shift();
+    } else if (plain) {
+      stderr.write(`${current.failed ? "✗" : "✓"} ${current.label} (${fmtElapsed(ms)})\n`);
+    }
+    current = null;
+  };
+
+  return {
+    /** Begin a new active action (folds the previous one into the rolling window). `id` (a vendor
+     *  tool_use id) lets a later result() attach to THIS tool even after it has folded — needed when
+     *  one assistant turn dispatches several tools before their results arrive. */
+    action(label, id) {
+      commit();
+      current = { label: String(label || "working…"), id, startedAt: Date.now(), failed: false };
+      ensureTimer();
+      if (interactive) renderBlock();
+      else if (plain) stderr.write(`→ ${current.label}\n`);
+    },
+    /** Mark the current action as failed (it folds in as a red ●). */
+    fail() { if (current) current.failed = true; },
+    /** Attach a short result summary to a tool — rendered as a dim `⎿ summary` tree line. `id` keys
+     *  it to a SPECIFIC tool_use so a batch of tools dispatched in one turn each keep their own result
+     *  (without an id it falls back to the current tool). Always recorded to the transcript. */
+    result(summary, failed, id) {
+      const s = String(summary || "").replace(/\s+/g, " ").trim();
+      if (!s && !failed) return;
+      // Find the target: prefer the matching id (current, else the most-recent committed item with
+      // that id); otherwise the current tool. This keeps earlier batched tools' ⎿ from being lost.
+      let target = null;
+      if (id != null) {
+        if (current && current.id === id) target = current;
+        else for (let k = recent.length - 1; k >= 0; k -= 1) { if (recent[k].id === id) { target = recent[k]; break; } }
+      }
+      if (!target) target = current;
+      if (target) { if (s) target.result = s; if (failed) target.failed = true; }
+      if (s) transcript.push(`  ⎿ ${s}`);
+      if (plain && s) stderr.write(`  ⎿ ${s}\n`);
+      // A result attached to an ALREADY-folded item must redraw the block to show its new ⎿.
+      if (interactive && target && target !== current) renderBlock();
+    },
+    /** Narration text from the model. Always to the transcript; inline only in --verbose (printed
+     *  ABOVE the live window, which then redraws below it). */
+    text(chunk) {
+      const t = String(chunk || "").trim();
+      if (!t) return;
+      transcript.push(t);
+      if (!verbose) return;
+      if (interactive) { eraseBlock(); stderr.write(`${INDENT}${paint(ANSI.dim, truncate(t, cols() - 2))}\n`); renderBlock(); }
+      else if (plain) stderr.write(`${truncate(t, cols())}\n`);
+    },
+    /** A short status note (e.g. provider summary). Transcript always; inline in --verbose. */
+    note(text) { this.text(text); },
+    /** Stop the spinner + restore the terminal. Idempotent. */
+    finishLive() { stop(); },
+    /** Persist the full transcript (narration + tool I/O) regardless of verbosity. */
+    writeTranscript(filePath) {
+      try { fs.writeFileSync(filePath, `# Agent transcript\n\n${transcript.join("\n")}\n`, "utf8"); } catch { /* advisory */ }
+    },
+    isVerbose: () => verbose
+  };
+
+  // Stop: fold the last action in, erase the live window, and collapse to ONE permanent summary
+  // line (`  ✓ <provider> — N steps · 2m41s`) so the worker leaves a single calm trace.
+  function stop() {
+    if (timer) { clearInterval(timer); timer = null; }
+    commit();
+    if (interactive) {
+      eraseBlock();
+      if (steps > 0) {
+        const summary = `${paint(ANSI.green, "●")} ${paint(ANSI.dim, `${label} · ${steps} step${steps === 1 ? "" : "s"} · ${fmtElapsed(Date.now() - runStart)}`)}`;
+        stderr.write(`${INDENT}${summary}\n`);
+      }
+    }
+    restoreCursor();
+  }
+}
+
 function shortText(value, max = 100) {
   const text = String(value || "").replace(/\s+/g, " ").trim();
   if (!text) return "";
@@ -96,6 +323,52 @@ function toolArgFromEvent(ev) {
   return firstString(input.file_path, input.path, input.pattern, input.command, input.query, input.url, input.cmd) || "";
 }
 
+// ---- Claude-Code-style tool labels: `ToolName(compactArg)` -------------------------------------
+// File tools show the BASENAME (Read(foo.ts), not Read(/Users/…/foo.ts)); everything else (Bash
+// commands, Grep/Glob patterns) is collapsed + truncated. Shared by every wrapper so the look can't
+// drift per vendor.
+const FILE_TOOLS = /^(Read|Write|Edit|MultiEdit|NotebookEdit|NotebookRead)$/i;
+function compactToolArg(name, rawArg) {
+  const s = String(rawArg || "").replace(/\s+/g, " ").trim();
+  if (!s) return "";
+  if (FILE_TOOLS.test(String(name || "")) && s.includes("/")) return s.split("/").filter(Boolean).pop() || s;
+  return s.length > 40 ? `${s.slice(0, 39)}…` : s;
+}
+function toolLabel(name, rawArg) {
+  const n = String(name || "").trim();
+  const arg = compactToolArg(n, rawArg);
+  return arg ? `${n}(${arg})` : n;
+}
+// The present-tense verb for the live "thinking" line, derived from the tool.
+function verbFor(name) {
+  const t = String(name || "").toLowerCase();
+  if (/read|cat|notebookread/.test(t)) return "Reading";
+  if (/write|edit/.test(t)) return "Editing";
+  if (/bash|shell|exec|run|command/.test(t)) return "Running";
+  if (/grep|glob|search|find|ls|list/.test(t)) return "Searching";
+  if (/fetch|web|http|download/.test(t)) return "Fetching";
+  if (/task|agent|sub/.test(t)) return "Delegating";
+  return "Working";
+}
+
+// A short result summary for the `⎿` tree line, derived from the tool + its raw output (Claude-Code
+// feel: `⎿ 245 lines` / `⎿ 12 matches` / `⎿ error`). Heuristic + tool-aware; never throws.
+function summarizeToolResult(name, text, isError) {
+  if (isError) return "error";
+  const raw = String(text || "");
+  const lines = raw.split("\n").filter((l) => l.trim().length).length;
+  const t = String(name || "").toLowerCase();
+  let s;
+  if (/read|cat/.test(t)) s = `${lines} line${lines === 1 ? "" : "s"}`;
+  else if (/glob|ls|find/.test(t)) s = `${lines} file${lines === 1 ? "" : "s"}`;
+  else if (/grep|search/.test(t)) s = `${lines} match${lines === 1 ? "" : "es"}`;
+  else if (/bash|shell|exec|run/.test(t)) {
+    const first = raw.split("\n").map((l) => l.trim()).find(Boolean) || "";
+    s = lines <= 1 && first ? first : `${lines} line${lines === 1 ? "" : "s"}`;
+  } else s = `${lines} line${lines === 1 ? "" : "s"}`;
+  return s.length > 40 ? `${s.slice(0, 39)}…` : s;
+}
+
 function textFromEvent(ev) {
   const delta = maybeObject(ev.delta);
   const msg = maybeObject(ev.message);
@@ -109,20 +382,28 @@ function renderJsonEvent(provider, ev, state) {
   const usage = usageFromEvent(ev);
   if (usage) state.usage = usage;
 
+  const r = state.renderer;
   const type = String(ev.type || ev.event || ev.kind || "");
+  if (ev.is_error === true && r) r.fail();
+
   const toolName = toolNameFromEvent(ev);
   if (toolName || /tool|command/i.test(type)) {
-    const arg = shortText(toolArgFromEvent(ev), 80);
-    trace(`  -> ${toolName || type}${arg ? ` ${arg}` : ""}`);
+    const label = toolLabel(toolName || type, toolArgFromEvent(ev));
+    if (r) r.action(label);
+    else trace(`  -> ${label}`);
     return;
   }
 
   const text = textFromEvent(ev);
   if (text && /assistant|message|delta|text|response|output/i.test(type || "text")) {
-    trace(`  ${shortText(text, 240)}`);
+    if (r) r.text(text);
+    else trace(`  ${shortText(text, 240)}`);
   } else if (/turn|step|summary|status/i.test(type)) {
     const status = firstString(ev.status, ev.status_detail, ev.summary, ev.message);
-    if (status) trace(`  . ${provider}: ${shortText(status, 160)}`);
+    if (status) {
+      if (r) r.note(`${provider}: ${status}`);
+      else trace(`  . ${provider}: ${shortText(status, 160)}`);
+    }
   }
 }
 
@@ -173,6 +454,10 @@ module.exports = {
   streamEnabled,
   traceEnabled,
   trace,
+  createRenderer,
+  truncate, // exported only so cli-render-smoke can assert it stays identical to term.ts truncate()
+  toolLabel, // `ToolName(compactArg)` — shared by the claude wrapper so the label format can't drift
+  summarizeToolResult, // `⎿` result summary — shared so vendors derive it identically
   parseJsonLines,
   flushJsonLines,
   writeResult,

package/scripts/agents/claude-p-agent.js

@@ -28,12 +28,13 @@
 //   CW_AGENT_COMMAND="node $(pwd)/scripts/agents/claude-p-agent.js {{input}} {{result}}"
 
 const fs = require("node:fs");
+const path = require("node:path");
 const { spawn, spawnSync } = require("node:child_process");
 // Share the ONE canonical result contract with the codex/gemini/opencode
 // wrappers instead of carrying a private copy. A drifted inline copy (ASCII
 // hyphens silently became em-dashes here) meant claude was sent a different
 // instruction text than the other providers for the same contract.
-const { buildPrompt } = require("./agent-adapter-core");
+const { buildPrompt, createRenderer, toolLabel, summarizeToolResult } = require("./agent-adapter-core");
 
 const inputPath = process.argv[2];
 const resultPath = process.argv[3];
@@ -77,32 +78,37 @@ if (!streamEnabled) {
   process.exit(0);
 }
 
-// Live trace → stderr only. Concise; one line per meaningful event.
-function trace(line) {
-  if (!traceEnabled) return;
-  process.stderr.write(`${line}\n`);
-}
-function shortInput(tool, input) {
+// The shared `toolLabel` (from the core) renders `ToolName(basename)` — the Claude-tree label format
+// every vendor uses, so the look can't drift between wrappers.
+function pickInput(input) {
   if (!input || typeof input !== "object") return "";
-  const v = input.file_path || input.path || input.pattern || input.command || input.query || input.url || "";
-  const s = String(v).replace(/\s+/g, " ").trim();
-  return s ? ` ${s.length > 80 ? s.slice(0, 77) + "…" : s}` : "";
+  return input.file_path || input.path || input.pattern || input.command || input.query || input.url || "";
 }
 
-// stream-json so claude emits incremental NDJSON events we can render live, while
-// we reconstruct the single {model, usage, result} object CW consumes on stdout.
+// The live view (spinner + folding actions on a TTY, plain append-only when piped, silent when
+// CW_AGENT_STREAM=0) + cursor hygiene + an always-on-disk transcript live in the shared core.
+void traceEnabled; // superseded by the renderer (which does its own TTY/stream gating)
+const render = createRenderer({ env: process.env, stderr: process.stderr, label: "claude" });
+const transcriptPath = path.join(path.dirname(resultPath), "transcript.md");
+
+// stream-json so claude emits incremental NDJSON events we render live. We CAPTURE claude's
+// own stderr (do NOT inherit) so it can never corrupt the live region; it's surfaced only on a
+// non-zero exit.
 const child = spawn(
   "claude",
   ["-p", prompt, "--output-format", "stream-json", "--verbose", "--allowedTools", "Read,Grep,Glob,Bash"],
-  { stdio: ["ignore", "pipe", "inherit"] } // claude's own stderr → straight through
+  { stdio: ["ignore", "pipe", "pipe"] }
 );
 
 let model;
 let usage;
 let resultText;
 let buf = "";
+let childStderr = "";
+child.stderr.setEncoding("utf8");
+child.stderr.on("data", (d) => { if (childStderr.length < 1024 * 1024) childStderr += d; });
 
-trace("● claude: reading the repo (read-only)…");
+render.action("claude: reading the repo (read-only)…");
 
 child.stdout.setEncoding("utf8");
 child.stdout.on("data", (chunk) => {
@@ -122,32 +128,53 @@ child.stdout.on("data", (chunk) => {
   }
 });
 
+const toolIds = new Map(); // tool_use id -> tool name, so a later tool_result can name its tool
+function toolResultText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.map((b) => (b && typeof b.text === "string" ? b.text : "")).join("\n");
+  return "";
+}
+
 function renderEvent(ev) {
   if (ev.type === "assistant" && ev.message) {
     if (!model && typeof ev.message.model === "string") model = ev.message.model;
     for (const part of ev.message.content || []) {
       if (part.type === "text" && part.text && part.text.trim()) {
-        trace(`  ${part.text.trim().replace(/\n+/g, "\n  ")}`);
+        render.text(part.text.trim());
       } else if (part.type === "tool_use") {
-        trace(`  → ${part.name}${shortInput(part.name, part.input)}`);
+        if (part.id) toolIds.set(part.id, part.name);
+        render.action(toolLabel(part.name, pickInput(part.input)), part.id);
+      }
+    }
+  } else if (ev.type === "user" && ev.message) {
+    // claude runs the tools itself (headless -p) and echoes each result back as a tool_result block;
+    // summarize it into the `⎿` tree line for the tool it belongs to.
+    for (const part of ev.message.content || []) {
+      if (part && part.type === "tool_result") {
+        const name = toolIds.get(part.tool_use_id) || "";
+        render.result(summarizeToolResult(name, toolResultText(part.content), part.is_error), part.is_error, part.tool_use_id);
       }
     }
   } else if (ev.type === "system" && ev.subtype === "post_turn_summary" && ev.status_detail) {
-    trace(`  · ${ev.status_detail}`);
+    render.note(ev.status_detail);
   } else if (ev.type === "result") {
     if (typeof ev.result === "string") resultText = ev.result;
     if (ev.usage && typeof ev.usage === "object") usage = ev.usage;
-    if (ev.is_error) trace("  ✗ claude reported an error result");
+    if (ev.is_error) render.fail();
   }
 }
 
 child.on("error", (err) => {
+  render.finishLive(); // restore the terminal before exiting
   process.stderr.write(`claude spawn failed: ${err.message}\n`);
   process.exit(1);
 });
 
 child.on("close", (code) => {
+  render.finishLive(); // stop the spinner + restore the cursor BEFORE any further output
+  render.writeTranscript(transcriptPath); // full narration + tool I/O always saved
   if (code !== 0) {
+    if (childStderr.trim()) process.stderr.write(`${childStderr.trim()}\n`);
     process.stderr.write(`claude exited ${code === null ? "(timeout/killed)" : code}\n`);
     process.exit(code === null ? 1 : code);
   }
@@ -158,7 +185,6 @@ child.on("close", (code) => {
   }
   // Persist the AGENT's final markdown to the worker's result.md (CW is transport).
   fs.writeFileSync(resultPath, resultText, "utf8");
-  trace("● done — result captured");
   // The single JSON CW consumes on STDOUT (data channel): model + usage + result.
   process.stdout.write(JSON.stringify({ model, usage, result: resultText }));
 });