drafted 1.14.0 → 1.14.2

package/cli/drafted.mjs

@@ -1911,89 +1911,89 @@ skillCmd
     else console.log(`ok\t${id}\t${data.hash}\tpushed ${data.count}${data.stripped ? `, stripped ${data.stripped}` : ''}${gitignored ? ', gitignored .skillinstall/' : ''}`);
   });
 
-// ── Collectors: management seam (parity with the MCP `collector` tool) ──
-// Collectors are checklist-driven intake surfaces. Management is behind the
-// agent allowlist (same gate as Minion) and scoped to the session's active org.
-function emitCollectorResult(format, obj) {
+// ── Minions: management seam (parity with the MCP `minion` tool) ──
+// Minions are checklist-driven intake surfaces. Management is behind the
+// agent allowlist and scoped to the session's active org.
+function emitMinionResult(format, obj) {
   if (format === 'json') { console.log(JSON.stringify(obj)); return; }
   console.log([obj.status, obj.id || '', obj.slug || '', obj.name || '', obj.error || ''].join('\t'));
 }
 
-async function collectorSetEnabled(id, enabled, format) {
+async function minionSetEnabled(id, enabled, format) {
   requireLogin();
   const server = getServerUrl().replace(/\/$/, '');
-  const res = await authFetch(`${server}/api/collectors/${encodeURIComponent(id)}`, {
+  const res = await authFetch(`${server}/api/minions/${encodeURIComponent(id)}`, {
     method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ enabled }),
   });
   const data = await res.json().catch(() => ({}));
-  if (!res.ok) { emitCollectorResult(format, { status: res.status === 404 ? 'not-found' : 'error', error: data.error || `HTTP ${res.status}` }); process.exit(1); }
-  const c = data.collector || {};
-  emitCollectorResult(format, { status: 'ok', id: c.id, slug: c.slug, name: c.name });
+  if (!res.ok) { emitMinionResult(format, { status: res.status === 404 ? 'not-found' : 'error', error: data.error || `HTTP ${res.status}` }); process.exit(1); }
+  const c = data.minion || {};
+  emitMinionResult(format, { status: 'ok', id: c.id, slug: c.slug, name: c.name });
 }
 
-const collectorCmd = program.command('collector').description('Collector management (checklist-driven intake surfaces). Requires the agent allowlist.');
+const minionCmd = program.command('minion').description('Minion management (checklist-driven intake surfaces). Requires the agent allowlist.');
 
-collectorCmd
+minionCmd
   .command('list')
-  .description('List collectors (scoped to --project or your active project; all org collectors if neither)')
+  .description('List Minions (scoped to --project or your active project; all org Minions if neither)')
   .option('--project <id>', 'project to scope to (defaults to your active project)')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (opts) => {
     const pid = opts.project || getActiveProject()?.id;
-    const data = await readApiGet('collector:list', withQuery('/api/collectors', { projectId: pid }));
-    const rows = data.collectors || [];
+    const data = await readApiGet('minion:list', withQuery('/api/minions', { projectId: pid }));
+    const rows = data.minions || [];
     if (opts.format === 'json') { console.log(JSON.stringify(rows)); return; }
     for (const c of rows) console.log(`${c.id}\t${c.slug}\t${c.enabled ? 'enabled' : 'disabled'}\t${c.name}`);
   });
 
-collectorCmd
+minionCmd
   .command('get <id>')
-  .description('Get a collector by id')
+  .description('Get a Minion by id')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (id, opts) => {
-    const data = await readApiGet('collector:get', `/api/collectors/${encodeURIComponent(id)}`);
-    if (opts.format === 'json') { console.log(JSON.stringify(data.collector || data)); return; }
-    const c = data.collector || {};
+    const data = await readApiGet('minion:get', `/api/minions/${encodeURIComponent(id)}`);
+    if (opts.format === 'json') { console.log(JSON.stringify(data.minion || data)); return; }
+    const c = data.minion || {};
     console.log(`${c.id}\t${c.slug}\t${c.enabled ? 'enabled' : 'disabled'}\t${c.name}`);
   });
 
-collectorCmd
+minionCmd
   .command('meta')
-  .description('Project layers/lanes/frames for building a collector target/output')
+  .description('Project layers/lanes/frames for building a Minion target/output')
   .option('--project <id>', 'project (defaults to your active project)')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (opts) => {
     const pid = opts.project || getActiveProject()?.id;
     if (!pid) { console.error('No active project. Pass --project <id> or run `drafted use <project>`.'); process.exit(1); }
-    const data = await readApiGet('collector:meta', withQuery('/api/collectors/meta', { projectId: pid }));
+    const data = await readApiGet('minion:meta', withQuery('/api/minions/meta', { projectId: pid }));
     console.log(JSON.stringify(data));
   });
 
