openvisio-agent 0.25.5 → 0.25.6

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## [0.25.6] — 2026-09-21
+
+- Keep healthy backend watchers event-driven after their connection recovery pass instead of polling every project for tasks and activity every 30 seconds.
+- Stop idle journal heartbeats, derive Studio liveness from watcher PID locks, and apply model-setting changes through filesystem notifications instead of two-second polling.
+- Add semantic icons and status colors to Agent Studio's watcher, model-settings, and agent-removal actions.
+
 ## [0.25.5] — 2026-09-21
 
 - Add Gemini CLI and Qwen Code as coding-agent providers through their native ACP modes.

package/README.md

@@ -81,7 +81,7 @@ The integration follows Mastra's [semantic memory](https://mastra.ai/docs/memory
 
 Model selections are stable. Exact IDs (including reasoning effort) are preserved. An unsuffixed ACP model may resolve once to the same model with `medium` effort; the watcher saves that exact selection. Unavailable selections produce an explicit error rather than switching generations or families. Claude versioned IDs are preserved, with automatic family fallbacks disabled. Codex uses the configured chat model for replies.
 
-Backend/BYO watchers reconcile immediately whenever the process starts or the WebSocket connects. A direct MCP session discovers and caches the backend's actual `tools/list` response, then uses available tools such as `list_agents`, `list_projects`, `list_tasks`, `list_task_types`, and `list_activity` to recover assigned tasks and recent mention activity missed while offline. Team discovery is shared by every runtime provider: structured MCP results and compact Markdown list envelopes are normalized once before the watcher resolves its project, identity, boards, tickets, or dedicated channel. Adding another model provider therefore reuses the same saved team connection and setup path instead of adding provider-specific project discovery. Optional actions such as ticket comments are used only when advertised; their absence cannot strand a completed ticket in a retry loop. The same zero-model check runs every 30 seconds as a safety net; a model starts only when pending work exists.
+Backend/BYO watchers reconcile once whenever the WebSocket starts or reconnects. A direct MCP session discovers and caches the backend's actual `tools/list` response, then uses available tools such as `list_agents`, `list_projects`, `list_tasks`, `list_task_types`, and `list_activity` to recover assigned tasks and recent mention activity missed while offline. Team discovery is shared by every runtime provider: structured MCP results and compact Markdown list envelopes are normalized once before the watcher resolves its project, identity, boards, tickets, or dedicated channel. Adding another model provider therefore reuses the same saved team connection and setup path instead of adding provider-specific project discovery. Optional actions such as ticket comments are used only when advertised; their absence cannot strand a completed ticket in a retry loop. After the recovery pass, the healthy event connection waits without polling MCP tools and starts a model only when work arrives.
 
 The backend MCP may be stateful or stateless. A successful initialize response without `Mcp-Session-Id` is accepted as stateless, so OpenCode agents do not stop with “MCP initialize returned no session id.” Each OpenCode lane keeps its MCP identity in a private per-agent config directory while the repository is supplied separately with `--dir`; stale workspace configuration therefore cannot swap one agent's credentials for another's. The generated remote configuration sends the agent headers directly, disables OAuth probing, and backend cycles never request relay-only inbox calls or MCP resource-discovery tools in place of team actions.
 
@@ -114,7 +114,7 @@ Authorization recovery checks paused repositories locally every two seconds and
 
 Fresh top-level messages belong in the agent’s dedicated channel; responses to existing requests stay in their source thread. The watcher resolves a unique exact identity/name match (including `agent-alex` and `alex-agent`) and never falls back to general. Use `connect ... --channel <id>` for a differently named dedicated channel. If it is missing or ambiguous, ticket results remain recorded and channel delivery stays pending; the watcher does not invent a channel-creation tool.
 
