openzoo 0.50.54 → 0.50.56

package/lib/cursorbackend.js

@@ -52,6 +52,8 @@ import {
 import {
   desktopAction, displayBounds, imageSize, noteShotMeta, resolveAppName,
 } from './grokbotDesktop.js';
+import { startHostMcps, hostMcpTools, hostMcpHas, callHostMcp, hostMcpServers } from './mcpbridge.js';
+import * as ship from './ship.js';
 
 const TLS_DIR = path.join(os.homedir(), '.openzoo', 'cursor-tls');
 const CURSOR_HOSTS = ['api2.cursor.sh', 'api3.cursor.sh', 'api4.cursor.sh', 'repo42.cursor.sh'];
@@ -1455,6 +1457,27 @@ function seedBriefOnCanvas(agent, log) {
   }
   return kickBriefedAgent(agent, log || ((m) => console.error(m)));
 }
+/** Overlay prompts ITS user: no factory yet -> paint how to start one. Once per process. */
+export function shipNudgeText() {
+  return [
+    '[grok ship] No software factory on this Mac yet.',
+    'Tell me: set up Grok Ship for ~/path/to/repo',
+    'I will create Firstmate (the one bot you talk to) and a crewmate for that repo. Then give Firstmate ship tasks: it runs a worker on a branch, a fresh review of the diff, and opens the PR only when the review is clean. You merge.',
+  ].join('\n');
+}
+let shipNudged = false;
+function seedShipNudge(list, activeId) {
+  if (shipNudged || !activeId) return false;
+  const roster = Array.isArray(list) ? list : [];
+  if (roster.some((a) => /^firstmate$/i.test(String(a?.name || '')))) { shipNudged = true; return false; }
+  const t = agentTranscript(activeId);
+  if ((t.entries || []).some((e) => /\[grok ship\]/.test(String(e?.content || e?.message?.content || '')))) { shipNudged = true; return false; }
+  shipNudged = true;
+  const nonce = `oz-ship-nudge-${activeId}`;
+  const line = fanoutLine(activeId, 'assistant', shipNudgeText(), { clientNonce: nonce, requestId: nonce });
+  ssePush('transcript', { ...gatewayEntry(line), agentId: activeId });
+  return true;
+}
 function groupMemberIds(agentId) {
   const a = (cachedAgentList() || []).find((x) => x.id === agentId);
   if (!a?.isGroup) return [];
@@ -2170,10 +2193,89 @@ const LOCAL_TOOLS = [
       },
     },
   },
