farming-code 2.2.8 → 2.2.12

package/backend/acp-runtime.js

@@ -5,17 +5,18 @@ const { spawn } = require('child_process');
 const { Readable, Writable } = require('stream');
 const { createRequire } = require('module');
 const packageJson = require('../package.json');
+const { AcpCheckpointStore } = require('./acp-checkpoint-store');
 const { AcpSessionState } = require('./acp-session-state');
+const { readCodexHistoryImageData } = require('./codex-transcript');
 const { AcpClientFileSystem, AcpClientTerminalManager } = require('./acp/client-services');
 const { permissionSecurityWarnings } = require('./acp/permission-security');
 const { rejectPatch } = require('./acp/patch-decisions');
+const { getProviderAdapter, listProviderAdapters } = require('./provider-adapters');
+
+const ADAPTER_VERSIONS = Object.freeze(Object.fromEntries(
+  listProviderAdapters().filter(adapter => adapter.acp).map(adapter => [adapter.id, adapter.acp.version]),
+));
 
-const ADAPTER_VERSIONS = Object.freeze({
-  codex: '1.1.2',
-  claude: '0.58.1',
-  opencode: 'native',
-  qoder: 'native',
-});
 const DEFAULT_INITIALIZE_TIMEOUT_MS = 15_000;
 const DEFAULT_SESSION_SETUP_TIMEOUT_MS = 120_000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
@@ -44,67 +45,38 @@ function adapterEntry(packageName) {
   return entry;
 }
 
