@clearlysh/beehaven 0.8.16

package/dist/commands/sheet.js

@@ -0,0 +1,264 @@
+/**
+ * `beehaven sheet` — spreadsheets.
+ *
+ * ⚠⚠ WHY A VERB WHEN `call` ALREADY WORKED. Same argument `ticket.ts` makes: the six `sheet-*`
+ * actions had no CLI door at all, so every spreadsheet touched from a terminal was
+ * `beehaven call sheet-set '{…}'` — not by preference, but because there was nothing else. A
+ * first-class artifact with no verb is one nobody thinks to look for.
+ *
+ * ⚠ AND IT MAKES TWO TRAPS UNTYPEABLE, which is the only reason a wrapper earns its place here:
+ *
+ *   · `sheet-set` takes `{ id, at, rows }` — an ANCHOR cell plus a row array — or `{ id, cells }`
+ *     keyed by A1 reference. It does NOT take `range` + `tsv`; that is `sheet-get`'s shape, and
+ *     sending it here is two unknown keys, which validation strips, leaving a call that returns
+ *     ok having written nothing. ⚠ I wrote this verb wrong the first time on exactly that guess —
+ *     caught by reading `explain sheet-set`, not by reasoning about the name.
+ *   · `sheet-from-file` needs a workspace fileId, NOT a local path. Handing it `./data.csv` fails
+ *     in a way that reads as the file being unreadable; the refusal here says to `teleport` first.
+ *
+ * ⚠ `agentRpc`, NEVER bare `rpcOnce` — a bare call runs as the ACCOUNT OWNER rather than as the
+ * signed-in agent, skipping `agent-invoke`, the per-agent gate and the activity log.
+ */
+import { agentRpc as rpcOnce } from './workspace.js';
+const c = {
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+function getTimeout(values) {
+    const t = Number(values?.timeout);
+    return Number.isFinite(t) && t > 0 ? t : 30_000;
+}
+/** ⚠ `rpcOnce` returns `{ error }` as a VALUE and never throws — see `rpcFailure` in workspace.ts. */
+function failure(res) {
+    if (!res || typeof res !== 'object')
+        return null;
+    if (typeof res.error === 'string' && res.error)
+        return res.error;
+    if (res.ok === false)
+        return String(res.message ?? res.code ?? 'the workspace refused the call');
+    return null;
+}
+/**
+ * ⚠ `\n` AND `\t` ARRIVE LITERAL FROM A SHELL THAT DID NOT INTERPRET THEM. Single quotes, most
+ * `sh` builtins and every scripted caller pass the backslash through, so the documented example
+ * would otherwise store one cell containing `Region\tQ1`. Shared by `set` and `append` — they had
+ * drifted apart on exactly this, and a spreadsheet verb that disagrees with its sibling about what
+ * a tab is stores garbage that looks like data.
+ */
+function unescapeTsv(s) {
+    return s.replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+}
+function die(msg, hint) {
+    console.error(`  ${msg}`);
+    if (hint)
+        console.error(c.dim(`  ${hint}`));
+    process.exit(1);
+}
+export async function cmdSheet(sub, rest, values) {
+    const t = getTimeout(values);
+    if (!sub || sub === 'help') {
+        console.log(`
+  ${c.cyan('beehaven sheet')} — spreadsheets
+
+    sheet list                  Every sheet, newest first
+    sheet new "<title>"         Create one  (--project <id>)
+    sheet get <id>              Read it     (--range A1:D20)
+    sheet set <id> <at> <tsv>   Write a block at a cell  (<at> = TOP-LEFT, e.g. A1)
+    sheet append <id> <tsv>     Add rows at the end
+    sheet import <fileId>       Build a sheet from an uploaded CSV/spreadsheet
+
+  ${c.dim('<id> is a sheet id or its key (e.g. CLR-42).')}
+  ${c.dim('TSV: tab-separated cells, newline-separated rows. Quote the whole thing.')}
+  ${c.dim('<at> is one cell, not a range — set writes a block starting there.')}
+  ${c.dim('set REPLACES what it covers; append never overwrites. They are not synonyms.')}
+`);
+        return;
+    }
+    if (sub === 'list') {
+        const res = await rpcOnce('sheet-list', {}, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const rows = res?.sheets ?? [];
+        if (!rows.length) {
+            console.log('  No sheets.');
+            return;
+        }
+        console.log('');
+        for (const s of rows)
+            console.log(`  ${c.cyan(String(s.key ?? s.id ?? ''))}  ${String(s.title ?? 'Untitled')}`);
+        console.log('');
+        return;
+    }
+    if (sub === 'new' || sub === 'create') {
+        const title = rest.join(' ').trim();
+        if (!title)
+            die('a title is required', 'beehaven sheet new "Q1 revenue"');
+        /**
+         * ⚠⚠ `rows: []` IS LOAD-BEARING — `sheet-create` IS AN IMPORT VERB AND REFUSES A BARE TITLE.
+         *
+         * Measured: `{ title }` alone answers *"Nothing to import — pass csv, tsv, text, rows or
+         * localPath"* (`code: 'no-content'`). Reasonable for the job it was written for; wrong for the
+         * word "new", which to a person means an EMPTY spreadsheet they can then fill in.
+         *
+         * An empty array satisfies the `Array.isArray(input.rows)` branch, which returns before the
+         * content check — so it creates a real, empty sheet. Verified against the live worker.
+         */
+        const res = await rpcOnce('sheet-create', {
+            title,
+            rows: [],
+            ...(values.project ? { projectId: String(values.project) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Created ${c.cyan(String(res?.key ?? res?.id ?? ''))}`);
+        return;
+    }
+    if (sub === 'get') {
+        const id = rest[0];
+        if (!id)
+            die('a sheet id or key is required', 'beehaven sheet get CLR-42');
+        const res = await rpcOnce('sheet-get', {
+            id,
+            ...(values.range ? { range: String(values.range) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        /**
+         * ⚠⚠ THE DATA IS `cells`. `rows` IS A COUNT, AND READING IT LOOKS LIKE AN EMPTY SHEET.
+         *
+         * `sheet-get` answers `{ cells: [[…]], rows: 4, cols: 2, range: "A1:B4" }` — so `res.rows` is
+         * the NUMBER 4, `.length` on it is `undefined`, and this printed "(empty)" for a sheet with
+         * four populated rows. Written from the field name, caught only by reading a live response.
+         * A confident empty answer is the worst failure available here: it reads as data loss.
+         */
+        const rows = Array.isArray(res?.cells) ? res.cells : [];
+        // ⚠ TAB-SEPARATED, not a drawn table. The output of a spreadsheet read is data — a caller
+        //   pipes it into `cut`/`awk`, and box-drawing characters make that a parsing job.
+        const tsv = rows.map((r) => r.map((cell) => String(cell ?? '')).join('\t')).join('\n');
+        /**
+         * ⚠⚠ IT ACCEPTED `--out` AND WROTE NOTHING (CBH2-85). `--out`/`-o` are global in `parseArgs`,
+         * so this verb took the flag and printed to stdout anyway — the accept-and-ignore class this
+         * sweep keeps finding. `planDeckExport` is REUSED rather than re-implemented: it already owns
+         * the clobber refusal and the extension fallback, both sabotage-tested, and a second copy is
+         * how one verb comes to refuse an overwrite while its sibling silently performs one.
+         *
+         * ⚠ THE EMPTY CASE IS HANDLED **AFTER** THE WRITE DECISION, DELIBERATELY. Returning early on
+         * `!rows.length` would make `--out` on an empty sheet print "(empty)" and write nothing —
+         * accept-and-ignore again, in the one case a caller cannot distinguish from a failed read.
+         * An empty sheet writes an empty file, which is the honest answer.
+         */
+        const outPath = (values.out ?? values.output);
+        if (outPath) {
+            const { writeFileSync, existsSync } = await import('fs');
+            const { resolve } = await import('path');
+            const { planDeckExport } = await import('./slides.js');
+            const plan = planDeckExport(
+            // ⚠ A SYNTHETIC PAYLOAD, because the planner is shaped by the RESULT, not by the verb —
+            //   `{ content, filename }` is the same shape `deck-export`'s markdown returns.
+            { content: tsv, filename: `${res?.key ?? id}.tsv` }, { format: 'tsv', out: outPath, id: String(id), force: !!values.force }, existsSync, resolve);
+            if (!plan.ok)
+                die(plan.error, plan.hint);
+            for (const file of plan.files) {
+                const buf = Buffer.from(file.body.kind === 'text' ? file.body.content : '', 'utf8');
+                writeFileSync(file.dest, buf);
+                console.log(`  Wrote ${c.cyan(file.dest)}${c.dim(`  · ${buf.length} bytes · ${rows.length} rows`)}`);
+            }
+            return;
+        }
+        if (!rows.length) {
+            console.log('  (empty)');
+            return;
+        }
+        console.log(tsv);
+        return;
+    }
+    if (sub === 'set') {
+        /**
+         * ⚠⚠ `at` + `rows`, NOT `range` + `tsv` — AND I WROTE IT THE WRONG WAY FIRST.
+         *
+         * The obvious guess from the verb name is a RANGE (`A1:C2`) and a blob of text, which is what
+         * `sheet-get` takes. `sheet-set` takes a top-left ANCHOR (`at`) plus a `rows` array, or a
+         * `cells` map keyed by A1 reference. Sending `{ range, tsv }` is two unknown keys: validation
+         * strips them, `id` alone is valid, and the call returns ok having written nothing.
+         *
+         * This verb exists to make that untypeable, so it takes the anchor and does the parse.
+         */
+        const [id, at, ...tsvParts] = rest;
+        if (!id || !at) {
+            die('usage: beehaven sheet set <id> <at> <tsv>', 'e.g. beehaven sheet set CLR-42 A1 "Region\\tQ1\\nAPAC\\t7"  — `at` is the TOP-LEFT cell, not a range.');
+        }
+        const tsv = tsvParts.join(' ');
+        if (!tsv)
+            die('nothing to write', 'Pass TSV: tab-separated cells, newline-separated rows.');
+        // ⚠ `\n` and `\t` arrive as literal backslash-n from a shell that did not interpret them;
+        //   accept both so the documented example works whichever quoting the caller used.
+        const rows = unescapeTsv(tsv).split('\n').map((line) => line.split('\t'));
+        const res = await rpcOnce('sheet-set', { id, at, rows }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Wrote ${rows.length} row${rows.length === 1 ? '' : 's'} at ${c.cyan(at)} in ${c.cyan(id)}`);
+        return;
+    }
+    if (sub === 'append') {
+        const [id, ...tsvParts] = rest;
+        if (!id)
+            die('a sheet id or key is required', 'beehaven sheet append CLR-42 "row\\tvalues"');
+        const tsv = tsvParts.join(' ');
+        if (!tsv)
+            die('nothing to append');
+        // ⚠ SAME ESCAPE HANDLING AS `set` — without it `append "LATAM\t4"` stored the literal
+        //   backslash-t as ONE cell. A shell that did not interpret the escape hands it through
+        //   verbatim, and only `set` was expanding it, so the two verbs disagreed about their input.
+        const res = await rpcOnce('sheet-append', { id, tsv: unescapeTsv(tsv) }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Appended to ${c.cyan(id)}`);
+        return;
+    }
+    if (sub === 'import') {
+        const fileId = rest[0];
+        if (!fileId) {
+            die('a workspace fileId is required', 'Upload first:  beehaven teleport ./data.csv   → then pass the id it prints.');
+        }
+        const res = await rpcOnce('sheet-from-file', {
+            fileId,
+            ...(values.title ? { title: String(values.title) } : {}),
+            ...(values.project ? { projectId: String(values.project) } : {}),
+        }, t, values);
+        const f = failure(res);
+        if (f)
+            die(f);
+        if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        console.log(`  Created ${c.cyan(String(res?.key ?? res?.id ?? ''))}`);
+        return;
+    }
+    die(`unknown subcommand "${sub}"`, 'beehaven sheet help');
+}

package/dist/commands/shell-output.js

@@ -0,0 +1,309 @@
+/**
+ * What the shell verbs PRINT — extracted from `shell.ts` so the decision is testable.
+ *
+ * ⚠⚠ THE DEFECT THIS MODULE EXISTS FOR IS DISCARD, NOT ABSENCE. Every fact these commands failed
+ * to print was already in the RPC result and was dropped on the way to the terminal:
+ *
+ *   mv "~/nope.md" "~/x.md"  ->  { ok:false, error:'no such file', code:'enoent', hint:'Nothing at …' }
+ *   mkdir "~/Probe"          ->  { ok:true, folder:'~/Probe', id:'0bfecca9-…', created:true }
+ *   rm "~/Probe/OP-3.md"     ->  { ok:true, archived:['~/…'], note:'moved to Trash — restore …' }
+ *
+ * …and `execNotesShell` read only `stdout`, `rows` and `stderr`, so ALL of the above printed
+ * nothing at all. A failed `mv` and a successful one were byte-identical on screen.
+ *
+ * ⚠⚠ SO THE RULE IS GENERIC, NEVER A PER-VERB TEMPLATE. `summariseResult` renders whatever
+ * non-envelope fields came back, in the order the server sent them. A template per verb would
+ * have to be extended for every future verb, and the verb it was NOT extended for goes back to
+ * printing nothing — which is exactly the failure mode being fixed. Nothing here invents a field:
+ * if the server said it, it is printed; if it did not, it is absent.
+ *
+ * ⚠ AND A FAILURE IS NEVER SILENT, whatever shape it arrives in. `formatShellResult` falls back to
+ * a compact JSON dump of the result when `ok === false` carries no message, because an unreadable
+ * error is recoverable and an invisible one is not.
+ */
+/**
+ * Fields that are transport plumbing or an echo of the request — never news.
+ *
+ * ⚠ `command` AND `cwd` ARE AN ECHO, NOT A RESULT. The notes shell returns both on every call;
+ * printing them would repeat the line the caller just typed, under the breadcrumb that already
+ * repeats it.
+ *
+ * ⚠ `stdout`/`stderr`/`rows` ARE RENDERED SEPARATELY, and must not also appear in the summary —
+ * `sql` would print its whole result set twice.
+ */
+export const ENVELOPE_FIELDS = new Set([
+    'ok', 'type', 'requestId', 'command', 'cwd', 'stdout', 'stderr', 'rows', 'exitCode',
+]);
+/**
+ * Fields that are a SENTENCE rather than a value, so they get their own line.
+ *
+ * `rm`'s `note` ("moved to Trash — restore from the gallery, or with document-restore") is the
+ * single most load-bearing thing the organise verbs return, and inlining it into a `·`-joined
+ * summary buries it.
+ */
+const PROSE_FIELDS = new Set(['note', 'hint', 'warning', 'message']);
+const MAX_LIST_ITEMS = 3;
+function renderValue(v) {
+    if (Array.isArray(v)) {
+        const shown = v.slice(0, MAX_LIST_ITEMS).map((x) => (typeof x === 'string' ? x : JSON.stringify(x)));
+        const more = v.length > MAX_LIST_ITEMS ? ` (+${v.length - MAX_LIST_ITEMS} more)` : '';
+        return `${shown.join(', ')}${more}`;
+    }
+    if (v && typeof v === 'object')
+        return JSON.stringify(v);
+    return String(v);
+}
+/**
+ * A one-line confirmation built from the fields the server actually returned.
+ *
+ * ⚠ A `true` BOOLEAN RENDERS AS ITS BARE NAME (`created`, `existed`) and a `false` one is dropped.
+ * `created true` reads as a field dump; `created` reads as an outcome — and `mkdir` distinguishing
+ * `created` from `existed` is the whole difference between "I made that" and "it was already
+ * there", which the caller currently cannot see at all.
+ *
+ * Returns `''` when there is genuinely nothing beyond the envelope. Silence is only correct when
+ * nothing was discarded.
+ */
+export function summariseResult(r) {
+    const empty = { line: '', prose: [] };
+    if (!r || typeof r !== 'object' || Array.isArray(r))
+        return empty;
+    const parts = [];
+    const prose = [];
+    for (const [k, v] of Object.entries(r)) {
+        if (ENVELOPE_FIELDS.has(k))
+            continue;
+        if (v === undefined || v === null || v === '')
+            continue;
+        if (v === false)
+            continue;
+        if (PROSE_FIELDS.has(k)) {
+            prose.push(String(v));
+            continue;
+        }
+        if (v === true) {
+            parts.push(k);
+            continue;
+        }
+        if (Array.isArray(v) && v.length === 0)
+            continue;
+        parts.push(`${k} ${renderValue(v)}`);
+    }
+    return { line: parts.join(' · '), prose };
+}
+/**
+ * ⚠⚠ A HINT THAT NAMES A CAUSE MUST NOT BE RELAYED WHEN THE PAYLOAD CARRIES NO EVIDENCE FOR IT —
+ * CBH2-52.
+ *
+ *     $ beehaven edit ~/CH-1.md draft final          # CH-1 has NEVER contained "draft"
+ *     edit: find text not present
+ *       hint They edited this note after you last wrote to it — see changedByThem for what
+ *            moved, then retry with the passage as it now reads.
+ *
+ * The first line is correct. The hint asserts a SPECIFIC cause — a concurrent editor — that is
+ * false here: the string was never in the document, and the workspace has one author. There is no
+ * `changedByThem` in the payload to look at either.
+ *
+ * ⚠⚠ IT IS WORSE THAN NO HINT, WHICH IS THE WHOLE POINT. It sends the reader to diff a document
+ * against an edit that never happened, and on a shared workspace it INVENTS a collaborator
+ * conflict — a social fact, out of a typo. Same class as CBH2-61 and CBH2-51: an error that names
+ * the wrong cause is more expensive than one that names none, because it is actionable and the
+ * action is wasted.
+ *
+ * THE RULE, and it generalises past this one message: **a hint that tells you to go and look at a
+ * named field is only true if the field is there.** `see <field>` is a checkable claim, so it is
+ * checked against the payload rather than trusted. A hint that makes no such claim is relayed
+ * untouched — this suppresses false causes, not hints.
+ *
+ * ⚠ THE FIX IS HERE, NOT IN THE SERVER'S WORDING. `notes-edit` is right to offer the concurrent-
+ * edit story when it HAS the evidence, and this is the one place every shell verb's refusal passes
+ * through — so the check lands once instead of per verb, and a future hint of the same shape is
+ * covered on the day it is written.
+ *
+ * PURE and exported, so the decision is testable without a workspace.
+ */
+/**
+ * Does this receipt actually show something MOVING?
+ *
+ * ⚠⚠ PRESENCE IS NOT EVIDENCE, AND MEASURING IT WAS THE FIRST WRONG FIX. `changedByThem` is
+ * returned on EVERY `notes-edit` refusal, so a test for "is the field there" fires never. Measured
+ * on a freshly created document with one author and zero edits:
+ *
+ *     changedByThem: { edits: 1, at: 1788702512564, unchanged: true }
+ *
+ * **`unchanged: true`** — the workspace has already worked out that nothing moved, and prints
+ * *"They edited this note after you last wrote to it"* on top of its own contrary finding. So the
+ * check has to read the receipt, not count it. `edits: 1` there is the document's own CREATION.
+ */
+function movedSomething(v) {
+    if (v === undefined || v === null || v === '')
+        return false;
+    if (Array.isArray(v))
+        return v.length > 0;
+    if (typeof v !== 'object')
+        return true;
+    const r = v;
+    if (Object.keys(r).length === 0)
+        return false;
+    if (r.unchanged === true)
+        return false; // it says so itself
+    const moved = (k) => Array.isArray(r[k]) && r[k].length > 0;
+    // ⚠ Only when the receipt HAS these keys. A differently-shaped receipt is not evidence of
+    //   nothing — absent added/removed, a non-empty object that does not claim `unchanged` stands.
+    if ('added' in r || 'removed' in r)
+        return moved('added') || moved('removed');
+    return true;
+}
+export function vetHint(o, verb = '') {
+    const raw = typeof o.hint === 'string' ? o.hint.trim() : '';
+    if (!raw)
+        return null;
+    // The only claim shape worth policing: "…see <field> for what moved…" points at the payload.
+    const m = /\bsee\s+([a-z][A-Za-z0-9_]*)\b/.exec(raw);
+    if (!m)
+        return raw;
+    if (movedSomething(o[m[1]]))
+        return raw; // receipts — the hint stands
+    /**
+     * Unsupported. Say what IS known instead of what was guessed.
+     * ⚠ `not-found` gets a real next step; anything else gets SILENCE rather than an invented one —
+     * replacing one wrong cause with another is not an improvement.
+     */
+    if (o.code === 'not-found') {
+        const what = verb === 'edit' ? 'The passage is not in the document' : 'It is not there';
+        return `${what} — it may never have been, or it may have changed. `
+            + `Read it with \`cat\`, or \`grep\` for a phrase you are sure of, then retry with the exact text.`;
+    }
+    return null;
+}
+/**
+ * What a failed shell call says.
+ *
+ * ⚠⚠ IT CAN NEVER RETURN AN EMPTY STRING. The server's `error`/`code`/`hint` triple is the normal
+ * case, but a refusal that arrives in some other shape must still reach the screen — hence the
+ * JSON fallback. "The command failed and said nothing" is the one outcome this whole module
+ * exists to make impossible.
+ */
+export function formatFailure(r, verb = '') {
+    const o = (r && typeof r === 'object' ? r : {});
+    const prefix = verb ? `${verb}: ` : '';
+    const msg = [o.error, o.message, o.stderr].find((x) => typeof x === 'string' && x.trim());
+    const lines = [];
+    if (msg) {
+        lines.push(`${prefix}${String(msg).replace(/\n+$/, '')}`);
+    }
+    else {
+        // Nothing message-shaped came back. Show the whole thing rather than nothing.
+        const { line, prose } = summariseResult(o);
+        const detail = [line, ...prose].filter(Boolean).join(' · ');
+        lines.push(`${prefix}failed${detail ? ` — ${detail}` : ` — ${JSON.stringify(o)}`}`);
+    }
+    if (typeof o.code === 'string' && o.code.trim())
+        lines.push(`  code ${o.code}`);
+    // ⚠ CBH2-52 — vetted, not relayed. See `vetHint`: a hint naming a cause the payload cannot
+    //   support is worse than no hint, because it is actionable and the action is wasted.
+    const hint = vetHint(o, verb);
+    if (hint)
+        lines.push(`  hint ${hint}`);
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * The whole result → terminal mapping for a notes-shell call.
+ *
+ * ⚠ A STRUCTURED ANSWER IS STILL AN ANSWER. Most builtins write `stdout`; `sql` returns `rows`;
+ * the organise verbs return neither and were therefore invisible. All three are handled here so
+ * that one function can be asserted against every shape the shell produces.
+ *
+ * ⚠ A BARE `exit N` IS NOT A MESSAGE. The notes shell reports a non-zero exit as
+ * `stderr: "exit 1"`, and `grep` exits 1 when it matched nothing — real grep says nothing at all
+ * in that case. The code still rides on `exitCode`, so a script sees it and a person does not.
+ */
+export function formatShellResult(r, verb = '') {
+    const o = (r && typeof r === 'object' ? r : {});
+    const failed = o.ok === false;
+    const rawOut = String(o.stdout ?? '');
+    const rows = o.rows;
+    /**
+     * ⚠ JSON, NOT AN INVENTED TABLE. `beehaven call` already prints results this way, so a script
+     * can parse it and a person can read it; a second bespoke renderer here would be one more thing
+     * to keep in step with the shape the workspace actually returns.
+     */
+    const structured = !rawOut && Array.isArray(rows) ? `${JSON.stringify(rows, null, 2)}\n` : '';
+    let stdout = rawOut || structured;
+    const stderrText = String(o.stderr ?? '');
+    const bareExit = /^exit \d+$/.test(stderrText.trim());
+    let stderr = '';
+    if (failed) {
+        // ⚠ `exit 1` from a no-match grep is not an error to report; anything else is.
+        stderr = bareExit && !o.error && !o.hint ? '' : formatFailure(o, verb);
+    }
+    else if (stderrText && !bareExit) {
+        stderr = `${stderrText.replace(/\n$/, '')}\n`;
+    }
+    // ⚠ ONLY WHEN THERE IS NO STREAM OUTPUT. `ls` returns both a `stdout` listing and a `cwd`; a
+    // summary beside a listing is noise, and the listing is what was asked for.
+    if (!failed && !stdout) {
+        const { line, prose } = summariseResult(o);
+        const all = [line, ...prose.map((p) => `  ${p}`)].filter(Boolean);
+        if (all.length)
+            stdout = `${all.join('\n')}\n`;
+    }
+    if (stdout && !stdout.endsWith('\n'))
+        stdout += '\n';
+    return { stdout, stderr, exitCode: failed ? 1 : 0 };
+}
+/**
+ * ⚠⚠ `home` IS A ONE-WORD ADDRESS, AND THE BREADCRUMB WAS SPELLING IT `home/home`.
+ *
+ * `resolveDefaultBuilding` represents the default workspace as the tuple
+ * `{ buildingType: 'home', buildingId: 'home' }` — a deliberate special case, because `home` has
+ * no `<type>/<id>` shape. Rendering that tuple with a slash names a location that is not in the
+ * documented grammar (`home | <type>/<id> | <appName>`) and cannot be typed back into `cd`, while
+ * `beehaven call` prints the same target as plain `home` two lines earlier.
+ */
+export function breadcrumbAddress(buildingType, buildingId) {
+    if (buildingType === 'home')
+        return 'home';
+    return `${buildingType}/${buildingId}`;
+}
+/**
+ * ⚠⚠ `grep foo ~/Dir` RECURSED AND HID THE FILENAMES — the flag said `-r` and the search did not.
+ *
+ * The shell builtin decides attribution with `showFilenames = recursive || nonFlags.length > 2`,
+ * where `recursive` means "the caller typed `-r`". But a DIRECTORY target auto-recurses anyway
+ * (its own comment: *"A recursive search over a directory must include the path so callers can
+ * locate matches"*), so a directory search produced matches from many documents with nothing to
+ * say which document any came from. Reproduced with three identical lines from three different
+ * notes.
+ *
+ * ⚠ THE SERVER ALREADY KNOWS HOW TO SEND THEM — it was never asked. Injecting `-r -n` asks, and
+ * the same door answers `~/Probe/OP-1 One.md:2:…`. Nothing here reformats the match: it is
+ * printed as received.
+ *
+ * ⚠ ONLY WHEN A PATH OPERAND IS PRESENT. With no path the builtin takes a different branch that
+ * ALREADY emits `path:line:text`; injecting flags there changes nothing and would make this look
+ * like it was doing more than it is.
+ *
+ * ⚠ AND ONLY FLAGS THE CALLER DID NOT TYPE. `-i`, `-l`, `-c`, `-v` keep working because the
+ * command still goes through the same builtin — routing to the structured `notes-grep` RPC would
+ * have silently dropped all four, which is the same class of defect in a new place. (`notes-grep`
+ * also defaults to case-INSENSITIVE, so that route would have quietly changed what matches.)
+ */
+export function grepAttributionFlags(args) {
+    const typed = new Set();
+    let operands = 0;
+    for (const a of args) {
+        if (a.startsWith('--'))
+            continue;
+        if (a.startsWith('-') && a.length > 1) {
+            for (const ch of a.slice(1))
+                typed.add(ch);
+            continue;
+        }
+        operands++;
+    }
+    // `grep PATTERN` with no path — the builtin already attributes that branch.
+    if (operands < 2)
+        return [];
+    return ['r', 'n'].filter((f) => !typed.has(f)).map((f) => `-${f}`);
+}