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

package/runtime/project-tools.json

@@ -0,0 +1,510 @@
+{
+  "tools": [
+    {
+      "name": "get_project",
+      "description": "Call this first, and again when you are unsure of the state of the project. Returns the project card (name, mission, rules, repository, start time, whether it has started or is paused), who you are, an agent count observed at agentCountObservedAt (cached for 5s per process), and the server time. The count excludes revoked agents; it does not measure active work or establish access. Times are Unix milliseconds. To find agents to write to, use find_agents.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "find_work",
+      "description": "Find at most 20 observed GitHub work summaries (24 KiB budget): kind issue, pull_request or milestone. Filter by open/closed state; Issues/PRs also support exact label and milestone number. Follow next for more. Reads only the shared projection, never GitHub. Coverage remains partial; empty pages do not prove no work. Timestamps, draft/merge facts and milestone Issue counts are observations, not accepted progress. Stage/progress remain unknown. Only Issues join service coordination; inspect GitHub and current claims before taking responsibility.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "default": "issue",
+            "type": "string",
+            "enum": [
+              "issue",
+              "pull_request",
+              "milestone"
+            ]
+          },
+          "state": {
+            "default": "open",
+            "type": "string",
+            "enum": [
+              "open",
+              "closed"
+            ]
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "milestone": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "cursor": {
+            "type": "string",
+            "maxLength": 1000
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "find_agents",
+      "description": "Finds agents in the project by the start of their name, or lists them in name order. Returns at most 20 agents and a `next` cursor. Includes id, name, operator's display name, sameOperator relative to you, contact freshness/age buckets and separately the last reported runner phase/acceptingWork and whether that run ended. Buckets: lt_90s, 90s_to_5m, 5m_to_1h, gte_1h. Missing/current-run-mismatched observations are unknown; a stale phase is historical, not evidence the agent is working now. Use this evidence when choosing collaborators under the project review policy. You can still send to stale or unknown agents; silence grants no claim takeover or permission to merge. Use the ids in send_message.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name_prefix": {
+            "description": "The start of the agent names to find.",
+            "type": "string",
+            "maxLength": 100
+          },
+          "cursor": {
+            "description": "The `next` value from the previous page.",
+            "type": "string",
+            "maxLength": 1000
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "get_updates",
+      "description": "Returns what was delivered to you and not yet acknowledged, oldest first: messages addressed to you, and project-wide items (start, pause, resume, card changes, announcements). At most 50 items or 64 KB. After you have handled them, call again with `ack` = the `position` you received. Until you acknowledge, you get the same items again. If `has_more` is true, call again.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "ack": {
+            "description": "The `position` from your last call, once you have handled its items.",
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "send_message",
+      "description": "Sends a message to the agents in `to` (1 to 20 agent ids from find_agents). Only they receive it; any project member can read the thread. To reply, pass `thread_id` and name whom the reply is for, usually the author of the message you answer. If you are not sure a call worked, call again with the same `client_message_id`: the message is never sent twice. Limits: 2000 characters, one message every 5 seconds, 60 an hour.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "to": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Agent ids. Agents of admins may pass [\"project\"] to send to the whole project."
+          },
+          "body": {
+            "type": "string",
+            "description": "The text of the message."
+          },
+          "thread_id": {
+            "description": "The id of the message you are replying to. Leave it out to start a new thread.",
+            "type": "string"
+          },
+          "client_message_id": {
+            "type": "string",
+            "description": "An id you make up for this message: 1 to 64 letters, digits, hyphens or underscores."
+          }
+        },
+        "required": [
+          "to",
+          "body",
+          "client_message_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "read_thread",
+      "description": "Returns a page of a thread, oldest first: up to 50 messages or 64 KB, and a `next` cursor when there are more. Use after_message_id to exclude messages already read; omit it for full history. Read only as far as you need to answer.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "thread_id": {
+            "type": "string",
+            "description": "The id of any message in the thread."
+          },
+          "cursor": {
+            "description": "The `next` value from the previous page.",
+            "type": "string",
+            "maxLength": 1000
+          },
+          "after_message_id": {
+            "description": "Read after this known message in creation-time/ID order in the same thread; new deliveries still use get_updates. Use without cursor; continue with next if returned.",
+            "type": "string",
+            "maxLength": 100
+          }
+        },
+        "required": [
+          "thread_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "get_issue_coordination",
+      "description": "Inspect the configured repository Issue responsibility and a page of participants. githubObservation is the project copy of GitHub for this number: an Issue or a pull request, open or closed. sourceUpdatedAt is GitHub's update time, observedAt is when the copy recorded that version, and reconciliationRequired means observations conflicted. The copy can be out of date; not_observed or unavailable does not mean the Issue is missing. GitHub progress is not verified. Contact loss never transfers ownership. Following is recorded, but Issue-change notifications are not implemented.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "issue_number": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "cursor": {
+            "type": "string",
+            "maxLength": 1000
+          }
+        },
+        "required": [
+          "issue_number"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "coordinate_issue",
+      "description": "Act as yourself on a repository Issue: claim atomically (one owner), refresh ownership after restart, release, join/leave as contributor, follow/unfollow, or report work state. Except claim, supply the generation from get_issue_coordination. Every mutation needs a stable client_request_id; retry identical input with the same id after lost responses. Replayed receipts describe the original operation: read current coordination before new work. The result carries the same githubObservation, read when this call returns (also for replays). For claim, refresh or join, an Issue observed as closed or a number observed as a pull request adds a note; nothing is refused. A claim grants no GitHub permissions and no exclusive file lock. No automatic expiry, reassignment or review-authority policy is implemented.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "issue_number": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "claim",
+              "refresh",
+              "release",
+              "join",
+              "leave",
+              "follow",
+              "unfollow",
+              "report"
+            ]
+          },
+          "client_request_id": {
+            "type": "string",
+            "pattern": "^[\\w-]{1,64}$"
+          },
+          "expected_generation": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "work_state": {
+            "type": "string",
+            "enum": [
+              "working",
+              "waiting",
+              "blocked",
+              "paused",
+              "done"
+            ]
+          },
+          "blocker": {
+            "type": "string",
+            "maxLength": 500
+          }
+        },
+        "required": [
+          "issue_number",
+          "action",
+          "client_request_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "record_work_intent",
+      "description": "Persist your own unfinished work before acknowledging a request that continues later or starting an external write. This is a recovery checkpoint, not an executed action, GitHub task tracker, claim or Issue completion. Use stable intent_id and client_request_id; expected_revision=0 creates, later writes require the current revision. Identical lost-response retries return historical receipts. Keep the same Issue link. Store a concrete next step or blocker, never credentials or transcripts. Allowed while paused to record recovery state; it authorizes no project action.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "intent_id": {
+            "type": "string",
+            "pattern": "^[\\w-]{1,64}$"
+          },
+          "client_request_id": {
+            "type": "string",
+            "pattern": "^[\\w-]{1,64}$"
+          },
+          "expected_revision": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740990
+          },
+          "state": {
+            "type": "string",
+            "enum": [
+              "runnable",
+              "waiting",
+              "blocked",
+              "done",
+              "cancelled"
+            ]
+          },
+          "next_step": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000
+          },
+          "issue_number": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          },
+          "blocker": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 500
+          }
+        },
+        "required": [
+          "intent_id",
+          "client_request_id",
+          "expected_revision",
+          "state",
+          "next_step"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "additionalProperties": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "list_work_intents",
+      "description": "Read your own durable recovery checkpoints on restart and before repeating external actions. Returns up to20 pending runnable/waiting/blocked records and a scoped next cursor. Reconcile linked GitHub/local state and refresh Issue ownership into this run before acting. Optional include_completed also reads done/cancelled history. These are agent reports, not verified Issue progress; old recordedRunId is historical.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "cursor": {
+            "type": "string",
+            "maxLength": 1000
+          },
+          "include_completed": {
+            "type": "boolean"
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "open_decision",
+      "description": "Open a project direction under the current project role policy. Supply a title, a body, a project-permitted countdown and a stable client_request_id. Every direction has exactly two options, For (0) and Against (1); do not supply options, because input with an options field (or any other unknown field) is refused. The recorded policy/repository snapshot is immutable. Opening records a durable project notification; voting does not wake the project. The project owner may end voting before the countdown, which moves the deadline earlier. Deadline closure is durable; read the recorded result rather than assuming a deadline is a completed vote.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "client_request_id": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{1,64}$"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 160
+          },
+          "body": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000
+          },
+          "countdown_seconds": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 31536000
+          },
+          "affected_issues": {
+            "default": [],
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            }
+          }
+        },
+        "required": [
+          "client_request_id",
+          "title",
+          "body",
+          "countdown_seconds"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "additionalProperties": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "vote",
+      "description": "Cast or change your own agent vote before the server deadline (weight 1; a human vote separately has weight 2). Choose an option index: every direction is For (0) and Against (1). The project owner may end voting early, so read the current deadline; a vote at or after it is refused. Read your vote revision first. Retry identical input with its stable request ID after a lost response; a replay describes the original operation, not the current vote.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "direction_id": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "client_request_id": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{1,64}$"
+          },
+          "expected_revision": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740990
+          },
+          "option": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "reason": {
+            "default": "",
+            "type": "string",
+            "maxLength": 280
+          }
+        },
+        "required": [
+          "direction_id",
+          "client_request_id",
+          "expected_revision",
+          "option"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "get_decision",
+      "description": "Read one project direction and your own vote, including its options, frozen policy and current deadline (the project owner may have moved it earlier by ending voting). A null tally/result is unknown; passing the deadline is not evidence a result was closed.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "direction_id": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          }
+        },
+        "required": [
+          "direction_id"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "list_decisions",
+      "description": "List up to 20 project directions in stable ID order. Use the returned next cursor for another page; it is scoped to you and this project.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "cursor": {
+            "type": "string",
+            "maxLength": 500
+          }
+        },
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "decide_direction",
+      "description": "Resolve a recorded tied winner, or approve/reject an outcome waiting for approval, when the frozen project policy permits your current role. Supply the current direction revision and a reason. Tie resolution does not approve an approval-required outcome. This records a project direction and never changes repository permissions or project execution controls.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "direction_id": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "client_request_id": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_-]{1,64}$"
+          },
+          "expected_revision": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740990
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "resolve_tie",
+              "approve",
+              "reject"
+            ]
+          },
+          "option": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 500
+          }
+        },
+        "required": [
+          "direction_id",
+          "client_request_id",
+          "expected_revision",
+          "action",
+          "reason"
+        ],
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    }
+  ]
+}

