farming-code 2.2.19 → 2.2.22

package/backend/farming-session-store.js

@@ -1,11 +1,41 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
+const { isDeepStrictEqual } = require('util');
 const { legacyRuntimeMetadata } = require('./agent-runtime-binding');
+const { lifecycleJournal } = require('./agent-lifecycle-journal');
 const storageLayout = require('./storage-layout');
 
-const SESSION_ID_PREFIX = 'fsess';
+const AGENT_RECORD_ID_PREFIX = 'agent';
+const AGENT_RECORD_VERSION = 1;
+const AGENT_STATE_VERSION = 1;
 const MAX_MAIN_PAGE_SESSION_KEYS = 50;
+const AGENT_STATE_FIELDS = [
+  'acpState',
+  'acpError',
+  'acpStopReason',
+  'acpPendingPermission',
+  'acpPendingPermissions',
+  'acpPendingElicitation',
+  'acpPendingElicitations',
+  'acpActiveElicitations',
+  'acpSessionUpdatedAt',
+  'acpSessionRevision',
+  'jsonCliState',
+  'jsonCliError',
+  'jsonCliTranscriptUpdatedAt',
+  'attentionSeq',
+  'readAttentionSeq',
+  'attentionUpdatedAt',
+  'readAttentionAt',
+  'attentionReason',
+  'attentionOutputEpoch',
+  'attentionOutputSeq',
+  'readOutputEpoch',
+  'readOutputSeq',
+  'unread',
+];
+const AGENT_STATE_FIELD_SET = new Set(AGENT_STATE_FIELDS);
 const PRODUCT_STATE_FIELDS = [
   'projectWorkspace',
   'task',
@@ -29,15 +59,45 @@ function now() {
   return Date.now();
 }
 
-function createSessionId() {
+function createAgentRecordId() {
   const stamp = now().toString(36);
   const random = crypto.randomBytes(6).toString('hex');
-  return `${SESSION_ID_PREFIX}_${stamp}_${random}`;
+  return `${AGENT_RECORD_ID_PREFIX}_${stamp}_${random}`;
 }
 
 function safeSessionFileName(id) {
   const value = String(id || '').trim();
-  return /^fsess_[A-Za-z0-9_-]+$/.test(value) ? `${value}.json` : '';
+  return /^(?:agent|fsess)_[A-Za-z0-9_-]+$/.test(value) ? `${value}.json` : '';
+}
+
+function isLegacySessionId(id) {
+  return /^fsess_[A-Za-z0-9_-]+$/.test(String(id || '').trim());
+}
+
+function isAgentRecordId(id) {
+  return /^agent_[A-Za-z0-9_-]+$/.test(String(id || '').trim());
+}
+
+function agentRecordIdFor(agent) {
+  if (agent && Object.prototype.hasOwnProperty.call(agent, 'persistentSessionId')) {
+    return typeof agent.persistentSessionId === 'string' ? agent.persistentSessionId : '';
+  }
+  return typeof agent?.agentRecordId === 'string' ? agent.agentRecordId : '';
+}
+
+function cloneJson(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function sameJson(left, right) {
+  return isDeepStrictEqual(left, right);
+}
+
+function withoutUpdatedAt(value) {
+  const copy = { ...(value || {}) };
+  delete copy.updatedAt;
+  return copy;
 }
 
 function atomicWriteJson(file, value) {
@@ -77,17 +137,62 @@ class FarmingSessionStore {
   init({ legacyMainPageSessionKeys = [] } = {}) {
     fs.mkdirSync(this.sessionsDir, { recursive: true });
     this.index = this.readIndex();
+    this.reconcileProviderSessionIndex();
     if (!Array.isArray(this.index.mainPageSessionKeys) || this.index.mainPageSessionKeys.length === 0) {
-      const migrated = this.normalizeMainPageSessionKeys(legacyMainPageSessionKeys);
+      const migrated = this.filterRecoverableMainPageSessionKeys(legacyMainPageSessionKeys);
       if (migrated.length > 0) {
         this.setMainPageSessionKeys(migrated);
         return;
       }
     }
-    this.index.mainPageSessionKeys = this.normalizeMainPageSessionKeys(this.index.mainPageSessionKeys);
+    this.index.mainPageSessionKeys = this.filterRecoverableMainPageSessionKeys(
+      this.index.mainPageSessionKeys,
+    );
     this.writeIndex();
   }
 
+  reconcileProviderSessionIndex() {
+    const index = this.ensureIndex();
+    const recordsByProviderKey = new Map();
+    const records = this.listStoredAgentRecords();
+    const successors = this.legacySuccessors(records);
+    for (const record of records) {
+      if (successors.has(record.id)) continue;
+      const sessionKey = String(record?.providerSessionKey || '');
+      if (!record || record.kind !== 'agent' || !parseProviderSessionKey(sessionKey)) continue;
+      const matches = recordsByProviderKey.get(sessionKey) || [];
+      matches.push(record);
+      recordsByProviderKey.set(sessionKey, matches);
+    }
+
+    for (const [sessionKey, records] of recordsByProviderKey) {
+      const indexedId = index.providerSessionRecords[sessionKey];
+      const indexedRecord = indexedId ? records.find(record => record.id === indexedId) : null;
+      if (records.length > 1) {
+        const ids = records.map(record => record.id).sort().join(', ');
+        throw new Error(`Conflicting Farming session records for ${sessionKey}: ${ids}`);
+      }
+      if (!indexedRecord || isLegacySessionId(indexedId)) {
+        index.providerSessionRecords[sessionKey] = records[0].id;
+      }
+    }
+  }
+
+  filterRecoverableMainPageSessionKeys(keys) {
+    return this.normalizeMainPageSessionKeys(keys).filter(sessionKey => {
+      const record = this.getRecordForProviderSessionKey(sessionKey);
+      if (!record) return true;
+      if (record.archived === true) return false;
+      const entries = lifecycleJournal(record).entries;
+      const latest = entries.length > 0 ? entries[entries.length - 1] : null;
+      return !(
+        latest
+        && ['delete', 'archive'].includes(latest.type)
+        && latest.state === 'succeeded'
+      );
+    });
+  }
+
   readIndex() {
     try {
       if (fs.existsSync(this.indexFile)) {
@@ -135,7 +240,11 @@ class FarmingSessionStore {
     return fileName ? path.join(this.sessionsDir, fileName) : '';
   }
 
-  readRecord(id) {
+  agentStateFile(id) {
+    return isAgentRecordId(id) ? storageLayout.agentStateFile(this.configDir, id) : '';
+  }
+
+  readMetadataRecord(id) {
     const file = this.sessionFile(id);
     if (!file) return null;
     try {
@@ -147,11 +256,122 @@ class FarmingSessionStore {
     }
   }
 
+  readAgentState(id) {
+    const file = this.agentStateFile(id);
+    if (!file) return null;
+    try {
+      if (!fs.existsSync(file)) return null;
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (
+        !parsed
+        || typeof parsed !== 'object'
+        || parsed.agentRecordId !== id
+        || parsed.agentStateVersion !== AGENT_STATE_VERSION
+      ) {
+        return null;
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  readRecord(id) {
+    const metadata = this.readMetadataRecord(id);
+    if (!metadata) return null;
+    if (!isAgentRecordId(id)) return metadata;
+    const state = this.readAgentState(id);
+    if (!state) return { ...metadata, agentRecordId: id };
+    const merged = { ...metadata, agentRecordId: id };
+    AGENT_STATE_FIELDS.forEach(field => {
+      if (Object.prototype.hasOwnProperty.call(state, field)) merged[field] = cloneJson(state[field]);
+    });
+    return merged;
+  }
+
+  splitAgentRecord(record, id) {
+    const metadata = {};
+    const state = {
+      agentStateVersion: AGENT_STATE_VERSION,
+      agentRecordId: id,
+      kind: 'agent-state',
+    };
+    Object.entries(record || {}).forEach(([field, value]) => {
+      if (AGENT_STATE_FIELD_SET.has(field)) state[field] = cloneJson(value);
+      else metadata[field] = cloneJson(value);
+    });
+    metadata.id = id;
+    metadata.agentRecordId = id;
+    metadata.kind = 'agent';
+    metadata.recordVersion = AGENT_RECORD_VERSION;
+    return { metadata, state };
+  }
+
+  promoteIndexRecordId(previousId, nextId) {
+    if (!this.index || !previousId || previousId === nextId) return;
+    Object.entries(this.index.providerSessionRecords).forEach(([key, id]) => {
+      if (id === previousId) this.index.providerSessionRecords[key] = nextId;
+    });
+  }
+
   writeRecord(record) {
     if (!record || !safeSessionFileName(record.id)) return '';
-    const file = this.sessionFile(record.id);
-    atomicWriteJson(file, record);
-    return record.id;
+    const previousId = record.id;
+    const id = isLegacySessionId(previousId) ? createAgentRecordId() : previousId;
+    if (!isAgentRecordId(id)) return '';
+    const promoted = id !== previousId;
+    const nextRecord = {
+      ...record,
+      id,
+      agentRecordId: id,
+      ...(promoted ? { legacyRecordId: previousId } : {}),
+    };
+    const { metadata, state } = this.splitAgentRecord(nextRecord, id);
+    const existingMetadata = this.readMetadataRecord(id);
+    const existingState = this.readAgentState(id);
+    const metadataChanged = !existingMetadata
+      || !sameJson(withoutUpdatedAt(existingMetadata), withoutUpdatedAt(metadata));
+    const stateChanged = !existingState
+      || !sameJson(withoutUpdatedAt(existingState), withoutUpdatedAt(state));
+    if (stateChanged) {
+      state.updatedAt = now();
+      atomicWriteJson(this.agentStateFile(id), state);
+    }
+    if (metadataChanged) {
+      metadata.updatedAt = now();
+      atomicWriteJson(this.sessionFile(id), metadata);
+    }
+    if (promoted) this.promoteIndexRecordId(previousId, id);
+    return id;
+  }
+
+  listStoredAgentRecords() {
+    let names = [];
+    try {
+      names = fs.readdirSync(this.sessionsDir);
+    } catch {
+      return [];
+    }
+    return names
+      .filter(name => name.endsWith('.json') && !name.endsWith('.state.json'))
+      .map(name => name.slice(0, -5))
+      .filter(id => safeSessionFileName(id))
+      .map(id => this.readRecord(id))
+      .filter(record => record && record.kind === 'agent');
+  }
+
+  legacySuccessors(records) {
+    const successors = new Map();
+    for (const record of Array.isArray(records) ? records : []) {
+      const legacyId = String(record?.legacyRecordId || '').trim();
+      if (!isLegacySessionId(legacyId)) continue;
+      const previous = successors.get(legacyId);
+      if (previous && previous !== record.id) {
+        throw new Error(`Conflicting Agent record successors for ${legacyId}: ${previous}, ${record.id}`);
+      }
+      successors.set(legacyId, record.id);
+    }
+    return successors;
   }
 
   providerSessionKeyForAgent(agent) {
@@ -188,6 +408,15 @@ class FarmingSessionStore {
       providerSessionTitle: typeof agent.providerSessionTitle === 'string' ? agent.providerSessionTitle : '',
       providerSessionWorkspace: typeof agent.providerSessionWorkspace === 'string' ? agent.providerSessionWorkspace : '',
       terminalInputReceived: agent.terminalInputReceived === true,
+      structuredRuntimeProcess: agent.structuredRuntimeProcess
+        && typeof agent.structuredRuntimeProcess === 'object'
+        ? JSON.parse(JSON.stringify(agent.structuredRuntimeProcess))
+        : null,
+      legacyAcpProcessExitAcknowledgedAt:
+        typeof agent.legacyAcpProcessExitAcknowledgedAt === 'number'
+          ? agent.legacyAcpProcessExitAcknowledgedAt
+          : null,
+      ...(agent.lifecycleJournal ? { lifecycleJournal: lifecycleJournal(agent) } : {}),
       ...legacyRuntimeMetadata(agent),
       engine: typeof agent.engineName === 'string' ? agent.engineName : '',
       category: typeof agent.category === 'string' ? agent.category : '',
@@ -217,7 +446,6 @@ class FarmingSessionStore {
           ? agent.providerSessionTitle
           : (typeof agent.sessionTitle === 'string' ? agent.sessionTitle : '')),
       startedAt: typeof agent.startedAt === 'number' ? agent.startedAt : null,
-      lastSeenAt: now(),
     };
   }
 
@@ -226,9 +454,21 @@ class FarmingSessionStore {
     if (!parsed) return '';
     const index = this.ensureIndex();
     const existingId = index.providerSessionRecords[sessionKey];
+    const normalizedPreferredId = safeSessionFileName(preferredId) ? preferredId : '';
+    const preferredRecord = normalizedPreferredId ? this.readRecord(normalizedPreferredId) : null;
+    if (
+      !safeSessionFileName(existingId)
+      && preferredRecord?.providerSessionTemporary !== true
+      && preferredRecord?.providerSessionKey
+      && preferredRecord.providerSessionKey !== sessionKey
+    ) {
+      throw new Error(
+        `Farming session ${normalizedPreferredId} is already bound to ${preferredRecord.providerSessionKey}`,
+      );
+    }
     const id = safeSessionFileName(existingId)
       ? existingId
-      : (safeSessionFileName(preferredId) ? preferredId : createSessionId());
+      : (normalizedPreferredId || createAgentRecordId());
     const existing = this.readRecord(id) || {};
     const record = {
       id,
@@ -248,17 +488,21 @@ class FarmingSessionStore {
     if (typeof record.customTitle === 'string' && record.customTitle) {
       record.title = record.customTitle;
     }
-    index.providerSessionRecords[sessionKey] = id;
-    this.writeRecord(record);
+    Object.entries(index.providerSessionRecords).forEach(([key, recordId]) => {
+      if (key !== sessionKey && recordId === id) delete index.providerSessionRecords[key];
+    });
+    const writtenId = this.writeRecord(record);
+    index.providerSessionRecords[sessionKey] = writtenId;
     this.writeIndex();
-    return id;
+    return writtenId;
   }
 
   ensureRecordForAgent(agent, patch = {}) {
     const providerSessionKey = this.providerSessionKeyForAgent(agent);
     if (providerSessionKey) {
-      const previousId = safeSessionFileName(agent?.persistentSessionId)
-        ? agent.persistentSessionId
+      const preferredId = agentRecordIdFor(agent);
+      const previousId = safeSessionFileName(preferredId)
+        ? preferredId
         : '';
       const previous = previousId ? this.readRecord(previousId) : null;
       const canonical = this.getRecordForProviderSessionKey(providerSessionKey);
@@ -275,10 +519,15 @@ class FarmingSessionStore {
       const id = this.ensureRecordForProviderSessionKey(providerSessionKey, {
         ...agentPatch,
         ...patch,
-      }, agent?.persistentSessionId || '');
+      }, preferredId || '');
       if (previousId && previousId !== id) {
-        if (previous && (previous.providerSessionTemporary === true || !previous.providerSessionKey)) {
-          this.writeRecord({
+        const promotedFromPrevious = this.readRecord(id)?.legacyRecordId === previousId;
+        if (
+          !promotedFromPrevious
+          && previous
+          && (previous.providerSessionTemporary === true || !previous.providerSessionKey)
+        ) {
+          const mergedId = this.writeRecord({
             ...previous,
             runtimeAgentId: '',
             visibleOnMainPage: false,
@@ -287,13 +536,15 @@ class FarmingSessionStore {
             mergedInto: id,
             updatedAt: now(),
           });
+          if (mergedId && mergedId !== previousId) this.writeIndex();
         }
       }
       return id;
     }
 
-    const existingId = safeSessionFileName(agent?.persistentSessionId) ? agent.persistentSessionId : '';
-    const id = existingId || createSessionId();
+    const preferredId = agentRecordIdFor(agent);
+    const existingId = safeSessionFileName(preferredId) ? preferredId : '';
+    const id = existingId || createAgentRecordId();
     const existing = this.readRecord(id) || {};
     const record = {
       id,
@@ -306,8 +557,7 @@ class FarmingSessionStore {
       ...patch,
       updatedAt: now(),
     };
-    this.writeRecord(record);
-    return id;
+    return this.writeRecord(record);
   }
 
   setProviderSessionDisplayState(sessionKey, patch = {}) {
@@ -358,11 +608,12 @@ class FarmingSessionStore {
       const id = index.providerSessionRecords[key];
       const existing = this.readRecord(id);
       if (existing) {
-        this.writeRecord({
+        const writtenId = this.writeRecord({
           ...existing,
           visibleOnMainPage: false,
           updatedAt: now(),
         });
+        if (writtenId) index.providerSessionRecords[key] = writtenId;
       }
     });
     index.mainPageSessionKeys = normalized;
@@ -377,11 +628,12 @@ class FarmingSessionStore {
     const id = index.providerSessionRecords[sessionKey];
     const existing = this.readRecord(id);
     if (existing) {
-      this.writeRecord({
+      const writtenId = this.writeRecord({
         ...existing,
         visibleOnMainPage: false,
         updatedAt: now(),
       });
+      if (writtenId) index.providerSessionRecords[sessionKey] = writtenId;
     }
     this.writeIndex();
     return true;
@@ -407,20 +659,15 @@ class FarmingSessionStore {
 
   listAgentRecords() {
     this.ensureIndex();
-    let names = [];
-    try {
-      names = fs.readdirSync(this.sessionsDir);
-    } catch {
-      return [];
-    }
-    return names
-      .filter(name => name.endsWith('.json') && safeSessionFileName(name.slice(0, -5)))
-      .map(name => this.readRecord(name.slice(0, -5)))
-      .filter(record => record && record.kind === 'agent');
+    const records = this.listStoredAgentRecords();
+    const successors = this.legacySuccessors(records);
+    return records.filter(record => !successors.has(record.id));
   }
 }
 
 module.exports = {
+  AGENT_RECORD_VERSION,
+  AGENT_STATE_VERSION,
   FarmingSessionStore,
   MAX_MAIN_PAGE_SESSION_KEYS,
   parseProviderSessionKey,

package/backend/json-cli-runtime.js

@@ -3,6 +3,48 @@ const { spawn } = require('child_process');
 const { AgentJsonStreamParser } = require('./agent-json-stream');
 
 const MAX_EVENTS = 12_000;
+const PROCESS_EXIT_TIMEOUT_MS = 1500;
+const PROCESS_KILL_TIMEOUT_MS = 1000;
+
+function childHasExited(child) {
+  return !child
+    || (child.exitCode !== null && child.exitCode !== undefined)
+    || (child.signalCode !== null && child.signalCode !== undefined);
+}
+
+function processTreeHasExited(child, ownsProcessGroup) {
+  if (!ownsProcessGroup || !child?.pid || process.platform === 'win32') {
+    return childHasExited(child);
+  }
+  try {
+    process.kill(-child.pid, 0);
+    return false;
+  } catch (error) {
+    return error?.code === 'ESRCH';
+  }
+}
+
+async function waitForProcessTreeExit(child, ownsProcessGroup, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    if (processTreeHasExited(child, ownsProcessGroup)) return true;
+    await new Promise(resolve => setTimeout(resolve, 25));
+  }
+  return processTreeHasExited(child, ownsProcessGroup);
+}
+
+function signalProcessTree(child, ownsProcessGroup, signal) {
+  if (!child || processTreeHasExited(child, ownsProcessGroup)) return;
+  if (ownsProcessGroup && child.pid && process.platform !== 'win32') {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch (error) {
+      if (error?.code === 'ESRCH') return;
+    }
+  }
+  child.kill(signal);
+}
 
 function codexPermissionArgs(mode) {
   if (mode === 'full') return ['--dangerously-bypass-approvals-and-sandbox'];
@@ -35,13 +77,23 @@ class JsonCliRuntime extends EventEmitter {
   constructor(options = {}) {
     super();
     this.spawn = options.spawn || spawn;
+    this.processExitTimeoutMs = options.processExitTimeoutMs ?? PROCESS_EXIT_TIMEOUT_MS;
+    this.processKillTimeoutMs = options.processKillTimeoutMs ?? PROCESS_KILL_TIMEOUT_MS;
+    this.ownsProcessGroups = options.ownsProcessGroups ?? process.platform !== 'win32';
     this.bindings = new Map();
+    this.disposing = false;
+    this.disposePromise = null;
+    this.disposed = false;
   }
 
   registerAgent(options) {
+    if (this.disposing || this.disposed) {
+      throw new Error('JSON CLI runtime is shutting down');
+    }
     const binding = {
       ...options,
       events: Array.isArray(options.initialEvents) ? [...options.initialEvents].slice(-MAX_EVENTS) : [],
+      ownsProcessGroup: this.ownsProcessGroups,
       child: null,
       operationSeq: 0,
       state: 'idle',
@@ -53,11 +105,31 @@ class JsonCliRuntime extends EventEmitter {
 
   unregisterAgent(agentId) {
     const binding = this.bindings.get(agentId);
-    if (binding?.child && !binding.child.killed) binding.child.kill('SIGTERM');
+    if (binding?.child) signalProcessTree(binding.child, binding.ownsProcessGroup, 'SIGTERM');
     this.bindings.delete(agentId);
   }
 
+  async unregisterAgentAndWait(agentId) {
+    const binding = this.bindings.get(agentId);
+    if (!binding) return false;
+    const child = binding.child;
+    if (child && !processTreeHasExited(child, binding.ownsProcessGroup)) {
+      signalProcessTree(child, binding.ownsProcessGroup, 'SIGTERM');
+      if (!await waitForProcessTreeExit(child, binding.ownsProcessGroup, this.processExitTimeoutMs)) {
+        signalProcessTree(child, binding.ownsProcessGroup, 'SIGKILL');
+        if (!await waitForProcessTreeExit(child, binding.ownsProcessGroup, this.processKillTimeoutMs)) {
+          throw new Error(`JSON Agent process tree ${child.pid || ''} did not exit`);
+        }
+      }
+    }
+    if (this.bindings.get(agentId) === binding) this.bindings.delete(agentId);
+    return true;
+  }
+
   async submitComposerMessage(agentId, message, patch = {}) {
+    if (this.disposing || this.disposed) {
+      throw new Error('JSON CLI runtime is shutting down');
+    }
     const binding = this.bindings.get(agentId);
     if (!binding) throw new Error('JSON CLI Agent is not registered');
     if (binding.child) throw new Error('Agent is already working');
@@ -75,6 +147,7 @@ class JsonCliRuntime extends EventEmitter {
       cwd: binding.cwd,
       env: binding.env,
       stdio: ['pipe', 'pipe', 'pipe'],
+      detached: binding.ownsProcessGroup,
     });
     binding.child = child;
     this.emitRuntime(binding);
@@ -89,7 +162,7 @@ class JsonCliRuntime extends EventEmitter {
         stderr = `${stderr}${chunk.toString('utf8')}`.slice(-8000);
       });
       child.on('error', error => {
-        binding.child = null;
+        if (!child.pid) binding.child = null;
         binding.state = 'error';
         binding.error = error.message;
         this.emitRuntime(binding);
@@ -100,12 +173,19 @@ class JsonCliRuntime extends EventEmitter {
         binding.events.push(...parser.events);
         if (binding.events.length > MAX_EVENTS) binding.events.splice(0, binding.events.length - MAX_EVENTS);
         if (parser.sessionId) binding.sessionId = parser.sessionId;
-        binding.child = null;
-        binding.state = code === 0 ? 'idle' : 'error';
-        binding.error = code === 0 ? '' : (stderr.trim() || `JSON CLI exited with code ${code}${signal ? ` (${signal})` : ''}`);
+        const processTreeExited = processTreeHasExited(child, binding.ownsProcessGroup);
+        if (processTreeExited) binding.child = null;
+        binding.state = code === 0 && processTreeExited ? 'idle' : 'error';
+        binding.error = code === 0 && processTreeExited
+          ? ''
+          : (
+            !processTreeExited
+              ? 'JSON CLI root exited while its process tree remained live'
+              : (stderr.trim() || `JSON CLI exited with code ${code}${signal ? ` (${signal})` : ''}`)
+          );
         this.emit('transcript', { agentId, transcript: this.getTranscript(agentId) });
         this.emitRuntime(binding);
-        if (code === 0) resolve({ sessionId: binding.sessionId });
+        if (code === 0 && processTreeExited) resolve({ sessionId: binding.sessionId });
         else reject(new Error(binding.error));
       });
       if (launch.stdin) child.stdin.end(launch.stdin);
@@ -148,6 +228,40 @@ class JsonCliRuntime extends EventEmitter {
     };
   }
 
+  dispose() {
+    if (this.disposed) return Promise.resolve();
+    if (this.disposePromise) return this.disposePromise;
+
+    this.disposing = true;
+    const disposePromise = this.performDispose();
+    this.disposePromise = disposePromise;
+    void disposePromise.finally(() => {
+      if (this.disposePromise === disposePromise) this.disposePromise = null;
+      if (!this.disposed) this.disposing = false;
+    }).catch(() => {});
+    return disposePromise;
+  }
+
+  resumeAfterDisposeAbort() {
+    this.disposed = false;
+    this.disposing = false;
+  }
+
+  async performDispose() {
+    const failures = [];
+    for (const agentId of [...this.bindings.keys()]) {
+      try {
+        await this.unregisterAgentAndWait(agentId);
+      } catch (error) {
+        failures.push(error);
+      }
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(failures, 'One or more JSON Agent process trees did not exit');
+    }
+    this.disposed = true;
+  }
+
   emitRuntime(binding) {
     this.emit('agent-runtime', {
       agentId: binding.agentId,