+  {
+    type: 'function',
+    function: {
+      name: 'ship_crew',
+      description: 'Grok Ship: set up the factory for a repo. Creates Firstmate (once) and one crewmate bot for this repo with standing briefs, detects the forge (gh/glab). Call when the user asks for a software factory / Grok Ship / crew for a repo.',
+      parameters: {
+        type: 'object',
+        properties: { cwd: { type: 'string', description: 'Repo path on this Mac.' } },
+        required: ['cwd'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'ship_forge',
+      description: 'Grok Ship: detect the source-control forge for a repo (github/gitlab/bitbucket/origin) and which CLI is authenticated (gh/glab). Do not assume GitHub.',
+      parameters: { type: 'object', properties: { cwd: { type: 'string' } }, required: ['cwd'] },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'ship_launch_worker',
+      description: 'Grok Ship: start a coding worker (claude-zoo, paid via x402) in a fresh git worktree on a new branch. Returns a task id. Pass the same task id again to send review findings back to the same branch. Never opens a PR.',
+      parameters: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Repo path.' },
+          title: { type: 'string' },
+          prompt: { type: 'string', description: 'Goal, acceptance criteria, constraints. Or the review findings on a follow-up.' },
+          base: { type: 'string', description: 'Base branch. Default: origin HEAD.' },
+          task: { type: 'string', description: 'Existing task id to resume on its branch.' },
+        },
+        required: ['cwd', 'prompt'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'ship_status',
+      description: 'Grok Ship: is the worker alive, did it push, what did it commit, log tail. Poll this (with schedule_wakeup) instead of guessing.',
+      parameters: { type: 'object', properties: { task: { type: 'string' } }, required: ['task'] },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'ship_review',
+      description: 'Grok Ship: FRESH adversarial review of the pushed branch (one-shot, no chat history, only the diff). Returns findings + gate. Run after every push, before any PR.',
+      parameters: {
+        type: 'object',
+        properties: {
+          task: { type: 'string' },
+          cwd: { type: 'string', description: 'Without a task: repo path.' },
+          branch: { type: 'string' },
+          base: { type: 'string' },
+        },
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'ship_open_pr',
+      description: 'Grok Ship: open the PR/MR for a task. Refuses unless the last ship_review gate is clean and the branch is on origin. Never merges.',
+      parameters: {
+        type: 'object',
+        properties: { task: { type: 'string' }, title: { type: 'string' }, body: { type: 'string' } },
+        required: ['task'],
+      },
+    },
+  },
 ];
 
 export const LOCAL_TOOL_NAMES = LOCAL_TOOLS.map((t) => t.function.name);
 
+function liveTools() {
+  const extra = hostMcpTools();
+  return extra.length ? [...LOCAL_TOOLS, ...extra] : LOCAL_TOOLS;
+}
+
 async function captureScreenshot(log) {
   const dir = path.join(os.tmpdir(), 'openzoo-screens');
   fs.mkdirSync(dir, { recursive: true });
@@ -2361,12 +2463,77 @@ async function runLocalTool(name, args, log, ctx = {}) {
       if (!who) return 'ERROR no such agent';
       return JSON.stringify(cancelAgentWakeup(who.id));
     }
+    if (name.startsWith('ship_')) {
+      return await runShipTool(name, args, log, ctx);
+    }
+    if (hostMcpHas(name)) {
+      return await callHostMcp(name, args);
+    }
     return `unknown tool ${name}`;
   } catch (e) {
     return `ERROR ${e.message}`;
   }
 }
 
+/** Grok Ship tools. `run` is execLocal so workers/PRs use the same shell the bot does. */
+async function runShipTool(name, args, log, ctx = {}) {
+  const run = (command, cwd) => execLocal(command, cwd, log);
+  const home = HOME;
+  if (name === 'ship_forge') {
+    const cwd = expandUserPath(String(args.cwd || ''));
+    return JSON.stringify(await ship.probeForge(cwd, run));
+  }
+  if (name === 'ship_crew') {
+    const cwd = expandUserPath(String(args.cwd || ''));
+    const forge = await ship.probeForge(cwd, run);
+    const list = cachedAgentList() || [];
+    let firstmate = list.find((a) => /^firstmate$/i.test(String(a.name || '')));
+    if (!firstmate) {
+      firstmate = mintLocalAgent({ name: 'Firstmate', brief: ship.firstmateBrief() });
+      pushCreatedAgent(firstmate, { select: false });
+      seedBriefOnCanvas(firstmate, log);
+    }
+    const repoName = path.basename(cwd);
+    let crew = list.find((a) => String(a.brief || '').includes(`crewmate for the repo at ${cwd}`));
+    if (!crew) {
+      crew = mintLocalAgent({ name: `Crew · ${repoName}`, brief: ship.crewmateBrief({ repo: cwd, forge: forge.forge }) });
+      pushCreatedAgent(crew, { select: false });
+      seedBriefOnCanvas(crew, log);
+    }
+    log(`cursor-backend:      ship_crew repo=${cwd} forge=${forge.forge} cli=${forge.cli} firstmate=${firstmate.id} crew=${crew.id}`);
+    return JSON.stringify({
+      ok: true,
+      forge,
+      firstmate: { id: firstmate.id, name: firstmate.name },
+      crewmate: { id: crew.id, name: crew.name },
+      next: forge.cli ? 'Talk to Firstmate. It hands ship tasks to the crewmate.' : `No authenticated forge CLI (${forge.forge}); run gh auth login / glab auth login on this Mac before ship_open_pr.`,
+    });
+  }
+  if (name === 'ship_launch_worker') {
+    const cwd = expandUserPath(String(args.cwd || ''));
+    const task = await ship.launchWorker({
+      cwd, title: args.title, prompt: args.prompt, base: args.base, taskId: args.task, home, run, log,
+    });
+    return JSON.stringify({ ok: true, task: task.id, branch: task.branch, base: task.base, worktree: task.worktree, log: task.log, pid: task.pid, attempts: task.attempts });
+  }
+  if (name === 'ship_status') {
+    return JSON.stringify(await ship.taskStatus({ taskId: String(args.task || ''), home, run }));
+  }
+  if (name === 'ship_review') {
+    const got = await ship.reviewBranch({
+      taskId: args.task ? String(args.task) : undefined,
+      cwd: args.cwd ? expandUserPath(String(args.cwd)) : undefined,
+      branch: args.branch, base: args.base,
+      model: currentModel(ctx.agentId), home, run, log,
+    });
+    return JSON.stringify(got);
+  }
+  if (name === 'ship_open_pr') {
+    return JSON.stringify(await ship.openPr({ taskId: String(args.task || ''), title: args.title, body: args.body, home, run, log }));
+  }
+  return `unknown tool ${name}`;
+}
+
 /** Model parked instead of writing files. Host keeps the tool loop going. */
 export function looksStoppedReply(s) {
   return /stopped on research|no (?:new )?app files written|nothing (?:extra )?to open yet|say go again|next message i['’]?ll write|stopped — no new/i.test(String(s || ''));
@@ -2457,11 +2624,28 @@ async function zooComplete(prompt, log, agentId, parsed = {}, opts = {}) {
             return brief ? `${who} Standing brief (persisted): ${brief}` : who;
           })(),
           `You HAVE local tools on the user's computer via ${via}.`,
-          'Tools: read_file, write_file, exec, list_dir, screenshot, click, type_text, key, ui_tree, focus_app, open_url, create_agent, set_brief, list_agents, message_agent, schedule_wakeup, cancel_wakeup.',
+          'Tools: read_file, write_file, exec, list_dir, screenshot, click, type_text, key, ui_tree, focus_app, open_url, create_agent, set_brief, list_agents, message_agent, schedule_wakeup, cancel_wakeup, ship_crew, ship_forge, ship_launch_worker, ship_status, ship_review, ship_open_pr.',
+          'If no sidebar bot is named Firstmate and the human brings code or repo work, ask ONE question: which repo path to set up Grok Ship for. Then call ship_crew with that cwd. Do not start coding outside the factory.',
+          'Grok Ship (software factory): ship_crew sets up Firstmate + a crewmate per repo. A crewmate ships with ship_launch_worker -> ship_status until pushed -> ship_review (fresh, diff-only) -> ship_open_pr only when gate.clean. Never merge; the human does.',
+          (() => {
+            const extra = hostMcpTools();
+            const names = extra.map((t) => t.function.name);
+            const servers = hostMcpServers();
+            if (!names.length) {
+              return 'Host MCP servers (Claude/Grok chrome-devtools, brave, …) are connecting. When chrome-devtools__* tools appear, use them for web pages.';
+            }
+            const chrome = names.filter((n) => /chrome|devtools|browser/i.test(n));
+            return [
+              `Host MCP tools from the user's local Claude/Grok config are attached (${servers.join(', ') || 'mcp'}): ${names.slice(0, 36).join(', ')}${names.length > 36 ? '…' : ''}.`,
+              chrome.length
+                ? 'For any web page or HTML form, use chrome-devtools tools (navigate_page / take_snapshot / fill / click). Do NOT use osascript, Quartz, Python Foundation, or AppleScript to read Brave. screenshot/click/type_text are for native Mac UI only.'
+                : 'Use matching MCP tools instead of inventing shell one-liners.',
+            ].join(' ');
+          })(),
           'create_agent mints a sidebar bot. ALWAYS pass brief so they keep the job across restart. set_brief updates it. list_agents + message_agent talk to other bots (one hop). Do not tell the human to copy-paste between canvases.',
           'NEVER STOP / cron / keep working between human messages: call schedule_wakeup every="5m". That is a host timer. There is no crontab. Do not spawn more bots for persistence. Do not re-read SITREP-NOW.md or STANDING-ORDERS.md every turn — do the next file or click. exec sysctl/uptime is not the job. If the tray already has named workers, answer "no" to spawning more.',
           'You CAN click the Mac and fill/submit browser forms. That is required when the user asks. Do not write a markdown briefing instead of clicking. Do not tell the user to click.',
-          'Form loop: focus_app Brave Browser → screenshot → click the field (query or x,y) → type_text → screenshot to confirm → click Submit / key enter. screenshot.screen is click coordinate space. Prefer click query="Submit".',
+          'Form loop: if chrome-devtools MCP tools exist, navigate_page + take_snapshot + fill the fields + click the submit button. Else fallback: focus_app Brave Browser → screenshot → click the field → type_text → screenshot → click Submit.',
           'screenshot captures the display and attaches the image. For any on-screen form, dashboard, or click target, screenshot first this turn. Do not guess at UI you have not seen.',
           'Pasted images arrive as attachments — you can see them when present. Do not claim you cannot see images if they are in this turn.',
           'Never claim you lack filesystem access or local-exec. If a tool errors, report the error.',
@@ -2560,7 +2744,7 @@ async function zooComplete(prompt, log, agentId, parsed = {}, opts = {}) {
     throwIfAborted();
     const payload = { model, messages, max_tokens: maxTok };
     if (!chatOnly) {
-      payload.tools = LOCAL_TOOLS;
+      payload.tools = liveTools();
       payload.tool_choice = 'auto';
     }
     const { r, data } = await zooPost(payload);
@@ -2970,6 +3154,7 @@ async function handleHijackedPodHttp(req, res, full, body, log) {
           activeAgentId: active,
         });
       }
+      if (seedShipNudge(list, active)) log(`cursor-backend:      ship nudge painted on ${active}`);
       log(`cursor-backend:      listAgents local n=${list.length} account=${activeAccountId || 'none'} active=${active || 'none'}`);
       return true;
     }
