aiden-runtime 4.0.1 → 4.1.0

package/dist/cli/v4/table.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/table.ts — lightweight ASCII table renderer (Tier-3.1).
+ *
+ * Drop-in replacement for `Display.twoColumnBlock` style output at
+ * call sites that want full multi-column tables (`/skills`,
+ * `/cron list`, `/channel list`). No `cli-table3` dependency — the
+ * renderer is ~150 lines, ANSI-aware via `string-width`, and uses
+ * the same SkinEngine colour kinds as the rest of v4.
+ *
+ * Box drawing is sharp ASCII (`─ │ ┌ ┐ └ ┘ ├ ┤`) to stay aligned
+ * with the rest of the v4.1-tier3.1 box pass.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTable = renderTable;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const stringWidth = require('string-width');
+const skinEngine_1 = require("./skinEngine");
+const box_1 = require("./box");
+/**
+ * Visible (post-ANSI-strip) column width. Falls back to
+ * `visibleLength` from box.ts when string-width is unavailable
+ * (which would only happen if the dep was removed).
+ */
+function vWidth(s) {
+    try {
+        return stringWidth(s);
+    }
+    catch {
+        return (0, box_1.visibleLength)(s);
+    }
+}
+/** Pad `s` to `w` visible columns using `align`. ANSI-safe. */
+function pad(s, w, align = 'left') {
+    const sw = vWidth(s);
+    if (sw >= w)
+        return s;
+    const gap = w - sw;
+    if (align === 'right')
+        return ' '.repeat(gap) + s;
+    if (align === 'center') {
+        const l = Math.floor(gap / 2);
+        return ' '.repeat(l) + s + ' '.repeat(gap - l);
+    }
+    return s + ' '.repeat(gap);
+}
+/** Truncate to `max` visible columns with a single `…` tail. */
+function truncCell(s, max) {
+    if (vWidth(s) <= max)
+        return s;
+    if (max <= 1)
+        return '…';
+    return (0, box_1.truncateVisible)(s, max - 1) + '…';
+}
+/** Resolve a column's display string for one row. */
+function cellValue(row, col) {
+    const raw = row[col.key];
+    const v = col.format ? col.format(raw, row) : (raw == null ? '' : String(raw));
+    if (col.truncate && vWidth(v) > col.truncate) {
+        return truncCell(v, col.truncate);
+    }
+    return v;
+}
+/**
+ * Tier-3.1b: word-boundary-aware truncate. Tries to cut at the last
+ * space inside `[max*0.5, max-1]` and append `…`. Falls back to the
+ * dumb mid-word cut when no space lives in that range. Never produces
+ * a result wider than `max`.
+ */
+function smartTrunc(s, max) {
+    if (vWidth(s) <= max)
+        return s;
+    if (max <= 1)
+        return '…';
+    const candidate = (0, box_1.truncateVisible)(s, max - 1);
+    // Word-boundary search — only honour spaces that leave at least
+    // half the column populated, otherwise the cell looks empty.
+    const lastSpace = candidate.lastIndexOf(' ');
+    if (lastSpace >= Math.floor(max * 0.5)) {
+        return candidate.slice(0, lastSpace) + '…';
+    }
+    return candidate + '…';
+}
+/**
+ * Tier-3.1b: allocate per-column widths to fit `available` chars.
+ * Non-flex columns prefer their natural width; flex columns absorb
+ * the leftover space proportional to their natural sizes. When even
+ * fixed columns overflow, every column is shrunk proportionally with
+ * a hard floor of 8 chars per column.
+ */
+function allocateWidths(cols, natural, available) {
+    const numCols = cols.length;
+    const totalNatural = natural.reduce((a, b) => a + b, 0);
+    if (totalNatural <= available)
+        return natural.slice();
+    // If any column declared flex:true, treat those as flex; otherwise
+    // the last column carries the flex flag (description-most case).
+    const explicitFlex = cols.some((c) => c.flex === true);
+    const flexFlags = cols.map((c, i) => explicitFlex ? c.flex === true : i === numCols - 1);
+    const fixedSum = natural.reduce((s, w, i) => s + (flexFlags[i] ? 0 : w), 0);
+    const flexNaturalSum = natural.reduce((s, w, i) => s + (flexFlags[i] ? w : 0), 0);
+    if (fixedSum >= available || flexNaturalSum === 0) {
+        // Even fixed columns don't fit — proportional shrink everything.
+        const ratio = available / Math.max(1, totalNatural);
+        return natural.map((w) => Math.max(8, Math.floor(w * ratio)));
+    }
+    const remainingForFlex = available - fixedSum;
+    return natural.map((w, i) => {
+        if (!flexFlags[i])
+            return w;
+        return Math.max(8, Math.floor(remainingForFlex * (w / flexNaturalSum)));
+    });
+}
+/**
+ * Render `rows` as an ASCII table. Returns the multi-line string
+ * (with a trailing `\n`); caller writes it via the display.
+ */
+function renderTable(rows, cols, opts = {}) {
+    const skin = (0, skinEngine_1.getSkinEngine)();
+    const indent = opts.indent ?? 2;
+    const showRule = opts.showHeaderRule !== false;
+    // Pre-compute uncoloured cell values so width math sees exact text.
+    const valueGrid = rows.map((row) => cols.map((c) => cellValue(row, c)));
+    // Natural widths — max(header, longest cell, minWidth).
+    const naturalWidths = cols.map((c, i) => {
+        let w = vWidth(c.header);
+        for (const rowVals of valueGrid) {
+            const cw = vWidth(rowVals[i]);
+            if (cw > w)
+                w = cw;
+        }
+        if (c.minWidth && c.minWidth > w)
+            w = c.minWidth;
+        return w;
+    });
+    // Tier-3.1b: responsive width allocation. Total table chars =
+    // indent + 1 (left border) + sum(width+2) + (numCols-1) inner
+    // separators + 1 (right border). Solve for content budget given
+    // the caller-provided maxWidth (or terminal columns).
+    const numCols = cols.length;
+    const overhead = indent + 3 * numCols + 1;
+    // Honor an explicit override first, then the live TTY width, then
+    // the COLUMNS env var (set by `term`-aware shells and most spawned
+    // subprocess wrappers — process.stdout.columns is `undefined` when
+    // stdout is a pipe, so falling back to env keeps tables responsive
+    // for piped consumers like /ui dashboards). Final fallback: 100.
+    const envCols = process.env.COLUMNS ? parseInt(process.env.COLUMNS, 10) : 0;
+    const maxWidth = opts.maxWidth ??
+        process.stdout.columns ??
+        (envCols > 0 ? envCols : 100);
+    const availableForContent = Math.max(numCols * 8, maxWidth - overhead);
+    const widths = allocateWidths(cols, naturalWidths, availableForContent);
+    // Apply smart truncation to any cell whose content exceeds its
+    // allocated width. Non-flex columns at natural width never trigger
+    // this branch; flex columns may.
+    for (let i = 0; i < numCols; i += 1) {
+        const w = widths[i];
+        for (const rowVals of valueGrid) {
+            if (vWidth(rowVals[i]) > w) {
+                rowVals[i] = smartTrunc(rowVals[i], w);
+            }
+        }
+    }
+    // Border characters (sharp ASCII).
+    const TL = '┌', TR = '┐', BL = '└', BR = '┘';
+    const T = '┬', B = '┴', L = '├', R = '┤';
+    const X = '┼', H = '─', V = '│';
+    const ind = ' '.repeat(indent);
+    // Top border.
+    const top = TL + widths.map((w) => H.repeat(w + 2)).join(T) + TR;
+    // Header row — heading colour, padded. Truncate first if the
+    // header itself is wider than the allocated width (rare, but
+    // keeps borders aligned under aggressive narrow-width pressure).
+    const headerCells = cols.map((c, i) => {
+        const w = widths[i];
+        const text = vWidth(c.header) > w ? smartTrunc(c.header, w) : c.header;
+        const padded = pad(text, w, c.align ?? 'left');
+        return ' ' + skin.applyColors(padded, 'heading') + ' ';
+    });
+    const headerRow = V + headerCells.join(V) + V;
+    // Header rule.
+    const rule = L + widths.map((w) => H.repeat(w + 2)).join(X) + R;
+    // Body rows.
+    const bodyLines = [];
+    const compact = opts.compact === true;
+    valueGrid.forEach((rowVals, rIdx) => {
+        if (!compact && rIdx > 0) {
+            // Tier-3.1a: inter-row separator using `├─…─┼─…─┤` glyphs.
+            bodyLines.push(L + widths.map((w) => H.repeat(w + 2)).join(X) + R);
+        }
+        const cells = cols.map((c, i) => {
+            const raw = rowVals[i];
+            const padded = pad(raw, widths[i], c.align ?? 'left');
+            const colorKind = c.color ? c.color(rows[rIdx][c.key], rows[rIdx]) : undefined;
+            const painted = colorKind ? skin.applyColors(padded, colorKind) : padded;
+            return ' ' + painted + ' ';
+        });
+        bodyLines.push(V + cells.join(V) + V);
+    });
+    // Bottom border.
+    const bot = BL + widths.map((w) => H.repeat(w + 2)).join(B) + BR;
+    const allLines = [
+        top,
+        headerRow,
+        ...(showRule ? [rule] : []),
+        ...bodyLines,
+        bot,
+    ].map((l) => ind + l);
+    return allLines.join('\n') + '\n';
+}

