orquestra-mcp 1.50.0 → 1.52.0

package/bin/orquestra-mcp.mjs

@@ -3,6 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { createServer, createSetupNeededServer } from '../src/server.mjs'
 import { runSetup } from '../src/setup.mjs'
 import { runVaultSync } from '../src/vaultSync.mjs'
+import { startUpdateCheck } from '../src/updateCheck.mjs'
 
 const HELP_TEXT = `orquestra-mcp -- Servidor MCP de Orquestra (132 tools)
 
@@ -10,6 +11,9 @@ Uso:
   npx orquestra-mcp            Inicia el servidor MCP por stdio -- lo usa tu cliente
                                 MCP (Claude Code, Claude Desktop, etc.), no se corre a mano
   npx orquestra-mcp setup      Login por navegador + conecta esta carpeta a un proyecto
+  npx orquestra-mcp setup --agent codex
+                                Lo mismo para una herramienta puntual (claude-code, codex,
+                                cursor, gemini-cli...): cada una firma con su propio agente
   npx orquestra-mcp vault sync <carpeta> [--apply]
                                 Sincroniza la base de conocimiento del workspace con una
                                 carpeta de tu vault de Obsidian (la 1ra vez solo muestra el plan)
@@ -17,7 +21,8 @@ Uso:
 
 Config (la deja lista "setup"): ~/.orquestra/mcp-config.json
 Alternativa manual (variables de entorno): ORQUESTRA_API_TOKEN, ORQUESTRA_WORKSPACE_ID,
-ORQUESTRA_DEFAULT_PROJECT_ID
+ORQUESTRA_DEFAULT_PROJECT_ID. ORQUESTRA_AGENT elige el token de una herramienta
+(ej. codex) cuando la carpeta tiene varias conectadas.
 
 Docs completas: https://orquestra.me/mcp
 `
@@ -31,7 +36,8 @@ async function main() {
   }
 
   if (cmd === 'setup') {
-    await runSetup()
+    const agentIdx = process.argv.indexOf('--agent')
+    await runSetup({ agent: agentIdx > 0 ? process.argv[agentIdx + 1] : process.env.ORQUESTRA_AGENT })
     return
   }
 
@@ -45,6 +51,9 @@ async function main() {
     return
   }
 