@@ -3463,6 +3648,7 @@ export function startCursorBackend({ port = 8443, models, log = () => {} } = {})
   // the platform refuses (v6 disabled), fall back to v4 so we still work.
   server.on('error', (e) => log(`cursor-backend: server error ${e.code || e.message}`));
   const onUp = (what) => log(`cursor-backend: listening on ${what}:${port} as ${CURSOR_HOSTS[0]}`);
+  startHostMcps({ log }).catch((e) => log(`cursor-backend:      mcp start ${e.message}`));
   try {
     server.listen({ port, host: '::', ipv6Only: false }, () => onUp('[::]+127.0.0.1'));
   } catch {

package/lib/mcpbridge.js

@@ -0,0 +1,350 @@
+/**
+ * Load the operator's local MCP servers (Grok / Claude / Cursor) and expose
+ * them as OpenAI function tools for Grok Bot zoo turns.
+ *
+ * chrome-devtools is always attached if missing — that is Claude-in-Chrome
+ * for this hijack: navigate / snapshot / fill the live page, not osascript.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import net from 'node:net';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const SKIP = /^(openzoo|openzoo-mcp)$/i;
+const NAME_RE = /[^a-zA-Z0-9_-]/g;
+
+const registry = new Map();
+let openaiTools = [];
+let started = null;
+let serversUp = [];
+
+export function hostMcpTools() {
+  return openaiTools;
+}
+
+export function hostMcpHas(name) {
+  return registry.has(String(name || ''));
+}
+
+export function hostMcpServers() {
+  return [...serversUp];
+}
+
+export function toolOpenaiName(server, toolName) {
+  return `${String(server || 'mcp').replace(NAME_RE, '_') }__${String(toolName || 'tool').replace(NAME_RE, '_')}`.slice(0, 64);
+}
+
+export function flattenMcpResult(r) {
+  const parts = [];
+  const content = Array.isArray(r?.content) ? r.content : [];
+  for (const c of content) {
+    if (!c || typeof c !== 'object') continue;
+    if (c.type === 'text' && c.text) parts.push(String(c.text));
+    else if (c.type === 'image') parts.push(`[image ${c.mimeType || 'png'} ${(c.data || '').length}b]`);
+    else parts.push(JSON.stringify(c));
+  }
+  const body = parts.join('\n').trim() || JSON.stringify(r ?? {});
+  const out = r?.isError ? `ERROR ${body}` : body;
+  return out.slice(0, 20_000);
+}
+
+function stripJsonComments(s) {
+  return String(s || '').replace(/^\s*\/\/.*$/gm, '');
+}
+
+function readJsonFile(p) {
+  try { return JSON.parse(stripJsonComments(fs.readFileSync(p, 'utf8'))); } catch { return null; }
+}
+
+/** Enough TOML for ~/.grok/config.toml [mcp_servers.*] tables. */
+export function parseTomlMcpServers(text) {
+  const servers = {};
+  let cur = null;
+  let nested = null;
+  let arrayKey = null;
+  let arrayBuf = [];
+  const ensure = (name) => {
+    if (!servers[name]) servers[name] = { name };
+    return servers[name];
+  };
+  const flushArray = () => {
+    if (!cur || !arrayKey) return;
+    const vals = arrayBuf.map((x) => unquote(x)).filter((x) => x !== '');
+    cur[arrayKey] = vals;
+    arrayKey = null;
+    arrayBuf = [];
+  };
+  const unquote = (raw) => {
+    let s = String(raw || '').trim().replace(/,$/, '').trim();
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+      s = s.slice(1, -1);
+    }
+    if (s === 'true') return true;
+    if (s === 'false') return false;
+    if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s);
+    return s;
+  };
+  for (const rawLine of String(text || '').split(/\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (arrayKey) {
+      if (line.startsWith(']')) {
+        flushArray();
+        continue;
+      }
+      arrayBuf.push(line.replace(/,$/, ''));
+      continue;
+    }
+    const nestedSec = line.match(/^\[mcp_servers\.([^\]]+?)\.([a-zA-Z0-9_-]+)\]$/);
+    if (nestedSec) {
+      cur = ensure(nestedSec[1]);
+      nested = nestedSec[2];
+      if (!cur[nested] || typeof cur[nested] !== 'object' || Array.isArray(cur[nested])) cur[nested] = {};
+      continue;
+    }
+    const sec = line.match(/^\[mcp_servers\.([^\]]+)\]$/);
+    if (sec) {
+      cur = ensure(sec[1]);
+      nested = null;
+      continue;
+    }
+    if (line.startsWith('[')) {
+      cur = null;
+      nested = null;
+      continue;
+    }
+    if (!cur) continue;
+    const kv = line.match(/^([a-zA-Z0-9_-]+)\s*=\s*(.*)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    const rest = kv[2].trim();
+    if (rest === '[' || rest.startsWith('[')) {
+      arrayKey = key;
+      arrayBuf = [];
+      const inner = rest.replace(/^\[/, '').replace(/\]\s*$/, '').trim();
+      if (rest.includes(']') && rest !== '[') {
+        if (inner) arrayBuf = inner.split(',').map((x) => x.trim());
+        flushArray();
+      }
+      continue;
+    }
+    const val = unquote(rest);
+    if (nested) cur[nested][key] = val;
+    else cur[key] = val;
+  }
+  flushArray();
+  return Object.values(servers);
+}
+
+export function fromJsonMcpServers(obj, fallbackName) {
+  if (!obj || typeof obj !== 'object') return [];
+  const src = obj.mcpServers && typeof obj.mcpServers === 'object' ? obj.mcpServers : obj;
+  const out = [];
+  for (const [name, raw] of Object.entries(src)) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
+    out.push({
+      name: String(name || fallbackName || 'mcp'),
+      command: raw.command,
+      args: Array.isArray(raw.args) ? raw.args.map(String) : (Array.isArray(raw.command) ? raw.command.slice(1) : undefined),
+      url: raw.url,
+      type: raw.type,
+      env: raw.env && typeof raw.env === 'object' ? raw.env : undefined,
+      headers: raw.headers && typeof raw.headers === 'object' ? raw.headers : undefined,
+      enabled: raw.enabled !== false,
+    });
+  }
+  return out;
+}
+
+function shapeServer(raw) {
+  const name = String(raw?.name || '').trim();
+  if (!name || SKIP.test(name) || raw?.enabled === false) return null;
+  const command = Array.isArray(raw.command) ? raw.command[0] : raw.command;
+  const args = Array.isArray(raw.args)
+    ? raw.args.map(String)
+    : (Array.isArray(raw.command) ? raw.command.slice(1).map(String) : []);
+  const url = raw.url ? String(raw.url) : '';
+  if (!url && !command) return null;
+  return {
+    name,
+    command: command ? String(command) : '',
+    args,
+    url,
+    env: raw.env && typeof raw.env === 'object' ? Object.fromEntries(Object.entries(raw.env).map(([k, v]) => [k, String(v)])) : undefined,
+    headers: raw.headers && typeof raw.headers === 'object' ? raw.headers : undefined,
+  };
+}
+
+export function loadHostMcpConfigs(home = os.homedir()) {
+  const piles = [];
+  const grokToml = path.join(home, '.grok', 'config.toml');
+  try { piles.push(...parseTomlMcpServers(fs.readFileSync(grokToml, 'utf8'))); } catch { /* */ }
+  for (const p of [
+    path.join(home, '.claude', 'mcp.json'),
+    path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+    path.join(home, '.cursor', 'mcp.json'),
+  ]) {
+    const j = readJsonFile(p);
+    if (j) piles.push(...fromJsonMcpServers(j));
+  }
+  const seen = new Set();
+  const out = [];
+  for (const raw of piles) {
+    const s = shapeServer(raw);
+    if (!s || seen.has(s.name)) continue;
+    seen.add(s.name);
+    out.push(s);
+  }
+  if (![...seen].some((n) => /chrome|devtools|browser/i.test(n))) {
+    out.push({
+      name: 'chrome-devtools',
+      command: 'npx',
+      args: ['-y', 'chrome-devtools-mcp@latest'],
+      url: '',
+    });
+  }
+  return out;
+}
+
+export function mcpToOpenAiTool(server, tool) {
+  const schema = tool?.inputSchema && typeof tool.inputSchema === 'object'
+    ? { ...tool.inputSchema }
+    : { type: 'object', properties: {} };
+  if (!schema.type) schema.type = 'object';
+  if (!schema.properties) schema.properties = {};
+  delete schema.$schema;
+  return {
+    type: 'function',
+    function: {
+      name: toolOpenaiName(server, tool.name),
+      description: `[MCP ${server}] ${String(tool.description || tool.name || '').slice(0, 900)}`,
+      parameters: schema,
+    },
+  };
+}
+
+function portOpen(port, host = '127.0.0.1', ms = 150) {
+  return new Promise((resolve) => {
+    const sock = net.connect({ port, host });
+    const done = (ok) => {
+      try { sock.destroy(); } catch { /* */ }
+      resolve(ok);
+    };
+    sock.setTimeout(ms);
+    sock.on('connect', () => done(true));
+    sock.on('timeout', () => done(false));
+    sock.on('error', () => done(false));
+  });
+}
+
+async function chromeArgs(baseArgs) {
+  const args = [...(baseArgs || ['-y', 'chrome-devtools-mcp@latest'])];
+  if (args.some((a) => String(a).includes('browserUrl') || String(a) === '--browserUrl')) return args;
+  for (const port of [9222, 9333]) {
+    if (await portOpen(port)) {
+      args.push('--browserUrl', `http://127.0.0.1:${port}`);
+      break;
+    }
+  }
+  return args;
+}
+
+async function connectOne(cfg, log) {
+  const client = new Client({ name: 'openzoo-grokbot', version: '0.50.55' });
+  let transport;
+  if (cfg.url) {
+    const headers = {};
+    for (const [k, v] of Object.entries(cfg.headers || {})) headers[k] = String(v);
+    transport = new StreamableHTTPClientTransport(new URL(cfg.url), {
+      requestInit: { headers },
+    });
+  } else {
+    let args = cfg.args || [];
+    if (cfg.name === 'chrome-devtools') args = await chromeArgs(args);
+    const env = { ...getDefaultEnvironment(), PATH: process.env.PATH || '', ...(cfg.env || {}) };
+    if (process.env.NVM_DIR) env.NVM_DIR = process.env.NVM_DIR;
+    transport = new StdioClientTransport({
+      command: cfg.command,
+      args,
+      env,
+      stderr: 'pipe',
+    });
+    try {
+      transport.stderr?.on?.('data', (buf) => {
+        const line = String(buf).trim().split('\n')[0];
+        if (line) log?.(`cursor-backend:      mcp ${cfg.name} ${line.slice(0, 160)}`);
+      });
+    } catch { /* */ }
+  }
+  const ms = cfg.name === 'chrome-devtools' ? 90_000 : 45_000;
+  await Promise.race([
+    client.connect(transport),
+    new Promise((_, rej) => setTimeout(() => rej(new Error(`timeout ${ms}ms`)), ms)),
+  ]);
+  const listed = await client.listTools();
+  const tools = Array.isArray(listed?.tools) ? listed.tools : [];
+  return { client, tools };
+}
+
+function rebuildOpenai() {
+  openaiTools = [];
+  for (const [name, rec] of registry) {
+    openaiTools.push(mcpToOpenAiTool(rec.server, { name: rec.tool, description: rec.description, inputSchema: rec.schema }));
+    void name;
+  }
+}
+
+export async function callHostMcp(name, args) {
+  const rec = registry.get(String(name || ''));
+  if (!rec) throw new Error(`no mcp tool ${name}`);
+  const r = await rec.client.callTool({ name: rec.tool, arguments: args && typeof args === 'object' ? args : {} });
+  return flattenMcpResult(r);
+}
+
+export function resetHostMcpForTests() {
+  registry.clear();
+  openaiTools = [];
+  serversUp = [];
+  started = null;
+}
+
+export async function startHostMcps({ log = () => {}, home = os.homedir() } = {}) {
+  if (started) return started;
+  if (process.env.OZ_GROKBOT_MCP === '0') {
+    started = { tools: [], servers: [] };
+    return started;
+  }
+  started = (async () => {
+    const configs = loadHostMcpConfigs(home);
+    log(`cursor-backend:      mcp loading n=${configs.length} ${configs.map((c) => c.name).join(',')}`);
+    const results = await Promise.allSettled(configs.map((cfg) => connectOne(cfg, log)));
+    for (let i = 0; i < results.length; i++) {
+      const cfg = configs[i];
+      const r = results[i];
+      if (r.status !== 'fulfilled') {
+        log(`cursor-backend:      mcp ${cfg.name} FAIL ${r.reason?.message || r.reason}`);
+        continue;
+      }
+      serversUp.push(cfg.name);
+      for (const tool of r.value.tools) {
+        const openaiName = toolOpenaiName(cfg.name, tool.name);
+        if (registry.has(openaiName)) continue;
+        registry.set(openaiName, {
+          client: r.value.client,
+          server: cfg.name,
+          tool: tool.name,
+          description: tool.description || tool.name,
+          schema: tool.inputSchema,
+        });
+      }
+      log(`cursor-backend:      mcp ${cfg.name} tools=${r.value.tools.length}`);
+    }
+    rebuildOpenai();
+    log(`cursor-backend:      mcp ready servers=${serversUp.join(',') || 'none'} tools=${openaiTools.length}`);
+    return { tools: openaiTools, servers: serversUp };
+  })();
+  return started;
+}

