aiden-runtime 4.0.2 → 4.1.1

package/dist/cli/v4/doctorLiveness.js

@@ -0,0 +1,329 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/doctorLiveness.ts — Phase v4.1.1-oauth-fix Phase 4.
+ *
+ * `aiden doctor --providers` deep-mode helper. Pings every configured /
+ * authed provider with a minimal request, reports green / red / skipped
+ * + per-provider latency + verbatim upstream error message.
+ *
+ * Why a separate file:
+ *   - Default doctor (`aiden doctor` with no flag) stays unchanged and
+ *     fast — config-shape checks only.
+ *   - `--providers` is opt-in. When the user types it we extend the
+ *     report with one liveness row per probe, then render a summary
+ *     line at the bottom.
+ *   - Tool-catalog validation is deliberately OUT of scope. Liveness
+ *     probes ship `tools: []` (see comment in checkProviderLiveness)
+ *     so one bad tool schema doesn't false-red every provider that
+ *     validates strictly. The eval-harness / registration-time schema
+ *     validator (v4.1.1 main) is the right home for that concern.
+ *
+ * Trust artifact:
+ *   - On failure we surface `err.message` VERBATIM (truncated to 200
+ *     chars). Phase 3 (`providers/v4/errors.ts`) already composes the
+ *     upstream response body into ProviderError.message — so a 400
+ *     prints the actual OpenAI reason, not a generic "provider failed."
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enumerateConfiguredProviders = enumerateConfiguredProviders;
+exports.checkProviderLiveness = checkProviderLiveness;
+exports.runProviderLiveness = runProviderLiveness;
+exports.renderProviderLivenessSection = renderProviderLivenessSection;
+const registry_1 = require("../../providers/v4/registry");
+const runtimeResolver_1 = require("../../providers/v4/runtimeResolver");
+const credentialResolver_1 = require("../../providers/v4/credentialResolver");
+const tokenStore_1 = require("../../core/v4/auth/tokenStore");
+const DEFAULT_LIVENESS_TIMEOUT_MS = 8000;
+const PROBE_MAX_TOKENS = 4;
+const ERROR_TRUNCATE_CHARS = 200;
+const OLLAMA_PROBE_TIMEOUT_MS = 1500;
+const OLLAMA_HEALTH_URL = 'http://127.0.0.1:11434/api/tags';
+// ── Helpers ─────────────────────────────────────────────────────────────
+/**
+ * Truncate a long error string for display. The full error remains on
+ * the in-memory `LivenessResult.error` for programmatic consumers /
+ * test assertions.
+ */
+function truncate(s, max = ERROR_TRUNCATE_CHARS) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max - 1)}…`;
+}
+/**
+ * Wrap a promise with a hard timeout. Resolves to the inner result on
+ * success, throws a clearly-labelled `Error` on timeout. Cleans up the
+ * timer either way.
+ */
+async function withTimeout(p, ms, label) {
+    let timer;
+    try {
+        return await Promise.race([
+            p,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${label}: timeout after ${ms}ms`)), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Decide whether a provider counts as "configured" for liveness purposes.
+ * Three paths:
+ *   1. API key in env (`apiKeyEnvVar` set and the env var is non-empty).
+ *   2. OAuth (entry.oauth present and a non-expired token sits in the
+ *      tokenStore at <paths.root>/auth/<providerId>.json).
+ *   3. Local providers (ollama) — probed via a quick HTTP health check.
+ *
+ * Anything else is `configured: false` and gets a `skip_reason`.
+ */
+async function enumerateConfiguredProviders(opts) {
+    const env = opts.env ?? process.env;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const out = [];
+    for (const entry of Object.values(registry_1.PROVIDER_REGISTRY)) {
+        // Every provider needs at least one model to probe against.
+        const model = entry.modelIds[0];
+        if (!model) {
+            out.push({
+                entry,
+                model: '',
+                configured: false,
+                reason: 'no models declared in registry',
+            });
+            continue;
+        }
+        // 1. API-key providers.
+        if (entry.apiKeyEnvVar) {
+            const value = env[entry.apiKeyEnvVar];
+            if (value && value.length > 0) {
+                out.push({ entry, model, configured: true });
+            }
+            else {
+                out.push({
+                    entry,
+                    model,
+                    configured: false,
+                    reason: `env ${entry.apiKeyEnvVar} not set`,
+                });
+            }
+            continue;
+        }
+        // 2. OAuth providers — check tokenStore.
+        if (entry.oauth) {
+            try {
+                const tokens = await (0, tokenStore_1.loadTokens)(opts.paths, entry.oauth.providerId);
+                if (tokens && tokens.accessToken) {
+                    if ((0, tokenStore_1.isExpired)(tokens, tokenStore_1.PREFLIGHT_REFRESH_WINDOW_MS)) {
+                        out.push({
+                            entry,
+                            model,
+                            configured: false,
+                            reason: 'OAuth token expired — run `/auth refresh` or `/auth login`',
+                        });
+                    }
+                    else {
+                        out.push({ entry, model, configured: true });
+                    }
+                }
+                else {
+                    out.push({
+                        entry,
+                        model,
+                        configured: false,
+                        reason: 'no OAuth token — run `/auth login`',
+                    });
+                }
+            }
+            catch (err) {
+                out.push({
+                    entry,
+                    model,
+                    configured: false,
+                    reason: `tokenStore read failed: ${err.message}`,
+                });
+            }
+            continue;
+        }
+        // 3. Local / no-credential providers (ollama). Configured = the
+        // local daemon answers a health probe.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), OLLAMA_PROBE_TIMEOUT_MS);
+        try {
+            const res = await fetchImpl(OLLAMA_HEALTH_URL, { signal: controller.signal });
+            if (res.ok) {
+                out.push({ entry, model, configured: true });
+            }
+            else {
+                out.push({
+                    entry,
+                    model,
+                    configured: false,
+                    reason: `local daemon HTTP ${res.status}`,
+                });
+            }
+        }
+        catch (err) {
+            out.push({
+                entry,
+                model,
+                configured: false,
+                reason: `not running on ${OLLAMA_HEALTH_URL}`,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return out;
+}
+/**
+ * Probe one provider/model pair via a minimal `adapter.call()`. Returns
+ * a structured result; never throws.
+ *
+ * On failure, `result.error` is `err.message` verbatim truncated to
+ * 200 chars. Phase v4.1.1-oauth-fix Phase 3 made `ProviderError.message`
+ * carry the upstream response body, so a 400 surfaces the actual
+ * reason (e.g. "Invalid schema for function 'subagent_fanout': …").
+ */
+async function checkProviderLiveness(provider, model, adapter, opts) {
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_LIVENESS_TIMEOUT_MS;
+    const start = Date.now();
+    // Liveness probes "is this provider reachable + authenticated?".
+    // Tool-catalog validation is a separate concern (eval harness,
+    // v4.1.1 main). Sending tools: [] ensures one bad tool schema
+    // doesn't false-red every provider that validates strictly.
+    const input = {
+        messages: [{ role: 'user', content: 'ping' }],
+        tools: [],
+        maxTokens: PROBE_MAX_TOKENS,
+    };
+    try {
+        await withTimeout(adapter.call(input), timeoutMs, `liveness ${provider}`);
+        return {
+            provider,
+            model,
+            status: 'green',
+            latency_ms: Date.now() - start,
+        };
+    }
+    catch (err) {
+        const raw = err instanceof Error ? err.message : String(err);
+        return {
+            provider,
+            model,
+            status: 'red',
+            latency_ms: Date.now() - start,
+            error: truncate(raw),
+        };
+    }
+}
+/**
+ * Run liveness probes against every provider returned by
+ * `enumerateConfiguredProviders`. Unconfigured providers come back as
+ * `status: 'skipped'` without any network traffic.
+ *
+ * Returns `{ results, summary }`. Summary tallies + a wall-clock total
+ * so the UI can print "X green · Y red · Z skipped · NNNms total".
+ */
+async function runProviderLiveness(opts) {
+    const start = Date.now();
+    const parallel = opts.parallel ?? true;
+    const resolver = opts.resolverImpl ?? new runtimeResolver_1.RuntimeResolver(new credentialResolver_1.CredentialResolver(opts.paths.authJson));
+    const configured = await enumerateConfiguredProviders({
+        paths: opts.paths,
+        env: opts.env,
+        fetchImpl: opts.fetchImpl,
+    });
+    const probe = async (c) => {
+        if (!c.configured) {
+            return {
+                provider: c.entry.id,
+                status: 'skipped',
+                latency_ms: 0,
+                skip_reason: c.reason ?? 'not configured',
+            };
+        }
+        try {
+            const adapter = await resolver.resolve({
+                providerId: c.entry.id,
+                modelId: c.model,
+                paths: opts.paths,
+            });
+            return await checkProviderLiveness(c.entry.id, c.model, adapter, { timeoutMs: opts.timeoutMs });
+        }
+        catch (err) {
+            // Resolve failure (missing credential, unknown model, etc.).
+            // Same surface treatment as a probe failure.
+            const raw = err instanceof Error ? err.message : String(err);
+            return {
+                provider: c.entry.id,
+                model: c.model,
+                status: 'red',
+                latency_ms: 0,
+                error: truncate(raw),
+            };
+        }
+    };
+    const results = parallel
+        ? await Promise.all(configured.map(probe))
+        : await runSequential(configured.map((c) => () => probe(c)));
+    const summary = {
+        green: results.filter((r) => r.status === 'green').length,
+        red: results.filter((r) => r.status === 'red').length,
+        skipped: results.filter((r) => r.status === 'skipped').length,
+        total_ms: Date.now() - start,
+    };
+    return { results, summary };
+}
+async function runSequential(thunks) {
+    const out = [];
+    for (const t of thunks)
+        out.push(await t());
+    return out;
+}
+/**
+ * Render the liveness section as plain-text rows. The doctor command
+ * prints this BELOW the standard health box so the default `aiden doctor`
+ * output stays byte-identical.
+ *
+ * Visual style matches the existing doctor rows (✓ / ✗ / -) but lays
+ * out as a tabular block rather than a box — the rows can be long
+ * (upstream error bodies) and forcing them into the 100-col box would
+ * truncate the diagnostic that's the whole point of the feature.
+ */
+function renderProviderLivenessSection(results, summary) {
+    const nameWidth = Math.max(8, ...results.map((r) => r.provider.length));
+    const lines = [];
+    lines.push('');
+    lines.push('  Provider liveness (deep check)');
+    lines.push(`  ${'─'.repeat(60)}`);
+    for (const r of results) {
+        const icon = r.status === 'green' ? '✓'
+            : r.status === 'red' ? '✗'
+                : '-';
+        const name = r.provider.padEnd(nameWidth);
+        const status = r.status === 'green' ? 'green'.padEnd(8)
+            : r.status === 'red' ? 'red  '.padEnd(8)
+                : 'skip '.padEnd(8);
+        const latency = r.latency_ms > 0
+            ? `${r.latency_ms}ms`.padEnd(8)
+            : ''.padEnd(8);
+        const tail = r.status === 'green' ? (r.model ?? '')
+            : r.status === 'red' ? (r.error ?? 'unknown error')
+                : (r.skip_reason ?? 'not configured');
+        lines.push(`  ${icon} ${name}  ${status}${latency}${tail}`);
+    }
+    lines.push(`  ${'─'.repeat(60)}`);
+    lines.push(`  ${summary.green} green · ${summary.red} red · ${summary.skipped} skipped · ${summary.total_ms}ms total`);
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/cli/v4/envSources.js

@@ -33,9 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_PROVIDER_KEYS = void 0;
 exports.loadAidenEnvFile = loadAidenEnvFile;
 exports.getEnvSource = getEnvSource;
 exports.__resetEnvSources = __resetEnvSources;
+exports.resolveAidenInstallDir = resolveAidenInstallDir;
+exports.loadMcpEnvSources = loadMcpEnvSources;
+exports.describeProviderKeys = describeProviderKeys;
 /**
  * Copyright (c) 2026 Shiva Deore (Taracod).
  * Licensed under AGPL-3.0. See LICENSE for details.
@@ -59,6 +63,7 @@ exports.__resetEnvSources = __resetEnvSources;
  *   - 'unset'     — not in process.env
  */
 const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const ENV_SOURCE_TAG = Symbol.for('aiden.envSource');
 function getMap() {
     let m = globalThis[ENV_SOURCE_TAG];
@@ -121,3 +126,103 @@ function getEnvSource(key) {
 function __resetEnvSources() {
     getMap().clear();
 }
+// ── Phase v4.1-mcp.2 — Multi-source env loader for `aiden mcp serve` ──
+//
+// When Claude Desktop / Cursor / Claude Code spawn `aiden mcp serve`
+// over stdio, they pass an EMPTY env block by default. Without an
+// explicit `env: {...}` per-server entry in the client config, the
+// spawned aiden has no GROQ_API_KEY, GEMINI_API_KEY, etc. Provider-
+// using tools (subagent_fanout, web_search, fetch_url, …) then fail
+// with "no providers configured".
+//
+// Fix: at MCP serve startup, eagerly load .env files from a small
+// list of well-known locations into process.env. Same fill-only
+// semantics as `loadAidenEnvFile` (preset > file). Caller passes
+// `paths.envFile` (covers `~/.aiden/.env` and Windows-equivalent).
+// We additionally probe the install directory so a project-local
+// `.env` in the Aiden checkout works out of the box.
+//
+// NEVER log the values — only the source path and the set of keys
+// (names) detected.
+/** Walk up from `from` looking for an Aiden install root — a directory
+ *  containing a `package.json` whose `name` is `aiden-runtime`. Returns
+ *  null when no candidate is found within `maxDepth` levels. */
+function resolveAidenInstallDir(from = __dirname, maxDepth = 8) {
+    let dir = path.resolve(from);
+    for (let i = 0; i < maxDepth; i += 1) {
+        const pkg = path.join(dir, 'package.json');
+        try {
+            const text = fs.readFileSync(pkg, 'utf8');
+            const parsed = JSON.parse(text);
+            if (parsed.name === 'aiden-runtime')
+                return dir;
+        }
+        catch { /* not present or unparseable, walk up */ }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Load `.env` files for `aiden mcp serve`. Order:
+ *
+ *   1. `<aiden_install_dir>/.env`  — project-local, dev convenience
+ *   2. `aidenHomeEnv`               — per-user, `paths.envFile`
+ *
+ *   3. process.env — already loaded; takes precedence over both
+ *                    via fill-only semantics.
+ *
+ *  Caller logs the report via the mcp-stdio logger (stderr-safe).
+ *  Values are NEVER returned — only counts + key names. */
+function loadMcpEnvSources(opts) {
+    const attempts = [];
+    const installDir = opts.installDir ?? resolveAidenInstallDir();
+    const candidates = [];
+    if (installDir)
+        candidates.push(path.join(installDir, '.env'));
+    candidates.push(opts.aidenHomeEnv);
+    let appliedTotal = 0;
+    for (const file of candidates) {
+        const before = new Set(Object.keys(process.env));
+        let exists = false;
+        try {
+            fs.accessSync(file, fs.constants.R_OK);
+            exists = true;
+        }
+        catch { /* missing — record and skip */ }
+        if (exists)
+            loadAidenEnvFile(file);
+        const appliedKeys = [];
+        for (const k of Object.keys(process.env)) {
+            if (!before.has(k))
+                appliedKeys.push(k);
+        }
+        appliedTotal += appliedKeys.length;
+        attempts.push({ path: file, exists, appliedKeys });
+    }
+    return { attempts, appliedTotal };
+}
+/** The provider-key surface aiden cares about for `mcp status` output.
+ *  Listed explicitly so we never accidentally enumerate / log a
+ *  newly-added secret.  */
+exports.KNOWN_PROVIDER_KEYS = [
+    'GROQ_API_KEY',
+    'GEMINI_API_KEY',
+    'TOGETHER_API_KEY',
+    'OPENROUTER_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'OPENAI_API_KEY',
+    'CEREBRAS_API_KEY',
+    'NVIDIA_API_KEY',
+    'COHERE_API_KEY',
+];
+/** Snapshot of provider-key presence + source. Values NEVER returned;
+ *  only the source tag (`preset`/`aiden-env`/`unset`). */
+function describeProviderKeys(keys = exports.KNOWN_PROVIDER_KEYS) {
+    return keys.map((key) => ({
+        key,
+        present: typeof process.env[key] === 'string' && process.env[key].length > 0,
+        source: getEnvSource(key),
+    }));
+}

package/dist/cli/v4/ghostMatch.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/ghostMatch.ts — Tier-3.1.1 (v4.1-tier3.1.1)
+ *
+ * Compute the best ghost-text match for what the user has typed so far.
+ * The aidenPrompt component calls `findGhost(typed, ctx)` on every
+ * keystroke and renders the returned suggestion (in dim) past the
+ * cursor.
+ *
+ * Two modes:
+ *
+ *   1. Slash mode (typed starts with `/`): match against registered
+ *      slash command names + aliases. Longest start-with match wins
+ *      (so `/p` favours `/plugins` over `/personality`/`/providers`
+ *      only if no shorter unique match exists; ties broken by
+ *      alphabetical order so the result is deterministic).
+ *
+ *   2. Free-text mode: match against recent user prompts (most recent
+ *      first). Returns the first prompt that starts with `typed` and
+ *      is strictly longer.
+ *
+ * Returns the SUFFIX to append after the typed text, or `null` if no
+ * match exists. Empty/whitespace-only typed text → null. Typed text
+ * containing a paste-compression label (`[paste #N: …]`) → null
+ * (don't suggest over a compressed paste).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findGhost = findGhost;
+const PASTE_LABEL_RE = /\[paste #\d+:[^\]]*\]/;
+/**
+ * Return the suffix to append (everything past `typed`) or null.
+ *
+ * Examples:
+ *   findGhost('/cr',  { slashNames: ['cron','clear'], … }) → 'on'
+ *   findGhost('/x',   { slashNames: ['cron'], … })          → null
+ *   findGhost('how ', { history: ['how do I quit'], … })    → 'do I quit'
+ */
+function findGhost(typed, ctx) {
+    if (!typed || typed.trim().length === 0)
+        return null;
+    if (PASTE_LABEL_RE.test(typed))
+        return null;
+    if (typed.startsWith('/')) {
+        const stem = typed.slice(1);
+        if (stem.length === 0)
+            return null;
+        const all = [...ctx.slashNames, ...ctx.slashAliases];
+        // Longest start-with match wins. Ties broken alphabetically.
+        const candidates = all
+            .filter((n) => n.startsWith(stem) && n.length > stem.length)
+            .sort();
+        if (candidates.length === 0)
+            return null;
+        // Prefer the SHORTEST candidate that uniquely starts with stem
+        // (more likely the user-intended completion). Fall back to the
+        // alphabetically-first if all share the same length.
+        const shortest = candidates.reduce((best, c) => c.length < best.length ? c : best);
+        return shortest.slice(stem.length);
+    }
+    // Free-text — history fallback. Prefer the most-recent strict
+    // start-with match.
+    for (const past of ctx.history) {
+        if (past.startsWith(typed) && past.length > typed.length) {
+            return past.slice(typed.length);
+        }
+    }
+    return null;
+}

package/dist/cli/v4/historyStore.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/historyStore.ts — Tier-3.1.1 (v4.1-tier3.1.1)
+ *
+ * Persistent input history for the chat REPL. Each user prompt is
+ * appended to `<aidenHome>/.aiden_history`, one entry per line,
+ * multiline-encoded so a prompt with embedded newlines round-trips
+ * faithfully:
+ *   - `\n` inside a prompt is encoded as `\\n` on disk
+ *   - `\\` inside a prompt is encoded as `\\\\` on disk
+ *
+ * The store filters out:
+ *   - blank entries
+ *   - duplicates of the most recent entry
+ *   - very-short entries (<3 chars after trim) — too noisy to suggest
+ *   - paste-labelled entries (`[paste #N: …]`) — privacy. The user's
+ *     real prompt was the label-substituted text; storing the label
+ *     would leak nothing but storing the expanded text would leak the
+ *     entire pasted block into a plain-text history file.
+ *
+ * On startup, `loadRecent()` returns the last `limit` entries (newest
+ * first) for the autosuggest history fallback.
+ *
+ * Atomic write: each `append` writes a temp sibling then renames over
+ * the live file (Windows rename is atomic on the same volume), so a
+ * crash mid-write can never corrupt the history.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HISTORY_MAX_ENTRIES = void 0;
+exports.appendHistory = appendHistory;
+exports.loadRecent = loadRecent;
+exports._resetForTests = _resetForTests;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("../../core/v4/paths");
+const HISTORY_FILENAME = '.aiden_history';
+const PASTE_LABEL_RE = /\[paste #\d+:[^\]]*\]/;
+let writeLatch = Promise.resolve();
+function historyPath() {
+    return node_path_1.default.join((0, paths_1.resolveAidenPaths)().root, HISTORY_FILENAME);
+}
+/** Encode a prompt for one-line storage on disk. */
+function encode(s) {
+    return s.replace(/\\/g, '\\\\').replace(/\n/g, '\\n');
+}
+/** Reverse of `encode`. */
+function decode(s) {
+    // Walk the string so `\\\\n` decodes to `\\n` (literal backslash + n)
+    // rather than the placeholder for newline.
+    let out = '';
+    for (let i = 0; i < s.length; i += 1) {
+        const c = s[i];
+        if (c === '\\' && i + 1 < s.length) {
+            const next = s[i + 1];
+            if (next === 'n') {
+                out += '\n';
+                i += 1;
+            }
+            else if (next === '\\') {
+                out += '\\';
+                i += 1;
+            }
+            else {
+                out += c;
+            }
+        }
+        else {
+            out += c;
+        }
+    }
+    return out;
+}
+/**
+ * Append `entry` to the history file. Filters per the rules above.
+ * Best-effort — disk failures are swallowed so a crashed history
+ * write never breaks the agent loop.
+ */
+/**
+ * Tier-3-essentials: cap the live file at this many entries. When an
+ * append would push the count above, we rotate the oldest out before
+ * writing the new line. 5000 = ~250 KB at typical prompt sizes,
+ * trivial to keep on disk and load on every prompt.
+ */
+exports.HISTORY_MAX_ENTRIES = 5000;
+async function appendHistory(entry) {
+    const trimmed = entry.trim();
+    if (trimmed.length < 3)
+        return;
+    if (PASTE_LABEL_RE.test(trimmed))
+        return;
+    await (writeLatch = writeLatch.then(async () => {
+        try {
+            const p = historyPath();
+            const dir = node_path_1.default.dirname(p);
+            if (!(0, node_fs_1.existsSync)(dir))
+                (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+            // Read current contents once — we use them for both dup-suppress
+            // and rotation.
+            let priorLines = [];
+            try {
+                const cur = await node_fs_1.promises.readFile(p, 'utf8');
+                priorLines = cur.split('\n').filter((l) => l.length > 0);
+            }
+            catch { /* file may not exist yet */ }
+            // Skip if equal to the last entry on disk (cheap dup-suppress).
+            const lastDecoded = priorLines.length > 0 ? decode(priorLines[priorLines.length - 1]) : '';
+            if (lastDecoded === entry)
+                return;
+            // Rotation: cap at HISTORY_MAX_ENTRIES. The new line will push
+            // total to len+1; if that exceeds the cap, drop the oldest
+            // (len+1 - cap) entries from the front so we land EXACTLY at
+            // the cap.
+            const wantTotal = priorLines.length + 1;
+            if (wantTotal > exports.HISTORY_MAX_ENTRIES) {
+                const dropFront = wantTotal - exports.HISTORY_MAX_ENTRIES;
+                priorLines = priorLines.slice(dropFront);
+            }
+            const tmp = `${p}.tmp`;
+            const nextContent = priorLines.join('\n')
+                + (priorLines.length > 0 ? '\n' : '')
+                + `${encode(entry)}\n`;
+            await node_fs_1.promises.writeFile(tmp, nextContent, 'utf8');
+            await node_fs_1.promises.rename(tmp, p);
+        }
+        catch {
+            // History write failure must not bubble up.
+        }
+    }));
+}
+/**
+ * Return the last `limit` entries (newest first). Decoded — caller
+ * sees the original prompt verbatim including any embedded newlines.
+ *
+ * Tier-3-essentials: default raised 100 → 500 so the autosuggest
+ * history-mode reaches further back. The on-disk cap is independently
+ * controlled by `HISTORY_MAX_ENTRIES`.
+ */
+async function loadRecent(limit = 500) {
+    try {
+        const p = historyPath();
+        const raw = await node_fs_1.promises.readFile(p, 'utf8');
+        const lines = raw.split('\n').filter((l) => l.length > 0);
+        const decoded = lines.map(decode);
+        const sliced = decoded.slice(Math.max(0, decoded.length - limit));
+        return sliced.reverse();
+    }
+    catch {
+        return [];
+    }
+}
+/** Test/reset hook: drop in-process state. Disk untouched. */
+function _resetForTests() {
+    writeLatch = Promise.resolve();
+}