@cspeach/cli 0.8.0 → 1.0.0

package/dist/projects/workspace.js

@@ -90,6 +90,24 @@ function maybeAddToGitignore(workspaceDir) {
         // still works, the user just has to ignore it manually.
     }
 }
+/**
+ * Resolve the workspace folder PATH without creating it. Same resolution
+ * order as ensureWorkspace (config override > project-rooted default) but
+ * strictly read-only: no mkdir, no .gitignore append. For callers that only
+ * need to LOOK at the workspace — e.g. the pre-confirm prior-plan scan in
+ * save-command.ts, which must not leave filesystem side effects before the
+ * user says yes to the save.
+ */
+export async function resolveWorkspacePath() {
+    const cfg = await loadConfig();
+    const configured = cfg.workspace_folder?.trim();
+    return resolveTarget(configured);
+}
+function resolveTarget(configured) {
+    return configured && configured.length > 0
+        ? expandHome(configured)
+        : defaultWorkspaceFor(process.cwd());
+}
 /**
  * Resolve the workspace folder path, creating it if missing.
  * Returns the absolute path. Idempotent.
@@ -97,9 +115,7 @@ function maybeAddToGitignore(workspaceDir) {
 export async function ensureWorkspace() {
     const cfg = await loadConfig();
     const configured = cfg.workspace_folder?.trim();
-    const target = configured && configured.length > 0
-        ? expandHome(configured)
-        : defaultWorkspaceFor(process.cwd());
+    const target = resolveTarget(configured);
     const justCreated = !existsSync(target);
     if (justCreated) {
         mkdirSync(target, { recursive: true });
@@ -159,7 +175,8 @@ export function listProjectFilesSync(workspace) {
         for (const name of entries) {
             const isEnvelope = name.endsWith('.cspeach.json');
             const isText = isTextFilename(name);
-            if (!isEnvelope && !isText)
+            const isDoc = isDocFilename(name);
+            if (!isEnvelope && !isText && !isDoc)
                 continue;
             const full = join(workspace, name);
             const stat = statSync(full);
@@ -167,7 +184,7 @@ export function listProjectFilesSync(workspace) {
                 continue;
             out.push({
                 filename: name,
-                kind: isEnvelope ? 'envelope' : 'text',
+                kind: isEnvelope ? 'envelope' : isDoc ? 'doc' : 'text',
                 mtimeMs: stat.mtimeMs,
             });
         }
@@ -190,10 +207,31 @@ function expandHome(p) {
 }
 /** File suffixes recognised as text-input candidates for skills. */
 const TEXT_SUFFIXES = ['.txt', '.md'];