package/lib/ship.js

@@ -0,0 +1,476 @@
+/**
+ * Grok Ship on the zoo — factory tools for the hijacked Grok Bot.
+ *
+ * Shape borrowed from kunchenguid/grok-ship (MIT): one Firstmate bot the
+ * human talks to, one crewmate bot per repo, a worker that writes code on a
+ * branch, a FRESH adversarial review of that branch, and a pull request only
+ * when the review is clean. The human merges.
+ *
+ * What is different here, and why:
+ *   - Workers are `claude-zoo -p` (open-claude-code through the :8402 proxy)
+ *     in a git worktree, not Cursor cloud agents. Cloud agents bill Cursor and
+ *     need Cursor's GitHub connector; the whole point of the hijack is x402
+ *     per-call billing, so the coding worker must ride the zoo too.
+ *   - The backlog is the forge's own issues (gh/glab) plus a small JSON ledger
+ *     at ~/.openzoo/ship/tasks.json, not a SQLite file. Nothing to migrate.
+ *   - The review is a one-shot zoo completion with NO chat history — that is
+ *     what "fresh subagent" means in practice. It only sees the diff.
+ *
+ * Pure helpers take `run(cmd, cwd)` / `post(messages, model)` so tests can
+ * drive them without a shell or a wallet.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const SHIM_ROOT = path.dirname(here);
+
+export function shipDir(home = os.homedir()) {
+  return path.join(home, '.openzoo', 'ship');
+}
+export function tasksPath(home = os.homedir()) {
+  return path.join(shipDir(home), 'tasks.json');
+}
+
+export function loadTasks(home = os.homedir()) {
+  try {
+    const j = JSON.parse(fs.readFileSync(tasksPath(home), 'utf8'));
+    return j && typeof j === 'object' && !Array.isArray(j) ? j : {};
+  } catch {
+    return {};
+  }
+}
+
+export function saveTasks(home, tasks) {
+  fs.mkdirSync(shipDir(home), { recursive: true });
+  const tmp = `${tasksPath(home)}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(tasks, null, 2));
+  fs.renameSync(tmp, tasksPath(home));
+  return tasks;
+}
+
+export function newTaskId(now = Date.now(), rand = Math.random()) {
+  const t = now.toString(36).slice(-5).toUpperCase();
+  const r = Math.floor(rand * 1296).toString(36).padStart(2, '0').toUpperCase();
+  return `SH-${t}${r}`;
+}
+
+export function slugBranch(taskId, title = '') {
+  const slug = String(title || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  return `ship/${String(taskId).toLowerCase()}${slug ? `-${slug}` : ''}`;
+}
+
+/* ------------------------------------------------------------------ forge */
+
+/** Pure: which forge a remote points at, and which CLI we can use for it. */
+export function detectForge({ remoteUrl = '', ghAuth = false, glabAuth = false } = {}) {
+  const u = String(remoteUrl || '').toLowerCase();
+  let forge = 'none';
+  if (/github\.com/.test(u)) forge = 'github';
+  else if (/gitlab\./.test(u)) forge = 'gitlab';
+  else if (/bitbucket\.org/.test(u)) forge = 'bitbucket';
+  else if (/cursor\.(com|sh)|origin\./.test(u)) forge = 'origin';
+  else if (u) forge = 'other';
+  let cli = null;
+  if (forge === 'github' && ghAuth) cli = 'gh';
+  if (forge === 'gitlab' && glabAuth) cli = 'glab';
+  return { forge, cli, remoteUrl: String(remoteUrl || '').trim() };
+}
+
+/** Shell-backed: ask git and the forge CLIs. `run` throws on non-zero. */
+export async function probeForge(cwd, run) {
+  const tryRun = async (cmd) => {
+    try { return { ok: true, out: String(await run(cmd, cwd) || '') }; } catch (e) { return { ok: false, out: String(e?.message || e) }; }
+  };
+  const remote = await tryRun('git remote get-url origin');
+  const remoteUrl = remote.ok ? remote.out.trim().split('\n')[0] : '';
+  const gh = await tryRun('gh auth status');
+  const glab = await tryRun('glab auth status');
+  const ghAuth = gh.ok && !/not logged in/i.test(gh.out);
+  const glabAuth = glab.ok && !/not logged in/i.test(glab.out);
+  const base = await defaultBase(cwd, run);
+  return { ...detectForge({ remoteUrl, ghAuth, glabAuth }), base, cwd };
+}
+
+export async function defaultBase(cwd, run) {
+  try {
+    const ref = String(await run('git symbolic-ref --short refs/remotes/origin/HEAD', cwd) || '').trim();
+    const m = ref.match(/^origin\/(.+)$/);
+    if (m) return m[1];
+  } catch { /* fall through */ }
+  for (const b of ['main', 'master']) {
+    try {
+      await run(`git rev-parse --verify --quiet refs/heads/${b}`, cwd);
+      return b;
+    } catch { /* next */ }
+  }
+  return 'main';
+}
+
+/* ----------------------------------------------------------------- worker */
+
+export function workerPrompt({ taskId, title, prompt, branch, base, forge = 'none' } = {}) {
+  return [
+    `Task ${taskId}: ${title || '(untitled)'}`,
+    '',
+    String(prompt || '').trim(),
+    '',
+    'Working rules:',
+    `- You are in a dedicated git worktree already on branch ${branch} (base ${base}). Do not switch branches.`,
+    '- Implement the task. Run the project tests the way the repo runs them. Fix what you break.',
+    '- Commit with clear messages. When done: `git push -u origin ' + branch + '`.',
+    '- Do NOT open a pull request or merge request. A separate reviewer reads the pushed branch first.',
+    `- Forge: ${forge}. Do not assume GitHub.`,
+    '- Finish with a short summary: what changed, how it was tested, anything the reviewer should look at.',
+  ].join('\n');
+}
+
+/** argv for the worker process. Override the binary with OPENZOO_SHIP_WORKER. */
+export function workerCommand({ prompt, shimRoot = SHIM_ROOT, env = process.env } = {}) {
+  const custom = env.OPENZOO_SHIP_WORKER;
+  const flags = ['-p', prompt, '--permission-mode', 'bypassPermissions', '--output-format', 'text'];
+  if (custom) return { file: custom, args: flags };
+  return { file: process.execPath, args: [path.join(shimRoot, 'bin', 'claude-zoo.js'), ...flags] };
+}
+
+export function isPidAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 0) return false;
+  try { process.kill(n, 0); return true; } catch (e) { return e?.code === 'EPERM'; }
+}
+
+/**
+ * Create the worktree, spawn a detached worker, record the task.
+ * `run(cmd, cwd)` runs shell; `spawnFn` defaults to child_process.spawn.
+ */
+export async function launchWorker({
+  cwd, title, prompt, base, taskId, home = os.homedir(), run, spawnFn = spawn, env = process.env, log = () => {},
+} = {}) {
+  if (!cwd) throw new Error('cwd (repo path) is required');
+  if (!prompt) throw new Error('prompt is required');
+  const tasks = loadTasks(home);
+  const existing = taskId ? tasks[taskId] : null;
+  if (existing && isPidAlive(existing.pid)) throw new Error(`task ${taskId} still has a live worker (pid ${existing.pid})`);
+  const id = existing?.id || taskId || newTaskId();
+  const forge = existing
+    ? { forge: existing.forge, cli: existing.cli, remoteUrl: existing.remoteUrl, base: existing.base }
+    : await probeForge(cwd, run);
+  const baseBranch = existing?.base || base || forge.base || 'main';
+  const branch = existing?.branch || slugBranch(id, title);
+  const worktree = existing?.worktree || path.join(shipDir(home), 'worktrees', id);
+  const logPath = existing?.log || path.join(shipDir(home), 'logs', `${id}.log`);
+  fs.mkdirSync(path.dirname(worktree), { recursive: true });
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+
+  if (!existing) {
+    try { await run(`git fetch origin ${baseBranch}`, cwd); } catch (e) { log(`ship: fetch ${baseBranch} failed: ${e.message}`); }
+    let start = `origin/${baseBranch}`;
+    try { await run(`git rev-parse --verify --quiet ${start}`, cwd); } catch { start = baseBranch; }
+    await run(`git worktree add -b ${branch} ${JSON.stringify(worktree)} ${start}`, cwd);
+  }
+
+  const text = workerPrompt({
+    taskId: id,
+    title: title || existing?.title,
+    prompt: existing ? `Follow-up on the branch you (or a prior worker) already pushed. Address these review findings, keep behavior otherwise unchanged, then push again:\n${prompt}` : prompt,
+    branch,
+    base: baseBranch,
+    forge: forge.forge,
+  });
+  const { file, args } = workerCommand({ prompt: text, env });
+  const out = fs.openSync(logPath, 'a');
+  fs.writeSync(out, `[ship] ${new Date().toISOString()} ${id} start ${file} in ${worktree}\n`);
+  const child = spawnFn(file, args, {
+    cwd: worktree,
+    detached: true,
+    stdio: ['ignore', out, out],
+    env: { ...env, OPENZOO_SHIP_TASK: id },
+  });
+  child.unref?.();
+  fs.closeSync(out);
+
+  tasks[id] = {
+    ...(existing || {}),
+    id,
+    title: String(title || existing?.title || ''),
+    prompt: existing ? `${existing.prompt}\n\n[follow-up] ${String(prompt)}` : String(prompt),
+    repo: existing?.repo || cwd,
+    attempts: (existing?.attempts || 0) + 1,
+    forge: forge.forge,
+    cli: forge.cli,
+    remoteUrl: forge.remoteUrl,
+    base: baseBranch,
+    branch,
+    worktree,
+    log: logPath,
+    pid: child.pid ?? null,
+    status: 'underway',
+    review: null,
+    result: null,
+    created_at: Date.now(),
+    updated_at: Date.now(),
+  };
+  saveTasks(home, tasks);
+  log(`ship: ${id} worker pid=${child.pid} branch=${branch} wt=${worktree}`);
+  return tasks[id];
+}
+
+export function tailFile(p, maxChars = 4000) {
+  try {
+    const s = fs.readFileSync(p, 'utf8');
+    return s.length > maxChars ? s.slice(-maxChars) : s;
+  } catch {
+    return '';
+  }
+}
+
+export async function taskStatus({ taskId, home = os.homedir(), run } = {}) {
+  const tasks = loadTasks(home);
+  const task = tasks[taskId];
+  if (!task) return { ok: false, error: `no task ${taskId}` };
+  const alive = isPidAlive(task.pid);
+  let commits = '';
+  let pushed = false;
+  try { commits = String(await run(`git log --oneline ${task.base}..${task.branch}`, task.worktree) || '').trim(); } catch { /* none yet */ }
+  try {
+    await run(`git fetch origin ${task.branch}`, task.worktree);
+    await run(`git rev-parse --verify --quiet origin/${task.branch}`, task.worktree);
+    pushed = true;
+  } catch { pushed = false; }
+  if (!alive && task.status === 'underway') {
+    task.status = pushed ? 'pushed' : 'worker-exited';
+    task.updated_at = Date.now();
+    saveTasks(home, tasks);
+  }
+  return {
+    ok: true,
+    task: { id: task.id, title: task.title, branch: task.branch, base: task.base, status: task.status, result: task.result },
+    worker: { pid: task.pid, alive },
+    pushed,
+    commits: commits.split('\n').filter(Boolean).slice(0, 30),
+    logTail: tailFile(task.log, 3000),
+    reviewGate: task.review ? reviewGate(task.review) : null,
+  };
+}
+
+/* ----------------------------------------------------------------- review */
+
+export const REVIEW_JSON_SHAPE = `{
+  "findings": [
+    { "severity": "error|warning|info", "action": "ask-user|auto-fix|no-op", "file": "path", "line": 1, "description": "..." }
+  ],
+  "risk_level": "low|medium|high",
+  "risk_rationale": "one sentence"
+}`;
+
+/** Fresh-context review prompt. No chat history rides along on purpose. */
+export function reviewMessages({ repo = '', branch, base, diff, gitlog = '', stat = '' } = {}) {
+  const system = [
+    'You are an adversarial code reviewer. You see only a branch diff. You have no tools and cannot run anything.',
+    'Find what would go wrong if this merged: bugs, security, performance regressions, breaking changes, missing error handling, and real simplifications that keep behavior identical.',
+    'Anchor every finding to a file and a 1-indexed line in the changed code. Do not report style, formatting, lint, or type-check noise. No generic advice.',
+    'Severity error must not merge. warning can follow up. info is optional.',
+    'action ask-user = product behavior or the author\'s intent is in question (default when unsure). auto-fix = non-functional, fixable without discussing intent. no-op = informational.',
+    'Do a full pass before answering. If the change is clean, return an empty findings array.',
+    `Return ONLY JSON in this shape:\n${REVIEW_JSON_SHAPE}`,
+  ].join('\n');
+  const user = [
+    `repo: ${repo}`,
+    `branch: ${branch}`,
+    `base: ${base}`,
+    gitlog ? `commits:\n${gitlog}` : '',
+    stat ? `diffstat:\n${stat}` : '',
+    'diff:',
+    '```diff',
+    String(diff || '').trim() || '(empty diff)',
+    '```',
+  ].filter(Boolean).join('\n');
+  return [{ role: 'system', content: system }, { role: 'user', content: user }];
+}
+
+const SEVERITIES = new Set(['error', 'warning', 'info']);
+const ACTIONS = new Set(['ask-user', 'auto-fix', 'no-op']);
+
+/** Tolerant: fences, prose around the JSON, odd casing. Never throws. */
+export function parseReview(text) {
+  const s = String(text || '');
+  let obj = null;
+  const fenced = s.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidates = [fenced?.[1], s.slice(s.indexOf('{'), s.lastIndexOf('}') + 1), s];
+  for (const c of candidates) {
+    if (!c) continue;
+    try { obj = JSON.parse(c); break; } catch { /* next */ }
+  }
+  if (!obj || typeof obj !== 'object') {
+    return {
+      findings: [{ severity: 'error', action: 'no-op', file: '', line: 0, description: 'reviewer returned no JSON' }],
+      risk_level: 'high',
+      risk_rationale: 'review output was not parseable',
+      parse_error: true,
+      raw: s.slice(0, 2000),
+    };
+  }
+  const findings = (Array.isArray(obj.findings) ? obj.findings : []).map((f) => {
+    const severity = String(f?.severity || 'warning').toLowerCase();
+    const action = String(f?.action || 'ask-user').toLowerCase();
+    return {
+      severity: SEVERITIES.has(severity) ? severity : 'warning',
+      action: ACTIONS.has(action) ? action : 'ask-user',
+      file: String(f?.file || ''),
+      line: Number.isFinite(Number(f?.line)) ? Number(f.line) : 0,
+      description: String(f?.description || '').slice(0, 1000),
+    };
+  });
+  const risk = String(obj.risk_level || '').toLowerCase();
+  return {
+    findings,
+    risk_level: ['low', 'medium', 'high'].includes(risk) ? risk : (findings.some((f) => f.severity === 'error') ? 'high' : 'medium'),
+    risk_rationale: String(obj.risk_rationale || ''),
+    parse_error: false,
+  };
+}
+
+/**
+ * Grok Ship's loop, as a decision:
+ *   error       -> blocked, do not raise
+ *   ask-user    -> blocked, one decision card to the human
+ *   auto-fix    -> blocked, send back to the worker, then a FRESH review
+ *   info / none -> clean, the PR may open
+ */
+export function reviewGate(review) {
+  const findings = Array.isArray(review?.findings) ? review.findings : [];
+  const errors = findings.filter((f) => f.severity === 'error');
+  const askUser = findings.filter((f) => f.action === 'ask-user' && f.severity !== 'error');
+  const autoFix = findings.filter((f) => f.action === 'auto-fix' && f.severity !== 'error');
+  if (review?.parse_error) return { clean: false, reason: 'review did not return JSON; run ship_review again', errors, askUser, autoFix };
+  if (errors.length) return { clean: false, reason: `${errors.length} error finding(s) block the PR`, errors, askUser, autoFix };
+  if (autoFix.length) return { clean: false, reason: `${autoFix.length} auto-fix finding(s): send them to the worker, then review again fresh`, errors, askUser, autoFix };
+  if (askUser.length) return { clean: false, reason: `${askUser.length} ask-user finding(s): one decision card to the human, do not raise`, errors, askUser, autoFix };
+  return { clean: true, reason: findings.length ? 'only info findings' : 'no findings', errors, askUser, autoFix };
+}
+
+export async function defaultZooPost(messages, model, { fetchFn = fetch, port = 8402, maxTokens = 4096, timeoutMs = 10 * 60_000 } = {}) {
+  const r = await fetchFn(`http://127.0.0.1:${port}/v1/chat/completions`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: 'Bearer sk-openzoo' },
+    body: JSON.stringify({ model, messages, max_tokens: maxTokens, temperature: 0 }),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const data = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(data?.error?.message || `zoo ${r.status}`);
+  const c = data?.choices?.[0]?.message?.content;
+  return Array.isArray(c) ? c.map((p) => (typeof p === 'string' ? p : p?.text || '')).join('') : String(c || '');
+}
+
+/**
+ * Review a pushed branch with a fresh one-shot completion. Reads the branch
+ * through git in the repo (or the task worktree), never a worker VM.
+ */
+export async function reviewBranch({
+  taskId, cwd, branch, base, model, home = os.homedir(), run, post = defaultZooPost, maxDiffChars = Number(process.env.OPENZOO_SHIP_DIFF_CHARS || 160_000), log = () => {},
+} = {}) {
+  const tasks = loadTasks(home);
+  const task = taskId ? tasks[taskId] : null;
+  if (taskId && !task) return { ok: false, error: `no task ${taskId}` };
+  const dir = task?.worktree || cwd;
+  const br = branch || task?.branch;
+  const bs = base || task?.base || (await defaultBase(dir, run));
+  if (!dir || !br) return { ok: false, error: 'need taskId, or cwd + branch' };
+
+  try { await run(`git fetch origin ${br}`, dir); } catch (e) { log(`ship: fetch ${br} ${e.message}`); }
+  let tip = br;
+  try { await run(`git rev-parse --verify --quiet origin/${br}`, dir); tip = `origin/${br}`; } catch { /* local branch */ }
+  const stat = String(await run(`git diff --stat ${bs}...${tip}`, dir) || '').trim();
+  let diff = String(await run(`git diff ${bs}...${tip}`, dir) || '');
+  const gitlog = String(await run(`git log --oneline ${bs}..${tip}`, dir) || '').trim();
+  if (!diff.trim()) return { ok: false, error: `no diff between ${bs} and ${tip}; has the worker pushed?` };
+  let truncated = false;
+  if (diff.length > maxDiffChars) { diff = `${diff.slice(0, maxDiffChars)}\n… (diff truncated at ${maxDiffChars} chars)`; truncated = true; }
+
+  const messages = reviewMessages({ repo: task?.repo || dir, branch: br, base: bs, diff, gitlog, stat });
+  log(`ship: review ${br} vs ${bs} diff=${diff.length}c model=${model}`);
+  const text = await post(messages, model);
+  const review = parseReview(text);
+  const gate = reviewGate(review);
+  if (task) {
+    task.review = { ...review, reviewed_at: Date.now(), tip, truncated };
+    task.status = gate.clean ? 'review-clean' : 'review-blocked';
+    task.updated_at = Date.now();
+    saveTasks(home, tasks);
+  }
+  return { ok: true, taskId: task?.id || null, branch: br, base: bs, truncated, review, gate };
+}
+
+/* --------------------------------------------------------------------- PR */
+
+export function prCommand({ cli, branch, base, title, body = '' } = {}) {
+  const t = JSON.stringify(String(title || branch));
+  const b = JSON.stringify(String(body || ''));
+  if (cli === 'gh') return `gh pr create --head ${branch} --base ${base} --title ${t} --body ${b}`;
+  if (cli === 'glab') return `glab mr create --source-branch ${branch} --target-branch ${base} --title ${t} --description ${b} --yes`;
+  throw new Error(`no authenticated forge CLI for this repo (cli=${cli || 'none'}); push is visible but the PR must be opened by hand`);
+}
+
+export async function openPr({ taskId, title, body, home = os.homedir(), run, log = () => {} } = {}) {
+  const tasks = loadTasks(home);
+  const task = tasks[taskId];
+  if (!task) return { ok: false, error: `no task ${taskId}` };
+  if (!task.review) return { ok: false, error: 'no review on record; run ship_review first' };
+  const gate = reviewGate(task.review);
+  if (!gate.clean) return { ok: false, error: `review not clean: ${gate.reason}`, gate };
+  try {
+    await run(`git fetch origin ${task.branch}`, task.repo);
+    await run(`git rev-parse --verify --quiet origin/${task.branch}`, task.repo);
+  } catch {
+    return { ok: false, error: `branch ${task.branch} is not on origin yet` };
+  }
+  const summary = body || [
+    task.title,
+    '',
+    task.prompt,
+    '',
+    `Adversarial review: ${gate.reason} (risk ${task.review.risk_level}).`,
+    `Ship task ${task.id}.`,
+  ].join('\n');
+  const cmd = prCommand({ cli: task.cli, branch: task.branch, base: task.base, title: title || task.title || task.branch, body: summary });
+  log(`ship: ${task.id} ${cmd.slice(0, 80)}`);
+  const out = String(await run(cmd, task.repo) || '');
+  const url = out.match(/https?:\/\/\S+/)?.[0] || out.trim();
+  task.result = url;
+  task.status = 'pr-open';
+  task.updated_at = Date.now();
+  saveTasks(home, tasks);
+  return { ok: true, taskId: task.id, url, branch: task.branch, base: task.base };
+}
+
+/* ------------------------------------------------------------------ briefs */
+
+export function firstmateBrief() {
+  return [
+    'You are Firstmate: the one bot the human talks to. They bring you everything; you make sure it gets done.',
+    'Other sidebar bots are crewmates with standing briefs, one per repo. Before creating one, list_agents and reuse a crewmate whose brief already covers the repo.',
+    'Hand work off with message_agent. Tag every hand-off with a short task id and ask for the outcome back against that id. Empty results still get reported.',
+    'Code goes through a crewmate, never through you. You never call ship_launch_worker, ship_review, or ship_open_pr yourself.',
+    'Classify factory work as scout (a report, never a PR) or ship (a branch, a fresh adversarial review, then a PR). Ship only when the human authorized the change.',
+    'Nothing merges without the human\'s explicit word. Relay PR URLs when they land. Bring decisions one at a time: what, why now, real options, your recommendation.',
+    'Detect the forge (GitHub, GitLab, Bitbucket, Origin). Do not assume GitHub. Speak in outcomes, not mechanics. Prefer schedule_wakeup over spawning more bots.',
+  ].join(' ');
+}
+
+export function crewmateBrief({ repo, forge = 'unknown' } = {}) {
+  return [
+    `You are the crewmate for the repo at ${repo} (forge: ${forge}). Firstmate hands you tasks with an id; report every outcome back to Firstmate against that id with message_agent.`,
+    'Scout: investigate with read_file / exec (git log, grep, tests). Write the report to ~/.openzoo/ship/reports/<task id>.md and return the path. Never a PR.',
+    'Ship: ship_launch_worker with cwd=the repo, a clear prompt (goal, acceptance criteria, constraints). Poll ship_status until the worker exits and the branch is pushed.',
+    'Then ship_review on the task. If the gate is not clean: for auto-fix findings call ship_launch_worker again with the same task id and the findings as the prompt (same branch, same worktree); ask-user findings go to Firstmate as one decision; error findings block. Review again fresh after any fix.',
+    'Only when ship_review reports gate.clean: ship_open_pr. Relay the URL. Never merge; the human does.',
+    'Use the forge CLI recorded for this repo (gh or glab) via exec for issues and checks. Do not assume GitHub.',
+  ].join(' ');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzoo",
-  "version": "0.50.54",
+  "version": "0.50.56",
   "description": "Local x402-paying proxy + MCP server for openzoo.fun — point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
   "license": "MIT",
   "type": "module",