@michelj/context-guard 0.6.3 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michelj/context-guard",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Next-generation collaboration layer for humans and coding agents on Codex, Cursor, and Claude.",
   "repository": {
     "type": "git",
@@ -56,8 +56,8 @@
     "node": ">=18"
   },
   "devDependencies": {
-    "@michelj/context-guard-core": "https://github.com/Michel-Johnson/Context-Guard-Cloud/releases/download/shared-v1.1.1/michelj-context-guard-core-1.1.1.tgz",
-    "@michelj/context-guard-workbench": "https://github.com/Michel-Johnson/Context-Guard-Cloud/releases/download/shared-v1.1.1/michelj-context-guard-workbench-1.1.1.tgz",
+    "@michelj/context-guard-core": "https://github.com/Michel-Johnson/Context-Guard-Cloud/releases/download/shared-v1.1.2/michelj-context-guard-core-1.1.2.tgz",
+    "@michelj/context-guard-workbench": "https://github.com/Michel-Johnson/Context-Guard-Cloud/releases/download/shared-v1.1.2/michelj-context-guard-workbench-1.1.2.tgz",
     "marked": "15.0.12",
     "playwright": "1.62.1"
   }

package/prototype/workbench-sync.mjs

@@ -117,6 +117,8 @@ export class WorkbenchSync {
     this.urlPinned = Boolean(requestedSession) && !this.config?.root?.startsWith('cloud:');
     this.panel = document.createElement('details'); this.panel.id = 'cg-sync'; this.panel.className = 'set-block sync-settings';
     this.panel.innerHTML = '<summary>同步与恢复</summary><p id="cg-sync-status"></p><span id="cg-sync-version" hidden></span><div class="sync-actions"><button id="cg-sync-initialize" hidden>将当前图设为真实地图</button><button id="cg-sync-retry">重试</button><button id="cg-sync-export">导出草稿/旧缓存</button><button id="cg-sync-import">导入并比较</button><button id="cg-sync-reload">保留草稿后读取磁盘</button></div><label>Agent 会话<select id="cg-sync-session"></select></label><input id="cg-sync-file" type="file" accept="application/json" hidden>';
+    this.cloudBindingNotice = document.createElement('p'); this.cloudBindingNotice.hidden = true;
+    this.cloudBindingNotice.setAttribute('role', 'status'); this.panel.querySelector('#cg-sync-status').after(this.cloudBindingNotice);
     this.repairButton = document.createElement('button'); this.repairButton.id = 'cg-sync-repair'; this.repairButton.hidden = true;
     this.panel.querySelector('.sync-actions').append(this.repairButton);
     if (this.config?.interfaceCapabilities?.deviceLogin && !this.config.root?.startsWith('cloud:')) {
@@ -764,12 +766,19 @@ export class WorkbenchSync {
     this.a.setAccess(active && !unavailableMeta ? this.grants?.[this.activeSession]?.nodes || [] : [], this.activeSession, active, this.activeSession === ALL_SESSIONS, this.project?.main || null);
   }
   renderCloudStatus(status) {
+    const bindingLabel = status?.configured && status.status === 'conflict'
+      ? status.reason === 'session-bound-elsewhere' ? '当前会话绑定旧设备，请新建会话'
+        : status.reason === 'binding-conflict' ? '会话绑定冲突，请新建会话' : ''
+      : '';
+    if (this.cloudBindingNotice) {
+      this.cloudBindingNotice.hidden = !bindingLabel; this.cloudBindingNotice.textContent = bindingLabel;
+    }
     if (!this.cloudIndicator) return;
     if (!status?.configured) { this.cloudIndicator.hidden = true; return; }
     const value = status.status === 'synced' ? 'synced' : ['conflict', 'error'].includes(status.status) ? status.status : 'syncing';
     this.cloudIndicator.hidden = false; this.cloudIndicator.className = `cloud-sync-status ${value}`;
-    const label = value === 'synced' ? '云端已同步' : value === 'syncing' ? '云端同步中' : value === 'conflict' ? '云端同步冲突' : '云端同步失败';
-    this.cloudIndicator.setAttribute('aria-label', label); this.cloudIndicator.title = label;
+    const label = bindingLabel || (value === 'synced' ? '云端已同步' : value === 'syncing' ? '云端同步中' : value === 'conflict' ? '云端同步冲突' : '云端同步失败');
+    this.cloudIndicator.setAttribute('aria-label', label); this.cloudIndicator.title = bindingLabel ? `${label}；旧记录与队列保持不变` : label;
   }
   async refreshCloudStatus() {
     if (this.config?.root?.startsWith('cloud:')) { this.renderCloudStatus({ configured: true, status: this.pendingSession ? 'syncing' : 'synced' }); return; }

package/references/cloud-sync-interface.md

@@ -61,6 +61,13 @@ Network failure leaves current queues on disk. Reconnect retries with backoff;
 conflicts require explicit reconciliation. Do not manufacture a new request ID,
 erase private state or report success merely because a connection is alive.
 
+A confirmed Session-binding rejection stops automatic binding retries. When a
+Session belongs to another device, create a new actual conversation in the host
+and connect using that host-issued Session ID. Do not take over the old Session,
+alias/change its ID, discard its failed receipt or move its tasks/queues to the
+new conversation. Older binding-conflict receipts cannot prove which device owns
+the Session; they also require a new host conversation, not blind retries.
+
 The private Session service uses authorized `/v1/projects/:project/sessions/`
 reads, changes/events and map writes. Session generations and server authorization
 remain enforced. Credentials never belong in Maps, logs or generated HTML.

package/scripts/shared/protocol-store.mjs

@@ -465,7 +465,8 @@ export class ProtocolStore extends EventEmitter {
           previous.sessionId = payload.sessionId;
           return { session: { id: payload.sessionId, generation: previous.generation }, bindingVersion: previous.version };
         }
-        if (previous && (!options.allowMigration || previous.deviceId !== p.deviceId || payload.expectedBindingVersion !== previous.version)) fail('CONFLICT', 'Migration requires the owning device and current binding version', { currentVersion: previous.version });
+        if (previous && previous.deviceId !== p.deviceId) fail('CONFLICT', 'Session is already bound to another device', { reason: 'session-bound-elsewhere' });
+        if (previous && (!options.allowMigration || payload.expectedBindingVersion !== previous.version)) fail('CONFLICT', 'Migration requires the owning device and current binding version', { currentVersion: previous.version });
         if (!previous && payload.expectedBindingVersion) fail('CONFLICT', 'Binding does not exist', { currentVersion: '' });
         const binding = { sessionId: payload.sessionId, deviceId: p.deviceId, agentId: payload.agentId, worktreeId: payload.worktreeId, generation: (previous?.generation || 0) + 1, version: randomUUID() };
         for (const creation of Object.values(state.sessionCreations || {})) {

package/scripts/workbench/browser-login.mjs

@@ -10,7 +10,11 @@ async function request(origin, route, input, fetcher, timeoutMs = 15000) {
   try {
     response = await fetcher(new URL(route, origin), { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
       headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input) });
-  } catch { fail('UNAVAILABLE', 'Cloud authorization is unavailable; retry the same connection command'); }
+  } catch (error) {
+    const beforeConnection = ['ENOTFOUND', 'ECONNREFUSED', 'UND_ERR_CONNECT_TIMEOUT'].includes(error?.cause?.code || error?.code);
+    fail('UNAVAILABLE', route.endsWith('/poll') && !beforeConnection ? 'Authorization claim outcome is unknown; explicitly retry browser authorization' : 'Cloud authorization is unavailable; retry the same connection command',
+      { retryableConnection: route.endsWith('/start') || beforeConnection });
+  }
   if ([404, 405, 426].includes(response.status)) fail('UPGRADE_REQUIRED', 'Cloud does not support browser authorization; upgrade Cloud or use the explicit private-input login');
   if (!response.headers.get('content-type')?.includes('application/json')) fail('UNAVAILABLE', 'Cloud returned an invalid authorization reply');
   let result;
@@ -19,7 +23,8 @@ async function request(origin, route, input, fetcher, timeoutMs = 15000) {
     for await (const chunk of response.body) { size += chunk.length; if (size > 16384) fail('TOO_LARGE', 'Authorization reply is too large'); chunks.push(chunk); }
     result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
   } catch (error) { if (error.code === 'TOO_LARGE') throw error; fail('UNAVAILABLE', 'Cloud authorization reply was interrupted'); }
-  if (!response.ok || result?.ok !== true) fail(result?.error?.code || 'UNAVAILABLE', result?.error?.message || 'Cloud authorization failed');
+  if (!response.ok || result?.ok !== true) fail(result?.error?.code || 'UNAVAILABLE', result?.error?.message || 'Cloud authorization failed',
+    { retryableConnection: [502, 503, 504].includes(response.status) && result?.error?.code === 'UNAVAILABLE' && result.error.retryable === true });
   if (!result.data || typeof result.data !== 'object') fail('UNAVAILABLE', 'Cloud returned an invalid authorization reply');
   return { data: result.data, credential: response.headers.get('x-context-guard-credential') };
 }
@@ -32,15 +37,22 @@ export async function browserLogin(device, { repository, repositoryId, wait = fa
   const file = path.join(device.directory, 'browser-login.json');
   let deadline = clock() + 600000, grant;
   const checkDeadline = () => {
-    if (wait && clock() >= deadline) fail('UNAUTHORIZED', 'Browser authorization expired; retry the connection command');
+    if (wait && clock() >= deadline) fail('UNAUTHORIZED', 'Browser authorization expired; retry the connection command', { reason: 'authorization-wait-expired' });
   };
   const authorize = async (route, input) => {
-    checkDeadline();
-    try {
-      const result = await request(device.origin, route, input, fetcher, wait ? Math.max(1, Math.min(15000, Math.ceil(deadline - clock()))) : 15000);
+    for (let attempt = 0; attempt < 3; attempt++) {
       checkDeadline();
-      return result;
-    } catch (error) { checkDeadline(); throw error; }
+      try {
+        const result = await request(device.origin, route, input, fetcher, wait ? Math.max(1, Math.min(15000, Math.ceil(deadline - clock()))) : 15000);
+        checkDeadline();
+        return result;
+      } catch (error) {
+        checkDeadline();
+        if (attempt === 2 || error.code !== 'UNAVAILABLE' || error.details?.retryableConnection !== true) throw error;
+        await sleep(wait ? Math.min(250 * 2 ** attempt, Math.max(1, deadline - clock())) : 250 * 2 ** attempt);
+        checkDeadline();
+      }
+    }
   };
   let first = true;
   for (;;) {
@@ -85,7 +97,7 @@ export async function browserLogin(device, { repository, repositoryId, wait = fa
       let result;
       try { result = await authorize('/api/auth/device/poll', { deviceCode: pending.deviceCode }); }
       catch (error) {
-        if (['UNAUTHORIZED', 'FORBIDDEN'].includes(error.code)) await atomicWrite(file, encode({ status: error.code }));
+        if (['UNAUTHORIZED', 'FORBIDDEN'].includes(error.code) && error.details?.reason !== 'authorization-wait-expired') await atomicWrite(file, encode({ status: error.code }));
         throw error;
       }
       if (result.data.status === 'pending') return safe;

package/scripts/workbench/claude-runtime.mjs

@@ -292,6 +292,68 @@ export class ClaudeRuntime {
   }
 }
 
+// Monitor an already-created native process. The worker calls this immediately
+// after spawn; it does not wait for a model-specific readiness handshake.
+export async function runClaudeTurn(child, { config, sessionId, message, logFile, onStarted, onFinished }) {
+  const exit = new Promise((resolve, reject) => { child.once('close', resolve); child.once('error', reject); });
+  exit.catch(() => {}); // A spawn failure may precede opening the private log.
+  let buffer = '', bytes = 0, result = null, initialized = false, stopReason = null;
+  const decoder = new StringDecoder('utf8');
+  const output = await fs.open(logFile, 'a', 0o600);
+  let writes = Promise.resolve();
+  const idleMs = config.timeoutMs || 600000;
+  let idleTimer, killTimer;
+  const terminate = (reason = 'CLAUDE_TIMEOUT_OR_INTERRUPTED') => {
+    if (stopReason) return;
+    stopReason = reason; child.kill('SIGTERM');
+    killTimer = setTimeout(() => child.kill('SIGKILL'), 5000);
+  };
+  const active = () => { clearTimeout(idleTimer); idleTimer = setTimeout(terminate, idleMs); };
+  active();
+  // Activity keeps the idle timer alive, but cannot extend a native turn
+  // indefinitely. A stopped turn stays recoverable in the same Session.
+  const hardTimer = setTimeout(() => terminate('CLAUDE_TURN_LIMIT'), Math.max(idleMs, config.maxTurnMs || 1800000));
+  const interrupted = () => terminate();
+  const stdinError = () => {};
+  const receive = chunk => {
+    bytes += chunk.length;
+    if (bytes > (config.outputLimitBytes || 64 * 1024 * 1024)) { terminate('CLAUDE_OUTPUT_LIMIT'); return; }
+    active();
+    writes = writes.then(() => output.write(chunk));
+    buffer += decoder.write(chunk);
+    for (;;) {
+      const index = buffer.indexOf('\n'); if (index < 0) break;
+      const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+      try {
+        const event = JSON.parse(line);
+        if (event.session_id && event.session_id !== sessionId) { terminate('CLAUDE_SESSION_MISMATCH'); break; }
+        if (event.type === 'system' && event.subtype === 'init') initialized = true;
+        if (event.type === 'result') result = event;
+      } catch { /* Native diagnostic text is not a protocol receipt. */ }
+    }
+  };
+  process.once('SIGTERM', interrupted); process.once('SIGINT', interrupted);
+  child.stdout.on('data', receive);
+  child.stderr.on('data', active); // Activity only; never publish provider stderr or credentials.
+  child.stdin.on('error', stdinError);
+  try {
+    child.stdin.end(message);
+    await onStarted?.(); // Same point as the worker's original running update.
+    const code = await exit;
+    await writes; await output.sync();
+    const outcome = { state: stopReason || !result ? 'interrupted' : code === 0 && !result.is_error ? 'finished' : 'failed',
+      error: stopReason || (!result ? 'CLAUDE_NO_RESULT' : result.is_error ? 'CLAUDE_FAILED' : null), initialized };
+    await onFinished?.(outcome); // Preserve persistence before timer/log cleanup.
+    return outcome;
+  } finally {
+    clearTimeout(idleTimer); clearTimeout(hardTimer); clearTimeout(killTimer);
+    process.removeListener('SIGTERM', interrupted); process.removeListener('SIGINT', interrupted);
+    child.stdout.removeListener('data', receive); child.stderr.removeListener('data', active);
+    child.stdin.removeListener('error', stdinError);
+    await output.close();
+  }
+}
+
 async function runWorker(file, jobFile) {
   const session = await readJSON(file), config = session.config;
   const job = await readJSON(jobFile);
@@ -303,66 +365,24 @@ async function runWorker(file, jobFile) {
   // Written before spawning Claude. A crash after this point is uncertain, not
   // permission to submit the same prompt again.
   await update({ workerPid: process.pid, state: 'dispatching' });
-  let child, stopReason = null;
   try {
     const credentials = await readJSON(config.environmentFile);
     if (Object.keys(credentials).some(key => !providerKeys.has(key)) || Object.values(credentials).some(value => typeof value !== 'string')) fail('INVALID_ENVIRONMENT', 'Only provider settings are accepted in the private environment file');
     const env = await claudeEnvironment(config, credentials);
-    child = spawn(config.command, claudeArguments(config, { sessionId: session.sessionId, resume: job.resume }), {
+    const child = spawn(config.command, claudeArguments(config, { sessionId: session.sessionId, resume: job.resume }), {
       cwd: config.root, env, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
     });
-    const exit = new Promise((resolve, reject) => { child.once('close', resolve); child.once('error', reject); });
-    exit.catch(() => {}); // A spawn failure may precede opening the private log.
-    let buffer = '', bytes = 0, result = null, initialized = false;
-    const decoder = new StringDecoder('utf8');
-    const output = await fs.open(jobFile + '.jsonl', 'a', 0o600);
-    let writes = Promise.resolve();
-    const idleMs = config.timeoutMs || 600000;
-    let idleTimer, killTimer;
-    const terminate = (reason = 'CLAUDE_TIMEOUT_OR_INTERRUPTED') => {
-      if (stopReason) return;
-      stopReason = reason; child.kill('SIGTERM');
-      killTimer = setTimeout(() => child.kill('SIGKILL'), 5000);
-    };
-    const active = () => { clearTimeout(idleTimer); idleTimer = setTimeout(terminate, idleMs); };
-    active();
-    // Activity keeps the idle timer alive, but cannot extend a native turn
-    // indefinitely. A stopped turn stays recoverable in the same Session.
-    const hardTimer = setTimeout(() => terminate('CLAUDE_TURN_LIMIT'), Math.max(idleMs, config.maxTurnMs || 1800000));
-    const interrupted = () => terminate();
-    process.once('SIGTERM', interrupted); process.once('SIGINT', interrupted);
-    child.stdout.on('data', chunk => {
-      bytes += chunk.length;
-      if (bytes > (config.outputLimitBytes || 64 * 1024 * 1024)) { terminate('CLAUDE_OUTPUT_LIMIT'); return; }
-      active();
-      writes = writes.then(() => output.write(chunk));
-      buffer += decoder.write(chunk);
-      for (;;) {
-        const index = buffer.indexOf('\n'); if (index < 0) break;
-        const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
-        try {
-          const event = JSON.parse(line);
-          if (event.session_id && event.session_id !== session.sessionId) { terminate('CLAUDE_SESSION_MISMATCH'); break; }
-          if (event.type === 'system' && event.subtype === 'init') initialized = true;
-          if (event.type === 'result') result = event;
-        } catch { /* Native diagnostic text is not a protocol receipt. */ }
-      }
+    await runClaudeTurn(child, { config, sessionId: session.sessionId, message: job.message,
+      logFile: jobFile + '.jsonl', onStarted: () => update({ state: 'running', childPid: child.pid }),
+      onFinished: async ({ initialized, ...outcome }) => {
+        await update(outcome);
+        await withFileLock(file + '.lock', async () => {
+          const latest = await readJSON(file);
+          await atomicWrite(file, encode({ ...latest, initialized: latest.initialized || initialized,
+            ...(['finished', 'failed'].includes(job.state) ? { active: null } : {}), updatedAt: job.updatedAt }));
+        });
+      },
     });
-    child.stderr.on('data', active); // Activity only; never publish provider stderr or credentials.
-    child.stdin.on('error', () => {});
-    child.stdin.end(job.message);
-    try {
-      await update({ state: 'running', childPid: child.pid });
-      const code = await exit;
-      await writes; await output.sync();
-      await update({ state: stopReason || !result ? 'interrupted' : code === 0 && !result.is_error ? 'finished' : 'failed',
-        error: stopReason || (!result ? 'CLAUDE_NO_RESULT' : result.is_error ? 'CLAUDE_FAILED' : null) });
-      await withFileLock(file + '.lock', async () => {
-        const latest = await readJSON(file);
-        await atomicWrite(file, encode({ ...latest, initialized: latest.initialized || initialized,
-          ...(['finished', 'failed'].includes(job.state) ? { active: null } : {}), updatedAt: job.updatedAt }));
-      });
-    } finally { clearTimeout(idleTimer); clearTimeout(hardTimer); clearTimeout(killTimer); await output.close(); }
   } catch (error) { await update({ state: 'interrupted', error: String(error.code || 'CLAUDE_LAUNCH_FAILED').slice(0, 100) }); }
 }
 

package/scripts/workbench/listen.mjs

@@ -0,0 +1,5 @@
+export function canRetryWorkbenchListen(error, port, attempt, platform = process.platform) {
+  if (port === 0 || attempt >= 20) return false;
+  return error?.code === 'EADDRINUSE' || platform === 'win32' && error?.code === 'EACCES'
+    && error.syscall === 'listen' && error.address === '127.0.0.1' && error.port === port + attempt;
+}

package/scripts/workbench/named-proxy.mjs

@@ -6,6 +6,7 @@ import { randomBytes } from 'node:crypto';
 import { atomicWrite, encode, readJSON } from '../shared/io.mjs';
 import { RouteStore } from './portless-routes.mjs';
 import { compatibleRuntime } from './runtime.mjs';
+import { canRetryWorkbenchListen } from './listen.mjs';
 import { DeviceHeartbeat } from './device-heartbeat.mjs';
 
 const secret = () => randomBytes(32).toString('base64url');
@@ -81,8 +82,16 @@ export async function startNamedProxy({ dir, port = 1355 } = {}) {
   server.on('upgrade', (_req, socket) => socket.destroy()); // Workbench uses SSE, not WebSockets.
   server.requestTimeout = 15000; server.headersTimeout = 10000;
   for (let attempt = 0; ; attempt++) {
-    try { await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port ? port + attempt : 0, '127.0.0.1', () => { server.removeListener('error', reject); resolve(); }); }); break; }
-    catch (e) { server.removeAllListeners('error'); if (e.code !== 'EADDRINUSE' || !port || attempt >= 20) throw e; }
+    try {
+      await new Promise((resolve, reject) => {
+        const onListening = () => { server.off('error', onError); resolve(); };
+        const onError = error => { server.off('error', onError); server.off('listening', onListening); reject(error); };
+        server.once('error', onError);
+        try { server.listen(port ? port + attempt : 0, '127.0.0.1', onListening); }
+        catch (error) { onError(error); }
+      });
+      break;
+    } catch (error) { if (!canRetryWorkbenchListen(error, port, attempt)) throw error; }
   }
   base = `http://127.0.0.1:${server.address().port}`;
   const state = { version: 1, runtimeSchema: PROXY_RUNTIME_SCHEMA, instance, pid: process.pid, base, adminToken };

package/scripts/workbench/project.mjs

@@ -89,14 +89,31 @@ async function physicalGitDirectories(root) {
   return { topLevel, commonDir };
 }
 
+async function commitIds(root, mainRef) {
+  if (!mainRef) return [await git(root, ['rev-parse', 'HEAD'], { optional: true }), ''];
+  try {
+    const output = await git(root, ['rev-parse', '--revs-only', '--end-of-options', 'HEAD', `${mainRef}^{commit}`]);
+    const records = output.split(/\r?\n/);
+    if (records.length === 2 && records.every(value => /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value))
+      && records[0].length === records[1].length) return records;
+  } catch (error) {
+    if (!optionalGitMiss(error)) throw error;
+  }
+  // Missing refs, older options and ambiguous output retain the independent
+  // fresh reads; process/system failures must not silently enter this fallback.
+  return Promise.all([
+    git(root, ['rev-parse', 'HEAD'], { optional: true }),
+    git(root, ['rev-parse', '--verify', '--quiet', `${mainRef}^{commit}`], { optional: true }),
+  ]);
+}
+
 async function worktreeMetadata(root, main = null, physicalGitDir) {
   const mainBranch = main?.branch || '';
   const mainRef = main?.ref || '';
-  const [head, currentBranch, rawGitDir, mainSha] = await Promise.all([
-    git(root, ['rev-parse', 'HEAD'], { optional: true }),
+  const [[head, mainSha], currentBranch, rawGitDir] = await Promise.all([
+    commitIds(root, mainRef),
     git(root, ['branch', '--show-current'], { optional: true }),
     physicalGitDir === undefined ? git(root, ['rev-parse', '--path-format=absolute', '--git-dir'], { optional: true }) : physicalGitDir,
-    mainRef ? git(root, ['rev-parse', '--verify', '--quiet', `${mainRef}^{commit}`], { optional: true }) : '',
   ]);
   const gitDir = rawGitDir ? await fs.realpath(rawGitDir).catch(() => path.resolve(root, rawGitDir)) : '';
   return { branch: currentBranch, head, gitDir, mainBranch, mainRef, mainSha };

package/scripts/workbench/protocol-device.mjs

@@ -9,6 +9,13 @@ import { sendMessage, ProjectMessagePump } from './protocol-client.mjs';
 
 const readTypes = new Set(['sync.heartbeat', 'sync.read', 'workbench.read', 'object.read', 'blob.get']);
 const messageScope = message => message.session?.id || message.payload.sessionId || 'project';
+function rejectedBindingReason(record, sessionId) {
+  if (record?.state !== 'rejected' || record.message?.type !== 'session.bind' || record.message.payload?.sessionId !== sessionId || record.error?.code !== 'CONFLICT') return '';
+  if (record.error.details?.reason === 'session-bound-elsewhere') return 'session-bound-elsewhere';
+  // This older rejection also covered same-device migration/version conflicts.
+  if (record.error.message === 'Migration requires the owning device and current binding version' && typeof record.error.details?.currentVersion === 'string') return 'binding-conflict';
+  return '';
+}
 // A single project host owns this connection. Agents never receive its credential.
 export class DeviceConnection {
   constructor({ directory, origin, transport = sendMessage, allowLoopback = false }) {
@@ -180,9 +187,19 @@ export class DeviceConnection {
     const file = path.join(this.directory, 'bindings', `${hash(message.payload.sessionId)}.json`);
     return withFileLock(`${file}.lock`, async () => {
       const versions = await readJSON(file, {});
-      const remote = await this.send(message, wire => ({ ...wire, payload: { ...wire.payload,
+      let remote;
+      try { remote = await this.send(message, wire => ({ ...wire, payload: { ...wire.payload,
         expectedBindingVersion: versions[wire.payload.expectedBindingVersion] || '',
-      } }));
+      } })); }
+      catch (error) {
+        const receipt = await readJSON(path.join(this.directory, 'outcomes', `${hash(message.id)}.json`), null);
+        if (rejectedBindingReason(receipt, localBinding.session.id)) {
+          versions.rejections ||= {};
+          versions.rejections[localBinding.bindingVersion] = message.id;
+          await atomicWrite(file, encode(versions));
+        }
+        throw error;
+      }
       if (remote.session.id !== localBinding.session.id || remote.session.generation !== localBinding.session.generation) {
         fail('STALE_SESSION', 'Cloud and local binding generations differ');
       }
@@ -192,16 +209,27 @@ export class DeviceConnection {
     });
   }
   async ensureBinding(binding) {
-    const versions = await readJSON(path.join(this.directory, 'bindings', `${hash(binding.sessionId)}.json`), {});
-    if (versions[binding.version]) return;
+    const status = await this.bindingStatus(binding);
+    if (status.status === 'ready') return;
+    if (status.status === 'conflict') fail('CONFLICT', 'Session binding requires a new host Session', { reason: status.reason });
     await this.bind({ v: 2, id: `bind:${hash(binding.version)}`, type: 'session.bind', payload: {
       sessionId: binding.sessionId, worktreeId: binding.worktreeId, agentId: binding.agentId,
       expectedBindingVersion: binding.version,
     } }, { session: { id: binding.sessionId, generation: binding.generation }, bindingVersion: binding.version });
   }
-  async bindingReady(binding) {
+  async bindingStatus(binding) {
+    if (!binding) return { status: 'pending' };
     const versions = await readJSON(path.join(this.directory, 'bindings', `${hash(binding.sessionId)}.json`), {});
-    if (versions[binding.version]) return true;
+    if (versions[binding.version]) return { status: 'ready' };
+    const requestId = versions.rejections?.[binding.version] || `bind:${hash(binding.version)}`;
+    const receipt = await readJSON(path.join(this.directory, 'outcomes', `${hash(requestId)}.json`), null);
+    const reason = rejectedBindingReason(receipt, binding.sessionId);
+    return reason ? { status: 'conflict', code: 'CONFLICT', reason } : { status: 'pending' };
+  }
+  async bindingReady(binding) {
+    const status = await this.bindingStatus(binding);
+    if (status.status === 'ready') return true;
+    if (status.status === 'conflict') return false;
     this.enrolling ||= new Map();
     if (!this.enrolling.has(binding.sessionId) && this.enrolling.size < 4) {
       const job = this.ensureBinding(binding).catch(error => { this.lastError = error.code || 'UNAVAILABLE'; })

package/scripts/workbench/protocol-repository.mjs

@@ -1,6 +1,8 @@
 import { fail } from '../shared/protocol.mjs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { performance } from 'node:perf_hooks';
+import { pause } from '../shared/io.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -20,15 +22,35 @@ export async function lookupRepository(slug, {
   fetcher = fetch,
   token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN,
   tokenProvider = keychainToken,
+  clock = () => performance.now(),
+  sleep = pause,
 } = {}) {
   if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(slug) || slug.split('/').some(part => ['.', '..'].includes(part))) fail('INVALID_ARGUMENT', 'Invalid GitHub repository');
   let url = new URL(`https://api.github.com/repos/${slug}`);
-  let authorization = token || '', keychainChecked = !!authorization;
+  const deadline = clock() + 40000;
+  const checkDeadline = () => { if (clock() >= deadline) fail('UNAVAILABLE', 'GitHub repository identity verification timed out'); };
+  const authorization = token || await tokenProvider() || '';
+  checkDeadline();
+  const request = async target => {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      checkDeadline();
+      let response;
+      try {
+        response = await fetcher(target, { redirect: 'manual', signal: AbortSignal.timeout(Math.max(1, Math.min(10000, Math.ceil(deadline - clock())))),
+          headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'Context-Guard', ...(authorization ? { Authorization: `Bearer ${authorization}` } : {}) } });
+      } catch {
+        checkDeadline();
+        if (attempt === 2) fail('UNAVAILABLE', 'GitHub repository identity could not be verified');
+      }
+      checkDeadline();
+      if (response && ![502, 503, 504].includes(response.status)) return response;
+      await response?.body?.cancel();
+      if (attempt === 2) fail('UNAVAILABLE', 'GitHub repository is temporarily unavailable');
+      await sleep(Math.min(250 * 2 ** attempt, Math.max(1, deadline - clock())));
+    }
+  };
   for (let attempt = 0; attempt < 4; attempt++) {
-    let response;
-    try { response = await fetcher(url, { redirect: 'manual', signal: AbortSignal.timeout(10000),
-      headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'Context-Guard', ...(authorization ? { Authorization: `Bearer ${authorization}` } : {}) } }); }
-    catch { fail('UNAVAILABLE', 'GitHub repository identity could not be verified'); }
+    const response = await request(url);
     if ([301, 302, 307, 308].includes(response.status)) {
       const location = response.headers.get('location'); await response.body?.cancel();
       if (!location) fail('UNAVAILABLE', 'GitHub redirect is missing');
@@ -38,11 +60,6 @@ export async function lookupRepository(slug, {
     }
     if (!response.ok) {
       await response.body?.cancel();
-      if (!authorization && !keychainChecked && [401, 403, 404].includes(response.status)) {
-        keychainChecked = true;
-        authorization = await tokenProvider();
-        if (authorization) { attempt -= 1; continue; }
-      }
       fail(response.status === 404 ? 'NOT_FOUND' : [401, 403].includes(response.status) ? 'FORBIDDEN' : 'UNAVAILABLE', 'GitHub repository is unavailable to this backend');
     }
     let value;
@@ -51,6 +68,7 @@ export async function lookupRepository(slug, {
       for await (const chunk of response.body) { size += chunk.length; if (size > 1024 * 1024) fail('TOO_LARGE', 'GitHub response exceeds limit'); chunks.push(chunk); }
       value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
     } catch { fail('UNAVAILABLE', 'GitHub returned an invalid repository identity'); }
+    checkDeadline();
     if (!Number.isSafeInteger(value.id) || value.id <= 0 || typeof value.full_name !== 'string') fail('UNAVAILABLE', 'GitHub returned an invalid repository identity');
     return { repositoryId: String(value.id), slug: value.full_name };
   }

package/scripts/workbench/registry.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { atomicWrite, encode, readJSON, withFileLock } from '../shared/io.mjs';
 import { MapError } from '../shared/map-model.mjs';
 
@@ -100,6 +101,11 @@ export async function rememberProject(project, { dir = globalWorkbenchDirectory(
       } : previous?.runtime || null,
       updatedAt: new Date().toISOString(),
     };
+    if (previous) {
+      const { updatedAt: _previousUpdatedAt, ...previousContent } = previous;
+      const { updatedAt: _nextUpdatedAt, ...nextContent } = record;
+      if (isDeepStrictEqual(previousContent, nextContent)) return previous;
+    }
     const next = {
       version: 1,
       projects: [...registry.projects.filter(item => item.projectId !== project.projectId), record]

package/scripts/workbench/server.mjs

@@ -15,6 +15,7 @@ import { memoryRequest, sessionMemoryDir, memoryConfigPath } from './memory.mjs'
 import { MemorySyncCoordinator } from './sync-coordinator.mjs';
 import { inspectRetiredSync } from './sync.mjs';
 import { runtimeIdentity } from './runtime.mjs';
+import { canRetryWorkbenchListen } from './listen.mjs';
 import { Attachments } from './attachments.mjs';
 import { ProtocolStore } from '../shared/protocol-store.mjs';
 import { ProtocolBlobs, serveBlob } from '../shared/protocol-blobs.mjs';
@@ -144,6 +145,8 @@ export async function health(state) {
   return result?.ok ? result.value : null;
 }
 export { loopbackJSON };
+export { canRetryWorkbenchListen };
+
 export async function startServer({ root, port = 8877, host = '127.0.0.1', fault, messageQueue = queueCodexMessage, repositoryLookup = lookupRepository } = {}) {
   if (!['127.0.0.1', 'localhost'].includes(host)) throw new MapError('INVALID_HOST', 'Workbench only listens on loopback');
   const directory = await defaultDirectoryAvailability();
@@ -476,6 +479,14 @@ export async function startServer({ root, port = 8877, host = '127.0.0.1', fault
       const connection = await projectDevice();
       const coordinator = new MemorySyncCoordinator({ project: sessionProject, sessionId, store: target, directory: syncDirectory,
         managed: !!connection && await connection.supports('private-map-heads'),
+        request: async (...args) => {
+          if (connection && await connection.connected()) {
+            const binding = await protocolStore.registeredBinding(backendPrincipal, sessionId);
+            const status = await connection.bindingStatus(binding);
+            if (status.status === 'conflict') throw new MapError('CONFLICT', 'Session binding requires a new host Session', 409, { reason: status.reason });
+          }
+          return memoryRequest(...args);
+        },
         display: async () => {
           const identity = (await access.sessionRegistry()).find(item => item.id === sessionId);
           return identity?.name ? { name: identity.name, platform: identity.platform } : null;
@@ -555,6 +566,13 @@ export async function startServer({ root, port = 8877, host = '127.0.0.1', fault
     return refreshing;
   }
   async function cloudSyncStatus(viewId = 'main') {
+    if (viewId.startsWith('session:')) {
+      const connection = await projectDevice();
+      if (connection && await connection.connected()) {
+        const status = await connection.bindingStatus(await protocolStore.registeredBinding(backendPrincipal, viewId.slice(8)));
+        if (status.status === 'conflict') return { ...(syncCoordinators.get(viewId)?.snapshot() || {}), configured: true, status: 'conflict', error: status.code, reason: status.reason };
+      }
+    }
     if (syncCoordinators.has(viewId)) return syncCoordinators.get(viewId).snapshot();
     return { configured: false, status: 'disabled', cursor: 0, receivedCursor: 0, conflict: null, serviceAlive: false };
   }
@@ -593,7 +611,17 @@ export async function startServer({ root, port = 8877, host = '127.0.0.1', fault
         else await connection.bind(bindMessage, protocolBinding);
         cloudBinding = { status: 'ready' };
       }
-      catch (error) { cloudBinding = { status: 'pending', code: error.code || 'UNAVAILABLE' }; }
+      catch (error) {
+        const status = await connection.bindingStatus({ sessionId: prepared.sessionId, version: protocolBinding.bindingVersion });
+        cloudBinding = status.status === 'conflict' ? status : { status: 'pending', code: error.code || 'UNAVAILABLE' };
+        if (cloudBinding.status === 'conflict') {
+          const directory = path.join(sessionMemoryDir(prepared.sessionProject, prepared.sessionId), 'remote-sync');
+          const stateFile = path.join(directory, 'state.json');
+          await atomicWrite(stateFile, encode({ ...await readJSON(stateFile, {}), configured: true,
+            status: 'conflict', error: 'CONFLICT', reason: cloudBinding.reason,
+            pending: await readJSON(path.join(directory, 'outbox.json'), null) ? 1 : 0 }));
+        }
+      }
     }
     const lazyCloudMap = connection && await connection.supports('private-map-heads');
     const sessionFiles = project.kind === 'git' && !lazyCloudMap && !stores.has(`session:${prepared.sessionId}`) ? await ensureSessionMap(prepared.sessionProject, prepared.sessionId) : null;
@@ -965,8 +993,8 @@ export async function startServer({ root, port = 8877, host = '127.0.0.1', fault
         if (route.startsWith('/api/')) {
           const actor = auth(req, url);
           const viewId = viewFor(actor, url);
-          const activeStore = await storeFor(viewId);
           if (route === '/api/cloud-sync' && req.method === 'GET') { isHuman(actor); return send(res, 200, await cloudSyncStatus(viewId)); }
+          const activeStore = await storeFor(viewId);
           if (route === '/api/events' && req.method === 'GET') {
             isHuman(actor); const id = url.searchParams.get('clientId');
             if (!id || id.length > 100) throw new MapError('INVALID_CLIENT', 'Invalid clientId');
@@ -1108,8 +1136,17 @@ export async function startServer({ root, port = 8877, host = '127.0.0.1', fault
     });
     server.requestTimeout = 10000; server.headersTimeout = 10000;
     for (let attempt = 0; ; attempt++) {
-      try { await new Promise((resolve, reject) => { const onError = e => reject(e); server.once('error', onError); server.listen(port === 0 ? 0 : port + attempt, '127.0.0.1', () => { server.off('error', onError); resolve(); }); }); break; }
-      catch (e) { if (e.code !== 'EADDRINUSE' || attempt >= 20 || port === 0) throw e; }
+      try {
+        await new Promise((resolve, reject) => {
+          const onListening = () => { server.off('error', onError); resolve(); };
+          const onError = error => { server.off('error', onError); server.off('listening', onListening); reject(error); };
+          server.once('error', onError);
+          try { server.listen(port === 0 ? 0 : port + attempt, '127.0.0.1', onListening); }
+          catch (error) { onError(error); }
+        });
+        break;
+      }
+      catch (e) { if (!canRetryWorkbenchListen(e, port, attempt)) throw e; }
     }
     base = `http://127.0.0.1:${server.address().port}`;
     const state = { ...runtimeIdentity(), root, projectId: project.projectId, worktreeRoot: project.worktreeRoot, worktreeId: project.worktreeId, sharedDir: project.sharedDir, pid: process.pid, instance, url: base + '/prototype/workbench.html', adminToken };

package/scripts/workbench/sync-coordinator.mjs

@@ -126,6 +126,13 @@ export class MemorySyncCoordinator extends EventEmitter {
     this.update(fields);
     await atomicWrite(this.stateFile, encode(this.status));
   }
+  async preserveBindingConflict(error) {
+    const reason = error?.details?.reason;
+    if (error?.code !== 'CONFLICT' || !['session-bound-elsewhere', 'binding-conflict'].includes(reason)) return false;
+    await this.persist({ status: 'conflict', error: 'CONFLICT', reason,
+      conflict: { code: 'CONFLICT', reason }, pending: await readJSON(this.outboxFile, null) ? 1 : 0 });
+    return true;
+  }
 
   async start() {
     await fs.mkdir(this.directory, { recursive: true });
@@ -272,6 +279,7 @@ export class MemorySyncCoordinator extends EventEmitter {
       await this.persist({ status: equalDocument(acknowledged, this.store.doc) ? 'synced' : 'syncing', pending: 0, lastSyncedAt: result.persistedAt || new Date().toISOString() });
       if (!equalDocument(acknowledged, this.store.doc)) await this.queueLocal();
     } catch (error) {
+      if (await this.preserveBindingConflict(error)) return;
       if (error.code === 'SESSION_REOPEN_REQUIRED') {
         await this.createSessionGeneration();
         return;
@@ -451,6 +459,7 @@ export class MemorySyncCoordinator extends EventEmitter {
         this.retryDelay = this.retryMin;
       } catch (error) {
         clearTimeout(this.streamTimer);
+        if (await this.preserveBindingConflict(error)) break;
         if (this.closed || this.managed) break;
         if (this.abort?.signal.reason?.code === 'EVENT_STREAM_TIMEOUT') error = this.abort.signal.reason;
         await this.schedule(async () => {
@@ -497,6 +506,7 @@ export class MemorySyncCoordinator extends EventEmitter {
       if (this.status.pending) await this.flush();
       else if (['offline', 'error', 'connecting'].includes(this.status.status)) await this.persist({ status: 'synced', error: null });
     }).catch(async error => {
+      if (await this.preserveBindingConflict(error)) throw error;
       if (!this.status.conflict) await this.persist({ status: error.code === 'UNAUTHORIZED' ? 'error' : 'offline', error: error.code || 'MEMORY_UNAVAILABLE' });
       throw error;
     });

package/scripts/workbench/sync.mjs

@@ -77,6 +77,7 @@ export async function sessionSync(root, sessionId, action) {
   const project = await resolveProject(root);
   if (!(await bindingStatus(project, sessionId)).session.bound) throw new MapError('SESSION_BINDING_REQUIRED', 'Bind the actual Session before synchronization', 409);
   if (!status.configured) throw new MapError('MEMORY_NOT_CONFIGURED', 'Connect this project using workbench connect', 503);
+  if (status.state?.status === 'conflict' && ['session-bound-elsewhere', 'binding-conflict'].includes(status.state.reason)) throw new MapError('CONFLICT', 'Session binding requires a new host Session', 409, { reason: status.state.reason });
   if (['prepare', 'pull', 'checkpoint'].includes(action)) return prepareMemory(project, sessionId);
   if (action === 'finish') {
     const receipt = await synchronizeMemory(root, sessionId);