aiden-runtime 4.9.2 → 4.9.4

package/README.md

@@ -105,6 +105,13 @@ Windows · Linux · WSL · macOS (API Mode)
 
 
 
+https://github.com/user-attachments/assets/1081e5c5-f1ec-4980-b710-1640981ec58b
+
+
+
+
+
+
 > A semi-autonomous AI agent that runs on your machine. Touches your files, browser, and shell. Remembers what matters. Built solo. Open source. Still rough in spots.
 
 <br>
@@ -130,7 +137,13 @@ Drop a file in `~/Documents/inbox/anything.txt` and Aiden acts on it. The agent
 
 <br>
 
-![Aiden in action](docs/screenshots/autonomy.png)
+
+
+
+
+https://github.com/user-attachments/assets/7a66bc19-8b17-4b01-be85-3aa5945a1b3b
+
+
 
 <br>
 
@@ -219,6 +232,13 @@ Full v4.5 internals: [`docs/v4.5/`](docs/v4.5/) (overview, triggers, architectur
 | **MCP** | Model Context Protocol bridge — stdio + HTTP transports, schema discovery, tool dispatch. |
 | **Security moat** | Tiered approval engine (`safe` / `caution` / `dangerous`), dangerous-command pattern classifier, honesty enforcement (post-loop scan rewrites false claims), memory guard, planner-guard tool narrowing, SSRF-safe URL fetcher, secret/PII pre-write scanner, skill-teacher (auto-create skills from successful flows). |
 
+
+
+
+
+
+
+
 <br>
 
 ## Architecture
@@ -229,6 +249,13 @@ Detailed diagrams + module map in [`docs/v4.5/architecture.md`](docs/v4.5/archit
 
 <br>
 
+
+
+
+https://github.com/user-attachments/assets/323c9aa7-959a-425a-a5b3-4bae2b1a14bc
+
+
+
 ## Install + first run
 
 ### Linux / WSL / macOS (one-line)
@@ -285,6 +312,10 @@ Remove-Item -Recurse -Force $env:LOCALAPPDATA\aiden
 <img width="938" height="1049" alt="preview (3)" src="https://github.com/user-attachments/assets/4e32ae38-74ad-433d-b986-0a15bc2dffec" />
 
 
+
+https://github.com/user-attachments/assets/398e1d48-cc5a-4fb5-a195-05dbef824198
+
+
 ## Recommended terminal setup
 
 For best visual rendering, Aiden looks crispest with:
@@ -488,6 +519,21 @@ Common issues live in [`docs/v4.5/troubleshooting.md`](docs/v4.5/troubleshooting
 - **`/help` doesn't list a command** — that command likely needs an active session field; run from a real REPL
 - **`npm install` permission errors on Windows** — install into a real folder (not a drive root like `S:\`)
 
+
+
+
+https://github.com/user-attachments/assets/3acc997f-1d71-45d1-9955-11b67abd0c50
+
+
+
+https://github.com/user-attachments/assets/9e734168-cf76-4cc0-975a-379e5402ee90
+
+
+
+https://github.com/user-attachments/assets/5e7011a5-630d-43bd-8ed3-67084c7645db
+
+
+
 <br>
 
 ## The book

package/dist/cli/v4/chatSession.js

@@ -83,6 +83,7 @@ const uiBuild_1 = require("./uiBuild");
 const sessionSummaryGate_1 = require("./sessionSummaryGate");
 const aidenPrompt_1 = __importDefault(require("./aidenPrompt"));
 const confirmPrompt_1 = require("./confirmPrompt");
+const greeter_1 = require("./greeter");
 const historyStore_1 = require("./historyStore");
 const modelMetadata_1 = require("../../core/v4/modelMetadata");
 // v4.1.3-prebump: classify provider errors so the catch path can show
@@ -1681,6 +1682,22 @@ class ChatSession {
             }
         }
         catch { /* never let a missing marker crash boot */ }
+        // v4.9.3 Slice 1b — boot greeter. Silent on first-ever launch (lets
+        // renderFirstRunHint above own boot #1), silent when /greeter off,
+        // silent when no offer wins. Lazy-required so test-harness sessions
+        // without `paths` wired skip the fs cost. Internal errors are
+        // already swallowed inside renderGreeter; outer try/catch is the
+        // belt-and-braces guarantee against a boot-crash regression.
+        try {
+            if (this.opts.paths) {
+                await (0, greeter_1.renderGreeter)({
+                    paths: this.opts.paths,
+                    version: version_1.VERSION,
+                    display: this.opts.display,
+                });
+            }
+        }
+        catch { /* never let the greeter crash boot */ }
         // v4.9.0 pre-ship UI: hint moved BEFORE the closing rule so the
         // rule sits adjacent to the active prompt (it becomes the visual
         // top of the prompt zone). New order: blank · hint · blank · rule.

package/dist/cli/v4/commands/greeter.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/commands/greeter.ts — v4.9.3 SLICE 1a.
+ *
+ * `/greeter on | off | status` — REPL controls for the boot greeter.
+ *   - on     → set disabled: false; init the file if missing
+ *   - off    → confirm-gated (uses v4.9.2 Slice 3 ctx.confirm), set
+ *              disabled: true
+ *   - status → print current state + last greeting + offer summary
+ *
+ * Slice 1a: the slash command operates on the history file even
+ * though the greeter doesn't fire on boot yet (Slice 1b wires that).
+ * `/greeter off` BEFORE Slice 1b still durably disables, so when
+ * Slice 1b lands the user's choice is already honored.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.greeter = void 0;
+const history_1 = require("../greeter/history");
+exports.greeter = {
+    name: 'greeter',
+    description: 'Manage the boot greeter. Actions: on, off, status.',
+    category: 'system',
+    icon: '👋',
+    handler: async (ctx) => {
+        if (!ctx.paths) {
+            ctx.display.printError('Cannot read greeter state — paths not wired in this session.');
+            return;
+        }
+        const sub = (ctx.args[0] ?? 'status').toLowerCase();
+        if (sub === 'on') {
+            const h = (await (0, history_1.readHistory)(ctx.paths)) ?? initial();
+            h.disabled = false;
+            await (0, history_1.writeHistory)(ctx.paths, h);
+            ctx.display.success('Greeter on. Next boot will check for noticeable changes.');
+            return;
+        }
+        if (sub === 'off') {
+            if (!ctx.confirm) {
+                ctx.display.printError('Cannot confirm in this context.');
+                return;
+            }
+            const proceed = await ctx.confirm('Turn the boot greeter off? You can re-enable with /greeter on.');
+            if (!proceed)
+                return; // confirm() already printed the rejection reason
+            const h = (await (0, history_1.readHistory)(ctx.paths)) ?? initial();
+            h.disabled = true;
+            await (0, history_1.writeHistory)(ctx.paths, h);
+            ctx.display.success('Greeter off. No greeting on boot until /greeter on.');
+            return;
+        }
+        if (sub === 'status') {
+            const h = await (0, history_1.readHistory)(ctx.paths);
+            if (!h) {
+                ctx.display.dim('Greeter has not been initialized yet (no boots since v4.9.3).');
+                return;
+            }
+            const state = h.disabled ? 'off' : 'on';
+            const accepted = h.offers.filter((o) => o.response === 'accepted').length;
+            const ignored = h.offers.filter((o) => o.response === 'ignored').length;
+            const pending = h.offers.filter((o) => !o.response).length;
+            ctx.display.write('\n  Greeter status:\n');
+            ctx.display.write(`    state:         ${state}\n`);
+            ctx.display.write(`    first launch:  ${h.firstLaunchAt}\n`);
+            ctx.display.write(`    last greeting: ${h.lastGreetingAt}\n`);
+            ctx.display.write(`    offers:        ${h.offers.length} (${accepted} accepted · ${ignored} ignored · ${pending} pending)\n\n`);
+            return;
+        }
+        ctx.display.printError(`Unknown greeter action '${sub}'.`, 'Try: /greeter on | off | status');
+    },
+};
+function initial() {
+    const now = new Date().toISOString();
+    return {
+        v: 1,
+        firstLaunchAt: now,
+        lastGreetingAt: now,
+        offers: [],
+        disabled: false,
+    };
+}

package/dist/cli/v4/commands/help.js

@@ -79,6 +79,8 @@ exports.SUBSECTION_MAP = {
     // v4.9.1 amendment — REPL surfaces for memory + hooks (daemon already mapped).
     memory: 'System',
     hooks: 'System',
+    // v4.9.3 Slice 1b — boot greeter management.
+    greeter: 'System',
     // ── Authentication ──
     auth: 'Authentication',
     // ── Help ──

package/dist/cli/v4/commands/index.js

@@ -111,6 +111,8 @@ const memorySlash_1 = require("./memorySlash");
 Object.defineProperty(exports, "memory", { enumerable: true, get: function () { return memorySlash_1.memory; } });
 const hooksSlash_1 = require("./hooksSlash");
 Object.defineProperty(exports, "hooks", { enumerable: true, get: function () { return hooksSlash_1.hooks; } });
+// v4.9.3 Slice 1b — boot greeter management.
+const greeter_1 = require("./greeter");
 /** All built-in system commands, in canonical order. */
 exports.allCommands = [
     help_1.help,
@@ -166,6 +168,8 @@ exports.allCommands = [
     // v4.9.1 amendment — REPL slash surfaces mirroring CLI subcommands.
     memorySlash_1.memory,
     hooksSlash_1.hooks,
+    // v4.9.3 Slice 1b — boot greeter management.
+    greeter_1.greeter,
     clear_1.clear,
     quit_1.quit,
 ];

package/dist/cli/v4/greeter/history.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/greeter/history.ts — v4.9.3 SLICE 1a.
+ *
+ * Greeter state persistence. Single JSON file at
+ * `<paths.root>/.greeter-history.json` — matches the existing
+ * `.first-run-shown` / `.recent-commands.json` precedent rather than
+ * carving out a `state/` subdirectory for one file.
+ *
+ * Three exported helpers:
+ *   - readHistory   → null when the file does not exist (first launch)
+ *   - writeHistory  → atomic via tmp + rename, matches the v4
+ *                     `upsertEnv` pattern
+ *   - reconcilePending → pure function that walks the history and
+ *                       resolves pending offers (no `response` yet)
+ *                       using passive next-boot signals from the scan
+ *                       result. No fs IO inside; caller writes after.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.historyPath = historyPath;
+exports.readHistory = readHistory;
+exports.writeHistory = writeHistory;
+exports.reconcilePending = reconcilePending;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const types_1 = require("./types");
+const FILE_NAME = '.greeter-history.json';
+/** Absolute path to the greeter history file. Exported for tests. */
+function historyPath(paths) {
+    return node_path_1.default.join(paths.root, FILE_NAME);
+}
+/**
+ * Read the history file. Returns null when:
+ *   - the file does not exist (first launch — caller stays silent), OR
+ *   - the JSON fails to parse (treat as corrupt → start fresh)
+ *
+ * Returns the parsed object on success. Schema version is checked; an
+ * unknown `v` value also returns null so a forward-incompatible file
+ * doesn't crash an older Aiden mid-boot. Real schema migrations get
+ * their own seam in a future slice.
+ */
+async function readHistory(paths, fsImpl = node_fs_1.promises) {
+    try {
+        const raw = await fsImpl.readFile(historyPath(paths), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed?.v !== 1)
+            return null;
+        return {
+            v: 1,
+            firstLaunchAt: typeof parsed.firstLaunchAt === 'string' ? parsed.firstLaunchAt : new Date().toISOString(),
+            lastGreetingAt: typeof parsed.lastGreetingAt === 'string' ? parsed.lastGreetingAt : new Date().toISOString(),
+            lastCwd: typeof parsed.lastCwd === 'string' ? parsed.lastCwd : undefined,
+            offers: Array.isArray(parsed.offers) ? parsed.offers : [],
+            disabled: parsed.disabled === true,
+        };
+    }
+    catch {
+        // ENOENT or parse error — caller decides what null means.
+        return null;
+    }
+}
+/**
+ * Atomically write the history file. tmp + rename so a process crash
+ * mid-write never leaves a half-written JSON the next boot trips on.
+ * Errors are swallowed at the boundary by callers (orchestrator) so
+ * a read-only disk doesn't crash the REPL.
+ */
+async function writeHistory(paths, history, fsImpl = node_fs_1.promises) {
+    await fsImpl.mkdir(paths.root, { recursive: true });
+    const dst = historyPath(paths);
+    const tmp = `${dst}.${process.pid}.tmp`;
+    await fsImpl.writeFile(tmp, JSON.stringify(history, null, 2) + '\n', 'utf8');
+    await fsImpl.rename(tmp, dst);
+}
+function reconcilePending(input) {
+    const { history, installedVersion, now } = input;
+    const ageDays = (offeredAt) => (now.getTime() - Date.parse(offeredAt)) / (1000 * 60 * 60 * 24);
+    const resolved = history.offers.map((o) => {
+        if (o.response)
+            return o; // already settled
+        // update-available-<targetVersion> — accepted if running >= target.
+        if (o.id.startsWith('update-available-')) {
+            const target = o.id.slice('update-available-'.length);
+            if (semverGte(installedVersion, target)) {
+                return { ...o, response: 'accepted' };
+            }
+            if (ageDays(o.offeredAt) > types_1.DECAY_DAYS_UPDATE) {
+                return { ...o, response: 'ignored' };
+            }
+            return o;
+        }
+        // Greeting-only offers (no expectedAction) — close immediately on
+        // next boot. Decay against future offers of the same id happens at
+        // selectOffer time, not here.
+        if (!o.expectedAction) {
+            return { ...o, response: 'ignored' };
+        }
+        // Other environment offers with an expectedAction — decay by env
+        // window. (Slice 1 has none in this category; v4.10 may add.)
+        if (ageDays(o.offeredAt) > types_1.DECAY_DAYS_ENVIRONMENT) {
+            return { ...o, response: 'ignored' };
+        }
+        return o;
+    });
+    return { ...history, offers: resolved };
+}
+/**
+ * Lightweight semver-`>=` for dot-separated numeric versions. Enough
+ * for the v4.X.Y space; does not handle pre-release tags (offer ids
+ * never carry them — they're built from `UpdateStatus.latest` which
+ * the npm registry returns as a clean release version).
+ */
+function semverGte(a, b) {
+    const pa = a.split('.').map((s) => Number(s) || 0);
+    const pb = b.split('.').map((s) => Number(s) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const va = pa[i] ?? 0;
+        const vb = pb[i] ?? 0;
+        if (va > vb)
+            return true;
+        if (va < vb)
+            return false;
+    }
+    return true; // equal
+}

package/dist/cli/v4/greeter/index.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/greeter/index.ts — v4.9.3 SLICE 1a.
+ *
+ * Boot-time greeter orchestrator. One shot per process.
+ *
+ * Behaviour contract (per Phase A/B):
+ *   1. SILENT on first-ever launch (history file missing). Writes a
+ *      fresh v:1 history then returns. The existing renderFirstRunHint
+ *      owns the first-boot moment.
+ *   2. SILENT when history.disabled === true (kill switch).
+ *   3. SILENT when no offer wins (nothing noticeable).
+ *   4. NEVER throws — internal errors are swallowed; a broken greeter
+ *      must not crash the REPL.
+ *   5. Reconciles pending offers from prior boots against current
+ *      scan state BEFORE selecting a new offer; the new offer (if any)
+ *      is appended to history with `response` undefined (pending).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderGreeter = renderGreeter;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const theme_1 = require("../../../core/v4/ui/theme");
+const history_1 = require("./history");
+const scan_1 = require("./scan");
+const selectOffer_1 = require("./selectOffer");
+/**
+ * Run the greeter exactly once. Always resolves; never throws.
+ *
+ * Returns nothing — speech (or silence) is written via display.write.
+ * Tests assert against captured display.write calls, NOT a return
+ * value (Slice 2 lesson: return-value snapshots prove nothing about
+ * what reaches the terminal).
+ */
+async function renderGreeter(opts) {
+    try {
+        await renderGreeterUnsafe(opts);
+    }
+    catch {
+        // Greeter must never crash the REPL. Silent on any internal error.
+    }
+}
+async function renderGreeterUnsafe(opts) {
+    const fsImpl = opts.fsImpl ?? node_fs_1.promises;
+    const now = opts.now ?? new Date();
+    const cwd = opts.cwd ?? process.cwd();
+    // ── First-launch path: write fresh history, stay silent --------------
+    const existing = await (0, history_1.readHistory)(opts.paths, fsImpl);
+    if (existing === null) {
+        const fresh = {
+            v: 1,
+            firstLaunchAt: now.toISOString(),
+            lastGreetingAt: now.toISOString(),
+            lastCwd: cwd,
+            offers: [],
+            disabled: false,
+        };
+        await (0, history_1.writeHistory)(opts.paths, fresh, fsImpl);
+        return; // SILENT — renderFirstRunHint owns this moment
+    }
+    // ── Reconcile pending offers from prior boots ------------------------
+    const scanForReconcile = await (0, scan_1.runScans)({
+        paths: opts.paths,
+        cwd,
+        now,
+        version: opts.version,
+        history: existing,
+        fsImpl,
+    });
+    const reconciled = (0, history_1.reconcilePending)({
+        history: existing,
+        scan: scanForReconcile,
+        installedVersion: opts.version,
+        now,
+    });
+    // ── Pick at most one offer to render this boot ----------------------
+    const distillation = await loadLatestDistillation(opts.paths, fsImpl);
+    const offer = (0, selectOffer_1.selectOffer)({
+        scan: scanForReconcile,
+        history: reconciled,
+        now,
+        paintMuted: (s) => opts.display.paint(s, 'muted'),
+        paintAccent: (s) => theme_1.c.accent(s),
+        openItem: distillation?.openItem,
+        lastDecision: distillation?.lastDecision,
+    });
+    // ── Render (or stay silent) -----------------------------------------
+    if (offer) {
+        // 2-space indent + trailing blank to match firstRunHint layout.
+        opts.display.write('  ' + offer.speech + '\n\n');
+    }
+    // ── Persist updated history -----------------------------------------
+    const updated = {
+        ...reconciled,
+        lastGreetingAt: now.toISOString(),
+        lastCwd: cwd,
+        offers: offer
+            ? [...reconciled.offers, {
+                    id: offer.id,
+                    offeredAt: now.toISOString(),
+                    expectedAction: offer.expectedAction,
+                }]
+            : reconciled.offers,
+    };
+    await (0, history_1.writeHistory)(opts.paths, updated, fsImpl);
+}
+/**
+ * Read the newest distillation file and extract (open_items[0],
+ * decisions[0]). Returns null when no distillations exist or any IO
+ * fails — caller (selectOffer) treats null as "no continuity signal".
+ *
+ * Slice 1 strategy: list distillationsDir, sort by filename desc (the
+ * existing distillation naming convention timestamps the filename so
+ * lexicographic sort is reverse-chronological), read the newest, parse,
+ * extract. No schema dependency on the distillation index — just the
+ * field shape.
+ */
+async function loadLatestDistillation(paths, fsImpl) {
+    try {
+        const dir = node_path_1.default.join(paths.root, 'distillations');
+        const entries = await fsImpl.readdir(dir);
+        if (entries.length === 0)
+            return null;
+        const newest = [...entries].sort().reverse()[0];
+        const raw = await fsImpl.readFile(node_path_1.default.join(dir, newest), 'utf8');
+        const parsed = JSON.parse(raw);
+        const openItem = Array.isArray(parsed.open_items) && typeof parsed.open_items[0] === 'string'
+            ? parsed.open_items[0]
+            : null;
+        const lastDecision = Array.isArray(parsed.decisions) && typeof parsed.decisions[0] === 'string'
+            ? parsed.decisions[0]
+            : null;
+        return { openItem, lastDecision };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cli/v4/greeter/scan.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/greeter/scan.ts — v4.9.3 SLICE 1a.
+ *
+ * Four scanners feed `ScanResult`. None spawn subprocesses, none hit
+ * the network, none scan large files. Total cost target: < 20ms on
+ * a warm cache, < 50ms cold.
+ *
+ *   • scanTimeOfDay      — local hour from `now` (cheapest; no IO)
+ *   • scanCwd            — cwd vs history.lastCwd (no IO)
+ *   • scanLastSessionEnd — mtime of newest distillation file
+ *   • scanUpdate         — reads existing `.update_check.json` cache
+ *                          (populated by core/v4/update/checkUpdate.ts);
+ *                          DOES NOT hit the npm registry itself —
+ *                          consumes the existing background check.
+ *
+ * Git observations are deferred to v4.10 per Phase A decision.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runScans = runScans;
+exports.scanCwd = scanCwd;
+exports.scanLastSessionEnd = scanLastSessionEnd;
+exports.scanUpdate = scanUpdate;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Run all four scanners and aggregate. Pure with respect to its
+ * `now` / `cwd` / `version` parameters — given identical inputs and
+ * identical disk state, produces identical output. The orchestrator
+ * supplies these explicitly so tests can drive them deterministically.
+ */
+async function runScans(input) {
+    const fsImpl = input.fsImpl ?? node_fs_1.promises;
+    const [hoursSinceLastSession, update] = await Promise.all([
+        scanLastSessionEnd(input.paths, input.now, fsImpl),
+        scanUpdate(input.paths, input.version, fsImpl),
+    ]);
+    return {
+        hourOfDay: input.now.getHours(),
+        cwdChanged: scanCwd(input.cwd, input.history),
+        cwd: input.cwd,
+        hoursSinceLastSession,
+        update,
+    };
+}
+// ── Individual scanners — exported for fine-grained unit tests --------
+/** True iff cwd differs from history.lastCwd. False when history has no
+ *  prior cwd (treats first-seen-cwd as "not changed"). */
+function scanCwd(cwd, history) {
+    if (!history.lastCwd)
+        return false;
+    return node_path_1.default.resolve(history.lastCwd) !== node_path_1.default.resolve(cwd);
+}
+/**
+ * Hours since the most recent distillation file (mtime). Returns null
+ * when the distillations directory is missing or empty — caller treats
+ * null as "no prior session to remember".
+ *
+ * Reads directory entries, takes the newest mtime, returns elapsed
+ * hours rounded to nearest int. Hard-caps at 100 entries scanned —
+ * if the user has thousands of distillations the cost stays bounded
+ * (we only care about the newest; sorting is fine on 100 entries).
+ */
+async function scanLastSessionEnd(paths, now, fsImpl = node_fs_1.promises) {
+    const dir = node_path_1.default.join(paths.root, 'distillations');
+    let entries;
+    try {
+        entries = await fsImpl.readdir(dir);
+    }
+    catch {
+        return null; // dir missing → no prior session
+    }
+    if (entries.length === 0)
+        return null;
+    // Cap at 100 — newest-mtime extraction; we only need the max.
+    const scanList = entries.slice(0, 100);
+    let newest = 0;
+    for (const e of scanList) {
+        try {
+            const st = await fsImpl.stat(node_path_1.default.join(dir, e));
+            if (st.mtimeMs > newest)
+                newest = st.mtimeMs;
+        }
+        catch { /* skip unreadable entry */ }
+    }
+    if (newest === 0)
+        return null;
+    const elapsedMs = now.getTime() - newest;
+    return Math.max(0, Math.round(elapsedMs / (1000 * 60 * 60)));
+}
+/**
+ * Read the existing update-status cache (written by the background
+ * checkUpdate flow). Returns the update info when `latest > installed`,
+ * null otherwise. NEVER hits the network — the greeter consumes
+ * whatever the boot-time update-check already cached.
+ *
+ * Cache shape (per core/v4/update/checkUpdate.ts contract):
+ *   { latest: string, lastCheckedAt: string, ... }
+ * We read minimally — just `latest`. If parsing fails, return null
+ * (don't speculate about an update we can't confirm).
+ */
+async function scanUpdate(paths, version, fsImpl = node_fs_1.promises) {
+    const cachePath = node_path_1.default.join(paths.root, '.update_check.json');
+    try {
+        const raw = await fsImpl.readFile(cachePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.latest || typeof parsed.latest !== 'string')
+            return null;
+        if (!isNewer(parsed.latest, version))
+            return null;
+        return { latest: parsed.latest, installed: version };
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns true iff `a > b` under dot-numeric semver. Local copy so
+ *  scan has no dependency on history's identical helper. */
+function isNewer(a, b) {
+    const pa = a.split('.').map((s) => Number(s) || 0);
+    const pb = b.split('.').map((s) => Number(s) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const va = pa[i] ?? 0;
+        const vb = pb[i] ?? 0;
+        if (va > vb)
+            return true;
+        if (va < vb)
+            return false;
+    }
+    return false;
+}

package/dist/cli/v4/greeter/selectOffer.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/greeter/selectOffer.ts — v4.9.3 SLICE 1a.
+ *
+ * Pure-function priority selector. Given the post-reconcile scan +
+ * history + (optional) distillation snippet, returns at most one
+ * `Offer` to render. Returns null when nothing wins (silence rule).
+ *
+ * Tier ordering: 1 > 2 > 3 > 4. Within a tier, the first detected
+ * candidate wins (no scoring beyond the order listed below).
+ *
+ * Decay (applied per tier): an offer whose `id` exists in history.offers
+ * with response === 'ignored' AND whose offeredAt is newer than the
+ * per-tier window is SUPPRESSED. Exception: welcome-back has no decay —
+ * it always fires when the threshold is crossed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectOffer = selectOffer;
+const types_1 = require("./types");
+const templates_1 = require("./templates");
+function selectOffer(input) {
+    // Greeter respects the kill switch absolutely.
+    if (input.history.disabled)
+        return null;
+    const today = isoDateLocal(input.now);
+    // ── Tier 2: continuity ----------------------------------------------
+    // The orchestrator wires open_items + decisions from the most-recent
+    // distillation. Prefer open-item over decision (open work is more
+    // actionable; closed decisions are recap).
+    if (input.openItem && input.openItem.length > 0) {
+        return buildOffer('continuity-open-item', 2, undefined, {
+            openItem: input.openItem,
+        }, input);
+    }
+    if (input.lastDecision && input.lastDecision.length > 0) {
+        return buildOffer('continuity-decision', 2, undefined, {
+            decision: input.lastDecision,
+        }, input);
+    }
+    // welcome-back: always fires when hoursSinceLastSession >= 24, no
+    // decay. (Per dispatch: not really an offer — a continuity signal.)
+    if (input.scan.hoursSinceLastSession !== null &&
+        input.scan.hoursSinceLastSession >= types_1.WELCOME_BACK_THRESHOLD_HOURS) {
+        return buildOffer('welcome-back', 2, undefined, {
+            hoursAgo: input.scan.hoursSinceLastSession,
+        }, input);
+    }
+    // ── Tier 3: environment ---------------------------------------------
+    // Both gated on no-tier-2-fired (handled implicitly by being later in
+    // the function) AND not-in-3-day-decay-window.
+    if (input.scan.hourOfDay >= 18) {
+        const id = `time-of-day-evening-${today}`;
+        if (!isDecayedRecently(id, input.history, types_1.DECAY_DAYS_ENVIRONMENT, input.now)) {
+            return buildOffer('time-of-day-evening', 3, undefined, {}, input, id);
+        }
+    }
+    if (input.scan.cwdChanged) {
+        const id = `cwd-changed-${today}`;
+        if (!isDecayedRecently(id, input.history, types_1.DECAY_DAYS_ENVIRONMENT, input.now)) {
+            return buildOffer('cwd-changed', 3, undefined, {
+                cwd: input.scan.cwd,
+                previousCwd: input.history.lastCwd,
+            }, input, id);
+        }
+    }
+    // ── Tier 4: update --------------------------------------------------
+    if (input.scan.update) {
+        const id = `update-available-${input.scan.update.latest}`;
+        if (!isDecayedRecently(id, input.history, types_1.DECAY_DAYS_UPDATE, input.now)) {
+            return buildOffer('update-available', 4, '/update install', {
+                installed: input.scan.update.installed,
+                latest: input.scan.update.latest,
+            }, input, id);
+        }
+    }
+    return null; // silence rule
+}
+// ── helpers ----------------------------------------------------------
+/**
+ * True iff history contains an `ignored` record for `id` whose age is
+ * within the decay window. Pending offers do NOT suppress — only
+ * ignored ones do (caller has logic for re-firing if the user just
+ * didn't see it).
+ */
+function isDecayedRecently(id, history, days, now) {
+    const cutoffMs = now.getTime() - days * 24 * 60 * 60 * 1000;
+    return history.offers.some((o) => o.id === id &&
+        o.response === 'ignored' &&
+        Date.parse(o.offeredAt) >= cutoffMs);
+}
+/** YYYY-MM-DD in the local timezone (matches the "good evening at 6pm
+ *  local time" intent of the time-of-day scanner). */
+function isoDateLocal(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const dd = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${dd}`;
+}
+function buildOffer(templateId, tier, expectedAction, data, input, customId) {
+    const ctx = {
+        ...data,
+        paintMuted: input.paintMuted,
+        paintAccent: input.paintAccent,
+    };
+    return {
+        id: customId ?? `${templateId}-${isoDateLocal(input.now)}`,
+        templateId,
+        tier,
+        expectedAction,
+        speech: templates_1.TEMPLATES[templateId](ctx),
+    };
+}

package/dist/cli/v4/greeter/templates.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/greeter/templates.ts — v4.9.3 SLICE 1a.
+ *
+ * Pure-function templates per TemplateId. Identical ctx ⇒ identical
+ * string out. No clock peek, no randomness, no env reads inside —
+ * every dynamic value arrives via the TemplateContext bag, including
+ * the two paint helpers.
+ *
+ * Render-site indent (2 spaces) and trailing newline are added by the
+ * orchestrator, NOT by these templates. Templates return one logical
+ * line of speech.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEMPLATES = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * The eight templates. Tier-1 entries (daemon-crashed, hook-auto-disabled)
+ * are forward declarations — Slice 1's selectOffer never picks them. They
+ * exist so v4.10's tier-1 scanners have a typed home to drop offers into.
+ */
+exports.TEMPLATES = {
+    // ── Tier 1 (stubs — scanners deferred to v4.10) ----------------------
+    'daemon-crashed': (ctx) => `Daemon crashed mid-session. ${ctx.paintAccent('/daemon doctor')} for the postmortem.`,
+    'hook-auto-disabled': (ctx) => `A hook auto-disabled after repeated failures. ${ctx.paintAccent('/hooks audit')} for details.`,
+    // ── Tier 2 (continuity) ----------------------------------------------
+    'continuity-open-item': (ctx) => `Last session left this open: ${ctx.paintMuted(`"${ctx.openItem ?? ''}"`)}.`,
+    'continuity-decision': (ctx) => `Last session: ${ctx.paintMuted(ctx.decision ?? '')}.`,
+    'welcome-back': (ctx) => `Welcome back. Last session ended ${ctx.hoursAgo ?? 0}h ago.`,
+    // ── Tier 3 (environment) ---------------------------------------------
+    'time-of-day-evening': (_ctx) => `Good evening.`,
+    'cwd-changed': (ctx) => {
+        // Per user's prose suggestion: avoid "now" (implies temporal change).
+        // Phrasing: "In <basename> this time (last session: <previous>)."
+        const cur = ctx.cwd ? node_path_1.default.basename(ctx.cwd) : '';
+        const prv = ctx.previousCwd ? node_path_1.default.basename(ctx.previousCwd) : '';
+        return `In ${ctx.paintAccent(cur)} this time (last session: ${ctx.paintMuted(prv)}).`;
+    },
+    // ── Tier 4 (update) --------------------------------------------------
+    'update-available': (ctx) => `aiden-runtime ${ctx.installed ?? '?'} → ${ctx.latest ?? '?'} available. ` +
+        `${ctx.paintAccent('/update install')} to ship.`,
+};

package/dist/cli/v4/greeter/types.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/greeter/types.ts — v4.9.3 SLICE 1a.
+ *
+ * Shared types for the boot greeter. Kept in one file so the rest of
+ * the module imports a single typed surface — no circular-import risk
+ * when scan / history / selectOffer / templates reference each other.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WELCOME_BACK_THRESHOLD_HOURS = exports.DECAY_DAYS_ENVIRONMENT = exports.DECAY_DAYS_UPDATE = void 0;
+// ── Decay windows -------------------------------------------------------
+/** Days an "ignored" update offer remains suppressed. */
+exports.DECAY_DAYS_UPDATE = 7;
+/** Days an "ignored" environment offer (cwd, time-of-day) remains suppressed. */
+exports.DECAY_DAYS_ENVIRONMENT = 3;
+/** Hours since last session before welcome-back fires. */
+exports.WELCOME_BACK_THRESHOLD_HOURS = 24;

package/dist/core/v4/aidenAgent.js

@@ -80,6 +80,9 @@ exports.AidenAgent = void 0;
 // AIDEN_TCE=0 to disable. Zero
 // behavioral change when unset. See core/v4/turnState.ts.
 const turnState_1 = require("./turnState");
+// v4.9.4 Slice 1 — tool-call/result protocol invariant + synthetic
+// blocked-result helpers used at the surface + abort fill sites.
+const toolCallInvariant_1 = require("./toolCallInvariant");
 // v4.2 Phase 1 — per-tool result verifier. Same TCE gate as
 // TurnState (default ON, opt-out via AIDEN_TCE=0); classification
 // feeds the recovery controller.
@@ -152,6 +155,7 @@ class AidenAgent {
         this.provider = opts.provider;
         this.toolExecutor = opts.toolExecutor;
         this.tools = opts.tools;
+        this.turnStateFactory = opts.turnStateFactory;
         this.maxTurns = opts.maxTurns ?? DEFAULT_MAX_TURNS;
         this.fallback = opts.fallback;
         this.onToolCall = opts.onToolCall;
@@ -640,7 +644,9 @@ class AidenAgent {
         // When disabled, TurnState.recordToolCall short-circuits with
         // `{kind: 'allow'}` and the entire v4.2 recovery surface stays
         // dormant (zero behavioural change vs v4.1.6).
-        const turnState = new turnState_1.TurnState();
+        // v4.9.4 Slice 1 — honor optional test-seam factory. Production
+        // paths never pass turnStateFactory → falls through to real ctor.
+        const turnState = this.turnStateFactory?.() ?? new turnState_1.TurnState();
         // v4.2 Phase 1 — per-tool verifier registry. Constructed
         // unconditionally (cheap, no side effects) but only used to
         // classify tool outcomes when TCE is enabled; verification args
@@ -850,13 +856,27 @@ class AidenAgent {
             // TurnState internals + pushes a corrective system message,
             // then continues the outer iteration loop from a clean baseline.
             let rollbackDecision = null;
-            for (const call of output.toolCalls) {
+            // v4.9.4 Slice 1 — `.entries()` so the surface + abort fill sites
+            // can slice from `callIndex + 1` to compute the un-dispatched tail.
+            for (const [callIndex, call] of output.toolCalls.entries()) {
                 // v4.6 prep — pre-tool-call cooperative-cancellation check.
                 // If the caller aborted between the model emitting tool calls
                 // and us dispatching them, skip the remaining calls in this
                 // batch. We set finishReason here; the outer-while break is
                 // handled after the for-of exits.
                 if (runOptions.signal?.aborted) {
+                    // v4.9.4 Slice 1 — fill synthetic results so the assistant's
+                    // toolCalls[] is balanced before we break. `call` (the one we
+                    // were ABOUT to dispatch) gets variant='interrupted'; every
+                    // remaining call gets variant='skipped'. Both with reason
+                    // 'cancelled'. CRITICAL: also push turnToolMessages into the
+                    // history NOW — the outer `if (finishReason === 'interrupted')`
+                    // break (post-for-of) exits before reaching the line 1599
+                    // bulk-push. Without this explicit push the synthetic results
+                    // we just collected get discarded.
+                    turnToolMessages.push((0, toolCallInvariant_1.synthesizeBlockedToolResult)(call, 'cancelled', { variant: 'interrupted' }));
+                    (0, toolCallInvariant_1.fillRemainingAsBlocked)(turnToolMessages, output.toolCalls, callIndex + 1, 'cancelled', 'skipped');
+                    messages.push(...turnToolMessages);
                     finishReason = 'interrupted';
                     finalContent = '';
                     break;
@@ -1084,9 +1104,22 @@ class AidenAgent {
                 }
                 else if (recovery.kind === 'surface' && recovery.surfaceCard) {
                     // Stage 3: structured failure. Stop dispatching the rest of
-                    // the batch — anything else is throwing good budget after
-                    // bad. The outer loop reads `surfaceDecision` below and
-                    // exits cleanly.
+                    // the batch — anything else is throwing good budget after bad.
+                    // The outer loop reads `surfaceDecision` below and exits cleanly.
+                    //
+                    // v4.9.4 Slice 1 — BEFORE breaking, fill synthetic blocked-
+                    // tool-result messages for every un-dispatched call in this
+                    // batch (slice from callIndex+1; the current call already had
+                    // its real result pushed at line ~1440 just above). Without
+                    // this fill, the assistant message at line ~1170 carries
+                    // tool_call_ids whose matching tool results never land in
+                    // history. The outer surfaceDecision branch (line ~1573)
+                    // pushes turnToolMessages into `messages` and breaks the
+                    // outer while loop, ending the turn — but the persisted
+                    // history carries the orphans. A resumed conversation (or
+                    // any second provider call in the same turn) then returns
+                    // 400 "No tool output found for function call <id>".
+                    (0, toolCallInvariant_1.fillRemainingAsBlocked)(turnToolMessages, output.toolCalls, callIndex + 1, 'tool_loop_surface');
                     surfaceDecision = recovery;
                     break;
                 }
@@ -1211,6 +1244,15 @@ class AidenAgent {
      * loop sees the same `ProviderCallOutput` regardless.
      */
     async callProvider(messages, tools, runOptions) {
+        // v4.9.4 Slice 1 — tool-call protocol preflight. Every assistant
+        // toolCalls[] entry must have a matching {role:'tool', toolCallId}
+        // BEFORE shipping to any provider. If this throws, a guard in
+        // runTurnLoop is leaking orphan tool_call_ids — find the culprit,
+        // don't catch this. The surface + abort fill sites above already
+        // satisfy the invariant; preflight is the audit-loud safety net
+        // for new guards added later (v4.10 rate-limit / cost-budget /
+        // hook-deny). See core/v4/toolCallInvariant.ts.
+        (0, toolCallInvariant_1.assertNoUnansweredToolCalls)(messages);
         const wantStream = runOptions.stream === true && typeof this.provider.callStream === 'function';
         // v4.1.5 Issue K — fire just before the HTTP request opens, so the
         // display layer can transition the activity verb from local-prep

package/dist/core/v4/toolCallInvariant.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/toolCallInvariant.ts — v4.9.4 SLICE 1.
+ *
+ * The tool-call/tool-result protocol invariant required by the OpenAI /
+ * ChatGPT-Plus / Anthropic / Codex Responses message wire formats:
+ *
+ *   For every assistant message with toolCalls[],
+ *   every tool_call.id MUST be answered by a later `tool` role message
+ *   carrying the same toolCallId, before the next provider request.
+ *
+ * Aiden previously violated this in two known dispatch sites
+ * (aidenAgent runTurnLoop's surfaceDecision break + abort-signal break)
+ * which left orphan tool_call_ids in persisted history. Resuming such
+ * a history triggered 400 from the provider:
+ *
+ *   Provider chatgpt-plus request failed (400):
+ *   No tool output found for function call call_<id>.
+ *
+ * This module exposes three primitives:
+ *   - assertNoUnansweredToolCalls(messages)        — preflight gate
+ *   - synthesizeBlockedToolResult(call, reason)    — fill primitive
+ *   - fillRemainingAsBlocked(buf, calls, idx, ..)  — batch helper
+ *
+ * Plus the OrphanToolCallError class thrown by the preflight.
+ *
+ * Provider-agnostic — each adapter translates Aiden's internal Message
+ * type into its native wire shape. Assertions run against the internal
+ * Message shape itself.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrphanToolCallError = void 0;
+exports.assertNoUnansweredToolCalls = assertNoUnansweredToolCalls;
+exports.synthesizeBlockedToolResult = synthesizeBlockedToolResult;
+exports.fillRemainingAsBlocked = fillRemainingAsBlocked;
+// ── Error class ──────────────────────────────────────────────────────
+/**
+ * Thrown by assertNoUnansweredToolCalls. Subclassed from Error so
+ * triage code can:
+ *
+ *   try { ... } catch (e) {
+ *     if (e instanceof OrphanToolCallError) { ... }
+ *   }
+ *
+ * Production code MUST NOT catch this. If it fires, a guard upstream
+ * is leaking orphan tool_call_ids and we want the failure loud at the
+ * site that introduced the leak.
+ */
+class OrphanToolCallError extends Error {
+    constructor(orphans) {
+        const ids = orphans.map((o) => `${o.toolName}#${o.toolCallId}`).join(', ');
+        super(`Tool-call/result protocol violated: ${orphans.length} unanswered tool_call_id(s) [${ids}]. ` +
+            `Some guard in the dispatch loop emitted an assistant message with tool_calls[] ` +
+            `but did not push a matching {role:'tool', toolCallId} for every id. ` +
+            `Find the guard and add a synthesizeBlockedToolResult() call before its break/continue.`);
+        this.name = 'OrphanToolCallError';
+        this.orphans = orphans;
+    }
+}
+exports.OrphanToolCallError = OrphanToolCallError;
+// ── Preflight assertion ──────────────────────────────────────────────
+/**
+ * Walk the messages once. For each assistant message at index i, scan
+ * messages[i+1..] for `{ role: 'tool', toolCallId }` entries matching
+ * each toolCalls[].id. Orphans (unmatched ids) accumulate; a single
+ * Error is thrown listing all of them so a single debugging session
+ * sees the full damage (better than throw-on-first).
+ *
+ * Pure. No IO, no clock. Cost is O(N*M) where N = total messages and
+ * M = avg tool-calls-per-assistant-turn; trivial for any realistic
+ * session (low hundreds of messages, low tens of tool calls per turn).
+ *
+ * Called from AidenAgent.callProvider() as the single boundary preflight
+ * — every provider adapter receives messages[] through that one funnel.
+ */
+function assertNoUnansweredToolCalls(messages) {
+    // Collect all tool-result ids first (single pass) so we can resolve
+    // each assistant's tool_calls in O(1) against a Set.
+    const answeredIds = new Set();
+    for (const m of messages) {
+        if (m.role === 'tool')
+            answeredIds.add(m.toolCallId);
+    }
+    // Now walk assistants and collect orphans.
+    const orphans = [];
+    for (const m of messages) {
+        if (m.role !== 'assistant' || !m.toolCalls)
+            continue;
+        for (const tc of m.toolCalls) {
+            if (!answeredIds.has(tc.id)) {
+                orphans.push({ toolCallId: tc.id, toolName: tc.name });
+            }
+        }
+    }
+    if (orphans.length > 0)
+        throw new OrphanToolCallError(orphans);
+}
+// ── Synthesis primitives ─────────────────────────────────────────────
+/**
+ * Build a tool-role message whose content is a JSON-stringified failure
+ * object the LLM can parse:
+ *
+ *   { ok: false, blocked: true, reason: <code>, message: <human> }
+ *
+ * Same shape regardless of which guard fired so the LLM sees a uniform
+ * signal. Internal Aiden Message type — providers/v4 adapters handle
+ * wire-shape translation per their native protocol.
+ */
+function synthesizeBlockedToolResult(call, reason, opts = {}) {
+    const variant = opts.variant ?? 'skipped';
+    const humanMessage = variant === 'interrupted'
+        ? `This call was interrupted before execution. (reason: ${reason})`
+        : `This call was skipped because the turn was cancelled. (reason: ${reason})`;
+    // tool_loop_surface variant is always 'skipped' semantically (we
+    // already executed the call before the surface decision fired, so
+    // the SKIPPED calls are the remainder). But we still let the caller
+    // override if a future site has a different shape.
+    const content = JSON.stringify({
+        ok: false,
+        blocked: true,
+        reason,
+        message: humanMessage,
+    });
+    return {
+        role: 'tool',
+        toolCallId: call.id,
+        content,
+    };
+}
+/**
+ * Push synthetic blocked-tool-result messages for every unprocessed
+ * call from `startIdx` (inclusive) onward. Mutates `buf` in place
+ * (matches the existing turnToolMessages accumulator pattern in
+ * aidenAgent.ts; pure-returning would force a spread at every call
+ * site).
+ *
+ * Exported because v4.10 guards (rate-limit, cost-budget, hook-deny)
+ * will want the same shape.
+ */
+function fillRemainingAsBlocked(buf, toolCalls, startIdx, reason, variant = 'skipped') {
+    for (let i = startIdx; i < toolCalls.length; i++) {
+        buf.push(synthesizeBlockedToolResult(toolCalls[i], reason, { variant }));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiden-runtime",
-  "version": "4.9.2",
+  "version": "4.9.4",
   "publishConfig": {
     "access": "public"
   },