farming-code 2.2.20 → 2.2.22

package/backend/server.js

@@ -18,7 +18,6 @@ const { listAvailableAgents, resolveCompatibleCodexExecutable } = require('./exe
 const { readClaudeSettingsSummary } = require('./claude-settings');
 const { listCodexModelOptions } = require('./codex-models');
 const { listCodexSessions } = require('./codex-session-history');
-const { unarchiveCodexSession } = require('./codex-session-archive');
 const {
   buildAgentSessionResumeCommand,
   findAgentSession,
@@ -32,6 +31,7 @@ const {
 const {
   findActiveAgentClaimingSession,
   mainPageAgentSessionKey,
+  mainPageAgentSessionFromKey,
   mainPageAgentSessionsToAutoResume,
   resumedAgentSource,
 } = require('./main-page-session');
@@ -112,6 +112,20 @@ const agentManager = new AgentManager(configManager, {
   authDisabled: !authEnabled,
   cliBinDir: resolveCliBinDir(),
 });
+
+async function requireAgentRecoveryForHttp(res) {
+  try {
+    await agentManager.whenRecovered();
+    return true;
+  } catch (error) {
+    res.status(503).json({
+      error: error?.message || 'Agent lifecycle recovery is unavailable',
+      retryable: true,
+    });
+    return false;
+  }
+}
+
 const themeManager = new ThemeManager({ configDir: configManager.farmingDir });
 const workspaceFileService = new WorkspaceFileService();
 const workspaceRootRegistry = new WorkspaceRootRegistry(agentManager);
@@ -817,16 +831,6 @@ app.get(routePath(BASE_PATH, '/api/update'), async (req, res) => {
 });
 
 app.post(routePath(BASE_PATH, '/api/update/install'), express.json(), async (req, res) => {
-  const blockers = blockingUpdateAgents();
-  const force = req.body && req.body.force === true;
-  if (blockers.length > 0 && !force) {
-    res.status(409).json({
-      error: 'Cannot upgrade while non-recoverable project agents are running',
-      blockingAgents: blockers,
-    });
-    return;
-  }
-
   try {
     const state = await updateService.startInstall({
       assetName: req.body && typeof req.body.assetName === 'string' ? req.body.assetName : '',
@@ -834,7 +838,7 @@ app.post(routePath(BASE_PATH, '/api/update/install'), express.json(), async (req
     res.status(202).json({
       update: {
         state,
-        blockingAgents: blockers,
+        blockingAgents: blockingUpdateAgents(),
       },
     });
   } catch (error) {
@@ -842,6 +846,25 @@ app.post(routePath(BASE_PATH, '/api/update/install'), express.json(), async (req
   }
 });
 
+app.post(routePath(BASE_PATH, '/api/update/restart'), express.json(), async (req, res) => {
+  const blockers = blockingUpdateAgents();
+  const force = req.body && req.body.force === true;
+  if (blockers.length > 0 && !force) {
+    res.status(409).json({
+      error: 'Cannot restart for update while non-recoverable project agents are running',
+      blockingAgents: blockers,
+    });
+    return;
+  }
+
+  try {
+    const state = await updateService.applyPreparedUpdate();
+    res.status(202).json({ update: { state, blockingAgents: blockers } });
+  } catch (error) {
+    res.status(500).json({ error: error.message || 'Failed to restart for update' });
+  }
+});
+
 function warmCodexExecutableVersionCache() {
   const startedAt = Date.now();
   try {
@@ -961,6 +984,40 @@ app.patch(routePath(BASE_PATH, '/api/agent-sessions/:provider/:sessionId'), expr
   res.json({ sessionKey, pinned: req.body.pinned });
 });
 
+app.post(routePath(BASE_PATH, '/api/main-page-agent-sessions'), express.json(), (req, res) => {
+  const operation = req.body?.operation;
+  const requestedKeys = Array.isArray(req.body?.sessionKeys) ? req.body.sessionKeys : [];
+  const sessionKeys = [...new Set(requestedKeys.map(key => String(key || '').trim()).filter(Boolean))];
+  if (
+    !['add', 'remove'].includes(operation)
+    || sessionKeys.length === 0
+    || sessionKeys.length > 50
+    || sessionKeys.some(key => !mainPageAgentSessionFromKey(key))
+  ) {
+    res.status(400).json({ error: 'A valid main-page Agent session mutation is required' });
+    return;
+  }
+
+  if (operation === 'add') {
+    [...sessionKeys].reverse().forEach(sessionKey => {
+      const session = mainPageAgentSessionFromKey(sessionKey);
+      configManager.rememberMainPageSessionKey(sessionKey, {
+        provider: session.provider,
+        providerSessionId: session.sessionId,
+        providerSessionKey: sessionKey,
+        providerHomeId: session.providerHomeId || 'default',
+      });
+    });
+  } else {
+    configManager.removeMainPageSessionKeys(sessionKeys);
+  }
+
+  const mainPageSessionKeys = configManager.getMainPageSessionKeys();
+  agentSessionsCache.invalidate();
+  res.json({ success: true, mainPageSessionKeys });
+  scheduleBroadcastState();
+});
+
 app.get(routePath(BASE_PATH, '/api/themes'), (req, res) => {
   const currentTheme = configManager.getSettings().theme || 'terminal';
   res.json({
@@ -1313,13 +1370,60 @@ app.post(routePath(BASE_PATH, '/api/agents/:agentId/codex-terminal-profile'), ex
 });
 
 app.patch(routePath(BASE_PATH, '/api/agents/:agentId'), express.json(), async (req, res) => {
+  if (!await requireAgentRecoveryForHttp(res)) return;
   const body = req.body || {};
   const updates = {};
+  const providedPatchFields = [
+    'customTitle',
+    'task',
+    'pinned',
+    'unread',
+    'archived',
+    'readAttentionSeq',
+    'readOutputEpoch',
+    'readOutputSeq',
+    'launchPermissionMode',
+    'agentRuntimeMode',
+  ].filter(field => Object.prototype.hasOwnProperty.call(body, field));
+  const lifecyclePatchFields = providedPatchFields.filter(field => (
+    field === 'launchPermissionMode'
+    || field === 'agentRuntimeMode'
+    || (field === 'archived' && body.archived === true)
+  ));
+  if (lifecyclePatchFields.length > 0 && providedPatchFields.length > 1) {
+    res.status(400).json({
+      error: 'Archive, permission restart, and runtime switch must be requested separately from other Agent updates',
+    });
+    return;
+  }
+  const ordinaryPatchGroups = [
+    providedPatchFields.includes('customTitle') ? 'customTitle' : '',
+    providedPatchFields.includes('task') ? 'task' : '',
+    providedPatchFields.some(field => [
+      'pinned',
+      'unread',
+      'archived',
+      'readAttentionSeq',
+      'readOutputEpoch',
+      'readOutputSeq',
+    ].includes(field)) ? 'flags' : '',
+  ].filter(Boolean);
+  if (ordinaryPatchGroups.length > 1) {
+    res.status(400).json({
+      error: 'Agent title, task, and flags must be updated in separate requests',
+    });
+    return;
+  }
+
+  await agentManager.whenAgentLifecycleIdle(req.params.agentId);
 
   if (typeof body.customTitle === 'string') {
     const result = agentManager.renameAgent(req.params.agentId, body.customTitle);
     if (result.error) {
-      res.status(404).json({ error: result.error });
+      const status = result.error === 'Agent not found'
+        ? 404
+        : (result.error.startsWith('Failed to ') ? 500 : 409);
+      res.status(status).json({ error: result.error });
       return;
     }
     updates.customTitle = result.customTitle;
@@ -1328,7 +1432,10 @@ app.patch(routePath(BASE_PATH, '/api/agents/:agentId'), express.json(), async (r
   if (typeof body.task === 'string') {
     const result = agentManager.setAgentTask(req.params.agentId, body.task);
     if (result.error) {
-      res.status(404).json({ error: result.error });
+      const status = result.error === 'Agent not found'
+        ? 404
+        : (result.error.startsWith('Failed to ') ? 500 : 409);
+      res.status(status).json({ error: result.error });
       return;
     }
     updates.task = result.task;
@@ -1356,8 +1463,10 @@ app.patch(routePath(BASE_PATH, '/api/agents/:agentId'), express.json(), async (r
   if (flagPatch.archived === true) {
     const result = await agentManager.archiveAgent(req.params.agentId);
     if (result.error) {
-      const status = result.error === 'Agent not found' ? 404 : 400;
-      res.status(status).json({ error: result.error });
+      const status = result.stopped === true
+        ? 409
+        : (result.error === 'Agent not found' ? 404 : 400);
+      res.status(status).json(result);
       return;
     }
     Object.assign(updates, result);
@@ -1369,7 +1478,9 @@ app.patch(routePath(BASE_PATH, '/api/agents/:agentId'), express.json(), async (r
   if (Object.keys(flagPatch).length > 0) {
     const result = agentManager.updateAgentFlags(req.params.agentId, flagPatch);
     if (result.error) {
-      const status = result.error === 'Agent not found' ? 404 : 400;
+      const status = result.error === 'Agent not found'
+        ? 404
+        : (result.error.startsWith('Failed to ') ? 500 : 409);
       res.status(status).json({ error: result.error });
       return;
     }
@@ -1415,13 +1526,17 @@ app.patch(routePath(BASE_PATH, '/api/agents/:agentId'), express.json(), async (r
   res.json({ agentId: req.params.agentId, ...updates });
 });
 
-app.post(routePath(BASE_PATH, '/api/agents/:agentId/reorder'), express.json(), (req, res) => {
+app.post(routePath(BASE_PATH, '/api/agents/:agentId/reorder'), express.json(), async (req, res) => {
+  if (!await requireAgentRecoveryForHttp(res)) return;
+  await agentManager.whenAgentLifecycleIdle(req.params.agentId);
   const result = agentManager.reorderAgent(req.params.agentId, {
     beforeAgentId: req.body?.beforeAgentId,
     afterAgentId: req.body?.afterAgentId,
   });
   if (result.error) {
-    const status = result.error === 'Agent not found' ? 404 : 400;
+    const status = result.error === 'Agent not found'
+      ? 404
+      : (result.error.startsWith('Failed to ') ? 500 : 409);
     res.status(status).json({ error: result.error });
     return;
   }
@@ -1430,8 +1545,21 @@ app.post(routePath(BASE_PATH, '/api/agents/:agentId/reorder'), express.json(), (
 });
 
 app.post(routePath(BASE_PATH, '/api/agents/:agentId/fork'), express.json(), async (req, res) => {
+  if (!await requireAgentRecoveryForHttp(res)) return;
   const mode = req.body && typeof req.body.mode === 'string' ? req.body.mode : 'same-worktree';
-  const result = await agentManager.forkAgent(req.params.agentId, mode);
+  const targetRuntime = req.body && typeof req.body.targetRuntime === 'string'
+    ? req.body.targetRuntime
+    : '';
+  if (targetRuntime && targetRuntime !== 'chat') {
+    res.status(400).json({ error: 'Unsupported Fork target runtime' });
+    return;
+  }
+  const result = await agentManager.forkAgent(req.params.agentId, mode, {
+    ...(targetRuntime ? { targetRuntime } : {}),
+    ...(Number.isSafeInteger(req.body?.expectedRevision)
+      ? { expectedRevision: req.body.expectedRevision }
+      : {}),
+  });
   if (result.error) {
     const status = result.error === 'Agent not found' ? 404 : 400;
     res.status(status).json({ error: result.error });
@@ -1537,6 +1665,16 @@ app.post(routePath(BASE_PATH, '/api/projects/pin'), express.json(), (req, res) =
   }
 });
 
+app.patch(routePath(BASE_PATH, '/api/projects/name'), express.json(), (req, res) => {
+  try {
+    const result = configManager.setProjectName(req.body?.workspace, req.body?.name);
+    scheduleBroadcastState();
+    res.json(result);
+  } catch (error) {
+    res.status(400).json({ error: error.message || 'Failed to rename Project' });
+  }
+});
+
 app.post(routePath(BASE_PATH, '/api/projects/create-worktree'), express.json(), async (req, res) => {
   let created = null;
   try {
@@ -1568,6 +1706,7 @@ app.post(routePath(BASE_PATH, '/api/projects/create-worktree'), express.json(),
 });
 
 app.post(routePath(BASE_PATH, '/api/projects/delete-worktree'), express.json(), async (req, res) => {
+  if (!await requireAgentRecoveryForHttp(res)) return;
   const body = req.body || {};
   const workspace = typeof body.workspace === 'string' ? body.workspace : '';
   const inspected = await agentManager.inspectForkWorktreeProject(workspace);
@@ -1584,42 +1723,22 @@ app.post(routePath(BASE_PATH, '/api/projects/delete-worktree'), express.json(),
     return;
   }
 
-  const wasPinned = (configManager.getSettings().pinnedProjectWorkspaces || []).includes(inspected.workspace);
-  let membership;
-  try {
-    membership = configManager.removeProjectWorkspace(inspected.workspace);
-  } catch (error) {
-    res.status(500).json({
-      ...inspected,
-      error: error.message || 'Project removal failed; the worktree was not deleted',
-    });
-    return;
-  }
   const result = await agentManager.deleteForkWorktreeProject(inspected.workspace, { force: body.force === true });
   if (result.error) {
-    let rollbackError = '';
-    try {
-      configManager.mountProjectWorkspace(inspected.workspace);
-      if (wasPinned) configManager.setProjectWorkspacePinned(inspected.workspace, true);
-    } catch (error) {
-      rollbackError = error.message || String(error);
-    }
     broadcastState();
     const status = result.requiresForce ? 409 : 400;
-    res.status(status).json({
-      ...result,
-      ...(rollbackError ? {
-        error: `${result.error}. Project restore failed: ${rollbackError}`,
-        rollbackError,
-      } : {}),
-    });
+    res.status(status).json(result);
     return;
   }
-  if (result.cleanupError) {
+
+  let membership;
+  try {
+    membership = configManager.removeProjectWorkspace(inspected.workspace);
+  } catch (error) {
     broadcastState();
     res.status(500).json({
       ...result,
-      error: `Worktree was deleted, but Agent cleanup failed: ${result.cleanupError}`,
+      error: `Worktree was deleted, but Project membership cleanup failed: ${error.message || error}`,
     });
     return;
   }
@@ -1762,30 +1881,36 @@ async function resumeAgentSessionById(provider, rawSessionId, options = {}) {
       providerHomeId,
       providerHomes: configuredProviderHomes(),
     });
+    if (
+      options.allowUnarchiveArchived === true
+      && normalizedProvider === 'codex'
+      && !requestedAsMain
+    ) {
+      const providerHomes = configuredProviderHomes();
+      const configuredHomePath = (providerHomes.codex || [])
+        .find(home => home.id === providerHomeId)?.path || '';
+      const unarchiveResult = await agentManager.ensureCodexSessionAvailable(sessionId, {
+        providerHomeId,
+        providerHomePath: session?.providerHomePath || configuredHomePath,
+        providerHomes,
+        cwd: session?.cwd || session?.workspace || '',
+      });
+      if (unarchiveResult?.error) return unarchiveResult;
+      session = await findAgentSession(normalizedProvider, sessionId, {
+        limit: 1000,
+        providerLimit: 1000,
+        scanLimit: 5000,
+        providerHomeId,
+        providerHomes,
+      }) || (session ? { ...session, archived: false } : session);
+    }
     if (session && session.archived && !shouldFork) {
-      if (options.allowUnarchiveArchived === true && normalizedProvider === 'codex' && !requestedAsMain) {
-        const unarchiveResult = await unarchiveCodexSession(sessionId, session);
-        if (unarchiveResult.error) {
-          return unarchiveResult;
-        }
-        session = await findAgentSession(normalizedProvider, sessionId, {
-          limit: 1000,
-          providerLimit: 1000,
-          scanLimit: 5000,
-          providerHomeId,
-          providerHomes: configuredProviderHomes(),
-        }) || {
-          ...session,
-          archived: false,
-        };
-      } else {
-        forgetMainPageAgentSession(normalizedProvider, sessionId, providerHomeId);
-        return {
-          error: `${session.providerName || normalizedProvider} session is archived. Unarchive it before resuming.`,
-          status: 409,
-          archived: true,
-        };
-      }
+      forgetMainPageAgentSession(normalizedProvider, sessionId, providerHomeId);
+      return {
+        error: `${session.providerName || normalizedProvider} session is archived. Unarchive it before resuming.`,
+        status: 409,
+        archived: true,
+      };
     }
     if (!shouldFork && !requestedAsMain) {
       const claimingAgent = findActiveAgentClaimingSession(agentManager.getState().agents, normalizedProvider, {
@@ -2109,6 +2234,7 @@ async function autoResumeMainPageAgentSessions() {
 
 app.post(routePath(BASE_PATH, '/api/settings'), express.json(), (req, res) => {
   const settingsPatch = { ...(req.body || {}) };
+  delete settingsPatch.mainPageSessionKeys;
   delete settingsPatch.projectWorkspaces;
   delete settingsPatch.pinnedProjectWorkspaces;
   configManager.updateSettings(settingsPatch);
@@ -2246,7 +2372,11 @@ function restartMainAgent(ws, command) {
         agent.id === state.mainAgentId || agent.isMain === true
       ));
       if (currentMain) {
-        await agentManager.killAgent(currentMain.id);
+        const killed = await agentManager.killAgent(currentMain.id);
+        if (killed?.error) {
+          ws.send(JSON.stringify({ type: 'error', message: killed.error }));
+          return;
+        }
       }
 
       await agentManager.startAgent(normalizedCommand, null, (agentId, error) => {
@@ -2268,6 +2398,39 @@ function restartMainAgent(ws, command) {
   })();
 }
 
+async function killAgentFromMessage(ws, agentId, options = {}) {
+  try {
+    const requested = await agentManager.requestKillAgent(agentId, {
+      acknowledgeUnprovenAcpExit: options.acknowledgeUnprovenAcpExit === true,
+    });
+    const result = requested.result;
+    if (result?.error) {
+      ws.send(JSON.stringify({ type: 'error', message: result.error }));
+    } else if (result?.accepted) {
+      ws.send(JSON.stringify({ type: 'agent-delete-accepted', ...result }));
+      void requested.completion.then(completed => {
+        if (completed?.error && ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ type: 'error', message: completed.error }));
+        }
+      }).catch(error => {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({
+            type: 'error',
+            message: error instanceof Error ? error.message : 'Failed to stop Agent',
+          }));
+        }
+      }).finally(() => broadcastState());
+    }
+  } catch (error) {
+    ws.send(JSON.stringify({
+      type: 'error',
+      message: error instanceof Error ? error.message : 'Failed to stop Agent',
+    }));
+  } finally {
+    broadcastState();
+  }
+}
+
 async function sendInputMessage(ws, data) {
   const targetAgentId = resolveInputTargetAgentId(ws, data);
   if (!targetAgentId) return;
@@ -2404,6 +2567,7 @@ function handleMessage(ws, data) {
           task: typeof data.task === 'string' ? data.task : '',
           workflowTemplate: typeof data.workflowTemplate === 'string' ? data.workflowTemplate : '',
           customTitle: typeof data.customTitle === 'string' ? data.customTitle : '',
+          createRequestId: typeof data.requestId === 'string' ? data.requestId : '',
           codexApprovalMode: typeof data.codexApprovalMode === 'string' ? data.codexApprovalMode : undefined,
           agentRuntimeMode: ['json', 'acp', 'chat'].includes(data.agentRuntimeMode) ? data.agentRuntimeMode : 'terminal',
           acpHistoryMode: data.acpHistoryMode === 'resume' ? 'resume' : 'load',
@@ -2486,8 +2650,9 @@ function handleMessage(ws, data) {
       break;
       
     case 'kill-agent':
-      agentManager.killAgent(data.agentId);
-      broadcastState();
+      void killAgentFromMessage(ws, data.agentId, {
+        acknowledgeUnprovenAcpExit: data.acknowledgeUnprovenAcpExit === true,
+      });
       break;
 
     case 'restart-main-agent':
@@ -2502,10 +2667,26 @@ function handleMessage(ws, data) {
 const { resolveInputTargetAgentId } = require('./input-routing');
 
 function sendWorkspaceFileWatchError(ws, error) {
+  if (ws.readyState !== WebSocket.OPEN) return;
   const message = error instanceof WorkspaceFileError ? error.message : 'failed to watch workspace files';
   ws.send(JSON.stringify({ type: 'error', message }));
 }
 
+function isCurrentWorkspaceFileWatch(ws, agentId, record) {
+  return Boolean(
+    !record.cancelled
+    && ws.workspaceFileUnsubscribes?.get(agentId) === record
+  );
+}
+
+function closeWorkspaceFileWatchRecord(record) {
+  record.cancelled = true;
+  if (!record.unsubscribe) return;
+  Promise.resolve(record.unsubscribe()).catch((error) => {
+    console.error('Failed to clear workspace file watch:', error);
+  });
+}
+
 function clearWorkspaceFileWatch(ws, agentId = null) {
   const watches = ws.workspaceFileUnsubscribes;
   if (!watches) return;
@@ -2514,12 +2695,10 @@ function clearWorkspaceFileWatch(ws, agentId = null) {
     ? [[agentId, watches.get(agentId)]]
     : Array.from(watches.entries());
 
-  entries.forEach(([watchedAgentId, unsubscribe]) => {
-    if (!unsubscribe) return;
-    watches.delete(watchedAgentId);
-    Promise.resolve(unsubscribe()).catch((error) => {
-      console.error('Failed to clear workspace file watch:', error);
-    });
+  entries.forEach(([watchedAgentId, record]) => {
+    if (!record) return;
+    if (watches.get(watchedAgentId) === record) watches.delete(watchedAgentId);
+    closeWorkspaceFileWatchRecord(record);
   });
 
   if (watches.size === 0) {
@@ -2535,33 +2714,62 @@ async function watchWorkspaceFiles(ws, data) {
     if (!ws.workspaceFileUnsubscribes) {
       ws.workspaceFileUnsubscribes = new Map();
     }
-    if (ws.workspaceFileUnsubscribes.has(data.agentId)) {
-      ws.send(JSON.stringify({
-        type: 'workspace-file-watch',
-        agentId: data.agentId,
-        watching: true,
-      }));
+    const watches = ws.workspaceFileUnsubscribes;
+    const existing = watches.get(data.agentId);
+    if (existing) {
+      const watching = await existing.ready;
+      if (watching && isCurrentWorkspaceFileWatch(ws, data.agentId, existing) && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({
+          type: 'workspace-file-watch',
+          agentId: data.agentId,
+          watching: true,
+        }));
+      }
       return;
     }
 
     const root = resolveWorkspaceRoot(agentManager, data.agentId);
-
-    const unsubscribe = await workspaceFileService.subscribe(root, (event) => {
-      if (ws.readyState !== WebSocket.OPEN) return;
-      ws.send(JSON.stringify({
-        type: 'workspace-file-event',
-        event: {
+    const record = {
+      cancelled: false,
+      unsubscribe: null,
+      ready: null,
+    };
+    record.ready = (async () => {
+      const unsubscribe = await workspaceFileService.subscribe(root, (event) => {
+        if (!isCurrentWorkspaceFileWatch(ws, data.agentId, record) || ws.readyState !== WebSocket.OPEN) return;
+        ws.send(JSON.stringify({
+          type: 'workspace-file-event',
+          event: {
+            agentId: data.agentId,
+            ...event,
+          },
+        }));
+      });
+      record.unsubscribe = unsubscribe;
+      if (!isCurrentWorkspaceFileWatch(ws, data.agentId, record) || ws.readyState !== WebSocket.OPEN) {
+        closeWorkspaceFileWatchRecord(record);
+        return false;
+      }
+      return true;
+    })();
+    watches.set(data.agentId, record);
+    try {
+      const watching = await record.ready;
+      if (watching && isCurrentWorkspaceFileWatch(ws, data.agentId, record) && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({
+          type: 'workspace-file-watch',
           agentId: data.agentId,
-          ...event,
-        },
-      }));
-    });
-    ws.workspaceFileUnsubscribes.set(data.agentId, unsubscribe);
-    ws.send(JSON.stringify({
-      type: 'workspace-file-watch',
-      agentId: data.agentId,
-      watching: true,
-    }));
+          watching: true,
+        }));
+      }
+    } catch (error) {
+      if (watches.get(data.agentId) === record) watches.delete(data.agentId);
+      closeWorkspaceFileWatchRecord(record);
+      if (watches.size === 0 && ws.workspaceFileUnsubscribes === watches) {
+        ws.workspaceFileUnsubscribes = null;
+      }
+      throw error;
+    }
   } catch (error) {
     sendWorkspaceFileWatchError(ws, error);
   }
@@ -2904,18 +3112,40 @@ async function shutdownServer(options = {}) {
     ? options.preserveTerminalHost === true
     : process.env.FARMING_NATIVE_PTY_HOST_PERSIST !== '0';
 
+  try {
+    await agentManager.dispose({ preserveTerminalHost });
+  } catch (error) {
+    const teardownFrozen = agentManager.disposing === true;
+    shutdownStarted = false;
+    console.error('Farming shutdown blocked because Agent runtime cleanup could not be verified:', error);
+    if (teardownFrozen) {
+      clearBroadcastTimers();
+      tokenAuth.cleanup();
+      await Promise.allSettled([
+        closeWebSocketServer(),
+        workspaceFileService.dispose(),
+        closeHttpServer(),
+      ]);
+    }
+    if (options.exit === true) process.exitCode = 1;
+    return {
+      error: error?.message || 'Agent runtime cleanup could not be verified',
+      ...(teardownFrozen ? { frozen: true } : {}),
+    };
+  }
+
   clearBroadcastTimers();
   tokenAuth.cleanup();
   await Promise.allSettled([
     closeWebSocketServer(),
     workspaceFileService.dispose(),
-    agentManager.dispose({ preserveTerminalHost }),
     closeHttpServer(),
   ]);
 
   if (options.exit === true) {
     process.exit(options.exitCode || 0);
   }
+  return { stopped: true };
 }
 
 agentManager.onSessionStream((stream) => {

package/backend/storage-layout.js

@@ -25,6 +25,10 @@ function acpCheckpointsDir(configDir) {
   return path.join(sessionsDir(configDir), 'acp-checkpoints');
 }
 
+function agentStateFile(configDir, agentRecordId) {
+  return path.join(sessionsDir(configDir), `${agentRecordId}.state.json`);
+}
+
 function historyDir(configDir) {
   return path.join(configDir, 'history');
 }
@@ -89,6 +93,10 @@ function updateLogFile(configDir) {
   return path.join(configDir, 'farming-update.log');
 }
 
+function updateStagingDir(configDir) {
+  return path.join(configDir, 'updates');
+}
+
 function farmingNetInstancesFile(configDir) {
   return path.join(configDir, 'instances.json');
 }
@@ -115,6 +123,7 @@ function farmingNetTrustFile(configDir) {
 
 module.exports = {
   acpCheckpointsDir,
+  agentStateFile,
   farmingNetInstancesFile,
   farmingNetServerLogFile,
   farmingNetServerStateFile,
@@ -140,6 +149,7 @@ module.exports = {
   settingsFile,
   themeSettingsFile,
   updateLogFile,
+  updateStagingDir,
   updateStateFile,
   usageHistoryCacheFile,
 };