-function isTextFilename(name) {
+/**
+ * Whether `name` is a text-input candidate (.txt / .md). Exported so the
+ * @<file> picker (at-picker.ts) reuses the exact same suffix rule instead
+ * of duplicating it.
+ */
+export function isTextFilename(name) {
     const lower = name.toLowerCase();
     return TEXT_SUFFIXES.some((s) => lower.endsWith(s));
 }
+/** File suffixes recognised as binary document inputs (read via extraction). */
+const DOC_SUFFIXES = ['.docx', '.pdf'];
+/**
+ * Whether `name` is a binary document input (.docx / .pdf). Listed and pickable
+ * like text inputs, but ingested via document extraction (the same path
+ * read_document uses) rather than read as UTF-8 text — so a picked Word/PDF
+ * spec just works as skill input.
+ */
+export function isDocFilename(name) {
+    const lower = name.toLowerCase();
+    return DOC_SUFFIXES.some((s) => lower.endsWith(s));
+}
+/** Any user-droppable skill input the @<file> picker should surface. */
+export function isAttachableFilename(name) {
+    return isTextFilename(name) || isDocFilename(name);
+}
 /**
  * List supported workspace files (.cspeach.json envelopes AND .txt/.md
  * text inputs), parsed for a tiny metadata summary. Sorted by mtime
@@ -210,7 +248,8 @@ export async function listProjectFiles() {
     for (const name of entries) {
         const isEnvelope = name.endsWith('.cspeach.json');
         const isText = isTextFilename(name);
-        if (!isEnvelope && !isText)
+        const isDoc = isDocFilename(name);
+        if (!isEnvelope && !isText && !isDoc)
             continue;
         const path = join(ws, name);
         const stat = statSync(path);
@@ -244,11 +283,11 @@ export async function listProjectFiles() {
             });
         }
         else {
-            // text — no envelope metadata, just the file presence
+            // text / doc — no envelope metadata, just the file presence
             out.push({
                 path,
                 filename: name,
-                kind: 'text',
+                kind: isDoc ? 'doc' : 'text',
                 artefactType: 'unknown',
                 version: null,
                 title: null,
@@ -336,14 +375,96 @@ export function resolveAtToken(args) {
     }
     return { kind: 'ambiguous', matches };
 }
+/**
+ * Whether `token` is a BARE name (no path semantics) — the only case the
+ * cwd fallback applies to. Absolute paths and relative paths (./, ../, or
+ * containing a separator) already resolve verbatim in resolveAtToken.
+ */
+function isBareToken(token) {
+    if (isAbsolute(token))
+        return false;
+    if (token.startsWith('./') || token.startsWith('../') || token.startsWith('.\\') || token.startsWith('..\\')) {
+        return false;
+    }
+    if (token.includes('/') || token.includes('\\'))
+        return false;
+    return true;
+}
+/**
+ * Substring-match a BARE token against the .txt/.md/.docx/.pdf files directly
+ * in `cwd` (non-recursive). Mirrors the workspace matching rule:
+ *   - exactly one match → { kind: 'path', path: join(cwd, filename) }
+ *   - multiple matches  → { kind: 'ambiguous', matches }
+ *   - none              → null (caller keeps the original notFound)
+ *
+ * Never throws — an unreadable cwd yields null. Exported for direct unit
+ * testing of the fallback in isolation from ensureWorkspace I/O.
+ */
+export function resolveBareTokenInCwd(token, cwd) {
+    let entries;
+    try {
+        entries = readdirSync(cwd);
+    }
+    catch {
+        return null;
+    }
+    const lower = token.toLowerCase();
+    const matchedFiles = [];
+    for (const name of entries) {
+        if (name.startsWith('.'))
+            continue;
+        if (!isAttachableFilename(name))
+            continue;
+        if (!name.toLowerCase().includes(lower))
+            continue;
+        const path = join(cwd, name);
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        matchedFiles.push({
+            path,
+            filename: name,
+            kind: isDocFilename(name) ? 'doc' : 'text',
+            artefactType: 'unknown',
+            version: null,
+            title: null,
+            sizeBytes: stat.size,
+            mtimeMs: stat.mtimeMs,
+        });
+    }
+    if (matchedFiles.length === 1) {
+        return { kind: 'path', path: matchedFiles[0].path };
+    }
+    if (matchedFiles.length > 1) {
+        return { kind: 'ambiguous', matches: matchedFiles };
+    }
+    return null;
+}
 /**
  * High-level resolver — combines listProjectFiles + resolveAtToken into a
  * single async call. Callers in promote-command, status, etc. use this.
+ *
+ * Bug #4: when a BARE token doesn't match anything in the workspace, fall
+ * back to matching .txt/.md files in `cwd` before reporting notFound. This
+ * lets a user drop a spec file next to their project and reference it with
+ * a plain `@spec.txt` instead of an absolute path.
  */
 export async function resolveAtTokenAsync(token, cwd) {
     const workspace = await ensureWorkspace();
     const files = await listProjectFiles();
-    return resolveAtToken({ token, cwd, workspace, files });
+    const result = resolveAtToken({ token, cwd, workspace, files });
+    if (result.kind === 'notFound' && isBareToken(token)) {
+        const cwdResult = resolveBareTokenInCwd(token, cwd);
+        if (cwdResult)
+            return cwdResult;
+    }
+    return result;
 }
 /**
  * Format `listProjectFiles` output as a human-readable block for the
@@ -362,7 +483,7 @@ export function formatProjectFileList(files, workspace) {
         const ageStr = relativeTime(now - f.mtimeMs);
         const meta = f.kind === 'envelope'
             ? `${f.artefactType.padEnd(9)} v${f.version ?? '?'}`
-            : `text       ${formatBytes(f.sizeBytes).padStart(7)}`;
+            : `${f.kind.padEnd(9)} ${formatBytes(f.sizeBytes).padStart(7)}`;
         lines.push(`  ${f.filename}  —  ${meta}  ${ageStr}`);
     }
     lines.push('');
@@ -439,8 +560,10 @@ export async function expandTextFileAttachments(userMessage, cwd, log) {
         if (resolved.kind !== 'path')
             continue;
         const path = resolved.path;
-        if (!isTextFilename(path))
-            continue;
+        const asText = isTextFilename(path);
+        const asDoc = isDocFilename(path);
+        if (!asText && !asDoc)
+            continue; // envelopes / unknown → left for --from/--status
         // Only ingest if the file exists. Missing files are just left as
         // literal @<token> in the message (the LLM gets to see them too).
         if (!existsSync(path)) {
@@ -448,19 +571,40 @@ export async function expandTextFileAttachments(userMessage, cwd, log) {
                 log(`(attached @${token} not found in workspace — left as literal)`);
             continue;
         }
+        const filename = path.split(/[\\\/]/).pop() ?? token;
         let content;
-        try {
-            content = readFileSync(path, 'utf8');
+        if (asDoc) {
+            // .docx/.pdf — extract text the same way read_document does, so a picked
+            // Word/PDF spec becomes inline skill input with no separate tool call.
+            try {
+                const buf = readFileSync(path);
+                const ext = path.toLowerCase().endsWith('.pdf') ? '.pdf' : '.docx';
+                const { extractDocument } = await import('../tools/filesystem/extract-document.js');
+                const res = await extractDocument(buf, ext, { maxPages: 150 });
+                content = res.text;
+                if (log)
+                    for (const w of res.warnings)
+                        log(`(${filename}: ${w})`);
+            }
+            catch (err) {
+                if (log)
+                    log(`(could not read @${token}: ${err.message})`);
+                continue;
+            }
         }
-        catch (err) {
-            if (log)
-                log(`(could not read @${token}: ${err.message})`);
-            continue;
+        else {
+            try {
+                content = readFileSync(path, 'utf8');
+            }
+            catch (err) {
+                if (log)
+                    log(`(could not read @${token}: ${err.message})`);
+                continue;
+            }
         }
         if (content.length > MAX_TEXT_FILE_CHARS) {
             content = content.slice(0, MAX_TEXT_FILE_CHARS) + '\n... [truncated, file exceeds 64 KB]';
         }
-        const filename = path.split(/[\\\/]/).pop() ?? token;
         const replacement = `<attached file="${filename}">\n${content}\n</attached>`;
         substitutions.push({ index, matchLen: match.length, replacement });
         if (log)

package/dist/renderer/notices.js

@@ -0,0 +1,64 @@
+/**
+ * Notice rendering — the 'warn' / 'info' side-channel (battery B2 fix).
+ *
+ * Tool handlers emit user-facing notices on the SAME EventEmitter that
+ * carries 'chunk' stream data:
+ *
+ *   ctx.chunkEmitter?.emit('warn', msg)   — user-actionable notices
+ *                                           (e.g. "ignoring transport=X,
+ *                                           object locked in Y")
+ *   ctx.chunkEmitter?.emit('info', msg)   — dim, non-fatal diagnostics
+ *                                           (e.g. "snapshot ✓", lookup
+ *                                           fallback traces)
+ *
+ * Before this module existed those events were NO-OPS in the live REPL:
+ * the Ink Body only consumed 'chunk', and the classic/one-shot paths never
+ * put a chunkEmitter on the ToolContext at all. resolveWriteTransport's
+ * carefully-worded Rule 9 notices (D15/D20) were invisible.
+ *
+ * Two consumers, one formatter:
+ *   - Ink:      ui/body.tsx subscribes 'warn'/'info' and pushes
+ *                formatNoticeLine(...) through the SAME chunk batcher, so
+ *                ordering relative to surrounding chunks is preserved.
+ *   - classic / one-shot: createClassicOutputEmitter() returns an emitter
+ *                whose listeners write straight to stdout. repl.tsx
+ *                (classic branch) and one-shot.ts put it on ctx.chunkEmitter.
+ *
+ * Deliberately NOT wired for subagents (tools/subagent/agent_run.ts):
+ * their ctx.chunkEmitter stays undefined so child-turn notices remain
+ * muted — exactly the pre-existing contract pinned in agent_run.test.ts.
+ */
+import chalk from 'chalk';
+import { EventEmitter } from 'node:events';
+/**
+ * Format one notice as a single terminal line (trailing newline included).
+ * Multi-line messages are collapsed to one line — notices are glanceable
+ * margin notes, not documents; anything long belongs in the tool result.
+ *
+ *   warn → yellow  "  ⚠ message"
+ *   info → dim     "  · message"
+ */
+export function formatNoticeLine(level, message) {
+    const oneLine = message.replace(/\s*\r?\n\s*/g, ' ').trim();
+    if (level === 'warn')
+        return chalk.yellow(`  ⚠ ${oneLine}`) + '\n';
+    return chalk.dim(`  · ${oneLine}`) + '\n';
+}
+/**
+ * Build the output emitter for the NON-Ink paths (classic REPL, one-shot).
+ *
+ * Listeners:
+ *   'chunk' → written verbatim (already-formatted stream text — e.g. the
+ *             verify-chain line emitted by write tools)
+ *   'warn'  → formatNoticeLine('warn', …)
+ *   'info'  → formatNoticeLine('info', …)
+ *
+ * The `write` sink defaults to process.stdout — injectable for tests.
+ */
+export function createClassicOutputEmitter(write = (s) => process.stdout.write(s)) {
+    const emitter = new EventEmitter();
+    emitter.on('chunk', (s) => write(s));
+    emitter.on('warn', (msg) => write(formatNoticeLine('warn', msg)));
+    emitter.on('info', (msg) => write(formatNoticeLine('info', msg)));
+    return emitter;
+}

package/dist/renderer/progress-chatter.js

@@ -92,6 +92,10 @@ const MESSAGES = {
         'Reserving a transport request…',
         'Asking SAP for a fresh TR…',
     ],
+    sap_transport_for_object: [
+        'Checking who owns {object_name}…',
+        'Looking for an owning transport…',
+    ],
     sap_transport_list: [
         'Listing open transports…',
         'Finding modifiable TRs…',
@@ -156,6 +160,10 @@ const MESSAGES = {
         'Publishing service binding…',
         'Asking SAP to expose the OData endpoint…',
     ],
+    sap_service_binding_unpublish: [
+        'Unpublishing service binding…',
+        'Asking SAP to remove the OData endpoint…',
+    ],
 };
 const FALLBACK_MESSAGES = [
     'Working on it…',

package/dist/renderer/syntax.js

@@ -22,10 +22,25 @@
  * that object — the shape of the API is the same.
  */
 import { highlight } from 'cli-highlight';
-import hljs from 'highlight.js';
+import { createRequire } from 'node:module';
 import abapGrammar from './highlighters/abap.js';
 import cdsGrammar from './highlighters/cds.js';
 import bdefGrammar from './highlighters/bdef.js';
+// A5 fix (2026-06-06) — registration must hit the EXACT module instance
+// cli-highlight loads, and on this pnpm/Windows layout that is NOT what a
+// plain `import hljs from 'highlight.js'` (or even a local require)
+// resolves to. Diagnosed live: our resolution lands on the top-level
+// `node_modules/highlight.js` while cli-highlight requires its nested
+// `.pnpm/highlight.js@10.7.3/...` copy — node treats them as two separate
+// modules with separate language registries, so the grammars registered
+// on ours were invisible to cli-highlight and EVERY abap/cds/bdef block
+// silently fell back to unhighlighted echo ("Could not find the language
+// 'abap'") — in production as well as tests, since the first release.
+// Fix: chain createRequire through cli-highlight's own entry point so we
+// follow its resolution and register on the instance it actually uses.
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const hljs = createRequire(require.resolve('cli-highlight'))('highlight.js');
 // Module-load-time registration. The grammar modules export plain objects
 // (shape matches highlight.js `Language` definition). Cast is safe — the
 // grammars match the runtime contract even when strict typings drift.

package/dist/renderer/thinking-heartbeat.js

@@ -29,7 +29,7 @@
  * fallback.
  */
 import chalk from 'chalk';
-const THRESHOLDS_MS = [
+const LLM_THRESHOLDS = [
     { at: 3_000, label: 'thinking…' },
     { at: 10_000, label: 'thinking… (10s)' },
     { at: 30_000, label: 'thinking… (30s)' },
@@ -39,10 +39,22 @@ const THRESHOLDS_MS = [
     { at: 180_000, label: 'thinking… (3m — Ctrl+C is recommended; the stream may have stalled)' },
     { at: 300_000, label: 'thinking… (5m — Ctrl+C and try again)' },
 ];
+/** Suffixes for labelled (tool / hook) waits — appended to opts.label. */
+const GENERIC_SUFFIXES = [
+    { at: 3_000, suffix: '' },
+    { at: 10_000, suffix: ' (10s)' },
+    { at: 30_000, suffix: ' (30s)' },
+    { at: 60_000, suffix: ' (60s — still running, hold on)' },
+    { at: 120_000, suffix: ' (2m — still running; Ctrl+C aborts the turn)' },
+    { at: 300_000, suffix: ' (5m — likely stuck; Ctrl+C and check the VPN)' },
+];
 export function startThinkingHeartbeat(opts) {
     const startedAt = Date.now();
     let nextIdx = 0;
     let stopped = false;
+    const THRESHOLDS_MS = opts?.label
+        ? GENERIC_SUFFIXES.map((t) => ({ at: t.at, label: `${opts.label}${t.suffix}` }))
+        : LLM_THRESHOLDS;
     const emitLine = (line) => {
         if (opts?.chunkEmitter) {
             // Phase A #4 — route through Ink's chunk pipeline. The Body

package/dist/renderer/tool-widget.js

@@ -61,7 +61,7 @@ export function renderToolCallTop(params) {
         else
             process.stdout.write(s);
     };
-    const summary = argSummary(name, args);
+    const summary = summariseToolArgs(name, args);
     const wrapped = summary ? chalk.gray('(') + chalk.gray(summary) + chalk.gray(')') : '';
     const line = `${peach('⏺')} ${chalk.bold(name)}${wrapped}`;
     write('\n' + line + '\n');
@@ -136,7 +136,7 @@ function startSpinnerWithVerbs(params, verbs, defaultVerb) {
     return { stop: stopFn };
 }
 export function renderToolCallBottom(params) {
-    const { durationMs, isError, resultSummary, chunkEmitter } = params;
+    const { durationMs, isError, resultSummary, chunkEmitter, name, args } = params;
     const write = (s) => {
         if (chunkEmitter)
             chunkEmitter.emit('chunk', s);
@@ -144,15 +144,26 @@ export function renderToolCallBottom(params) {
             process.stdout.write(s);
     };
     const icon = isError ? chalk.red('✗') : chalk.green('✓');
+    // Label: plain (not bold — the top line keeps visual primacy) name +
+    // dim arg summary, mirroring the top-line shape so orphaned rows still
+    // read as "which tool, on what object".
+    let label = '';
+    if (name) {
+        const summary = summariseToolArgs(name, args ?? {});
+        const wrapped = summary ? chalk.gray('(') + chalk.gray(summary) + chalk.gray(')') : '';
+        label = ` ${name}${wrapped}`;
+    }
     const detailRaw = resultSummary ? truncate(resultSummary, RESULT_SUMMARY_MAX) : '';
     const detail = detailRaw
         ? (isError ? chalk.red(detailRaw) : chalk.gray(detailRaw))
         : '';
     const timing = chalk.dim(formatDuration(durationMs));
     const sep = chalk.dim('·');
-    let line = `  ${peach('⎿')} ${icon}`;
+    let line = `  ${peach('⎿')} ${icon}${label}`;
     if (detail)
         line += ` ${detail} ${sep} ${timing}`;
+    else if (label)
+        line += ` ${sep} ${timing}`;
     else
         line += ` ${timing}`;
     write(line + '\n');
@@ -162,8 +173,11 @@ export function renderToolCallBottom(params) {
  * arguments. Per-tool aware: pulls LLM-supplied summary first, then the
  * common (name, type, package) triple, then specific keys for known tools.
  * Falls back to a truncated JSON dump.
+ *
+ * Exported (D29) so the bottom result row can self-identify with the same
+ * summary the top line used.
  */
-function argSummary(toolName, args) {
+export function summariseToolArgs(toolName, args) {
     if (!args || Object.keys(args).length === 0)
         return '';
     const a = args;

package/dist/renderer/tty.js

@@ -25,6 +25,36 @@ export function setRenderingOverride(mode) {
 export function getRenderingOverride() {
     return renderingOverride;
 }
+/**
+ * B5 (2026-06-11) — headless answer policy signal.
+ *
+ * "Headless" means NO human can answer a prompt: stdin will never deliver
+ * an answer, so any inquirer/readline wait blocks forever (battery S2 Pass A
+ * stalled on exactly this — defect D1). Consumers (ask_question, the save
+ * hook, request_approval) branch to auto-answer / fail-fast policies instead
+ * of prompting.
+ *
+ * Decision order:
+ *   1. Explicit override — runOneShot() sets `true` at startup because
+ *      one-shot is a single non-interactive turn by design (CI parity:
+ *      the same invocation must behave identically piped or from a
+ *      terminal). Tests set/clear it directly.
+ *   2. Fallback — stdin is not a TTY. Covers piped/redirected invocations
+ *      that never went through runOneShot. stdin (not stdout) is the right
+ *      floor: prompts BLOCK on stdin; piping only stdout still leaves a
+ *      human able to answer.
+ */
+let headlessOverride = null;
+/** Set (or clear with null) the explicit headless override. */
+export function setHeadlessOverride(v) {
+    headlessOverride = v;
+}
+/** True when no human can answer prompts — see setHeadlessOverride. */
+export function isHeadless() {
+    if (headlessOverride !== null)
+        return headlessOverride;
+    return process.stdin.isTTY !== true;
+}
 /**
  * True when the Ink UI frame should be mounted.
  *
@@ -32,8 +62,17 @@ export function getRenderingOverride() {
  *   1. If override === 'classic', never use Ink (explicit opt-out)
  *   2. If override === 'ink', use Ink when a TTY is available; otherwise
  *      fall back — Ink cannot render on a pipe regardless of user preference
- *   3. If override === 'auto' (default), use Ink when interactive TTY +
- *      not one-shot + CI=unset
+ *   3. If override === 'auto' (default), use Ink when interactive TTY on
+ *      BOTH stdout and stdin + not one-shot + CI=unset
+ *
+ * UX-5 review C1 (2026-06-12): the auto branch must also require
+ * `process.stdin.isTTY` — Ink mounts raw-mode key handling on stdin, and a
+ * piped stdin (`"/cost`n/exit" | cspeach`) cannot enter raw mode. Worse,
+ * mounting Ink there bypassed the classic loop's early-line buffer
+ * (UX-5 #5), so every piped line was dropped. Piped-stdin invocations now
+ * take the classic path even when stdout is a terminal. The explicit
+ * `ui.rendering = 'ink'` override (branch 2) deliberately keeps its
+ * stdout-only floor — that's the user's explicit choice.
  *
  * v0.3+: pipeline.ts and approvals/render.ts branch on this.
  */
@@ -42,8 +81,8 @@ export function shouldUseInk() {
         return false;
     if (renderingOverride === 'ink')
         return isTTY();
-    // auto
-    return isTTY() && !isOneShot() && !process.env['CI'];
+    // auto — stdin must be a TTY too (raw-mode capable, no piped lines to drop)
+    return isTTY() && process.stdin.isTTY === true && !isOneShot() && !process.env['CI'];
 }
 /**
  * Stub for v0.3 Windows ConPTY / CI TTY hinting.

package/dist/renderer/verify-chain.js

@@ -0,0 +1,77 @@
+/**
+ * Verify-chain line — one compact row per completed SAP write summarizing
+ * the Forge-Rule pipeline the tool actually ran (tour slide-7 alignment):
+ *
+ *   ① snapshot ✓ ② written ✓ ③ syntax ✓ ④ activate pending
+ *
+ * HONESTY CONTRACT: every segment is derived from the tool's real result —
+ * never synthesized. States render truthfully:
+ *   - snapshot 'new_object'  → "① snapshot – (new object)" (genuine ADT 404 —
+ *     nothing to save; NEVER used for other read failures)
+ *   - snapshot 'source_read_failed' → "① snapshot – (no source read: <msg>)" —
+ *     the pre-write read failed for a non-404 reason; the object may exist
+ *     but there is no recovery copy. Hard-gate tools block instead of
+ *     emitting this; it only appears on soft (best-effort) gates.
+ *   - snapshot 'best_effort_failed' → "① snapshot – (skipped)" (write tools
+ *     where the gate is soft, e.g. class includes)
+ *   - syntax fail → "③ syntax ✗ (L12: MESSAGE …)" AND no ④ at all —
+ *     activation is blocked, so we don't show a fake pending step
+ *   - syntax 'not_checked' → "③ syntax – (checked at activation)" —
+ *     sap_set_class_include has no standalone syntax gate
+ *   - ④ is always 'pending', never '✓': activation is a SEPARATE tool call
+ *     (sap_activate); these write tools never activate.
+ *
+ * Consumed by the write tools in tools/sap-write.ts, emitted on the
+ * 'chunk' channel so it lands between the ⏺ dispatch line and the ⎿
+ * result row in both renderers.
+ */
+import chalk from 'chalk';
+const pass = (s) => `${s} ${chalk.green('✓')}`;
+const fail = (s, detail) => `${s} ${chalk.red('✗')}${detail ? ' ' + chalk.red(`(${detail})`) : ''}`;
+const skip = (s, why) => chalk.dim(`${s} – (${why})`);
+const ERROR_DETAIL_MAX = 60;
+const SNAPSHOT_DETAIL_MAX = 40;
+const truncate = (s, max) => {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? flat.substring(0, max - 1) + '…' : flat;
+};
+/**
+ * Build the chain line (no trailing newline). Returns the full line
+ * including the two-space indent that aligns with the ⎿ result row.
+ */
+export function buildWriteChainLine(input) {
+    const parts = [];
+    // ① snapshot
+    if (input.snapshot === 'taken')
+        parts.push(pass('① snapshot'));
+    else if (input.snapshot === 'new_object')
+        parts.push(skip('① snapshot', 'new object'));
+    else if (input.snapshot === 'source_read_failed') {
+        // Honest: the read failed — we do NOT know the object is new, and there
+        // is no recovery copy. Never render this as "(new object)".
+        const why = input.snapshotDetail
+            ? `no source read: ${truncate(input.snapshotDetail, SNAPSHOT_DETAIL_MAX)}`
+            : 'no source read';
+        parts.push(skip('① snapshot', why));
+    }
+    else
+        parts.push(skip('① snapshot', 'skipped'));
+    // ② written
+    parts.push(input.written ? pass('② written') : fail('② written'));
+    // ③ syntax (+ ④ activate, which only exists when activation is possible)
+    if (input.syntax === 'not_checked') {
+        parts.push(skip('③ syntax', 'checked at activation'));
+        parts.push(chalk.dim('④ activate pending'));
+    }
+    else if (input.syntax.ok) {
+        parts.push(pass('③ syntax'));
+        parts.push(chalk.dim('④ activate pending'));
+    }
+    else {
+        const first = (input.syntax.errors[0] ?? 'syntax errors').replace(/\s+/g, ' ').trim();
+        const detail = first.length > ERROR_DETAIL_MAX ? first.substring(0, ERROR_DETAIL_MAX - 1) + '…' : first;
+        parts.push(fail('③ syntax', detail));
+        // No ④ — activation is blocked; rendering a pending step would lie.
+    }
+    return '  ' + parts.join('  ');
+}