@phuetz/code-buddy 2.0.0 → 2.1.0

package/README.fr.md

@@ -0,0 +1,56 @@
+# Code Buddy 2.1 — mémoire, apprentissage et coopération
+
+Code Buddy peut conserver des informations utiles, proposer des leçons, réutiliser des skills et évaluer des variantes de code. Ces mécanismes agissent sur le contexte et les artefacts du système ; ils ne réentraînent pas les poids du modèle.
+
+Pour l’installation et les autres usages, consulter le [README principal](README.md). Cette présentation thématique en français, qui n’est pas une traduction intégrale du README principal, accompagne le [guide technique et ses preuves de source](docs/learning-mechanisms.md).
+
+## Nouveautés 2.1
+
+La version 2.1 ajoute un catalogue explicite de ressources, la recherche RagChat avec citations de pages, l’import de configurations MCP et un pont A2A JSON-RPC limité aux échanges texte documentés. Elle corrige aussi des problèmes de sessions terminal, de mémoire par fournisseur, de diagnostic de configuration et d’interface Cowork. Les [notes de version](docs/RELEASE-NOTES-2.1.0.md) détaillent les limites : pas de reprise automatique des tâches après panne, pas de compatibilité universelle ni de garantie de qualité OCR.
+
+```sh
+npm install -g @phuetz/code-buddy@2.1.0
+buddy --version
+buddy doctor --offline
+```
+
+La CI impose Linux, macOS et Windows avec Node.js 20 et 22. Cowork reste une installation distincte du paquet npm CLI.
+
+## Ce qui reste d’une session à l’autre
+
+La mémoire de projet se trouve notamment dans `.codebuddy/CODEBUDDY_MEMORY.md`, la mémoire utilisateur dans `~/.codebuddy/memory.md`. Leur contenu peut rejoindre le prompt dans les limites et selon la portée du contexte actif. Les leçons constituent une autre couche : une session substantielle peut proposer des candidatures, à examiner avant qu’elles deviennent des leçons actives.
+
+```bash
+buddy lessons candidate list
+buddy lessons list
+buddy lessons search "profil"
+buddy lessons context
+```
+
+Exemple d’usage : conserver une convention de tests du dépôt, puis proposer une leçon après un diagnostic utilisant le mauvais profil. Le rapprochement avec [Manus](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) concerne le contexte externalisé et les observations d’erreurs, pas une copie de son système interne.
+
+## Des procédures réutilisables et contrôlables
+
+Les skills décrivent comment mener une tâche. Le système sait proposer des skills authored et consolider des procédures qui se recouvrent. Il conserve les skills épinglés et refuse les pertes de couverture détectées. Ces contrôles textuels doivent être complétés par une utilisation réelle de la procédure.
+
+`buddy improve skills-list` inspecte les procédures authored. `buddy improve skills-consolidate` prévisualise une consolidation et peut appeler un modèle. Son option `--apply` demande explicitement l’installation et l’archivage ; son contrat diffère de celui des commandes génératives voisines.
+
+## Améliorer les artefacts, puis évaluer les variantes de code
+
+`CODEBUDDY_SELF_IMPROVE=true` conserve le mode proposition. La valeur `auto-apply`, ou l’autorisation explicite prévue par la commande concernée, permet de garder les changements validés. La voie `improve` portant sur la couche apprise et la voie `evolve` portant sur le code doivent être distinguées.
+
+`buddy evolve list` et `buddy evolve review IDENTIFIANT` permettent d’examiner des variantes. Le moteur travaille dans des worktrees et ne fusionne pas automatiquement. Sa référence [DGM de Sakana](https://sakana.ai/dgm/) exprime une inspiration de méthode ; les performances publiées par Sakana ne sont pas des résultats de Code Buddy. Un score hors ligne reste limité au benchmark utilisé.
+
+## Coopérer et explorer plusieurs pistes
+
+Le Council peut répartir des rôles complémentaires, évaluer les réponses et les synthétiser. [Fugu, développé par Sakana AI](https://sakana.ai/fugu-release/) ; son modèle d’orchestration entraîné se distingue du conducteur déterministe actuellement présent dans Code Buddy.
+
+Le moteur de raisonnement propose ToT/MCTS avec des budgets de recherche. `/think status` permet d’inspecter le réglage. Une consigne de raisonnement injectée par un middleware ne prouve pas qu’un arbre de recherche a été exécuté. Les références [ToT](https://arxiv.org/abs/2305.10601), [RethinkMCTS](https://arxiv.org/abs/2409.09584) et [MCTSr](https://arxiv.org/abs/2406.07394) sont explicitées dans le guide ; aucune équivalence de benchmark n’est annoncée.
+
+Une recette de flotte a déjà relié deux hôtes : revue du Buddy Windows par RPC, correction du Buddy Linux, puis oracle indépendant réussi sur les deux systèmes (5/5 chacun). Le relais était assuré manuellement par le pilote. [Déroulement vérifié](docs/reports/2026-09/fleet-two-hosts-learning-example.md).
+
+Le gain se vérifie sur une tâche concrète : référence avant changement, actions capturées, résultat, coût et régressions. La présence du code, son activation et son bénéfice observé sont trois constats différents.
+
+## Portée des preuves
+
+Le guide d’apprentissage a initialement été relu sur le candidat `01fc0dbd3` le 14 septembre 2026. Ce contrôle historique ne constitue pas la validation de la version 2.1.0 ; consulter les [notes de version](docs/RELEASE-NOTES-2.1.0.md) et les contrôles du commit publié pour identifier cette livraison.

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# Code Buddy 2
+# Code Buddy 2.1
 
 **A local-first AI coding agent that can also run as a fleet, a desktop app, and a companion.**
 It reads your repository, writes code, runs commands, and you can watch it work — on your machine,
@@ -12,7 +12,8 @@ at $0 with [Ollama](https://ollama.com) or a ChatGPT subscription.
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-BSL_1.1-feca57.svg?style=flat-square" alt="License: Business Source License 1.1"/></a>
 </p>
 
-[What 2.0 is](#what-20-is) ·
+[Français](README.fr.md) ·
+[What Code Buddy is](#what-code-buddy-is) ·
 [Install](#install) ·
 [First run](#first-run) ·
 [Opt-in](#opt-in) ·
@@ -26,16 +27,34 @@ at $0 with [Ollama](https://ollama.com) or a ChatGPT subscription.
   <sub>A local model reasons on screen, then uses a tool to create a real file. No cloud API bill.</sub>
 </p>
 
+<p>
+  <a href="docs/assets/infographic-code-buddy-2.webp"><img src="docs/assets/infographic-code-buddy-2.webp" width="900" alt="Code Buddy 2 architecture: you, multi-channel interfaces (terminal, Cowork, PWA, chat, voice, App Studio), the agentic runtime (council, fleet, memory, shadow workspace, evolve, knowledge graph), 220+ tools, 64 providers, and the autonomous engineering loop"/></a>
+  <br/>
+  <sub>The big picture: interfaces, the agentic runtime, tools and providers, and the loop that turns an idea into an improvement.</sub>
+</p>
+
 </div>
 
 ---
 
-## What 2.0 is
+## What Code Buddy is
+
+### One minute with Lisa · French presentation
+
+[![Lisa introduces Code Buddy and its installation command](assets/site/lisa/presentation.jpg)](https://youtu.be/2XgFHxBeI8Q)
+
+[Watch on YouTube](https://youtu.be/2XgFHxBeI8Q) · [MP4 alternative](https://www.agile-up.com/code-buddy/lisa/presentation.mp4) · [French subtitles](assets/site/lisa/presentation.fr.srt)
 
-1.x was a terminal coding agent: 64 providers behind one router — cloud, gateway and local
-runtimes — and 220+ tools selected per query. 2.0 keeps all of that unchanged and adds five
-surfaces around it. Every one of them is **opt-in**: with its environment variable unset, behavior
-is the same as 1.8.0. There is no `BREAKING CHANGE` in the 2.0 range.
+Lisa introduces the multi-AI hub, installation and optional perception components. Edited on September 13, 2026 from an existing September 10 master, with a synthetic voice and portrait, illustrative footage and French captions. Illustrations are not execution evidence. Voice and robotics require additional components beyond the npm package.
+
+Code Buddy combines a terminal coding agent with cloud, gateway and local model routing,
+query-selected tools, and the following interfaces. Optional services require their documented
+configuration; enabling a feature does not replace its permission checks.
+
+**New in 2.1:** explicit resource discovery and selection, RagChat search with page citations,
+MCP configuration import, a bounded A2A JSON-RPC bridge, and fixes for terminal sessions,
+configuration diagnostics and Cowork workflows. Read the [release notes](docs/RELEASE-NOTES-2.1.0.md)
+for setup and the limits of each integration.
 
 - **A multi-AI fleet hub.** Peers running `buddy server` observe each other's events and call each
   other's models: one-shot `peer.chat`, multi-turn `peer.chat-session.*`, and `peer.tool.invoke`
@@ -101,6 +120,24 @@ The **Cowork** desktop app is a separate step needing Node.js ≥ 22: `buddy ins
 
 ---
 
+## Use it from Claude Code (plugin, one command)
+
+This repository is also a Claude Code plugin marketplace. It installs a skill
+that teaches Claude Code how to drive `buddy` correctly (headless one-shot,
+provider and model pinning, permission modes, the verify loop) and a read-only
+MCP server exposing Code Buddy's tools:
+
+```bash
+npm i -g @phuetz/code-buddy
+claude plugin marketplace add phuetz/code-buddy
+claude plugin install code-buddy@code-buddy
+# optional, same marketplace: the context filter
+claude plugin install lm-resizer@code-buddy
+```
+
+Codex users: `cp -r .codex/skills/code-buddy ~/.codex/skills/`. Remove with
+`claude plugin uninstall code-buddy@code-buddy`.
+
 ## First run
 
 A real task, start to finish. `buddy loop` plans, edits, runs your verification command, and stops
@@ -136,6 +173,14 @@ names it.
 
 ---
 
+## Memory and learning
+
+Code Buddy keeps project/user memory, retrieves relevant lessons and can propose review-gated lesson candidates after substantial sessions. Authored skills can be inspected, improved and consolidated; code evolution evaluates variants in isolated worktrees. These change external state and inference-time behavior, not model weights.
+
+Start with `buddy lessons candidate list`, `buddy lessons list`, `buddy improve status` and `buddy evolve list`. Council's role-based cooperation and the ToT/MCTS engine are separate mechanisms with their own execution paths and budgets. Inspiration from Manus, Sakana DGM/ShinkaEvolve/Fugu and reasoning papers is not a reproduction claim or a measured productivity gain.
+
+Read [activation conditions, source evidence and limitations](docs/learning-mechanisms.md), or the [French overview](README.fr.md). A [two-host fleet recipe](docs/reports/2026-09/fleet-two-hosts-learning-example.md) has combined a Windows RPC review, a Linux code correction and an independent five-case oracle passing on both hosts. The pilot explicitly relayed messages and files; this was not a Council run.
+
 ## Opt-in
 
 Nothing below is needed to chat with a local model. Defaults stay off.
@@ -144,7 +189,7 @@ Nothing below is needed to chat with a local model. Defaults stay off.
 | --- | --- |
 | `CODEBUDDY_PROVIDER=ollama` | Force the local Ollama path (no API key). |
 | `CODEBUDDY_MAX_CONTEXT` | Override the context window for every consumer, including the Ollama server itself. |
-| `CODEBUDDY_SELF_IMPROVE=true` | Let the agent author its own tools and skills behind empirical gates. It never edits `src/`. |
+| `CODEBUDDY_SELF_IMPROVE=true` | Enable the learned-layer proposal path. `true` stays propose-only; keeping validated changes needs explicit application authorization. The separate `buddy evolve` path can edit code in isolated worktrees. See [contracts](docs/learning-mechanisms.md). |
 | `CODEBUDDY_SHADOW_WORKSPACE` | Validate proposed writes in a ghost worktree *before* touching your files. |
 | `CODEBUDDY_TIMELINE` | Per-turn timeline; `buddy replay` inspects, restores or forks a session. |
 | `CODEBUDDY_INTENTS` | Falsifiable versioned specs, so "done" stays re-provable later. |
@@ -172,13 +217,12 @@ their own gates, listed in [`docs/cb2/README.md`](docs/cb2/README.md) and
 
 Honest limits for a first-time visitor:
 
-- **The npm release can lag this tree.** Check `buddy --version` after installing; the source
-  checkout above is what this page describes.
-- **Only the Linux CI legs are blocking.** macOS and Windows run best-effort — their results are
-  visible but do not gate a green build. Interactive-shell execution on macOS is a known open
-  issue.
-- **The test toolchain needs Node ≥ 20** even though the shipped CLI declares `>= 18`. That
-  affects contributors, not users.
+- **The npm release can lag this tree.** Releases use GitHub Actions trusted publication.
+  Check `buddy --version`, the npm dist-tag and the corresponding Git tag when identifying a build.
+- **CI gates all three operating systems.** Linux, macOS and Windows run Node.js 20 and 22
+  jobs. A local pass or an earlier platform recipe does not replace the candidate’s CI results.
+- **Node ≥ 20 is the real floor**, for the CLI and for the test toolchain alike (`engines` says
+  so since 2.0.0).
 - **Cowork** is a separate install (Node.js ≥ 22, `buddy install-gui`), not part of the three
   commands above.
 - **Film production** needs `ffmpeg`; without a local voice binary, scenes stay silent rather than
@@ -194,6 +238,18 @@ Honest limits for a first-time visitor:
 
 ---
 
+## Test suite
+
+38 088 tests in 2 115 files at `788f0ef23` (measured 2026-09-10 with `npm test`; 26 failures on that run were environment-only: a running local server, `dist/` not built, 20 s timeouts under load). `npm test -- tests/path/to/file.test.ts` to run a slice.
+
+## Part of a toolchain
+
+<p align="center">
+  <a href="docs/assets/infographic-ai-engineering-stack.webp"><img src="docs/assets/infographic-ai-engineering-stack.webp" width="900" alt="The AI engineering stack: Code Explorer understands the repository, lm-resizer protects the context budget, Code Buddy 2 acts with AI agents"/></a>
+</p>
+
+Code Buddy is the agent. Two sibling tools carry the context work around it: [lm-resizer](https://github.com/phuetz/lm-resizer) filters noisy command output before it reaches the model (Rust, Apache-2.0, `npm i @phuetz/lm-resizer`), and Code Explorer pre-indexes a repository into a queryable knowledge graph served over MCP (available as a service on private codebases — [agile-up.com](https://agile-up.com)). Understand, compress, act.
+
 ## License
 
 Business Source License 1.1 — see [LICENSE](LICENSE). Self-host and personal / non-commercial use
@@ -205,7 +261,8 @@ to Apache 2.0 on 2030-08-31. Bundled Python skills stay MIT (see their `SKILL.md
 ## Documentation
 
 - **[Getting started](docs/getting-started.md)** — first run, headless mode, sessions.
-- **[Release notes 2.0.0](docs/RELEASE-NOTES-2.0.0.md)** — what changed since 1.8.0.
+- **[Release notes 2.1.0](docs/RELEASE-NOTES-2.1.0.md)** — current changes and integration limits.
+- [Release notes 2.0.0](docs/RELEASE-NOTES-2.0.0.md) — previous major release.
 - [Install](docs/install.md) — published npm, Docker/VPS, the one-command installer.
 - [Commands](docs/commands.md) · [Features](docs/features.md) · [Security](docs/security.md)
 - [Cowork Desktop](docs/cowork.md) · [Fleet](docs/fleet-guide.md) · [Code Buddy 2 features](docs/cb2/README.md)

package/codebuddy-runtime.json

@@ -2,17 +2,17 @@
   "schemaVersion": 2,
   "corePackage": {
     "name": "@phuetz/code-buddy",
-    "version": "2.0.0",
-    "description": "Open-source AI coding agent for the terminal, desktop, and HTTP. 64 LLM providers (Claude, GPT, Grok, Gemini, Ollama, LM Studio, NVIDIA NIM, …), 30 of them free-tier or local $0, with automatic failover. 220+ tools selected per query, a peer-to-peer fleet, opt-in self-improvement, multi-channel messaging, and a skills system."
+    "version": "2.1.0",
+    "description": "AI coding agent with terminal and HTTP interfaces, optional Cowork desktop integration, multi-provider routing, tools, fleet collaboration and inspectable memory. See release notes for supported integrations and limits."
   },
-  "sourceRevision": "92c913a97b1b9d7a03ab266de5615a472a2ac899",
+  "sourceRevision": "555f73ed991d2060fae76d4bca157f117c16f87c",
   "sourceDirty": null,
   "sourceRevisionOrigin": "env:GITHUB_SHA",
   "distDigest": {
     "algorithm": "sha256",
     "scope": "dist-tree-code-without-maps-v1",
-    "value": "c015f4b49e66354adecbb87b4a31c7aa4ca7691344a281ea5eb3288e8a9e7519",
-    "fileCount": 5041
+    "value": "cc1eee996ab91732307df6008cd527ee0a350e5f13078cc95a95405d8349349b",
+    "fileCount": 5191
   },
   "runtime": {
     "kind": "codebuddy-core",

package/dist/agent/codebuddy-agent.d.ts

@@ -59,6 +59,8 @@ export declare class CodeBuddyAgent extends BaseAgent {
     private _budgetAlertListener?;
     /** Nested host gates currently holding assistant text in a private draft state. */
     private transcriptSnapshotSuspensions;
+    /** Serializes interactive session writes (one per completed TUI turn). */
+    private interactivePersistence;
     /**
      * Create a new CodeBuddyAgent instance
      *
@@ -84,11 +86,16 @@ export declare class CodeBuddyAgent extends BaseAgent {
      * Called by dev workflows to associate tool calls with a RunStore run.
      */
     setRunId(runId: string | undefined): void;
+    private memoryBotId;
     /**
      * Multi-bot channels: scope this agent's per-bot state (persistent memory,
      * lessons) to a bot id. Tool-execution contexts get tagged with it so
      * `remember`/`lessons` write under `~/.codebuddy/bots/<botId>/`.
      */
+    getMemoryScope(): {
+        cwd: string;
+        botId?: string;
+    };
     setChannelBotId(botId: string | undefined): void;
     /** Scope raw tool-result recovery to an embedding host's conversation. */
     setRecoverySessionId(sessionId: string | undefined): void;
@@ -196,6 +203,17 @@ export declare class CodeBuddyAgent extends BaseAgent {
      */
     getSessionCostExtended(): ExtendedCostInfo;
     saveCurrentSession(): Promise<void> | void;
+    /**
+     * Persist the interactive (TUI) conversation after a completed turn.
+     *
+     * The headless path creates its session up front and saves once; the TUI
+     * used to do neither, so interactive turns never reached the session file
+     * and `--resume` had nothing to continue. The first turn with a user message
+     * creates the session (named from that message); every later turn rewrites
+     * the session from the agent's chat history, which is idempotent: no turn is
+     * appended twice. Calls are serialized; `--ephemeral` stores nothing.
+     */
+    persistInteractiveSession(): Promise<void>;
     getCurrentSessionId(): string | null;
     getClient(): CodeBuddyClient;
     setModel(model: string): void;

package/dist/agent/codebuddy-agent.js

@@ -22,9 +22,11 @@ import { MessageQueue } from "./message-queue.js";
 import { CostPredictor } from "../analytics/cost-predictor.js";
 import { BudgetAlertManager } from "../analytics/budget-alerts.js";
 import { initializeMemory, getMemoryManager } from "../memory/persistent-memory.js";
+import { restoreSessionHistory } from '../persistence/session-history.js';
 import { getUserHooksManager } from "../hooks/user-hooks.js";
 import { isFeatureEnabled } from "../config/feature-flags.js";
 import { getActiveRunStore } from "../observability/run-store.js";
+import { recordSkillActivity } from "../skills/skill-usage-store.js";
 import { resetIdentityManager } from "../identity/identity-manager.js";
 import { resetHotReloadManager } from "../config/hot-reload/index.js";
 import { resetConfigWatcher } from "../config/hot-reload/watcher.js";
@@ -85,6 +87,8 @@ export class CodeBuddyAgent extends BaseAgent {
     _budgetAlertListener;
     /** Nested host gates currently holding assistant text in a private draft state. */
     transcriptSnapshotSuspensions = 0;
+    /** Serializes interactive session writes (one per completed TUI turn). */
+    interactivePersistence = Promise.resolve();
     /**
      * Create a new CodeBuddyAgent instance
      *
@@ -158,7 +162,7 @@ export class CodeBuddyAgent extends BaseAgent {
         this.marketplace = this.infrastructure.marketplace;
         this.repairCoordinator = this.infrastructure.repairCoordinator;
         // Initialize Persistent Memory (CLAUDE.md style)
-        initializeMemory().catch(err => {
+        initializeMemory(undefined, initialWorkingDirectory).catch(err => {
             logger.error('Failed to initialize persistent memory', { error: String(err) });
         });
         // Initialize cost prediction and budget alerts
@@ -451,7 +455,7 @@ export class CodeBuddyAgent extends BaseAgent {
             memoryEnabled: this.memoryEnabled,
             morphEditorEnabled: !!this.toolHandler.morphEditor,
             cwd: initialWorkingDirectory,
-        }, this.promptCacheManager, this.memory, this.infrastructure.moltbotHooksManager, getMemoryManager());
+        }, this.promptCacheManager, this.memory, this.infrastructure.moltbotHooksManager, getMemoryManager(undefined, undefined, initialWorkingDirectory));
         // Set up executors for the repair coordinator
         this.repairCoordinator.setExecutors({
             commandExecutor: async (cmd) => {
@@ -596,13 +600,19 @@ Look at the screenshot and find the element matching the user's intent. Output o
     setRunId(runId) {
         this.toolHandler.setRunId(runId);
     }
+    memoryBotId;
     /**
      * Multi-bot channels: scope this agent's per-bot state (persistent memory,
      * lessons) to a bot id. Tool-execution contexts get tagged with it so
      * `remember`/`lessons` write under `~/.codebuddy/bots/<botId>/`.
      */
+    getMemoryScope() {
+        return { cwd: this.toolHandler.getWorkingDirectory(), botId: this.memoryBotId };
+    }
     setChannelBotId(botId) {
+        this.memoryBotId = botId;
         this.toolHandler.setBotId(botId);
+        this.promptBuilder.setPersistentMemory(getMemoryManager(undefined, botId, this.toolHandler.getWorkingDirectory()));
     }
     /** Scope raw tool-result recovery to an embedding host's conversation. */
     setRecoverySessionId(sessionId) {
@@ -1152,6 +1162,7 @@ Look at the screenshot and find the element matching the user's intent. Output o
                     catch {
                         // Skill usage telemetry is best-effort and must not block a turn.
                     }
+                    recordSkillActivity(unifiedSkill.name, 'use', { source: 'match' });
                 }
             }
             else {
@@ -1380,6 +1391,7 @@ Look at the screenshot and find the element matching the user's intent. Output o
         this.contextManager.importConversationState(cloned.contextManagerState);
         this.toolHandler.restoreWorkingDirectory(cloned.workingDirectory);
         this.promptBuilder.updateConfig({ cwd: cloned.workingDirectory });
+        this.promptBuilder.setPersistentMemory(getMemoryManager(undefined, this.memoryBotId, cloned.workingDirectory));
     }
     getCurrentDirectory() {
         return this.toolHandler.bash.getCurrentDirectory();
@@ -1394,16 +1406,12 @@ Look at the screenshot and find the element matching the user's intent. Output o
     setWorkingDirectory(dir) {
         this.toolHandler.setWorkingDirectory(dir);
         this.promptBuilder.updateConfig({ cwd: dir || process.cwd() });
+        this.promptBuilder.setPersistentMemory(getMemoryManager(undefined, this.memoryBotId, dir));
     }
     /** Rehydrate chat and LLM history from a persisted session (headless --resume). */
     hydratePersistedSession(session) {
         const entries = this.sessionStore.convertMessagesToChatEntries(session.messages);
-        const llmMessages = [];
-        for (const entry of entries) {
-            if (entry.type === 'user' || entry.type === 'assistant') {
-                llmMessages.push({ role: entry.type, content: entry.content });
-            }
-        }
+        const llmMessages = restoreSessionHistory(entries);
         this.historyManager.setChatHistory(entries);
         this.historyManager.setMessages(llmMessages);
         if (session.workingDirectory) {
@@ -1508,6 +1516,35 @@ Look at the screenshot and find the element matching the user's intent. Output o
             turns,
         });
     }
+    /**
+     * Persist the interactive (TUI) conversation after a completed turn.
+     *
+     * The headless path creates its session up front and saves once; the TUI
+     * used to do neither, so interactive turns never reached the session file
+     * and `--resume` had nothing to continue. The first turn with a user message
+     * creates the session (named from that message); every later turn rewrites
+     * the session from the agent's chat history, which is idempotent: no turn is
+     * appended twice. Calls are serialized; `--ephemeral` stores nothing.
+     */
+    persistInteractiveSession() {
+        this.interactivePersistence = this.interactivePersistence.then(async () => {
+            const store = this.sessionStore;
+            if (store.isEphemeral())
+                return;
+            const history = this.historyManager.getChatHistory();
+            const firstUser = history.find((entry) => entry.type === 'user');
+            if (!firstUser)
+                return;
+            if (!store.getCurrentSessionId()) {
+                const { generateConversationTitle } = await import('../utils/conversation-title.js');
+                await store.createSession(generateConversationTitle(firstUser.content), this.getCurrentModel());
+            }
+            await this.saveCurrentSession();
+        }).catch((error) => {
+            logger.warn('[session] interactive turn not persisted', { error: error instanceof Error ? error.message : String(error) });
+        });
+        return this.interactivePersistence;
+    }
     getCurrentSessionId() {
         return this.sessionStore.getCurrentSessionId();
     }

package/dist/agent/execution/agent-executor.d.ts

@@ -1,12 +1,3 @@
-/**
- * Agent Executor Module
- *
- * Implements the core agentic loop for processing user messages,
- * both sequential and streaming. Handles tool execution rounds,
- * token counting, cost tracking, and context management.
- *
- * @module agent/execution
- */
 import { CodeBuddyClient, CodeBuddyMessage } from "../../codebuddy/client.js";
 import { ChatEntry, StreamingChunk } from "../types.js";
 import { ToolHandler } from "../tool-handler.js";