package/dist/cli/v4/themeDetect.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/themeDetect.ts — Phase v4.1-tier3-essentials
+ *
+ * Multi-signal auto theme detection. The skin engine consults this
+ * once at boot when the configured skin is `auto`; otherwise the
+ * explicitly-named skin wins.
+ *
+ * Priority order (first non-undefined hit wins):
+ *
+ *   1. AIDEN_THEME=light|dark         — explicit override
+ *   2. AIDEN_THEME=auto / unset goes through 2..5
+ *   3. NO_COLOR set                   — forced monochrome
+ *   4. COLORFGBG="<fg>;<bg>"          — slot 7 or 15 = light, others = dark
+ *   5. TERM_PROGRAM allow-list        — Apple_Terminal default to light
+ *   6. Fallback: dark
+ *
+ * Returns 'light' / 'dark' / 'mono'. The skin engine maps:
+ *   'mono'  → monochrome skin (no colour)
+ *   'light' → light skin
+ *   'dark'  → default skin
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectTheme = detectTheme;
+exports.detectedToSkinName = detectedToSkinName;
+const LIGHT_DEFAULT_TERM_PROGRAMS = new Set([
+    // Apple Terminal default profile is on a light background.
+    'Apple_Terminal',
+]);
+/**
+ * Run the multi-signal detection. Pure function — env can be
+ * overridden for tests.
+ */
+function detectTheme(env = process.env) {
+    const explicit = (env.AIDEN_THEME ?? '').trim().toLowerCase();
+    if (explicit === 'light')
+        return 'light';
+    if (explicit === 'dark')
+        return 'dark';
+    if (explicit === 'mono' || explicit === 'monochrome')
+        return 'mono';
+    // NO_COLOR (https://no-color.org) — monochrome is its own theme,
+    // independent of light/dark, so it wins over the auto path.
+    if (env.NO_COLOR != null && env.NO_COLOR !== '')
+        return 'mono';
+    // COLORFGBG = "<fg>;<bg>" where slot 7 (light grey) or 15 (white)
+    // signals a light terminal background. Other slots = dark.
+    const colorfgbg = (env.COLORFGBG ?? '').trim();
+    if (colorfgbg) {
+        const parts = colorfgbg.split(';');
+        const lastField = parts[parts.length - 1] ?? '';
+        if (/^\d+$/.test(lastField)) {
+            const bg = Number(lastField);
+            if (bg === 7 || bg === 15)
+                return 'light';
+            if (bg >= 0 && bg < 16)
+                return 'dark';
+        }
+    }
+    // TERM_PROGRAM allow-list.
+    const termProgram = (env.TERM_PROGRAM ?? '').trim();
+    if (LIGHT_DEFAULT_TERM_PROGRAMS.has(termProgram))
+        return 'light';
+    // Fallback.
+    return 'dark';
+}
+/** Surfaced for skinEngine integration: maps DetectedTheme → skin name. */
+function detectedToSkinName(theme) {
+    switch (theme) {
+        case 'light': return 'light';
+        case 'mono': return 'monochrome';
+        case 'dark':
+        default: return 'default';
+    }
+}

