farming-code 2.2.23 → 2.2.28

package/backend/farming-session-store.js

@@ -2,6 +2,7 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { isDeepStrictEqual } = require('util');
+const { atomicWriteJson } = require('./atomic-json-store');
 const { legacyRuntimeMetadata } = require('./agent-runtime-binding');
 const { lifecycleJournal } = require('./agent-lifecycle-journal');
 const storageLayout = require('./storage-layout');
@@ -9,6 +10,7 @@ const storageLayout = require('./storage-layout');
 const AGENT_RECORD_ID_PREFIX = 'agent';
 const AGENT_RECORD_VERSION = 1;
 const AGENT_STATE_VERSION = 1;
+const SESSION_INDEX_VERSION = 2;
 const MAX_MAIN_PAGE_SESSION_KEYS = 50;
 const AGENT_STATE_FIELDS = [
   'acpState',
@@ -34,6 +36,7 @@ const AGENT_STATE_FIELDS = [
   'readOutputEpoch',
   'readOutputSeq',
   'unread',
+  'composerCommands',
 ];
 const AGENT_STATE_FIELD_SET = new Set(AGENT_STATE_FIELDS);
 const PRODUCT_STATE_FIELDS = [
@@ -100,14 +103,6 @@ function withoutUpdatedAt(value) {
   return copy;
 }
 
-function atomicWriteJson(file, value) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmpFile = `${file}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(tmpFile, JSON.stringify(value, null, 2), { mode: 0o600 });
-  fs.renameSync(tmpFile, file);
-  fs.chmodSync(file, 0o600);
-}
-
 function parseProviderSessionKey(key) {
   const match = String(key || '').match(/^agent-session:([^:]+):(.+)$/);
   if (!match) return null;
@@ -131,28 +126,38 @@ class FarmingSessionStore {
     this.normalizeMainPageSessionKeys = typeof options.normalizeMainPageSessionKeys === 'function'
       ? options.normalizeMainPageSessionKeys
       : keys => (Array.isArray(keys) ? keys : []).slice(0, MAX_MAIN_PAGE_SESSION_KEYS);
+    this.writeJson = typeof options.writeJson === 'function'
+      ? options.writeJson
+      : (file, value) => atomicWriteJson(file, value, { mode: 0o600 });
     this.index = null;
+    this.legacyProviderSessionRecords = {};
+    this.providerSessionRecords = new Map();
   }
 
   init({ legacyMainPageSessionKeys = [] } = {}) {
     fs.mkdirSync(this.sessionsDir, { recursive: true });
     this.index = this.readIndex();
     this.reconcileProviderSessionIndex();
+    let nextMainPageSessionKeys = this.index.mainPageSessionKeys;
     if (!Array.isArray(this.index.mainPageSessionKeys) || this.index.mainPageSessionKeys.length === 0) {
       const migrated = this.filterRecoverableMainPageSessionKeys(legacyMainPageSessionKeys);
       if (migrated.length > 0) {
-        this.setMainPageSessionKeys(migrated);
-        return;
+        nextMainPageSessionKeys = migrated;
       }
     }
-    this.index.mainPageSessionKeys = this.filterRecoverableMainPageSessionKeys(
-      this.index.mainPageSessionKeys,
-    );
-    this.writeIndex();
+    nextMainPageSessionKeys = this.filterRecoverableMainPageSessionKeys(nextMainPageSessionKeys);
+    nextMainPageSessionKeys.forEach(sessionKey => {
+      if (this.getRecordForProviderSessionKey(sessionKey)) return;
+      this.ensureRecordForProviderSessionKey(sessionKey, {
+        archived: false,
+        lastSeenAt: now(),
+      });
+    });
+    this.writeIndex({ ...this.index, mainPageSessionKeys: nextMainPageSessionKeys });
+    this.legacyProviderSessionRecords = {};
   }
 
   reconcileProviderSessionIndex() {
-    const index = this.ensureIndex();
     const recordsByProviderKey = new Map();
     const records = this.listStoredAgentRecords();
     const successors = this.legacySuccessors(records);
@@ -166,16 +171,23 @@ class FarmingSessionStore {
     }
 
     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;
+      recordsByProviderKey.set(sessionKey, records[0].id);
+    }
+
+    for (const [sessionKey, id] of Object.entries(this.legacyProviderSessionRecords)) {
+      if (recordsByProviderKey.has(sessionKey)) continue;
+      const record = this.readRecord(id);
+      if (!record || successors.has(record.id)) continue;
+      if (record.providerSessionKey && record.providerSessionKey !== sessionKey) {
+        throw new Error(`Farming session ${id} is indexed as ${sessionKey} but bound to ${record.providerSessionKey}`);
       }
+      recordsByProviderKey.set(sessionKey, record.id);
     }
+    this.providerSessionRecords = recordsByProviderKey;
   }
 
   filterRecoverableMainPageSessionKeys(keys) {
@@ -197,6 +209,7 @@ class FarmingSessionStore {
     try {
       if (fs.existsSync(this.indexFile)) {
         const parsed = JSON.parse(fs.readFileSync(this.indexFile, 'utf8'));
+        this.legacyProviderSessionRecords = this.normalizeProviderSessionRecords(parsed?.providerSessionRecords);
         return this.normalizeIndex(parsed);
       }
     } catch (error) {
@@ -206,22 +219,25 @@ class FarmingSessionStore {
   }
 
   normalizeIndex(index) {
-    const providerSessionRecords = index && typeof index.providerSessionRecords === 'object' && !Array.isArray(index.providerSessionRecords)
-      ? index.providerSessionRecords
-      : {};
+    return {
+      version: SESSION_INDEX_VERSION,
+      mainPageSessionKeys: this.normalizeMainPageSessionKeys(index?.mainPageSessionKeys),
+      updatedAt: typeof index?.updatedAt === 'number' ? index.updatedAt : now(),
+    };
+  }
+
+  normalizeProviderSessionRecords(providerSessionRecords) {
     const normalizedProviderSessionRecords = {};
-    Object.entries(providerSessionRecords).forEach(([key, id]) => {
+    Object.entries(
+      providerSessionRecords && typeof providerSessionRecords === 'object' && !Array.isArray(providerSessionRecords)
+        ? providerSessionRecords
+        : {},
+    ).forEach(([key, id]) => {
       if (!parseProviderSessionKey(key)) return;
       if (!safeSessionFileName(id)) return;
       normalizedProviderSessionRecords[key] = id;
     });
-
-    return {
-      version: 1,
-      mainPageSessionKeys: this.normalizeMainPageSessionKeys(index?.mainPageSessionKeys),
-      providerSessionRecords: normalizedProviderSessionRecords,
-      updatedAt: typeof index?.updatedAt === 'number' ? index.updatedAt : now(),
-    };
+    return normalizedProviderSessionRecords;
   }
 
   ensureIndex() {
@@ -229,10 +245,11 @@ class FarmingSessionStore {
     return this.index;
   }
 
-  writeIndex() {
-    const index = this.ensureIndex();
-    index.updatedAt = now();
-    atomicWriteJson(this.indexFile, index);
+  writeIndex(index = this.ensureIndex()) {
+    const nextIndex = this.normalizeIndex({ ...index, updatedAt: now() });
+    this.writeJson(this.indexFile, nextIndex);
+    this.index = nextIndex;
+    return nextIndex;
   }
 
   sessionFile(id) {
@@ -308,10 +325,10 @@ class FarmingSessionStore {
   }
 
   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;
-    });
+    if (!previousId || previousId === nextId) return;
+    for (const [key, id] of this.providerSessionRecords) {
+      if (id === previousId) this.providerSessionRecords.set(key, nextId);
+    }
   }
 
   writeRecord(record) {
@@ -335,11 +352,11 @@ class FarmingSessionStore {
       || !sameJson(withoutUpdatedAt(existingState), withoutUpdatedAt(state));
     if (stateChanged) {
       state.updatedAt = now();
-      atomicWriteJson(this.agentStateFile(id), state);
+      this.writeJson(this.agentStateFile(id), state);
     }
     if (metadataChanged) {
       metadata.updatedAt = now();
-      atomicWriteJson(this.sessionFile(id), metadata);
+      this.writeJson(this.sessionFile(id), metadata);
     }
     if (promoted) this.promoteIndexRecordId(previousId, id);
     return id;
@@ -397,6 +414,8 @@ class FarmingSessionStore {
       projectWorkspace: typeof agent.projectWorkspace === 'string' ? agent.projectWorkspace : '',
       mainWorkspace: typeof agent.mainWorkspace === 'string' ? agent.mainWorkspace : '',
       source: typeof agent.source === 'string' ? agent.source : '',
+      parentAgentId: typeof agent.parentAgentId === 'string' ? agent.parentAgentId : '',
+      forkRequestId: typeof agent.forkRequestId === 'string' ? agent.forkRequestId : '',
       provider: parsed ? parsed.provider : (typeof agent.providerSessionProvider === 'string' ? agent.providerSessionProvider : ''),
       providerHomeId: parsed ? parsed.providerHomeId : (typeof agent.providerHomeId === 'string' ? agent.providerHomeId : ''),
       providerHomePath: typeof agent.providerHomePath === 'string' ? agent.providerHomePath : '',
@@ -407,6 +426,9 @@ class FarmingSessionStore {
       providerSessionResolvedAt: typeof agent.providerSessionResolvedAt === 'number' ? agent.providerSessionResolvedAt : null,
       providerSessionTitle: typeof agent.providerSessionTitle === 'string' ? agent.providerSessionTitle : '',
       providerSessionWorkspace: typeof agent.providerSessionWorkspace === 'string' ? agent.providerSessionWorkspace : '',
+      forkedFromProviderSessionId: typeof agent.forkedFromProviderSessionId === 'string'
+        ? agent.forkedFromProviderSessionId
+        : '',
       terminalInputReceived: agent.terminalInputReceived === true,
       structuredRuntimeProcess: agent.structuredRuntimeProcess
         && typeof agent.structuredRuntimeProcess === 'object'
@@ -435,6 +457,9 @@ class FarmingSessionStore {
       attentionOutputSeq: typeof agent.attentionOutputSeq === 'number' ? agent.attentionOutputSeq : null,
       readOutputEpoch: typeof agent.readOutputEpoch === 'string' ? agent.readOutputEpoch : '',
       readOutputSeq: typeof agent.readOutputSeq === 'number' ? agent.readOutputSeq : null,
+      composerCommands: Array.isArray(agent.composerCommands)
+        ? cloneJson(agent.composerCommands)
+        : [],
       archived: agent.archived === true,
       archivedAt: typeof agent.archivedAt === 'number' ? agent.archivedAt : null,
       ...(typeof agent.customTitle === 'string' && agent.customTitle
@@ -452,8 +477,8 @@ class FarmingSessionStore {
   ensureRecordForProviderSessionKey(sessionKey, patch = {}, preferredId = '') {
     const parsed = parseProviderSessionKey(sessionKey);
     if (!parsed) return '';
-    const index = this.ensureIndex();
-    const existingId = index.providerSessionRecords[sessionKey];
+    this.ensureIndex();
+    const existingId = this.providerSessionRecords.get(sessionKey);
     const normalizedPreferredId = safeSessionFileName(preferredId) ? preferredId : '';
     const preferredRecord = normalizedPreferredId ? this.readRecord(normalizedPreferredId) : null;
     if (
@@ -485,15 +510,15 @@ class FarmingSessionStore {
       providerSessionTemporary: false,
       updatedAt: now(),
     };
+    delete record.visibleOnMainPage;
     if (typeof record.customTitle === 'string' && record.customTitle) {
       record.title = record.customTitle;
     }
-    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();
+    for (const [key, recordId] of this.providerSessionRecords) {
+      if (key !== sessionKey && recordId === writtenId) this.providerSessionRecords.delete(key);
+    }
+    this.providerSessionRecords.set(sessionKey, writtenId);
     return writtenId;
   }
 
@@ -536,7 +561,7 @@ class FarmingSessionStore {
             mergedInto: id,
             updatedAt: now(),
           });
-          if (mergedId && mergedId !== previousId) this.writeIndex();
+          if (mergedId && mergedId !== previousId) this.promoteIndexRecordId(previousId, mergedId);
         }
       }
       return id;
@@ -569,23 +594,21 @@ class FarmingSessionStore {
   rememberMainPageSessionKey(sessionKey, patch = {}) {
     const id = this.ensureRecordForProviderSessionKey(sessionKey, {
       ...patch,
-      visibleOnMainPage: true,
       archived: false,
       lastSeenAt: now(),
     });
     if (!id) return this.getMainPageSessionKeys();
     const index = this.ensureIndex();
-    index.mainPageSessionKeys = this.normalizeMainPageSessionKeys([
+    const nextIndex = this.writeIndex({ ...index, mainPageSessionKeys: this.normalizeMainPageSessionKeys([
       sessionKey,
       ...index.mainPageSessionKeys.filter(key => key !== sessionKey),
-    ]);
-    this.writeIndex();
-    return index.mainPageSessionKeys.slice();
+    ]) });
+    return nextIndex.mainPageSessionKeys.slice();
   }
 
   rememberAgent(agent) {
     const providerSessionKey = this.providerSessionKeyForAgent(agent);
-    const id = this.ensureRecordForAgent(agent, providerSessionKey ? { visibleOnMainPage: true, archived: false } : {});
+    const id = this.ensureRecordForAgent(agent, providerSessionKey ? { archived: false } : {});
     if (providerSessionKey) {
       this.rememberMainPageSessionKey(providerSessionKey, this.recordPatchFromAgent(agent));
     }
@@ -595,54 +618,33 @@ class FarmingSessionStore {
   setMainPageSessionKeys(keys) {
     const normalized = this.normalizeMainPageSessionKeys(keys);
     const index = this.ensureIndex();
-    const visible = new Set(normalized);
     normalized.forEach(key => {
       this.ensureRecordForProviderSessionKey(key, {
-        visibleOnMainPage: true,
         archived: false,
         lastSeenAt: now(),
       });
     });
-    index.mainPageSessionKeys.forEach(key => {
-      if (visible.has(key)) return;
-      const id = index.providerSessionRecords[key];
-      const existing = this.readRecord(id);
-      if (existing) {
-        const writtenId = this.writeRecord({
-          ...existing,
-          visibleOnMainPage: false,
-          updatedAt: now(),
-        });
-        if (writtenId) index.providerSessionRecords[key] = writtenId;
-      }
-    });
-    index.mainPageSessionKeys = normalized;
-    this.writeIndex();
-    return normalized.slice();
+    return this.writeIndex({ ...index, mainPageSessionKeys: normalized }).mainPageSessionKeys.slice();
   }
 
   removeMainPageSessionKey(sessionKey) {
     const index = this.ensureIndex();
     if (!index.mainPageSessionKeys.includes(sessionKey)) return false;
-    index.mainPageSessionKeys = index.mainPageSessionKeys.filter(key => key !== sessionKey);
-    const id = index.providerSessionRecords[sessionKey];
-    const existing = this.readRecord(id);
-    if (existing) {
-      const writtenId = this.writeRecord({
-        ...existing,
-        visibleOnMainPage: false,
-        updatedAt: now(),
-      });
-      if (writtenId) index.providerSessionRecords[sessionKey] = writtenId;
-    }
-    this.writeIndex();
+    this.writeIndex({
+      ...index,
+      mainPageSessionKeys: index.mainPageSessionKeys.filter(key => key !== sessionKey),
+    });
     return true;
   }
 
   removeMainPageSessionKeys(keys) {
-    const removed = [];
-    keys.forEach(key => {
-      if (this.removeMainPageSessionKey(key)) removed.push(key);
+    const index = this.ensureIndex();
+    const requested = new Set(Array.isArray(keys) ? keys : []);
+    const removed = index.mainPageSessionKeys.filter(key => requested.has(key));
+    if (removed.length === 0) return [];
+    this.writeIndex({
+      ...index,
+      mainPageSessionKeys: index.mainPageSessionKeys.filter(key => !requested.has(key)),
     });
     return removed;
   }
@@ -652,8 +654,8 @@ class FarmingSessionStore {
   }
 
   getRecordForProviderSessionKey(sessionKey) {
-    const index = this.ensureIndex();
-    const id = index.providerSessionRecords[sessionKey];
+    this.ensureIndex();
+    const id = this.providerSessionRecords.get(sessionKey);
     return safeSessionFileName(id) ? this.readRecord(id) : null;
   }
 
@@ -670,5 +672,6 @@ module.exports = {
   AGENT_STATE_VERSION,
   FarmingSessionStore,
   MAX_MAIN_PAGE_SESSION_KEYS,
+  SESSION_INDEX_VERSION,
   parseProviderSessionKey,
 };

package/backend/main-agent-skills.js

@@ -57,6 +57,22 @@ const MAIN_AGENT_OPERATING_GUIDE = [
 ];
 
 const MAIN_AGENT_SKILLS = [
+  {
+    id: 'browser-resource',
+    name: '系统浏览器操作',
+    trigger: '用户要求打开、查看或操作 Farming Project 下的 Browser Resource，或者需要绕过静态 HTML Viewer 限制验证真实网页时',
+    summary: '通过 Farming Browser ID 操作用户当前看到的同一个 Headless 系统浏览器；先 Snapshot 获取当前 Ref，再进行点击或输入，页面变化后重新 Snapshot。',
+    commands: [
+      'farming browser list --workspace <repo>',
+      'farming browser start <browser-id>',
+      'farming browser snapshot <browser-id>',
+      'farming browser navigate <browser-id> <url>',
+      'farming browser click <browser-id> <ref-or-css=selector>',
+      'farming browser fill <browser-id> <ref-or-css=selector> <text>',
+      'farming browser screenshot <browser-id> <output.png>',
+      'farming browser stop <browser-id>',
+    ],
+  },
   {
     id: 'memory-report',
     name: '记忆读取总结',
@@ -137,6 +153,7 @@ function renderMainAgentSkills() {
   });
 
   lines.push('Rules:');
+  lines.push('- Use `farming browser` only for Browser Resources already in the user-selected Project scope; take a new snapshot after navigation or DOM-changing actions.');
   lines.push('- Use `farming memory report` when you need recent context from local agent memories.');
   lines.push('- Use “牧场除虫计划” when the user asks for systematic bug hunting across a directory or module tree.');
   lines.push('- Before spawning child agents for pest control, map modules and module protocols first; do not send overlapping or vague tasks.');

package/backend/native-pty-host-client.js

@@ -4,7 +4,10 @@ const crypto = require('crypto');
 const fs = require('fs');
 const net = require('net');
 const path = require('path');
-const { nativePtyHostSocketPath } = require('./native-pty-host-path');
+const {
+  nativePtyHostPrivateSocketNamePattern,
+  nativePtyHostSocketPath,
+} = require('./native-pty-host-path');
 const {
   nativePtyHostRuntimeIdentity,
   nativePtyHostRuntimeIdentityMatches,
@@ -17,6 +20,7 @@ const {
 const { isTemporaryProviderSessionId } = require('./provider-session-id');
 const storageLayout = require('./storage-layout');
 const { deserializeTerminalState } = require('./terminal-state-serialization');
+const { probeUnixSocket } = require('./terminal-runtime-cleanup');
 
 const DEFAULT_CONNECT_RETRIES = 300;
 const DEFAULT_CONNECT_RETRY_MS = 50;
@@ -184,6 +188,7 @@ class NativePtyHostClient extends EventEmitter {
     this.controllerIdentityReady = null;
     this.hostRotationTimeoutMs = options.hostRotationTimeoutMs || DEFAULT_HOST_ROTATION_TIMEOUT_MS;
     this.connectedHostInfo = null;
+    this.connectedSocketPath = '';
     this.runtimeRotationInfo = null;
     this.socket = null;
     this.socketGeneration = 0;
@@ -235,7 +240,85 @@ class NativePtyHostClient extends EventEmitter {
 
   canConnectWithoutStartingHost() {
     if (process.platform === 'win32') return true;
-    return fs.existsSync(this.socketPath);
+    return fs.existsSync(this.socketPath) || this.privateSocketCandidates().length > 0;
+  }
+
+  privateSocketCandidates() {
+    if (process.platform === 'win32') return [];
+    const directory = path.dirname(this.socketPath);
+    const pattern = nativePtyHostPrivateSocketNamePattern(this.socketPath);
+    try {
+      return fs.readdirSync(directory)
+        .filter(name => pattern.test(name))
+        .map(name => path.join(directory, name));
+    } catch (error) {
+      if (error?.code === 'ENOENT') return [];
+      throw error;
+    }
+  }
+
+  connectedPrivateSocketPath(hostInfo = {}) {
+    if (process.platform === 'win32') return '';
+    if (typeof hostInfo.privateSocketPath === 'string' && hostInfo.privateSocketPath) {
+      return hostInfo.privateSocketPath;
+    }
+    if (!this.connectedSocketPath || this.connectedSocketPath !== this.socketPath) {
+      return this.connectedSocketPath;
+    }
+
+    let publicIdentity;
+    try {
+      const stat = fs.statSync(this.socketPath, { bigint: true });
+      publicIdentity = { dev: stat.dev, ino: stat.ino };
+    } catch (error) {
+      if (error?.code === 'ENOENT') return '';
+      throw error;
+    }
+
+    const matching = this.privateSocketCandidates().filter((candidate) => {
+      try {
+        const stat = fs.statSync(candidate, { bigint: true });
+        return stat.dev === publicIdentity.dev && stat.ino === publicIdentity.ino;
+      } catch (error) {
+        if (error?.code === 'ENOENT') return false;
+        throw error;
+      }
+    });
+    return matching.length === 1 ? matching[0] : '';
+  }
+
+  async resolveConnectSocketPath() {
+    if (process.platform === 'win32' || fs.existsSync(this.socketPath)) {
+      return this.socketPath;
+    }
+    const active = [];
+    for (const candidate of this.privateSocketCandidates()) {
+      const probe = await probeUnixSocket(candidate);
+      if (probe.active) active.push(candidate);
+    }
+    if (active.length > 1) {
+      const error = new Error('Multiple live native PTY hosts were found for this Farming config');
+      error.code = 'FARMING_NATIVE_HOST_AMBIGUOUS';
+      error.socketPaths = active;
+      throw error;
+    }
+    return active[0] || this.socketPath;
+  }
+
+  restorePublicSocketPath(connectedPath) {
+    if (
+      process.platform === 'win32'
+      || !connectedPath
+      || connectedPath === this.socketPath
+      || fs.existsSync(this.socketPath)
+    ) {
+      return;
+    }
+    try {
+      fs.linkSync(connectedPath, this.socketPath);
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+    }
   }
 
   spawnHost() {
@@ -288,9 +371,10 @@ class NativePtyHostClient extends EventEmitter {
     });
   }
 
-  connectOnce() {
+  async connectOnce() {
+    const connectedPath = await this.resolveConnectSocketPath();
     return new Promise((resolve, reject) => {
-      const socket = net.createConnection(this.socketPath);
+      const socket = net.createConnection(connectedPath);
       const onError = (error) => {
         socket.destroy();
         reject(error);
@@ -298,6 +382,8 @@ class NativePtyHostClient extends EventEmitter {
       socket.once('error', onError);
       socket.once('connect', () => {
         socket.off('error', onError);
+        this.restorePublicSocketPath(connectedPath);
+        this.connectedSocketPath = connectedPath;
         this.attachSocket(socket);
         resolve();
       });
@@ -373,6 +459,9 @@ class NativePtyHostClient extends EventEmitter {
         if (error && error.code === 'FARMING_NATIVE_HOST_RUNTIME_MISMATCH') {
           throw error;
         }
+        if (error && error.code === 'FARMING_NATIVE_HOST_AMBIGUOUS') {
+          throw error;
+        }
         if (this.hostStartError) {
           lastError = this.hostStartError;
         }
@@ -427,7 +516,7 @@ class NativePtyHostClient extends EventEmitter {
     return this.controllerIdentityReady;
   }
 
-  async waitForHostRelease() {
+  async waitForHostRelease(privateSocketPath = '') {
     const deadline = Date.now() + this.hostRotationTimeoutMs;
     if (process.platform === 'win32') {
       await delay(Math.min(250, this.hostRotationTimeoutMs));
@@ -437,7 +526,8 @@ class NativePtyHostClient extends EventEmitter {
       const childReleased = !this.hostChild ||
         this.hostChild.exitCode !== null ||
         this.hostChild.signalCode !== null;
-      if (!fs.existsSync(this.socketPath) && childReleased) return;
+      const privateReleased = !privateSocketPath || !fs.existsSync(privateSocketPath);
+      if (!fs.existsSync(this.socketPath) && privateReleased && childReleased) return;
       await delay(50);
     }
     const error = new Error('Timed out waiting for the previous native PTY host to stop');
@@ -589,6 +679,7 @@ class NativePtyHostClient extends EventEmitter {
       throw mismatchError;
     }
 
+    const privateSocketPath = this.connectedPrivateSocketPath(hostInfo);
     const socket = this.socket;
     if (socket) this.suppressedDisconnectSockets.add(socket);
     let shutdownUncertain = false;
@@ -622,7 +713,7 @@ class NativePtyHostClient extends EventEmitter {
     }
 
     try {
-      await this.waitForHostRelease();
+      await this.waitForHostRelease(privateSocketPath || this.connectedSocketPath);
     } catch (error) {
       if (shutdownUncertain) {
         try {
@@ -674,6 +765,7 @@ class NativePtyHostClient extends EventEmitter {
     this.socket = null;
     this.buffer = '';
     this.connectedHostInfo = null;
+    this.connectedSocketPath = '';
     if (this.disposed) return;
     const error = new Error('Native pty host disconnected');
     error.code = 'ECONNRESET';

package/backend/native-pty-host-path.js

@@ -17,6 +17,26 @@ function nativePtyHostSocketPath(configDir) {
   return path.join(os.tmpdir(), `farming-native-pty-${process.getuid ? process.getuid() : 'user'}-${hash}.sock`);
 }
 
+function nativePtyHostPrivateSocketHash(socketPath) {
+  return crypto.createHash('sha256').update(socketPath).digest('hex').slice(0, 8);
+}
+
+function nativePtyHostPrivateSocketPath(socketPath, options = {}) {
+  const pid = Number(options.pid || process.pid);
+  const nonce = String(options.nonce || crypto.randomBytes(4).toString('hex'));
+  return path.join(
+    path.dirname(socketPath),
+    `.fpty-${pid}-${nativePtyHostPrivateSocketHash(socketPath)}-${nonce}.sock`,
+  );
+}
+
+function nativePtyHostPrivateSocketNamePattern(socketPath) {
+  const hash = nativePtyHostPrivateSocketHash(socketPath);
+  return new RegExp(`^\\.fpty-\\d+-${hash}-[a-f0-9]+\\.sock$`);
+}
+
 module.exports = {
+  nativePtyHostPrivateSocketNamePattern,
+  nativePtyHostPrivateSocketPath,
   nativePtyHostSocketPath,
 };

package/backend/native-pty-host.js

@@ -7,7 +7,10 @@ const os = require('os');
 const path = require('path');
 
 const TerminalScreenWorkerPool = require('./terminal-screen-worker-pool');
-const { nativePtyHostSocketPath } = require('./native-pty-host-path');
+const {
+  nativePtyHostPrivateSocketPath,
+  nativePtyHostSocketPath,
+} = require('./native-pty-host-path');
 const { terminalInputToPtyString } = require('./input-parts');
 const { normalizeInteractiveTerminalEnv } = require('./agent-env');
 const {
@@ -95,10 +98,7 @@ class NativePtyHost {
     this.exitOnShutdown = options.exitOnShutdown !== false;
     this.boundSocketPath = process.platform === 'win32'
       ? this.socketPath
-      : path.join(
-          path.dirname(this.socketPath),
-          `.fpty-${process.pid}-${crypto.createHash('sha256').update(this.socketPath).digest('hex').slice(0, 8)}-${crypto.randomBytes(4).toString('hex')}.sock`,
-        );
+      : nativePtyHostPrivateSocketPath(this.socketPath);
     this.boundSocketIdentity = null;
     this.sessions = new Map();
     this.clients = new Set();
@@ -347,6 +347,7 @@ class NativePtyHost {
         return {
           ok: true,
           pid: process.pid,
+          privateSocketPath: process.platform === 'win32' ? '' : this.boundSocketPath,
           runtimeIdentity: this.runtimeIdentity,
         };
       case 'registerController':