@cspeach/cli 0.9.0 → 1.1.0

package/dist/repl/bracketed-paste.js

@@ -59,18 +59,6 @@ export function disableBracketedPaste(stream = process.stdout) {
     if (stream.isTTY)
         stream.write(BRACKETED_PASTE_DISABLE);
 }
-/**
- * Transform stream that collapses the content between `\x1b[200~` and
- * `\x1b[201~` into a single line (newlines replaced with spaces). The
- * markers themselves are stripped. All other bytes pass through
- * unchanged, including keystrokes, arrow-key escape sequences, and
- * terminal responses — these are not affected because they never contain
- * the paste markers.
- *
- * The implementation uses Buffer operations (not string concat) to avoid
- * splitting multi-byte UTF-8 sequences at chunk boundaries when a paste
- * spans multiple `data` events.
- */
 export class BracketedPasteDecoder extends Transform {
     /**
      * Readline with `terminal: true` inspects `input.isTTY` and calls
@@ -81,9 +69,17 @@ export class BracketedPasteDecoder extends Transform {
      *
      * We present as a TTY and forward the raw-mode toggle and the size
      * getters to the real `process.stdin` / `process.stdout`.
+     *
+     * (Typed `boolean`, not the literal `true`, so InkStdinPasteGuard can
+     * mirror the real process.stdin.isTTY instead.)
      */
     // eslint-disable-next-line @typescript-eslint/naming-convention
     isTTY = true;
+    emitVerbatim;
+    constructor(options = {}) {
+        super();
+        this.emitVerbatim = options.emitVerbatim ?? false;
+    }
     setRawMode(mode) {
         if (typeof process.stdin.setRawMode === 'function')
             process.stdin.setRawMode(mode);
@@ -166,9 +162,9 @@ export class BracketedPasteDecoder extends Transform {
             this.carryTimer = null;
         }
         // End of stream. If we were still inside a paste (unterminated),
-        // flush the buffered content as a single line so it's not lost.
+        // flush the buffered content so it's not lost.
         if (this.inPaste && this.pasteBuf.length > 0) {
-            this.push(this.collapseNewlines(this.pasteBuf));
+            this.push(this.emitVerbatim ? this.pasteBuf : this.collapseNewlines(this.pasteBuf));
             this.pasteBuf = Buffer.alloc(0);
             this.inPaste = false;
         }
@@ -192,11 +188,24 @@ export class BracketedPasteDecoder extends Transform {
                     return;
                 }
                 this.pasteBuf = Buffer.concat([this.pasteBuf, data.subarray(i, endIdx)]);
-                this.push(this.collapseNewlines(this.pasteBuf));
-                // Append a newline so readline commits the pasted line as a
-                // single input — otherwise the user would still have to press
-                // Enter after the paste.
-                this.push(Buffer.from('\n'));
+                if (this.emitVerbatim) {
+                    // Ink mode: ONE chunk, newlines intact, markers stripped, no
+                    // synthetic Enter. Downstream (Ink useInput → text-input paste
+                    // branch) buffers the complete lines and keeps the fragment —
+                    // nothing submits until the user presses Enter. Crucially a
+                    // `\r` that arrived as its own stdin chunk INSIDE the span was
+                    // accumulated here instead of reaching Ink's parseKeypress,
+                    // which would have flagged it key.return and submitted.
+                    if (this.pasteBuf.length > 0)
+                        this.push(this.pasteBuf);
+                }
+                else {
+                    this.push(this.collapseNewlines(this.pasteBuf));
+                    // Append a newline so readline commits the pasted line as a
+                    // single input — otherwise the user would still have to press
+                    // Enter after the paste.
+                    this.push(Buffer.from('\n'));
+                }
                 this.pasteBuf = Buffer.alloc(0);
                 this.inPaste = false;
                 i = endIdx + END_MARKER.length;

package/dist/repl/builtin-commands.js

@@ -0,0 +1,42 @@
+/**
+ * Built-in (non-skill) slash commands — the single source of truth.
+ *
+ * Extracted from slash-picker.ts (2026-06-11) so the router layer
+ * (src/router/classifier.ts) can distinguish "user typed a builtin with
+ * arguments" (e.g. `/help me`) from "user typed an unknown skill"
+ * WITHOUT importing the inquirer-backed picker module. Pure data — no
+ * runtime dependencies.
+ */
+export const BUILTIN_ENTRIES = [
+    { name: '/cancel', description: 'Cancel the current pre-filled command, return to a clean prompt' },
+    { name: '/cost', description: 'Show this session\'s API spend so far ($ + token breakdown)' },
+    { name: '/compact', description: 'Summarise older turns into a compact context block — cuts subsequent turn cost by 80-90%' },
+    { name: '/export', description: 'Export the signable session audit record — /export audit [filename]' },
+    { name: '/context', description: 'Show what fills the model context window — a composition grid of bars' },
+    { name: '/exit', description: 'Exit CSPeach' },
+    { name: '/quit', description: 'Exit CSPeach (alias)' },
+    { name: '/help', description: 'Show all skills and commands' },
+    { name: '/skills', description: 'Show all skills (alias)' },
+    { name: '/mode', description: 'Cycle or set the session write mode (advisory / gated / auto) — config unchanged' },
+    { name: '/new', description: 'Reset routing — next prompt is classified afresh' },
+    { name: '/recap', description: 'Show the session recap (last session · open tasks · plan progress)' },
+    { name: '/reset', description: 'Reset routing (alias)' },
+    { name: '/rewind', description: 'Undo a write from this session — restore an object to a pre-write snapshot (Esc Esc)' },
+    { name: '/ui', description: 'View or change rendering mode (auto / ink / classic)' },
+    { name: '/reroute', description: 'Re-dispatch the previous prompt to a different skill' },
+    { name: '/transport', description: 'View or set the active transport for this session' },
+    { name: '/safety-mode', description: 'Toggle structured Forge Rule confirmation cards (on / off / status)' },
+];
+/**
+ * Builtin command heads for routing checks. Superset of BUILTIN_ENTRIES:
+ * `/files` is a real REPL builtin (repl.tsx handles it in both paths) but
+ * is deliberately absent from the picker catalogue, so it's added here.
+ */
+const BUILTIN_HEADS = new Set([
+    ...BUILTIN_ENTRIES.map((e) => e.name),
+    '/files',
+]);
+/** True when `head` (e.g. '/help', as typed, any case) is a builtin command. */
+export function isBuiltinCommandHead(head) {
+    return BUILTIN_HEADS.has(head.toLowerCase());
+}

package/dist/repl/current-transport.js

@@ -14,16 +14,26 @@
  *
  * Module-scope singleton per CLI process. Tests must call clearCurrentTransport()
  * in beforeEach to avoid leakage across Vitest test files.
+ *
+ * Task 9 (ux-wave1) — this setter is ALSO the single statusline wire for the
+ * `tr <TRKORR>` segment: every path that changes the session transport
+ * (sap_transport create success, owning-transport adoption in the create
+ * guard, /transport slash command) funnels through set/clear here, so the
+ * globalStore push lives HERE rather than scattered across tool handlers.
+ * Store writes are harmless in classic mode (nothing subscribes there).
  */
+import { globalStore } from '../ui/sap-state-store.js';
 let currentTransport = null;
 export function setCurrentTransport(trkorr) {
     currentTransport = trkorr;
+    globalStore.update({ transport: trkorr });
 }
 export function getCurrentTransport() {
     return currentTransport;
 }
 export function clearCurrentTransport() {
     currentTransport = null;
+    globalStore.update({ transport: null });
 }
 /**
  * Handles the `/transport [<trkorr>|clear]` slash command. Returns user-facing

package/dist/repl/early-line-buffer.js

@@ -0,0 +1,68 @@
+/**
+ * Early-line buffer for piped-stdin REPL runs — UX-5 #5 (2026-06-12).
+ *
+ * The bug (found 2026-06-11): lines piped into the classic REPL
+ * (`"/cost`n/exit" | cspeach`) arrive on the readline BEFORE the loop's
+ * first rl.question() is pending. Node's readline only routes a line to a
+ * question callback when one is registered; otherwise it emits the 'line'
+ * EVENT — which nobody consumed, so every early line was silently dropped
+ * (even /cost never dispatched). stdin EOF then closed the readline and
+ * the old 'close' handler hard-exited. This blocked CI-driven multi-phase
+ * plan runs entirely.
+ *
+ * Fix shape:
+ *   - attach a 'line' listener at readline creation that QUEUES lines
+ *     arriving while no question is pending (readline emits 'line' only
+ *     in that case — a pending question consumes the line directly);
+ *   - the REPL loop drains this queue before calling rl.question;
+ *   - on stdin EOF ('close') the buffer flips `closed` and the loop keeps
+ *     processing queued lines before exiting (the repl.tsx close handler
+ *     no longer hard-exits in piped mode);
+ *   - the FIRST piped line gets a UTF-8 BOM strip — PowerShell pipes
+ *     inject one, which used to corrupt the first command head.
+ *
+ * Only attached when stdin is NOT a TTY (see repl.tsx): in interactive
+ * mode, type-ahead during a turn should keep its existing
+ * behaviour rather than silently becoming queued commands.
+ */
+/** Strip a single leading UTF-8 BOM (PowerShell pipes inject one). */
+export function stripBom(s) {
+    return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+/**
+ * Attach the queueing listeners to `rl` and return the buffer handle.
+ * Call once, immediately after readline creation, BEFORE any awaits —
+ * piped data starts flowing on the next tick.
+ */
+export function attachEarlyLineBuffer(rl) {
+    const queue = [];
+    let firstLine = true;
+    let isClosed = false;
+    rl.on('line', (l) => {
+        let line = String(l);
+        if (firstLine) {
+            line = stripBom(line);
+            firstLine = false;
+        }
+        queue.push(line);
+    });
+    rl.on('close', () => {
+        isClosed = true;
+    });
+    return {
+        size: () => queue.length,
+        shift: () => queue.shift(),
+        closed: () => isClosed,
+    };
+}
+/**
+ * Inert buffer for interactive (TTY) runs — keeps the repl.tsx loop free
+ * of `isTTY` branches at every drain site.
+ */
+export function noopEarlyLineBuffer() {
+    return {
+        size: () => 0,
+        shift: () => undefined,
+        closed: () => false,
+    };
+}

package/dist/repl/history.js

@@ -0,0 +1,86 @@
+/**
+ * Persistent REPL history — the ONE writer shared by every append site:
+ *  - classic readline path (repl.tsx)
+ *  - Ink handleSubmit (repl.tsx)
+ *  - Ink Footer (ui/footer.tsx)
+ *
+ * File shape: `~/.cspeach/history`, one entry per line, chronological
+ * (oldest at top, newest at bottom), appended on every submit; capped at
+ * READ time (HISTORY_SIZE in repl.tsx), not write time.
+ *
+ * Task 8 (ux-wave1) — consecutive-duplicate dedup lives HERE so all
+ * append sites share a single guard (CC parity: bash
+ * HISTCONTROL=ignoredups). `x, y, x` stores three entries — only
+ * back-to-back repeats collapse, never across gaps. Comparison is on the
+ * flattened + trimmed entry, against the file tail — so it also holds
+ * across session restarts, AND it collapses the Ink path's historical
+ * double append (Footer wrote the entry, then repl.tsx's handleSubmit
+ * wrote the same submission again — unflattened).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+// Resolved lazily (not at module load) so it honours the HOME/USERPROFILE
+// active at call time — lets tests point it at a temp dir.
+export function historyFile() {
+    return path.join(os.homedir(), '.cspeach', 'history');
+}
+/** All persisted entries, oldest → newest, trimmed, blank lines dropped. */
+export function readHistoryEntries() {
+    try {
+        return fs
+            .readFileSync(historyFile(), 'utf-8')
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Flatten a submission into a single history-file entry: `\r\n` becomes
+ * ONE space, then every remaining C0 control + DEL becomes a space.
+ *
+ * Wave1 fast-follow (tab-flatten): newlines were already flattened, but
+ * tabs (e.g. from a pasted tab-indented ABAP snippet) survived into the
+ * history file. A tab-bearing entry later rendered in the Ctrl+R fuzzy
+ * list dodges Ink's truncate-end — widestLine/string-width measure `\t`
+ * as 0 cells while the terminal renders up to 8 — re-opening the exact
+ * wrapped-row erase-accounting leak Bug 1 fixed (see text-input.tsx
+ * maxDisplayWidth doc). Flattening at WRITE time keeps new entries clean;
+ * the fuzzy-row render flattens too, covering pre-fix history files.
+ */
+export function flattenHistoryEntry(line) {
+    // eslint-disable-next-line no-control-regex
+    return line.replace(/\r\n/g, ' ').replace(/[\x00-\x1f\x7f]/g, ' ').trim();
+}
+/**
+ * Append one entry to the history file.
+ *  - Submissions are flattened (newlines, tabs, and all other C0
+ *    controls → ' ') — the file is one-entry-per-line (Task 7 contract)
+ *    and entries must never carry width-invisible controls (tab-flatten
+ *    fast-follow; see flattenHistoryEntry).
+ *  - Skips when the flattened + trimmed entry equals the file's LAST
+ *    entry (consecutive dedup — trimmed comparison).
+ *  - Never throws: history persistence failure must not crash the REPL.
+ *
+ * @returns true when the entry was written, false when skipped.
+ */
+export function appendHistoryEntry(line) {
+    const entry = flattenHistoryEntry(line);
+    if (!entry)
+        return false;
+    try {
+        const entries = readHistoryEntries();
+        if (entries.length > 0 && entries[entries.length - 1] === entry)
+            return false;
+        const file = historyFile();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, entry + '\n', 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/repl/ink-stdin-guard.js

@@ -0,0 +1,64 @@
+/**
+ * InkStdinPasteGuard — bracketed-paste interception for the INK path
+ * (wave1 live-fix, Bug 2: multiline paste submitted line-by-line on real
+ * Windows Terminal).
+ *
+ * What the live test proved (and Task 7's assumption it disproved):
+ * Windows Terminal does NOT deliver a paste as one big chunk with
+ * embedded newlines — pasted newlines arrive as `\r`, and a `\r` can
+ * land as its OWN stdin chunk. Ink's parseKeypress flags a chunk that is
+ * exactly '\r' as key.return (ink/build/parse-keypress.js:145-148), so
+ * every pasted line submitted immediately — the garbled multi-dispatch
+ * the user saw.
+ *
+ * Why the interception must happen BEFORE Ink parses:
+ *  - With DEC 2004 enabled the paste arrives as `\x1b[200~ … \x1b[201~`,
+ *    but Ink's parser mangles the markers: parse-keypress' fnKeyRe
+ *    matches `\x1b[200~` with code '[200~' → name undefined, and
+ *    use-input.js:73-75 strips the leading ESC from the sequence, so the
+ *    marker would land in the input as literal garbage text ("[200~…").
+ *    There is no reliable way to reassemble a marker split across chunks
+ *    from inside useInput.
+ *  - The reliable seam is the stdin stream itself: Ink accepts a custom
+ *    `stdin` in its render options and touches exactly this surface on
+ *    it (ink/build/components/App.js:104-139): `isTTY`, `setEncoding`,
+ *    `ref`/`unref`, `setRawMode`, `addListener('readable')` + `read()`.
+ *    A Transform (Duplex) provides the readable side natively; the four
+ *    TTY-ish members are shimmed here, forwarding to process.stdin.
+ *
+ * Wiring (repl.tsx Ink branch): enableBracketedPaste() →
+ * `process.stdin.pipe(guard)` → `render(…, { stdin: guard })`. The base
+ * class (BracketedPasteDecoder with emitVerbatim) strips the markers,
+ * accumulates the whole span — including any `\r`-only chunks inside it —
+ * and re-emits the paste as ONE chunk with newlines preserved. Ink then
+ * hands that single chunk unsplit to useInput, where text-input's Task-7
+ * paste branch buffers complete lines via onPasteLines and keeps the
+ * tail fragment. NOTHING can submit mid-paste because no `\r`-only chunk
+ * ever reaches parseKeypress between the markers.
+ *
+ * Terminals without bracketed-paste support simply never send markers:
+ * the guard is pass-through and behaviour is exactly the pre-fix Task 7
+ * path (no regression, same as the classic-mode caveat).
+ */
+import { BracketedPasteDecoder } from './bracketed-paste.js';
+export class InkStdinPasteGuard extends BracketedPasteDecoder {
+    /**
+     * Mirror the REAL stdin's TTY-ness (the base class hardcodes true for
+     * readline's sake). Ink gates isRawModeSupported on this — lying about
+     * a non-TTY stdin would make Ink call setRawMode on a pipe.
+     */
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    isTTY = process.stdin.isTTY ?? false;
+    constructor() {
+        super({ emitVerbatim: true });
+    }
+    /** Ink calls stdin.ref()/unref() around raw-mode enable/disable. */
+    ref() {
+        process.stdin.ref?.();
+        return this;
+    }
+    unref() {
+        process.stdin.unref?.();
+        return this;
+    }
+}

package/dist/repl/inquirer-guard.js

@@ -28,6 +28,50 @@
  */
 import { clearActiveSpinner } from '../renderer/tool-widget.js';
 let state = null;
+/**
+ * UX-5 #4 (2026-06-12) — sequence-scoped (debounced) release.
+ *
+ * Failure mode this fixes: between BACK-TO-BACK inquirer prompts fired by
+ * the SAME handler (safety-confirm's two-step select, ask_question's
+ * select → custom-input follow-up, /files step 1 → step 2), the old
+ * per-prompt release resumed the outer readline the instant prompt N
+ * finished — readline repainted its prompt with a stale history/buffer
+ * entry for a frame — and then prompt N+1 paused it again. The user saw
+ * the old line flash between the two pickers.
+ *
+ * Scope note (M1, 2026-06-12): consecutive ask_question TOOL calls are
+ * separated by a full LLM round-trip (seconds apart) — the 50ms debounce
+ * neither covers nor needs to cover those; readline legitimately resumes
+ * between turns. The debounce only spans same-handler prompt sequences.
+ *
+ * Fix shape: the release (rl.resume + suppress-clear) is DEFERRED by
+ * RELEASE_DEBOUNCE_MS. If another withInquirer starts inside that window
+ * (an ask SEQUENCE), the pending release is cancelled and the outer
+ * prompt stays parked across the whole sequence — no repaint between
+ * prompts. Only the final prompt's release actually fires.
+ *
+ * Note: this is a CLASSIC-path concern only. Under Ink, ask_question /
+ * approval render through the Ink-native emitter modals (see
+ * tools/ask-question.ts shouldUseInk branch) and registerReadline is
+ * never called, so withInquirer is a pass-through there.
+ *
+ * The suppress flag intentionally stays TRUE during the debounce window —
+ * any spurious 'close' inquirer emits on release is still swallowed,
+ * which is strictly safer than the old nextTick clearing.
+ */
+// 50ms (M4 rationale): covers same-tick and next-macrotask prompt chaining
+// with ~3 frames of margin (one terminal frame ≈ 16ms) while staying far
+// below human-perceptible delay before the outer prompt repaints.
+export const RELEASE_DEBOUNCE_MS = 50;
+let pendingRelease = null;
+/** Re-entrancy depth — release is scheduled only when the OUTERMOST call exits. */
+let activeDepth = 0;
+function cancelPendingRelease() {
+    if (pendingRelease) {
+        clearTimeout(pendingRelease);
+        pendingRelease = null;
+    }
+}
 /**
  * Called by repl.tsx once the main readline is created. The `setSuppress`
  * callback must flip the same boolean the readline 'close' handler
@@ -38,6 +82,8 @@ export function registerReadline(rl, setSuppress) {
 }
 /** Clear the guard — call when the REPL is shutting down. */
 export function unregisterReadline() {
+    cancelPendingRelease();
+    activeDepth = 0;
     state = null;
 }
 /**
@@ -66,6 +112,12 @@ export async function withInquirer(fn) {
     // which collides with inquirer's prompt rendering — visible as ghost-text
     // and a cursor that hides under the rotating frame while the user types.
     clearActiveSpinner();
+    // UX-5 #4 — continuing an ask SEQUENCE: a release from the previous
+    // prompt is still pending, so cancel it. The readline stays parked
+    // (paused + close-suppressed) across the gap — no stale-line repaint
+    // between consecutive prompts.
+    cancelPendingRelease();
+    activeDepth++;
     // 2026-05-08: snapshot stdin 'data' / 'keypress' listeners BEFORE the
     // inquirer prompt runs. Some inquirer widgets (notably `search`, used
     // by /files step 1) strip ALL listeners on cleanup — including
@@ -120,11 +172,24 @@ export async function withInquirer(fn) {
         // Order matters here:
         //  1. resume stdin so the event loop stays referenced (otherwise the
         //     next rl.question prints its prompt and the process exits).
-        //  2. resume the readline so it accepts new input.
-        //  3. defer the suppress-clear so the spurious 'close' that inquirer
-        //     synchronously emits on release is still ignored.
+        //  2. SCHEDULE the readline resume + suppress-clear instead of doing
+        //     them inline (UX-5 #4). If another inquirer prompt opens within
+        //     RELEASE_DEBOUNCE_MS — an ask sequence — the entry above cancels
+        //     this timer and the outer readline never repaints between
+        //     prompts. The timer is deliberately NOT unref'd: it must hold
+        //     the event loop open across the gap.
+        //  3. inside the deferred release, still defer the suppress-clear by
+        //     one tick so the spurious 'close' that inquirer synchronously
+        //     emits on release is ignored.
         process.stdin.resume();
-        rl.resume();
-        process.nextTick(() => setSuppress(false));
+        activeDepth = Math.max(0, activeDepth - 1);
+        if (activeDepth === 0) {
+            cancelPendingRelease();
+            pendingRelease = setTimeout(() => {
+                pendingRelease = null;
+                rl.resume();
+                process.nextTick(() => setSuppress(false));
+            }, RELEASE_DEBOUNCE_MS);
+        }
     }
 }

package/dist/repl/mode-ceiling.js

@@ -0,0 +1,16 @@
+/** Ordered from most to least restricted. */
+export const WRITE_MODE_ORDER = ['advisory-only', 'approval-gated', 'auto'];
+const ROLE_CEILING = {
+    dev: 'auto',
+    qas: 'approval-gated',
+    prd: 'advisory-only',
+};
+/** The most permissive write mode a system role allows. */
+export function modeCeiling(role) {
+    return role === undefined ? 'auto' : ROLE_CEILING[role];
+}
+/** Clamp a mode to the role's ceiling. */
+export function clampToCeiling(mode, role) {
+    const ceiling = modeCeiling(role);
+    return WRITE_MODE_ORDER.indexOf(mode) <= WRITE_MODE_ORDER.indexOf(ceiling) ? mode : ceiling;
+}

package/dist/repl/mode-cycle.js

@@ -0,0 +1,104 @@
+import { clampToCeiling, modeCeiling, WRITE_MODE_ORDER, } from './mode-ceiling.js';
+/**
+ * Session-scoped effective write mode + cycling core (UX Wave 1, Task 2).
+ *
+ * The config's `write_mode` is the durable setting; this module layers a
+ * SESSION override on top (Shift+Tab-style cycling, lost on exit) and clamps
+ * the result to the active system role's ceiling (mode-ceiling.ts):
+ *
+ *   effective = clamp(sessionOverride ?? configMode, roleCeiling)
+ *
+ * Cycling walks WRITE_MODE_ORDER restricted to the modes the role allows:
+ *   dev / unset → advisory → gated → auto → advisory …
+ *   qas         → advisory → gated → advisory …   (auto not in the cycle — a
+ *                                                  gated→advisory step is a
+ *                                                  WRAP, not a cap)
+ *   prd         → pinned at advisory-only; a cycle attempt reports
+ *                 `capped: true` so the caller can render the refusal line.
+ *
+ * Pure module — no I/O, no config access; callers pass config mode + role in.
+ * Module-level state is test-resettable via `setSessionWriteMode(null)`.
+ */
+let sessionWriteMode = null;
+/** Session override; null = follow config. Module-level, test-resettable. */
+export function setSessionWriteMode(mode) {
+    sessionWriteMode = mode;
+}
+export function getSessionWriteMode() {
+    return sessionWriteMode;
+}
+/** cfgMode overlaid by session override, then clamped to the alias role's ceiling. */
+export function getEffectiveWriteMode(cfgMode, role) {
+    return clampToCeiling(sessionWriteMode ?? cfgMode, role);
+}
+/**
+ * Cycle to the next mode the role allows (wraps). Sets the session override
+ * so the new mode takes effect immediately. Returns the new mode AND whether
+ * the requested step was capped (for the refusal line).
+ */
+export function cycleWriteMode(cfgMode, role) {
+    const ceilingIdx = WRITE_MODE_ORDER.indexOf(modeCeiling(role));
+    // Modes at or below the ceiling, in cycling order (most→least restricted).
+    const allowed = WRITE_MODE_ORDER.slice(0, ceilingIdx + 1);
+    if (allowed.length === 1) {
+        // prd: pinned — there is nowhere to step. Report capped for the refusal line.
+        setSessionWriteMode(allowed[0]);
+        return { mode: allowed[0], capped: true };
+    }
+    const current = getEffectiveWriteMode(cfgMode, role);
+    const next = allowed[(allowed.indexOf(current) + 1) % allowed.length];
+    setSessionWriteMode(next);
+    return { mode: next, capped: false };
+}
+/** Short /mode arguments → WriteMode. */
+const MODE_ARGS = {
+    advisory: 'advisory-only',
+    gated: 'approval-gated',
+    auto: 'auto',
+};
+function announceLine(prev, next) {
+    return `mode: ${prev} → ${next} (session only — config unchanged)`;
+}
+function refusalLine(clamped, role, alias) {
+    return `mode capped at ${clamped} — sap.${alias ?? '?'}.role = ${role} (policy)`;
+}
+/**
+ * /mode command core (UX Wave 1, Task 3). Pure apart from the session
+ * override it shares with cycleWriteMode — the REPL builtin and the
+ * Shift+Tab / Alt+M keybindings are thin shells over this.
+ *
+ *   - bare / empty arg      → cycle (wraps within the role's allowed modes)
+ *   - 'advisory'|'gated'|'auto' → jump directly (still clamped to the ceiling;
+ *                             a jump above it returns the refusal line and
+ *                             the clamped mode)
+ *   - anything else         → usage line, mode untouched
+ *
+ * Returns the line to print (caller dims it) and the resulting effective
+ * mode (caller pushes it into the SapStateStore so the statusline is live).
+ */
+export function runModeCommand(arg, cfgMode, role, alias) {
+    const prev = getEffectiveWriteMode(cfgMode, role);
+    const normalized = arg?.trim().toLowerCase() ?? '';
+    if (normalized === '') {
+        const { mode, capped } = cycleWriteMode(cfgMode, role);
+        // capped is only ever true with a prd role, so `role!` is safe here.
+        if (capped)
+            return { line: refusalLine(mode, role, alias), mode };
+        return { line: announceLine(prev, mode), mode };
+    }
+    const target = MODE_ARGS[normalized];
+    if (target === undefined) {
+        return {
+            line: `usage: /mode [advisory|gated|auto] — bare /mode cycles (current: ${prev})`,
+            mode: prev,
+        };
+    }
+    const clamped = clampToCeiling(target, role);
+    setSessionWriteMode(clamped);
+    if (clamped !== target) {
+        // Jump above the ceiling — clamp landed us lower than requested. `role!`
+        // is safe: without a role the ceiling is 'auto' and nothing clamps.
+        return { line: refusalLine(clamped, role, alias), mode: clamped };
+    }
+    return { line: announceLine(prev, clamped), mode: clamped };
+}