package/dist/cli/v4/uiBuild.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIDEN_PRESHIP_BUILD = exports.AIDEN_CROSS_PLATFORM_BUILD = exports.AIDEN_REPLY_FORMAT_BUILD = exports.AIDEN_SKILL_MINING_BUILD = exports.AIDEN_UI_BUILD = void 0;
+exports.citationsEnabled = citationsEnabled;
+exports.isMcpServeMode = isMcpServeMode;
+exports.isNoUiMode = isNoUiMode;
+exports.uiIconsEnabled = uiIconsEnabled;
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod). Licensed under AGPL-3.0.
+ *
+ * cli/v4/uiBuild.ts — Aiden v4.1 Tier-3 UI build fingerprint.
+ *
+ * A single source-of-truth string the smokes can `require()` from
+ * the built artifact. Bumped by hand at the start of each tier-3
+ * sub-phase so smoke harnesses can pin against the expected build.
+ */
+exports.AIDEN_UI_BUILD = 'v4.1-tier3-essentials';
+/**
+ * Phase v4.1-skill-mining: build fingerprint for the auto-extract
+ * subsystem. Bumped per skill-mining sub-phase so smokes can pin
+ * against the expected build.
+ */
+exports.AIDEN_SKILL_MINING_BUILD = 'v4.1-skill-mining';
+/**
+ * Phase v4.1-reply-formatting: build fingerprint for the structured
+ * markdown rendering / citation footer / streaming stable-prefix
+ * subsystem. Render-layer only — no agent prompts or behavior change.
+ */
+exports.AIDEN_REPLY_FORMAT_BUILD = 'v4.1-reply-formatting';
+/**
+ * Phase v4.1-cross-platform: build fingerprint for the Linux / macOS
+ * compatibility pass — path helpers, audio backend detection, skill
+ * loader case-insensitive lookup, doctor checks per OS, CI matrix.
+ */
+exports.AIDEN_CROSS_PLATFORM_BUILD = 'v4.1-cross-platform';
+/**
+ * Phase v4.1-preship-cleanup: build fingerprint for the day-one
+ * polish batch — vitest baseline goes from 37 fails to 0, telegram
+ * 409 path gains a local-machine polling lock to prevent same-box
+ * rivals from racing.
+ */
+exports.AIDEN_PRESHIP_BUILD = 'v4.1-preship-cleanup';
+/** Predicate: is the citation footer enabled? Default off. */
+function citationsEnabled() {
+    return process.env.AIDEN_CITATIONS === '1';
+}
+/**
+ * Predicate: are we running in MCP serve mode? When true, the
+ * stdout channel belongs to JSON-RPC and any UI write would corrupt
+ * the wire. Tier-3 UI helpers consult this before printing.
+ *
+ * The MCP server CLI (cli/v4/commands/mcp.ts) sets
+ * `process.env.AIDEN_MCP_SERVE = '1'` early in its boot path; that
+ * env-var check is intentionally cheap and safe to read often.
+ */
+function isMcpServeMode() {
+    return process.env.AIDEN_MCP_SERVE === '1';
+}
+/**
+ * Predicate: is the legacy/no-UI flag in effect? Disables tier-3
+ * polish (autosuggest ghost text, inline status line, etc.) and
+ * falls back to pre-tier3.1 rendering. Set by `aiden --no-ui`.
+ */
+function isNoUiMode() {
+    return process.env.AIDEN_NO_UI === '1';
+}
+/**
+ * Predicate: should slash-command icons render? Default OFF; opt-in
+ * via `AIDEN_UI_ICONS=1`. Lets users with emoji-friendly terminals
+ * recover the previous icon column.
+ */
+function uiIconsEnabled() {
+    return process.env.AIDEN_UI_ICONS === '1';
+}

