relayrun 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# relayrun
+
+Watch a Claude agent work on a real codebase — together, live, with exactly one
+person holding the wheel.
+
+`relayrun` runs the agent **on your own machine**, against your own repository, on
+your own credentials. It connects out to a coordination server and prints a link.
+Anyone who opens that link watches the same session stream in the same moment.
+
+Part of [Relay](https://github.com/Avaya02/Relay). The agent engine is the
+[Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) — the same
+one Claude Code runs.
+
+## Quick start
+
+```bash
+cd your-project
+npx relayrun
+```
+
+That's it. You'll get:
+
+```
+  repo     your-project  (/Users/you/your-project)
+  agent    claude code login
+  session  8M2zrrx9Ng
+
+  Share this link:
+    https://relay-web-green.vercel.app/session/8M2zrrx9Ng
+```
+
+Send the link to anyone. They watch the agent work — every tool call, every
+diff, every failure — as it happens.
+
+## Why exactly one driver
+
+Multiplayer plus an agent that writes files is a concurrency problem. Relay
+avoids it rather than solving it: **only one participant can send instructions**,
+and the lock is enforced on the server, not in the UI. Everyone else watches, and
+can propose an instruction that the driver chooses to send or dismiss.
+
+Control moves by explicit hand-over. A driver who disconnects frees the wheel
+rather than wedging the session.
+
+## Options
+
+| Flag | |
+|---|---|
+| `--repo <path>` | Repository to work in (default: current directory) |
+| `--api-key <key>` | Bill runs to this key instead of your Claude Code login |
+| `--mock` | Scripted offline agent — see below |
+| `--session <id>` | Reattach to an existing session (needs `--token`) |
+| `--token <tok>` | Runner token for `--session` |
+| `--github-repo <o/n>` | Open a PR here on publish |
+| `--github-token <tok>` | Token for `--github-repo` |
+| `--server <url>` | Coordination server to use |
+| `--web <url>` | Web app, for the printed link |
+| `-h, --help` | Show usage |
+
+`--mock` replays a fixed script and **ignores what you type**. It's free and
+offline, and it exists for developing the UI — not for real answers.
+
+## Billing
+
+By default runs are billed to your existing Claude Code login. Pass `--api-key`
+to bill an Anthropic API key instead; it's verified before the session opens, so
+a bad key fails immediately rather than mid-run.
+
+Either way, the credential stays on your machine. It is never sent to the
+coordination server.
+
+## What leaves your machine
+
+The agent works in a **disposable clone**, not your live checkout, so an agent
+mistake can't touch uncommitted work.
+
+Sent to the server: the transcript viewers need — instructions, tool calls,
+results, diffs, and status. Not sent: your credentials, your working tree, or
+anything the agent didn't emit as part of a run.
+
+The connection is outbound only. Nothing listens, so there are no ports to open.
+
+## Reattaching
+
+If the CLI stops, the session survives. Restart with the token it printed:
+
+```bash
+relayrun --session 8M2zrrx9Ng --token <runner-token>
+```
+
+## Requirements
+
+- Node.js >= 20.9.0
+- `git`, and a repository to run in
+- A Claude Code login or an Anthropic API key (unless using `--mock`)
+
+## License
+
+MIT

package/dist/agent/diff.js

@@ -0,0 +1,75 @@
+import { planItems } from "./summarize.js";
+/**
+ * Line-level diff for the expandable detail on an edit row.
+ *
+ * Hand-written rather than pulled from a package: the inputs are one Edit's
+ * old/new strings, and this keeps a diff library out of the browser bundle —
+ * the ledger receives finished lines, not two blobs to diff client-side.
+ */
+export function lineDiff(oldStr, newStr) {
+    const a = oldStr.split("\n");
+    const b = newStr.split("\n");
+    // Guard against a pathological LCS table on a huge Write. Above this, show
+    // the change wholesale rather than hanging the run.
+    if (a.length * b.length > 40_000) {
+        return [
+            ...a.map((text) => ({ op: "-", text })),
+            ...b.map((text) => ({ op: "+", text })),
+        ];
+    }
+    const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            dp[i][j] =
+                a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            out.push({ op: " ", text: a[i] });
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            out.push({ op: "-", text: a[i++] });
+        }
+        else {
+            out.push({ op: "+", text: b[j++] });
+        }
+    }
+    while (i < a.length)
+        out.push({ op: "-", text: a[i++] });
+    while (j < b.length)
+        out.push({ op: "+", text: b[j++] });
+    return out;
+}
+// What, if anything, is worth showing when a row is expanded. Only edits get a
+// diff — a Read's contents are the agent's business, not the watcher's.
+export function detailForCall(tool, input, path) {
+    if (tool === "Edit" &&
+        typeof input.old_string === "string" &&
+        typeof input.new_string === "string") {
+        return { type: "diff", path, lines: lineDiff(input.old_string, input.new_string) };
+    }
+    if (tool === "Write" && typeof input.content === "string") {
+        // A new file is all additions — that IS the diff, and it reads correctly in
+        // the same renderer.
+        return {
+            type: "diff",
+            path,
+            lines: input.content.split("\n").map((text) => ({ op: "+", text })),
+        };
+    }
+    if (tool === "TodoWrite") {
+        // The whole checklist rides along on the event. The client takes the newest
+        // one as the session's current plan, which is what makes it survive replay
+        // and late joins with no separate plan message and no server-side state.
+        const todos = planItems(input.todos);
+        if (todos.length)
+            return { type: "plan", todos };
+    }
+    return undefined;
+}