-collectorCmd
+minionCmd
   .command('create')
-  .description('Create a collector from stdin JSON {name,description?,target,checklist,output,enabled?}')
+  .description('Create a Minion from stdin JSON {name,description?,target,checklist,output,enabled?}')
   .option('--project <id>', 'project to bind to (defaults to your active project)')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (opts) => {
     requireLogin();
     const pid = opts.project || getActiveProject()?.id;
-    if (!pid) { emitCollectorResult(opts.format, { status: 'error', error: 'no project — pass --project <id> or run `drafted use <project>`' }); process.exit(1); }
+    if (!pid) { emitMinionResult(opts.format, { status: 'error', error: 'no project — pass --project <id> or run `drafted use <project>`' }); process.exit(1); }
     let p;
     try { p = readStdinJSON(); } catch { console.error('invalid JSON on stdin'); process.exit(1); }
     const server = getServerUrl().replace(/\/$/, '');
-    const res = await authFetch(`${server}/api/collectors`, {
+    const res = await authFetch(`${server}/api/minions`, {
       method: 'POST', headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ projectId: pid, name: p.name, description: p.description, target: p.target, checklist: p.checklist, output: p.output, enabled: p.enabled }),
     });
     const data = await res.json().catch(() => ({}));
-    if (!res.ok) { emitCollectorResult(opts.format, { status: res.status === 403 ? 'forbidden' : 'error', error: data.error || `HTTP ${res.status}` }); process.exit(1); }
-    const c = data.collector || {};
-    emitCollectorResult(opts.format, { status: 'ok', id: c.id, slug: c.slug, name: c.name });
+    if (!res.ok) { emitMinionResult(opts.format, { status: res.status === 403 ? 'forbidden' : 'error', error: data.error || `HTTP ${res.status}` }); process.exit(1); }
+    const c = data.minion || {};
+    emitMinionResult(opts.format, { status: 'ok', id: c.id, slug: c.slug, name: c.name });
   });
 
-collectorCmd
+minionCmd
   .command('update <id>')