package/dist/cli/v4/voiceCli.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/voiceCli.ts — Phase v4.1-voice-cli
+ *
+ * `aiden voice <action>` top-level CLI subcommand. Three actions:
+ *
+ *   doctor          — print diagnostics: build, TTY, mic backend,
+ *                     TTS providers, current config. No mic open.
+ *   tts <text>      — synthesise + play one short clip. Real
+ *                     provider call.
+ *   transcribe <f>  — STT one audio file. Reuses the v4.1-3
+ *                     `whisper-transcribe` channel pipeline.
+ *
+ * Distinct from the `/voice` slash command (which mutates session
+ * state from inside the REPL). This subcommand exists so users can
+ * verify mic + speaker setup BEFORE entering the REPL — useful for
+ * first-run mic-permission grants on Windows where the OS prompts
+ * the first time the device is opened.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIDEN_VOICE_CLI_BUILD = void 0;
+exports.runVoiceSubcommand = runVoiceSubcommand;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const node_fs_1 = require("node:fs");
+const diagnostics_1 = require("../../core/v4/voice/diagnostics");
+Object.defineProperty(exports, "AIDEN_VOICE_CLI_BUILD", { enumerable: true, get: function () { return diagnostics_1.AIDEN_VOICE_CLI_BUILD; } });
+const tts_1 = require("../../core/voice/tts");
+const whisper_transcribe_1 = require("../../core/channels/whisper-transcribe");
+async function runVoiceSubcommand(action, args, opts = {}) {
+    const writeOut = opts.writeOut ?? ((t) => process.stdout.write(t));
+    const writeErr = opts.writeErr ?? ((t) => process.stderr.write(t));
+    switch (action) {
+        case 'doctor': {
+            const diag = await (0, diagnostics_1.collectVoiceDiagnostics)();
+            writeOut(`Aiden voice — ${diagnostics_1.AIDEN_VOICE_CLI_BUILD}\n`);
+            writeOut(`  tty:            ${diag.isTty ? 'yes' : 'no'}\n`);
+            writeOut(`  enabled:        ${diag.enabled ? 'yes' : 'no (refused — non-TTY stdin)'}\n`);
+            writeOut(`  mic backend:    ${diag.audio.backend}\n`);
+            writeOut(`  mic active:     ${diag.audio.active ? 'yes' : 'no'}\n`);
+            writeOut(`  sox on PATH:    ${diag.audio.soxOnPath ? 'yes' : 'no'}\n`);
+            writeOut(`  mode:           ${diag.config.mode}\n`);
+            writeOut(`  tts voice:      ${diag.config.ttsVoice}\n`);
+            writeOut(`  beeps:          ${diag.config.beepsEnabled ? 'on' : 'off'}\n`);
+            writeOut(`  tts providers:\n`);
+            for (const p of diag.ttsProviders) {
+                const tag = p.available ? '✓' : '✗';
+                writeOut(`    ${tag} ${p.name.padEnd(12)} ${p.note ?? ''}\n`);
+            }
+            // Mic-backend hint when nothing is installed.
+            if (diag.audio.backend === 'unavailable') {
+                writeOut(`\n  Hint: install \`decibri\` (npm i decibri) for prebuilt mic capture,\n`);
+                writeOut(`        OR install sox (https://sox.sourceforge.io/) + node-record-lpcm16.\n`);
+            }
+            return 0;
+        }
+        case 'tts': {
+            const text = args.join(' ').trim();
+            if (!text) {
+                writeErr(`Usage: aiden voice tts "<text>"\n`);
+                return 1;
+            }
+            const cleaned = (0, tts_1.cleanForTTS)(text);
+            if (!cleaned) {
+                writeErr(`Empty after cleanForTTS — nothing to speak.\n`);
+                return 1;
+            }
+            writeOut(`Synthesising via TTS chain (${cleaned.length} chars)...\n`);
+            const r = await (0, tts_1.synthesize)({ text: cleaned });
+            if (r.error) {
+                writeErr(`TTS failed: ${r.error}\n`);
+                return 1;
+            }
+            writeOut(`TTS ok — provider: ${r.provider}, ${r.durationMs}ms\n`);
+            return 0;
+        }
+        case 'transcribe': {
+            const filePath = args[0];
+            if (!filePath) {
+                writeErr(`Usage: aiden voice transcribe <audio-file>\n`);
+                return 1;
+            }
+            try {
+                await node_fs_1.promises.access(filePath);
+            }
+            catch {
+                writeErr(`File not found: ${filePath}\n`);
+                return 1;
+            }
+            writeOut(`Transcribing ${filePath}...\n`);
+            const r = await (0, whisper_transcribe_1.transcribeForChannel)({ filePath });
+            if (!r.success) {
+                writeErr(`Transcribe failed: ${r.error ?? 'unknown'}\n`);
+                return 1;
+            }
+            const conf = typeof r.avgLogprob === 'number'
+                ? ` (avgLogprob=${r.avgLogprob.toFixed(2)})`
+                : '';
+            writeOut(`Transcript${conf}:\n${r.text ?? ''}\n`);
+            return 0;
+        }
+        default: {
+            writeErr(`Unknown 'aiden voice' action: ${action}\n`);
+            writeErr(`Actions: doctor | tts <text> | transcribe <file>\n`);
+            return 1;
+        }
+    }
+}