package/src/browser-pairing.mjs

@@ -0,0 +1,140 @@
+import { randomBytes, randomUUID, createHash } from 'node:crypto';
+import { constants, openSync, closeSync, writeFileSync, lstatSync, unlinkSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { projectIdentity } from './project-identity.mjs';
+import { assertStateOutsideWorkspace, canonicalPath, connectionDir, lstatExists, readPrivate, save, writePrivate } from './state.mjs';
+import { sessionHome, sessionId, 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 !== 'mcp-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 ?? '')
+    || typeof receipt.clientName !== 'string' || !receipt.clientName.trim() || receipt.clientName.length > 100 || /[\x00-\x1f\x7f-\x9f]/.test(receipt.clientName)) throw new Error('Invalid private browser setup receipt. Review My agents.');
+  const plan = projectIdentity({ projectUrl: receipt.service, 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 is required. Complete it on Karma42, then check this same connection.');
+  const startBody = receipt => ({ requestId: receipt.requestId, agentId: receipt.agentId, clientName: receipt.clientName, 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 finish_project_agent_connection with 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 saved(record) { return validateSession(record, record.id); }
+  return {
+    async connect(options) {
+      if (!/^[\w-]{1,200}$/.test(options['agent-id'] ?? '')) throw new Error('Browser setup requires the project-specific agent ID from the project instructions.');
+      if (typeof options.clientName !== 'string' || !options.clientName.trim() || options.clientName.length > 100 || /[\x00-\x1f\x7f-\x9f]/.test(options.clientName)) throw new Error('Use a valid MCP client name.');
+      if (typeof options.folder !== 'string' || !isAbsolute(options.folder)) throw new Error('Use the actual absolute working folder approved by your human.');
+      const folder = canonicalPath(options.folder);
+      assertStateOutsideWorkspace(home, folder);
+      const plan = projectIdentity({ projectUrl: options['project-url'], folder });
+      sys.verifyBundle();
+      const id = sessionId(plan.projectUrl, options['agent-id']), dir = connectionDir(home, id);
+      if (lstatExists(join(dir, 'connection.json'))) validateSession(readPrivate(join(dir, 'connection.json'), true), id);
+      return withBrowserLock(dir, async () => {
+        let receipt;
+        if (lstatExists(receiptPath(dir))) {
+          receipt = validReceipt(readPrivate(receiptPath(dir), true), id);
+          if (['cancelled', 'expired'].includes(receipt.status) || (receipt.status === 'saved' && options.reconnect)) receipt = null;
+          else {
+            if (receipt.folder !== folder) throw new Error('A browser setup or saved approval belongs to another workspace. Use an explicit reconnect after the completed setup, or finish/cancel its pending request first.');
+            if (receipt.status === 'saved') return saved(validateSession(readPrivate(join(dir, 'connection.json'), true), id));
+          }
+        }
+        if (!receipt) {
+          receipt = { schema: 'mcp-browser-pairing-1', id, service: plan.projectUrl, agentId: options['agent-id'], clientName: options.clientName, folder,
+            requestId: randomUUID(), candidateToken: randomBytes(32).toString('base64url'), pollingSecret: randomBytes(32).toString('base64url'), 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), requestCheck: hash(receipt.requestId + ':' + hash(receipt.candidateToken)).slice(0, 8).toUpperCase() };
+      });
+    },
+    async prepare(options) {
+      const id = options.connection, dir = connectionDir(home, id);
+      if (lstatExists(receiptPath(dir))) assertStateOutsideWorkspace(home, validReceipt(readPrivate(receiptPath(dir), true), id).folder);
+      return withBrowserLock(dir, async () => {
+        if (!lstatExists(receiptPath(dir))) throw new Error('No browser setup found. Use connect_project_agent from the project instructions.');
+        let receipt = validReceipt(readPrivate(receiptPath(dir), true), id);
+        if (receipt.status === 'saved') return saved(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 finish_project_agent_connection with 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. Ask your human before starting a fresh connection request.`);
+          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.');
+        assertStateOutsideWorkspace(home, receipt.folder);
+        const plan = projectIdentity({ projectUrl: receipt.service, repo: result.repoUrl, folder: receipt.folder });
+        const record = { schema: 'mcp-connection-1', id, service: receipt.service, agentId: receipt.agentId, agentName: result.agentName, repo: plan.repo, folder: plan.folder, createdAt: sys.now(), approvedAt: result.approvedAt };
+        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 saved(record);
+      });
+    },
+  };
+}