@karma42/agent 0.1.0-beta.2 → 0.1.0-beta.3

package/README.md

@@ -1,14 +1,26 @@
 # Karma42 agent — current-session MCP connection
 
-Version `0.1.0-beta.2` adds a named project connection to your existing Claude Code or Codex conversation. The npm package bundles the local MCP bridge. It does not launch a coding model or change client approval/sandbox settings.
+Version `0.1.0-beta.3` is the browser-pairing candidate. Publication and real-client acceptance are separate release checks. The bundled bridge adds a named connection to your existing Claude Code or Codex conversation; it does not launch another coding model or change client permissions.
 
-Get the project-specific prompt and a private code in **My agents**. Paste the prompt into your current agent conversation. Run `session-connect --project-url HTTPS_SERVICE/p/PROJECT_ID --provider claude|codex --agent-id AGENT_ID` in the current workspace; supply the code privately when prompted, never in arguments or chat. Review the authoritative project, repository, agent and workspace before saving. This setup does not check GitHub access, clone a repository or record model authentication as verified.
+In **My agents**, choose an agent and copy its project-specific instructions. After your setup approval, your agent runs:
+
+```sh
+npx --ignore-scripts @karma42/agent@0.1.0-beta.3 browser-connect --project-url HTTPS_SERVICE/p/PROJECT_ID --provider claude --agent-id AGENT_ID
+```
+
+Use `--provider codex` in Codex. The current folder is the requested workspace; `--folder /absolute/workspace` selects another. Setup prints a browser link and request check, then exits immediately. Open the link, sign in with Google, match the request check to this session, and review the project, agent, requested folder and access before approving. The browser does not independently verify that local folder. Approval does not grant filesystem/GitHub permissions, start development or edit client settings. Native client trust prompts remain yours.
+
+Run `browser-prepare --connection ID` after approval. It checks once; if pending it prints the link again without keeping a process or lock open. Approved requests save the credential privately and return the secret-free named MCP entry. Lost HTTP replies and interrupted local saves are recoverable by retrying this same command; do not delete the private receipt or create another request. `browser-status --connection ID` shows local pending/saved metadata only, never online activity. Cancel a pending request in the signed-in browser. Expired/cancelled requests preserve existing saved credentials; repeat `browser-connect` for a fresh request. `browser-connect --reconnect` requests a replacement after a previously saved setup, with browser confirmation required before any active connection is replaced.
+
+The server receives the hash of a locally generated credential, never its plaintext. The polling secret and candidate credential stay in private 0600 files under 0700 directories; neither appears in the URL, command arguments, chat or MCP configuration. Per-project/service/agent locks cover only short local operations and HTTP requests. No lock is held while a human approves in the browser. Recognized browser-operation locks whose PID is confirmed dead recover automatically; live, reused or uncertain PIDs and legacy bridge locks are never stopped or removed. Recovery attempts are serialized and recheck the lock inode/content. An interrupted recovery guard is conservatively refused rather than deleting an uncertain lock. Two different agents/projects can set up independently; duplicate operations for the same identity are refused safely. Pending requests expire on the service; approved receipts remain recoverable.
+
+The deployed beta.2 private-code command remains an identified compatibility path: `session-connect` requires an interactive terminal, rejects pipes/redirected input before taking a lock and never runs in the background. Codes belong only in its private prompt. Expected agent IDs lock only that agent, without a whole-home lock. Existing beta.2 session records remain valid and continue to pin their beta.2 bridge rather than silently upgrading a live connection. OPE-43 owns retirement after participant migration and independent acceptance.
 
 Setup returns a secret-free MCP entry and instructions for the selected client. Ask your current agent to add only that entry after your approval, preserving all other entries. Claude uses its workspace-local `mcp add --scope local` command; Codex uses the trusted workspace’s `.codex/config.toml`. Do not share machine-specific paths in repository config. Native trust and permission prompts remain under your control. The client may need MCP reload before tools appear; return to the existing conversation and verify `get_project` on the named entry before continuing. macOS is the tested package environment; Linux and Windows acceptance remains pending. Independent real-client reload/continuation acceptance is still pending; configuration generation and the actual stdio process are tested separately.
 
 Each service/project/agent combination has its own ID, credentials and MCP name. Local and production services are distinct even when their IDs match. Several catalogs may load without claiming their agents. The first `get_project` call claims only its connection and verifies `you.agentId` and `you.agentName`; other tool calls are refused until this succeeds. Use a separate named agent for concurrent sessions. A second process using one identity is refused without takeover. Workspace scoping is client configuration, not a security sandbox; credentials are scoped by the service to their project agent.
 
