openvisio-agent 0.25.1 → 0.25.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.25.3] — 2026-09-21
+
+- Normalize structured and compact Markdown MCP list results through one provider-neutral discovery path, so every runtime can resolve projects, agents, boards, tasks, task types, and channels from the same saved setup.
+- Recognize backend-generated dedicated channel names that append the agent identifier suffix, allowing first-connection introductions and fresh threads to reach the correct agent channel.
+
+## [0.25.2] — 2026-09-21
+
+- Load each provider's available models in Agent Studio, apply the selected model exactly to new ACP sessions, and show the model the running watcher actually uses.
+- Add Start, Stop, and Restart controls for local watchers in Agent Studio, backed by lifecycle APIs that report current watcher state.
+- Recognize mentions addressed to saved agent display names containing spaces or hyphens, so names such as `Andre - Opencode` reliably trigger their watcher.
+- Reconcile backend activity every 30 seconds to recover missed mentions promptly while preserving immediate startup and reconnect checks.
+
 ## [0.25.1] — 2026-09-19
 
 - Discover task columns by board when required by the live MCP schema; remove the incorrect project-only instruction that caused failed calls and assignment lookups.

package/README.md

@@ -79,7 +79,7 @@ The integration follows Mastra's [semantic memory](https://mastra.ai/docs/memory
 
 Model selections are stable. Exact IDs (including reasoning effort) are preserved. An unsuffixed ACP model may resolve once to the same model with `medium` effort; the watcher saves that exact selection. Unavailable selections produce an explicit error rather than switching generations or families. Claude versioned IDs are preserved, with automatic family fallbacks disabled. Codex uses the configured chat model for replies.
 
