aiden-runtime 4.1.1 → 4.1.3

package/dist/providers/v4/registry.js

@@ -232,12 +232,19 @@ exports.PROVIDER_REGISTRY = {
         apiMode: 'chat_completions',
         baseUrl: 'https://api.deepseek.com/v1',
         apiKeyEnvVar: 'DEEPSEEK_API_KEY',
-        description: 'DeepSeek direct API — V3 chat + R1 reasoning.',
+        description: 'DeepSeek direct API — V4 Pro reasoning flagship + legacy aliases.',
         tier: 'paid',
         hasFreeTier: false,
         docsUrl: 'https://api-docs.deepseek.com/',
         supportsToolCalling: true,
-        modelIds: ['deepseek-chat', 'deepseek-reasoner'],
+        // Phase v4.1.2-deepseek: `deepseek-v4-pro` prepended as the new
+        // flagship — becomes the auto-pick default for new users via
+        // pickProbeModel(). Legacy `deepseek-chat` and `deepseek-reasoner`
+        // retained for back-compat (still functional aliases of the V4
+        // flash family per DeepSeek docs; deprecated-but-live). Removal
+        // is its own deprecation slice. Per-call thinking + reasoning
+        // _effort defaults for v4-pro live in providers/v4/modelDefaults.ts.
+        modelIds: ['deepseek-v4-pro', 'deepseek-chat', 'deepseek-reasoner'],
     },
     mistral: {
         id: 'mistral',

package/dist/providers/v4/runtimeResolver.js

@@ -39,6 +39,7 @@ const chatCompletionsAdapter_1 = require("./chatCompletionsAdapter");
 const anthropicAdapter_1 = require("./anthropicAdapter");
 const codexResponsesAdapter_1 = require("./codexResponsesAdapter");
 const ollamaPromptToolsAdapter_1 = require("./ollamaPromptToolsAdapter");
+const modelDefaults_1 = require("./modelDefaults");
 const tokenStore_1 = require("../../core/v4/auth/tokenStore");
 class RuntimeResolver {
     constructor(credentialResolver) {
@@ -61,6 +62,11 @@ class RuntimeResolver {
                     model: model.id,
                     providerName: entry.id,
                     extraHeaders: entry.extraHeaders,
+                    // Phase v4.1.2-deepseek: per-model body defaults (e.g.
+                    // DeepSeek V4-Pro's mandatory thinking + reasoning_effort).
+                    // Undefined for models without registered defaults — adapter
+                    // skips the merge in that case.
+                    defaultExtraBody: (0, modelDefaults_1.getModelDefaults)(entry.id, model.id)?.extraBody,
                 });
             case 'anthropic_messages':
                 if (!credentials.apiKey) {

package/dist/tools/v4/index.js

@@ -21,7 +21,8 @@
  * Status: PHASE 8.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.memoryRemoveTool = exports.memoryReplaceTool = exports.memoryAddTool = exports.processWaitTool = exports.processKillTool = exports.processLogReadTool = exports.processListTool = exports.processSpawnTool = exports.executeCodeTool = exports.shellExecTool = exports.naturalEventsTool = exports.nowPlayingTool = exports.systemInfoTool = exports.makeLookupToolSchema = exports.skillManageTool = exports.skillViewTool = exports.skillsListTool = exports.sessionListTool = exports.sessionSearchTool = exports.browserCloseTool = exports.browserScrollTool = exports.browserFillTool = exports.browserTypeTool = exports.browserClickTool = exports.browserNavigateTool = exports.browserGetUrlTool = exports.browserExtractTool = exports.browserScreenshotTool = exports.fileCopyTool = exports.fileMoveTool = exports.fileDeleteTool = exports.filePatchTool = exports.fileWriteTool = exports.fileListTool = exports.fileReadTool = exports.deepResearchTool = exports.webPageTool = exports.webFetchTool = exports.webSearchTool = exports.makeSubagentFanoutTool = void 0;
+exports.memoryReplaceTool = exports.memoryAddTool = exports.processWaitTool = exports.processKillTool = exports.processLogReadTool = exports.processListTool = exports.processSpawnTool = exports.executeCodeTool = exports.shellExecTool = exports.appInputTool = exports.mediaTransportTool = exports.mediaSessionsTool = exports.clipboardWriteTool = exports.clipboardReadTool = exports.appCloseTool = exports.appLaunchTool = exports.volumeSetTool = exports.mediaKeyTool = exports.osProcessListTool = exports.screenshotTool = exports.naturalEventsTool = exports.nowPlayingTool = exports.systemInfoTool = exports.makeLookupToolSchema = exports.skillManageTool = exports.skillViewTool = exports.skillsListTool = exports.sessionListTool = exports.sessionSearchTool = exports.browserCloseTool = exports.browserScrollTool = exports.browserFillTool = exports.browserTypeTool = exports.browserClickTool = exports.browserNavigateTool = exports.browserGetUrlTool = exports.browserExtractTool = exports.browserScreenshotTool = exports.fileCopyTool = exports.fileMoveTool = exports.fileDeleteTool = exports.filePatchTool = exports.fileWriteTool = exports.fileListTool = exports.fileReadTool = exports.deepResearchTool = exports.webPageTool = exports.webFetchTool = exports.webSearchTool = exports.makeSubagentFanoutTool = void 0;
+exports.sessionSummaryTool = exports.memoryRemoveTool = void 0;
 exports.registerReadOnlyTools = registerReadOnlyTools;
 exports.registerWriteTools = registerWriteTools;
 exports.registerAllTools = registerAllTools;
@@ -49,6 +50,7 @@ const browserScroll_1 = require("./browser/browserScroll");
 const browserClose_1 = require("./browser/browserClose");
 const sessionSearch_1 = require("./sessions/sessionSearch");
 const sessionList_1 = require("./sessions/sessionList");
+const recallSession_1 = require("./sessions/recallSession");
 const skillsList_1 = require("./skills/skillsList");
 const skillView_1 = require("./skills/skillView");
 const skillManage_1 = require("./skills/skillManage");
@@ -56,6 +58,25 @@ const lookupToolSchema_1 = require("./skills/lookupToolSchema");
 const systemInfo_1 = require("./system/systemInfo");
 const nowPlaying_1 = require("./system/nowPlaying");
 const naturalEvents_1 = require("./system/naturalEvents");
+// Phase v4.1.2-followup-3 computer-control bundle.
+const screenshot_1 = require("./system/screenshot");
+const osProcessList_1 = require("./system/osProcessList");
+const mediaKey_1 = require("./system/mediaKey");
+const volumeSet_1 = require("./system/volumeSet");
+const appLaunch_1 = require("./system/appLaunch");
+const appClose_1 = require("./system/appClose");
+const clipboardRead_1 = require("./system/clipboardRead");
+const clipboardWrite_1 = require("./system/clipboardWrite");
+// v4.1.4-media — three-layer media-control bundle.
+// Layer 2 (OS media session): mediaSessions (read) + mediaTransport (write).
+// Layer 3 fallback (mediaKey, blind keystroke) remains unchanged.
+// Layer 1 (semantic API) is per-app and out of this slice.
+const mediaSessions_1 = require("./system/mediaSessions");
+const mediaTransport_1 = require("./system/mediaTransport");
+const appInput_1 = require("./system/appInput");
+// Phase v4.1.2-update — natural-language self-update entry point.
+// Routes through the same shared executeInstall executor as `/update install`.
+const aidenSelfUpdate_1 = require("./system/aidenSelfUpdate");
 const shellExec_1 = require("./terminal/shellExec");
 const executeCode_1 = require("./executeCode");
 const processSpawn_1 = require("./process/processSpawn");
@@ -66,6 +87,7 @@ const processWait_1 = require("./process/processWait");
 const memoryAdd_1 = require("./memory/memoryAdd");
 const memoryReplace_1 = require("./memory/memoryReplace");
 const memoryRemove_1 = require("./memory/memoryRemove");
+const sessionSummary_1 = require("./memory/sessionSummary");
 const subagentFanout_1 = require("./subagent/subagentFanout");
 /**
  * Register every read-only tool into `registry`. The
@@ -94,11 +116,24 @@ function registerReadOnlyTools(registry) {
     registry.register(browserGetUrl_1.browserGetUrlTool);
     registry.register(sessionSearch_1.sessionSearchTool);
     registry.register(sessionList_1.sessionListTool);
+    // Phase v4.1.2-memory-C: recall_session reads SessionDistillation
+    // files written by Phase A+B. Sits alongside session_search — the
+    // two have distinct purposes (FTS5-over-messages vs ranked
+    // distillation summaries); descriptions force the right model
+    // choice.
+    registry.register(recallSession_1.recallSessionTool);
     registry.register(skillsList_1.skillsListTool);
     registry.register(skillView_1.skillViewTool);
     registry.register(systemInfo_1.systemInfoTool);
     registry.register(nowPlaying_1.nowPlayingTool);
     registry.register(naturalEvents_1.naturalEventsTool);
+    // Phase v4.1.2-followup-3 — computer-control read-only tools.
+    registry.register(screenshot_1.screenshotTool);
+    registry.register(osProcessList_1.osProcessListTool);
+    registry.register(clipboardRead_1.clipboardReadTool);
+    // v4.1.4-media — GSMTC session enumeration (read). Pair with
+    // mediaTransport (write) in the write-tools registration below.
+    registry.register(mediaSessions_1.mediaSessionsTool);
     registry.register((0, lookupToolSchema_1.makeLookupToolSchema)(registry));
     // Phase v4.1-subagent — register a stub for subagent_fanout so its
     // schema is visible to the agent loop, the MCP server, and the
@@ -158,9 +193,27 @@ function registerWriteTools(registry) {
     registry.register(memoryAdd_1.memoryAddTool);
     registry.register(memoryReplace_1.memoryReplaceTool);
     registry.register(memoryRemove_1.memoryRemoveTool);
+    // Phase v4.1.2 alive-core: cross-session continuity via /quit auto-summary.
+    registry.register(sessionSummary_1.sessionSummaryTool);
     // Phase 10: skill_manage — mutating, also goes through the approval
     // engine. skills_list / skill_view stay in registerReadOnlyTools.
     registry.register(skillManage_1.skillManageTool);
+    // Phase v4.1.2-update: natural-language entry to the same install
+    // executor that /update install uses. Two-step confirmation gate
+    // (confirm:false → status; confirm:true → install).
+    registry.register(aidenSelfUpdate_1.aidenSelfUpdateTool);
+    // Phase v4.1.2-followup-3 — computer-control mutating tools. All
+    // route through the approval engine like every other write.
+    registry.register(mediaKey_1.mediaKeyTool);
+    registry.register(volumeSet_1.volumeSetTool);
+    registry.register(appLaunch_1.appLaunchTool);
+    registry.register(appClose_1.appCloseTool);
+    registry.register(clipboardWrite_1.clipboardWriteTool);
+    // v4.1.4-media — verified GSMTC transport (replaces mediaKey for
+    // the "name an app, play/pause it" case) + focused-window SendKeys
+    // (escape hatch when GSMTC doesn't enumerate the surface).
+    registry.register(mediaTransport_1.mediaTransportTool);
+    registry.register(appInput_1.appInputTool);
 }
 /** Register every v4 tool. Most callers want this. */
 function registerAllTools(registry) {
@@ -227,6 +280,30 @@ var nowPlaying_2 = require("./system/nowPlaying");
 Object.defineProperty(exports, "nowPlayingTool", { enumerable: true, get: function () { return nowPlaying_2.nowPlayingTool; } });
 var naturalEvents_2 = require("./system/naturalEvents");
 Object.defineProperty(exports, "naturalEventsTool", { enumerable: true, get: function () { return naturalEvents_2.naturalEventsTool; } });
+// Phase v4.1.2-followup-3 computer-control bundle exports.
+var screenshot_2 = require("./system/screenshot");
+Object.defineProperty(exports, "screenshotTool", { enumerable: true, get: function () { return screenshot_2.screenshotTool; } });
+var osProcessList_2 = require("./system/osProcessList");
+Object.defineProperty(exports, "osProcessListTool", { enumerable: true, get: function () { return osProcessList_2.osProcessListTool; } });
+var mediaKey_2 = require("./system/mediaKey");
+Object.defineProperty(exports, "mediaKeyTool", { enumerable: true, get: function () { return mediaKey_2.mediaKeyTool; } });
+var volumeSet_2 = require("./system/volumeSet");
+Object.defineProperty(exports, "volumeSetTool", { enumerable: true, get: function () { return volumeSet_2.volumeSetTool; } });
+var appLaunch_2 = require("./system/appLaunch");
+Object.defineProperty(exports, "appLaunchTool", { enumerable: true, get: function () { return appLaunch_2.appLaunchTool; } });
+var appClose_2 = require("./system/appClose");
+Object.defineProperty(exports, "appCloseTool", { enumerable: true, get: function () { return appClose_2.appCloseTool; } });
+var clipboardRead_2 = require("./system/clipboardRead");
+Object.defineProperty(exports, "clipboardReadTool", { enumerable: true, get: function () { return clipboardRead_2.clipboardReadTool; } });
+var clipboardWrite_2 = require("./system/clipboardWrite");
+Object.defineProperty(exports, "clipboardWriteTool", { enumerable: true, get: function () { return clipboardWrite_2.clipboardWriteTool; } });
+// v4.1.4-media exports — three-layer media-control bundle.
+var mediaSessions_2 = require("./system/mediaSessions");
+Object.defineProperty(exports, "mediaSessionsTool", { enumerable: true, get: function () { return mediaSessions_2.mediaSessionsTool; } });
+var mediaTransport_2 = require("./system/mediaTransport");
+Object.defineProperty(exports, "mediaTransportTool", { enumerable: true, get: function () { return mediaTransport_2.mediaTransportTool; } });
+var appInput_2 = require("./system/appInput");
+Object.defineProperty(exports, "appInputTool", { enumerable: true, get: function () { return appInput_2.appInputTool; } });
 var shellExec_2 = require("./terminal/shellExec");
 Object.defineProperty(exports, "shellExecTool", { enumerable: true, get: function () { return shellExec_2.shellExecTool; } });
 var executeCode_2 = require("./executeCode");
@@ -247,3 +324,5 @@ var memoryReplace_2 = require("./memory/memoryReplace");
 Object.defineProperty(exports, "memoryReplaceTool", { enumerable: true, get: function () { return memoryReplace_2.memoryReplaceTool; } });
 var memoryRemove_2 = require("./memory/memoryRemove");
 Object.defineProperty(exports, "memoryRemoveTool", { enumerable: true, get: function () { return memoryRemove_2.memoryRemoveTool; } });
+var sessionSummary_2 = require("./memory/sessionSummary");
+Object.defineProperty(exports, "sessionSummaryTool", { enumerable: true, get: function () { return sessionSummary_2.sessionSummaryTool; } });

package/dist/tools/v4/memory/memoryRemove.js

@@ -12,14 +12,37 @@
  * Returns `verified: true` only after the post-write read confirms
  * the text is gone from the file.
  *
- * Status: PHASE 9.
+ * Phase v4.1.2-bug-X: user-approved durable facts (anything in
+ * MEMORY.md `## Durable facts`) are protected from autonomous
+ * deletion. A subsequent session on a weak model (llama-3.3 in the
+ * smoke test) called memory_remove on a Phase-D-promoted fact with
+ * reasoning "outdated" — violating Phase D's opt-in trust contract.
+ *
+ * The guard is STRICT: if the requested substring appears ANYWHERE
+ * in the `## Durable facts` body, the call is rejected. Substring
+ * removal operates whole-file, so partial protection would still
+ * nuke the durable copy as side-effect. Hard rejection (vs propose-
+ * and-defer) is honest: model must surface to user; only the user
+ * (editing MEMORY.md directly, or via a future `/forget` slash
+ * command) can revoke durable content.
+ *
+ * Status: PHASE 9 (PHASE v4.1.2-bug-X: section protection).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoryRemoveTool = void 0;
+const memoryGuard_1 = require("../../../moat/memoryGuard");
+/** Section in MEMORY.md that Phase D promotion writes to. */
+const DURABLE_FACTS_HEADER = '## Durable facts';
 exports.memoryRemoveTool = {
     schema: {
         name: 'memory_remove',
-        description: 'Remove an entry from MEMORY.md or USER.md by substring match. Returns verified=true only after the change is confirmed on disk.',
+        description: 'Remove an entry from MEMORY.md or USER.md by substring match. ' +
+            'CANNOT remove entries in MEMORY.md `## Durable facts` — those are ' +
+            'user-approved facts the user explicitly promoted; only the user ' +
+            'can revoke them by editing MEMORY.md directly. If you think a ' +
+            'durable fact is outdated, surface that to the user and ask them ' +
+            'to confirm; do not propose autonomous removal. Returns ' +
+            'verified=true only after the change is confirmed on disk.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -42,6 +65,38 @@ exports.memoryRemoveTool = {
         }
         const file = args.file === 'user' ? 'user' : 'memory';
         const text = String(args.text ?? '');
+        // Phase v4.1.2-bug-X: durable-section protection. Only applies
+        // to MEMORY.md (USER.md has no section structure today). The
+        // check requires snapshot access — when ctx.memory is not
+        // wired (test contexts, future surface refactors), we fall
+        // through to the existing guardedRemove behavior. Real CLI
+        // sessions wire memoryManager, so production paths get the
+        // guard. Documented intentional fall-through.
+        if (file === 'memory' && ctx.memory) {
+            try {
+                const snap = await ctx.memory.loadSnapshot();
+                const memoryMd = snap?.memoryMd ?? '';
+                if (memoryMd && (0, memoryGuard_1.containsInSection)(memoryMd, text, DURABLE_FACTS_HEADER)) {
+                    const preview = text.length > 60
+                        ? `${text.slice(0, 60)}…`
+                        : text;
+                    return {
+                        success: false,
+                        verified: false,
+                        error: `Cannot remove "${preview}" — it's in MEMORY.md ` +
+                            `\`${DURABLE_FACTS_HEADER}\`, which holds user-approved facts. ` +
+                            `Only the user can revoke these. Ask them to confirm removal ` +
+                            `in their next message; do not propose autonomous deletion.`,
+                        file,
+                        protectedSection: DURABLE_FACTS_HEADER,
+                    };
+                }
+            }
+            catch {
+                // Snapshot read failed — fall through to old behavior rather
+                // than block legitimate removals on transient I/O errors.
+            }
+        }
         const r = await ctx.memoryGuard.guardedRemove(file, text);
         return {
             success: r.ok,

package/dist/tools/v4/memory/sessionSummary.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/memory/sessionSummary.ts — Phase v4.1.2 alive-core.
+ *
+ * `session_summary` — append a five-bullet summary of the current
+ * session to MEMORY.md under a `## Recent sessions` section.
+ *
+ * Why this exists: until v4.1.2, "what did we work on last session?"
+ * was unanswerable — MEMORY.md held durable facts but no rolling
+ * conversation log. After this tool runs at /quit (or on demand), the
+ * NEXT session's PromptBuilder injects MEMORY.md as a slot, and the
+ * model can read the summary back as ambient context.
+ *
+ * Design:
+ *
+ *   - The model is responsible for generating the five bullets. It
+ *     already has the full conversation context in its message
+ *     history, so this tool's job is *persistence* — not LLM dispatch.
+ *     This avoids threading the AuxiliaryClient into ToolContext just
+ *     for one tool and keeps the verify-on-disk contract clean.
+ *
+ *   - Section rotation: append the new entry at the top of the
+ *     section (most-recent-first), keep the most recent 10, drop the
+ *     rest. Bound the size so MEMORY.md doesn't grow indefinitely.
+ *
+ *   - Write goes through `MemoryGuard.replaceSection`, which preserves
+ *     the standard `verified: true` contract that
+ *     HonestyEnforcement relies on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionSummaryTool = void 0;
+const RECENT_SESSIONS_HEADER = '## Recent sessions';
+const MAX_RECENT_ENTRIES = 10;
+/**
+ * Render one summary entry: timestamp header + bullets. Trims and
+ * normalises so two adjacent entries don't collide on whitespace.
+ */
+function formatEntry(bullets, when) {
+    const stamp = when.toISOString().replace(/\.\d+Z$/, 'Z'); // second precision
+    const cleaned = bullets
+        .map((b) => b.trim())
+        .filter((b) => b.length > 0)
+        .map((b) => (b.startsWith('-') ? b : `- ${b}`));
+    return [`### ${stamp}`, ...cleaned].join('\n');
+}
+/**
+ * Split an existing Recent-sessions body into entries (each headed by
+ * a `### ` timestamp line). The most-recent entry is index 0.
+ */
+function parseEntries(body) {
+    const trimmed = body.trim();
+    if (!trimmed)
+        return [];
+    // Split on `### ` at line start; first chunk is empty when the body
+    // starts with the marker, which we filter out.
+    const parts = trimmed
+        .split(/^### /m)
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0)
+        .map((p) => `### ${p}`);
+    return parts;
+}
+exports.sessionSummaryTool = {
+    schema: {
+        name: 'session_summary',
+        description: 'Append a five-bullet summary of the current session to MEMORY.md ' +
+            '(under "## Recent sessions"). The next session will see it as ambient ' +
+            'context. Call this at the end of a meaningful session, or right before ' +
+            'the user types /quit. You craft the bullets — be concise and concrete: ' +
+            'what we worked on, decisions made, files changed, problems solved, open items.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bullets: {
+                    type: 'array',
+                    description: 'Exactly five concise bullets (3-15 words each) summarising the session. ' +
+                        'Focus on what will be useful for the next session.',
+                    items: {
+                        type: 'string',
+                        description: 'One bullet. Plain prose; leading "- " optional (added if missing).',
+                    },
+                },
+                trigger: {
+                    type: 'string',
+                    enum: ['manual', 'auto-quit'],
+                    description: 'Diagnostic only — whether the model invoked this directly ' +
+                        '("manual") or the REPL auto-triggered it on /quit ("auto-quit"). ' +
+                        'Defaults to "manual" when omitted.',
+                },
+            },
+            required: ['bullets'],
+        },
+    },
+    category: 'write',
+    mutates: true,
+    toolset: 'memory',
+    async execute(args, ctx) {
+        if (!ctx.memoryGuard) {
+            return { success: false, error: 'memory guard not configured' };
+        }
+        if (!ctx.memory) {
+            return { success: false, error: 'memory manager not configured' };
+        }
+        const rawBullets = Array.isArray(args.bullets) ? args.bullets : [];
+        const bullets = rawBullets
+            .filter((b) => typeof b === 'string')
+            .map((b) => b.trim())
+            .filter((b) => b.length > 0);
+        if (bullets.length === 0) {
+            return {
+                success: false,
+                error: 'session_summary requires at least one non-empty bullet',
+            };
+        }
+        const now = new Date();
+        const newEntry = formatEntry(bullets, now);
+        // Read current MEMORY.md to find existing Recent-sessions body.
+        const snap = await ctx.memory.loadSnapshot();
+        const memoryMd = snap.memoryMd ?? '';
+        // Pull existing section body (if any). The header consumes its
+        // line; the capture group grabs everything until the next h2 or
+        // EOF. Whitespace-only bodies are captured as empty after trim.
+        const headerEscaped = RECENT_SESSIONS_HEADER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        // Note: NO `m` flag — we want `$` to mean end-of-string, not
+        // end-of-line. With `m`, the lookahead `$` matches before every
+        // newline and we capture only the first body line instead of the
+        // whole section.
+        const sectionRe = new RegExp(`${headerEscaped}[^\\n]*\\n([\\s\\S]*?)(?=\\n## |$)`);
+        const match = memoryMd.match(sectionRe);
+        const existingBody = match ? (match[1] ?? '').trim() : '';
+        const existingEntries = parseEntries(existingBody);
+        // Most-recent-first ordering, capped to 10.
+        const combined = [newEntry, ...existingEntries].slice(0, MAX_RECENT_ENTRIES);
+        const newBody = combined.join('\n\n');
+        const result = await ctx.memoryGuard.replaceSection('memory', RECENT_SESSIONS_HEADER, newBody);
+        return {
+            success: result.ok,
+            verified: result.verified,
+            error: result.ok ? undefined : result.reason,
+            entries: combined.length,
+            trigger: args.trigger ?? 'manual',
+            timestamp: now.toISOString(),
+        };
+    },
+};

package/dist/tools/v4/sessions/recallSession.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/sessions/recallSession.ts — Phase v4.1.2-memory-C.
+ *
+ * `recall_session` — return ranked SessionDistillation summaries for
+ * past sessions matching the user's query (or just the most recent N
+ * when no query is supplied).
+ *
+ * Coexists with `session_search`:
+ *   - session_search → FTS5 over message TEXT in SessionStore.
+ *     Returns per-message snippets. Use when the user wants the exact
+ *     words of a past message.
+ *   - recall_session → ranked DISTILLATIONS by TOPIC. Returns
+ *     structured per-session summaries (decisions, open items, files
+ *     touched). Use when the user wants context on what HAPPENED in
+ *     past sessions.
+ *
+ * Index strategy: scan-all. Reads every distillation JSON from
+ * `<paths.root>/distillations/` per query. Expected file count is
+ * <1000 per user; sub-100ms at that scale. When telemetry shows
+ * latency >500ms, the escalation path is direct migration to SQLite
+ * FTS5 — JSON-index intermediate is intentionally skipped.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__testFs = exports.recallSessionTool = void 0;
+exports.getDistillationsDir = getDistillationsDir;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = require("node:fs");
+const distillationStore_1 = require("../../../core/v4/distillationStore");
+const distillationIndex_1 = require("../../../core/v4/distillationIndex");
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 25;
+exports.recallSessionTool = {
+    schema: {
+        name: 'recall_session',
+        description: 'Recall past SESSIONS by topic. Returns ranked summaries — ' +
+            'decisions made, files touched, open items, tool usage — from ' +
+            'previously persisted session distillations. ' +
+            'For the EXACT WORDS of a past message, call `session_search` ' +
+            'instead (FTS5 over message text). For "what happened" / "what ' +
+            'did we work on" / "what was unfinished", use this tool.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Optional keyword filter. Case-insensitive substring match ' +
+                        'across keywords, bullets, decisions, open_items, and ' +
+                        'tool names. Omit to get the most recent sessions.',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Maximum number of matches to return. Default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}.`,
+                },
+                days: {
+                    type: 'number',
+                    description: 'Optional recency window in days. Drops distillations older ' +
+                        'than this before ranking. Omit for no time filter.',
+                },
+                include_full: {
+                    type: 'boolean',
+                    description: 'When true, each match also carries tools_used + keywords ' +
+                        '(useful when the agent needs granular tool history). ' +
+                        'Default false to keep responses compact.',
+                },
+            },
+        },
+    },
+    category: 'read',
+    mutates: false,
+    toolset: 'sessions',
+    async execute(args, ctx) {
+        if (!ctx.paths?.root) {
+            return {
+                success: false,
+                error: 'recall_session requires resolved aiden paths',
+            };
+        }
+        const dir = node_path_1.default.join(ctx.paths.root, 'distillations');
+        // Read everything off disk first. Each failure (malformed JSON,
+        // EACCES on individual files) is skipped silently; the diagnostic
+        // for "files exist but couldn't be read" is the gap between
+        // scanned (id count) and dists.length (parse-success count).
+        let ids;
+        try {
+            ids = await (0, distillationStore_1.listDistillationIds)(dir);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ENOENT') {
+                // No distillations directory yet — first-run case is
+                // success with zero matches, NOT a failure.
+                return {
+                    success: true,
+                    query: typeof args.query === 'string' ? args.query : undefined,
+                    matches: [],
+                    total_found: 0,
+                    scanned: 0,
+                };
+            }
+            return {
+                success: false,
+                error: `Failed to enumerate distillations: ${err.message}`,
+            };
+        }
+        const dists = [];
+        for (const id of ids) {
+            try {
+                const d = await (0, distillationStore_1.readDistillation)(dir, id);
+                if (d)
+                    dists.push(d);
+            }
+            catch {
+                // One bad file shouldn't prevent the agent from seeing the
+                // rest. The user can diagnose via `aiden doctor` (the file
+                // is still on disk).
+            }
+        }
+        const recallQuery = {
+            query: typeof args.query === 'string' ? args.query : undefined,
+            limit: typeof args.limit === 'number' ? args.limit : undefined,
+            days: typeof args.days === 'number' ? args.days : undefined,
+            include_full: args.include_full === true,
+        };
+        const ranked = (0, distillationIndex_1.rankDistillations)(dists, recallQuery);
+        // v4.1.3-repl-polish: mark degraded when any matched session was
+        // distilled with the Phase A+B `partial: true` flag (LLM-timeout
+        // path — deterministic fields present, semantic bullets/decisions
+        // may be empty). The model still gets the full match list; the
+        // trail row renders yellow so the user knows recall completed
+        // against partial data.
+        const partialCount = ranked.matches.filter((m) => m.partial === true).length;
+        const degraded = partialCount > 0;
+        return {
+            success: true,
+            query: recallQuery.query,
+            matches: ranked.matches,
+            total_found: ranked.total_found,
+            // scanned reflects files we attempted to read — useful diagnostic.
+            // If scanned > ranked.total_found AND dists.length < scanned, the
+            // delta is malformed files; the agent can suggest running aiden
+            // doctor to inspect.
+            scanned: ids.length,
+            ...(degraded && {
+                degraded: true,
+                degradedReason: partialCount === 1
+                    ? '1 matched session has partial distillation data'
+                    : `${partialCount} matched sessions have partial distillation data`,
+            }),
+        };
+        // Note re: subsystem health — wire-up happens at the runtime
+        // construction layer (cli/v4/aidenCLI.ts) where the registry is
+        // built. The tool itself stays pure of registry-knowledge for
+        // testability; the registry caller decides whether to wrap the
+        // file-read errors in a tracker.
+    },
+};
+// Expose the directory path for runtime wire-up. Tools that want to
+// register recall_session with the slice3 SubsystemHealthRegistry
+// pass this helper to the tracker so they get health snapshots without
+// hard-coding the path in two places.
+function getDistillationsDir(rootDir) {
+    return node_path_1.default.join(rootDir, 'distillations');
+}
+// Re-export read-only fs surface used by tests under controlled
+// fixtures. Production code never imports from here; the tool calls
+// fs directly.
+exports.__testFs = node_fs_1.promises;

package/dist/tools/v4/sessions/sessionSearch.js

@@ -22,7 +22,11 @@ const MAX_LIMIT = 50;
 exports.sessionSearchTool = {
     schema: {
         name: 'session_search',
-        description: 'Search past conversation sessions by keyword (FTS5 full-text). Returns matching message snippets with the session id and timestamp. Use to recall something the user said in an earlier conversation.',
+        description: 'Search past conversation MESSAGES by keyword (FTS5 full-text). ' +
+            'Returns matching message SNIPPETS with the session id and timestamp. ' +
+            'Use when you need the exact words a past message contained. ' +
+            'For topic-level recall of what happened in past sessions (decisions, ' +
+            'files touched, open items), call `recall_session` instead.',
         inputSchema: {
             type: 'object',
             properties: {