-Codex, OpenCode, Gemini CLI, and Qwen Code use Mastra ACP directly. OpenCode starts only for an accepted cycle and exits as soon as that cycle releases it, so the idle watcher does not retain an OpenCode child process. Other runtimes retain work sessions per ticket in a six-entry pool and reply sessions in an eight-entry pool; their idle sessions expire after five minutes, and active sessions cannot be evicted. Git snapshots are asynchronous, lightweight commands lazily load the watcher, and logs separate queue wait, preflight, first-event, and total runtime time. Projects reconcile with concurrency three and enqueue tickets before reading optional activity history. Coordination sessions can update the board without gaining repository access.
+Codex, OpenCode, Gemini CLI, and Qwen Code use Mastra ACP directly. OpenCode starts only for an accepted cycle and exits as soon as that cycle releases it, so the idle watcher does not retain an OpenCode child process. Other runtimes retain work sessions per ticket in a six-entry pool and reply sessions in an eight-entry pool; their idle sessions expire after five minutes, and active sessions cannot be evicted. Git snapshots are asynchronous, lightweight commands lazily load the watcher, and logs separate queue wait, preflight, first-event, and total runtime time. Studio reads watcher liveness from the local PID lock instead of requiring journal heartbeats, and model changes arrive through filesystem notifications. Projects reconcile with concurrency three and enqueue tickets before reading optional activity history. Coordination sessions can update the board without gaining repository access.
 
 Assignments use independent FIFO entries with stable-key duplicate suppression and bounded, worktree-aware concurrency. Backlog recovery uses the same ticket verification path as WebSocket events, and each queued ticket is checked again before a model starts. MCP calls have a 20-second deadline including response bodies; tool discovery is cached and paginated. Codex MCP failures retain a bounded, credential-redacted reason in the watcher log. Cancellation targets only its ACP session. Credentials and replay state use atomic file replacement; Mastra persists contextual memory in libSQL.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.25.5",
+  "version": "0.25.6",
   "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/scripts/certify.mjs

@@ -24,6 +24,7 @@ run('diff whitespace check', 'git', ['diff', '--check'], repo)
 const watcher = readFileSync(join(root, 'src', 'watch.mjs'), 'utf8')
 const events = readFileSync(join(root, 'src', 'events.mjs'), 'utf8')
 const memory = readFileSync(join(root, 'src', 'memory.mjs'), 'utf8')
+const journal = readFileSync(join(root, 'src', 'agent-journal.mjs'), 'utf8')
 const mcpHttp = readFileSync(join(root, 'src', 'mcp-http.mjs'), 'utf8')
 const opencodeConfig = readFileSync(join(root, 'src', 'opencode-config.mjs'), 'utf8')
 const codexConfig = readFileSync(join(root, 'src', 'codex-config.mjs'), 'utf8')