package/dist/cli/v4/voicePromptApi.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/voicePromptApi.ts — Phase v4.1-voice-cli
+ *
+ * Wraps a default `ChatPromptApi` implementation with a raw-mode
+ * spacebar toggle for push-to-talk recording. When the user is at
+ * the prompt and presses Space:
+ *
+ *   1. Switch to raw mode + start `cliVoice.startRecording()`
+ *   2. Update the spinner: "🎤 recording (Space to stop, Esc to cancel)"
+ *   3. On second Space: stop and transcribe → return transcript
+ *   4. On Esc: cancel and return empty (caller falls back to text)
+ *   5. On any other character before the first Space: hand control
+ *      back to the wrapped `inquirer` prompt so the user types
+ *      normally
+ *
+ * Hard-refuses activation when `process.stdin.isTTY` is false. This
+ * is the MCP-stdio invariant — `aiden mcp serve` uses stdin as the
+ * JSON-RPC transport, and toggling raw mode there would corrupt
+ * every protocol frame. The refusal is silent in MCP context (the
+ * default `readLine` runs unchanged); explicit in REPL context (a
+ * stderr warning + fall-through).
+ *
+ * `selectSlashCommand` is delegated unchanged — slash commands
+ * still go through the inquirer dropdown.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVoicePromptApi = createVoicePromptApi;
+exports.voiceModeAllowed = voiceModeAllowed;
+const factory_1 = require("../../core/v4/logger/factory");
+const KEY_SPACE = 0x20;
+const KEY_ESC = 0x1b;
+/** Build a prompt API that intercepts Space for push-to-talk and
+ *  falls through to `inner` for normal text input. */
+function createVoicePromptApi(opts) {
+    const logger = (opts.logger ?? (0, factory_1.noopLogger)()).child('voice-prompt');
+    const stdin = opts.stdin ?? process.stdin;
+    const stdout = opts.stdout ?? process.stdout;
+    return {
+        async readLine(prompt) {
+            // Hard refuse when stdin isn't a TTY. Voice mode requires raw
+            // mode; raw mode requires a TTY. MCP stdio mode hits this path
+            // when Claude Desktop spawns aiden — silently fall through.
+            if (!stdin.isTTY) {
+                return opts.inner.readLine(prompt);
+            }
+            const transcript = await waitForSpaceOrTypedInput({
+                prompt,
+                stdin,
+                stdout,
+                voice: opts.voice,
+                onStatus: opts.onStatus,
+                logger,
+            });
+            if (transcript === null) {
+                // User typed text — hand off to the regular prompt API. The
+                // first character is already in the typeahead via the buffer
+                // — `inner.readLine` reads from there.
+                return opts.inner.readLine(prompt);
+            }
+            if (transcript === '') {
+                // Cancelled — fall back to text prompt.
+                return opts.inner.readLine(prompt);
+            }
+            return transcript;
+        },
+        async selectSlashCommand(source) {
+            // Slash commands don't get voice intercept — they're a
+            // discrete dropdown.
+            return opts.inner.selectSlashCommand(source);
+        },
+    };
+}
+/** Wait for either Space (start recording) or any other char (fall
+ *  through to text prompt). Returns:
+ *   - the transcribed string when recording completes
+ *   - '' when user cancels (Esc)
+ *   - null when user types non-space (fall through to inner) */
+async function waitForSpaceOrTypedInput(args) {
+    // Show a brief hint so users know voice mode is hot.
+    args.stdout.write(`${args.prompt}\x1b[2m(Space to talk)\x1b[0m `);
+    const stdin = args.stdin;
+    // Snapshot current raw mode state to restore on exit.
+    const wasRaw = !!stdin.isRaw;
+    if (!wasRaw)
+        stdin.setRawMode(true);
+    stdin.resume();
+    let result = undefined;
+    let recording = false;
+    let transcript = null;
+    let resolveOuter = null;
+    const cleanup = () => {
+        stdin.removeListener('data', onData);
+        stdin.removeListener('error', onError);
+        if (!wasRaw) {
+            try {
+                stdin.setRawMode(false);
+            }
+            catch { /* ignore */ }
+        }
+        stdin.pause();
+    };
+    const onData = (chunk) => {
+        if (chunk.length === 0)
+            return;
+        const code = chunk[0];
+        if (!recording) {
+            if (code === KEY_SPACE) {
+                // Start recording.
+                recording = true;
+                args.voice.startRecording().catch((err) => {
+                    args.logger.warn('startRecording threw', { error: err.message });
+                });
+            }
+            else if (code === KEY_ESC) {
+                result = '';
+                cleanup();
+                resolveOuter?.('');
+            }
+            else if (code === 0x03) {
+                // Ctrl+C — propagate to inner via empty cancel.
+                result = '';
+                cleanup();
+                resolveOuter?.('');
+            }
+            else {
+                // Any other key — fall through to inner prompt. Push the
+                // byte back so inner reads it (best-effort; on Windows
+                // the unread() trick isn't reliable, so we just signal
+                // null and inner re-prompts).
+                result = null;
+                cleanup();
+                resolveOuter?.(null);
+            }
+        }
+        else {
+            // Already recording. Space stops; Esc cancels.
+            if (code === KEY_SPACE) {
+                args.voice.stopRecording().catch((err) => {
+                    args.logger.warn('stopRecording threw', { error: err.message });
+                });
+            }
+            else if (code === KEY_ESC || code === 0x03) {
+                args.voice.cancel();
+                result = '';
+                cleanup();
+                resolveOuter?.('');
+            }
+        }
+    };
+    const onError = (err) => {
+        args.logger.warn('stdin error during voice prompt', { error: err.message });
+        cleanup();
+        resolveOuter?.(null);
+    };
+    // Voice handle's onTranscript wins the race when recording succeeds.
+    // We register a one-shot subscription via the existing callback by
+    // taking advantage of the fact that handle.startRecording resolves
+    // when transcribe completes — at that point transcript will be set
+    // through the host's status callback. To keep this module narrowly
+    // scoped, we POLL voice.getStatus() between awaits via a watcher.
+    const watcher = setInterval(() => {
+        const s = args.voice.getStatus();
+        args.onStatus?.(s);
+        // Recording finished naturally OR errored.
+        if (recording && s === 'idle') {
+            // Drain stdin and resolve. The transcript was forwarded via
+            // the host's onTranscript callback (set up in the cliVoice
+            // constructor); the host stitches it into the conversation.
+            // For the prompt-API contract we resolve with empty so the
+            // outer loop spins to the next iteration.
+            cleanup();
+            clearInterval(watcher);
+            resolveOuter?.(transcript ?? '');
+        }
+    }, 50);
+    stdin.on('data', onData);
+    stdin.on('error', onError);
+    return new Promise((resolve) => {
+        resolveOuter = (v) => {
+            clearInterval(watcher);
+            resolve(v);
+        };
+    });
+}
+/** Test-only helper: enforce the TTY guard. Returns true when voice
+ *  mode is allowed to activate in this process. */
+function voiceModeAllowed(stdin = process.stdin) {
+    return !!stdin.isTTY;
+}