+  // Sin await: el aviso de versión nueva no debe atrasar el arranque.
+  startUpdateCheck()
+
   let server
   try {
     server = createServer()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.50.0",
+  "version": "1.52.0",
   "description": "Servidor MCP de Orquestra -- 135 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -1,4 +1,4 @@
-import { readConfigFile, resolveProjectForCwd, CONFIG_PATH } from './configFile.mjs'
+import { readConfigFile, resolveProjectForCwd, entryForAgent, agentKey, CONFIG_PATH } from './configFile.mjs'
 import { request } from './http.mjs'
 
 const DEFAULT_API_BASE = 'https://api.orquestra.me'
@@ -8,7 +8,19 @@ export function loadConfig() {
   // Todo sale de la MISMA carpeta mapeada (ver resolveProjectForCwd) --
   // apiToken/workspaceId/projectId siempre son de una sola cuenta, nunca
   // el token de una carpeta con el proyecto de otra.
-  const folderConfig = resolveProjectForCwd(fileConfig?.projects, process.cwd())
+  const folderEntry = resolveProjectForCwd(fileConfig?.projects, process.cwd())
+  // ORQUESTRA_AGENT (ORQ-415) elige el token de esa herramienta en la
+  // carpeta. Si no está conectada falla explícito: caer al token default
+  // haría que sus cambios queden firmados por otra herramienta.
+  const agent = agentKey(process.env.ORQUESTRA_AGENT)
+  const folderConfig = agent ? entryForAgent(folderEntry, agent) : folderEntry
+  if (agent && folderEntry && !folderConfig && !process.env.ORQUESTRA_API_TOKEN) {
+    throw new Error(
+      `La herramienta "${process.env.ORQUESTRA_AGENT}" (ORQUESTRA_AGENT) no está conectada en esta carpeta (${process.cwd()}), ` +
+      `solo otras. Para que sus cambios queden a su nombre y no al de otra herramienta, abre una terminal aquí, ` +
+      `corre "npx orquestra-mcp@latest setup" y elige esa herramienta; después reconecta el MCP.`
+    )
+  }
 
   const apiBase = process.env.ORQUESTRA_API_BASE || folderConfig?.apiBase || DEFAULT_API_BASE
   const apiToken = process.env.ORQUESTRA_API_TOKEN || folderConfig?.apiToken

package/src/configFile.mjs

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
-import { homedir } from 'os'
+import { homedir, hostname } from 'os'
+import { randomBytes } from 'crypto'
 import { join, dirname, win32, posix } from 'path'
 
 export const CONFIG_PATH = join(homedir(), '.orquestra', 'mcp-config.json')
@@ -45,19 +46,104 @@ export function writeConfigFile(data) {
   writeFileSync(CONFIG_PATH, JSON.stringify(data, null, 2), { mode: 0o600 })
 }
 
+// Identidad por herramienta (ORQ-415): cada herramienta (Claude Code, Codex,
+// Cursor...) tiene su propio token -- su propio agente en Orquestra -- aunque
+// trabajen en la misma carpeta. La entrada de la carpeta guarda la conexión
+// "default" arriba (la que se usa sin ORQUESTRA_AGENT) con `agent` = su
+// herramienta, y todas en `agents[clave]`. Una entrada de antes de ORQ-415 no
+// trae `agent`: su token es el de "Claude Code", el default histórico.
+// Mismo slug que agentSlug() de bootstrap.mjs en orquestra-infra.
+export function agentKey(label) {
+  return String(label || '')
+    .normalize('NFD').replace(/[̀-ͯ]/g, '')
+    .toLowerCase().trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+const LEGACY_AGENT = 'claude-code'
+const defaultAgentOf = entry => entry?.agent || (entry?.apiToken ? LEGACY_AGENT : null)
+const connectionOf = ({ apiBase, apiToken, workspaceId, projectId }) => ({ apiBase, apiToken, workspaceId, projectId })
+
+// La conexión de UNA herramienta dentro de la entrada de una carpeta, o null
+// si esa herramienta nunca se conectó ahí (nunca cae al token de otra: eso
+// es justo lo que hacía firmar a Codex como Claude Code).
+export function entryForAgent(entry, key) {
+  if (!entry || !key) return entry
+  if (entry.agents?.[key]) return entry.agents[key]
+  return defaultAgentOf(entry) === key ? connectionOf(entry) : null
+}
+
 // Guarda/actualiza la cuenta+proyecto de UNA carpeta sin pisar las demás --
 // setup se puede correr varias veces, una por cada carpeta contenedora de
 // repos (ver resolveProjectForCwd), y cada corrida solo debe tocar su
 // propia entrada -- incluida la cuenta (apiToken/workspaceId), para poder
 // tener una carpeta en una cuenta de Orquestra y otra carpeta en otra
-// cuenta distinta al mismo tiempo.
-export function upsertProjectMapping({ apiBase, apiToken, workspaceId, folderPath, projectId }) {
+// cuenta distinta al mismo tiempo. Con `agent` solo toca la conexión de esa
+// herramienta: la default de la carpeta cambia únicamente si era la misma
+// herramienta (o la carpeta no tenía ninguna).
+export function upsertProjectMapping({ apiBase, apiToken, workspaceId, folderPath, projectId, agent }) {
   const existing = readConfigFile() || { projects: {} }
   const projects = { ...(existing.projects || {}) }
-  projects[folderPath] = { apiBase, apiToken, workspaceId, projectId }
+  const conn = { apiBase, apiToken, workspaceId, projectId }
+  if (!agent) {
+    projects[folderPath] = conn
+  } else {
+    const prev = projects[folderPath]
+    const agents = { ...(prev?.agents || {}), [agent]: conn }
+    const keepDefault = prev && defaultAgentOf(prev) && defaultAgentOf(prev) !== agent
+    projects[folderPath] = keepDefault
+      ? { ...connectionOf(prev), agent: defaultAgentOf(prev), agents }
+      : { ...conn, agent, agents }
+  }
   writeConfigFile({ projects })
 }
 
+// El setup de una herramienta ya conocida en esta máquina revoca su token
+// anterior (bootstrap en orquestra-infra): hay que ponerle el nuevo a TODAS
+// las carpetas donde esa herramienta usa el mismo workspace, no solo a la del
+// setup, o las demás quedarían con un token muerto. Devuelve las carpetas.
+export function replaceAgentToken({ workspaceId, agent, apiToken }) {
+  const existing = readConfigFile()
+  if (!existing?.projects) return []
+  const updated = []
+  for (const [folderPath, entry] of Object.entries(existing.projects)) {
+    let touched = false
+    if (defaultAgentOf(entry) === agent && entry.workspaceId === workspaceId) { entry.apiToken = apiToken; touched = true }
+    const own = entry.agents?.[agent]
+    if (own && own.workspaceId === workspaceId) { own.apiToken = apiToken; touched = true }
+    if (touched) updated.push(folderPath)
+  }
+  if (updated.length) writeConfigFile(existing)
+  return updated
+}
+
+// Herramientas ya conectadas en esta máquina (en cualquier carpeta).
+export function connectedAgents() {
+  const keys = new Set()
+  for (const entry of Object.values(readConfigFile()?.projects || {})) {
+    if (defaultAgentOf(entry)) keys.add(defaultAgentOf(entry))
+    for (const key of Object.keys(entry.agents || {})) keys.add(key)
+  }
+  return keys
+}
+
+// Identidad de la máquina (ORQ-415): un id aleatorio, no el serial ni la MAC
+// -- solo distingue esta instalación ("Codex · MacBook-Pro" vs "Codex ·
+// Mac-mini"). Se crea una vez y se reusa en cada setup.
+export const MACHINE_PATH = join(homedir(), '.orquestra', 'machine.json')
+
+export function readOrCreateMachine() {
+  try {
+    const saved = JSON.parse(readFileSync(MACHINE_PATH, 'utf8'))
+    if (/^[a-f0-9]{16,64}$/.test(saved.id)) return { id: saved.id, name: saved.name || hostname().replace(/\.local$/, '') }
+  } catch {}
+  const machine = { id: randomBytes(8).toString('hex'), name: hostname().replace(/\.local$/, '') }
+  mkdirSync(dirname(MACHINE_PATH), { recursive: true })
+  writeFileSync(MACHINE_PATH, JSON.stringify(machine, null, 2), { mode: 0o600 })
+  return machine
+}
+
 // Busca, subiendo desde cwd hacia la raíz, la carpeta mapeada más específica
 // -- mismo criterio que .editorconfig/.gitconfig: el ancestro más cercano
 // gana, así que un repo individual con su propio mapeo (y su propia cuenta)

package/src/server.mjs

@@ -5,6 +5,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
 import { loadConfig, apiGet, apiPost, apiPatch, apiPatchPath, apiDelete, apiDeletePath, putToPresignedUrl, ApiError } from './api.mjs'
 import { cancelContext } from './http.mjs'
+import { updateNotice } from './updateCheck.mjs'
 import { STAGES, PLAYBOOKS } from './stages.mjs'
 import { FOUNDATIONS } from './foundations.mjs'
 import { PLATFORM_PLAYBOOKS, TRACKING_TOOLS } from './platformPlaybooks.mjs'
@@ -104,7 +105,7 @@ const SETUP_GUIDE = {
 // preguntar en vez de adivinar.
 const SERVER_INSTRUCTIONS = `Este server conecta con Orquestra, la app de gestión de proyectos del usuario -- úsalo para mantener su proyecto sincronizado con el trabajo real, sin que tenga que pedírtelo cada vez.
 
-Al empezar una sesión de trabajo en este proyecto, llama una vez a get_project_context para saber en qué fase está, qué tareas hay abiertas/vencidas/bloqueadas y qué se hizo recientemente. Úsalo como contexto de fondo, no lo repitas en cada mensaje.
+Al empezar una sesión de trabajo en este proyecto, llama una vez a get_project_context para saber en qué fase está, qué tareas hay abiertas/vencidas/bloqueadas y qué se hizo recientemente. Úsalo como contexto de fondo, no lo repitas en cada mensaje. Si trae orquestraMcpUpdate, avísale al usuario UNA sola vez en la sesión que hay una versión nueva de este MCP y cómo actualizar (usa su campo message), sin interrumpir lo que estaba pidiendo.
 
 Si get_project_context devuelve un proyecto vacío (sin módulos ni tareas), es la primera vez que se usa este MCP aquí -- pero "vacío en Orquestra" NO significa "recién empezado en la realidad". Antes de ofrecer nada, pregúntale al usuario: ¿este proyecto es una idea nueva, o ya existe y solo lo estás conectando por primera vez? Según la respuesta:
 - Si es una idea nueva: llama a get_setup_guide y ofrece un playbook de etapa "pre" (get_stage_playbook + apply_stage_playbook) -- ahí sí basta con eso, el proyecto de verdad no tiene nada más que sincronizar todavía.
@@ -133,6 +134,7 @@ Durante el trabajo normal de código, sin que el usuario te lo pida explícitame
 - Paridad por producto: las distribuciones que son el mismo producto en distintas plataformas (típicamente Web/iOS/Android) comparten un productKey (list_distributions lo muestra). Si al crear una tarea con scope en una de ellas la respuesta trae parityAddedDistIds, el server sumó las hermanas como pendientes -- dícelo al usuario ("también quedó pendiente en iOS y Android") y no lo deshagas salvo que el trabajo sea genuinamente de una sola plataforma (entonces skipParity:true, o quítalas con update_task/scope explicando por qué). Al cerrar una tarea con scope multiplataforma, marca done:true SOLO en la plataforma donde de verdad se hizo (update_task/scope) -- el estatus "Listo" no mueve esos flags solo; cuando un commit o PR del repo de otra plataforma menciona el código de la tarea (ej. "(ORQ-123)"), el servidor propone solo una sugerencia scope_done_proposal (list_suggestions) para marcar esa plataforma como hecha: si la ves, confirma con el código real y acéptala con accept_suggestion en vez de editar el scope a mano. Si el trabajo de otra plataforma ya vive en OTRA tarea (una tarea gemela, ej. "[iOS] ..." y "[Android] ..."), no dupliques scope: liga la hermana con update_task parityOf=<id de la tarea origen> y en paridad cuentan como un solo item; al cerrar la hermana su plataforma queda hecha sola. Dejar las hermanas en done:false es exactamente lo que hace que el desfase aparezca en get_parity_summary y en la revisión de sincronización (tasksClosedWithParityPending), que es el punto: que nunca se olvide el trabajo del otro lado. Si el proyecto tiene 2+ plataformas y ninguna tiene productKey (get_parity_summary → productGroups.configured=false), pregúntale al usuario cuáles son el mismo producto y configúralo con update_distribution -- nunca lo infieras solo del tipo de plataforma.
 - Al crear o editar una tarea (o un módulo), llena TODO campo para el que tengas un dato real, no solo title/moduleId/dueDate/comment: type (no lo dejes en el default "feature" si en realidad es un bug/mejora/doc/etc.), tags, stack (tecnologías que genuinamente tocaste), scope (paridad multiplataforma, si aplica), y los campos de código (branch/prNumber/prUrl/prStatus/commitCount/resolvedCommitSha/resolvedCommitMessage/resolvedCommitUrl/resolvedCommitAt) cuando de verdad sepas esos valores (el branch en el que estás trabajando, el PR que abriste, el commit que resolvió la tarea). No dejes un campo en blanco solo porque no es obligatorio -- pero esto no es licencia para inventar: si no tenés el dato real (ej. no hay branch/PR porque el proyecto commitea directo a main), dejalo vacío en vez de rellenarlo con algo plausible pero falso -- mismo criterio que ya se pedía para resolvedCommitSha.
 - Si una tarea tiene más de una actividad o paso concreto, no los amontones como texto corrido en description -- usa el checklist (add_checklist_item, un ítem por actividad, opcionalmente con responsable) para que cada paso se pueda marcar independientemente. description queda para el contexto/propósito general de la tarea (el qué y el por qué), no como lista de pasos. Si estás editando una tarea existente cuya description ya creció así, migra esos puntos a checklist en vez de seguir agregando ahí.
+- Una tarea = UN entregable; un ítem del checklist = UN paso corto de ese entregable. Si el título junta varias cosas con comas o "y" ("X, Y y Z"), o un ítem del checklist tendría su propio deploy, commits, pruebas o alertas (es una integración/función entera, no un paso), son tareas separadas: créalas aparte en el mismo módulo (si son muchas del mismo tema, ese tema es un módulo, no una tarea con 14 ítems). Lo que depende de algo externo o futuro (un contrato, un proveedor, una versión que todavía no sale, la respuesta de una tienda) va en su propia tarea -- en Bloqueado o con reviewDate --, nunca dentro de una tarea que ya está lista, porque la deja abierta indefinidamente. El texto de un ítem es la acción ("Configurar cron diario de la CSL"), no la bitácora: commits, "probado en vivo", tiempos y tamaños van en un comment de la tarea, en resolvedCommitSha o en el changelog. Algo que ya no aplica no se deja como ítem pendiente con "ya no hace falta" en el texto: díselo al usuario y bórralo con delete_checklist_item (con un comment en la tarea explicando por qué). No reorganices tareas que ya existen así salvo que el usuario lo pida -- la regla es para lo nuevo.
 - Al cerrar una tarea en la que trabajaste de verdad (o al final de una sesión de trabajo real sobre ella), registrá las horas con log_time -- el tiempo REAL que llevó ese trabajo en esta sesión (aproximalo con honestidad: minutos de trabajo real, no la duración del chat ni la estimación de la tarea), con una nota corta de qué se hizo. Ese registro alimenta "Horas del equipo" en Inversión de Contenido y es la única forma de que el costo real del proyecto no dependa de que el usuario lo cargue a mano. No lo inventes ni lo infles; si genuinamente no podés estimar el tiempo de la sesión, no registres nada.
 - No todas las tareas necesitan una corrida de QA -- clasifica antes de disparar una: cambios que afectan comportamiento real (features, bugs, UI, lógica de negocio, endpoints/API) sí la necesitan; cambios que no alteran comportamiento (docs, comentarios, refactors sin cambio funcional, config/tooling interno, notas/reuniones/ideas) no. Si decides que sí, revisa primero con list_agents que exista un agente (kind="qa") para el stack que tocaste (si no hay ninguno, créalo con create_agent -- necesita una máquina ya emparejada, ver Workspace → Máquinas) y llama a create_agent_run en la rama real de ese trabajo (manda taskId si el trabajo era de una tarea puntual -- si el agente tiene la revisión con IA activada, la acota a eso en vez de "revisa todo el proyecto"), dejando la tarea en "En revisión" -- NUNCA la muevas a "Listo" ni digas que "QA lo revisó" sin haber confirmado con get_agent_run un estatus terminal "passed" de verdad (las corridas son asíncronas, tardan minutos en otra máquina). Si tarda, dile al usuario que quedó en cola (con el runId) y que confirmas cuando termine -- no lo des por hecho nunca.
 
@@ -175,7 +177,10 @@ export function createSetupNeededServer(reason) {
   server.registerTool('diagnostico_conexion', {
     description: 'Explica por qué Orquestra no está conectado en esta carpeta y cómo arreglarlo.',
     inputSchema: {},
-  }, async () => ({ content: [{ type: 'text', text: `orquestra-mcp ${PKG_VERSION}: ${reason}` }] }))
+  }, async () => {
+    const update = updateNotice(PKG_VERSION)
+    return { content: [{ type: 'text', text: `orquestra-mcp ${PKG_VERSION}: ${reason}${update ? `\n\n${update.message}` : ''}` }] }
+  })
   return server
 }
 
@@ -205,14 +210,14 @@ export function createServer() {
     return projectId
   }
 
-  function registerRead(name, path, description, extraSchema, buildParams) {
+  function registerRead(name, path, description, extraSchema, buildParams, decorate = data => data) {
     server.registerTool(
       name,
       { description, inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC), ...extraSchema } },
       async (args) => {
         try {
           const data = await apiGet(config, path, buildParams(args, resolveProjectId(args.projectId)))
-          return textResult(data)
+          return textResult(decorate(data))
         } catch (err) {
           return errorResult(err)
         }
@@ -264,7 +269,11 @@ export function createServer() {
     '/v1/context',
     'Resumen compacto del estado de un proyecto de Orquestra: fase, plataformas, tareas abiertas/vencidas/bloqueadas, módulos, ideas y changelog reciente.',
     {},
-    (args, projectId) => ({ projectId })
+    (args, projectId) => ({ projectId }),
+    data => {
+      const update = updateNotice(PKG_VERSION)
+      return update ? { ...data, orquestraMcpUpdate: update } : data
+    }
   )
 
   registerRead(
@@ -295,10 +304,10 @@ export function createServer() {
   registerRead(
     'search',
     '/v1/search',
-    'Busca por texto en tareas, actividades (reuniones/llamadas), notas, ideas y docs de un proyecto de Orquestra. También por folio ("ORQ-123") o por clave de módulo ("AUTH-3") -- la exacta sale primero -- y sin importar acentos. Primero lo que coincide en el folio o el título, después en el cuerpo; tope de 30 resultados: si buscas ideas o docs en un proyecto con muchas tareas, pasa `types` para que no queden tapadas.',
+    'Busca por texto en tareas, actividades (reuniones/llamadas), notas, ideas, docs, riesgos, módulos, contenido y distribuciones de un proyecto de Orquestra -- en los mismos campos que pueden tener [[wikilinks]] (descripción, mitigación, criterios de cierre, puntos, verificaciones...). También por folio ("ORQ-123") o por clave de módulo ("AUTH-3") -- la exacta sale primero -- y sin importar acentos. Primero lo que coincide en el folio o el título, después en el cuerpo; tope de 30 resultados: si buscas ideas o docs en un proyecto con muchas tareas, pasa `types` para que no queden tapadas.',
     {
       q: z.string().describe('Texto a buscar'),
-      types: z.array(z.enum(['task', 'activity', 'note', 'idea', 'doc', 'knowledge'])).optional().describe('Limitar a estos tipos (opcional). Sin esto busca en todos. knowledge = solo la base vinculada a este proyecto.'),
+      types: z.array(z.enum(['task', 'activity', 'note', 'idea', 'doc', 'knowledge', 'risk', 'module', 'content', 'distribution'])).optional().describe('Limitar a estos tipos (opcional). Sin esto busca en todos. knowledge = solo la base vinculada a este proyecto.'),
     },
     (args, projectId) => ({ projectId, q: args.q, types: args.types?.join(',') })
   )
@@ -751,7 +760,7 @@ export function createServer() {
   registerCreate(
     'create_task',
     '/v1/tasks',
-    'Crea una tarea en un proyecto de Orquestra. moduleId y dueDate son OBLIGATORIOS -- revisa list_modules primero (si ninguno aplica, creá uno con create_module antes de crear la tarea, nunca la dejes sin agrupar); dueDate se calcula con criterio real (prioridad/tamaño del trabajo), nunca un valor arbitrario. Una reunión, llamada o seguimiento NO es tarea: usa log_activity (type "business" sí es tarea: entregable no-código).',
+    'Crea una tarea en un proyecto de Orquestra. moduleId y dueDate son OBLIGATORIOS -- revisa list_modules primero (si ninguno aplica, creá uno con create_module antes de crear la tarea, nunca la dejes sin agrupar); dueDate se calcula con criterio real (prioridad/tamaño del trabajo), nunca un valor arbitrario. Una reunión, llamada o seguimiento NO es tarea: usa log_activity (type "business" sí es tarea: entregable no-código). Una tarea = UN entregable: si el título junta varias cosas con comas o "y", crea una tarea por cada una (mismo módulo); lo que espera algo externo o futuro va en su propia tarea, no dentro de otra.',
     {
       relatedTo: RELATED_TO,
       title: z.string().describe('Título de la tarea'),
@@ -1580,7 +1589,7 @@ export function createServer() {
   server.registerTool(
     'add_checklist_item',
     {
-      description: 'Agrega un ítem al checklist de una tarea de Orquestra, opcionalmente con un responsable.',
+      description: 'Agrega un ítem al checklist de una tarea de Orquestra, opcionalmente con un responsable. Un ítem es UN paso corto del entregable de la tarea, escrito como acción. Si lleva su propio deploy, commits, pruebas o alertas, o depende de algo externo (contrato, proveedor, versión futura), es una tarea aparte (create_task), no un ítem. Commits y "probado en vivo" van en un comment de la tarea, no en el texto del ítem.',
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
         taskId: z.string().describe('ID de la tarea'),

package/src/setup.mjs

@@ -4,7 +4,7 @@ import { exec } from 'child_process'
 import { createInterface } from 'readline'
 import { homedir } from 'os'
 import { resolve } from 'path'
-import { upsertProjectMapping, CONFIG_PATH } from './configFile.mjs'
+import { upsertProjectMapping, replaceAgentToken, connectedAgents, readOrCreateMachine, agentKey, CONFIG_PATH } from './configFile.mjs'
 
 const DEFAULT_API_BASE = 'https://api.orquestra.me'
 const DEFAULT_WEB_URL = 'https://app.orquestra.me'
@@ -15,12 +15,16 @@ function openBrowser(url) {
   exec(`${cmd} "${url}"`, () => {})
 }
 
+// Herramientas conocidas (ORQ-415): cada una queda como su propio agente en
+// Orquestra ("Codex · MacBook-Pro") y con su propio token en la carpeta.
+const TOOLS = ['Claude Code', 'Codex', 'Cursor', 'Gemini CLI', 'Claude Desktop']
+
 function prompt(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer) }))
 }
 
-export async function runSetup() {
+export async function runSetup({ agent: presetAgent } = {}) {
   const apiBase = process.env.ORQUESTRA_API_BASE || DEFAULT_API_BASE
   const webUrl = process.env.ORQUESTRA_WEB_URL || DEFAULT_WEB_URL
   const state = randomBytes(16).toString('hex')
@@ -75,8 +79,9 @@ export async function runSetup() {
   const idToken = await idTokenPromise
   console.log('Login recibido, configurando...')
 
-  const agentLabelAnswer = await prompt('¿Cómo se llama este agente/herramienta? [Claude Code]: ')
-  const agentLabel = agentLabelAnswer.trim() || 'Claude Code'
+  const machine = readOrCreateMachine()
+  const agentLabel = await chooseTool(presetAgent, machine)
+  const agent = agentKey(agentLabel)
 
   // askIfMissing: si no hay workspace la API no crea nada solo -- avisa
   // (needsWorkspace) y aquí se le pide el nombre al usuario.
@@ -84,7 +89,7 @@ export async function runSetup() {
     const res = await fetch(`${apiBase}/v1/bootstrap`, {
       method: 'POST',
       headers: { Authorization: `Bearer ${idToken}`, 'Content-Type': 'application/json' },
-      body: JSON.stringify({ agentLabel, askIfMissing: true, ...extra }),
+      body: JSON.stringify({ agentLabel, machineId: machine.id, machineName: machine.name, askIfMissing: true, ...extra }),
     })
     const body = await res.json()
     if (!res.ok) throw new Error(body?.error || `HTTP ${res.status}`)
@@ -123,6 +128,14 @@ export async function runSetup() {
   }
 
   const { workspaceId, token, projects } = body
+  // La API anterior a ORQ-415 no manda `agent`.
+  // El token anterior ya quedó revocado en el servidor: se reemplaza en todas
+  // las carpetas de esta herramienta AHORA, antes de las preguntas, para que
+  // cancelar el setup a la mitad no deje carpetas con un token muerto.
+  const renewedFolders = body.agent?.known ? replaceAgentToken({ workspaceId, agent, apiToken: token }) : []
+  if (body.agent?.known) console.log(`\nYa te conocía: "${body.agent.name}". Renové su token (el anterior quedó revocado).`)
+  else if (body.agent?.adopted) console.log(`\nTu agente "${agentLabel}" de antes quedó ligado a esta máquina como "${body.agent.name}".`)
+  else if (body.agent) console.log(`\nNuevo agente en tu equipo de Orquestra: "${body.agent.name}".`)
   // La API de producción anterior a ORQ-388 no manda workspaceName.
   const wsLabel = body.workspaceName ? ` del workspace "${body.workspaceName}"` : ''
   let defaultProjectId
@@ -173,20 +186,64 @@ export async function runSetup() {
     : folderAnswer.trim()
   const folderPath = expanded ? resolve(expanded) : process.cwd()
 
-  upsertProjectMapping({ apiBase, apiToken: token, workspaceId, folderPath, projectId: defaultProjectId })
-  console.log(`\nListo. "${folderPath}" (y sus subcarpetas) ya apunta a este proyecto -- guardado en ${CONFIG_PATH}.`)
-  // En Windows Claude Code necesita `cmd /c` para lanzar npx, y el config de
-  // Claude Desktop vive en %APPDATA%. `@latest` evita que npx reuse una
-  // versión vieja de su caché.
-  const isWindows = process.platform === 'win32'
-  console.log('\nSiguiente paso -- conéctalo a tu agente de IA:\n')
-  console.log('  Claude Code:')
-  console.log(`    claude mcp add orquestra -- ${isWindows ? 'cmd /c ' : ''}npx -y orquestra-mcp@latest`)
-  if (isWindows) console.log('    (si "claude" no se reconoce: npm install -g @anthropic-ai/claude-code y abre otra terminal)')
-  console.log('    Después reinicia Claude Code o reconéctalo con /mcp.\n')
-  console.log(`  Claude Desktop -- agrega esto a ${isWindows ? '%APPDATA%\\Claude\\' : '~/Library/Application Support/Claude/'}claude_desktop_config.json:`)
-  console.log('    { "mcpServers": { "orquestra": { "command": "npx", "args": ["-y", "orquestra-mcp@latest"] } } }\n')
-  console.log('  ¿Usas Cursor, ChatGPT/Codex o Gemini CLI? La config de cada uno está en:')
-  console.log('    https://www.orquestra.me/mcp#instalacion\n')
+  upsertProjectMapping({ apiBase, apiToken: token, workspaceId, folderPath, projectId: defaultProjectId, agent })
+  const others = renewedFolders.filter(f => f !== folderPath)
+  console.log(`\nListo. "${folderPath}" (y sus subcarpetas) ya apunta a este proyecto con ${agentLabel} -- guardado en ${CONFIG_PATH}.`)
+  if (others.length) console.log(`También actualicé el token de ${agentLabel} en: ${others.join(', ')}.`)
+  console.log('\nSiguiente paso -- conéctalo a tu herramienta (si ya estaba conectada, solo reconecta el MCP):\n')
+  console.log(connectionHelp(agent, agentLabel))
+  console.log('\n¿Otra herramienta en esta misma carpeta? Corre de nuevo "npx orquestra-mcp@latest setup" y elígela:')
+  console.log('cada una firma con su propio agente.')
   console.log('Docs completas y todas las tools disponibles: https://www.orquestra.me/mcp')
 }
+
+// Sin preguntar "¿cómo se llama?" cada vez: se elige de la lista (o viene con
+// --agent) y se marca lo que ya está conectado en esta máquina.
+async function chooseTool(preset, machine) {
+  if (preset?.trim()) return TOOLS.find(t => agentKey(t) === agentKey(preset)) || preset.trim()
+  const connected = connectedAgents()
+  const already = TOOLS.filter(t => connected.has(agentKey(t)))
+  console.log(`\nEsta máquina: ${machine.name}${already.length ? ` (ya conectadas: ${already.join(', ')})` : ''}`)
+  console.log('¿Para qué herramienta es esta conexión?')
+  TOOLS.forEach((t, i) => console.log(`  ${i + 1}. ${t}${connected.has(agentKey(t)) ? ' (ya conectada: renueva su token)' : ''}`))
+  console.log(`  ${TOOLS.length + 1}. Otra`)
+  for (;;) {
+    const answer = (await prompt('Número [Enter para Claude Code]: ')).trim()
+    const idx = answer === '' ? 1 : parseInt(answer, 10)
+    if (idx >= 1 && idx <= TOOLS.length) return TOOLS[idx - 1]
+    if (idx === TOOLS.length + 1) {
+      const name = (await prompt('Nombre de la herramienta: ')).trim()
+      if (name) return name
+    }
+    console.log('Selección inválida.')
+  }
+}
+
+// La config de cada herramienta lleva ORQUESTRA_AGENT para que use SU token
+// (sin eso usaría el default de la carpeta y firmaría como otra).
+// En Windows Claude Code necesita `cmd /c` para lanzar npx, y el config de
+// Claude Desktop vive en %APPDATA%. `@latest` evita que npx reuse una
+// versión vieja de su caché.
+function connectionHelp(agent, agentLabel) {
+  const isWindows = process.platform === 'win32'
+  const json = file => `  ${agentLabel} -- agrega esto a ${file}:\n` +
+    `    { "mcpServers": { "orquestra": { "command": "npx", "args": ["-y", "orquestra-mcp@latest"], "env": { "ORQUESTRA_AGENT": "${agent}" } } } }`
+  if (agent === 'claude-code') {
+    return '  Claude Code:\n' +
+      `    claude mcp add orquestra -e ORQUESTRA_AGENT=${agent} -- ${isWindows ? 'cmd /c ' : ''}npx -y orquestra-mcp@latest\n` +
+      (isWindows ? '    (si "claude" no se reconoce: npm install -g @anthropic-ai/claude-code y abre otra terminal)\n' : '') +
+      '    (si ya estaba agregado: claude mcp remove orquestra y vuelve a agregarlo)\n' +
+      '    Después reinicia Claude Code o reconéctalo con /mcp.'
+  }
+  if (agent === 'codex') {
+    return '  Codex -- en ~/.codex/config.toml:\n' +
+      '    [mcp_servers.orquestra]\n' +
+      '    command = "npx"\n' +
+      '    args = ["-y", "orquestra-mcp@latest"]\n' +
+      `    env = { ORQUESTRA_AGENT = "${agent}" }`
+  }
+  if (agent === 'cursor') return json('~/.cursor/mcp.json')
+  if (agent === 'gemini-cli') return json('~/.gemini/settings.json')
+  if (agent === 'claude-desktop') return json(`${isWindows ? '%APPDATA%\\Claude\\' : '~/Library/Application Support/Claude/'}claude_desktop_config.json`)
+  return json('la config de MCP de tu herramienta') + '\n  Guía por herramienta: https://www.orquestra.me/mcp#instalacion'
+}

package/src/updateCheck.mjs

@@ -0,0 +1,56 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+// Aviso de versión nueva (ORQ-415): al arrancar, el server pregunta a npm cuál
+// es la última versión publicada (caché de 12 h en ~/.orquestra, así casi
+// ningún arranque sale a la red) y get_project_context la devuelve en
+// `orquestraMcpUpdate` para que el agente le diga al usuario cómo actualizar.
+// Nunca bloquea el arranque ni falla: sin red simplemente no hay aviso.
+const CACHE_PATH = join(homedir(), '.orquestra', 'update-check.json')
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000
+const REGISTRY_URL = 'https://registry.npmjs.org/orquestra-mcp/latest'
+
+let latestKnown = null
+
+export function isNewer(latest, current) {
+  const parts = v => String(v).split('-')[0].split('.').map(n => parseInt(n, 10) || 0)
+  const [a, b] = [parts(latest), parts(current)]
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] || 0) !== (b[i] || 0)) return (a[i] || 0) > (b[i] || 0)
+  }
+  return false
+}
+
+export async function startUpdateCheck({ fetchImpl = fetch, now = Date.now() } = {}) {
+  if (process.env.ORQUESTRA_NO_UPDATE_CHECK) return null
+  try {
+    const cached = JSON.parse(readFileSync(CACHE_PATH, 'utf8'))
+    if (cached.latest && now - cached.checkedAt < CACHE_TTL_MS) return (latestKnown = cached.latest)
+  } catch {}
+  try {
+    const res = await fetchImpl(REGISTRY_URL, { signal: AbortSignal.timeout(3000) })
+    if (!res.ok) return null
+    const { version } = await res.json()
+    if (!version) return null
+    latestKnown = version
+    mkdirSync(dirname(CACHE_PATH), { recursive: true })
+    writeFileSync(CACHE_PATH, JSON.stringify({ latest: version, checkedAt: now }))
+    return version
+  } catch {
+    return null
+  }
+}
+
+export function updateNotice(current) {
+  if (!latestKnown || !isNewer(latestKnown, current)) return null
+  return {
+    current,
+    latest: latestKnown,
+    message:
+      `Hay una versión nueva de orquestra-mcp (${latestKnown}; esta sesión usa ${current}). ` +
+      `Para actualizar, reinicia tu herramienta o reconecta el MCP (en Claude Code: /mcp → orquestra → Reconnect). ` +
+      `Si sigue la versión vieja, en la config del MCP cambia "orquestra-mcp" por "orquestra-mcp@latest" ` +
+      `(sin @latest, npx reusa la versión que tiene en caché). Novedades: https://www.orquestra.me/mcp`,
+  }
+}