openvisio-agent 0.25.0 → 0.25.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [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.
+- Stop surviving watcher descendants before deleting agent data, preserve shared Studio processes, and explain when an older Studio needs restarting to enable removal.
+
 ## [0.25.0] — 2026-09-18
 
 - Reduce Studio journal-processing CPU by caching unchanged files, refreshing every two seconds, and disconnecting hidden or paused views.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "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,21 +16,22 @@ 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' }
   let watcher, connection, messageId = 100, closed = 0
   const memory = createByoMemoryGraph({ path: join(dir, 'ledger.json') })
   const mcp = {
-    listTools: async () => ['list_agents', 'list_projects', 'list_tasks', 'get_ticket', 'update_ticket', 'post_message', 'list_message_thread', 'list_channels', 'list_task_types', 'list_activity', ...commentTools].map((name) => ({ name })),
+    listTools: async () => ['list_agents', 'list_projects', 'list_boards', 'list_tasks', 'get_ticket', 'update_ticket', 'post_message', 'list_message_thread', 'list_channels', 'list_task_types', 'list_activity', ...commentTools].map((name) => ({ name, ...(name === 'list_task_types' ? { inputSchema: { required: ['project_id', 'board_id'], properties: { project_id: {}, board_id: {} } } } : {}) })),
     callTool: async (name, args = {}) => {
       calls.push({ name, args })
       if (commentTools.includes(name)) return onComment ? await onComment(name, args) : { id: 500 }
       if (name === 'list_agents') return listAgents ? await listAgents() : { agents: [selfProfile] }
       if (name === 'list_projects') return { projects: [{ id: 1, name: 'Workspace' }] }
       if (name === 'list_tasks') return { tasks: task ? [{ ...ticket }] : [] }
-      if (name === 'list_task_types') return { types: [{ id: 1, name: 'In Progress' }, { id: 2, name: 'Testing' }, { id: 3, name: 'Done' }] }
+      if (name === 'list_boards') return { boards: [{ id: 4 }] }
+      if (name === 'list_task_types') { assert.equal(args.board_id, 4); return { types: [{ id: 1, name: 'In Progress' }, { id: 2, name: 'Testing' }, { id: 3, name: 'Done' }] } }
       if (name === 'get_ticket') { assert.equal(args.project_id, 1); assert.equal(args.ticket_id, 77); return { ticket: getTicket ? getTicket(ticket) : { ...ticket } } }
       if (name === 'update_ticket') { Object.assign(ticket, args); return { ticket: { ...ticket } } }
       if (name === 'list_channels' && listChannels) return { channels: await listChannels() }
@@ -70,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/agent-processes.mjs

@@ -0,0 +1,46 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { setTimeout as delay } from 'node:timers/promises'
+
+const exec = promisify(execFile)
+export async function agentProcessSnapshot() {
+  const { stdout } = await exec('ps', ['-axo', 'pid=,ppid=,stat=,command='], { maxBuffer: 4 * 1024 * 1024 })
+  return stdout.split('\n').flatMap(line => {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/.exec(line)
+    return match && !match[3].startsWith('Z') ? [{ pid: Number(match[1]), parent: Number(match[2]), command: match[4] }] : []
+  })
+}
+
+export function agentProcessTree(rows, slug) {
+  const selected = new Map()
+  for (const row of rows) {
+    const name = /(?:^|\s)--name(?:=|\s+)["']?([^"'\s]+)/.exec(row.command)?.[1]
+    if (/\bopenvisio-agent\b/.test(row.command) && /\bwatch\b/.test(row.command) && name === slug) selected.set(row.pid, row)
+  }
+  let added
+  do {
+    added = false
+    for (const row of rows) {
+      // Studio is shared by all agents, even when a watcher launched it.
+      if (selected.has(row.pid) || !selected.has(row.parent) || /\bcli\.mjs\s+studio\b/.test(row.command)) continue
+      selected.set(row.pid, row); added = true
+    }
+  } while (added)
+  return [...selected.values()]
+}
+
+export async function stopAgentProcessTree(captured, { snapshot = agentProcessSnapshot, signal = process.kill.bind(process), wait = delay } = {}) {
+  const remaining = async () => (await snapshot()).filter(row => captured.some(old => old.pid === row.pid && old.command === row.command))
+  for (const name of ['SIGTERM', 'SIGKILL']) {
+    const rows = await remaining()
+    if (!rows.length) return
+    for (const row of rows.reverse()) {
+      try { signal(row.pid, name) } catch (error) { if (error.code !== 'ESRCH') throw error }
+    }
+    for (let attempt = 0; attempt < 20; attempt++) {
+      await wait(100)
+      if (!(await remaining()).length) return
+    }
+  }
+  throw new Error('Agent processes are still running. Local data has been kept; retry removal after they stop.')
+}

package/src/agent-removal.mjs

@@ -7,6 +7,7 @@ import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { OV_DIR, slugify } from './lib.mjs'
+import { agentProcessSnapshot, agentProcessTree, stopAgentProcessTree } from './agent-processes.mjs'
 
 const exec = promisify(execFile)
 const hash = value => createHash('sha256').update(value).digest('hex')
@@ -74,8 +75,13 @@ async function stopLocalAgent({ stateDir, slug }) {
   if (resolve(stateDir) !== resolve(OV_DIR)) throw problem('Stopping agents is supported only in this computer’s agent storage.')
   if (slugify(slug) !== slug) throw problem('This legacy local name cannot be stopped safely from Studio.')
   if (process.platform === 'win32') throw problem('Stop the watcher manually before removal on Windows; automatic removal is not supported yet.')
+  // Capture children before unloading the service, which can orphan runtimes.
+  // A stale lock PID is not proof of ownership and must never target another app.
+  const rows = await agentProcessSnapshot()
+  const captured = agentProcessTree(rows, slug)
   const lock = await readFile(join(stateDir, `watch-${slug}.lock`), 'utf8').catch(() => '')
-  const pid = /^\d+\s*$/.test(lock) ? Number(lock.trim()) : null
+  const lockedPid = /^\d+\s*$/.test(lock) ? Number(lock.trim()) : null
+  if (rows.some(row => row.pid === lockedPid) && !captured.some(row => row.pid === lockedPid)) throw problem('The recorded watcher uses an unrecognized command. Stop it before removing its data.')
   const service = process.platform === 'darwin'
     ? join(homedir(), 'Library', 'LaunchAgents', `io.openvisio.${slug}.plist`)
     : join(homedir(), '.config', 'systemd', 'user', `openvisio-${slug}.service`)
@@ -83,11 +89,8 @@ async function stopLocalAgent({ stateDir, slug }) {
     await exec('systemctl', ['--user', 'disable', '--now', `openvisio-${slug}.service`], { timeout: 15000 })
   }
   await exec(process.execPath, [fileURLToPath(new URL('../bin/cli.mjs', import.meta.url)), 'stop', '--name', slug], { timeout: 20000, maxBuffer: 65536 })
-  if (Number.isSafeInteger(pid) && pid > 0) {
-    let alive = false
-    try { process.kill(pid, 0); alive = true } catch (error) { alive = error.code === 'EPERM' }
-    if (alive) throw problem('The recorded watcher process is still running. Stop it before removing its data.')
-  }
+  await stopAgentProcessTree(captured)
+  if (agentProcessTree(await agentProcessSnapshot(), slug).length) throw problem('The watcher restarted. Stop its background service before removing data.')
   if (process.platform === 'darwin') {
     const loaded = await exec('launchctl', ['print', `gui/${process.getuid()}/io.openvisio.${slug}`], { timeout: 5000 }).then(() => true, () => false)
     if (loaded) throw problem('The background service is still loaded. Stop it before removing the agent.')

package/src/mastra-harness.mjs

@@ -12,7 +12,7 @@ import { opencodeProviderFailure } from './opencode-failure.mjs'
 import { isTransportInterruption } from './transport-recovery.mjs'
 
 const MCP_TOOL_NAMES = [
-  WORK_SESSION_TOOL, ...contextToolNames, 'list_agents', 'list_projects', 'list_tasks', 'list_task_types', 'get_ticket',
+  WORK_SESSION_TOOL, ...contextToolNames, 'list_agents', 'list_projects', 'list_boards', 'list_tasks', 'list_task_types', 'get_ticket',
   'create_ticket', 'update_ticket', 'list_channels', 'list_message_thread', 'list_activity',
   'post_message', 'react_message', 'list_codebases', 'get_codebase',
   'codebase_tree', 'create_codebase_branch', 'create_codebase_commit',
@@ -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/task-types.mjs

@@ -1,3 +1,21 @@
+export async function loadProjectTaskTypes({ projectId, listTools, callTool }) {
+  const tools = await listTools()
+  const tool = tools.find(tool => tool.name === 'list_task_types')
+  const schema = tool?.inputSchema || tool?.input_schema
+  if (!schema?.properties?.board_id && !schema?.required?.includes('board_id')) return callTool('list_task_types', { project_id: projectId })
+  const result = await callTool('list_boards', { project_id: projectId })
+  if (!Array.isArray(result?.boards)) throw new Error('Cannot verify project boards')
+  const types = []
+  for (const board of result.boards) {
+    if (board?.id == null) throw new Error('Cannot verify board identity')
+    const data = await callTool('list_task_types', { project_id: projectId, board_id: board.id })
+    const rows = data?.types ?? data?.task_types ?? data?.taskTypes
+    if (!Array.isArray(rows)) throw new Error('Cannot verify task columns')
+    types.push(...rows)
+  }
+  return { types }
+}
+
 export function createTaskTypeLookup({ load, now = Date.now, ttlMs = 60_000 }) {
   if (!Number.isFinite(ttlMs) || ttlMs < 0) throw new Error('Invalid task column cache lifetime')
   const cache = new Map(), pending = new Map()

package/src/watch.mjs

@@ -27,7 +27,7 @@ import { interruptedRuntimeResult, isTransportInterruption, transportRecoveryDel
 import { mapConcurrent } from './concurrency.mjs'
 import { releaseAuthorizedPause } from './authorization-resume.mjs'
 import { dedicatedChannel, repliesAfterSource } from './channel-routing.mjs'
-import { createTaskTypeLookup } from './task-types.mjs'
+import { createTaskTypeLookup, loadProjectTaskTypes } from './task-types.mjs'
 import { createThreadContextResolver } from './thread-context.mjs'
 import { assignmentRequest, assignmentStatusOnly, routeAssignments } from './assignment-routing.mjs'
 import { modelProcessOptions, stopModelProcess } from './process-lifecycle.mjs'
@@ -325,7 +325,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 +594,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,7 +896,9 @@ 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 (validBackendId(self.id)) selfAgentId = Number(self.id)
@@ -993,7 +995,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     try { return JSON.parse(text) } catch { return { text } }
   }
 
-  const taskTypeSets = createTaskTypeLookup({ load: (projectId) => callMcpTool('list_task_types', { project_id: projectId }).then(toolData) })
+  const taskTypeSets = createTaskTypeLookup({ load: (projectId) => loadProjectTaskTypes({ projectId, listTools: () => mcpClient.listTools(), callTool: (name, args) => callMcpTool(name, args).then(toolData) }) })
 
   const callMcpReadWithRetry = async (name, args = {}) => {
     try { return await callMcpTool(name, args) }
@@ -1681,6 +1683,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}`)
@@ -1883,7 +1888,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       if (activityChannel != null) sendStatus(activityChannel, 'thinking')
       const humanTicketRef = ticketSlug ? `ticket ${ticketSlug}` : `the ticket “${title}”`
       const workspaceDirective = preparedWorktree ? ` A prepared local git worktree for this ticket exists at ${JSON.stringify(preparedWorktree)}. Start repository inspection and edits there. Do not call list_codebases, codebase_tree, or get_codebase while this local worktree is available.` : ''
-      void drain(cycleKind, `Authoritative get_ticket verification confirms ${humanTicketRef} is open and assigned to YOU. Internal tool identity: project_id ${projectId}, ticket_id ${ticketId}. For every get_ticket call pass exactly { project_id: ${projectId}, ticket_id: ${ticketId} }; for list_task_types pass exactly { project_id: ${projectId} }. Numeric ids are MCP arguments only and must never appear in human-facing text; use ${ticketSlug || 'the ticket title'} instead. Ticket details: ${JSON.stringify({ slug: ticketSlug, title, description: ticket.description, priority: ticket.priority, typeId: ticket.type_id ?? ticket.typeId })}.${workspaceDirective} This assignment has no source thread: do not call post_message yourself. Choose the tools, context, validation, and ticket state appropriate to this request. Return your final response when you decide this turn is finished; the watcher will publish it once in the dedicated agent channel without changing ticket status.`, activityChannel == null ? [] : [activityChannel], { projectId, ticketId, channelId: activityChannel })
+      void drain(cycleKind, `Authoritative get_ticket verification confirms ${humanTicketRef} is open and assigned to YOU. Internal tool identity: project_id ${projectId}, ticket_id ${ticketId}. For every get_ticket call pass exactly { project_id: ${projectId}, ticket_id: ${ticketId} }; For list_task_types, follow its advertised schema: resolve the ticket’s board_id from the ticket or list_boards and include it when required. Never guess a board id. Numeric ids are MCP arguments only and must never appear in human-facing text; use ${ticketSlug || 'the ticket title'} instead. Ticket details: ${JSON.stringify({ slug: ticketSlug, title, description: ticket.description, priority: ticket.priority, typeId: ticket.type_id ?? ticket.typeId })}.${workspaceDirective} This assignment has no source thread: do not call post_message yourself. Choose the tools, context, validation, and ticket state appropriate to this request. Return your final response when you decide this turn is finished; the watcher will publish it once in the dedicated agent channel without changing ticket status.`, activityChannel == null ? [] : [activityChannel], { projectId, ticketId, channelId: activityChannel })
     } catch (e) {
       log(kind + ' ticket verification failed for #' + ticketId + ': ' + (e?.message || e))
     }
@@ -2079,7 +2084,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
           ? `The watcher verified this source message is addressed to you in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". ${codingMention ? 'Complete the concrete repository work and verification first.' : 'Answer the request directly.'} Do NOT call post_message; it is intentionally unavailable. Return only the final reply as your final answer. The watcher will re-check the live thread and render it at most once.${who ? ` To mention the requester, use their exact full name "@${who}".` : ''} Use additional discovery, resources, and history when they help answer this request.`
           : `The watcher verified this source message is addressed to you in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". ${codingMention ? `This is concrete repository work. Start the coding flow now. You may send at most one concrete progress update after work begins, but do not stop there: continue the work and then send one distinct final result with evidence or a real blocker. Use post_message for the final result even if you already sent a progress message` : 'Send EXACTLY ONE reply with post_message'}: arguments: channel_id ${cid}${threadRoot != null ? `, parent_id ${threadRoot} (reply IN THAT THREAD, do not start a new top-level message)` : ''}, using the authenticated session bridge. Never repeat the same message.${who ? ` To @mention them back, write their EXACT full name "@${who}". A mention only links when the name matches exactly.` : ''} Use additional discovery, resources, and history when they help answer this request.${codingMention ? ' Stop only after the work and final result/blocker.' : ' After your single reply, STOP.'}`
         : undefined
-      if (ctx && creatingTicket) ctx += ' This is a ticket-creation request, not repository implementation. Discover create_ticket on the authenticated watcher server, resolve the project and valid type using list_projects and list_task_types, then create the requested ticket once. Follow its actual schema. If a required detail is ambiguous, ask for that detail rather than inventing it. Report the returned ticket reference. Never replay a creation after a timeout or uncertain response.'
+      if (ctx && creatingTicket) ctx += ' This is a ticket-creation request, not repository implementation. Discover create_ticket on the authenticated watcher server, resolve the project, board, and valid type using list_projects, list_boards, and list_task_types, then create the requested ticket once. Follow its actual schema. If a required detail is ambiguous, ask for that detail rather than inventing it. Report the returned ticket reference. Never replay a creation after a timeout or uncertain response.'
       if (ctx && raw._threadRootContent) ctx += ` Verified thread root authored by you (context, not a new request): ${JSON.stringify(raw._threadRootContent)}. For requested repairs, inspect the referenced PR and its branch, run the failing verification, and fix that existing work. A review/testing handoff does not prevent an explicit human repair request.`
       if (codingMention) {
         // Activity indicators make accepted work visible. Do not add a canned
@@ -2192,7 +2197,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 +2394,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 +2438,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 +2489,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 +2515,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,11 +392,22 @@ 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); }
   }
   async function settingsFetch(path, options) {
@@ -877,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">