openvisio-agent 0.25.17 → 0.25.19

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.25.19] — 2026-10-06
+
+- Add Studio **Update connection** with discovery, a review of changed endpoints, and a pasted connection-object fallback. Verify saved credentials before saving, preserve agent settings, and restart the watcher after applying. Reject stale previews and updates during recorded active work; report restart failures separately from successful saves.
+- Recover guarded channel and task-comment replies after recognized runtime transport interruptions, using the existing bounded backoff, cancellation, and single-delivery controls.
+- Classify OpenCode provider failures carried in structured ACP error data, including quota, authentication, and unavailable-model errors. Unknown failures point to the local Studio process error without publishing raw diagnostics.
+- Include Studio credential-object import, task-comment project resolution, and explicit backend migration fixes.
+- Live smoke gate waived: no designated safe test organization/ticket is available. Real provider execution and Bard/Hindris behavior remain unverified. Automatic discovery requires the deployed app route; use the pasted connection-object fallback while it is unavailable.
+
+## [0.25.18] — 2026-10-05
+
+- Add `update --name <agent>` to fetch current connection URLs from agent setup without re-entering credentials. Support `--host` for the stable app address, manual URL overrides, and an optional background watcher restart.
+- Refresh backend connections at startup and after connection failures, with no periodic discovery polling. Preserve saved credentials and settings, retain the last known endpoints on discovery failure, and verify that discovered configuration matches the saved backend.
+- Reconnect changed WebSocket endpoints and use updated MCP endpoints for new runtime sessions while allowing active work to finish. Carry the discovery address through CLI and Studio setup.
+- Deployment requirement: the OpenVisio app must serve `/api/agent/setup/connection`. Immediate propagation to healthy connections still requires a backend configuration-change event publisher, which is not included in this release.
+- Live smoke gate waived: no designated safe test organization/ticket is configured for this release. Real provider execution and end-to-end behavior against deployed discovery and backend services remain unverified; local certification covers simulated service boundaries.
+
 ## [0.25.17] — 2026-09-25
 
 - Preserve the original goal across reply-to-work handoffs and require a structured assessment of requested outcomes and observed evidence before a successful cycle. Continue unfinished work in the same session up to twice, preserve specific blockers, and fail closed on invalid assessments.

package/README.md

@@ -1,6 +1,6 @@
 # openvisio-agent
 
-Connect your coding agent (**Claude Code, Codex, OpenCode, Gemini CLI, or Qwen Code**) to an [OpenVisio](https://openvisio.app) team — in one command. No shell scripts, no `curl | bash`.
+Connect your coding agent (**Claude Code, Codex, OpenCode, Gemini CLI, or Qwen Code**) to an [OpenVisio](https://openvisio.io) team — in one command. No shell scripts, no `curl | bash`.
 
 **New here?** Start with the [user guide](USER_GUIDE.md) for setup, everyday work, Agent Studio, and troubleshooting.
 
@@ -58,6 +58,27 @@ npx -y openvisio-agent@latest connect --backend https://api.your-org.example/dev
 
 Then `watch --name ada` auto-detects the backend agent and runs a WebSocket loop instead of polling: it connects with `?api_key=&identifier=`, keeps the connection warm with keepalives, reconnects with backoff, and queues each accepted assignment or mention independently. A work cycle can contain many assistant, tool, and message actions; emitting a progress message does not end it. The Mastra runtime requires **Node ≥ 22.13**.
 
+### Automatic connection updates
+
+Backend/BYO watchers fetch the current WebSocket and MCP URLs from the stable OpenVisio app's `/api/agent/setup/connection` endpoint at startup and after connection failures (at most once per 30 seconds). There is no periodic discovery timer: a healthy, idle watcher makes no discovery requests. The request sends no credentials and accepts only a complete configuration matching the saved backend. Failed discovery keeps the last saved endpoints. It does not poll team tasks or invoke a model.
+
+If the old connections remain healthy, an endpoint change is picked up on the next startup, connection failure, or explicit `update` command. Immediate propagation to healthy watchers requires a backend-published configuration-change event; that publisher is not implemented here.
+
+When URLs change, the watcher saves them, reconnects its WebSocket, and uses the new MCP endpoint for new runtime sessions. Active sessions finish before being retired; they can still encounter errors if their old MCP endpoint is removed during a turn. There is no automatic process restart or cancellation of accepted work. Credentials, runtime, models, workspace, and other settings are preserved.
+
+New setup commands and copied Studio credentials include the app address. For self-hosted or staging setups, pass `--host <app-url>` to `connect`. Legacy configurations try `https://openvisio.io`, but reject a different backend. Existing agents need this package version installed and their watcher restarted once. To set a different discovery host and refresh immediately:
+
+```bash
+npx -y openvisio-agent@latest update --name ada \
+  --host https://your-openvisio.app --restart
+```
+
+After the host is saved, `openvisio-agent update --name ada` fetches the current URLs without requiring either URL or another API key. Automatic refresh updates the watcher's scoped MCP configuration; the explicit `update` command also refreshes Claude's global registration when the MCP URL changes. Manual `--ws` and/or `--mcp-url` overrides remain available. Relay agents support manual MCP updates only.
+
+If the API backend itself has moved, pass `--backend <new-api-url>` along with the current `--ws <new-websocket-url>` (and `--mcp-url` if it changed). The update verifies the saved credentials against the new API before saving, preserves agent settings, and updates both API and WebSocket values in the agent's environment file. Without manual connection URLs, it discovers them from `--host` and requires that metadata to match the explicitly selected backend. Automatic discovery never migrates credentials to a different backend.
+
+`--restart` explicitly stops the named watcher (interrupting active work) and installs/starts its background service on macOS or Linux. It does not upgrade an existing global package; install the new release first. Omit it to save changes without interrupting work. Foreground watchers can be stopped and started with `openvisio-agent watch --name ada`. Explicit URL overrides on `watch` disable discovery for that invocation. The discovery app host must remain reachable; changing that host or the backend identity requires an explicit update/reconnect.
+
 ### `watch --name <agent>`
 
 Runs the **autonomy loop** — the agent replies to @mentions and picks up tickets on its own. It cheaply polls an inbox endpoint (no model spend when idle) and starts isolated runtime sessions only when something new arrives.

package/USER_GUIDE.md

@@ -35,9 +35,11 @@ npm install -g openvisio-agent@latest
 
 1. In OpenVisio, open **Agents** and choose the connection flow for your agent.
 2. Select your coding runtime, register the agent, and choose **Copy credentials**. The API key is shown only once.
-3. Open Agent Studio on your computer (`openvisio-agent studio`), choose **Connect agent**, and paste the credentials. You can also enter the fields individually.
+3. Open Agent Studio on your computer (`openvisio-agent studio`), choose **Connect agent**, and paste the generated JSON object. Choose **Use credentials** to review the fields, or **Verify and connect** to import and connect directly. You can also enter the fields individually.
 4. Choose **Verify and connect**. Studio checks the key and identifier and saves the connection privately on this computer. Install and sign in to your selected coding runtime, then select the agent and choose **Start watcher**.
 
+Studio retrieves missing MCP and WebSocket URLs from the OpenVisio app URL. If discovery is unavailable, enter those URLs manually; existing entered values are preserved.
+
 **Terminal option:** Expand **Or use a terminal command** in OpenVisio and run the supplied command. This remains available for CLI setup and advanced options. Existing agents can copy connection details from their profile and enter their previously saved API key in Studio.
 
 Treat copied credentials and setup commands as private. Studio does not retrieve a lost API key. Keep your one-time key somewhere safe before leaving the registration screen.
@@ -46,6 +48,14 @@ Coding mode is enabled by default for backend connections. The agent can handle
 
 For advanced connection options, see the [command reference](README.md#what-it-does).
 
+## Update an existing connection
+
+Select an agent in Studio and choose **Update connection**. Studio checks the saved OpenVisio app address for current connection URLs. Review the URLs, then choose **Apply and reconnect** to verify the saved credentials, save the settings, and restart the watcher.
+
+If the check fails, paste the latest connection JSON object from OpenVisio and choose **Check connection**. Only connection URLs are imported; the agent keeps its saved API key, identity, models, and workspace. Finish or stop active work before applying. If Studio cannot restart the watcher, it reports that the settings were saved and asks you to restart it manually.
+
+This control requires a package version containing the connection-update feature. Automatic discovery also requires the OpenVisio app to serve `/api/agent/setup/connection`; pasting the object works when discovery is unavailable.
+
 ## Start your watcher
 
 A **watcher** is the local program that listens for messages and assignments and runs your agent when there is work to do. Starting it can pick up existing assignments immediately.

package/bin/cli.mjs

@@ -26,9 +26,10 @@ Connect your coding agent to an OpenVisio team.
 
 Usage:
   openvisio-agent connect <ovs_code> --host <url> [--name "<agent>"] [--mcp-url <url>] [--agent ${supportedRuntimeList('|')}]
-  openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--ws <wss-url>] [--mcp-url <url>] [--agent ${supportedRuntimeList('|')}]
+  openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--host <app-url>] [--ws <wss-url>] [--mcp-url <url>] [--agent ${supportedRuntimeList('|')}]
   openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--model <m>] [--chat-model <m>] [--debug]
   openvisio-agent stop    --name <agent>
+  openvisio-agent update  --name <agent> [--host <app-url>] [--backend <url>] [--ws <wss-url>] [--mcp-url <url>] [--restart]
   openvisio-agent studio  [--port <number>] [--no-open] [--demo]
   openvisio-agent authorize-pr-push [--repo <dir>]
   openvisio-agent push-pr-branch