-Backend/BYO watchers reconcile immediately whenever the process starts or the WebSocket connects. A direct MCP session discovers and caches the backend's actual `tools/list` response, then uses available tools such as `list_agents`, `list_projects`, `list_tasks`, `list_task_types`, and `list_activity` to recover assigned tasks and recent mention activity missed while offline. Optional actions such as ticket comments are used only when advertised; their absence cannot strand a completed ticket in a retry loop. The same zero-model check runs every five minutes as a safety net; a model starts only when pending work exists.
+Backend/BYO watchers reconcile immediately whenever the process starts or the WebSocket connects. A direct MCP session discovers and caches the backend's actual `tools/list` response, then uses available tools such as `list_agents`, `list_projects`, `list_tasks`, `list_task_types`, and `list_activity` to recover assigned tasks and recent mention activity missed while offline. Team discovery is shared by every runtime provider: structured MCP results and compact Markdown list envelopes are normalized once before the watcher resolves its project, identity, boards, tickets, or dedicated channel. Adding another model provider therefore reuses the same saved team connection and setup path instead of adding provider-specific project discovery. Optional actions such as ticket comments are used only when advertised; their absence cannot strand a completed ticket in a retry loop. The same zero-model check runs every 30 seconds as a safety net; a model starts only when pending work exists.
 
 The backend MCP may be stateful or stateless. A successful initialize response without `Mcp-Session-Id` is accepted as stateless, so OpenCode agents do not stop with “MCP initialize returned no session id.” Each OpenCode lane keeps its MCP identity in a private per-agent config directory while the repository is supplied separately with `--dir`; stale workspace configuration therefore cannot swap one agent's credentials for another's. The generated remote configuration sends the agent headers directly, disables OAuth probing, and backend cycles never request relay-only inbox calls or MCP resource-discovery tools in place of team actions.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team \u2014 MCP tools + optional autonomy \u2014 in one command.",
   "type": "module",
   "bin": {

package/scenarios/workspace.scenarios.mjs

@@ -16,7 +16,7 @@ async function eventually(predicate, description) {
   assert.fail(`Watcher did not reach: ${description}`)
 }
 
-export function fixture({ agent = 'codex', task = true, run, threadError = false, commentTools = [], onComment, selfProfile = self, listAgents, getTicket, listChannels, transportRecoveryDelays, activityReporter } = {}) {
+export function fixture({ agent = 'codex', name, task = true, run, threadError = false, commentTools = [], onComment, selfProfile = self, listAgents, getTicket, listChannels, transportRecoveryDelays, activityReporter } = {}) {
   const dir = mkdtempSync(join(tmpdir(), 'byo-workspace-'))
   const posts = [], runs = [], calls = [], logs = [], messages = [], subscriptions = []
   const ticket = { id: 77, project_id: 1, slug: 'OPEN-77', title: 'Repair the component', agent_id: 7, status: 'In Progress', type_id: 1, updated_at: 'revision-1' }
@@ -71,7 +71,7 @@ export function fixture({ agent = 'codex', task = true, run, threadError = false
     }
   }
   const start = () => {
-    watcher = createBackendWatcher({ wsUrl: 'wss://unused.example.test', mcpUrl: 'https://unused.example.test/mcp', apiKey: 'test-key', identifier: 'alex', slug: 'test-alex', agent, workdir: join(dir, 'workspace'), model: 'test-code', chatModel: 'test-chat' }, {
+    watcher = createBackendWatcher({ wsUrl: 'wss://unused.example.test', mcpUrl: 'https://unused.example.test/mcp', apiKey: 'test-key', identifier: 'alex', slug: 'test-alex', name, agent, workdir: join(dir, 'workspace'), model: 'test-code', chatModel: 'test-chat' }, {
       stateDir: dir, memory, mcpClient: mcp, createRunner, transportRecoveryDelays, activityReporter, connect: (callbacks) => { connection = callbacks; return { close() {}, subscribeOrganization(id) { subscriptions.push(id) } } }, autoStart: false, log: (value) => logs.push(value),
     })
     return watcher

package/src/channel-routing.mjs

@@ -22,9 +22,10 @@ export function dedicatedChannel(channels, { id, identifier, aliases = [], chann
     return identifier && ownerIdentifier(channel) === identifier
   })
   if (owned.length) return owned.length === 1 ? owned[0] : null
+  const identifierSuffix = String(identifier || '').split('-').at(-1)?.toLowerCase() || ''
   const names = new Set([identifier, ...aliases].filter(Boolean).flatMap((alias) => {
     const name = normalize(alias)
-    return [name, `agent-${name}`, `${name}-agent`]
+    return [name, `agent-${name}`, `${name}-agent`, ...(identifierSuffix ? [`${name}-${identifierSuffix}`] : [])]
   }).filter((name) => !['general', 'team', 'project', 'dev', 'development'].includes(name)))
   // Explicit ownership always outranks a similar name. A recycled agent name
   // must never route a new thread into somebody else's dedicated channel.

package/src/mastra-harness.mjs

@@ -43,6 +43,38 @@ function commandFor(agent) {
   return null
 }
 
+export async function listAcpRuntimeModels(agent, { AcpAgentClass = AcpAgent, cwd = process.cwd(), timeoutMs = 15_000 } = {}) {
+  const runtime = commandFor(agent)
+  if (!runtime) return []
+  const acp = new AcpAgentClass({
+    id: `openvisio-${agent}-model-catalog-${Date.now()}`,
+    name: `OpenVisio ${agent} model catalog`,
+    description: 'Reads the models advertised by the local coding runtime.',
+    command: runtime.command,
+    args: runtime.args,
+    cwd,
+    session: { cwd, mcpServers: [] },
+    persistSession: false,
+    createClient: agent === 'codex' ? (client) => new Proxy(client, {
+      get(target, property, receiver) {
+        if (property === 'extNotification') return async () => {}
+        return Reflect.get(target, property, receiver)
+      },
+    }) : undefined,
+  })
+  let timer
+  try {
+    const models = await Promise.race([
+      acp.getAvailableModels(),
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`${agent} model discovery timed out`)), timeoutMs); timer.unref?.() }),
+    ])
+    return [...new Set((Array.isArray(models) ? models : []).map(entry => typeof entry === 'string' ? entry : entry?.modelId).map(value => String(value || '').trim()).filter(Boolean))]
+  } finally {
+    clearTimeout(timer)
+    try { acp.connection.disconnect() } catch { /* discovery may fail before the transport starts */ }
+  }
+}
+
 const proxyPath = fileURLToPath(new URL('./codex-mcp-proxy.mjs', import.meta.url))
 
 const execFileAsync = promisify(execFile)

package/src/model-settings.mjs

@@ -48,7 +48,14 @@ export function saveModelSettings(stateDir, slug, input) {
 
 export async function listRuntimeModels(provider) {
   if (provider === 'claude') return ['sonnet', 'opus', 'haiku']
-  if (provider === 'codex') return ['gpt-5.6-sol[medium]'] // Same default as the watcher; custom IDs remain available.
+  if (provider === 'codex') {
+    try {
+      const { listAcpRuntimeModels } = await import('./mastra-harness.mjs')
+      const models = (await listAcpRuntimeModels('codex')).filter(modelId)
+      if (models.length) return models.slice(0, 1000)
+    } catch { /* keep the configured watcher default available when ACP discovery is unavailable */ }
+    return ['gpt-5.6-sol[medium]']
+  }
   if (provider !== 'opencode') return []
   const command = onPath('opencode')
   if (!command) throw problem('OpenCode is not installed on this computer.', 503)

package/src/studio-server.mjs

@@ -7,6 +7,8 @@ import { fileURLToPath } from 'node:url'
 import { isPrivateThoughtEvent, sanitizeJournalData } from './agent-journal.mjs'
 import { readModelSettings, saveModelSettings, listRuntimeModels } from './model-settings.mjs'
 import { planAgentRemoval, removeLocalAgent } from './agent-removal.mjs'
+import { controlLocalWatcher } from './watcher-control.mjs'
+import { OV_DIR } from './lib.mjs'
 
 const MAX_EVENTS = 500, MAX_FILES = 32, MAX_FILE_BYTES = 256 * 1024, MAX_TOTAL_BYTES = 4 * 1024 * 1024
 const FRESH_MS = 45_000
@@ -67,7 +69,7 @@ async function configuredAgents(stateDir) {
       const lock = await readSmallLocalFile(join(stateDir, `watch-${config.slug}.lock`), 64).catch(() => null)
       if (/^\d+\s*$/.test(lock || '')) { pid = Number(lock.trim()); watcherAlive = pidAlive(pid) }
       const identifier = backend ? config.identifier : config.slug
-      agents.push(sanitizeJournalData({ id: identifier, identifier, slug: config.slug, name: config.name || config.slug, provider: config.agent || 'claude', configured: true, removable: process.platform !== 'win32', settingsEditable: !!backend, modelSettings: backend ? readModelSettings(stateDir, config.slug) : null, runId: null, pid, watcherAlive, status: 'uninstrumented', lastSeen: null, lastEventType: null }))
+      agents.push(sanitizeJournalData({ id: identifier, identifier, slug: config.slug, name: config.name || config.slug, provider: config.agent || 'claude', configured: true, removable: process.platform !== 'win32', watcherControllable: !!backend && process.platform !== 'win32' && resolve(stateDir) === resolve(OV_DIR), settingsEditable: !!backend, modelSettings: backend ? readModelSettings(stateDir, config.slug) : null, runId: null, pid, watcherAlive, status: 'uninstrumented', lastSeen: null, lastEventType: null }))
     } catch { /* unrelated, malformed or concurrently replaced setup file */ }
   }
   return agents
@@ -120,9 +122,12 @@ export async function readStudioSnapshot({ stateDir, now = Date.now, journalCach
     const profile = profileEvent?.type === 'agent.profile' ? profileEvent.data : profileEvent?.data?.profile
     if (typeof profile?.name === 'string' && profile.name.trim()) agent.name = profile.name.trim()
     if (typeof profile?.avatarSeed === 'string' && profile.avatarSeed) agent.avatarSeed = profile.avatarSeed
-    const applied = events.findLast(event => event.agent.identifier === agent.identifier && event.runId === agent.runId && typeof event.data?.modelSettingsRevision === 'string')
+    const loaded = events.findLast(event => event.agent.identifier === agent.identifier && event.runId === agent.runId && typeof event.data?.modelSettingsRevision === 'string')
+    const applied = events.findLast(event => event.agent.identifier === agent.identifier && event.runId === agent.runId && event.type === 'models.applied' && typeof event.data?.modelSettingsRevision === 'string')
+    agent.loadedModelRevision = loaded?.data.modelSettingsRevision || ''
     agent.appliedModelRevision = applied?.data.modelSettingsRevision || ''
-    agent.modelControlsSupported = !!applied
+    agent.appliedModels = applied ? { requested: applied.data.requestedModel || '', selected: applied.data.model || '', tier: applied.data.tier || '' } : null
+    agent.modelControlsSupported = !!loaded
   }
   agents.sort((a, b) => a.name.localeCompare(b.name))
   return { schemaVersion: 1, demo: false, generatedAt: new Date(now()).toISOString(), agents, events: events.slice(-MAX_EVENTS), limits: { maxEvents: MAX_EVENTS, maxFiles: MAX_FILES, maxTotalBytes: MAX_TOTAL_BYTES }, warnings }
@@ -153,7 +158,7 @@ function demoSnapshot(stamp) {
   return { schemaVersion: 1, demo: true, generatedAt: new Date(stamp).toISOString(), agents, events: events.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp)), limits: { maxEvents: MAX_EVENTS }, warnings: ['Demo mode contains simulated agent activity. No model or task is running.'] }
 }
 
-export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4317, assetsDir = DEFAULT_ASSETS, demo = false, modelCatalog = listRuntimeModels, removeAgent = removeLocalAgent }) {
+export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4317, assetsDir = DEFAULT_ASSETS, demo = false, modelCatalog = listRuntimeModels, removeAgent = removeLocalAgent, watcherControl = controlLocalWatcher }) {
   if (!['127.0.0.1', '::1', 'localhost'].includes(host)) throw new Error('Agent Studio can bind only to a loopback address')
   if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('Agent Studio port must be an integer from 0 to 65535')
   if (!stateDir) throw new Error('Agent Studio requires a local state directory')
@@ -163,6 +168,7 @@ export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4
   const catalogs = new Map()
   const journalCache = new Map()
   const removals = new Set()
+  const watcherChanges = new Set()
   const demoState = demo ? demoSnapshot(Date.now()) : null
   let current, pending, stopped = false, interval
   const delivered = new WeakMap()
@@ -221,6 +227,32 @@ export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4
         }
         return
       }