@@ -51,6 +52,8 @@ const assertions = [
   ['new follow-ups only deduplicate later replies', watcher.includes('repliesAfterSource(renderedAgentMessages') && watcher.includes('sourceMessageId: mid')],
   ['Mastra snapshots do not block the event loop', mastraHarness.includes('await execFileAsync') && !mastraHarness.includes('spawnSync')],
   ['OpenCode exits after work while the event watcher stays idle', runtimeProviders.includes("id: 'opencode'") && runtimeProviders.includes('idleSessionMs: 0') && watcher.includes('idleMs: runtimeIdleMs')],
+  ['healthy backend watchers do not poll projects while idle', watcher.includes('onConnect: () =>') && watcher.includes('void reconcileBacklog()') && !watcher.includes('taskProbeTimer') && !watcher.includes('taskProbeStartTimer')],
+  ['idle watchers use event notifications without journal or settings polling', watcher.includes('watchFs(stateDir') && !watcher.includes('modelSettingsTimer') && !journal.includes("emit('runtime.heartbeat'")],
   ['ticket pickup precedes optional activity reads', watcher.indexOf("await handleTaskSignal('task:assigned'", watcher.indexOf('const reconcileBacklog')) < watcher.indexOf("const activityData = await callMcpTool", watcher.indexOf('const reconcileBacklog'))],
   ['task:assigned is handled', watcher.includes("k === 'task:assigned'")],
   ['task signals are verified with get_ticket', watcher.includes("callMcpTool('get_ticket'")],

package/src/agent-journal.mjs

@@ -59,7 +59,7 @@ export function createAgentJournal({ stateDir, agent, secrets = [] }) {
   const stem = `${slug}-${digest}`
   const path = join(directory, stem + '.jsonl')
   let sequence = 0, pendingBytes = 0, dropped = 0, written = 0, lastError = null
-  let timer, heartbeat, closing = false, closePromise, writing = false
+  let timer, closing = false, closePromise, writing = false
   const pending = []
   const ready = (async () => {
     await mkdir(directory, { recursive: true, mode: 0o700 })
@@ -120,11 +120,8 @@ export function createAgentJournal({ stateDir, agent, secrets = [] }) {
     catch (error) { lastError = error; return false }
   }
   emit('runtime.started', { status: 'running' })
-  heartbeat = setInterval(() => emit('runtime.heartbeat', { status: 'running', droppedEvents: dropped }), 15_000)
-  heartbeat.unref?.()
   const close = () => {
     if (closePromise) return closePromise
-    clearInterval(heartbeat)
     emit('runtime.stopped', { status: 'stopped', droppedEvents: dropped })
     closing = true
     closePromise = (async () => {

package/src/studio-server.mjs

@@ -112,8 +112,13 @@ export async function readStudioSnapshot({ stateDir, now = Date.now, journalCach
   const agentsById = new Map(configured.map((agent) => [agent.identifier, agent]))
   for (const event of latest.values()) {
     const age = now() - Date.parse(event.timestamp)
-    const online = age >= -5000 && age <= FRESH_MS && event.type !== 'runtime.stopped' && pidAlive(event.pid)
     const existing = agentsById.get(event.agent.identifier)
+    // Configured watchers own a PID lock, so Studio can report their real process
+    // state without forcing an idle process to append heartbeat records forever.
+    // Freshness remains a compatibility fallback for older, unconfigured journals.
+    const configuredAlive = existing?.watcherAlive === true && existing.pid === event.pid
+    const recentUnconfigured = !existing?.configured && age >= -5000 && age <= FRESH_MS && pidAlive(event.pid)
+    const online = event.type !== 'runtime.stopped' && (configuredAlive || recentUnconfigured)
     agentsById.set(event.agent.identifier, { ...existing, id: event.agent.identifier, identifier: event.agent.identifier, slug: existing?.slug || event.agent.slug || event.agent.identifier, name: existing?.name || event.agent.slug || event.agent.identifier, provider: event.agent.provider || 'unknown', runId: event.runId, pid: Number.isSafeInteger(event.pid) ? event.pid : null, watcherAlive: online, status: online ? 'online' : 'offline', lastSeen: event.timestamp, lastEventType: event.type })
   }
   const agents = [...agentsById.values()]

package/src/watch.mjs

@@ -1,12 +1,10 @@
-// The OpenVisio autonomy watcher — an event-driven "warm" loop. Cheaply polls
-// /api/agent/inbox (no model) and pokes ONE persistent Claude Code stream-json
-// session with a cycle per new @mention / follow-up / ticket. Ported verbatim from
-// the shell installer so behaviour is identical — now shipped in the package rather
-// than written to disk from a pasted heredoc.
+// The OpenVisio autonomy watcher — an event-driven loop. It waits on the team
+// event connection and starts a runtime only for accepted work. Relay mode keeps
+// compatibility with older inbox polling connections.
 
 import { spawn, spawnSync } from 'node:child_process'
 import { AsyncLocalStorage } from 'node:async_hooks'
-import { closeSync, writeFileSync, mkdirSync, mkdtempSync, rmSync, existsSync, openSync, readFileSync, readdirSync, unlinkSync } from 'node:fs'
+import { closeSync, writeFileSync, mkdirSync, mkdtempSync, rmSync, existsSync, openSync, readFileSync, readdirSync, unlinkSync, watch as watchFs } from 'node:fs'
 import { homedir, tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { join, dirname } from 'node:path'
@@ -585,8 +583,8 @@ export function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, m
 
 // ── the backend WS loop ──────────────────────────────────────────────────────
 // One WebSocket identity feeds independent serialized work/reply queues. Each
-// accepted source keeps its own context; direct MCP reconciliation recovers work
-// without model spend while idle.
+// accepted source keeps its own context; direct MCP reconciliation runs once
+// when the event connection starts or reconnects, then the watcher stays idle.
 function loopBackendWs(options) {
   const watcher = createBackendWatcher(options)
   const stop = () => void watcher.close().then(() => process.exit(0))
@@ -2193,19 +2191,16 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
   deliveryTimer?.unref?.()
   const authorizationTimer = autoStart ? setInterval(() => void resumeReadyAuthorizations(), 2_000) : null
   authorizationTimer?.unref?.()
-  const modelSettingsTimer = autoStart ? setInterval(refreshModelSettings, 2_000) : null
-  modelSettingsTimer?.unref?.()
+  let modelSettingsWatcher = null
+  if (autoStart) {
+    try {
+      modelSettingsWatcher = watchFs(stateDir, { persistent: false }, (_event, filename) => {
+        if (!filename || String(filename) === `${slug}.json`) refreshModelSettings()
+      })
+    } catch { /* every cycle still refreshes settings before choosing a model */ }
+  }
   emit('models.updated', { model: codeModel, chatModel: liteModel, modelSettingsRevision })
-  const heartbeatTimer = autoStart ? setInterval(() => {
-    emit('watcher.heartbeat', { status: 'running', active: queues.work.activeSize + queues.reply.activeSize, pending: queues.work.size + queues.reply.size, model: codeModel, chatModel: liteModel, modelSettingsRevision, workdir: workdir || '', ...(agentAppearance ? { profile: agentAppearance } : {}) })
-    // The Studio reads a bounded journal tail. Re-state current queue ownership
-    // so a long-running cycle stays visible after its start event rotates out.
-    for (const { data, control } of liveCycles.values()) {
-      if (!control.cancelled) emit('cycle.snapshot', { ...data, status: control.outcome, attempt: control.attempt || 1 })
-    }
-  }, 15_000) : null
-  heartbeatTimer?.unref?.()
-  let introTimer = null, taskProbeStartTimer = null, taskProbeTimer = null
+  let introTimer = null
   if (autoStart && (mcpConfig || mcpUrl)) {
     // Workspace ethics: a one-time hello the FIRST time this agent ever connects.
     const introMarker = join(stateDir, 'intro-' + slugify(identifier) + '.done')
@@ -2218,13 +2213,8 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
         }).catch((e) => log('guarded introduction failed: ' + (e?.message || e)))
       }, 5000) // let the socket subscribe first
     }
-    // Reconciliation replaces the old model-driven startup/daily sweep. It uses
-    // supported MCP tools directly, stays silent when empty, and hands verified
-    // coding tasks to the full lane instead of letting Luna announce it cannot code.
-    taskProbeStartTimer = setTimeout(() => void reconcileBacklog(), 3_000)
-    // WebSocket delivery is primary. A short bounded reconciliation interval
-    // keeps mentions responsive when a deployment omits targeted dispatch.
-    taskProbeTimer = setInterval(() => void reconcileBacklog(), 30_000)
+    // The WebSocket onConnect hook performs one recovery pass. Do not poll the
+    // backend while a healthy event connection is already waiting for work.
   } else {
     log('no MCP config — skipping intro + daily sweep (agent has no tools to post/act)')
   }
@@ -2238,11 +2228,8 @@ export function createBackendWatcher({ backend, wsUrl, apiKey, identifier, slug,
     closePromise = (async () => {
       clearInterval(authorizationTimer)
       clearInterval(deliveryTimer)
-      clearInterval(heartbeatTimer)
-      clearInterval(modelSettingsTimer)
+      modelSettingsWatcher?.close()
       if (introTimer) clearTimeout(introTimer)
-      if (taskProbeStartTimer) clearTimeout(taskProbeStartTimer)
-      if (taskProbeTimer) clearInterval(taskProbeTimer)
       try { handle?.close() } catch { /* already disconnected */ }
       for (const queue of Object.values(queues)) {
         queue.cancel(() => true, (item) => { item.control.cancelled = true; item.control.wakeRecovery?.() })
@@ -2305,12 +2292,9 @@ function loop({ host, key, slug, claude, agent, mcpConfig, mcpUrl, workdir, mode
 
   const seen = new Set()
   let busy = false
-  const heartbeatTimer = setInterval(() => emit('watcher.heartbeat', { status: 'running', active: busy ? 1 : 0, model, chatModel, workdir: workdir || '' }), 15_000)
-  heartbeatTimer.unref?.()
   const close = () => {
     if (closePromise) return closePromise
     stopping = true
-    clearInterval(heartbeatTimer)
     clearTimeout(introTimer)
     clearInterval(sweepTimer)
     closePromise = (async () => {

package/studio/app.mjs

@@ -393,7 +393,7 @@ function initializeStudio() {
     $('open-model-settings').disabled = !agent.settingsEditable;
     $('open-agent-removal').disabled = !agent.removable;
     const watcherRunning = agent.status === 'online' || agent.watcherAlive === true;
-    $('toggle-watcher').textContent = watcherRunning ? 'Stop watcher' : 'Start watcher';
+    $('toggle-watcher').querySelector('span').textContent = watcherRunning ? 'Stop watcher' : 'Start watcher';
     $('toggle-watcher').dataset.action = watcherRunning ? 'stop' : 'start';
     $('toggle-watcher').disabled = watcherChanging || !agent.watcherControllable;
     $('restart-watcher').disabled = watcherChanging || !agent.watcherControllable;

package/studio/guide.html

@@ -51,7 +51,7 @@
           </section>
           <section id="remove">
             <h2>Remove a local agent</h2>
-            <p>Select an agent, choose <strong>Remove from computer</strong>, review the local data, and type its local name to confirm. Studio stops its watcher and background service, then removes its local connection credentials, logs, memory, and cached context. This cannot be undone.</p>
+            <p>Select an agent, choose <strong>Remove agent</strong>, review the local data, and type its local name to confirm. Studio stops its watcher and background service, then removes its local connection credentials, logs, memory, and cached context. This cannot be undone.</p>
             <p>Repositories, branches, shared model-provider logins, and the team’s agent profile stay in place. Context shared with another local connection is retained. Removal is available on macOS and Linux for the default local agent storage; custom state directories and Windows require manual management.</p>
           </section>
           <section id="watchers">
@@ -62,7 +62,7 @@
               <li>Select the agent in Studio and choose <strong>Start watcher</strong>. Studio installs its background watcher and starts it with the current package and saved model settings.</li>
               <li>Return to Studio. Your agent should appear in the sidebar. Select its name to see its activity.</li>
             </ol>
-            <p>Use <strong>Stop watcher</strong> to take an agent offline and <strong>Restart watcher</strong> after changing its runtime installation or troubleshooting a connection. Restarting preserves its configuration and model choices.</p>
+            <p>Use <strong>Stop watcher</strong> to take an agent offline and <strong>Restart watcher</strong> after changing its runtime installation or troubleshooting a connection. Restarting preserves its configuration and model choices. While connected and idle, the watcher waits for WebSocket or local settings events without starting a coding runtime or polling project activity.</p>
             <p>Watcher controls are available for backend agents in the default local agent storage on macOS and Linux. Their earlier activity cannot be reconstructed.</p>
           </section>
           <section id="find-work">

package/studio/index.html

@@ -34,6 +34,10 @@
       <symbol id="i-clock" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/></symbol>
       <symbol id="i-close" viewBox="0 0 24 24"><path d="m6 6 12 12M6 18 18 6"/></symbol>
       <symbol id="i-copy" viewBox="0 0 24 24"><rect x="8" y="8" width="12" height="13" rx="2"/><path d="M16 8V5a2 2 0 0 0-2-2H5a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h3"/></symbol>
+      <symbol id="i-power" viewBox="0 0 24 24"><path d="M12 3v9"/><path d="M7.1 5.8a8 8 0 1 0 9.8 0"/></symbol>
+      <symbol id="i-refresh" viewBox="0 0 24 24"><path d="M20 7v5h-5"/><path d="M4 17v-5h5"/><path d="M6.1 8a7 7 0 0 1 11.7-1L20 12M4 12l2.2 5a7 7 0 0 0 11.7-1"/></symbol>
+      <symbol id="i-sliders" viewBox="0 0 24 24"><path d="M4 6h10M18 6h2M4 12h2m4 0h10M4 18h8m4 0h4"/><circle cx="16" cy="6" r="2"/><circle cx="8" cy="12" r="2"/><circle cx="14" cy="18" r="2"/></symbol>
+      <symbol id="i-user-minus" viewBox="0 0 24 24"><circle cx="9" cy="8" r="4"/><path d="M2 21a7 7 0 0 1 14 0M17 11h6"/></symbol>
     </defs></svg>
     <a class="skip-link" href="#workspace">Skip to activity</a>
     <div class="app-shell">
@@ -61,7 +65,7 @@
         <div id="notice" class="notice" role="status" hidden></div>
         <section id="model-settings-summary" class="model-settings-summary" aria-label="Agent model settings" hidden>
           <div><h2 id="model-settings-agent">Model settings</h2><p id="model-settings-state" role="status"></p></div>
-          <div class="header-actions"><button id="toggle-watcher" class="button" type="button">Start watcher</button><button id="restart-watcher" class="button" type="button">Restart watcher</button><button id="open-model-settings" class="button" type="button">Model settings</button><button id="open-agent-removal" class="button" type="button">Remove from computer</button></div>
+          <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>
         </section>
         <dialog id="model-settings-dialog" aria-labelledby="model-settings-title">
           <form id="model-settings-form" class="model-settings-form">

package/studio/style.css

@@ -360,6 +360,13 @@
   .model-settings-summary:not([hidden]) { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 14px; padding: 18px; margin-bottom: 22px; border: 1px solid var(--border); border-radius: 20px; background: var(--surface, white); }
   .model-settings-summary h2 { margin: 0 0 6px; font-size: 13px; font-weight: 500; }
   .model-settings-summary p { margin: 0; color: var(--muted); font-size: 12px; overflow-wrap: anywhere; }
+  .model-settings-actions-row { gap: 8px; }
+  .studio-action .icon { transition: transform .16s ease-out, color .16s ease-out; }
+  .studio-action:hover .icon { transform: translateY(-1px); }
+  #toggle-watcher[data-action="start"] .icon { color: var(--success); }
+  #toggle-watcher[data-action="stop"] .icon, .remove-action .icon { color: var(--destructive); }
+  .restart-action .icon { color: var(--orange); }
+  .settings-action .icon { color: var(--purple); }
   #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; }
   #model-settings-dialog::backdrop, #agent-removal-dialog::backdrop { background: #0005; }
   .model-settings-form { display: grid; gap: 12px; }