aiden-runtime 4.9.2 → 4.9.3

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). |
 
+
+
+
+https://github.com/user-attachments/assets/a76bf4a5-28ca-43b5-8975-5ef0a66ee90d
+
+
+
 <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/package.json

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