-function resolveAcpLaunch(provider, options = {}) {
-  const normalized = String(provider || '').trim().toLowerCase();
-  if (normalized === 'codex') {
-    return {
-      command: process.execPath,
-      args: [adapterEntry('@agentclientprotocol/codex-acp')],
-      version: ADAPTER_VERSIONS.codex,
-    };
-  }
-  if (normalized === 'claude') {
+function nodeAdapterLaunch(entry, env = process.env) {
+  const runtimeEnv = env && typeof env === 'object' ? env : process.env;
+  const nodeBin = runtimeEnv.FARMING_NODE_BIN || process.execPath;
+  const ldPath = runtimeEnv.FARMING_NODE_LD || '';
+  const libraryPath = runtimeEnv.FARMING_NODE_LIBRARY_PATH || '';
+  if (ldPath && libraryPath) {
     return {
-      command: process.execPath,
-      args: [adapterEntry('@agentclientprotocol/claude-agent-acp')],
-      version: ADAPTER_VERSIONS.claude,
+      command: ldPath,
+      args: ['--library-path', libraryPath, nodeBin, entry],
     };
   }
-  if (normalized === 'opencode') {
-    return {
-      command: options.executable || 'opencode',
-      args: ['acp', '--cwd', path.resolve(options.cwd || process.cwd())],
-      version: ADAPTER_VERSIONS.opencode,
-    };
+  return { command: nodeBin, args: [entry] };
+}
+
+function resolveAcpLaunch(provider, options = {}) {
+  const adapter = getProviderAdapter(provider);
+  if (!adapter?.acp) throw new Error(`Unsupported ACP provider: ${provider}`);
+  if (adapter.acp.launch) {
+    return { ...adapter.acp.launch(options), version: adapter.acp.version };
   }
-  if (normalized === 'qoder') {
-    return {
-      command: options.executable || 'qodercli',
-      args: ['--acp'],
-      version: ADAPTER_VERSIONS.qoder,
-    };
+  if (adapter.acp.packageName) {
+    const launch = nodeAdapterLaunch(
+      adapterEntry(adapter.acp.packageName),
+      options.runtimeEnv || process.env,
+    );
+    return { ...launch, version: adapter.acp.version };
   }
   throw new Error(`Unsupported ACP provider: ${provider}`);
 }
 
 function codexAcpEnvironment(options = {}) {
-  const env = { ...(options.env || process.env) };
-  let config = {};
-  if (env.CODEX_CONFIG) {
-    try {
-      const parsed = JSON.parse(env.CODEX_CONFIG);
-      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) config = parsed;
-    } catch {
-      // A selected Farming profile below replaces an invalid adapter config.
-    }
-  }
-
-  if (options.model && options.model !== 'config') config.model = options.model;
-  if (options.reasoningEffort && options.reasoningEffort !== 'config') {
-    config.model_reasoning_effort = options.reasoningEffort;
-  }
-  if (options.serviceTier && !['config', 'default'].includes(options.serviceTier)) {
-    config.service_tier = options.serviceTier;
-  }
-  if (Object.keys(config).length > 0) env.CODEX_CONFIG = JSON.stringify(config);
-
-  const initialMode = {
-    ask: 'read-only',
-    approve: 'agent',
-    full: 'agent-full-access',
-  }[options.approvalMode];
-  if (initialMode) env.INITIAL_AGENT_MODE = initialMode;
-  return env;
+  return getProviderAdapter('codex').prepareAcpEnvironment(options);
 }
 
 function selectedPermission(option) {
@@ -226,6 +198,10 @@ function interactiveRuntimeState(binding, fallback = '') {
   return binding.sessionId ? 'idle' : 'connecting';
 }
 
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
 class AcpRuntime extends EventEmitter {
   constructor(options = {}) {
     super();
@@ -240,6 +216,8 @@ class AcpRuntime extends EventEmitter {
     this.historyReplayMinWaitMs = options.historyReplayMinWaitMs ?? DEFAULT_HISTORY_REPLAY_MIN_WAIT_MS;
     this.historyReplayQuietMs = options.historyReplayQuietMs ?? DEFAULT_HISTORY_REPLAY_QUIET_MS;
     this.historyReplayMaxWaitMs = options.historyReplayMaxWaitMs ?? DEFAULT_HISTORY_REPLAY_MAX_WAIT_MS;
+    this.checkpointStore = options.checkpointStore
+      || (options.configDir ? new AcpCheckpointStore(options.configDir, options.checkpointOptions) : null);
     this.bindings = new Map();
     this.permissionSequence = 0;
     this.elicitationSequence = 0;
@@ -256,8 +234,9 @@ class AcpRuntime extends EventEmitter {
     const binding = {
       agentId,
       provider,
+      providerHomeId: String(options.providerHomeId || 'default'),
       cwd: path.resolve(options.cwd || process.cwd()),
-      env: provider === 'codex' ? codexAcpEnvironment(options) : (options.env || process.env),
+      env: (getProviderAdapter(provider)?.prepareAcpEnvironment || (value => value.env || process.env))(options),
       launch,
       restartOptions: { ...options, agentId, provider },
       approvalMode: options.approvalMode || 'approve',
@@ -278,9 +257,11 @@ class AcpRuntime extends EventEmitter {
       subagentStates: new Map(),
       interactionOrigins: new Map(),
       promptActive: false,
+      historyReplayActive: false,
       sessionState: null,
       authTerminal: null,
       patchDecisions: new Map(),
+      checkpointProof: null,
       stderr: '',
       updatedAt: new Date().toISOString(),
     };
@@ -337,25 +318,81 @@ class AcpRuntime extends EventEmitter {
       let historyMode = 'new';
       if (requestedSessionId) {
         const capabilities = binding.initializeResponse.agentCapabilities || {};
-        if (options.historyMode !== 'resume' && capabilities.loadSession) {
+        let opened = false;
+        let restoredCheckpointState = null;
+        let restoredCheckpoint = null;
+        let saved = null;
+        if (options.historyMode === 'checkpoint' && this.checkpointStore) {
+          saved = await this.checkpointStore.load(
+            this.checkpointIdentity(binding, requestedSessionId),
+            { allowDirty: true },
+          );
+          restoredCheckpoint = this.restoreBindingCheckpoint(binding, saved?.state, {
+            sessionId: requestedSessionId,
+          });
+          restoredCheckpointState = restoredCheckpoint?.sessionState || null;
+        }
+        if (capabilities.sessionCapabilities?.resume && restoredCheckpoint) {
+          const providerStateMatches = restoredCheckpoint?.complete === true && saved?.exact === true
+            ? await this.checkpointMatchesProviderSession(connection, capabilities, sessionRequest, saved)
+            : false;
+          if (providerStateMatches) {
+            binding.sessionId = requestedSessionId;
+            binding.sessionState = restoredCheckpointState;
+            binding.subagentStates = restoredCheckpoint.subagentStates;
+            binding.patchDecisions = restoredCheckpoint.patchDecisions;
+            binding.checkpointProof = restoredCheckpoint.providerProof;
+            try {
+              sessionResponse = await withTimeout(
+                connection.resumeSession(sessionRequest),
+                this.sessionSetupTimeoutMs,
+                'ACP session/resume'
+              );
+              historyMode = 'checkpoint';
+              opened = true;
+            } catch (error) {
+              if (!capabilities.loadSession) throw error;
+              console.warn(`ACP checkpoint resume failed for ${provider}; replaying history:`, error && (error.message || error));
+            }
+          }
+        }
+        if (!opened && options.historyMode !== 'resume' && capabilities.loadSession) {
+          const replayRevisionBase = Math.max(revisionBase, Number(restoredCheckpointState?.revision || 0));
           binding.sessionId = requestedSessionId;
           binding.sessionState = new AcpSessionState({
             provider,
             sessionId: requestedSessionId,
             cwd: binding.cwd,
             maxUpdates: this.maxUpdates,
-            revisionBase,
-            resetBeforeRevision: revisionBase,
+            revisionBase: replayRevisionBase,
+            resetBeforeRevision: replayRevisionBase,
           });
-          sessionResponse = await withTimeout(
-            connection.loadSession(sessionRequest),
-            this.sessionSetupTimeoutMs,
-            'ACP session/load'
-          );
-          if (provider === 'qoder') await this.waitForHistoryReplay(binding);
+          binding.historyReplayActive = true;
+          try {
+            sessionResponse = await withTimeout(
+              connection.loadSession(sessionRequest),
+              this.sessionSetupTimeoutMs,
+              'ACP session/load'
+            );
+            if (provider === 'qoder') await this.waitForHistoryReplay(binding);
+          } finally {
+            binding.historyReplayActive = false;
+          }
           binding.sessionState.finishHistoryReplay();
+          if (provider === 'codex' && binding.sessionState.hasCodexHistoryImageReferences()) {
+            let imageDataByPath = new Map();
+            try {
+              imageDataByPath = await readCodexHistoryImageData(requestedSessionId, {
+                codexHome: binding.env.CODEX_HOME,
+              });
+            } catch {
+              // Local history images can still be restored from their adapter paths.
+            }
+            await binding.sessionState.hydrateCodexHistoryAttachments({ imageDataByPath });
+          }
           historyMode = 'load';
-        } else if (capabilities.sessionCapabilities?.resume) {
+          opened = true;
+        } else if (!opened && capabilities.sessionCapabilities?.resume) {
           binding.sessionId = requestedSessionId;
           binding.sessionState = new AcpSessionState({
             provider,
@@ -370,8 +407,9 @@ class AcpRuntime extends EventEmitter {
             'ACP session/resume'
           );
           historyMode = 'resume';
+          opened = true;
         } else {
-          throw new Error(`${provider} ACP Agent cannot load or resume session ${requestedSessionId}`);
+          if (!opened) throw new Error(`${provider} ACP Agent cannot load or resume session ${requestedSessionId}`);
         }
       } else {
         sessionResponse = await withTimeout(
@@ -399,6 +437,7 @@ class AcpRuntime extends EventEmitter {
       }
       binding.state = 'idle';
       binding.updatedAt = new Date().toISOString();
+      this.scheduleCheckpoint(binding, { exact: true });
       this.emitRuntime(binding);
       this.emitSession(binding);
       return {
@@ -417,6 +456,130 @@ class AcpRuntime extends EventEmitter {
     }
   }
 
+  checkpointIdentity(binding, sessionId = binding?.sessionId) {
+    if (!binding || !sessionId) return null;
+    return {
+      provider: binding.provider,
+      providerHomeId: binding.providerHomeId || 'default',
+      sessionId,
+      cwd: binding.cwd,
+    };
+  }
+
+  scheduleCheckpoint(binding, _options = {}) {
+    const identity = this.checkpointIdentity(binding);
+    if (!this.checkpointStore || !identity || !binding.sessionState) return;
+    // ACP currently has no conditional resume or provider-owned revision
+    // token. A timestamp/list check has a TOCTOU window, so runtime snapshots
+    // remain dirty and are used only as revision/reset fences. Full history
+    // load is the authoritative recovery path until such a proof is available.
+    this.checkpointStore.schedule(identity, this.bindingCheckpoint(binding), { exact: false });
+  }
+
+  async markCheckpointDirty(binding) {
+    const identity = this.checkpointIdentity(binding);
+    if (!this.checkpointStore || !identity) return;
+    await this.checkpointStore.markDirty(identity);
+  }
+
+  async writeCheckpoint(binding, _options = {}) {
+    const identity = this.checkpointIdentity(binding);
+    if (!this.checkpointStore || !identity || !binding.sessionState) return;
+    await this.checkpointStore.write(identity, this.bindingCheckpoint(binding), { exact: false });
+  }
+
+  bindingCheckpoint(binding) {
+    return {
+      exportCheckpoint: () => ({
+        version: 2,
+        complete: false,
+        sessionState: binding.sessionState?.exportCheckpoint() || null,
+        subagentStates: [...binding.subagentStates.entries()].map(([sessionId, state]) => ({
+          sessionId,
+          state: state.exportCheckpoint(),
+        })),
+        patchDecisions: [...binding.patchDecisions.entries()],
+        providerProof: binding.checkpointProof ? clone(binding.checkpointProof) : null,
+      }),
+    };
+  }
+
+  restoreBindingCheckpoint(binding, checkpoint, options = {}) {
+    if (!checkpoint) return null;
+    const mainCheckpoint = checkpoint.version === 2
+      ? checkpoint.sessionState
+      : checkpoint;
+    const sessionState = AcpSessionState.fromCheckpoint(mainCheckpoint, {
+      provider: binding.provider,
+      sessionId: options.sessionId || binding.sessionId,
+      cwd: binding.cwd,
+      maxUpdates: this.maxUpdates,
+    });
+    if (!sessionState) return null;
+    const subagentStates = new Map();
+    if (checkpoint.version === 2 && Array.isArray(checkpoint.subagentStates)) {
+      for (const item of checkpoint.subagentStates.slice(0, 32)) {
+        const sessionId = String(item?.sessionId || '');
+        if (!sessionId) continue;
+        const state = AcpSessionState.fromCheckpoint(item?.state, {
+          provider: binding.provider,
+          sessionId,
+          cwd: binding.cwd,
+          maxUpdates: this.maxUpdates,
+        });
+        if (state) subagentStates.set(sessionId, state);
+      }
+    }
+    const patchDecisions = new Map();
+    if (checkpoint.version === 2 && Array.isArray(checkpoint.patchDecisions)) {
+      for (const item of checkpoint.patchDecisions) {
+        if (!Array.isArray(item) || item.length !== 2) continue;
+        const key = String(item[0] || '');
+        const decision = String(item[1] || '');
+        if (key && ['kept', 'reverted'].includes(decision)) patchDecisions.set(key, decision);
+      }
+    }
+    return {
+      sessionState,
+      subagentStates,
+      patchDecisions,
+      providerProof: checkpoint.version === 2 ? clone(checkpoint.providerProof) : null,
+      complete: checkpoint.version === 2 && checkpoint.complete === true,
+    };
+  }
+
+  async checkpointMatchesProviderSession(connection, capabilities, request, saved) {
+    const proof = saved?.state?.providerProof;
+    if (
+      !capabilities?.sessionCapabilities?.list
+      || !proof
+      || typeof proof.token !== 'string'
+      || !proof.token
+    ) return false;
+    let cursor = '';
+    try {
+      for (let page = 0; page < 10; page += 1) {
+        const response = await withTimeout(connection.listSessions({
+          cwd: request.cwd,
+          ...(cursor ? { cursor } : {}),
+        }), this.requestTimeoutMs, 'ACP session/list checkpoint validation');
+        const session = (response?.sessions || []).find(item => item?.sessionId === request.sessionId);
+        if (session) {
+          const sessionCwd = path.resolve(String(session.cwd || ''));
+          const token = String(session?._meta?.checkpointRevision || session?.checkpointRevision || '');
+          return sessionCwd === path.resolve(request.cwd)
+            && token === proof.token
+            && path.resolve(String(proof.cwd || '')) === path.resolve(request.cwd);
+        }
+        cursor = String(response?.nextCursor || '');
+        if (!cursor) return false;
+      }
+    } catch (error) {
+      console.warn('Failed to validate ACP checkpoint against provider session metadata:', error && (error.message || error));
+    }
+    return false;
+  }
+
   async officialConnection(handlers, child) {
     const sdk = await loadAcpSdk();
     const stream = sdk.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
@@ -473,7 +636,14 @@ class AcpRuntime extends EventEmitter {
             if (parentTool) binding.sessionState.touchEntry(parentTool);
           }
           binding.updatedAt = new Date().toISOString();
-          this.emitSession(binding);
+          if (isPrimarySession && !binding.historyReplayActive && !binding.promptActive) {
+            this.scheduleCheckpoint(binding, { exact: true });
+          }
+          // A loaded history can contain hundreds of ordered updates. Applying
+          // them one by one is necessary, but broadcasting every replay step
+          // makes clients repeatedly abort/refetch and remount rich content.
+          // prepareAgent emits one complete snapshot after the replay settles.
+          if (!binding.historyReplayActive) this.emitSession(binding);
         }
       },
       requestPermission: request => this.requestPermission(binding, request),
@@ -588,6 +758,7 @@ class AcpRuntime extends EventEmitter {
     const binding = this.requireBinding(agentId);
     if (!['idle', 'error'].includes(binding.state)) throw new Error(`ACP Agent is not ready (${binding.state})`);
     const content = Array.isArray(prompt) ? prompt : [{ type: 'text', text: String(prompt || '') }];
+    await this.markCheckpointDirty(binding);
     binding.sessionState.beginPrompt(content);
     binding.promptActive = true;
     binding.state = 'working';
@@ -602,6 +773,7 @@ class AcpRuntime extends EventEmitter {
       binding.promptActive = false;
       binding.state = 'idle';
       binding.updatedAt = new Date().toISOString();
+      this.scheduleCheckpoint(binding, { exact: true });
       this.emitSession(binding);
       this.emitRuntime(binding);
       return { sessionId: binding.sessionId, stopReason: binding.stopReason };
@@ -616,6 +788,7 @@ class AcpRuntime extends EventEmitter {
       binding.promptActive = false;
       binding.state = 'error';
       binding.error = runtimeError.message;
+      this.scheduleCheckpoint(binding, { exact: true });
       this.emitSession(binding);
       this.emitRuntime(binding);
       throw runtimeError;
@@ -808,7 +981,11 @@ class AcpRuntime extends EventEmitter {
       approvalMode: binding.approvalMode,
       ...(binding.sessionId ? { sessionId: binding.sessionId } : {}),
       ...(revisionBase > 0 ? { revisionBase } : {}),
+      ...(binding.sessionId ? { historyMode: 'checkpoint' } : {}),
     };
+    if (binding.sessionState && !binding.promptActive) {
+      await this.writeCheckpoint(binding, { exact: true });
+    }
     this.unregisterAgent(agentId);
     return this.prepareAgent(options);
   }
@@ -862,12 +1039,19 @@ class AcpRuntime extends EventEmitter {
     );
     binding.sessionState.currentModeId = String(modeId || '');
     if (binding.modes) binding.modes = { ...binding.modes, currentModeId: binding.sessionState.currentModeId };
+    this.scheduleCheckpoint(binding, { exact: true });
     this.emitSession(binding);
     return { sessionId: binding.sessionId, modeId: binding.sessionState.currentModeId };
   }
 
   async setSessionConfigOption(agentId, configId, value) {
     const binding = this.requireBinding(agentId);
+    return this.enqueueSessionConfigMutation(binding, () => (
+      this.setSessionConfigOptionNow(binding, configId, value)
+    ));
+  }
+
+  async setSessionConfigOptionNow(binding, configId, value) {
     const option = binding.configOptions?.find(candidate => candidate.id === String(configId || ''));
     if (
       binding.provider === 'codex'
@@ -885,7 +1069,7 @@ class AcpRuntime extends EventEmitter {
       ));
       if (typeof reasoning?.currentValue === 'string' && reasoning.currentValue) {
         await this.refreshCodexSessionModel(binding, String(value ?? ''), reasoning.currentValue);
-        return this.applySessionConfigOption(binding, configId, value);
+        return this.applySessionConfigOption(binding, configId, value, { force: true });
       }
       this.emitSession(binding);
       return { sessionId: binding.sessionId, configOptions: binding.configOptions };
@@ -895,6 +1079,12 @@ class AcpRuntime extends EventEmitter {
 
   async setSessionConfigOptions(agentId, changes) {
     const binding = this.requireBinding(agentId);
+    return this.enqueueSessionConfigMutation(binding, () => (
+      this.setSessionConfigOptionsNow(binding, changes)
+    ));
+  }
+
+  async setSessionConfigOptionsNow(binding, changes) {
     const normalized = Array.isArray(changes)
       ? changes.filter(change => change && typeof change.configId === 'string' && Object.prototype.hasOwnProperty.call(change, 'value'))
       : [];
@@ -926,17 +1116,28 @@ class AcpRuntime extends EventEmitter {
         String(modelChange.value ?? ''),
         String(currentReasoning?.currentValue || reasoningChange.value || '')
       );
-      response = await this.applySessionConfigOption(binding, modelChange.configId, modelChange.value);
+      response = await this.applySessionConfigOption(binding, modelChange.configId, modelChange.value, { force: true });
       handled.add(modelChange);
       handled.add(reasoningChange);
     }
     for (const change of normalized) {
       if (handled.has(change)) continue;
-      response = await this.setSessionConfigOption(agentId, change.configId, change.value);
+      response = await this.setSessionConfigOptionNow(binding, change.configId, change.value);
     }
     return response;
   }
 
+  async enqueueSessionConfigMutation(binding, operation) {
+    const previous = binding.configMutationTail || Promise.resolve();
+    const pending = previous.catch(() => {}).then(operation);
+    binding.configMutationTail = pending;
+    try {
+      return await pending;
+    } finally {
+      if (binding.configMutationTail === pending) binding.configMutationTail = null;
+    }
+  }
+
   async refreshCodexSessionModel(binding, model, effort) {
     await withTimeout(
       binding.connection.request(CODEX_SET_SESSION_MODEL_METHOD, {
@@ -949,16 +1150,31 @@ class AcpRuntime extends EventEmitter {
   }
 
   async applySessionConfigOption(binding, configId, value, options = {}) {
+    const normalizedConfigId = String(configId || '');
+    const currentOption = binding.configOptions?.find(candidate => candidate.id === normalizedConfigId);
+    if (options.force !== true && currentOption?.currentValue === value) {
+      if (options.emit !== false) this.emitSession(binding);
+      return { sessionId: binding.sessionId, configOptions: binding.configOptions };
+    }
     const request = typeof value === 'boolean'
-      ? { sessionId: binding.sessionId, configId: String(configId || ''), type: 'boolean', value }
-      : { sessionId: binding.sessionId, configId: String(configId || ''), value: String(value ?? '') };
-    const response = await withTimeout(
-      binding.connection.setSessionConfigOption(request),
-      this.requestTimeoutMs,
-      'ACP session/set_config_option'
-    );
-    binding.configOptions = response?.configOptions || binding.configOptions;
+      ? { sessionId: binding.sessionId, configId: normalizedConfigId, type: 'boolean', value }
+      : { sessionId: binding.sessionId, configId: normalizedConfigId, value: String(value ?? '') };
+    let response;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      response = await withTimeout(
+        binding.connection.setSessionConfigOption(request),
+        this.requestTimeoutMs,
+        'ACP session/set_config_option'
+      );
+      binding.configOptions = response?.configOptions || binding.configOptions;
+      const confirmed = binding.configOptions?.find(candidate => candidate.id === normalizedConfigId);
+      if (confirmed?.currentValue === request.value) break;
+      if (attempt === 1) {
+        throw new Error(`ACP Agent did not confirm config option ${normalizedConfigId}`);
+      }
+    }
     binding.sessionState.configOptions = JSON.parse(JSON.stringify(binding.configOptions));
+    this.scheduleCheckpoint(binding, { exact: true });
     if (options.emit !== false) this.emitSession(binding);
     return { sessionId: binding.sessionId, configOptions: binding.configOptions };
   }
@@ -1070,6 +1286,7 @@ class AcpRuntime extends EventEmitter {
     };
     binding.sessionState?.touchEntry(entry);
     binding.updatedAt = new Date().toISOString();
+    this.scheduleCheckpoint(binding, { exact: true });
     this.emitSession(binding);
     return { ...result, toolCallId: String(toolCallId || '') };
   }
@@ -1202,6 +1419,7 @@ class AcpRuntime extends EventEmitter {
   unregisterAgent(agentId) {
     const binding = this.bindings.get(agentId);
     if (!binding) return;
+    if (binding.sessionState && !binding.promptActive) this.scheduleCheckpoint(binding, { exact: true });
     this.bindings.delete(agentId);
     for (const resolve of binding.permissionResolvers.values()) resolve({ outcome: { outcome: 'cancelled' } });
     for (const resolve of binding.elicitationResolvers.values()) resolve({ action: 'cancel' });
@@ -1221,8 +1439,13 @@ class AcpRuntime extends EventEmitter {
     if (binding.child && !binding.child.killed) binding.child.kill('SIGTERM');
   }
 
-  dispose() {
+  async dispose() {
+    for (const binding of this.bindings.values()) {
+      if (binding.sessionState && !binding.promptActive) this.scheduleCheckpoint(binding, { exact: true });
+    }
+    if (this.checkpointStore) await this.checkpointStore.flush();
     for (const agentId of [...this.bindings.keys()]) this.unregisterAgent(agentId);
+    if (this.checkpointStore) await this.checkpointStore.dispose();
   }
 }