package/dist/agent/mock.js

@@ -0,0 +1,175 @@
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+const STEP_DELAY_MS = 700;
+const INITIAL_DELAY_MS = 400;
+function textStep(text) {
+    return (emit) => emit.event("agent_text", { text });
+}
+function toolCallStep(id, tool, verb, target, detail) {
+    return (emit) => emit.event("tool_call", { id, tool, verb, target, detail });
+}
+function toolResultStep(id, tool, ok, summary, detail) {
+    return (emit) => emit.event("tool_result", { id, tool, ok, summary, detail });
+}
+// The mock has to exercise the plan strip too, for the same reason it has to
+// actually write files: a surface that only appears under the real agent can
+// only be tested by spending API quota.
+function planStep(id, done, active, steps) {
+    const todos = steps.map((content, i) => ({
+        content,
+        status: i < done ? "completed" : i === active ? "in_progress" : "pending",
+        activeForm: content.replace(/^[A-Z]/, (c) => c.toLowerCase()),
+    }));
+    const activeItem = todos.find((t) => t.status === "in_progress");
+    const target = activeItem
+        ? (activeItem.activeForm ?? activeItem.content)
+        : done === steps.length
+            ? "all steps complete"
+            : `${steps.length} steps`;
+    return [
+        toolCallStep(id, "TodoWrite", "planned", target, { type: "plan", todos }),
+        toolResultStep(id, "TodoWrite", true, "plan updated"),
+    ];
+}
+// Real agents answer "what's in here?" with a wall of markdown — the case that
+// used to push the whole ledger off screen, so the mock has to produce one or
+// the clamp is untestable offline.
+const MOCK_LONG_REPLY = [
+    "Here's what changed, with the surrounding structure for context:",
+    "",
+    "**Root**",
+    "",
+    ...["README.md", "RELAY_NOTES.md", "package.json", "pnpm-workspace.yaml", "tsconfig.json"].map((f) => `- \`${f}\``),
+    "",
+    "**src/**",
+    "",
+    ...[
+        "App.tsx",
+        "main.tsx",
+        "index.css",
+        "components/Button.tsx",
+        "components/Panel.tsx",
+        "hooks/use-store.ts",
+        "hooks/use-theme.ts",
+        "lib/api.ts",
+        "lib/format.ts",
+        "lib/types.ts",
+    ].map((f) => `- \`src/${f}\``),
+    "",
+    "**tests/**",
+    "",
+    ...["App.test.tsx", "lib/format.test.ts", "setup.ts"].map((f) => `- \`tests/${f}\``),
+    "",
+    "The only file I added is `RELAY_NOTES.md`; everything else was already tracked.",
+].join("\n");
+const MOCK_PLAN = [
+    "Read the existing notes file",
+    "Write RELAY_NOTES.md",
+    "Run the test suite",
+    "Fix the failing assertion",
+];
+const MOCK_DIFF = {
+    type: "diff",
+    path: "RELAY_NOTES.md",
+    lines: [
+        { op: "+", text: "# Relay notes" },
+        { op: "+", text: "" },
+        { op: "+", text: "Written by the mock agent." },
+    ],
+};
+function buildScript(instruction) {
+    const n = Date.now().toString(36);
+    return [
+        textStep(`On it — looking into **"${instruction.trim() || "your request"}"**.`),
+        ...planStep(`${n}-p1`, 0, 0, MOCK_PLAN),
+        toolCallStep(`${n}-1`, "Bash", "ran", "ls src/"),
+        toolResultStep(`${n}-1`, "Bash", true, "12 lines", {
+            type: "text",
+            text: "App.tsx\nmain.tsx\nindex.css\ncomponents/\nhooks/\nlib/",
+        }),
+        textStep("Found the right spot. Making the change now."),
+        ...planStep(`${n}-p2`, 1, 1, MOCK_PLAN),
+        toolCallStep(`${n}-2`, "Write", "wrote", "RELAY_NOTES.md", MOCK_DIFF),
+        toolResultStep(`${n}-2`, "Write", true, "written"),
+        // One nested path, deliberately: a root-only mock can't exercise the
+        // workspace rail's directory/filename split.
+        toolCallStep(`${n}-2b`, "Write", "wrote", "docs/session-log.md", {
+            type: "diff",
+            path: "docs/session-log.md",
+            lines: [
+                { op: "+", text: "# Session log" },
+                { op: "+", text: "" },
+                { op: "+", text: "Nested so the file list has a path to shorten." },
+            ],
+        }),
+        toolResultStep(`${n}-2b`, "Write", true, "written"),
+        ...planStep(`${n}-p3`, 2, 2, MOCK_PLAN),
+        toolCallStep(`${n}-3`, "Bash", "ran", "npm test"),
+        toolResultStep(`${n}-3`, "Bash", false, "1 failing — App renders a counter", {
+            type: "text",
+            text: "FAIL src/App.test.tsx\n  ● App › renders a counter\n    expected 1 to be 0",
+        }),
+        textStep("That test asserted the old markup. Fixing the assertion."),
+        ...planStep(`${n}-p4`, 3, 3, MOCK_PLAN),
+        toolCallStep(`${n}-4`, "Bash", "ran", "npm test"),
+        toolResultStep(`${n}-4`, "Bash", true, "4 passed"),
+        ...planStep(`${n}-p5`, 4, null, MOCK_PLAN),
+        textStep(MOCK_LONG_REPLY),
+        textStep("Done — tests pass."),
+    ];
+}
+/**
+ * The mock claims to edit files, so it should actually edit them. Otherwise the
+ * offline path can't exercise anything downstream of the working dir — the
+ * session diff and publish flow would only ever be testable by spending real
+ * API quota, which defeats the point of having a mock at all.
+ */
+async function applyMockEdits(dir) {
+    try {
+        await writeFile(path.join(dir, "RELAY_NOTES.md"), `# Relay notes\n\nWritten by the mock agent at ${new Date().toISOString()}.\n\n` +
+            `This file exists so the session-diff and publish flow can be exercised\n` +
+            `without spending API quota.\n`);
+        await mkdir(path.join(dir, "docs"), { recursive: true });
+        await writeFile(path.join(dir, "docs", "session-log.md"), `# Session log\n\nNested so the file list has a path to shorten.\n`);
+        await appendFile(path.join(dir, "README.md"), `\n<!-- touched by a Relay mock session -->\n`);
+    }
+    catch (err) {
+        console.error("mock agent: could not write to the working dir, continuing without file changes:", err instanceof Error ? err.message : err);
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+export async function runMockAgent(opts) {
+    const { emit, instruction, workingDir, signal } = opts;
+    const script = buildScript(instruction);
+    const startedAt = Date.now();
+    void applyMockEdits(workingDir);
+    await sleep(INITIAL_DELAY_MS, signal);
+    for (const step of script) {
+        if (signal.aborted) {
+            emit.status("idle");
+            return;
+        }
+        step(emit);
+        await sleep(STEP_DELAY_MS, signal);
+    }
+    if (signal.aborted) {
+        emit.status("idle");
+        return;
+    }
+    // Same shape the real agent reports, so the capstone row renders identically
+    // offline. The cost is fabricated; nothing was spent.
+    emit.event("agent_done", {
+        steps: 4,
+        durationMs: Date.now() - startedAt,
+        costUsd: 0.0128,
+    });
+    emit.status("done");
+}

package/dist/agent/orient.js

@@ -0,0 +1,51 @@
+import { readdir } from "node:fs/promises";
+// Directories that are never what someone means by "the project", and which
+// would otherwise dominate a top-level listing.
+const NOISE = new Set([
+    ".git", "node_modules", "dist", "build", ".next", ".turbo",
+    ".cache", "coverage", ".venv", "__pycache__", ".DS_Store",
+]);
+const MAX_ENTRIES = 40;
+/**
+ * A short description of where the agent has landed.
+ *
+ * Every run was opening with two or three failed reads: the agent starts in a
+ * disposable clone under the OS temp directory, guesses at conventional paths
+ * (`server.ts`, `README.md`) from the repository *name*, misses, and only then
+ * runs `pwd && ls` to orient itself. Observed on every real session so far.
+ *
+ * Handing it the listing up front removes that entirely. The cost is a few
+ * hundred tokens on the first turn; the saving is two round-trips of latency
+ * and the impression, for anyone watching the ledger, that the agent is lost.
+ */
+export async function orientation(workingDir) {
+    let listing;
+    try {
+        const entries = await readdir(workingDir, { withFileTypes: true });
+        const visible = entries
+            .filter((e) => !NOISE.has(e.name) && !e.name.startsWith("."))
+            .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+            .sort();
+        listing =
+            visible.length === 0
+                ? "(empty)"
+                : visible.slice(0, MAX_ENTRIES).join("  ") +
+                    (visible.length > MAX_ENTRIES ? `  … +${visible.length - MAX_ENTRIES} more` : "");
+    }
+    catch {
+        // Orientation is a convenience, never a precondition — a run must not fail
+        // because the listing could not be read.
+        return "";
+    }
+    return [
+        `You are working in ${workingDir}.`,
+        "",
+        "This is a disposable clone of the user's repository, so the path is a",
+        "temporary one and paths from the project's own documentation will not",
+        "resolve from anywhere else. Everything you need is under this directory.",
+        "",
+        `Top level: ${listing}`,
+        "",
+        "Use these names directly rather than guessing at conventional paths.",
+    ].join("\n");
+}

package/dist/agent/run.js

@@ -0,0 +1,129 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { redactKeys } from "../redact.js";
+import { detailForCall } from "./diff.js";
+import { resultText, summarizeToolCall, summarizeToolResult } from "./summarize.js";
+import { orientation } from "./orient.js";
+export async function runRealAgent(opts) {
+    const { emit, instruction, workingDir, signal, resume, apiKeyHelper } = opts;
+    const pending = new Map();
+    const model = process.env.RELAY_MODEL ?? "claude-haiku-4-5";
+    // The SDK wants an AbortController, but ownership of stopping a run belongs
+    // to the runner, which already holds one. Bridge the two.
+    const abort = new AbortController();
+    if (signal.aborted)
+        abort.abort();
+    else
+        signal.addEventListener("abort", () => abort.abort(), { once: true });
+    // Inline settings, so a run is unaffected by whatever the operator has in
+    // their own settings files, and the helper can't be overridden.
+    const keyOptions = apiKeyHelper
+        ? { settings: { apiKeyHelper } }
+        : {};
+    try {
+        // Resolved before the run so the agent opens by acting rather than by
+        // working out where it is — see orient.ts.
+        const where = await orientation(workingDir);
+        const q = query({
+            prompt: instruction,
+            options: {
+                cwd: workingDir,
+                model,
+                ...(where
+                    ? { systemPrompt: { type: "preset", preset: "claude_code", append: where } }
+                    : {}),
+                abortController: abort,
+                // Headless: there is no human here to approve each tool call. The agent
+                // runs with the operator's own permissions on their own machine, which
+                // is the same trust boundary as running Claude Code directly.
+                permissionMode: "bypassPermissions",
+                allowDangerouslySkipPermissions: true,
+                ...keyOptions,
+                ...(resume ? { resume } : {}),
+            },
+        });
+        for await (const msg of q) {
+            // Guarded on an actual change: the SDK repeats session_id on nearly every
+            // message, and reporting it each time would fire a Postgres upsert per
+            // tool call instead of once per run.
+            if ("session_id" in msg && msg.session_id && msg.session_id !== opts.resume) {
+                emit.agentSession(msg.session_id);
+            }
+            if (msg.type === "assistant") {
+                for (const block of msg.message.content) {
+                    if (block.type === "text") {
+                        const text = block.text.trim();
+                        if (text)
+                            emit.event("agent_text", { text });
+                    }
+                    else if (block.type === "tool_use") {
+                        const input = (block.input ?? {});
+                        const { verb, target } = summarizeToolCall(block.name, input, workingDir);
+                        pending.set(block.id, { tool: block.name, verb, target });
+                        emit.event("tool_call", {
+                            // `id` pairs this with its result so the ledger renders ONE row
+                            // per action: it appears now, pending, and completes on arrival.
+                            id: block.id,
+                            tool: block.name,
+                            verb,
+                            target,
+                            detail: detailForCall(block.name, input, target),
+                        });
+                    }
+                }
+            }
+            else if (msg.type === "user") {
+                const content = msg.message.content;
+                if (Array.isArray(content)) {
+                    for (const block of content) {
+                        if (block.type !== "tool_result")
+                            continue;
+                        const call = pending.get(block.tool_use_id);
+                        pending.delete(block.tool_use_id);
+                        const ok = block.is_error !== true;
+                        const tool = call?.tool ?? "tool";
+                        const full = resultText(block.content).trim();
+                        emit.event("tool_result", {
+                            id: block.tool_use_id,
+                            tool,
+                            ok,
+                            summary: summarizeToolResult(tool, block.content, workingDir, ok),
+                            // Bulk output goes behind the disclosure rather than being
+                            // truncated away — the summary stays scannable, the detail stays
+                            // available.
+                            detail: full.split("\n").length > 1
+                                ? { type: "text", text: full.split(`${workingDir}/`).join("") }
+                                : undefined,
+                        });
+                    }
+                }
+            }
+            else if (msg.type === "result") {
+                if (msg.subtype === "success") {
+                    emit.event("agent_done", {
+                        steps: msg.num_turns,
+                        durationMs: msg.duration_ms,
+                        costUsd: msg.total_cost_usd,
+                    });
+                    emit.status("done");
+                }
+                else {
+                    emit.event("agent_error", { message: `agent stopped: ${msg.subtype}` });
+                    emit.status("error");
+                }
+            }
+        }
+    }
+    catch (err) {
+        // An abort is a deliberate stop, not a failure to report as one. Still
+        // clear "working", so a driver who reconnects later isn't left watching a
+        // status that will never resolve on its own.
+        if (abort.signal.aborted) {
+            emit.status("idle");
+            return;
+        }
+        emit.event("agent_error", {
+            message: redactKeys(err instanceof Error ? err.message : String(err)),
+        });
+        emit.status("error");
+    }
+}

package/dist/agent/summarize.js

@@ -0,0 +1,151 @@
+import path from "node:path";
+/**
+ * TodoWrite's payload, defensively parsed. It arrives as untyped tool input,
+ * and a malformed one must degrade to "no plan" rather than throw inside the
+ * message loop and kill the run.
+ */
+export function planItems(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            continue;
+        const t = item;
+        if (typeof t.content !== "string")
+            continue;
+        const status = t.status === "in_progress" || t.status === "completed" ? t.status : "pending";
+        out.push({
+            content: t.content,
+            status,
+            activeForm: typeof t.activeForm === "string" ? t.activeForm : undefined,
+        });
+    }
+    return out;
+}
+/**
+ * Split into (verb, target) rather than one string so the ledger can align them
+ * as columns and the eye can scan down a column instead of parsing each line
+ * (DESIGN.md, ledger rule 3). Raw tool args must never be dumped into the UI —
+ * anything bulky goes in collapsed detail instead.
+ */
+export function summarizeToolCall(tool, input, workingDir) {
+    // Paths render relative to the repo root. An agent that guesses a path
+    // outside the working dir would otherwise produce a "../../../.." chain, so
+    // fall back to the bare filename in that case.
+    const rel = (p) => {
+        if (typeof p !== "string")
+            return "";
+        const relative = path.relative(workingDir, p);
+        if (!relative)
+            return path.basename(p);
+        return relative.startsWith("..") ? path.basename(p) : relative;
+    };
+    const clip = (s, n = 60) => {
+        const text = typeof s === "string" ? s.replace(/\s+/g, " ").trim() : "";
+        return text.length > n ? `${text.slice(0, n)}…` : text;
+    };
+    switch (tool) {
+        case "Bash":
+            return { verb: "ran", target: clip(input.command, 120) };
+        case "Read":
+            return { verb: "read", target: rel(input.file_path) };
+        case "Write":
+            return { verb: "wrote", target: rel(input.file_path) };
+        case "Edit":
+            return { verb: "edited", target: rel(input.file_path) };
+        case "NotebookEdit":
+            return { verb: "edited", target: rel(input.notebook_path) };
+        case "Glob":
+            return { verb: "globbed", target: clip(input.pattern, 60) };
+        case "Grep":
+            return { verb: "grepped", target: clip(input.pattern, 60) };
+        case "WebFetch":
+            return { verb: "fetched", target: clip(input.url, 70) };
+        case "WebSearch":
+            return { verb: "searched", target: clip(input.query, 60) };
+        case "Task":
+            return { verb: "delegated", target: clip(input.description, 70) };
+        case "TodoWrite": {
+            // "updated its plan" said nothing. Name the step it just started, so the
+            // ledger row carries the same information the plan strip does.
+            const todos = planItems(input.todos);
+            const active = todos.find((t) => t.status === "in_progress");
+            const done = todos.filter((t) => t.status === "completed").length;
+            if (active) {
+                return { verb: "planned", target: active.activeForm ?? active.content };
+            }
+            if (todos.length && done === todos.length) {
+                return { verb: "planned", target: "all steps complete" };
+            }
+            return {
+                verb: "planned",
+                target: todos.length ? `${todos.length} steps` : "updated its plan",
+            };
+        }
+        default:
+            return { verb: tool.toLowerCase(), target: "" };
+    }
+}
+export function resultText(content) {
+    return Array.isArray(content)
+        ? content
+            .map((b) => (b && typeof b === "object" && "text" in b ? String(b.text) : ""))
+            .join(" ")
+        : typeof content === "string"
+            ? content
+            : "";
+}
+// Phrasing the SDK writes for the model's benefit, not the watcher's. Left in,
+// it surfaces as "File created successfully at: REPORT.md (file state is
+// current in your…" — an internal aside truncated mid-sentence.
+const SDK_ASIDES = [
+    /\s*\(file state is current in your context[^)]*\)/gi,
+    /\s*<system-reminder>[\s\S]*?<\/system-reminder>/gi,
+];
+/**
+ * Per-tool result summaries. The generic "N lines" fallback told a watcher
+ * nothing on 12 of 13 rows in a real run (RELAY_PRODUCTION_PLAN.md §A3).
+ */
+export function summarizeToolResult(tool, content, workingDir, ok) {
+    let text = resultText(content);
+    for (const aside of SDK_ASIDES)
+        text = text.replace(aside, "");
+    // Absolute paths are noise in the ledger and leak the host's directory
+    // layout — show them relative to the repo root instead.
+    const cleaned = text.split(`${workingDir}/`).join("").trim();
+    const oneLine = cleaned.replace(/\s+/g, " ").trim();
+    const lines = cleaned ? cleaned.split("\n") : [];
+    const clip = (s, n = 70) => (s.length > n ? `${s.slice(0, n)}…` : s);
+    // A failure's reason is the whole point of the row — never flatten it to a
+    // bare "failed" (DESIGN.md ledger rule 7).
+    if (!ok)
+        return oneLine ? clip(oneLine, 90) : "failed";
+    switch (tool) {
+        case "Read":
+            return lines.length ? `${lines.length} lines` : "empty";
+        case "Write":
+            return "written";
+        case "Edit":
+        case "NotebookEdit":
+            return "applied";
+        case "Bash": {
+            if (!oneLine)
+                return "no output";
+            // One-line output is usually the answer itself; multi-line is bulk the
+            // watcher can expand into.
+            return lines.length > 1 ? `${lines.length} lines` : clip(oneLine);
+        }
+        case "Glob":
+        case "Grep": {
+            const n = lines.filter((l) => l.trim()).length;
+            return n === 1 ? "1 match" : `${n} matches`;
+        }
+        case "TodoWrite":
+            return "plan updated";
+        default:
+            if (!oneLine)
+                return "done";
+            return lines.length > 1 ? `${lines.length} lines` : clip(oneLine);
+    }
+}