@cspeach/cli 0.6.0

package/dist/agent/skill-checkpoint.js

@@ -0,0 +1,119 @@
+/**
+ * Layer 2 — skill-level checkpoints.
+ *
+ * Background. Layer 1 (commit be1c6d8) makes sure that when a turn aborts
+ * mid-stream, every prior assistant message + tool result + accumulated
+ * partial text lands on disk in `session.messages`. The model can resume
+ * with full conversation context.
+ *
+ * What Layer 1 does NOT cover: skill-internal state files. /abap-cca, for
+ * example, maintains `.abapforge/cca/projects/<id>/project.json` with an
+ * inventory of objects, classifications, and per-package state. The skill
+ * writes this file at PHASE BOUNDARIES (end of DISCOVER, end of INVENTORY,
+ * etc.). A crash mid-DISCOVER means the partial inventory in project.json
+ * is stale — the skill has to redo every probe on resume.
+ *
+ * Layer 2 fixes that. After every tool call returns, the agent loop calls
+ * `applyToolResultCheckpoint(...)` which dispatches to a registered handler
+ * for the active skill. The handler reads the prior on-disk state, applies
+ * one tool result, and writes back atomically. Resume picks up at the next
+ * probe with the partial inventory intact, no SAP work redone.
+ *
+ * v0.6 ships the infrastructure with a default JSONL handler that captures
+ * a per-session audit log of every tool call. Skill-specific handlers
+ * (e.g. for /abap-cca's project.json) can be added in follow-up commits
+ * without touching the loop.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+const HANDLERS = new Map();
+/**
+ * Register a skill-specific handler. Idempotent — re-registering replaces
+ * the prior handler. Skills should register at module-load time.
+ */
+export function registerCheckpointHandler(handler) {
+    HANDLERS.set(handler.skill, handler);
+}
+/** Test helper — clears the registry. Not exported in production paths. */
+export function _resetHandlersForTesting() {
+    HANDLERS.clear();
+}
+export function checkpointsRoot() {
+    return path.join(os.homedir(), '.cspeach', 'checkpoints');
+}
+/**
+ * Default handler — appends one JSONL row per tool call to
+ * ~/.cspeach/checkpoints/<sessionId>/tool-calls.jsonl.
+ *
+ * This runs for EVERY skill regardless of registered handlers. Provides a
+ * uniform audit trail without skills having to register anything. Safe for
+ * concurrent appends (atomic O_APPEND on POSIX, single-threaded on Node so
+ * mid-write interleaving doesn't happen).
+ */
+async function appendDefaultJsonl(input) {
+    try {
+        const dir = path.join(checkpointsRoot(), input.sessionId);
+        await fs.mkdir(dir, { recursive: true });
+        const filePath = path.join(dir, 'tool-calls.jsonl');
+        const row = {
+            at: input.completedAt,
+            tool: input.toolName,
+            args: truncateArgs(input.args),
+            ok: !input.isError,
+            duration_ms: input.durationMs,
+            // Cap result payload at 4KB to bound JSONL growth on long turns.
+            result: truncateResult(input.result),
+        };
+        await fs.appendFile(filePath, JSON.stringify(row) + '\n', 'utf-8');
+    }
+    catch {
+        // best-effort — never throw out
+    }
+}
+function truncateArgs(args) {
+    try {
+        const json = JSON.stringify(args);
+        if (json.length <= 1024)
+            return args;
+        return JSON.parse(json.slice(0, 1024) + '..."}');
+    }
+    catch {
+        return '<unstringifiable>';
+    }
+}
+function truncateResult(result) {
+    if (typeof result === 'string') {
+        return result.length <= 4096 ? result : result.slice(0, 4096) + '...';
+    }
+    try {
+        const json = JSON.stringify(result);
+        if (json.length <= 4096)
+            return result;
+        return json.slice(0, 4096) + '...';
+    }
+    catch {
+        return '<unstringifiable>';
+    }
+}
+/**
+ * Main entry point — call from the agent loop after every tool dispatch.
+ * Always runs the default JSONL handler. Also dispatches to a skill-specific
+ * handler if one is registered. Both are best-effort; failures are swallowed.
+ */
+export async function applyToolResultCheckpoint(input) {
+    // Default audit JSONL — runs for every skill.
+    await appendDefaultJsonl(input);
+    // Skill-specific handler (optional).
+    if (input.skill) {
+        const handler = HANDLERS.get(input.skill);
+        if (handler) {
+            try {
+                await handler.apply(input);
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+}

package/dist/agent/tool-dispatch.js

@@ -0,0 +1,47 @@
+import { getTool } from '../tools/index.js';
+import { presentSafetyConfirmation } from '../repl/safety-confirm.js';
+import { shouldGateRule8, recordWriteOp, renderPlanSummary, getWriteOpsThisTurn, } from '../repl/rule8-detector.js';
+export async function dispatchTool(name, args, ctx) {
+    const tool = getTool(name);
+    if (!tool) {
+        return { content: JSON.stringify({ error: `unknown_tool: ${name}` }), is_error: true };
+    }
+    // Rule 8 — no batch without plan. 2nd+ mutating call this turn requires
+    // explicit confirmation. Fires regardless of /safety-mode toggle (batch
+    // detection is unconditional per Plan 3 §6.6).
+    if (tool.isMutating && shouldGateRule8()) {
+        const r = await presentSafetyConfirmation({
+            rule: 'RULE_8_BATCH_PLAN',
+            op: tool.name,
+            object: {
+                type: typeof args?.type === 'string' ? args.type : 'BATCH',
+                name: typeof args?.name === 'string' ? args.name : '(multiple)',
+            },
+            what_will_happen: renderPlanSummary({ tool: tool.name, args }),
+            rollback_available: true, // snapshots taken per-write
+            transport: typeof args?.transport === 'string' ? args.transport : '',
+            batch_count: getWriteOpsThisTurn().length + 1,
+        });
+        if (!r.confirmed) {
+            return {
+                content: JSON.stringify({ error: 'cancelled_by_user', reason: r.reason }),
+                is_error: true,
+            };
+        }
+    }
+    try {
+        const result = await tool.handler(args, ctx);
+        // (regression-hunt trace removed 2026-05-01 after root cause found —
+        // see memory/project_phase3_lite_regression.md.)
+        // Always record AFTER successful mutating dispatch — applies to 1st and
+        // 2nd+ writes alike. The 1st write seeds the counter; without this the
+        // gate would never fire on the 2nd write.
+        if (tool.isMutating && !(result.is_error ?? false)) {
+            recordWriteOp(tool.name, args);
+        }
+        return { content: result.content, is_error: result.is_error ?? false };
+    }
+    catch (err) {
+        return { content: JSON.stringify({ error: String(err) }), is_error: true };
+    }
+}

package/dist/agent/turn-assistant-text.js

@@ -0,0 +1,49 @@
+/**
+ * Collect ALL assistant text emitted during a single turn.
+ *
+ * Why this exists: the end-of-turn save hook (loop.ts, maybeOfferSave call
+ * site) needs to scan the turn's assistant output for a skill manifest
+ * block (e.g. `<!-- csforge:cca-manifest ... -->` for /abap-cca). Before
+ * 2026-05-12 the call site only looked at the FINAL assistant message of
+ * the turn — but skills like /abap-cca emit the manifest in the report
+ * message, then call `ask_question` for a closing "what's next?" picker,
+ * then emit a short wrap-up message. The wrap-up message ended the turn
+ * but did not contain the manifest, so `extractCcaAssessment` threw
+ * "No manifest" and the save hook silently bailed (save-command.ts:114).
+ *
+ * Fix: walk session.messages from the per-turn start marker and join the
+ * text from every assistant message in between. The save hook now sees
+ * the full turn-worth of assistant output regardless of which inner
+ * message contained the manifest.
+ */
+/**
+ * Concatenate text from every assistant message in `messages` starting at
+ * `turnStartCount`. Non-text content blocks (tool_use, tool_result) are
+ * skipped. Non-string `.text` values are coerced to empty strings rather
+ * than thrown — defensive against malformed content arrays.
+ *
+ * Returns '' (not null) when nothing matches so the callsite stays simple.
+ *
+ * Messages are joined with `\n\n` so the model's pre-tool message and
+ * post-tool message stay separable in the joined output. The save hook's
+ * extractor uses a regex that doesn't care about inter-message whitespace.
+ */
+export function collectTurnAssistantText(messages, turnStartCount) {
+    if (turnStartCount < 0 || turnStartCount >= messages.length)
+        return '';
+    const parts = [];
+    for (let i = turnStartCount; i < messages.length; i++) {
+        const m = messages[i];
+        if (m.role !== 'assistant')
+            continue;
+        if (!Array.isArray(m.content))
+            continue;
+        for (const block of m.content) {
+            if (block?.type !== 'text')
+                continue;
+            if (typeof block.text === 'string')
+                parts.push(block.text);
+        }
+    }
+    return parts.join('\n\n');
+}

package/dist/agent/turn-error-ux.js

@@ -0,0 +1,126 @@
+/**
+ * Graceful turn-error UX.
+ *
+ * Replaces the v0.5 catch path that printed only `[error] <msg>` and lost
+ * everything. The new behaviour:
+ *
+ *   - Writes the full error (message + stack) to ~/.cspeach/logs/<sessionId>-<ts>.log
+ *   - Prints a clean 4-6 line block to stderr with: cause, session id,
+ *     stream path, log path, resume hint.
+ *   - Never throws — best-effort. The CLI returns to the prompt cleanly so
+ *     the user can either resume or type a new prompt.
+ *
+ * The previous loop persistence step (loop.ts try/catch) has already
+ * pushed any partial assistant content onto session.messages and saved
+ * the session before the throw bubbled here. Resume picks up that state.
+ */
+import chalk from 'chalk';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { TurnStreamWriter } from './turn-stream.js';
+export function logsRoot() {
+    return path.join(os.homedir(), '.cspeach', 'logs');
+}
+/**
+ * Pretty-print `err.message` for human display. Translates known
+ * provider-stream signatures into actionable phrases. Anything unknown
+ * falls through verbatim.
+ */
+export function describeError(err) {
+    if (err == null)
+        return 'unknown error';
+    const msg = err instanceof Error ? err.message : String(err);
+    if (!msg)
+        return 'unknown error';
+    // Undici / Node fetch closes a stream with bare "terminated".
+    if (msg === 'terminated' || msg.includes('terminated')) {
+        return 'provider stream closed mid-response';
+    }
+    if (msg.includes('ECONNRESET'))
+        return 'network connection reset';
+    if (msg.includes('ETIMEDOUT'))
+        return 'network timeout';
+    if (msg.toLowerCase().includes('aborterror'))
+        return 'request aborted';
+    return msg.slice(0, 200);
+}
+/**
+ * Write a full diagnostic log to ~/.cspeach/logs/<sessionId>-<ts>.log.
+ * Best-effort — failure here is silent, the user-facing block still renders.
+ * Returns the absolute path on success, null on failure.
+ */
+async function writeErrorLog(sessionId, err) {
+    try {
+        const dir = logsRoot();
+        await fs.mkdir(dir, { recursive: true });
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const filePath = path.join(dir, `${sessionId}-${stamp}.log`);
+        const lines = [
+            `# CSPeach turn error log`,
+            `session: ${sessionId}`,
+            `at: ${new Date().toISOString()}`,
+            ``,
+            `## error`,
+            `${err instanceof Error ? err.name + ': ' + err.message : String(err)}`,
+            ``,
+            `## stack`,
+            `${err instanceof Error && err.stack ? err.stack : '(no stack)'}`,
+            ``,
+        ];
+        if (err && typeof err === 'object') {
+            const e = err;
+            const status = e.status ?? e.response?.status;
+            if (status)
+                lines.push(`status: ${status}`);
+            const code = e.code;
+            if (code)
+                lines.push(`code: ${code}`);
+            const cause = e.cause;
+            if (cause) {
+                lines.push(``, `## cause`, String(cause));
+                if (cause instanceof Error && cause.stack) {
+                    lines.push(``, `## cause stack`, cause.stack);
+                }
+            }
+        }
+        await fs.writeFile(filePath, lines.join('\n') + '\n', 'utf-8');
+        return filePath;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Render the user-facing turn-error block. Writes a log file (best-effort)
+ * and prints a 4-6 line diagnostic that names the cause + the recovery path.
+ */
+export async function renderTurnError(input) {
+    const print = input.print ?? ((line) => process.stderr.write(line + '\n'));
+    print('');
+    if (input.userInterrupted) {
+        // User pressed Ctrl+C / Esc — frame as a deliberate cancellation,
+        // not a crash. Skip the log file (no diagnostic value).
+        print(chalk.yellow(`✋  Turn cancelled.`));
+        print(chalk.gray(`   Session: ${input.session.id}`));
+        print(chalk.gray(`   Resume:  cspeach --resume ${input.session.id}`));
+        print(chalk.gray(`            cspeach --resume  (no arg → pick from a list)`));
+        print('');
+        return;
+    }
+    const reason = describeError(input.err);
+    const logPath = await writeErrorLog(input.session.id, input.err);
+    print(chalk.red(`⚠  Turn interrupted: ${reason}`));
+    print(chalk.gray(`   Session: ${input.session.id}`));
+    if (input.streamFilePath) {
+        print(chalk.gray(`   Stream:  ${input.streamFilePath}`));
+    }
+    if (logPath) {
+        print(chalk.gray(`   Log:     ${logPath}`));
+    }
+    print(chalk.gray(`   Resume:  cspeach --resume ${input.session.id}`));
+    print(chalk.gray(`            cspeach --resume  (no arg → pick from a list)`));
+    print('');
+}
+/** Re-export for callers that want to compute a stream path independently. */
+export { TurnStreamWriter };

package/dist/agent/turn-stream.js

@@ -0,0 +1,79 @@
+/**
+ * Per-turn stream-to-disk mirror.
+ *
+ * The renderer (Ink + ANSI pipeline + widget extraction) is the SOLE display
+ * channel for assistant text in v0.5. If the terminal pipeline dies — Ink
+ * frame corruption, an exception inside the widget renderer, the host
+ * terminal closing — the user sees nothing and the in-memory text was, until
+ * v0.6, the only copy. (See loop.ts try/catch for the persistence side of
+ * the same problem.)
+ *
+ * This writer mirrors EVERY text delta arriving from the provider stream to
+ * a per-turn markdown file under ~/.cspeach/streams/<sessionId>/<ts>.md.
+ * Best-effort: file-IO failures NEVER throw out — a stream-to-disk hiccup
+ * must not crash a turn that is otherwise working.
+ *
+ * Use case: when a turn aborts mid-stream, the user runs `cat
+ * ~/.cspeach/streams/<sessionId>/<ts>.md` and recovers the partial output.
+ * The graceful error UX (T19) prints this path on every failed turn.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+export function streamsRoot() {
+    // Mirror the existing ~/.cspeach/sessions/ convention. The sessions/
+    // directory holds the structured JSON; streams/ holds the human-readable
+    // text mirror.
+    return path.join(os.homedir(), '.cspeach', 'streams');
+}
+export class TurnStreamWriter {
+    filePath;
+    headerWritten = false;
+    constructor(sessionId, startedAt = new Date()) {
+        // ISO timestamp with filename-safe punctuation.
+        const stamp = startedAt.toISOString().replace(/[:.]/g, '-');
+        this.filePath = path.join(streamsRoot(), sessionId, `${stamp}.md`);
+    }
+    /** The on-disk file path (absolute). Useful for the resume/error UX. */
+    path() {
+        return this.filePath;
+    }
+    /**
+     * Append assistant text to the stream file. Best-effort — silently swallows
+     * file-IO errors so a write hiccup never kills a working turn. Lazily writes
+     * a small header on the first append so an unused turn produces no file.
+     */
+    async append(text) {
+        if (!text || text.length === 0)
+            return;
+        try {
+            if (!this.headerWritten) {
+                await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+                const header = `# CSPeach turn stream\n_started ${new Date().toISOString()}_\n\n`;
+                await fs.writeFile(this.filePath, header, 'utf-8');
+                this.headerWritten = true;
+            }
+            await fs.appendFile(this.filePath, text, 'utf-8');
+        }
+        catch {
+            // best-effort: never throw out
+        }
+    }
+    /**
+     * Close the stream with an optional footer (token totals, duration, end
+     * status). Idempotent — safe to call multiple times.
+     */
+    async close(footer) {
+        if (!this.headerWritten)
+            return;
+        try {
+            const block = footer
+                ? `\n\n---\n${footer}\n`
+                : `\n\n---\n_closed ${new Date().toISOString()}_\n`;
+            await fs.appendFile(this.filePath, block, 'utf-8');
+        }
+        catch {
+            // best-effort
+        }
+    }
+}

package/dist/agent/turn-watchdog.js

@@ -0,0 +1,71 @@
+/**
+ * Layer 3 — long-turn watchdog.
+ *
+ * Background. The lost-77-minute /abap-cca on ZDPR_PAYMENTS run did 30+ tool
+ * calls and 200K output tokens in a single turn. Even with Layer 1 + 2, a
+ * turn that long is a smell: it's hard to follow, it consumes token budget
+ * unevenly, and it sits inside one Anthropic streaming session that's more
+ * likely to be cut by a network blip the longer it runs.
+ *
+ * The watchdog injects a synthetic advisory user message between tool rounds
+ * when the running turn approaches a budget. The model sees:
+ *
+ *   "[CSPeach watchdog] You've been running this turn for 18m / 92K output
+ *   tokens. Consider checkpointing what you have, summarizing progress so
+ *   far, and prompting the user to continue. Don't keep going as if nothing
+ *   changed."
+ *
+ * Soft signal — the model decides whether to wrap up or push through. The
+ * advisory is emitted exactly ONCE per turn so we don't spam.
+ *
+ * Defaults:
+ *   wall-clock:   20 minutes per turn  (overridable via CSPEACH_TURN_WALL_BUDGET_MS)
+ *   output tokens: 100,000 per turn    (overridable via CSPEACH_TURN_TOKEN_BUDGET)
+ *
+ * Set CSPEACH_TURN_WATCHDOG=off to disable entirely.
+ */
+export const DEFAULT_WALL_BUDGET_MS = 20 * 60 * 1000;
+export const DEFAULT_TOKEN_BUDGET = 100_000;
+export function loadWatchdogConfig(env = process.env) {
+    const enabled = (env.CSPEACH_TURN_WATCHDOG ?? 'on').toLowerCase() !== 'off';
+    const wallBudgetMs = parsePositiveInt(env.CSPEACH_TURN_WALL_BUDGET_MS, DEFAULT_WALL_BUDGET_MS);
+    const tokenBudget = parsePositiveInt(env.CSPEACH_TURN_TOKEN_BUDGET, DEFAULT_TOKEN_BUDGET);
+    return { wallBudgetMs, tokenBudget, enabled };
+}
+function parsePositiveInt(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+export function evaluateWatchdog(input, now = Date.now()) {
+    if (!input.config.enabled || input.alreadyWarned) {
+        return { shouldWarn: false, reason: '', message: '' };
+    }
+    const elapsedMs = Math.max(0, now - input.startedAt);
+    const wallExceeded = elapsedMs >= input.config.wallBudgetMs;
+    const tokensExceeded = input.outputTokensThisTurn >= input.config.tokenBudget;
+    if (!wallExceeded && !tokensExceeded) {
+        return { shouldWarn: false, reason: '', message: '' };
+    }
+    const wallMin = Math.floor(elapsedMs / 60_000);
+    const wallLimit = Math.floor(input.config.wallBudgetMs / 60_000);
+    const reasons = [];
+    if (wallExceeded)
+        reasons.push(`${wallMin}m elapsed (limit ${wallLimit}m)`);
+    if (tokensExceeded) {
+        reasons.push(`${kFormat(input.outputTokensThisTurn)} output tokens (limit ${kFormat(input.config.tokenBudget)})`);
+    }
+    const reason = reasons.join(', ');
+    const message = `[CSPeach watchdog] This turn has crossed a budget: ${reason}. ` +
+        `Consider checkpointing what you have, summarising progress so far, ` +
+        `and prompting the user to continue with a fresh turn. Don't keep ` +
+        `going as if nothing changed — long single-turn runs are more likely ` +
+        `to be cut by a network blip the longer they get.`;
+    return { shouldWarn: true, reason, message };
+}
+function kFormat(n) {
+    if (n < 1000)
+        return String(n);
+    return `${(n / 1000).toFixed(1).replace(/\.0$/, '')}K`;
+}

package/dist/approvals/advisory-prompt.js

@@ -0,0 +1,40 @@
+import clipboardy from 'clipboardy';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+export async function promptAdvisory(args) {
+    output.write(args.displayText + '\n');
+    const rl = readline.createInterface({ input, output });
+    try {
+        while (true) {
+            const answer = (await rl.question('[y]applied  [s]kip  [n]abort  [c]opy-to-clipboard: '))
+                .trim()
+                .toLowerCase();
+            switch (answer) {
+                case 'y':
+                case 'yes':
+                case 'applied':
+                    return 'applied';
+                case 's':
+                case 'skip':
+                case 'skipped':
+                    return 'skipped';
+                case 'n':
+                case 'no':
+                case 'abort':
+                case 'aborted':
+                    return 'aborted';
+                case 'c':
+                case 'copy':
+                    await clipboardy.write(args.clipboardText);
+                    output.write('✓ Copied to clipboard.\n');
+                    continue;
+                default:
+                    output.write('Unrecognised input. Try y, s, n, or c.\n');
+                    continue;
+            }
+        }
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/approvals/advisory-render.js

@@ -0,0 +1,38 @@
+import chalk from 'chalk';
+export function renderAdvisoryProposal(args) {
+    const displayParts = [];
+    const clipboardParts = [];
+    displayParts.push(chalk.yellow.bold('╔══ ADVISORY MODE — proposed change (no SAP write will occur) ══╗'));
+    displayParts.push(chalk.bold(`Summary: ${args.summary}`));
+    displayParts.push(`Risk: ${args.risk}`);
+    if (args.transport)
+        displayParts.push(`Target transport: ${args.transport}`);
+    displayParts.push('');
+    clipboardParts.push(`# ${args.summary}`);
+    if (args.transport)
+        clipboardParts.push(`# Target transport: ${args.transport}`);
+    clipboardParts.push('');
+    args.changes.forEach((change, idx) => {
+        const header = `Change ${idx + 1}: ${change.op.toUpperCase()} ${change.type} ${change.object}`;
+        displayParts.push(chalk.cyan(header));
+        clipboardParts.push(`## ${header}`);
+        if (change.diff) {
+            displayParts.push(chalk.gray('─'.repeat(64)));
+            displayParts.push(change.diff);
+            displayParts.push(chalk.gray('─'.repeat(64)));
+            clipboardParts.push('');
+            clipboardParts.push(change.diff);
+            clipboardParts.push('');
+        }
+    });
+    displayParts.push('');
+    displayParts.push(chalk.yellow('Next step: open this object in ADT or SE80, apply the change, save and activate.'));
+    displayParts.push(chalk.gray('Press c to copy to clipboard, y when applied, s to skip, n to abort.'));
+    displayParts.push(chalk.yellow.bold('╚══════════════════════════════════════════════════════════════════╝'));
+    clipboardParts.push('');
+    clipboardParts.push('# This is an advisory proposal. Apply manually in ADT/SE80.');
+    return {
+        displayText: displayParts.join('\n'),
+        clipboardText: clipboardParts.join('\n'),
+    };
+}

package/dist/approvals/approval-prompt.js

@@ -0,0 +1,100 @@
+import chalk from 'chalk';
+import { loadConfig, saveConfig } from '../config/loader.js';
+const BOX_WIDTH = 62;
+const TOP = '┌' + '─'.repeat(BOX_WIDTH) + '┐';
+const BOTTOM = '└' + '─'.repeat(BOX_WIDTH) + '┘';
+const pad = (s) => '│  ' + s.padEnd(BOX_WIDTH - 2) + '│';
+const blank = '│' + ' '.repeat(BOX_WIDTH) + '│';
+/**
+ * Capture a single keypress for the y/n/d answer. Raw-mode readline so the
+ * hand-drawn box stays the only visible affordance.
+ *
+ * Why readline, not inquirer `select`: inquirer would render its own full-screen
+ * picker below our hand-drawn box, giving the user TWO UIs for the same
+ * question. The spec §3.5 Option A says "the box is the UI" — one affordance,
+ * one keypress.
+ */
+async function promptNagChoice() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.setEncoding('utf8');
+        const onData = (key) => {
+            const k = key.toLowerCase();
+            // Ctrl-C → treat as 'n' and let the outer flow continue.
+            if (k === '\u0003') {
+                cleanup();
+                resolve('n');
+                return;
+            }
+            if (k === 'y' || k === 'n' || k === 'd') {
+                cleanup();
+                process.stdout.write(`\n${k}\n`);
+                resolve(k);
+            }
+        };
+        const cleanup = () => {
+            process.stdin.removeListener('data', onData);
+            if (process.stdin.isTTY)
+                process.stdin.setRawMode(false);
+            process.stdin.pause();
+        };
+        process.stdin.on('data', onData);
+    });
+}
+/**
+ * Called just before `renderPerChangeApproval` when the current change
+ * is low-risk on a `never` system and the nag has not been dismissed.
+ *
+ * Mutates config on 'y' (sets auto_approve = 'low') or 'd' (sets per-sap
+ * nag_dismissed = true — see M5 for the scoping rationale). Returns
+ * immediately (no side effect) on 'n'.
+ */
+export async function maybeShowAutoApproveNag(ctx) {
+    const cfg = await loadConfig();
+    const sapCfg = cfg.sap[ctx.sapAlias];
+    // Preconditions: low risk, never policy, per-sap nag not dismissed.
+    if (ctx.effectiveRisk !== 'low')
+        return;
+    if (!sapCfg || sapCfg.auto_approve !== 'never')
+        return;
+    if (sapCfg.nag_dismissed ?? false)
+        return;
+    // Draw the box. This is the ONLY visible UI — keypress answers it directly.
+    console.log('');
+    console.log(TOP);
+    console.log(blank);
+    console.log(pad(chalk.yellow('This change was classified as LOW risk.')));
+    console.log(blank);
+    console.log(pad(`Your current policy on ${ctx.sapAlias} prompts on everything.`));
+    console.log(pad('Want to auto-approve low-risk changes on this system?'));
+    console.log(blank);
+    console.log(pad(chalk.green('[y] yes') + '  (safer for DEV systems only)'));
+    console.log(pad(chalk.dim('[n] no ') + '  (keep prompting every time)'));
+    console.log(pad(chalk.dim('[d] don\'t ask me this again (on ' + ctx.sapAlias + ')')));
+    console.log(blank);
+    console.log(BOTTOM);
+    process.stdout.write(chalk.dim('Press y / n / d: '));
+    const choice = await promptNagChoice();
+    if (choice === 'y') {
+        const fresh = await loadConfig(); // re-read to avoid stale write
+        if (fresh.sap[ctx.sapAlias]) {
+            fresh.sap[ctx.sapAlias].auto_approve = 'low';
+            await saveConfig(fresh);
+            console.log(chalk.green(`Auto-approve set to "low" for ${ctx.sapAlias}.`));
+            console.log(chalk.gray('Change with: cspeach config set sap.' + ctx.sapAlias + '.auto_approve never\n'));
+        }
+    }
+    else if (choice === 'd') {
+        const fresh = await loadConfig();
+        // Per-sap scoping (M5): dismissing on DEV must not suppress the more
+        // important PROD prompt. Each sap system has its own `nag_dismissed` flag.
+        if (fresh.sap[ctx.sapAlias]) {
+            fresh.sap[ctx.sapAlias].nag_dismissed = true;
+            await saveConfig(fresh);
+            console.log(chalk.gray(`Noted. This prompt will not appear again on ${ctx.sapAlias}.\n`));
+        }
+    }
+    // 'n' → no config change, fall through to per-change approval normally.
+}