+      const watcherRoute = /^\/api\/agents\/([a-z0-9][a-z0-9_-]{0,79})\/watcher$/i.exec(path)
+      if (watcherRoute && !demo) {
+        const slug = watcherRoute[1]
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        try {
+          if (req.method !== 'POST') { res.writeHead(405); res.end(JSON.stringify({ error: 'Method not allowed' })); return }
+          if (req.headers.origin !== `http://${req.headers.host}` || req.headers['content-type']?.split(';')[0] !== 'application/json') throw Object.assign(new Error('Use the local Studio page to control a watcher.'), { status: 403 })
+          let body = ''
+          for await (const chunk of req) { body += chunk; if (Buffer.byteLength(body) > 1024) throw Object.assign(new Error('Watcher request is too large.'), { status: 413 }) }
+          let input
+          try { input = JSON.parse(body) } catch { throw Object.assign(new Error('Invalid watcher request.'), { status: 400 }) }
+          if (!input || !['start', 'stop', 'restart'].includes(input.action)) throw Object.assign(new Error('Choose start, stop, or restart.'), { status: 400 })
+          if (watcherChanges.has(slug)) throw Object.assign(new Error('This watcher is already changing state.'), { status: 409 })
+          watcherChanges.add(slug)
+          try {
+            const result = await watcherControl({ stateDir, slug, action: input.action })
+            journalCache.clear()
+            current = null
+            res.end(JSON.stringify(result))
+          } finally { watcherChanges.delete(slug) }
+        } catch (error) {
+          res.writeHead(error.status || 503)
+          res.end(JSON.stringify({ error: error.status ? error.message : `Could not control this watcher: ${error.message || error}` }))
+        }
+        return
+      }
       const settingsRoute = /^\/api\/agents\/([a-z0-9][a-z0-9_-]{0,79})\/(models|settings)$/i.exec(path)
       if (settingsRoute && !demo) {
         const [, slug, action] = settingsRoute

package/src/team-data.mjs

@@ -0,0 +1,41 @@
+const COLLECTIONS = {
+  list_agents: ['agents', 'name'],
+  list_boards: ['boards', 'name'],
+  list_channels: ['channels', 'name'],
+  list_projects: ['projects', 'name'],
+  list_tasks: ['tasks', 'title'],
+  list_task_types: ['types', 'name'],
+}
+
+function markdownRows(markdown, labelKey) {
+  if (typeof markdown !== 'string') return []
+  const rows = []
+  for (const line of markdown.split(/\r?\n/)) {
+    const match = /^\s*-\s+`(#?\d+)`(?:\s+(.+?))?\s*$/.exec(line)
+    if (!match) continue
+    const id = Number(match[1].replace(/^#/, ''))
+    if (!Number.isSafeInteger(id) || id <= 0) continue
+    rows.push({ id, [labelKey]: String(match[2] || '').trim() })
+  }
+  return rows
+}
+
+function normalizeCollection(data, toolName) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return data
+  const collection = COLLECTIONS[toolName]
+  if (!collection) return data
+  const [key, labelKey] = collection
+  if (Array.isArray(data[key])) return data
+  const rows = markdownRows(data.markdown, labelKey)
+  return { ...data, [key]: rows }
+}
+
+// Team tools may return either structured arrays or a compact JSON envelope
+// containing Markdown rows. Normalize that transport difference here so every
+// runtime provider uses the same watcher discovery path.
+export function toolData(result, toolName = '') {
+  const text = result?.content?.find?.((item) => item?.type === 'text')?.text
+  if (typeof text !== 'string') return normalizeCollection(result?.structuredContent ?? result ?? {}, toolName)
+  try { return normalizeCollection(JSON.parse(text), toolName) }
+  catch { return normalizeCollection(result?.structuredContent ?? { text }, toolName) }
+}

package/src/watch.mjs

@@ -36,6 +36,7 @@ import { claudeFallbackModels, resolveClaudeModel } from './model-selection.mjs'
 import { createAgentJournal } from './agent-journal.mjs'
 import { readModelSettings } from './model-settings.mjs'
 import { startStudioInBackground } from './studio-cli.mjs'
+import { toolData } from './team-data.mjs'
 
 function runtimeJournal(options, supplied) {
   let journal
@@ -325,7 +326,7 @@ export async function runWatch({ flags }) {
     assertWebSocket(fail)
     if (flags.install) return installService({ slug: slug || 'openvisio', claude, mcpConfig, workdir })
     startStudioInBackground()
-    return loopBackendWs({ backend, wsUrl, apiKey, identifier, slug: slug || 'openvisio', claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug: !!flags.debug })
+    return loopBackendWs({ backend, wsUrl, apiKey, identifier, slug: slug || 'openvisio', name: String(saved?.name || slug || identifier), claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug: !!flags.debug })
   }
 
   const host = stripSlash(flags.host || (saved && saved.host) || '')
@@ -594,7 +595,7 @@ function loopBackendWs(options) {
 
 // Production orchestration with replaceable I/O boundaries for deterministic
 // workspace simulations. Tests run this same routing, queue and delivery code.
-export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug, claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug }, dependencies = {}) {
+export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug, name, claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug }, dependencies = {}) {
   const validBackendId = (value) => value != null && /^\d+$/.test(String(value)) && Number.isSafeInteger(Number(value)) && Number(value) > 0
   const stateDir = dependencies.stateDir || OV_DIR
   const makeRunner = dependencies.createRunner || createCycleRunner
@@ -896,9 +897,15 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   let identityContext = memory.get?.(`identity:${identifier}`)?.meta?.context || agentProfileContext({}, identifier)
   let agentAppearance = memory.get?.(`identity:${identifier}`)?.meta?.appearance || null
   if (agentAppearance) emit('agent.profile', agentAppearance)
-  const selfAliases = new Set([slug, identifier].map((value) => String(value || '').toLowerCase()).filter(Boolean))
+  // The saved display name is authoritative recipient context even when an older
+  // MCP server returns list_agents as human-readable markdown without identifiers.
+  const selfAliases = new Set([slug, name, identifier].map((value) => String(value || '').trim().toLowerCase()).filter(Boolean))
   const rememberSelfAgent = (self) => {
-    if (!self || typeof self !== 'object' || String(self.identifier || self.slug || '') !== identifier) return
+    if (!self || typeof self !== 'object') return
+    const declaredIdentifier = String(self.identifier || self.slug || '')
+    const matchesIdentifier = declaredIdentifier === identifier
+    const matchesSavedName = !declaredIdentifier && String(name || '').trim() && String(self.name || '').trim().toLowerCase() === String(name).trim().toLowerCase()
+    if (!matchesIdentifier && !matchesSavedName) return
     if (validBackendId(self.id)) selfAgentId = Number(self.id)
     for (const alias of [self.name, self.identifier, self.slug]) if (alias) selfAliases.add(String(alias).toLowerCase())
     identityContext = agentProfileContext(self, identifier)
@@ -931,8 +938,11 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   const ensureSelfAgent = async () => {
     if (selfAgentId != null) return
     if (!selfRead && Date.now() < selfReadAfter) return
-    if (!selfRead) selfRead = callMcpTool('list_agents').then(toolData).then((data) => {
-      const self = (Array.isArray(data.agents) ? data.agents : []).find((row) => String(row?.identifier || row?.slug || '') === identifier)
+    if (!selfRead) selfRead = callMcpTool('list_agents').then((result) => toolData(result, 'list_agents')).then((data) => {
+      const agents = Array.isArray(data.agents) ? data.agents : []
+      const identified = agents.find((row) => String(row?.identifier || row?.slug || '') === identifier)
+      const named = agents.filter((row) => !row?.identifier && !row?.slug && String(row?.name || '').trim().toLowerCase() === String(name || '').trim().toLowerCase())
+      const self = identified || (named.length === 1 ? named[0] : null)
       rememberSelfAgent(self)
     }).catch((error) => {
       log('Agent profile unavailable; continuing with task ownership and configured aliases: ' + (error?.message || error))
@@ -987,13 +997,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     }
   }
   if (mcpUrl) void discoverMcpTools().catch(() => {})
-  const toolData = (result) => {
-    const text = result?.content?.find?.((c) => c?.type === 'text')?.text
-    if (typeof text !== 'string') return result?.structuredContent ?? result ?? {}
-    try { return JSON.parse(text) } catch { return { text } }
-  }
-
-  const taskTypeSets = createTaskTypeLookup({ load: (projectId) => loadProjectTaskTypes({ projectId, listTools: () => mcpClient.listTools(), callTool: (name, args) => callMcpTool(name, args).then(toolData) }) })
+  const taskTypeSets = createTaskTypeLookup({ load: (projectId) => loadProjectTaskTypes({ projectId, listTools: () => mcpClient.listTools(), callTool: (name, args) => callMcpTool(name, args).then((result) => toolData(result, name)) }) })
 
   const callMcpReadWithRetry = async (name, args = {}) => {
     try { return await callMcpTool(name, args) }
@@ -1004,21 +1008,21 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   }
 
   const loadPendingTickets = async () => {
-    const projectsData = toolData(await callMcpReadWithRetry('list_projects'))
+    const projectsData = toolData(await callMcpReadWithRetry('list_projects'), 'list_projects')
     const projects = Array.isArray(projectsData.projects) ? projectsData.projects : []
     const groups = await mapConcurrent(projects.filter((project) => project?.id != null), 3, async (project) => {
       const [tasksResult, typesResult] = await Promise.all([
         callMcpReadWithRetry('list_tasks', { project_id: project.id }),
         taskTypeSets(project.id),
       ])
-      const tasksData = toolData(tasksResult)
+      const tasksData = toolData(tasksResult, 'list_tasks')
       const { done: doneIds, review: reviewIds } = typesResult
       const tasks = await mapConcurrent(Array.isArray(tasksData.tasks) ? tasksData.tasks : [], 3, async (task) => {
         await resolveTaskOwner(task)
         if (ticketDisplaySlug(task) || task?.id == null || !taskBelongsToAgent(task, { id: selfAgentId, identifier })) return task
         // Some list responses omit the board slug. Resolve details by the real
         // database identity; never interpret the number in OPEN-105 as an id.
-        const data = toolData(await callMcpReadWithRetry('get_ticket', { project_id: project.id, ticket_id: task.id }))
+        const data = toolData(await callMcpReadWithRetry('get_ticket', { project_id: project.id, ticket_id: task.id }), 'get_ticket')
         const detail = data.ticket ?? data.task ?? data
         if (String(detail.id) !== String(task.id) || (detail.project_id != null && String(detail.project_id) !== String(project.id))) throw new Error('Ticket detail identity did not match its assignment.')
         return detail
@@ -1236,7 +1240,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     dedicatedChannelRead = (async () => {
       try {
         await ensureSelfAgent()
-        const data = toolData(await callMcpTool('list_channels'))
+        const data = toolData(await callMcpTool('list_channels'), 'list_channels')
         const channels = data.channels ?? data.data?.channels ?? data.data ?? data.items ?? []
         const channel = dedicatedChannel(Array.isArray(channels) ? channels : [], { id: selfAgentId, identifier, aliases: [...selfAliases], channelId: readConfig(slug)?.dedicatedChannelId })
         const channelId = channel ? Number(channel.id) : null
@@ -1252,7 +1256,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   }
 
   const announceIntroduction = async () => {
-    const projectsData = toolData(await callMcpTool('list_projects'))
+    const projectsData = toolData(await callMcpTool('list_projects'), 'list_projects')
     const projects = Array.isArray(projectsData.projects) ? projectsData.projects : []
     const project = projects.find((item) => Number.isFinite(Number(item.id)))
     if (!project) { log('no project available for first-connection introduction'); return false }
@@ -1421,7 +1425,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     if (!mcpUrl || backlogProbeBusy) return
     backlogProbeBusy = true
     try {
-      const projectsData = toolData(await callMcpTool('list_projects'))
+      const projectsData = toolData(await callMcpTool('list_projects'), 'list_projects')
       const projects = Array.isArray(projectsData.projects) ? projectsData.projects : []
       const mentionActivity = []
       let activityReplayTouched = false
@@ -1429,7 +1433,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
         try {
           const assigned = []
           const [tasksData, typesData] = await Promise.all([
-            callMcpTool('list_tasks', { project_id: project.id }).then(toolData),
+            callMcpTool('list_tasks', { project_id: project.id }).then((result) => toolData(result, 'list_tasks')),
             taskTypeSets(project.id),
           ])
           const { done: doneIds, review: reviewIds } = typesData
@@ -1681,6 +1685,9 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       cycleControl.outcome = 'running'
       log(`cycle timing preflight=${Math.round(performance.now() - cycleStartedAt)}ms kind=${kind}`)
       const result = await runner.runCycle(prompt, useModel, runnerOptions)
+      if (result?.model) {
+        emit('models.applied', { requestedModel: useModel, model: result.model, tier: kind === 'full' ? 'coding' : 'reply', modelSettingsRevision: cycleModelRevision })
+      }
       await cycleControl.planDelivery
       cycleControl.outcome = result?.is_error ? 'error' : result?.subtype || 'error'
       if (result?.timings) log(`cycle timing runtime=${JSON.stringify(result.timings)} kind=${kind}`)
@@ -2192,7 +2199,9 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     // supported MCP tools directly, stays silent when empty, and hands verified
     // coding tasks to the full lane instead of letting Luna announce it cannot code.
     taskProbeStartTimer = setTimeout(() => void reconcileBacklog(), 3_000)
-    taskProbeTimer = setInterval(() => void reconcileBacklog(), 5 * 60 * 1000)
+    // WebSocket delivery is primary. A short bounded reconciliation interval
+    // keeps mentions responsive when a deployment omits targeted dispatch.
+    taskProbeTimer = setInterval(() => void reconcileBacklog(), 30_000)
   } else {
     log('no MCP config — skipping intro + daily sweep (agent has no tools to post/act)')
   }
@@ -2387,8 +2396,13 @@ function loop({ host, key, slug, claude, agent, mcpConfig, mcpUrl, workdir, mode
 // ── background service install (launchd / systemd) ───────────────────────────
 /** Stop the auto-restarting service first, then every orphaned watcher whose
  *  --name resolves to this exact slug. Never use a broad pkill pattern. */
-export function stopWatchers({ slug, quiet = false }) {
+export function stopWatchers({ slug, quiet = false, stateDir = OV_DIR, throwOnError = false }) {
   const key = slugify(slug || 'openvisio')
+  const abort = (message) => {
+    if (throwOnError) throw new Error(message)
+    fail(message)
+  }
+  if (stateDir !== OV_DIR) abort('Watcher control is supported only in this computer’s agent storage.')
   let serviceStopped = false
 
   if (process.platform === 'darwin') {
@@ -2426,35 +2440,41 @@ export function stopWatchers({ slug, quiet = false }) {
   if (stubborn.length) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 150)
 
   const remaining = watcherPids()
-  if (remaining.length) fail(`Could not stop watcher${remaining.length === 1 ? '' : 's'} for "${key}": ${remaining.join(', ')}`)
-  try { unlinkSync(join(OV_DIR, `watch-${key}.lock`)) } catch { /* absent */ }
+  if (remaining.length) abort(`Could not stop watcher${remaining.length === 1 ? '' : 's'} for "${key}": ${remaining.join(', ')}`)
+  try { unlinkSync(join(stateDir, `watch-${key}.lock`)) } catch { /* absent */ }
   if (!quiet) ok(`Stopped ${found.length} watcher process${found.length === 1 ? '' : 'es'} for "${key}"${serviceStopped ? ' and disabled its background service' : ''}.`)
   return { stopped: found.length, serviceStopped }
 }
 
-export function installService({ slug, workdir }) {
+export function installService({ slug, workdir, stateDir = OV_DIR, serviceCommand, throwOnError = false }) {
+  const abort = (message) => {
+    if (throwOnError) throw new Error(message)
+    fail(message)
+  }
+  if (stateDir !== OV_DIR) abort('Watcher control is supported only in this computer’s agent storage.')
   // Replacing a service must also remove manually-started watchers. Otherwise the
   // new KeepAlive process repeatedly spawns, sees their lock, exits, and respawns.
-  stopWatchers({ slug, quiet: true })
-  const binPath = onPath('openvisio-agent')
-  if (!binPath || binPath.includes('/_npx/')) {
+  stopWatchers({ slug, quiet: true, stateDir, throwOnError })
+  const suppliedCommand = Array.isArray(serviceCommand) && serviceCommand.length ? serviceCommand.map(String) : null
+  const binPath = suppliedCommand ? suppliedCommand[0] : onPath('openvisio-agent')
+  if (!suppliedCommand && (!binPath || binPath.includes('/_npx/'))) {
     info('Installing openvisio-agent globally so the background service has a stable path…')
     spawnSync('npm', ['i', '-g', 'openvisio-agent'], { stdio: 'inherit', shell: process.platform === 'win32' })
   }
-  const bin = onPath('openvisio-agent') || 'openvisio-agent'
+  const command = suppliedCommand || [onPath('openvisio-agent') || 'openvisio-agent']
   const nodeDir = dirname(process.execPath)
   const claudeBin = onPath('claude')
   const opencodeBin = onPath('opencode')
   const codexBin = onPath('codex')
   const runPath = [nodeDir, claudeBin ? dirname(claudeBin) : '', codexBin ? dirname(codexBin) : '', opencodeBin ? dirname(opencodeBin) : '', join(homedir(), '.opencode', 'bin'), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin'].filter(Boolean).join(':')
   const args = ['watch', '--name', slug, ...(workdir ? ['--workdir', workdir] : [])]
-  mkdirSync(OV_DIR, { recursive: true })
-  const logFile = join(OV_DIR, `${slug}.log`)
+  mkdirSync(stateDir, { recursive: true })
+  const logFile = join(stateDir, `${slug}.log`)
 
   if (process.platform === 'darwin') {
     const label = `io.openvisio.${slug}`
     const plist = join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`)
-    const progArgs = [bin, ...args].map((a) => `    <string>${a}</string>`).join('\n')
+    const progArgs = [...command, ...args].map((a) => `    <string>${a}</string>`).join('\n')
     writeFileSync(plist, `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0"><dict>
@@ -2471,15 +2491,16 @@ ${progArgs}
 `)
     spawnSync('launchctl', ['unload', plist], { stdio: 'ignore' })
     const r = spawnSync('launchctl', ['load', plist], { stdio: 'inherit' })
-    if (r.status !== 0) fail('launchctl load failed — check the plist at ' + plist)
+    if (r.status !== 0) abort('launchctl load failed — check the plist at ' + plist)
     ok(`Live in the background, auto-starts at login. Logs:  tail -f ${logFile}`)
+    return { running: true, service: 'launchd', slug }
   } else if (process.platform === 'win32') {
-    fail('Background install isn\'t supported on Windows yet. Run it in the foreground:\n  openvisio-agent watch --name ' + slug)
+    abort('Background install isn\'t supported on Windows yet. Run it in the foreground:\n  openvisio-agent watch --name ' + slug)
   } else {
     const dir = join(homedir(), '.config', 'systemd', 'user')
     mkdirSync(dir, { recursive: true })
     const unit = join(dir, `openvisio-${slug}.service`)
-    const execStart = [bin, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')
+    const execStart = [...command, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')
     writeFileSync(unit, `[Unit]
 Description=OpenVisio agent watcher (${slug})
 After=network-online.target
@@ -2496,7 +2517,8 @@ WantedBy=default.target
     spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' })
     const r = spawnSync('systemctl', ['--user', 'enable', '--now', `openvisio-${slug}.service`], { stdio: 'inherit' })
     spawnSync('loginctl', ['enable-linger', process.env.USER || ''], { stdio: 'ignore' })
-    if (r.status !== 0) fail('systemctl enable failed — is this a systemd user session?')
+    if (r.status !== 0) abort('systemctl enable failed — is this a systemd user session?')
     ok(`Live in the background, auto-starts at login. Logs:  journalctl --user -u openvisio-${slug} -f`)
+    return { running: true, service: 'systemd', slug }
   }
 }

package/src/watcher-control.mjs

@@ -0,0 +1,39 @@
+import { constants, closeSync, fstatSync, openSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { OV_DIR, slugify } from './lib.mjs'
+import { installService, stopWatchers } from './watch.mjs'
+
+const problem = (message, status = 400) => Object.assign(new Error(message), { status })
+
+function localConfig(stateDir, slug) {
+  if (resolve(stateDir) !== resolve(OV_DIR)) throw problem('Watcher control is supported only in this computer’s agent storage.', 403)
+  if (slugify(slug) !== slug) throw problem('Invalid agent.', 404)
+  const fd = openSync(join(stateDir, `${slug}.json`), constants.O_RDONLY | (constants.O_NOFOLLOW || 0))
+  try {
+    const stat = fstatSync(fd)
+    if (!stat.isFile() || stat.size > 64 * 1024) throw problem('Agent settings are unavailable.', 404)
+    const config = JSON.parse(readFileSync(fd, 'utf8'))
+    if (config.slug !== slug || config.mode !== 'backend' || !config.identifier || !config.apiKey) throw problem('This agent does not support watcher control.', 404)
+    return config
+  } finally { closeSync(fd) }
+}
+
+export async function controlLocalWatcher({ stateDir, slug, action }) {
+  const config = localConfig(stateDir, slug)
+  if (!['start', 'stop', 'restart'].includes(action)) throw problem('Choose start, stop, or restart.')
+  if (process.platform === 'win32') throw problem('Watcher control is not available on Windows yet.', 501)
+  if (action === 'stop') {
+    const result = stopWatchers({ slug, quiet: true, stateDir, throwOnError: true })
+    return { action, slug, running: false, ...result }
+  }
+  const cli = fileURLToPath(new URL('../bin/cli.mjs', import.meta.url))
+  const result = installService({
+    slug,
+    workdir: config.chatOnly ? '' : config.workspace || config.workdir || '',
+    stateDir,
+    serviceCommand: [process.execPath, cli],
+    throwOnError: true,
+  })
+  return { action, slug, ...result }
+}

package/studio/app.mjs

@@ -260,6 +260,7 @@ function initializeStudio() {
   let launchSettings = launch.get('settings') === '1';
   let editingAgent = null, editingSettings = null, settingsRequest = 0;
   let removalPlan = null, removalRequest = 0, removing = false;
+  let watcherChanging = false;
   const state = {
     snapshot: null, model: null, pending: null, paused: false, connected: false,
     selectedAgent: launch.get('agent') || 'all', agentSearch: '', search: '', kind: 'all', status: 'all',
@@ -391,12 +392,21 @@ function initializeStudio() {
     $('model-settings-agent').textContent = `${agentName(agent)} · Models`;
     $('open-model-settings').disabled = !agent.settingsEditable;
     $('open-agent-removal').disabled = !agent.removable;
+    const watcherRunning = agent.status === 'online' || agent.watcherAlive === true;
+    $('toggle-watcher').textContent = watcherRunning ? 'Stop watcher' : 'Start watcher';
+    $('toggle-watcher').dataset.action = watcherRunning ? 'stop' : 'start';
+    $('toggle-watcher').disabled = watcherChanging || !agent.watcherControllable;
+    $('restart-watcher').disabled = watcherChanging || !agent.watcherControllable;
+    const watcherTitle = agent.watcherControllable ? '' : 'Watcher control is available for local backend agents on macOS and Linux.';
+    $('toggle-watcher').title = watcherTitle;
+    $('restart-watcher').title = watcherTitle;
     $('open-agent-removal').title = agent.removable == null ? 'Restart Agent Studio with the updated openvisio-agent package to enable removal.' : !agent.removable ? 'Automatic removal is unavailable on this platform.' : '';
     const settings = agent.modelSettings || {};
     const pending = settings.revision && agent.appliedModelRevision !== settings.revision;
+    const selected = agent.appliedModels?.selected;
     $('model-settings-state').textContent = !agent.settingsEditable ? 'Model controls are available for agents configured on this computer.'
-      : pending ? agent.modelControlsSupported && agent.status === 'online' ? 'Saved · waiting for the watcher to apply your choices.' : 'Saved for the next watcher connection. Older watchers need an update to apply changes live.'
-      : `Replies: ${settings.chatModel || settings.model || 'Runtime default'} · Coding: ${settings.model || 'Runtime default'}`;
+      : pending ? agent.loadedModelRevision === settings.revision ? 'Saved · the watcher loaded your choices and will apply them to the next request.' : 'Saved for the next watcher connection.'
+      : `Replies: ${settings.chatModel || settings.model || 'Runtime default'} · Coding: ${settings.model || 'Runtime default'}${selected ? ` · Runtime applied: ${selected}` : ''}`;
     if (agent.removable == null) $('model-settings-state').textContent += ' Restart Agent Studio with the updated package to enable agent removal.';
     if (launchSettings && agent.settingsEditable) { launchSettings = false; void openModelSettings(agent); }
   }
@@ -879,6 +889,26 @@ function initializeStudio() {
       if (request === settingsRequest) { $('model-settings-error').hidden = false; $('model-settings-error').textContent = error.message; }
     } finally { $('save-model-settings').disabled = false; $('save-model-settings').textContent = 'Save models'; }
   });
+  async function changeWatcher(action) {
+    const agent = state.model.agents.find(agent => agentId(agent) === state.selectedAgent);
+    if (!agent || watcherChanging || !agent.watcherControllable) return;
+    watcherChanging = true;
+    scheduleRender();
+    try {
+      await settingsFetch(`/api/agents/${encodeURIComponent(agent.slug)}/watcher`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ action }) });
+      await new Promise(resolve => setTimeout(resolve, 500));
+      receive(await settingsFetch('/api/snapshot'), true);
+      toast(action === 'stop' ? 'Watcher stopped.' : action === 'restart' ? 'Watcher restarted with the current models.' : 'Watcher started with the current models.');
+    } catch (error) {
+      state.error = error.message;
+      scheduleRender();
+    } finally {
+      watcherChanging = false;
+      scheduleRender();
+    }
+  }
+  $('toggle-watcher').addEventListener('click', () => void changeWatcher($('toggle-watcher').dataset.action || 'start'));
+  $('restart-watcher').addEventListener('click', () => void changeWatcher('restart'));
   $('pause-button').addEventListener('click', () => {
     state.paused = !state.paused;
     syncConnection();

package/studio/guide.html

@@ -45,7 +45,7 @@
           <section id="models">
             <h2>Change models</h2>
             <p>Select an agent in the sidebar, choose <strong>Model settings</strong>, select its reply and coding models, then choose <strong>Save models</strong>. Model fields let you search the runtime’s choices or enter a custom model ID.</p>
-            <p>Updated watchers apply saved choices to the next request without a restart. Work already running continues with its original model. Studio shows when a save is waiting for the watcher. Offline agents retain the selection for their next connection; older watchers need an update to apply changes live.</p>
+            <p>Updated watchers load saved choices immediately and apply them to the next request without a restart. Work already running continues with its original model. After a request starts, Studio shows the model the runtime actually selected. Offline agents retain the selection for their next connection.</p>
             <p>OpenCode choices come from its local model catalog. Listing a model does not guarantee credentials or available quota. If a model is rate-limited, choose one with available quota or retry after the provider’s limit resets.</p>
             <p>Studio controls agents configured on this computer. An agent running on another teammate’s computer must be managed there.</p>
           </section>
@@ -59,11 +59,11 @@
             <p>A <strong>watcher</strong> is the local program that listens for assignments and messages, then starts your coding agent when work arrives. Studio displays what the watcher records.</p>
             <ol>
               <li>Connect your agent using the setup command provided by your OpenVisio team. If you already connected it, keep that setup.</li>
-              <li>In a separate terminal, start its watcher. Replace <code>ada</code> with the name used during setup:<pre><code>openvisio-agent watch --name ada</code></pre></li>
+              <li>Select the agent in Studio and choose <strong>Start watcher</strong>. Studio installs its background watcher and starts it with the current package and saved model settings.</li>
               <li>Return to Studio. Your agent should appear in the sidebar. Select its name to see its activity.</li>
             </ol>
-            <p>Starting a watcher enables it to act on existing assignments and messages. If your watcher is already running, you do not need to start another one.</p>
-            <p>Older watchers need a Studio-capable update and a restart before they record activity. Their earlier activity cannot be reconstructed. See <a href="#troubleshooting">restart instructions</a> below.</p>
+            <p>Use <strong>Stop watcher</strong> to take an agent offline and <strong>Restart watcher</strong> after changing its runtime installation or troubleshooting a connection. Restarting preserves its configuration and model choices.</p>
+            <p>Watcher controls are available for backend agents in the default local agent storage on macOS and Linux. Their earlier activity cannot be reconstructed.</p>
           </section>
           <section id="find-work">
             <h2>Find and inspect work</h2>

package/studio/index.html

@@ -61,7 +61,7 @@
         <div id="notice" class="notice" role="status" hidden></div>
         <section id="model-settings-summary" class="model-settings-summary" aria-label="Agent model settings" hidden>
           <div><h2 id="model-settings-agent">Model settings</h2><p id="model-settings-state" role="status"></p></div>
-          <div class="header-actions"><button id="open-model-settings" class="button" type="button">Model settings</button><button id="open-agent-removal" class="button" type="button">Remove from computer</button></div>
+          <div class="header-actions"><button id="toggle-watcher" class="button" type="button">Start watcher</button><button id="restart-watcher" class="button" type="button">Restart watcher</button><button id="open-model-settings" class="button" type="button">Model settings</button><button id="open-agent-removal" class="button" type="button">Remove from computer</button></div>
         </section>
         <dialog id="model-settings-dialog" aria-labelledby="model-settings-title">
           <form id="model-settings-form" class="model-settings-form">