-Commands: `session-connect`, `session-prepare --connection ID` (recover interrupted pairing), `session-config --connection ID` (print the secret-free entry), `session-status` (local records only), and `session-serve --connection ID` (stdio transport, started by the MCP client). Session commands use separate private storage at `~/.karma42/sessions/SERVICE_PROJECT_HASH/AGENT_ID`; `--state-dir` selects a private test root. A saved pairing receipt survives cancellation. New setup codes rotate that identity’s service credential, so disconnect its old bridge/runner first. Other identities and their history are preserved.
+Commands: `session-connect`, `session-prepare --connection ID` (recover interrupted pairing), `session-config --connection ID` (print the secret-free entry), `session-status` (local records only), and `session-serve --connection ID` (stdio transport, started by the MCP client). Session commands use separate private storage at `~/.karma42/sessions/SERVICE_PROJECT_HASH/AGENT_ID`; `--state-dir` selects a private test root. Browser setup records survive interruption. Browser approval explicitly confirms credential replacement; pending/cancelled requests do not rotate it. Legacy private codes rotate that identity’s credential, so disconnect its old bridge/runner before private-code setup. Other identities and their history are preserved.
 
 The client owns the bridge process. EOF or SIGINT/SIGTERM/SIGHUP reports stopping, closes polling and releases the local identity lock. Closing a chat does not necessarily close the client-owned process; explicitly disconnect the named MCP entry to release it. A crash/SIGKILL cannot send a final report: the backend’s existing lease/fencing and stale-lock recovery still apply. No remote kill of the coding client is promised. Catalog discovery and connection contact are not evidence of model work or measured spending. The bridge retains the canonical bounded deferred-send journal/retries, only while connected. Revocation, stale runs, paused/not-started mutations and urgent runtime barriers remain enforced by the service; the bridge never downloads or executes cloud-selected runner updates to bypass a refusal.
 
@@ -100,4 +112,4 @@ Legacy `~/.agent-projects` helpers/launchers remain identified active consumers.
 
 Focused tests cover preparation/start separation, all provider/mode choices, cancelled acknowledgements, expired/refused responses, interrupted pairing, clone/readiness failures, wrong origin, credential privacy, stale consent, concurrent operations, reconnect preservation, pending recovery, GitHub account visibility, naming/path collisions and environment filtering. The foreground stop test uses the real supervisor with a disposable **stub runner**, not a model. An installed-artifact terminal rehearsal uses synthetic service responses and local tool fixtures. No production credentials, persistent emulator reset, real GitHub mutation or model execution is part of these tests.
 
-Browser OAuth pairing, website activation, signed runtime releases, independent operator/real-model acceptance and deployment remain separate release steps. This beta does not claim independent real-model acceptance. See `docs/onboarding/agent-connection-plan.md` for the product flow and release gates.
+Browser-pairing website activation, signed runtime releases, independent operator/real-model acceptance and deployment remain separate release steps. This beta does not claim independent real-model acceptance. See `docs/onboarding/agent-connection-plan.md` for the product flow and release gates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karma42/agent",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "description": "Karma42 named project MCP connections for your current coding session",
   "license": "UNLICENSED",
   "type": "module",

package/src/browser-pairing.mjs