-  .description('Update a collector from stdin JSON {name?,description?,target?,checklist?,output?,enabled?}')
+  .description('Update a Minion from stdin JSON {name?,description?,target?,checklist?,output?,enabled?}')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (id, opts) => {
     requireLogin();
@@ -2003,33 +2003,33 @@ collectorCmd
     for (const k of ['name', 'description', 'target', 'checklist', 'output', 'enabled']) {
       if (p[k] !== undefined) body[k] = p[k];
     }
-    if (Object.keys(body).length === 0) { emitCollectorResult(opts.format, { status: 'error', error: 'no fields to update' }); process.exit(1); }
+    if (Object.keys(body).length === 0) { emitMinionResult(opts.format, { status: 'error', error: 'no fields to update' }); process.exit(1); }
     const server = getServerUrl().replace(/\/$/, '');
-    const res = await authFetch(`${server}/api/collectors/${encodeURIComponent(id)}`, {
+    const res = await authFetch(`${server}/api/minions/${encodeURIComponent(id)}`, {
       method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
     });
     const data = await res.json().catch(() => ({}));
-    if (!res.ok) { emitCollectorResult(opts.format, { status: res.status === 404 ? 'not-found' : 'error', error: data.error || `HTTP ${res.status}` }); process.exit(1); }
-    const c = data.collector || {};
-    emitCollectorResult(opts.format, { status: 'ok', id: c.id, slug: c.slug, name: c.name });
+    if (!res.ok) { emitMinionResult(opts.format, { status: res.status === 404 ? 'not-found' : 'error', error: data.error || `HTTP ${res.status}` }); process.exit(1); }
+    const c = data.minion || {};
+    emitMinionResult(opts.format, { status: 'ok', id: c.id, slug: c.slug, name: c.name });
   });
 
-collectorCmd
+minionCmd
   .command('enable <id>')
-  .description('Make a collector live')
+  .description('Make a Minion live')
   .option('--format <fmt>', 'output format: json or text', 'text')
-  .action((id, opts) => collectorSetEnabled(id, true, opts.format));
+  .action((id, opts) => minionSetEnabled(id, true, opts.format));
 
-collectorCmd
+minionCmd
   .command('disable <id>')
-  .description('Take a collector offline')
+  .description('Take a Minion offline')
   .option('--format <fmt>', 'output format: json or text', 'text')
-  .action((id, opts) => collectorSetEnabled(id, false, opts.format));
+  .action((id, opts) => minionSetEnabled(id, false, opts.format));
 
-async function collectorTestPost(id, path, body, format) {
+async function minionTestPost(id, path, body, format) {
   requireLogin();
   const server = getServerUrl().replace(/\/$/, '');
-  const res = await authFetch(`${server}/api/collectors/${encodeURIComponent(id)}/${path}`, {
+  const res = await authFetch(`${server}/api/minions/${encodeURIComponent(id)}/${path}`, {
     method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body || {}),
   });
   const data = await res.json().catch(() => ({}));
@@ -2041,39 +2041,39 @@ async function collectorTestPost(id, path, body, format) {
   console.log(JSON.stringify(data));
 }
 
-collectorCmd
+minionCmd
   .command('test-start <id>')
-  .description('QA: start (or resume) a test run of a collector you own — works even when disabled. --fresh for a new run.')
+  .description('QA: start (or resume) a test run of a Minion you own — works even when disabled. --fresh for a new run.')
   .option('--fresh', 'start a brand-new run instead of resuming', false)
   .option('--format <fmt>', 'output format: json (default)', 'json')
-  .action((id, opts) => collectorTestPost(id, 'test-start', { fresh: !!opts.fresh }, opts.format));
+  .action((id, opts) => minionTestPost(id, 'test-start', { fresh: !!opts.fresh }, opts.format));
 
-collectorCmd
+minionCmd
   .command('test-say <id>')
   .description('QA: send a text answer to your test run; returns the agent reply, checklist state, pending actions.')
   .requiredOption('--text <text>', 'the consumer message to send')
   .option('--format <fmt>', 'output format: json (default)', 'json')
-  .action((id, opts) => collectorTestPost(id, 'test-message', { content: opts.text }, opts.format));
+  .action((id, opts) => minionTestPost(id, 'test-message', { content: opts.text }, opts.format));
 
-collectorCmd
+minionCmd
   .command('test-resolve <id>')
   .description('QA: approve or reject a pending destructive action in your test run.')
   .requiredOption('--action <actionId>', 'the pending action id')
   .option('--reject', 'reject instead of approve', false)
   .option('--format <fmt>', 'output format: json (default)', 'json')
-  .action((id, opts) => collectorTestPost(id, 'test-resolve', { actionId: opts.action, approve: !opts.reject }, opts.format));
+  .action((id, opts) => minionTestPost(id, 'test-resolve', { actionId: opts.action, approve: !opts.reject }, opts.format));
 
-collectorCmd
+minionCmd
   .command('delete <id>')
-  .description('Delete a collector (past submissions are kept as history)')
+  .description('Delete a Minion (past submissions are kept as history)')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (id, opts) => {
     requireLogin();
     const server = getServerUrl().replace(/\/$/, '');
-    const res = await authFetch(`${server}/api/collectors/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    const res = await authFetch(`${server}/api/minions/${encodeURIComponent(id)}`, { method: 'DELETE' });
     const data = await res.json().catch(() => ({}));
-    if (!res.ok) { emitCollectorResult(opts.format, { status: res.status === 404 ? 'not-found' : 'error', error: data.error || `HTTP ${res.status}` }); process.exit(1); }
-    emitCollectorResult(opts.format, { status: 'ok', id: data.id || id });
+    if (!res.ok) { emitMinionResult(opts.format, { status: res.status === 404 ? 'not-found' : 'error', error: data.error || `HTTP ${res.status}` }); process.exit(1); }
+    emitMinionResult(opts.format, { status: 'ok', id: data.id || id });
   });
 
 program.parse();

package/mcp/server.mjs

@@ -144,7 +144,7 @@ const REMOTE_JSON_STRING_PARAMS = {
   wiki: ['frontmatter', 'pages'],
   project: ['layers'],
   template: ['layers'],
-  collector: ['target', 'checklist', 'output'],
+  minion: ['target', 'checklist', 'output'],
 };
 
 // Remove sentences that reference local-file params from a tool description,
@@ -225,6 +225,9 @@ const TOOL_ANNOTATIONS = {
   // Identity — read-only introspection of THIS agent's session
   whoami:              { title: 'Session identity',    readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'Return THIS agent session\'s identity: its server-assigned human-readable name (the correlation key between an agent window and its web-app session tab), sessionId, userId, orgId, active projectId, editor label, server URL, and surfaced/alive state. Read-only. Use this — not guesses from the host environment — to report which session you are.' },
 
+  // Health — call once per session, right after whoami and before any real work
+  health:              { title: 'Server health',       readOnlyHint: true,  destructiveHint: false, openWorldHint: true,  description: 'Server reachability + installed MCP version/update status. Call this once per session, right after whoami and before doing any real work, so a required update surfaces before you act on stale tool behavior.' },
+
   // Projects
   project:             { title: 'Projects',            readOnlyHint: false, destructiveHint: false, openWorldHint: false, widgetUri: 'ui://widget/drafted-canvas-overview.html', description: 'Manage projects: list (start here), open (bind this agent session to a project — org derives from it), create (org= names where it is born), update, move to another org.' },
   get_org:             { title: 'Organization',        readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'List your orgs, the default org, and Google Drive availability (action="get", default), or fetch installed MCP update instructions (action="update_mcp"). There is no org switching — org derives from the resource you address; creates/searches take org=. When googleDrive.connected is true, strongly prefer Google Workspace frames for documents, sheets, and slides.' },
@@ -258,8 +261,8 @@ const TOOL_ANNOTATIONS = {
   skill:               { title: 'Skills',              readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage the Drafted skill library: search, load, add, update, remove, attach/detach from projects, favorite, and edit skill files.' },
   wiki:                { title: 'Wiki',                readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Per-org wiki. Markdown pages with paths as hierarchy. Dispatch by `action`.' },
 
-  // Collectors — checklist-driven, Minion-run intake surfaces bound to a project
-  collector:           { title: 'Collectors',          readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage Collectors: checklist-driven intake surfaces that guide a consumer through a checklist (via a shareable /c/<slug> link) and then write a producible into the project. Dispatch by `action`: meta (discover layers/lanes/frames), list, get, create, update, enable, disable, delete. QA your own collectors with test_start/test_say/test_resolve — drive the checklist conversation yourself (works even when disabled) and verify it produces the right Doc/Sheet output. Requires the agent allowlist (same gate as Minion).' },
+  // Minions — checklist-driven intake surfaces bound to a project
+  minion:              { title: 'Minions',             readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage Minions: checklist-driven intake surfaces that guide a consumer through a checklist (via a shareable /c/<slug> link) and then write a producible into the project. Dispatch by `action`: meta (discover layers/lanes/frames), list, get, create, update, enable, disable, delete. QA your own Minions with test_start/test_say/test_resolve — drive the checklist conversation yourself (works even when disabled) and verify it produces the right Doc/Sheet output. Requires the agent allowlist.' },
 };
 
 function isMutatingToolCall(name, args = {}) {
@@ -285,7 +288,7 @@ function isMutatingToolCall(name, args = {}) {
       return ['add', 'update', 'remove', 'attach', 'detach', 'favorite', 'unfavorite', 'update_file'].includes(action);
     case 'wiki':
       return ['log', 'write', 'edit', 'mv', 'rm', 'source-register', 'bulk-write'].includes(action);
-    case 'collector':
+    case 'minion':
       return ['create', 'update', 'enable', 'disable', 'delete', 'test_start', 'test_say', 'test_resolve'].includes(action);
     case 'rm':
     case 'shape':
@@ -371,6 +374,10 @@ function tool(name, descOrSchema, schemaOrHandler, handler) {
     state.currentTool = name;
     trackUmamiEvent(UMAMI_EVENTS.MCP_TOOL_CALLED, { tool: name, projectId: state.projectId || undefined, source: 'mcp' });
     reportInstallationEvent(UMAMI_EVENTS.DRAFTED_MCP_REQUEST, { tool: name });
+    if (!hasAnnouncedSubstantiveWork && !NON_SUBSTANTIVE_TOOLS.has(name)) {
+      hasAnnouncedSubstantiveWork = true;
+      announceSubstantiveWork().catch(() => {});
+    }
     try {
       const requiredUpdateError = await getRequiredMcpUpdateError(name, args?.[0] || {});
       if (requiredUpdateError) return err(new Error(requiredUpdateError));
@@ -1140,15 +1147,27 @@ function getCurrentProjectContext() {
   return s.projectMeta || { id: s.projectId, slug: null, name: null, orgId: null };
 }
 
+function scheduleAgentWsRetry() {
+  clearTimeout(agentWsReconnectTimer);
+  agentWsReconnectTimer = setTimeout(() => {
+    connectAgentWs().catch((e) => {
+      console.error('[MCP-WS] Reconnect failed:', e?.message || e);
+    });
+  }, 5000);
+}
+
 async function connectAgentWs() {
   await ensureSession();
   const auth = getAuthHeaders();
-  if (!auth.Cookie) return;
+  // No session yet (e.g. desktop sign-in still in progress) — retry instead of stranding
+  // the handshake forever, since there's no WebSocket here yet to trigger the close-based
+  // reconnect below.
+  if (!auth.Cookie) { scheduleAgentWsRetry(); return; }
 
   const serverUrl = getServerUrl().replace(/^http/, 'ws');
   try {
     agentWs = new WebSocket(serverUrl, { headers: auth });
-  } catch { return; }
+  } catch { scheduleAgentWsRetry(); return; }
 
   agentWs.on('open', () => {
     console.error('[MCP-WS] Connected');
@@ -1182,12 +1201,7 @@ async function connectAgentWs() {
     // and survive server restarts, so reusing the clone keeps this agent's surface (and
     // its playful tab name) stable across blips — otherwise every reconnect re-clones a
     // fresh session → a NEW greyed tab with a NEW name. A real 401 still triggers re-clone.
-    clearTimeout(agentWsReconnectTimer);
-    agentWsReconnectTimer = setTimeout(() => {
-      connectAgentWs().catch((e) => {
-        console.error('[MCP-WS] Reconnect failed:', e?.message || e);
-      });
-    }, 5000);
+    scheduleAgentWsRetry();
   });
 
   agentWs.on('error', () => {
@@ -1223,6 +1237,28 @@ async function joinAgentWsRoom(projectId) {
   }
 }
 
+// Tools that are pure introspection/sign-in, not "the agent started working" — excluded from
+// the first-substantive-action ping below so a bare whoami/health/auth never yanks the
+// desktop app's window to the front.
+const NON_SUBSTANTIVE_TOOLS = new Set(['whoami', 'health', 'auth']);
+let hasAnnouncedSubstantiveWork = false;
+
+// Tell the server this agent has started real work (first call past whoami/health/auth this
+// process), so it can foreground the desktop app's window. Fire-and-forget — never blocks or
+// fails the tool call that triggered it.
+async function announceSubstantiveWork() {
+  if (!agentWs || agentWs.readyState > WebSocket.OPEN) {
+    await connectAgentWs();
+  }
+  if (!agentWs) return;
+  const msg = JSON.stringify({ type: 'agent-active', projectId: getState().projectId || null });
+  if (agentWs.readyState === WebSocket.OPEN) {
+    agentWs.send(msg);
+  } else if (agentWs.readyState === WebSocket.CONNECTING) {
+    agentWs.once('open', () => agentWs.send(msg));
+  }
+}
+
 // Clone session and connect WebSocket on startup (delayed to let server be ready).
 // Guarded because createMcpServer() runs per HTTP request — the bootstrap must
 // fire exactly once per process, not per request.
@@ -1684,11 +1720,35 @@ async function sessionSurfaceBlock() {
 // Identity: report THIS agent session's own surface identity. Read-only — no state changed.
 tool('whoami', 'Return THIS agent session\'s identity: its server-assigned human-readable name (the correlation key between an agent window and its web-app session tab), sessionId, userId, orgId, active projectId, editor label, server URL, and surfaced/alive state. Read-only.', {}, async () => {
   try {
+    const block = await sessionSurfaceBlock();
+    // Tell the agent to actually surface its name to the user — returning `name` in the JSON isn't
+    // enough; without an explicit instruction agents rarely say which session they are, so users
+    // can't match them to their tab on the Drafted surface.
+    const instruction = block.name
+      ? `You are the session named "${block.name}". Tell the user you're "${block.name}" in your reply so they can match you to your tab on the Drafted surface.`
+      : undefined;
     return ok({
       server: getServerUrl(),
       editor: (process.env.DRAFTED_AGENT_NAME || '').trim() || null,
       agentLabel: getAgentLabel(),
-      ...(await sessionSurfaceBlock()),
+      ...block,
+      ...(instruction ? { instruction } : {}),
+    });
+  } catch (error) { return err(error); }
+});
+
+// Health: server reachability + installed-MCP staleness, meant to be the second call of a
+// session (right after whoami, before real work) so a required update surfaces early instead
+// of depending on an agent remembering to call get_org. Cached per-process — `whoami` stays
+// network-free between health checks, and repeat `health` calls in one session are free too.
+tool('health', {}, async () => {
+  try {
+    const mcpUpdate = await getCachedMcpUpdateMetadata();
+    return ok({
+      server: getServerUrl(),
+      ok: mcpUpdate.status !== 'unknown',
+      mcpVersion: PACKAGE_VERSION,
+      mcpUpdate,
     });
   } catch (error) { return err(error); }
 });
@@ -1705,7 +1765,6 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
   folder: z.string().nullable().optional().describe('[update] folder name (null to remove from folder)'),
   layers: z.array(z.object({}).passthrough()).optional().describe('[update] full layers array replacement. Use ls / to read current layers first.'),
   targetOrgId: z.string().optional().describe('[move] destination organization ID. Get org IDs from action=list (each project has an orgId field) or get_org. Both source and target org must include the current user.'),
-  skipBrowser: z.boolean().optional().describe('[open] skip opening/navigating a browser tab (use when the user already has the project open, e.g. from an invite snippet)'),
   format: z.string().optional().describe('[export] "files" returns {files:[{path,content}]} paginated via limit/offset (compact=true for paths only) instead of writing a local dir (stdio) or returning a download URL (remote).'),
   limit: z.number().optional().describe('[export] max files per page for format="files" (default 100, max 500)'),
   offset: z.number().optional().describe('[export] pagination offset for format="files"'),
@@ -1750,7 +1809,7 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
         return ok(data, { structuredContent });
       }
       case 'open': {
-        const { projectId, skipBrowser } = args;
+        const { projectId } = args;
         if (!projectId) throw new Error('projectId required for action=open');
         const result = await api('POST', '/api/project/switch', { projectId });
         joinAgentWsRoom(projectId);
@@ -1767,18 +1826,17 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
         } catch { /* fall back to projectId */ }
         setMcpActiveProject(projectId, projectMeta);
         const url = `${base}/project/${projectSlug}`;
+        // Surfacing to the user is the focus mechanism's job now (agent-active ping ->
+        // desktop window / notification+glow for browser tabs) — this used to also force
+        // `exec('open <url>')` on the MCP host machine, an unsolicited GUI action that both
+        // duplicated the focus mechanism and did nothing useful for remote/hosted MCP mode
+        // (no GUI to open on Drafted's own server). `url` is still returned below for the
+        // agent/human to open manually.
         let navigated = 0;
-        if (!skipBrowser) {
-          try {
-            const nav = await api('POST', '/api/project/navigate', { projectId });
-            navigated = nav.navigated || 0;
-          } catch { /* server may not support navigate yet */ }
-          if (navigated === 0) {
-            const { exec } = await import('child_process');
-            const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-            exec(`${cmd} ${JSON.stringify(url)}`);
-          }
-        }
+        try {
+          const nav = await api('POST', '/api/project/navigate', { projectId });
+          navigated = nav.navigated || 0;
+        } catch { /* server may not support navigate yet */ }
         // G4/G5 auto-inject (locked design): the project's attached skills + anchors
         // are pushed into the open response within the per-project context budget,
         // replacing the reject-style gate. Prefer the server-computed `priming`
@@ -2318,12 +2376,23 @@ async function getMcpUpdateMetadata() {
       mode,
       distribution: mode === 'stdio' ? 'npm-stdio' : 'hosted-http',
       update: { command: null, helper: null, packageManager: 'npm' },
-      restart: { required: false, guidance: 'Drafted MCP update status is unavailable; get_org still succeeded.' },
+      restart: { required: false, guidance: 'Drafted MCP update status is unavailable; this call still succeeded.' },
       checkedAt: null,
     };
   }
 }
 
