openvisio-agent 0.25.17 → 0.25.18

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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

@@ -58,6 +58,25 @@ 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.app`, 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.
+
+`--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/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>] [--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,14 @@ 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.app).
+  Watchers refresh at startup and after connection failures, with no periodic poll.
+  Explicit --ws/--mcp-url values remain available for manual updates.
+  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 +219,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.app' : 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 +272,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 +328,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.18",
   "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,45 @@
+export const DEFAULT_SETUP_HOST = 'https://openvisio.app'
+
+// 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 async function fetchConnectionSettings(saved, { fetchImpl = fetch, signal } = {}) {
+  if (saved.mode !== 'backend') throw new Error('Automatic connection discovery requires a backend agent.')
+  const setupHost = checkedUrl(saved.setupHost || DEFAULT_SETUP_HOST, ['https:', 'http:'])
+  const backend = checkedUrl(saved.backend, ['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 || checkedUrl(data.backend, ['https:', 'http:']) !== backend) throw new Error('Setup configuration does not match the saved backend. Use --host with this agent’s OpenVisio app URL.')
+  return { setupHost, wsUrl: checkedUrl(data.wsUrl, ['wss:', 'ws:']), mcpUrl: checkedUrl(data.mcpUrl, ['https:', 'http:']) }
+}
+
+// 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/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

@@ -25,6 +25,7 @@ export async function connectStudioAgent({ stateDir, input, fetchImpl = fetch })
   const backend = url('backend', ['https:', 'http:'])
   const mcpUrl = url('mcpUrl', ['https:', 'http:'])
   const wsUrl = url('wsUrl', ['wss:', 'ws:'])
+  const setupHost = field('setupHost', false) ? url('setupHost', ['https:', 'http:']) : 'https://openvisio.app'
   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 +41,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/update.mjs

@@ -0,0 +1,111 @@
+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'])
+  if (positional.length || Object.keys(flags).some(key => !allowed.has(key))) throw new Error('Usage: openvisio-agent update --name <agent> [--host <app-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.host !== undefined) next.setupHost = endpoint(flags.host, 'host', ['http:', 'https:'])
+  if (flags.ws === undefined && flags['mcp-url'] === undefined) {
+    const discovered = await fetchConnectionSettings(next)
+    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 discovery; retry the update.')
+    saved = current
+    next = { ...current, ...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:'])
+
+  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
+  // 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 && existsSync(envPath)) {
+    const lines = readFileSync(envPath, 'utf8').split(/\r?\n/)
+    const assignment = `OPENVISIO_AGENT_WS_URL='${next.wsUrl.replace(/'/g, "'\\''")}'`
+    let replaced = false
+    envText = lines.map(line => {
+      if (!/^\s*(?:export\s+)?OPENVISIO_AGENT_WS_URL=/.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()
@@ -952,7 +966,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 +979,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 +1024,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
@@ -2402,10 +2421,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 +2436,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 +2562,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 +2588,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

@@ -824,7 +824,7 @@ function initializeStudio() {
 
   $('server-address').textContent = location.host;
   let connectingAgent = false;
-  const credentialFields = ['name', 'identifier', 'apiKey', 'backend', 'mcpUrl', 'wsUrl', 'agent'];
+  const credentialFields = ['name', 'identifier', 'apiKey', 'backend', 'mcpUrl', 'wsUrl', 'setupHost', 'agent'];
   $('open-agent-connect').addEventListener('click', () => {
     $('agent-connect-error').hidden = true;
     $('agent-connect-dialog').showModal();

package/studio/index.html

@@ -79,6 +79,7 @@
             <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-setupHost">OpenVisio app URL (optional)</label><input id="connect-setupHost" type="url" maxlength="4096" placeholder="https://openvisio.app" 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>