@@ -0,0 +1,142 @@
+import { randomBytes, randomUUID, createHash } from 'node:crypto';
+import { constants, openSync, closeSync, writeFileSync, lstatSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { makePlan, VERSION } from './plan.mjs';
+import { canonicalPath, connectionDir, digest, lstatExists, readPrivate, save, writePrivate } from './state.mjs';
+import { sessionHome, sessionId, sessionConfiguration, validateSession } from './session.mjs';
+import { system } from './system.mjs';
+
+const TOKEN = /^[\w-]{43}$/;
+const hash = value => createHash('sha256').update(value).digest('hex');
+// Only locks created by this browser flow can be recovered automatically. Legacy/live bridge locks remain untouched.
+export function withBrowserLock(dir, action, processAlive = pid => { try { process.kill(pid, 0); return true; } catch (error) { if (error.code === 'ESRCH') return false; return true; } }) {
+  const path = join(dir, 'operation.lock'), guard = join(dir, 'browser-recovery.lock');
+  const create = () => {
+    const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try { writeFileSync(fd, JSON.stringify({ kind: 'karma42-browser-operation-1', pid: process.pid, nonce: randomUUID() })); }
+    finally { closeSync(fd); }
+    return lstatSync(path);
+  };
+  let owned;
+  try { owned = create(); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    let guardFd;
+    try { guardFd = openSync(guard, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+    catch { throw new Error('Another browser setup operation is checking this connection. Retry shortly; no process was stopped.'); }
+    try {
+      writeFileSync(guardFd, `${process.pid}\n`);
+      const before = lstatSync(path), raw = readPrivate(path);
+      let holder;
+      try { holder = JSON.parse(raw); } catch {}
+      if (holder?.kind !== 'karma42-browser-operation-1' || !Number.isSafeInteger(holder.pid) || holder.pid <= 0 || typeof holder.nonce !== 'string' || processAlive(holder.pid)) {
+        throw new Error('Another operation holds this connection. Finish or cancel its setup, or disconnect its active MCP entry, before retrying. No process was stopped.');
+      }
+      // Guard serializes recovery attempts; reread inode/content before touching the confirmed-dead lock.
+      const current = lstatSync(path);
+      if (current.dev !== before.dev || current.ino !== before.ino || readPrivate(path) !== raw) throw new Error('The connection lock changed. Retry setup; no process was stopped.');
+      unlinkSync(path);
+      owned = create();
+    } finally { closeSync(guardFd); unlinkSync(guard); }
+  }
+  return Promise.resolve().then(action).finally(() => {
+    if (!lstatExists(path)) return;
+    const current = lstatSync(path);
+    if (current.dev === owned.dev && current.ino === owned.ino) unlinkSync(path);
+  });
+}
+const receiptPath = dir => join(dir, 'pending-browser.json');
+function validReceipt(receipt, id) {
+  if (receipt?.schema !== 'browser-pairing-1' || receipt.id !== id || id !== sessionId(receipt.service, receipt.agentId)
+    || !TOKEN.test(receipt.pollingSecret ?? '') || !TOKEN.test(receipt.candidateToken ?? '')
+    || !/^[\w-]{1,200}$/.test(receipt.agentId ?? '') || !/^[a-f0-9-]{36}$/.test(receipt.requestId ?? '')
+    || receipt.packageVersion !== VERSION) throw new Error('Invalid private browser setup receipt. Review My agents.');
+  const plan = makePlan({ provider: receipt.provider, mode: 'guarded', projectUrl: receipt.service, repo: 'https://github.com/placeholder/project', folder: receipt.folder });
+  if (plan.projectUrl !== receipt.service || canonicalPath(receipt.folder) !== receipt.folder) throw new Error('Browser setup workspace changed. Review My agents.');
+  return receipt;
+}
+export function browserApprovalUrl(receipt) {
+  const service = new URL(receipt.service);
+  const page = new URL('/viewer/', service.origin);
+  page.searchParams.set('project', service.pathname.split('/')[2]);
+  page.searchParams.set('section', 'your-agent');
+  page.searchParams.set('pairing', receipt.requestId);
+  return page.href;
+}
+export function createBrowserOperations({ home = sessionHome(), io, sys = system } = {}) {
+  home = canonicalPath(home);
+  const showPending = receipt => io.say(`Browser approval required. Open this link, sign in and review the project, agent, workspace and requested access:\n${browserApprovalUrl(receipt)}\nRequest check: ${hash(receipt.requestId + ':' + hash(receipt.candidateToken)).slice(0, 8).toUpperCase()} (match this in the browser before approving)\nRequested workspace (not independently verified): ${receipt.folder}\nConnection: ${receipt.id}\nAfter approval run browser-prepare --connection ${receipt.id}${home === sessionHome() ? '' : ` --state-dir '${home.replaceAll("'", "'\\''")}'`}\nNo process is waiting. Native client trust prompts and approval to edit MCP configuration still apply.`);
+  const startBody = receipt => ({ requestId: receipt.requestId, agentId: receipt.agentId, provider: receipt.provider, folder: receipt.folder, pollingSecret: receipt.pollingSecret, candidateTokenHash: hash(receipt.candidateToken) });
+  async function start(dir, receipt) {
+    let result;
+    try { result = await sys.request(receipt.service, 'pairings/start', startBody(receipt)); }
+    catch { throw new Error(`Browser setup reply unavailable. Your private request is saved. Retry browser-prepare --connection ${receipt.id}; do not create another request or replace credentials.`); }
+    if (result?.requestId !== receipt.requestId || !['pending', 'approved', 'cancelled', 'expired'].includes(result.status)) throw new Error('Unexpected browser setup reply. The private request was preserved.');
+    receipt = { ...receipt, registered: true, expiresAt: result.expiresAt };
+    writePrivate(receiptPath(dir), receipt);
+    return receipt;
+  }
+  function showConfig(record) {
+    const config = sessionConfiguration(record, home);
+    io.say(`Saved session connection: ${record.id}\nMCP entry: ${config.name}\nBrowser approval completed. No coding model was launched and no client settings were changed.\nAsk before adding this named entry to the current workspace; preserve other entries and permission settings.\n${record.provider === 'claude' ? config.claudeCommand : config.codex}\nReload MCP if needed, return to this conversation, then call get_project on ${config.name} and verify agent ${record.agentName}.`);
+    return record;
+  }
+  return {
+    async connect(options) {
+      if (!/^[\w-]{1,200}$/.test(options['agent-id'] ?? '')) throw new Error('Browser setup requires the project-specific --agent-id from My agents.');
+      const folder = canonicalPath(resolve(options.folder ?? process.cwd()));
+      const plan = makePlan({ provider: options.provider, mode: 'guarded', projectUrl: options['project-url'], repo: 'https://github.com/placeholder/project', folder });
+      sys.verifyBundle();
+      const id = sessionId(plan.projectUrl, options['agent-id']), dir = connectionDir(home, id);
+      return withBrowserLock(dir, async () => {
+        let receipt;
+        if (lstatExists(receiptPath(dir))) {
+          receipt = validReceipt(readPrivate(receiptPath(dir), true), id);
+          if (receipt.folder !== folder || receipt.provider !== plan.provider) throw new Error('A browser setup is already pending for this agent in another workspace or client. Review or cancel it in My agents before starting another.');
+          if (['cancelled', 'expired'].includes(receipt.status) || (receipt.status === 'saved' && options.reconnect)) receipt = null;
+          else if (receipt.status === 'saved') return showConfig(validateSession(readPrivate(join(dir, 'connection.json'), true), id));
+        }
+        if (!receipt) {
+          receipt = { schema: 'browser-pairing-1', id, service: plan.projectUrl, agentId: options['agent-id'], provider: plan.provider, folder,
+            requestId: randomUUID(), candidateToken: randomBytes(32).toString('base64url'), pollingSecret: randomBytes(32).toString('base64url'), packageVersion: VERSION, createdAt: sys.now(), status: 'pending', registered: false };
+          // Persist the candidate BEFORE contacting the server: lost start/approval replies never lose the credential.
+          writePrivate(receiptPath(dir), receipt);
+        }
+        if (!receipt.registered) receipt = await start(dir, receipt);
+        showPending(receipt); return { id, status: receipt.status, approvalUrl: browserApprovalUrl(receipt) };
+      });
+    },
+    async prepare(options) {
+      const id = options.connection, dir = connectionDir(home, id);
+      return withBrowserLock(dir, async () => {
+        if (!lstatExists(receiptPath(dir))) throw new Error('No browser setup found. Use browser-connect from My agents.');
+        let receipt = validReceipt(readPrivate(receiptPath(dir), true), id);
+        if (receipt.status === 'saved') return showConfig(validateSession(readPrivate(join(dir, 'connection.json'), true), id));
+        if (!receipt.registered) receipt = await start(dir, receipt);
+        let result;
+        try { result = await sys.request(receipt.service, `pairings/${receipt.requestId}/poll`, {}, receipt.pollingSecret); }
+        catch { throw new Error(`Browser approval reply unavailable. Retry browser-prepare --connection ${id}; your private request and existing connection are preserved.`); }
+        if (!['pending', 'approved', 'cancelled', 'expired'].includes(result?.status)) throw new Error('Unexpected browser approval reply. Existing connection preserved.');
+        if (result.status === 'pending') { showPending(receipt); return { id, status: 'pending' }; }
+        if (result.status !== 'approved') {
+          writePrivate(receiptPath(dir), { ...receipt, status: result.status });
+          io.say(`Browser setup ${result.status}. Existing saved credentials were not changed. Start a fresh browser-connect when ready.`);
+          return { id, status: result.status };
+        }
+        if (result.agentId !== receipt.agentId || !/^[\w-]{1,64}$/.test(result.agentName ?? '') || !Number.isFinite(result.approvedAt)) throw new Error('Approved identity differs from the requested agent. Existing connection preserved. Review My agents.');
+        const plan = makePlan({ provider: receipt.provider, mode: 'guarded', projectUrl: receipt.service, repo: result.repoUrl, folder: receipt.folder });
+        const record = { schema: 'client-session-1', id, service: receipt.service, agentId: receipt.agentId, agentName: result.agentName, repo: plan.repo, folder: plan.folder, provider: plan.provider, packageVersion: VERSION, createdAt: sys.now(), approvedAt: result.approvedAt };
+        record.consent = digest([id, record.service, record.agentName, record.repo, record.folder, record.provider, VERSION]);
+        writePrivate(join(dir, 'token'), receipt.candidateToken); save(dir, record);
+        // Keep the private receipt for restart/recovery; never exchange another credential on retry.
+        writePrivate(receiptPath(dir), { ...receipt, status: 'saved' });
+        return showConfig(record);
+      });
+    },
+    status(options) {
+      const dir = connectionDir(home, options.connection);
+      const receipt = validReceipt(readPrivate(receiptPath(dir), true), options.connection);
+      io.say(JSON.stringify({ id: receipt.id, project: receipt.service, provider: receipt.provider, workspace: receipt.folder, state: receipt.status, approvalUrl: browserApprovalUrl(receipt), expiresAt: receipt.expiresAt, liveActivity: 'not checked' }, null, 2));
+    },
+  };
+}

package/src/cli.mjs

@@ -6,12 +6,16 @@ import { VERSION, makePlan, providerName, renderPlan } from './plan.mjs';
 import { doctor } from './doctor.mjs';
 import { createOperations } from './connection.mjs';
 import { createSessionOperations } from './session.mjs';
+import { createBrowserOperations } from './browser-pairing.mjs';
 import { serveSession } from './session-stdio.mjs';
 import { terminal } from './terminal.mjs';
 
 const HELP = `Karma42 agent ${VERSION} — beta release
 
 Commands:
+  browser-connect --project-url HTTPS_SERVICE/p/PROJECT_ID --provider claude|codex --agent-id AGENT_ID [--folder ABSOLUTE_WORKSPACE]
+  browser-prepare --connection ID (check approval once; safe to retry)
+  browser-status --connection ID (private local state only)
   session-connect --project-url HTTPS_SERVICE/p/PROJECT_ID --provider claude|codex [--agent-id EXPECTED_AGENT_ID] [--folder ABSOLUTE_WORKSPACE]
   session-prepare --connection ID (recover interrupted pairing)
   session-config --connection ID
@@ -39,6 +43,8 @@ Session commands use separate private storage (~/.karma42/sessions), keep your c
 No automatic personal client configuration edits or background launch.`;
 const selection = { connection: { type: 'string' }, 'state-dir': { type: 'string' } };
 const specs = {
+  'browser-connect': { reconnect: { type: 'boolean' }, 'agent-id': { type: 'string' }, provider: { type: 'string' }, 'project-url': { type: 'string' }, folder: { type: 'string' }, 'state-dir': { type: 'string' } },
+  'browser-prepare': selection, 'browser-status': selection,
   'session-connect': { 'agent-id': { type: 'string' }, provider: { type: 'string' }, 'project-url': { type: 'string' }, folder: { type: 'string' }, 'state-dir': { type: 'string' } },
   'session-prepare': selection, 'session-config': selection, 'session-serve': selection, 'session-status': { 'state-dir': { type: 'string' } },
   connect: { provider: { type: 'string' }, mode: { type: 'string' }, 'project-url': { type: 'string' }, folder: { type: 'string' }, 'state-dir': { type: 'string' } },
@@ -69,6 +75,10 @@ export function main(args, out = console.log, err = console.error, runDoctor = d
       if (v['state-dir'] && (!v['state-dir'].startsWith('/') || /[\x00-\x1f\x7f-\x9f]/.test(v['state-dir']))) throw new Error('Choose an absolute private state directory.');
       if (command === 'session-serve') return serveSession({ connection: v.connection, home: v['state-dir'] }).then(() => 0).catch(() => { err('MCP session could not start. Review its private connection record.'); return 2; });
       const io = terminal(); io.say = out;
+      if (command.startsWith('browser-')) {
+        const browser = createBrowserOperations({ home: v['state-dir'], io });
+        return Promise.resolve().then(() => browser[command.slice(8)](v)).then(() => 0).catch(error => { err(error.message); return 2; });
+      }
       if (command.startsWith('session-')) {
         const sessions = createSessionOperations({ home: v['state-dir'], io });
         return Promise.resolve().then(() => sessions[command.slice(8)](v)).then(() => 0).catch(error => { err(error.message); return 2; });

package/src/plan.mjs

@@ -1,6 +1,6 @@
 import { isAbsolute } from 'node:path';
 
-export const VERSION = '0.1.0-beta.2';
+export const VERSION = '0.1.0-beta.3';
 export const COPY_VERSION = '2026-10-09.2';
 // These descriptions reflect pilot/agent-kit/providers.mjs. They are a proposal
 // for the onboarding vocabulary, not a change to the current adapter settings.

package/src/session.mjs

@@ -11,7 +11,7 @@ const TOKEN = /^[\w-]{43}$/;
 export const sessionId = (service, agentId) => `${digest(service)}/${agentId}`;
 export const sessionName = record => `karma42-${digest([record.service, record.agentId]).slice(0, 24)}`;
 export function validateSession(record, id) {
-  if (record?.schema !== 'client-session-1' || record.id !== id || record.id !== sessionId(record.service, record.agentId) || record.packageVersion !== VERSION
+  if (record?.schema !== 'client-session-1' || record.id !== id || record.id !== sessionId(record.service, record.agentId) || !['0.1.0-beta.2', VERSION].includes(record.packageVersion)
     || !/^[\w-]{1,200}$/.test(record.agentId ?? '') || !/^[\w-]{1,64}$/.test(record.agentName ?? '')) throw new Error('Invalid session identity. Reconnect using My agents.');
   const plan = makePlan({ provider: record.provider, mode: 'guarded', projectUrl: record.service, repo: record.repo, folder: record.folder });
   if (plan.projectUrl !== record.service || canonicalPath(record.folder) !== record.folder) throw new Error('Session workspace changed. Review the connection again.');
@@ -55,12 +55,13 @@ export function createSessionOperations({ home = sessionHome(), io, sys = system
   }
   return {
     async connect(options) {
+      if (!io.interactive) throw new Error('Private-code setup needs an interactive terminal. Do not redirect input, pipe output or run it in the background. Prefer browser-connect, or run session-connect in your existing terminal.');
       const folder = canonicalPath(resolve(options.folder ?? process.cwd()));
       const plan = makePlan({ provider: options.provider, mode: 'guarded', projectUrl: options['project-url'], repo: 'https://github.com/placeholder/project', folder });
       if (options['agent-id'] !== undefined && !/^[\w-]{1,200}$/.test(options['agent-id'])) throw new Error('Choose a valid agent ID.');
       sys.verifyBundle();
       ensureHome(home);
-      return withLock(home, async () => {
+      {
         const expected = options['agent-id'];
         const expectedDir = expected ? connectionDir(home, sessionId(plan.projectUrl, expected)) : null;
         const pair = async () => {
@@ -77,8 +78,12 @@ export function createSessionOperations({ home = sessionHome(), io, sys = system
           if (expected && expected !== paired.agentId) throw new Error('This code belongs to a different agent. Its private recovery receipt was saved; the requested connection was preserved. Review My agents before proceeding.');
           return finish(dir, readPrivate(join(dir, 'pending-session.json'), true), Boolean(expectedDir));
         };
-        return expectedDir ? withLock(expectedDir, pair) : pair();
-      });
+        // Identified beta.2 code users retain isolated private-code setup. Unknown identity cannot acquire a per-agent lock until exchange.
+        if (expectedDir) return withLock(expectedDir, pair);
+        // Published beta.2 allowed an omitted ID. Isolate that legacy interactive path to its project, not the home shared by all agents.
+        const legacyDir = join(home, digest(plan.projectUrl)); privateDir(legacyDir);
+        return withLock(legacyDir, pair);
+      }
     },
     prepare(options) {
       const dir = connectionDir(home, options.connection);
@@ -97,6 +102,14 @@ export function createSessionOperations({ home = sessionHome(), io, sys = system
         for (const agent of readdirSync(join(home, key))) {
           if (!/^[\w-]{1,200}$/.test(agent)) continue;
           const id = `${key}/${agent}`, dir = connectionDir(home, id);
+          if (lstatExists(join(dir, 'pending-browser.json'))) {
+            const pending = readPrivate(join(dir, 'pending-browser.json'), true);
+            if (pending.status !== 'saved') {
+              const position = records.findIndex(record => record.id === id);
+              const browser = { id, service: pending.service, agentId: pending.agentId, agentName: 'browser approval', folder: pending.folder, provider: pending.provider, pendingBrowser: pending.status };
+              if (position >= 0) records[position] = browser; else records.push(browser);
+            }
+          }
           if (lstatExists(join(dir, 'pending-session.json'))) {
             const { token, ...receipt } = readPrivate(join(dir, 'pending-session.json'), true);
             const position = records.findIndex(record => record.id === id);
@@ -105,6 +118,6 @@ export function createSessionOperations({ home = sessionHome(), io, sys = system
           }
         }
       }
-      io.say(JSON.stringify(records.map(record => ({ id: record.id, agent: record.agentName, project: record.service, workspace: record.folder, provider: record.provider, mcp: sessionName(record), state: record.pending ? 'interrupted pairing; use session-prepare' : 'saved locally; live activity not checked' })), null, 2)); },
+      io.say(JSON.stringify(records.map(record => ({ id: record.id, agent: record.agentName, project: record.service, workspace: record.folder, provider: record.provider, mcp: sessionName(record), state: record.pendingBrowser ? `browser setup ${record.pendingBrowser}; use browser-prepare or browser-status --connection ${record.id}` : record.pending ? 'interrupted pairing; use session-prepare' : 'saved locally; live activity not checked' })), null, 2)); },
   };
 }