+// Process-lifetime cache: `health` is meant to be called every session, so avoid a network
+// round-trip on repeat calls. `get_org` shares the cache too (same underlying data).
+let mcpUpdateCache = null; // { data, fetchedAt }
+const MCP_UPDATE_CACHE_MS = 5 * 60_000;
+async function getCachedMcpUpdateMetadata() {
+  if (mcpUpdateCache && (Date.now() - mcpUpdateCache.fetchedAt) < MCP_UPDATE_CACHE_MS) return mcpUpdateCache.data;
+  const data = await getMcpUpdateMetadata();
+  mcpUpdateCache = { data, fetchedAt: Date.now() };
+  return data;
+}
+
 
 tool('get_org', {
   action: z.enum(['get', 'update_mcp']).optional().describe('Default: "get" returns your orgs, the default org, and Google Drive availability. Use "update_mcp" to get explicit installed stdio MCP update instructions. There is no org switching: org derives from the resource you address (projectId/pageId/skillId), and creates/searches take an explicit org param.'),
@@ -2347,7 +2416,7 @@ tool('get_org', {
     const activeOrg = sessionOrgId ? (orgs.find(o => o.id === sessionOrgId) || null) : null;
 
     const googleDrive = await getGoogleDriveAvailability();
-    const mcpUpdate = await getMcpUpdateMetadata();
+    const mcpUpdate = await getCachedMcpUpdateMetadata();
 
     let members = [];
     if (sessionOrgId) {
@@ -4171,51 +4240,51 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
   } catch (error) { return err(error); }
 });
 
-// ── Collectors ────────────────────────────────────────────────────
+// ── Minions ───────────────────────────────────────────────────────
 
-function compactCollectorEntry(c) {
+function compactMinionEntry(c) {
   if (!c || typeof c !== 'object') return c;
   return { id: c.id, slug: c.slug, name: c.name, enabled: c.enabled, projectId: c.projectId };
 }
 
-// Shape a {collectors:[...]} list with limit/offset pagination + optional compact
+// Shape a {minions:[...]} list with limit/offset pagination + optional compact
 // mode, mirroring shapeSkillCatalog so large lists stay within token budget.
-function shapeCollectorList(result, { limit, offset = 0, compact = false } = {}) {
-  if (!Array.isArray(result?.collectors)) return result;
-  const total = result.collectors.length;
+function shapeMinionList(result, { limit, offset = 0, compact = false } = {}) {
+  if (!Array.isArray(result?.minions)) return result;
+  const total = result.minions.length;
   const start = Math.max(0, Math.floor(Number(offset) || 0));
   const cap = Math.min(Math.max(1, Math.floor(Number(limit) || 25)), 100);
-  const page = result.collectors.slice(start, start + cap);
+  const page = result.minions.slice(start, start + cap);
   result.totalAvailable = total;
   result.offset = start;
   result.returned = page.length;
   result.truncated = start + page.length < total;
-  result.collectors = compact ? page.map(compactCollectorEntry) : page;
+  result.minions = compact ? page.map(compactMinionEntry) : page;
   result.note = compact
-    ? 'Compact list: {id,slug,name,enabled,projectId} only. Use collector(action="get", id="<id>") for full config; limit/offset to page.'
-    : 'Collectors are scoped to the active project (all org collectors when no project is open). Use limit/offset to page; compact=true for a leaner list.';
+    ? 'Compact list: {id,slug,name,enabled,projectId} only. Use minion(action="get", id="<id>") for full config; limit/offset to page.'
+    : 'Minions are scoped to the active project (all org Minions when no project is open). Use limit/offset to page; compact=true for a leaner list.';
   return result;
 }
 
 // Friendlier message when the agent allowlist gate (requireAgentAccess) rejects.
-function collectorGateError(e) {
+function minionGateError(e) {
   if (e?.status === 403 || e?.code === 'agent_disabled') {
-    return new Error('Collector management is not enabled for this org/account (agent allowlist). Ask an admin to add your org or email to DRAFTED_AGENT_ALLOWED_ORGS / DRAFTED_AGENT_ALLOWED_EMAILS.');
+    return new Error('Minion management is not enabled for this org/account (agent allowlist). Ask an admin to add your org or email to DRAFTED_AGENT_ALLOWED_ORGS / DRAFTED_AGENT_ALLOWED_EMAILS.');
   }
   return e;
 }
 
-tool('collector', {
-  action: z.enum(['meta', 'list', 'get', 'create', 'update', 'enable', 'disable', 'delete', 'test_start', 'test_say', 'test_resolve']).describe('Operation to perform. test_* drive a QA conversation against a collector you own (even disabled) to verify it end-to-end.'),
-  id: z.string().optional().describe('[get|update|enable|disable|delete|test_*] collector ID (UUID)'),
+tool('minion', {
+  action: z.enum(['meta', 'list', 'get', 'create', 'update', 'enable', 'disable', 'delete', 'test_start', 'test_say', 'test_resolve']).describe('Operation to perform. test_* drive a QA conversation against a Minion you own (even disabled) to verify it end-to-end.'),
+  id: z.string().optional().describe('[get|update|enable|disable|delete|test_*] Minion ID (UUID)'),
   text: z.string().optional().describe('[test_say] the consumer message to send to your test run'),
   fresh: z.boolean().optional().describe('[test_start] start a brand-new run instead of resuming your latest'),
   actionId: z.string().optional().describe('[test_resolve] id of the pending action to resolve'),
   approve: z.boolean().optional().describe('[test_resolve] approve (default true) or reject the pending action'),
   projectId: z.string().optional().describe('[create|meta] project to bind/scope to (defaults to the active project). The org derives from this project — open the target project first via project(action="open") if none is active.'),
-  name: z.string().optional().describe('[create|update] collector name'),
+  name: z.string().optional().describe('[create|update] Minion name'),
   description: z.string().optional().describe('[create|update] one-line description shown to the consumer'),
-  enabled: z.boolean().optional().describe('[create|update] whether the collector is live; a disabled collector 404s on its /c/<slug> link. enable/disable set this directly.'),
+  enabled: z.boolean().optional().describe('[create|update] whether the Minion is live; a disabled Minion 404s on its /c/<slug> link. enable/disable set this directly.'),
   target: z.object({
     type: z.enum(['new-record', 'layer', 'frame']).describe('what the run writes against'),
     layer: z.string().optional(),
@@ -4244,7 +4313,7 @@ tool('collector', {
   }).optional().describe('[create|update] where/how the producible lands'),
   limit: z.number().optional().describe('[list] max results per page (default 25, max 100)'),
   offset: z.number().optional().describe('[list] skip N results for pagination (default 0)'),
-  compact: z.boolean().optional().describe('[list] return only {id,slug,name,enabled,projectId} per collector'),
+  compact: z.boolean().optional().describe('[list] return only {id,slug,name,enabled,projectId} per Minion'),
 }, async (args) => {
   try {
     const { action } = args;
@@ -4254,18 +4323,18 @@ tool('collector', {
         const pid = active || args.projectId;
         if (!pid) throw new Error('No active project. Call project(action="open") first, or pass projectId.');
         // api() auto-appends the active project; add projectId explicitly only when none is active.
-        const path = active ? '/api/collectors/meta' : `/api/collectors/meta?projectId=${encodeURIComponent(pid)}`;
+        const path = active ? '/api/minions/meta' : `/api/minions/meta?projectId=${encodeURIComponent(pid)}`;
         return ok(await api('GET', path));
       }
       case 'list': {
         // api() auto-appends the active project as ?projectId — so this lists the
-        // active project's collectors, or all org collectors when none is open.
-        const result = await api('GET', '/api/collectors');
-        return ok(shapeCollectorList(result, { limit: args.limit, offset: args.offset, compact: args.compact }));
+        // active project's Minions, or all org Minions when none is open.
+        const result = await api('GET', '/api/minions');
+        return ok(shapeMinionList(result, { limit: args.limit, offset: args.offset, compact: args.compact }));
       }
       case 'get': {
         if (!args.id) throw new Error('id is required for action=get');
-        return ok(await api('GET', `/api/collectors/${args.id}`));
+        return ok(await api('GET', `/api/minions/${args.id}`));
       }
       case 'create': {
         // projectId lives in the BODY (the POST route reads body, ignores the query).
@@ -4278,7 +4347,7 @@ tool('collector', {
         const body = { projectId, name, target, checklist, output };
         if (description !== undefined) body.description = description;
         if (enabled !== undefined) body.enabled = enabled;
-        return ok(await api('POST', '/api/collectors', body));
+        return ok(await api('POST', '/api/minions', body));
       }
       case 'update': {
         if (!args.id) throw new Error('id is required for action=update');
@@ -4287,35 +4356,35 @@ tool('collector', {
           if (args[k] !== undefined) body[k] = args[k];
         }
         if (Object.keys(body).length === 0) throw new Error('At least one field is required for action=update');
-        return ok(await api('PATCH', `/api/collectors/${args.id}`, body));
+        return ok(await api('PATCH', `/api/minions/${args.id}`, body));
       }
       case 'enable':
       case 'disable': {
         if (!args.id) throw new Error(`id is required for action=${action}`);
-        return ok(await api('PATCH', `/api/collectors/${args.id}`, { enabled: action === 'enable' }));
+        return ok(await api('PATCH', `/api/minions/${args.id}`, { enabled: action === 'enable' }));
       }
       case 'delete': {
         if (!args.id) throw new Error('id is required for action=delete');
-        return ok(await api('DELETE', `/api/collectors/${args.id}`));
+        return ok(await api('DELETE', `/api/minions/${args.id}`));
       }
       case 'test_start': {
         if (!args.id) throw new Error('id is required for action=test_start');
-        return ok(await api('POST', `/api/collectors/${args.id}/test-start`, { fresh: !!args.fresh }));
+        return ok(await api('POST', `/api/minions/${args.id}/test-start`, { fresh: !!args.fresh }));
       }
       case 'test_say': {
         if (!args.id) throw new Error('id is required for action=test_say');
         if (!args.text) throw new Error('text is required for action=test_say');
-        return ok(await api('POST', `/api/collectors/${args.id}/test-message`, { content: args.text }));
+        return ok(await api('POST', `/api/minions/${args.id}/test-message`, { content: args.text }));
       }
       case 'test_resolve': {
         if (!args.id) throw new Error('id is required for action=test_resolve');
         if (!args.actionId) throw new Error('actionId is required for action=test_resolve');
-        return ok(await api('POST', `/api/collectors/${args.id}/test-resolve`, { actionId: args.actionId, approve: args.approve !== false }));
+        return ok(await api('POST', `/api/minions/${args.id}/test-resolve`, { actionId: args.actionId, approve: args.approve !== false }));
       }
       default:
-        throw new Error(`Unknown collector action: ${action}`);
+        throw new Error(`Unknown minion action: ${action}`);
     }
-  } catch (error) { return err(collectorGateError(error)); }
+  } catch (error) { return err(minionGateError(error)); }
 });
 
 // ── Resource: canvas info ─────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.14.0",
+  "version": "1.14.2",
   "description": "Drafted — visual thinking surface for humans and AI agents. Renders HTML, markdown, images, and code as frames on a zoomable canvas, with MCP tools for AI agents and real-time sync for humans.",
   "type": "module",
   "files": [