@@ -47,6 +48,7 @@ connect --backend
   (launchd/systemd) that auto-starts on login, so @mentions/assignments are caught
   even with no terminal open. Requests authenticate with the x-agent-api-key +
   x-agent-identifier headers.
+    --host <url>     stable OpenVisio app URL for automatic endpoint discovery.
     --ws <wss-url>   API-Gateway WebSocket base (same as NEXT_PUBLIC_BACKEND_WS_URL)
                      — enables real-time autonomy (task:assigned / agent:mention).
     --mcp-url <url>  registers the openvisio-team MCP so the agent has tools to ACT
@@ -78,6 +80,15 @@ watch
   setup needed. Use --workspace <dir> to relocate it (e.g. an existing clones folder),
   --chat-only to disable code work, and --install to run in the background on login.
 
+update
+  Fetches current connection URLs from agent setup, preserving credentials and
+  settings. --host selects the OpenVisio app (default: https://openvisio.io).
+  Watchers refresh at startup and after connection failures, with no periodic poll.
+  Explicit --ws/--mcp-url values remain available for manual updates.
+  Use --backend to migrate to a new API URL after verifying saved credentials.
+  Restart the watcher to apply changes. --restart stops the named watcher and
+  installs/starts its background service (macOS/Linux; interrupts active work).
+
 stop
   Stops the named agent's launchd/systemd service first, then terminates every
   remaining watcher with that exact --name and clears its stale lock. Use this
@@ -209,6 +220,8 @@ async function runConnect({ positional, flags }) {
 // We verify them live, then persist a config + a sourceable env file.
 async function runConnectBackend({ flags }) {
   const backend = stripSlash(String(flags.backend))
+  const { endpoint } = await import('../src/update.mjs')
+  const setupHost = flags.host === undefined ? 'https://openvisio.io' : endpoint(flags.host, 'host', ['http:', 'https:'])
   const apiKey = flags.key && String(flags.key)
   const identifier = flags.id && String(flags.id)
   if (!/^https?:\/\//.test(backend)) fail('The --backend value must be a full URL (e.g. https://api.your-org.example/dev).')
@@ -260,7 +273,7 @@ async function runConnectBackend({ flags }) {
   }
 
   if (!chatOnly) configurePrPublishing({ workspace: workdir || DEFAULT_WORKSPACE, enabled: !flags['no-pr-push'] })
-  writeJson(configPath(slug), { ...(flags.channel ? { dedicatedChannelId: Number(flags.channel) } : {}), prPublishing: !flags['no-pr-push'], mode: 'backend', backend, apiKey, identifier, name, slug, wsUrl, mcpUrl, mcpConfig, ...(agent !== 'claude' ? { agent } : {}), ...(workdir ? { workspace: workdir } : {}), ...(chatOnly ? { chatOnly: true } : {}), ...(flags.model ? { model: String(flags.model) } : {}), ...(flags['chat-model'] ? { chatModel: String(flags['chat-model']) } : {}) }, true)
+  writeJson(configPath(slug), { ...(flags.channel ? { dedicatedChannelId: Number(flags.channel) } : {}), prPublishing: !flags['no-pr-push'], mode: 'backend', backend, setupHost, apiKey, identifier, name, slug, wsUrl, mcpUrl, mcpConfig, ...(agent !== 'claude' ? { agent } : {}), ...(workdir ? { workspace: workdir } : {}), ...(chatOnly ? { chatOnly: true } : {}), ...(flags.model ? { model: String(flags.model) } : {}), ...(flags['chat-model'] ? { chatModel: String(flags['chat-model']) } : {}) }, true)
   // A sourceable env file, matching the setup snippet OpenVisio shows.
   const envPath = join(OV_DIR, `${slug}.env`)
   mkdirSync(OV_DIR, { recursive: true })
@@ -316,6 +329,7 @@ async function main() {
   const cmd = argv[0]
   const rest = parseFlags(argv.slice(1))
   if (cmd === 'connect') return runConnect(rest)
+  if (cmd === 'update') return (await import('../src/update.mjs')).runUpdate(rest)
   if (cmd === 'watch') return (await import('../src/watch.mjs')).runWatch(rest)
   if (cmd === 'studio') return (await import('../src/studio-cli.mjs')).runStudio(rest)
   if (cmd === 'stop') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.25.17",
+  "version": "0.25.19",
   "description": "Connect Claude Code, Codex, OpenCode, Gemini CLI, or Qwen Code 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', name, task = true, run, evaluateGoal, routeReport, threadError = false, commentTools = [], onComment, historyTools = [], readHistory, selfProfile = self, listAgents, getAgent, getTicket, listChannels, listActivity, transportRecoveryDelays, activityReporter } = {}) {
+export function fixture({ agent = 'codex', name, task = true, run, evaluateGoal, routeReport, threadError = false, commentTools = [], onComment, historyTools = [], readHistory, selfProfile = self, listAgents, getAgent, getTicket, listChannels, listActivity, transportRecoveryDelays, activityReporter, watcherOptions = {}, watcherDependencies = {} } = {}) {
   const dir = mkdtempSync(join(tmpdir(), 'byo-workspace-'))
   const posts = [], runs = [], calls = [], logs = [], messages = [], subscriptions = []
   const routingRuns = [], evaluations = []
@@ -82,14 +82,15 @@ export function fixture({ agent = 'codex', name, task = true, run, evaluateGoal,
     }
   }
   const start = () => {
-    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' }, {
+    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', ...watcherOptions }, {
       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),
+      ...watcherDependencies,
     })
     return watcher
   }
   start()
   return {
-    dir, ticket, posts, runs, evaluations, routingRuns, calls, logs, messages, memory, subscriptions,
+    dir, ticket, posts, runs, evaluations, routingRuns, calls, logs, messages, memory, subscriptions, mcp,
     get watcher() { return watcher },
     get connection() { return connection },
     get closed() { return closed },

package/src/connection-discovery.mjs

@@ -0,0 +1,61 @@
+export const DEFAULT_SETUP_HOST = 'https://openvisio.io'
+
+// Public deployment metadata. Discovery never sends agent credentials and must
+// match the saved backend before its endpoints can receive those credentials.
+function checkedUrl(value, protocols) {
+  if (typeof value !== 'string' || /\s/.test(value)) throw new Error('Invalid connection URL in setup configuration.')
+  let url
+  try { url = new URL(value) } catch { throw new Error('Invalid connection URL in setup configuration.') }
+  if (!protocols.includes(url.protocol) || !url.hostname || url.username || url.password || url.search || url.hash) throw new Error('Invalid connection URL in setup configuration.')
+  if (['http:', 'ws:'].includes(url.protocol) && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) throw new Error('Setup configuration requires secure connection URLs.')
+  return url.href.replace(/\/+$/, '')
+}
+
+export function validateConnectionManifest(data) {
+  return {
+    setupHost: checkedUrl(data.setupHost || DEFAULT_SETUP_HOST, ['https:', 'http:']),
+    backend: checkedUrl(data.backend, ['https:', 'http:']),
+    wsUrl: checkedUrl(data.wsUrl, ['wss:', 'ws:']),
+    mcpUrl: checkedUrl(data.mcpUrl, ['https:', 'http:']),
+  }
+}
+
+export async function fetchConnectionManifest(host, { fetchImpl = fetch, signal } = {}) {
+  const setupHost = checkedUrl(host || DEFAULT_SETUP_HOST, ['https:', 'http:'])
+  const response = await fetchImpl(`${setupHost}/api/agent/setup/connection`, {
+    headers: { accept: 'application/json' }, cache: 'no-store', redirect: 'error',
+    signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
+  })
+  if (!response.ok) { await response.body?.cancel(); throw new Error(`Connection discovery returned HTTP ${response.status}. Saved URLs are unchanged.`) }
+  const data = await response.json()
+  if (data?.version !== 1) throw new Error('Unsupported connection configuration version.')
+  return validateConnectionManifest({ ...data, setupHost })
+}
+
+export async function fetchConnectionSettings(saved, options = {}) {
+  if (saved.mode !== 'backend') throw new Error('Automatic connection discovery requires a backend agent.')
+  const backend = checkedUrl(saved.backend, ['https:', 'http:'])
+  const next = await fetchConnectionManifest(saved.setupHost, options)
+  if (next.backend !== backend) throw new Error('Setup configuration does not match the saved backend. Use --host with this agent’s OpenVisio app URL.')
+  const { backend: _, ...settings } = next
+  return settings
+}
+
+// Checks run only when requested by startup, failures, or an explicit command.
+// Serialize checks and throttle failure-triggered probes. A failed response
+// never clears a working endpoint, and shutdown aborts an outstanding request.
+export function createConnectionRefresh({ refresh, log = () => {}, minIntervalMs = 30_000, now = Date.now }) {
+  let pending = null, lastCheck = -Infinity, stopped = false
+  const controller = new AbortController()
+  const check = () => {
+    if (stopped) return Promise.resolve()
+    if (pending) return pending
+    if (now() - lastCheck < minIntervalMs) return Promise.resolve()
+    lastCheck = now()
+    pending = Promise.resolve().then(() => refresh(controller.signal)).catch(() => {
+      if (!stopped) log('Connection discovery unavailable; keeping the last saved endpoints.')
+    }).finally(() => { pending = null })
+    return pending
+  }
+  return { check, close() { stopped = true; controller.abort(); return pending || Promise.resolve() } }
+}

package/src/mastra-harness.mjs

@@ -450,7 +450,7 @@ export function createMastraAcpRunner({
     } catch (error) {
       if (!controller.signal.aborted) {
         inspectDiagnostics(true)
-        if (agent === 'opencode') providerFailure ||= opencodeProviderFailure(error?.message)
+        if (agent === 'opencode') providerFailure ||= opencodeProviderFailure(error)
       }
       const canceled = controller.signal.aborted
       const subtype = providerFailure?.subtype || (timedOut ? 'timeout' : canceled ? 'canceled' : 'error')
@@ -463,7 +463,7 @@ export function createMastraAcpRunner({
       log(`${agent} cycle done via Mastra ACP (${subtype}${!canceled && safeError ? ': ' + clean(safeError, 1200) : ''})`)
       invalidate()
       return {
-        type: 'result', subtype, transportInterrupted: subtype === 'error' && isTransportInterruption(error), userMessage: providerFailure?.userMessage || null, runtime: 'mastra-acp', model: selectedModel || null, requestedModel: requestedModel || null, outputText: outputText.trim(),
+        type: 'result', subtype, transportInterrupted: subtype === 'error' && isTransportInterruption(error), userMessage: providerFailure?.userMessage || (agent === 'opencode' && subtype === 'error' ? 'OpenCode could not finish the request. Open the failed cycle in Agent Studio and check its process error for the runtime or provider failure before retrying.' : null), runtime: 'mastra-acp', model: selectedModel || null, requestedModel: requestedModel || null, outputText: outputText.trim(),
         mcpCalls: [...calls], mcpErrors: [...errors.keys()], mcpErrorDetails: Object.fromEntries(errors),
         didCode, didRepoMutation, didMessage, didChannelMessage, didResultMessage,
         didMcpTaskRead, didMcpTaskUpdate,

package/src/opencode-failure.mjs

@@ -1,6 +1,22 @@
 // Classify runtime diagnostics only, never assistant prose or tool output.
 export function opencodeProviderFailure(value) {
-  const text = String(value || '').split('ACP agent stderr:')[0]
+  const seen = new Set()
+  const diagnostic = (item, depth = 0) => {
+    if (item == null || depth > 6 || seen.has(item)) return ''
+    if (typeof item === 'string') {
+      const text = item.split('ACP agent stderr:')[0].slice(0, 16000)
+      try { return diagnostic(JSON.parse(text), depth + 1) } catch { return text }
+    }
+    if (typeof item !== 'object') return String(item)
+    seen.add(item)
+    // ACP commonly wraps a provider error in data under "Internal error".
+    // Read diagnostic fields only; never inspect prompts, tool output, or headers.
+    return [
+      ...['name', 'message', 'code', 'data', 'error', 'cause'].map(key => diagnostic(item[key], depth + 1)),
+      ...['status', 'statusCode', 'status_code'].filter(key => item[key] != null).map(key => `status ${item[key]}`),
+    ].join(' ')
+  }
+  const text = diagnostic(value)
   if (/rate[_ -]?limit|too many requests|\b(?:HTTP|status(?: code)?)\s*[:=]?\s*429\b/i.test(text)) {
     return { subtype: 'rate_limited', userMessage: 'OpenCode’s model provider is rate-limiting this request. Retry after the provider limit resets, or select a model with available quota in Agent Studio.' }
   }

package/src/runner-pool.mjs

@@ -11,7 +11,7 @@ export function createRunnerPool({ create, capacity = 8, idleMs = 300_000, now =
   }
   function prune() {
     for (const [key, entry] of entries) {
-      if (!entry.busy && (idleMs === 0 || now() - entry.usedAt >= idleMs || entries.size > capacity)) {
+      if (!entry.busy && (entry.stale || idleMs === 0 || now() - entry.usedAt >= idleMs || entries.size > capacity)) {
         entries.delete(key)
         dispose(entry)
       }
@@ -20,6 +20,10 @@ export function createRunnerPool({ create, capacity = 8, idleMs = 300_000, now =
   const timer = idleMs === 0 ? null : setInterval(prune, Math.min(idleMs, 30_000))
   timer?.unref?.()
   return {
+    invalidate() {
+      for (const entry of entries.values()) entry.stale = true
+      prune()
+    },
     acquire(key, options) {
       if (closed) throw new Error('Session pool is closed')
       prune()

package/src/studio-connect.mjs

@@ -2,6 +2,7 @@ import { mkdir, open, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
 import { slugify } from './lib.mjs'
 import { runtimeProvider } from './runtime-providers.mjs'
+import { fetchConnectionSettings } from './connection-discovery.mjs'
 
 const problem = (message, status = 400) => Object.assign(new Error(message), { status })
 
@@ -23,8 +24,18 @@ export async function connectStudioAgent({ stateDir, input, fetchImpl = fetch })
   const agent = field('agent')
   if (!runtimeProvider(agent)) throw problem('Choose a supported runtime.')
   const backend = url('backend', ['https:', 'http:'])
-  const mcpUrl = url('mcpUrl', ['https:', 'http:'])
-  const wsUrl = url('wsUrl', ['wss:', 'ws:'])
+  let mcpUrl = field('mcpUrl', false) ? url('mcpUrl', ['https:', 'http:']) : ''
+  let wsUrl = field('wsUrl', false) ? url('wsUrl', ['wss:', 'ws:']) : ''
+  const setupHost = field('setupHost', false) ? url('setupHost', ['https:', 'http:']) : 'https://openvisio.io'
+  if (!mcpUrl || !wsUrl) {
+    try {
+      const discovered = await fetchConnectionSettings({ mode: 'backend', backend, setupHost }, { fetchImpl })
+      mcpUrl ||= discovered.mcpUrl
+      wsUrl ||= discovered.wsUrl
+    } catch {
+      throw problem('Could not discover the missing connection URLs. Check the OpenVisio app URL, or enter the MCP and WebSocket URLs manually.', 502)
+    }
+  }
   let response
   try {
     response = await fetchImpl(`${backend}/projects`, { headers: { accept: 'application/json', 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier }, redirect: 'error', signal: AbortSignal.timeout(15000) })
@@ -40,7 +51,7 @@ export async function connectStudioAgent({ stateDir, input, fetchImpl = fetch })
     // Exclusive creation also prevents overwriting existing connections or symlinks.
     for (const [path, value] of [
       [mcpPath, { mcpServers: { 'openvisio-team': { type: 'http', url: mcpUrl, headers: { 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier } } } }],
-      [configPath, { mode: 'backend', backend, apiKey, identifier, name, slug, agent, wsUrl, mcpUrl, mcpConfig: mcpPath, prPublishing: true }],
+      [configPath, { mode: 'backend', backend, setupHost, apiKey, identifier, name, slug, agent, wsUrl, mcpUrl, mcpConfig: mcpPath, prPublishing: true }],
     ]) {
       const handle = await open(path, 'wx', 0o600)
       created.push(path)

package/src/studio-connection.mjs

@@ -0,0 +1,52 @@
+import { constants, openSync, readFileSync, fstatSync, closeSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join } from 'node:path'
+import { DEFAULT_SETUP_HOST, fetchConnectionManifest, validateConnectionManifest } from './connection-discovery.mjs'
+import { saveConnectionSettings } from './update.mjs'
+
+const problem = (message, status = 400) => Object.assign(new Error(message), { status })
+const version = (saved, settings) => createHash('sha256').update(JSON.stringify({ saved, settings })).digest('hex')
+function readConnection(stateDir, slug) {
+  if (!/^[a-z0-9][a-z0-9_-]{0,79}$/i.test(slug)) throw problem('Invalid agent.')
+  const fd = openSync(join(stateDir, `${slug}.json`), constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    if (!fstatSync(fd).isFile() || fstatSync(fd).size > 65536) throw problem('Agent settings are unavailable.')
+    const saved = JSON.parse(readFileSync(fd, 'utf8'))
+    if (saved.mode !== 'backend' || saved.slug !== slug || !saved.apiKey || !saved.identifier) throw problem('This agent does not support connection updates.')
+    return saved
+  } finally { closeSync(fd) }
+}
+
+export async function previewStudioConnection({ stateDir, slug, input = {}, fetchImpl = fetch }) {
+  const saved = readConnection(stateDir, slug)
+  const setupHost = input.setupHost || (saved.setupHost === 'https://openvisio.app' ? DEFAULT_SETUP_HOST : saved.setupHost) || DEFAULT_SETUP_HOST
+  let settings
+  try {
+    settings = input.settings
+      ? validateConnectionManifest({ ...input.settings, setupHost: input.settings.setupHost || setupHost })
+      : await fetchConnectionManifest(setupHost, { fetchImpl })
+  } catch {
+    throw problem('Could not load current connection URLs. Check the app URL, or paste the latest connection object from OpenVisio and choose Check connection.', 502)
+  }
+  return { settings, version: version(saved, settings), backendChanged: saved.backend !== settings.backend }
+}
+
+export async function applyStudioConnection({ stateDir, slug, input, fetchImpl = fetch }) {
+  const saved = readConnection(stateDir, slug)
+  let settings
+  try { settings = validateConnectionManifest(input?.settings) } catch { throw problem('Check the connection settings before applying them.') }
+  if (!input.version || input.version !== version(saved, settings)) throw problem('Agent settings changed. Check the connection again before applying.', 409)
+  let response
+  try {
+    response = await fetchImpl(`${settings.backend}/projects`, {
+      headers: { accept: 'application/json', 'x-agent-api-key': saved.apiKey, 'x-agent-identifier': saved.identifier },
+      redirect: 'error', signal: AbortSignal.timeout(15000),
+    })
+  } catch { throw problem('Could not reach the selected backend. Saved settings are unchanged.', 502) }
+  await response.body?.cancel()
+  if (!response.ok) throw problem(`The selected backend rejected verification (HTTP ${response.status}). Saved settings are unchanged.`, 502)
+  const current = readConnection(stateDir, slug)
+  if (version(current, settings) !== input.version) throw problem('Agent settings changed during verification. Check the connection again.', 409)
+  saveConnectionSettings({ stateDir, slug, saved: current, next: { ...current, ...settings } })
+  return { saved: true }
+}

package/src/studio-server.mjs

@@ -9,6 +9,8 @@ import { readModelSettings, saveModelSettings, listRuntimeModels } from './model
 import { planAgentRemoval, removeLocalAgent } from './agent-removal.mjs'
 import { controlLocalWatcher } from './watcher-control.mjs'
 import { connectStudioAgent } from './studio-connect.mjs'
+import { previewStudioConnection, applyStudioConnection } from './studio-connection.mjs'
+import { deriveModel } from '../studio/app.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
@@ -164,7 +166,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, watcherControl = controlLocalWatcher, connectAgent = connectStudioAgent }) {
+export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4317, assetsDir = DEFAULT_ASSETS, demo = false, modelCatalog = listRuntimeModels, removeAgent = removeLocalAgent, watcherControl = controlLocalWatcher, connectAgent = connectStudioAgent, previewConnection = previewStudioConnection, applyConnection = applyStudioConnection }) {
   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')
@@ -227,6 +229,39 @@ export async function startStudioServer({ stateDir, host = '127.0.0.1', port = 4
         }
         return
       }
+      const connectionRoute = /^\/api\/agents\/([a-z0-9][a-z0-9_-]{0,79})\/connection$/i.exec(path)
+      if (connectionRoute) {
+        const slug = connectionRoute[1]
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        try {
+          if (demo) throw Object.assign(new Error('Connection updates are unavailable in demo mode.'), { status: 403 })
+          if (req.method !== 'POST') throw Object.assign(new Error('Method not allowed'), { status: 405 })
+          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 update connections.'), { status: 403 })
+          let body = ''
+          for await (const chunk of req) { body += chunk; if (Buffer.byteLength(body) > 16384) throw Object.assign(new Error('Connection request is too large.'), { status: 413 }) }
+          let input
+          try { input = JSON.parse(body) } catch { throw Object.assign(new Error('Invalid connection request.'), { status: 400 }) }
+          if (input?.action === 'check') { res.end(JSON.stringify(await previewConnection({ stateDir, slug, input }))); return }
+          if (input?.action !== 'apply') throw Object.assign(new Error('Choose check or apply.'), { status: 400 })
+          if (watcherChanges.has(slug) || removals.has(slug)) throw Object.assign(new Error('Another agent change is in progress.'), { status: 409 })
+          watcherChanges.add(slug)
+          try {
+            const model = deriveModel(await readStudioSnapshot({ stateDir, journalCache }))
+            if (model.cycles.some(cycle => cycle.agent?.slug === slug && ['active', 'queued', 'connecting', 'recovering'].includes(cycle.status))) throw Object.assign(new Error('This agent has active work. Finish or stop its work before applying and reconnecting.'), { status: 409 })
+            const result = await applyConnection({ stateDir, slug, input })
+            try {
+              await watcherControl({ stateDir, slug, action: 'restart' })
+              res.end(JSON.stringify({ ...result, restarted: true, message: 'Connection settings saved and watcher restarted. Check its activity for connection status.' }))
+            } catch {
+              res.end(JSON.stringify({ ...result, restarted: false, message: 'Connection settings saved, but the watcher could not restart. Start or restart it manually to apply the update.' }))
+            }
+          } finally { watcherChanges.delete(slug) }
+        } catch (error) {
+          res.writeHead(error.status || 503)
+          res.end(JSON.stringify({ error: error.status ? error.message : 'Could not update this agent connection. Check its saved configuration and try again.' }))
+        }
+        return
+      }
       const removalRoute = /^\/api\/agents\/([a-z0-9][a-z0-9_-]{0,79})\/removal$/i.exec(path)
       if (removalRoute && !demo) {
         const slug = removalRoute[1]

package/src/update.mjs

@@ -0,0 +1,135 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { fetchConnectionSettings } from './connection-discovery.mjs'
+import { OV_DIR, readConfig, writeJson, slugify, stripSlash, onPath, ok, info } from './lib.mjs'
+
+export function endpoint(value, flag, protocols) {
+  if (typeof value !== 'string' || !value.trim() || /\s/.test(value)) throw new Error(`--${flag} requires a full URL.`)
+  let url
+  try { url = new URL(value) } catch { throw new Error(`--${flag} requires a full URL.`) }
+  if (!protocols.includes(url.protocol) || !url.hostname || url.username || url.password || url.hash) {
+    throw new Error(`--${flag} requires a ${protocols.join(' or ')} URL without credentials or a fragment.`)
+  }
+  return value
+}
+
+export async function runUpdate({ flags, positional = [] }) {
+  const allowed = new Set(['name', 'ws', 'mcp-url', 'restart', 'host', 'backend'])
+  if (positional.length || Object.keys(flags).some(key => !allowed.has(key))) throw new Error('Usage: openvisio-agent update --name <agent> [--host <app-url>] [--backend <url>] [--ws <url>] [--mcp-url <url>] [--restart]')
+  if (typeof flags.name !== 'string' || !flags.name.trim()) throw new Error('Missing --name <agent>.')
+  if (flags.restart !== undefined && flags.restart !== true) throw new Error('--restart does not take a value.')
+  if (flags.restart && process.platform === 'win32') throw new Error('--restart requires macOS or Linux. Omit it and restart the foreground watcher yourself.')
+  const slug = slugify(flags.name)
+  let saved = readConfig(slug)
+  if (!saved || typeof saved !== 'object' || Array.isArray(saved)) throw new Error(`No readable configuration for "${slug}". Run connect first.`)
+  if (flags.ws !== undefined && saved.mode !== 'backend') throw new Error('--ws is supported only for backend agents.')
+  let next = { ...saved }
+  if (flags.backend !== undefined) {
+    if (saved.mode !== 'backend') throw new Error('--backend is supported only for backend agents.')
+    next.backend = stripSlash(endpoint(flags.backend, 'backend', ['https:', 'http:']))
+    const target = new URL(next.backend)
+    if (target.search || (target.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(target.hostname))) throw new Error('--backend requires HTTPS (or local HTTP), without a query.')
+  }
+  if (flags.host !== undefined) next.setupHost = endpoint(flags.host, 'host', ['http:', 'https:'])
+  if (flags.ws === undefined && flags['mcp-url'] === undefined) {
+    const discovered = await fetchConnectionSettings(next)
+    next = { ...next, ...discovered }
+  }
+  if (flags.ws !== undefined) next.wsUrl = stripSlash(endpoint(flags.ws, 'ws', ['ws:', 'wss:']))
+  if (flags['mcp-url'] !== undefined) next.mcpUrl = endpoint(flags['mcp-url'], 'mcp-url', ['http:', 'https:'])
+
+  if (next.backend !== saved.backend) {
+    // Only an explicit --backend may migrate credentials to another API host.
+    // Automatic discovery still requires an exact backend match.
+    let response
+    try {
+      response = await fetch(`${next.backend}/projects`, {
+        headers: { accept: 'application/json', 'x-agent-api-key': saved.apiKey, 'x-agent-identifier': saved.identifier },
+        redirect: 'error', signal: AbortSignal.timeout(15000),
+      })
+    } catch { throw new Error('Could not verify credentials at the new backend. Saved settings are unchanged.') }
+    await response.body?.cancel()
+    if (!response.ok) throw new Error(`New backend rejected verification (HTTP ${response.status}). Saved settings are unchanged.`)
+  }
+  const current = readConfig(slug)
+  if (!current || current.apiKey !== saved.apiKey || current.identifier !== saved.identifier || current.backend !== saved.backend) throw new Error('Saved agent identity changed during update; retry the update.')
+  next = { ...current, backend: next.backend, wsUrl: next.wsUrl, mcpUrl: next.mcpUrl, ...(next.setupHost ? { setupHost: next.setupHost } : {}) }
+  saved = current
+
+  saveConnectionSettings({ slug, saved, next, registerClaude: true })
+  ok(`Updated connection settings for "${slug}".`)
+  if (flags.restart) {
+    const { installService } = await import('./watch.mjs')
+    installService({ slug, workdir: next.workspace || '', throwOnError: true })
+  } else {
+    info('Running watchers keep their current endpoints until restarted.')
+    info(`Background watcher: openvisio-agent watch --name ${slug} --install`)
+    info(`Foreground watcher: stop it, then run openvisio-agent watch --name ${slug}`)
+  }
+}
+
+export function saveConnectionSettings({ slug, saved, next, registerClaude = false, stateDir = OV_DIR }) {
+  const mcpChanged = next.mcpUrl !== saved.mcpUrl
+  const wsChanged = next.wsUrl !== saved.wsUrl
+  const backendChanged = next.backend !== saved.backend
+  // Prepare every local file before changing anything. Preserve other servers
+  // and settings in the agent's scoped MCP configuration.
+  let scoped
+  let scopedPath
+  let headers
+  if (mcpChanged) {
+    headers = saved.mode === 'backend'
+      ? { 'x-agent-api-key': saved.apiKey, 'x-agent-identifier': saved.identifier }
+      : { Authorization: saved.key ? `Bearer ${saved.key}` : '' }
+    if (Object.values(headers).some(value => typeof value !== 'string' || !value)) throw new Error('Saved agent credentials are incomplete. Run connect first.')
+    if (saved.mcpConfig || !saved.agent || saved.agent === 'claude') {
+      scopedPath = saved.mcpConfig || join(stateDir, `${slug}-team.mcp.json`)
+      scoped = existsSync(scopedPath) ? JSON.parse(readFileSync(scopedPath, 'utf8')) : {}
+      scoped = { ...scoped, mcpServers: { ...scoped.mcpServers, 'openvisio-team': {
+        ...scoped.mcpServers?.['openvisio-team'], type: 'http', url: next.mcpUrl, headers,
+      } } }
+      next.mcpConfig = scopedPath
+    }
+  }
+  const envPath = join(stateDir, `${slug}.env`)
+  let envText
+  if ((wsChanged || backendChanged) && existsSync(envPath)) {
+    envText = readFileSync(envPath, 'utf8')
+    for (const [key, value] of [...(wsChanged ? [['OPENVISIO_AGENT_WS_URL', next.wsUrl]] : []), ...(backendChanged ? [['OPENVISIO_API_URL', next.backend]] : [])]) {
+      const assignment = `${key}='${value.replace(/'/g, "'\\''")}'`
+      let replaced = false
+      envText = envText.split(/\r?\n/).map(line => {
+        if (!new RegExp(`^\\s*(?:export\\s+)?${key}=`).test(line)) return line
+        replaced = true
+        return assignment
+      }).join('\n')
+      if (!replaced) envText = envText.replace(/\n?$/, '\n') + assignment + '\n'
+    }
+  }
+
+  // Claude also exposes the team MCP in interactive sessions at user scope.
+  // Report errors without printing credential-bearing arguments.
+  if (registerClaude && mcpChanged && (!saved.agent || saved.agent === 'claude')) {
+    const claude = onPath('claude')
+    if (!claude) throw new Error('Claude Code is not on PATH; install it before updating its MCP registration.')
+    spawnSync(claude, ['mcp', 'remove', 'openvisio-team', '-s', 'user'], { stdio: 'ignore' })
+    spawnSync(claude, ['mcp', 'remove', 'openvisio-team', '-s', 'local'], { stdio: 'ignore' })
+    const headerArgs = Object.entries(headers).flatMap(([key, value]) => ['--header', `${key}: ${value}`])
+    const result = spawnSync(claude, ['mcp', 'add', '--scope', 'user', '--transport', 'http', 'openvisio-team', next.mcpUrl, ...headerArgs], { stdio: 'ignore' })
+    if (result.status !== 0) throw new Error('Could not update the Claude MCP registration. Saved agent configuration is unchanged; retry the update after fixing Claude Code.')
+  }
+  if (scoped) writeJson(scopedPath, scoped, true)
+  if (envText !== undefined) {
+    const temporary = `${envPath}.${randomUUID()}.tmp`
+    try {
+      writeFileSync(temporary, envText, { flag: 'wx', mode: 0o600 })
+      renameSync(temporary, envPath)
+    } finally {
+      try { unlinkSync(temporary) } catch (error) { if (error.code !== 'ENOENT') throw error }
+    }
+  }
+  writeJson(join(stateDir, `${slug}.json`), next, true)
+  return next
+}

package/src/watch.mjs

@@ -44,6 +44,8 @@ import { startStudioInBackground } from './studio-cli.mjs'
 import { toolData } from './team-data.mjs'
 import { REPORT_ROUTING_PROMPT, reportChannelSelection } from './report-routing.mjs'
 import { runtimeProvider, supportedRuntimeList } from './runtime-providers.mjs'
+import { DEFAULT_SETUP_HOST, fetchConnectionSettings, createConnectionRefresh } from './connection-discovery.mjs'
+import { saveConnectionSettings } from './update.mjs'
 
 function runtimeJournal(options, supplied) {
   let journal
@@ -279,15 +281,15 @@ function acquireSingleInstance(key) {
 
 export async function runWatch({ flags }) {
   const slug = flags.name ? slugify(String(flags.name)) : null
-  const saved = slug ? readConfig(slug) : null
+  let saved = slug ? readConfig(slug) : null
   const claude = String(flags.claude || onPath('claude') || 'claude')
-  const mcpConfig = String(flags['mcp-config'] || (saved && saved.mcpConfig) || '')
+  let mcpConfig = String(flags['mcp-config'] || (saved && saved.mcpConfig) || '')
   // Which coding-agent runtime drives the cycles. Claude keeps its native stream;
   // ACP-capable runtimes share the Mastra harness. Default claude.
   const agent = String(flags.agent || flags.runtime || (saved && saved.agent) || 'claude').toLowerCase()
   const provider = runtimeProvider(agent)
   if (!provider) fail(`Unknown --agent "${agent}". Supported runtimes: ${supportedRuntimeList()}.`)
-  const mcpUrl = String(flags['mcp-url'] || (saved && saved.mcpUrl) || '')
+  let mcpUrl = String(flags['mcp-url'] || (saved && saved.mcpUrl) || '')
   // Code mode is the DEFAULT: an agent lives on the user's laptop and should just be
   // able to work across the org's repos with no per-repo setup. So `workdir` resolves
   // to (in order) an explicit --workdir/--workspace, the saved workspace, or the
@@ -329,6 +331,16 @@ export async function runWatch({ flags }) {
     process.on('exit', () => { try { lock.release && lock.release() } catch { /* noop */ } })
   }
 
+  if (saved?.mode === 'backend' && !flags.install && !flags.ws && !flags['mcp-url'] && !flags.backend && !flags.key && !flags.id) {
+    try {
+      const next = { ...saved, ...await fetchConnectionSettings(saved) }
+      if (next.wsUrl !== saved.wsUrl || next.mcpUrl !== saved.mcpUrl || next.setupHost !== saved.setupHost) saveConnectionSettings({ slug, saved, next })
+      saved = next
+      mcpUrl = String(saved.mcpUrl || '')
+      mcpConfig = String(flags['mcp-config'] || saved.mcpConfig || '')
+    } catch { info('Connection discovery unavailable; using the last saved endpoints.') }
+  }
+
   // Backend agents (connect --backend) drive autonomy over a real-time WS instead
   // of REST-polling the frontend relay. Detected by the saved mode / a --ws flag.
   const backendMode = (saved && saved.mode === 'backend') || !!flags.ws
@@ -342,7 +354,8 @@ 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', name: String(saved?.name || slug || identifier), claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug: !!flags.debug })
+    const setupHost = flags.ws || flags['mcp-url'] || flags.backend || flags.key || flags.id ? '' : (saved?.setupHost || DEFAULT_SETUP_HOST)
+    return loopBackendWs({ backend, wsUrl, apiKey, identifier, setupHost, 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) || '')
@@ -611,7 +624,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, name, claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug }, dependencies = {}) {
+export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, setupHost, 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
@@ -632,6 +645,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   const cycleContext = new AsyncLocalStorage()
   emit('watcher.started', { status: 'running', model, chatModel, workdir: workdir || '' })
   let handle = null
+  let connectionRefresh = null
   // Activity belongs to an individual cycle. Independent ticket workers must
   // not clear or overwrite each other's status targets.
   const replyStatusTargets = new Set()
@@ -767,7 +781,9 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
         const runner = replyRunners.acquire(key, { key, canCoordinate: item.kind === 'coord' })
         activeReplyRunners.add(runner)
         item.control.runner = runner
-        try { return await cycleContext.run({ cycleId: item.control.cycleId }, () => executeCycle(item.kind, item.context, item.targetChannels, item.taskRef, item.delivery, runner, item.control, '')) }
+        try { return await cycleContext.run({ cycleId: item.control.cycleId }, () => item.delivery?.watcherOwned
+          ? executeRecoverableCycle(item, runner)
+          : executeCycle(item.kind, item.context, item.targetChannels, item.taskRef, item.delivery, runner, item.control, '')) }
         finally { replyRunners.release(key); activeReplyRunners.delete(runner); item.control.runner = null }
       },
       onError: (error, item) => {
@@ -952,7 +968,8 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       handle?.subscribeOrganization?.(selfOrganizationId)
     }
   }
-  const mcpClient = dependencies.mcpClient || createMcpHttpClient({ url: mcpUrl, apiKey, identifier, clientVersion: '0.18.5', log })
+  const makeMcpClient = dependencies.createMcpClient || createMcpHttpClient
+  let mcpClient = dependencies.mcpClient || makeMcpClient({ url: mcpUrl, apiKey, identifier, clientVersion: '0.18.5', log })
   const callMcpTool = (name, args = {}) => {
     if (stopping) return Promise.reject(new Error('Watcher is stopping'))
     const toolCallId = `${journal.runId}:mcp:${++mcpSequence}`
@@ -964,6 +981,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       return result
     }, (error) => {
       emit('tool.finished', { ...metadata, status: 'failed' })
+      void connectionRefresh?.check()
       throw error
     }))
   }
@@ -1008,15 +1026,18 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     // The transport owns cache invalidation after a session reset. Do not keep
     // an independent name cache that can outlive its advertised capabilities.
     if (mcpToolDiscoveryPromise) return mcpToolDiscoveryPromise
-    mcpToolDiscoveryPromise = mcpClient.listTools(refresh).then((tools) => {
+    const client = mcpClient
+    const discovery = client.listTools(refresh).then((tools) => {
       const names = new Set(tools.map((tool) => String(tool?.name || '')).filter(Boolean))
+      if (client !== mcpClient) return names
       const changed = !mcpToolNames || names.size !== mcpToolNames.size || [...names].some((name) => !mcpToolNames.has(name))
       mcpToolNames = names
       const required = ['list_agents', 'list_projects', 'list_tasks', 'get_ticket', 'update_ticket', 'post_message']
       const missing = required.filter((name) => !mcpToolNames.has(name))
       if (changed) log(`MCP tools ready (${mcpToolNames.size})${missing.length ? '; missing core tools: ' + missing.join(', ') : ''}`)
       return mcpToolNames
-    }).finally(() => { mcpToolDiscoveryPromise = null })
+    }).finally(() => { if (mcpToolDiscoveryPromise === discovery) mcpToolDiscoveryPromise = null })
+    mcpToolDiscoveryPromise = discovery
     return mcpToolDiscoveryPromise
   }
   // Nearby channel roots are optional. Their deadline must not discard an
@@ -1691,7 +1712,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       activity.clear(control.cycleId)
       const delayMs = recoveryDelays[attempt - 1]
       emit('cycle.recovering', { cycleId: control.cycleId, status: 'recovering', attempt, retryInMs: delayMs, reason: 'Runtime connection interrupted; preserving accepted work' })
-      log(`coding runtime connection interrupted; resuming attempt ${attempt + 1} in ${delayMs / 1000}s or on reconnect`)
+      log(`${item.kind === 'full' ? 'coding' : 'reply'} runtime connection interrupted; resuming attempt ${attempt + 1} in ${delayMs / 1000}s or on reconnect`)
       await new Promise((resolve) => {
         const wake = () => { clearTimeout(timer); recoveryWaiters.delete(wake); control.wakeRecovery = null; resolve() }
         // A known event-channel outage can last longer than the retry budget.
@@ -1857,11 +1878,11 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
         return
       }
       if (!cycleSucceeded(result)) {
-        if (kind === 'full' && interruptedRuntimeResult(result) && cycleControl.attempt <= recoveryDelays.length) return { ...result, transportInterrupted: true }
+        if ((kind === 'full' || delivery?.watcherOwned) && interruptedRuntimeResult(result) && cycleControl.attempt <= recoveryDelays.length) return { ...result, transportInterrupted: true }
         const outcome = result?.subtype || 'an unknown runtime error'
         const providerPause = agent === 'opencode' && ['rate_limited', 'authentication_error', 'model_unavailable'].includes(outcome)
           ? { kind, model: result.model || useModel, retryAt: outcome === 'rate_limited' ? Date.now() + 30 * 60_000 : null } : null
-        const providerMessage = providerPause && result.userMessage ? result.userMessage : outcome === 'rate_limited' ? 'The model provider is rate-limiting this request. Choose a model with available quota in Agent Studio, or retry once the limit resets.' : ''
+        const providerMessage = result?.userMessage || (outcome === 'rate_limited' ? 'The model provider is rate-limiting this request. Choose a model with available quota in Agent Studio, or retry once the limit resets.' : '')
         const resumeMessage = providerPause ? (outcome === 'rate_limited'
           ? " I'll retry this ticket after a 30-minute cooldown, or when its model or ticket changes."
           : " I'll resume this ticket when its model or ticket changes; after fixing credentials, update the ticket to retry.") : " I've paused this revision until the ticket changes."
@@ -2048,17 +2069,51 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     }
   }
 
+  const commentProjectReads = new Map()
+  const resolveCommentProject = (ticketId) => {
+    const key = String(ticketId)
+    if (commentProjectReads.has(key)) return commentProjectReads.get(key)
+    const pending = (async () => {
+      const data = toolData(await callMcpReadWithRetry('list_projects'), 'list_projects')
+      const projects = Array.isArray(data.projects) ? data.projects : []
+      const matches = await mapConcurrent(projects.filter(project => validBackendId(project?.id)), 3, async project => {
+        const tasks = await loadProjectTickets({
+          projectId: Number(project.id),
+          read: async (name, args) => toolData(await callMcpReadWithRetry(name, args), name),
+          listTools: () => mcpClient.listTools(),
+          matches: task => String(task.id) === key,
+        })
+        return tasks.some(task => String(task.id) === key) ? Number(project.id) : null
+      })
+      const ids = [...new Set(matches.filter(id => id != null))]
+      if (ids.length !== 1) throw new Error('Could not resolve one authoritative project for this task comment.')
+      return ids[0]
+    })().finally(() => commentProjectReads.delete(key))
+    commentProjectReads.set(key, pending)
+    return pending
+  }
+
   const handleTaskComment = async (raw) => {
     const event = taskCommentFromEvent(raw)
-    const projectId = event?.projectId
+    let projectId = event?.projectId
     const ticketId = event?.taskId
     const comment = event?.comment
     const commentId = comment && (comment.id ?? comment.comment_id ?? comment.commentId)
     const text = String(comment?.content ?? comment?.body ?? comment?.text ?? comment?.message ?? '').replace(/\s+/g, ' ').trim()
-    if (!validBackendId(projectId) || !validBackendId(ticketId) || !validBackendId(commentId) || !text) {
+    if ((projectId != null && !validBackendId(projectId)) || !validBackendId(ticketId) || !validBackendId(commentId) || !text) {
       log('task:comment missing project/task/comment identity or content — ignored')
       return { status: 'ignored-malformed' }
     }
+    // Backend comment rows carry task_id but not project_id. Some broadcasts
+    // likewise omit the project. Resolve it from authenticated task listings;
+    // never infer it from another event or assume the first project is correct.
+    if (projectId == null) {
+      try { projectId = await resolveCommentProject(ticketId) }
+      catch (error) {
+        log(`task:comment project lookup failed for ticket #${ticketId}: ` + (error?.message || error))
+        return { status: 'retry' }
+      }
+    }
     const sourceKey = `task-comment:${Number(projectId)}:${Number(ticketId)}:${Number(commentId)}`
     if (memory.has(sourceKey, 'received')) {
       log(`task:comment duplicate project=${projectId} ticket=${ticketId} comment=${commentId} — skipped`)
@@ -2095,6 +2150,9 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
         log(`task:comment ticket #${ticketId} is not assigned to this agent — ignored`)
         return { status: 'ignored-unassigned' }
       }
+      // Duplicate deliveries can share the asynchronous project/owner reads.
+      // Recheck immediately before reserving this source and starting work.
+      if (memory.has(sourceKey, 'received')) return { status: 'duplicate' }
       if (peer) {
         const meta = admitPeerTurn(memory.get(loopKey), text, target)
         if (!meta) return { status: 'ignored-peer-loop' }
@@ -2402,10 +2460,11 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   // recover channel mentions even when the backend omits targeted dispatch.
   // All conversation event types share recipient, ownership and deduplication guards.
   log('up — backend WS watcher on ' + wsUrl + (canCode ? ' [code: ' + workdir + ']' : ''))
-  handle = (dependencies.connect || connectAgentWs)({ wsUrl, apiKey, identifier, onEvent,
+  const connectEvents = () => (dependencies.connect || connectAgentWs)({ wsUrl, apiKey, identifier, onEvent,
     onDisconnect: () => {
       eventConnection = 'disconnected'
       emit('connection.disconnected', { status: 'disconnected', reason: 'Event connection lost; accepted work remains running' })
+      void connectionRefresh?.check()
     },
     onConnect: () => {
       if (stopping) return
@@ -2416,6 +2475,45 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
       queueMicrotask(() => { if (!stopping) void ensureSelfAgent() })
       if (autoStart) setTimeout(() => { if (!stopping) void reconcileBacklog() }, 250)
     }, log })
+  handle = connectEvents()
+
+  const refreshConnection = async (signal) => {
+    if (stopping || !setupHost) return
+    const latest = await (dependencies.fetchConnectionSettings || fetchConnectionSettings)({ mode: 'backend', backend, setupHost }, { signal })
+    if (stopping) return
+    const mcpChanged = latest.mcpUrl !== mcpUrl
+    const wsChanged = latest.wsUrl !== wsUrl
+    if (!mcpChanged && !wsChanged) return
+    // Re-read immediately before saving to preserve live Studio/model updates.
+    const saved = JSON.parse(readFileSync(join(stateDir, `${slug}.json`), 'utf8'))
+    if (saved.identifier !== identifier || saved.apiKey !== apiKey || stripSlash(saved.backend) !== stripSlash(backend)) throw new Error('Saved agent identity changed; reconnect explicitly.')
+    saveConnectionSettings({ slug, saved, next: { ...saved, ...latest }, stateDir })
+    if (mcpChanged) {
+      mcpUrl = latest.mcpUrl
+      runnerOptions.mcpUrl = mcpUrl
+      mcpClient = makeMcpClient({ url: mcpUrl, apiKey, identifier, clientVersion: '0.18.5', log })
+      mcpToolNames = null
+      mcpToolDiscoveryPromise = null
+      mcpToolDiscoveryWarned = false
+      // Retire idle sessions now and active sessions when they finish. Never
+      // cancel accepted work just because deployment configuration changed.
+      workRunners.invalidate()
+      replyRunners.invalidate()
+      void discoverMcpTools().catch(() => {})
+    }
+    if (wsChanged) {
+      wsUrl = latest.wsUrl
+      handle?.close()
+      eventConnection = 'disconnected'
+      handle = connectEvents()
+      if (selfOrganizationId != null) handle?.subscribeOrganization?.(selfOrganizationId)
+    } else if (autoStart && mcpChanged) void reconcileBacklog()
+    log('Connection settings refreshed from agent setup; new sessions use the current endpoints.')
+  }
+  if (setupHost) {
+    connectionRefresh = createConnectionRefresh({ refresh: refreshConnection, log, ...dependencies.connectionRefreshOptions })
+    if (autoStart) void connectionRefresh.check()
+  }
 
   let authorizationProbeBusy = false
   const legacyAuthorizationChecks = new Set()
@@ -2503,6 +2601,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     closePromise = (async () => {
       clearInterval(authorizationTimer)
       clearInterval(deliveryTimer)
+      await connectionRefresh?.close()
       modelSettingsWatcher?.close()
       if (introTimer) clearTimeout(introTimer)
       try { handle?.close() } catch { /* already disconnected */ }
@@ -2528,6 +2627,7 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   return {
     done, close, receive: onEvent, reconcile: () => stopping ? Promise.resolve() : trackOperation(reconcileBacklog()),
     resumeAuthorizations: resumeReadyAuthorizations, retryDeliveries: flushPendingReplies,
+    refreshConnection: () => connectionRefresh?.check() || Promise.resolve(),
     get pending() { return queues.work.size + queues.reply.size + mentionIntake.size },
   }
 }

package/studio/app.mjs

@@ -10,6 +10,29 @@ const timeValue = value => Number.isFinite(Date.parse(value)) ? Date.parse(value
 const agentId = item => text(item?.identifier || item?.id || item?.slug || 'unknown');
 const agentName = item => text(item?.name || item?.slug || item?.identifier || 'Unknown agent');
 
+export const credentialFields = ['name', 'identifier', 'apiKey', 'backend', 'mcpUrl', 'wsUrl', 'setupHost', 'agent'];
+
+export function parseAgentCredentials(value) {
+  let credentials;
+  const source = value.trim().replace(/^```(?:json)?\s*\n([\s\S]*?)\n```$/i, '$1');
+  try { credentials = JSON.parse(source); }
+  catch { throw new Error('Paste a complete JSON credentials object from OpenVisio → Copy credentials.'); }
+  if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials)) throw new Error('Credentials must be a JSON object.');
+  const result = {};
+  for (const key of credentialFields) {
+    const raw = credentials[key];
+    if (raw !== undefined && typeof raw !== 'string') throw new Error(`The ${key} field must be text.`);
+    const field = (raw || '').trim();
+    if (field.length > 4096 || /[\r\n\0]/.test(field)) throw new Error(`Enter a valid ${key}.`);
+    result[key] = field;
+  }
+  const missing = ['name', 'identifier', 'apiKey', 'backend'].filter(key => !result[key]);
+  if (missing.length) throw new Error(`Credentials are missing: ${missing.join(', ')}. Copy the complete object from OpenVisio.`);
+  result.agent = result.agent.toLowerCase() || 'claude';
+  if (!['claude', 'codex', 'opencode', 'gemini', 'qwen'].includes(result.agent)) throw new Error('Choose a supported runtime: Claude Code, Codex, OpenCode, Gemini CLI, or Qwen Code.');
+  return result;
+}
+
 export function normalizeStatus(value, fallback = 'observed') {
   const status = text(value).toLowerCase().replaceAll('-', '_');
   if (['active', 'running', 'started', 'ready', 'in_progress', 'working', 'online', 'preflight'].includes(status)) return 'active';
@@ -400,6 +423,7 @@ function initializeStudio() {
     if (!agent || state.snapshot.demo) return;
     $('model-settings-agent').textContent = `${agentName(agent)} · Models`;
     $('open-model-settings').disabled = !agent.settingsEditable;
+    $('open-connection-update').disabled = !agent.settingsEditable || watcherChanging;
     $('open-agent-removal').disabled = !agent.removable;
     const watcherRunning = agent.status === 'online' || agent.watcherAlive === true;
     $('toggle-watcher').querySelector('span').textContent = watcherRunning ? 'Stop watcher' : 'Start watcher';
@@ -824,30 +848,37 @@ function initializeStudio() {
 
   $('server-address').textContent = location.host;
   let connectingAgent = false;
-  const credentialFields = ['name', 'identifier', 'apiKey', 'backend', 'mcpUrl', 'wsUrl', 'agent'];
   $('open-agent-connect').addEventListener('click', () => {
     $('agent-connect-error').hidden = true;
     $('agent-connect-dialog').showModal();
   });
   $('close-agent-connect').addEventListener('click', () => { if (!connectingAgent) $('agent-connect-dialog').close(); });
   $('agent-connect-dialog').addEventListener('cancel', event => { if (connectingAgent) event.preventDefault(); });
-  $('agent-connect-dialog').addEventListener('close', () => $('agent-connect-form').reset());
-  $('connect-credentials').addEventListener('input', () => {
-    if (!$('connect-credentials').value.trim()) return;
+  $('agent-connect-dialog').addEventListener('close', () => {
+    $('agent-connect-form').reset();
+    $('connect-import-status').textContent = 'Paste the complete object, then choose Use credentials to review the fields.';
+  });
+  const importCredentials = () => {
+    if (connectingAgent) return false;
     try {
-      const credentials = JSON.parse($('connect-credentials').value);
-      if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials)) throw new Error();
-      for (const key of credentialFields) $('connect-' + key).value = typeof credentials[key] === 'string' ? credentials[key] : key === 'agent' ? 'claude' : '';
+      const credentials = parseAgentCredentials($('connect-credentials').value);
+      for (const key of credentialFields) $('connect-' + key).value = credentials[key];
       $('connect-credentials').value = '';
       $('agent-connect-error').hidden = true;
-    } catch {
-      $('agent-connect-error').textContent = 'Paste the complete credentials from Copy credentials in OpenVisio, or enter the fields below.';
+      $('connect-import-status').textContent = 'Credentials imported. Review the fields, then choose Verify and connect.';
+      return true;
+    } catch (error) {
+      $('agent-connect-error').textContent = error.message;
       $('agent-connect-error').hidden = false;
+      return false;
     }
-  });
+  };
+  $('import-agent-credentials').addEventListener('click', importCredentials);
   $('agent-connect-form').addEventListener('submit', async event => {
     event.preventDefault();
     if (connectingAgent) return;
+    if ($('connect-credentials').value.trim() && !importCredentials()) return;
+    if (!$('agent-connect-form').reportValidity()) return;
     connectingAgent = true;
     $('save-agent-connect').disabled = true;
     $('close-agent-connect').disabled = true;
@@ -966,6 +997,75 @@ function initializeStudio() {
       scheduleRender();
     }
   }
+  let connectionAgent = null, connectionPlan = null, connectionBusy = false;
+  const connectionBusyState = busy => {
+    connectionBusy = busy;
+    for (const id of ['connection-update-host', 'connection-update-object', 'check-connection-update', 'close-connection-update']) $(id).disabled = busy;
+    $('apply-connection-update').disabled = busy || !connectionPlan;
+  };
+  const invalidateConnectionPlan = () => {
+    connectionPlan = null;
+    $('connection-update-preview').hidden = true;
+    $('apply-connection-update').disabled = true;
+    $('connection-update-status').textContent = '';
+    $('connection-update-error').hidden = true;
+  };
+  $('open-connection-update').addEventListener('click', () => {
+    connectionAgent = state.model.agents.find(agent => agentId(agent) === state.selectedAgent);
+    if (!connectionAgent?.settingsEditable) return;
+    $('connection-update-form').reset();
+    invalidateConnectionPlan();
+    $('connection-update-title').textContent = `Update ${agentName(connectionAgent)} connection`;
+    $('connection-update-dialog').showModal();
+    $('connection-update-form').requestSubmit();
+  });
+  $('close-connection-update').addEventListener('click', () => { if (!connectionBusy) $('connection-update-dialog').close(); });
+  $('connection-update-dialog').addEventListener('cancel', event => { if (connectionBusy) event.preventDefault(); });
+  $('connection-update-dialog').addEventListener('close', () => { $('connection-update-form').reset(); invalidateConnectionPlan(); });
+  for (const id of ['connection-update-host', 'connection-update-object']) $(id).addEventListener('input', invalidateConnectionPlan);
+  $('connection-update-form').addEventListener('submit', async event => {
+    event.preventDefault();
+    if (!connectionAgent || connectionBusy) return;
+    invalidateConnectionPlan();
+    connectionBusyState(true);
+    $('connection-update-status').textContent = 'Checking current connection URLs…';
+    try {
+      const input = { action: 'check', setupHost: $('connection-update-host').value.trim() || undefined };
+      const pasted = $('connection-update-object').value.trim();
+      if (pasted) {
+        let parsed;
+        try { parsed = JSON.parse(pasted.replace(/^```(?:json)?\s*\n([\s\S]*?)\n```$/i, '$1')); } catch { throw new Error('Paste a complete JSON connection object.'); }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('Paste a JSON connection object.');
+        input.settings = Object.fromEntries(['backend', 'mcpUrl', 'wsUrl', 'setupHost'].map(key => [key, parsed[key]]));
+        if (input.setupHost) input.settings.setupHost = input.setupHost;
+      }
+      connectionPlan = await settingsFetch(`/api/agents/${encodeURIComponent(connectionAgent.slug)}/connection`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input) });
+      $('connection-update-object').value = '';
+      $('connection-update-preview').textContent = JSON.stringify(connectionPlan.settings, null, 2);
+      $('connection-update-preview').hidden = false;
+      $('connection-update-status').textContent = connectionPlan.backendChanged ? 'The API backend has moved. Review the new URLs before applying. Your saved key will be verified against this backend.' : 'Review the current URLs, then apply and reconnect.';
+    } catch (error) {
+      $('connection-update-status').textContent = '';
+      $('connection-update-error').textContent = error.message;
+      $('connection-update-error').hidden = false;
+    } finally { connectionBusyState(false); }
+  });
+  $('apply-connection-update').addEventListener('click', async () => {
+    if (!connectionPlan || connectionBusy) return;
+    connectionBusyState(true);
+    $('connection-update-error').hidden = true;
+    $('connection-update-status').textContent = 'Verifying and applying connection settings…';
+    try {
+      const result = await settingsFetch(`/api/agents/${encodeURIComponent(connectionAgent.slug)}/connection`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ action: 'apply', ...connectionPlan }) });
+      connectionPlan = null;
+      $('connection-update-status').textContent = result.message;
+      receive(await settingsFetch('/api/snapshot'), true);
+    } catch (error) {
+      $('connection-update-status').textContent = '';
+      $('connection-update-error').textContent = error.message;
+      $('connection-update-error').hidden = false;
+    } finally { connectionBusyState(false); }
+  });
   $('toggle-watcher').addEventListener('click', () => void changeWatcher($('toggle-watcher').dataset.action || 'start'));
   $('restart-watcher').addEventListener('click', () => void changeWatcher('restart'));
   $('pause-button').addEventListener('click', () => {

package/studio/index.html

@@ -65,26 +65,46 @@
         <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 model-settings-actions-row"><button id="toggle-watcher" class="button studio-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-power"/></svg><span>Start watcher</span></button><button id="restart-watcher" class="button studio-action restart-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-refresh"/></svg><span>Restart watcher</span></button><button id="open-model-settings" class="button studio-action settings-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-sliders"/></svg><span>Model settings</span></button><button id="open-agent-removal" class="button studio-action remove-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-user-minus"/></svg><span>Remove agent</span></button></div>
+          <div class="header-actions model-settings-actions-row"><button id="toggle-watcher" class="button studio-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-power"/></svg><span>Start watcher</span></button><button id="restart-watcher" class="button studio-action restart-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-refresh"/></svg><span>Restart watcher</span></button><button id="open-connection-update" class="button studio-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-refresh"/></svg><span>Update connection</span></button><button id="open-model-settings" class="button studio-action settings-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-sliders"/></svg><span>Model settings</span></button><button id="open-agent-removal" class="button studio-action remove-action" type="button"><svg class="icon" aria-hidden="true"><use href="#i-user-minus"/></svg><span>Remove agent</span></button></div>
         </section>
         <dialog id="agent-connect-dialog" aria-labelledby="agent-connect-title">
-          <form id="agent-connect-form" class="model-settings-form" autocomplete="off">
+          <form id="agent-connect-form" class="model-settings-form" autocomplete="off" novalidate>
             <div class="section-heading"><h2 id="agent-connect-title">Connect agent</h2><button id="close-agent-connect" class="button" type="button">Cancel</button></div>
             <p>Copy credentials from OpenVisio after registering your agent, then paste them below. Or enter the fields yourself.</p>
-            <label for="connect-credentials">Paste credentials</label>
-            <textarea id="connect-credentials" rows="3" spellcheck="false" placeholder="Paste the copied credentials here"></textarea>
+            <label for="connect-credentials">Paste generated credentials object</label>
+            <textarea id="connect-credentials" rows="5" spellcheck="false" aria-describedby="connect-import-status" placeholder='Paste the JSON object from OpenVisio → Copy credentials'></textarea>
+            <button id="import-agent-credentials" class="button" type="button">Use credentials</button>
+            <p id="connect-import-status" role="status">Paste the complete object, then choose Use credentials to review the fields.</p>
             <label for="connect-name">Local agent name</label><input id="connect-name" type="text" required maxlength="4096" spellcheck="false">
             <label for="connect-identifier">Agent identifier</label><input id="connect-identifier" type="text" required maxlength="4096" spellcheck="false">
             <label for="connect-apiKey">API key</label><input id="connect-apiKey" type="password" required maxlength="4096" spellcheck="false">
             <label for="connect-backend">Backend URL</label><input id="connect-backend" type="url" required maxlength="4096" spellcheck="false">
-            <label for="connect-mcpUrl">MCP URL</label><input id="connect-mcpUrl" type="url" required maxlength="4096" spellcheck="false">
-            <label for="connect-wsUrl">WebSocket URL</label><input id="connect-wsUrl" type="url" required maxlength="4096" spellcheck="false">
+            <label for="connect-mcpUrl">MCP URL (optional)</label><input id="connect-mcpUrl" type="url" maxlength="4096" spellcheck="false">
+            <label for="connect-wsUrl">WebSocket URL (optional)</label><input id="connect-wsUrl" type="url" maxlength="4096" spellcheck="false">
+            <p>Missing connection URLs are retrieved from your OpenVisio app when you connect.</p>
+            <label for="connect-setupHost">OpenVisio app URL (optional)</label><input id="connect-setupHost" type="url" maxlength="4096" placeholder="https://openvisio.io" spellcheck="false">
             <label for="connect-agent">Runtime</label><select id="connect-agent"><option value="claude">Claude Code</option><option value="codex">Codex</option><option value="opencode">OpenCode</option><option value="gemini">Gemini CLI</option><option value="qwen">Qwen Code</option></select>
             <p>Install and sign in to your chosen runtime on this computer. After connecting, select the agent and choose Start watcher.</p>
             <p id="agent-connect-error" role="alert" hidden></p>
             <div class="model-settings-actions"><button id="save-agent-connect" class="button primary" type="submit">Verify and connect</button></div>
           </form>
         </dialog>
+        <dialog id="connection-update-dialog" aria-labelledby="connection-update-title">
+          <form id="connection-update-form" class="model-settings-form" autocomplete="off">
+            <div class="section-heading"><h2 id="connection-update-title">Update connection</h2><button id="close-connection-update" class="button" type="button">Close</button></div>
+            <p>Get the latest connection URLs using this agent’s saved credentials. Applying the update restarts the watcher; active work must finish first.</p>
+            <label for="connection-update-host">OpenVisio app URL (optional)</label>
+            <input id="connection-update-host" type="url" placeholder="Use the saved app URL" maxlength="4096">
+            <label for="connection-update-object">Latest connection object (optional)</label>
+            <textarea id="connection-update-object" rows="4" spellcheck="false" placeholder="If automatic discovery is unavailable, paste the connection JSON copied from OpenVisio."></textarea>
+            <p>Your saved API key and agent identity are kept. Only connection URLs are imported.</p>
+            <button id="check-connection-update" class="button" type="submit">Check connection</button>
+            <pre id="connection-update-preview" hidden></pre>
+            <p id="connection-update-status" role="status"></p>
+            <p id="connection-update-error" role="alert" hidden></p>
+            <div class="model-settings-actions"><button id="apply-connection-update" class="button primary" type="button" disabled>Apply and reconnect</button></div>
+          </form>
+        </dialog>
         <dialog id="model-settings-dialog" aria-labelledby="model-settings-title">
           <form id="model-settings-form" class="model-settings-form">
             <div class="section-heading"><h2 id="model-settings-title">Model settings</h2><button id="close-model-settings" class="button" type="button" aria-label="Close model settings">Close</button></div>

package/studio/style.css

@@ -368,8 +368,8 @@
   #toggle-watcher[data-action="stop"] .icon, .remove-action .icon { color: var(--destructive); }
   .restart-action .icon { color: var(--orange); }
   .settings-action .icon { color: var(--purple); }
-  #agent-connect-dialog, #model-settings-dialog, #agent-removal-dialog { width: min(500px, calc(100vw - 32px)); max-height: calc(100dvh - 32px); margin: auto; padding: 24px; overflow-y: auto; border: 1px solid var(--border); border-radius: 24px; color: var(--ink); background: var(--surface, white); box-shadow: 0 24px 80px #0002; }
-  #agent-connect-dialog::backdrop, #model-settings-dialog::backdrop, #agent-removal-dialog::backdrop { background: #0005; }
+  #agent-connect-dialog, #model-settings-dialog, #agent-removal-dialog, #connection-update-dialog { width: min(500px, calc(100vw - 32px)); max-height: calc(100dvh - 32px); margin: auto; padding: 24px; overflow-y: auto; border: 1px solid var(--border); border-radius: 24px; color: var(--ink); background: var(--surface, white); box-shadow: 0 24px 80px #0002; }
+  #agent-connect-dialog::backdrop, #model-settings-dialog::backdrop, #agent-removal-dialog::backdrop, #connection-update-dialog::backdrop { background: #0005; }
   .model-settings-form { display: grid; gap: 12px; }
   .model-settings-form h2 { font-size: 17px; font-weight: 500; }
   .model-settings-form p { margin: 0; font-size: 12px; line-height: 1.6; color: var(--muted); }
@@ -377,7 +377,7 @@
   .model-settings-form label span { font-size: 12px; color: var(--muted); }
   .model-settings-form input, .model-settings-form textarea, .model-settings-form select { width: 100%; min-width: 0; padding: 11px 14px; border: 1px solid var(--border); border-radius: 18px; background: transparent; color: var(--ink); font-size: 13px; }
   .model-settings-actions { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 12px; margin-top: 8px; }
-  #agent-connect-error, #model-settings-error, #agent-removal-error { color: #9f3030; }
+  #agent-connect-error, #model-settings-error, #agent-removal-error, #connection-update-error { color: #9f3030; }
   @media (max-width: 640px) {
     .page-header { flex-direction: column; }
     .header-actions { flex-direction: row; flex-wrap: wrap; align-items: center; padding: 0; gap: 8px; }
@@ -406,3 +406,5 @@
   }
   @media (prefers-reduced-motion: reduce) { *, *::before, *::after { transition-duration: 0s !important; animation-duration: 0s !important; scroll-behavior: auto !important; } }
 }
+
+  #connection-update-preview { white-space: pre-wrap; overflow-wrap: anywhere; min-width: 0; font-size: 12px; line-height: 1.6; }