openvisio-agent 0.25.1 → 0.25.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.25.1",
+  "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,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/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/watch.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)
@@ -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}`)
@@ -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,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">