openvisio-agent 0.9.0 → 0.10.1

package/README.md

@@ -1,12 +1,19 @@
 # openvisio-agent
 
-Connect your coding agent (**Claude Code**) to an [OpenVisio](https://openvisio.app) team — in one command. No shell scripts, no `curl | bash`.
+Connect your coding agent (**Claude Code, Codex, or OpenCode**) to an [OpenVisio](https://openvisio.app) team — in one command. No shell scripts, no `curl | bash`.
 
 ```bash
 npx -y openvisio-agent@latest connect ovs_YOURCODE --host https://your-openvisio.app --name "Ada"
 ```
 
-That's it. Your agent now has the team's tools (channels, tickets, docs, search) inside Claude Code.
+Use Codex as the autonomous runtime:
+
+```bash
+codex login
+npx -y openvisio-agent@latest connect ovs_YOURCODE --host https://your-openvisio.app --name "Ada" --agent codex
+```
+
+That's it. Your selected runtime now has the team's tools (channels, tickets, docs, search) during autonomy cycles.
 
 ## What it does
 
@@ -15,7 +22,7 @@ That's it. Your agent now has the team's tools (channels, tickets, docs, search)
 ### `connect <ovs_code> --host <url>`
 
 1. Redeems the **single-use** setup code for your agent key (`POST /api/agent/setup/exchange`). The code is short-lived and one-time, so it's inert if it leaks into your shell history.
-2. Registers the `openvisio-team` MCP server with Claude Code (`claude mcp add …`). Installs Claude Code first if it isn't on your PATH.
+2. Configures the `openvisio-team` MCP for the selected runtime. Claude Code is registered globally; Codex and OpenCode receive an isolated MCP configuration for each autonomy cycle.
 3. Saves a scoped config under `~/.openvisio/` (chmod `600`) for the optional watcher.
 
 Options: `--name "<agent>"` (label), `--mcp-url <url>` (override the MCP endpoint).
@@ -69,7 +76,7 @@ With `--workdir`, the agent gets file + Bash tools scoped to that repo and works
 ## Requirements
 
 - Node.js ≥ 18
-- [Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code) (auto-installed if missing)
+- Claude Code, Codex (`@openai/codex`), or OpenCode (the selected CLI is auto-installed if missing)
 
 ## Getting a setup code
 

package/bin/cli.mjs

@@ -13,7 +13,7 @@ import { spawnSync } from 'node:child_process'
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
-import { parseFlags, slugify, stripSlash, exchangeToken, ensureClaude, writeJson, mcpConfigPath, configPath, chmodSafe, onPath, OV_DIR, fail, ok, info } from '../src/lib.mjs'
+import { parseFlags, slugify, stripSlash, exchangeToken, ensureClaude, ensureCodex, writeJson, mcpConfigPath, configPath, chmodSafe, onPath, OV_DIR, fail, ok, info } from '../src/lib.mjs'
 import { runWatch, installService } from '../src/watch.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
@@ -24,14 +24,14 @@ const HELP = `openvisio-agent ${VERSION}
 Connect your coding agent to an OpenVisio team.
 
 Usage:
-  openvisio-agent connect <ovs_code> --host <url> [--name "<agent>"] [--mcp-url <url>] [--agent claude|opencode]
-  openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--ws <wss-url>] [--mcp-url <url>] [--agent claude|opencode]
+  openvisio-agent connect <ovs_code> --host <url> [--name "<agent>"] [--mcp-url <url>] [--agent claude|codex|opencode]
+  openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--ws <wss-url>] [--mcp-url <url>] [--agent claude|codex|opencode]
   openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--model <m>] [--chat-model <m>] [--debug]
   openvisio-agent --help | --version
 
 connect
-  Redeems the setup code, adds the "openvisio-team" MCP server to Claude Code, and
-  saves a config for the autonomy watcher.
+  Redeems the setup code, configures the "openvisio-team" MCP for the selected
+  runtime, and saves a config for the autonomy watcher.
 
 connect --backend
   Registers a BACKEND agent (created in OpenVisio → Agents → Connect your agent):
@@ -50,14 +50,13 @@ connect --backend
                      pushes its agent/* branch and opens PRs. Defaults to
                      ~/openvisio-workspace; point it at an existing clones folder to
                      reuse those. (--workdir is an accepted alias.)
-    --agent <name>   the coding-agent RUNTIME the cycles run on: claude (Claude Code,
-                     default) or opencode (opencode.ai). opencode is authenticated
-                     separately (opencode auth login) and uses provider/model ids.
+    --agent <name>   coding-agent runtime: claude (default), codex, or opencode.
+                     Codex authenticates separately with \`codex login\`; opencode
+                     authenticates with \`opencode auth login\`.
     --chat-only      disable code work — chat/ticket tools only.
-    --model <m>      the model the agent runs on (opus | sonnet | haiku | a full
-                     claude-… id). Defaults to sonnet — cost-effective, so the agent
-                     doesn't burn Opus tokens on routine chat. Engineers can also
-                     change it live from chat: "@agent /model sonnet".
+    --model <m>      model passed to the selected runtime. Claude defaults to
+                     sonnet; Codex and OpenCode use their configured default.
+                     Engineers can also change it live from chat: "@agent /model …".
     --chat-model <m> run the lighter chat/mention cycles on an even cheaper model
                      while code work stays on --model (e.g. --model sonnet
                      --chat-model haiku).
@@ -92,7 +91,8 @@ function mcpReplace(claude, addArgs) {
 // background service) to work — an `npx` connect leaves nothing installed. Make
 // the global install part of setup.
 function ensureAgentInstalled() {
-  if (onPath('openvisio-agent')) return
+  const current = onPath('openvisio-agent')
+  if (current && !current.includes('/_npx/')) return
   info('Installing openvisio-agent globally (so `watch` and the always-on service have a stable command)…')
   spawnSync('npm', ['i', '-g', 'openvisio-agent@latest'], { stdio: 'inherit', shell: process.platform === 'win32' })
 }
@@ -100,7 +100,7 @@ function ensureAgentInstalled() {
 // The chosen coding-agent RUNTIME the cycles run on. Default claude.
 function agentFlag(flags) {
   const a = String(flags.agent || flags.runtime || 'claude').toLowerCase()
-  if (a !== 'claude' && a !== 'opencode') fail(`Unknown --agent "${a}". Supported runtimes: claude | opencode.`)
+  if (a !== 'claude' && a !== 'codex' && a !== 'opencode') fail(`Unknown --agent "${a}". Supported runtimes: claude | codex | opencode.`)
   return a
 }
 
@@ -139,6 +139,8 @@ async function runConnect({ positional, flags }) {
     // A scoped MCP config for the watcher's --strict-mcp-config.
     mcpCfg = mcpConfigPath(slug)
     writeJson(mcpCfg, { mcpServers: { 'openvisio-team': { type: 'http', url: mcpUrl, headers: { Authorization: `Bearer ${key}` } } } }, true)
+  } else if (agent === 'codex') {
+    ensureCodex()
   } else {
     ensureOpencode() // the watcher writes opencode.json with the remote MCP at runtime
   }
@@ -149,7 +151,9 @@ async function runConnect({ positional, flags }) {
   info()
   info(agent === 'opencode'
     ? 'Runtime: opencode. The watcher writes an opencode.json with the openvisio-team tools; make sure opencode is authenticated (opencode auth login).'
-    : 'Claude Code now has the openvisio-team tools. Run  /mcp  in Claude Code to confirm.')
+    : agent === 'codex'
+      ? 'Runtime: Codex. The watcher injects only the openvisio-team MCP into each cycle; authenticate once with `codex login`.'
+      : 'Claude Code now has the openvisio-team tools. Run  /mcp  in Claude Code to confirm.')
   info()
   info('To let it work on its own (reply to mentions, pick up tickets, AND do real')
   info('coding — it clones/branches/pushes and opens PRs out of the box):')
@@ -213,6 +217,8 @@ async function runConnectBackend({ flags }) {
       mcpReplace(claude, ['--transport', 'http', 'openvisio-team', mcpUrl, ...hdr])
       mcpConfig = mcpConfigPath(slug)
       writeJson(mcpConfig, { mcpServers: { 'openvisio-team': { type: 'http', url: mcpUrl, headers: { 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier } } } }, true)
+    } else if (agent === 'codex') {
+      ensureCodex()
     } else {
       ensureOpencode() // the watcher writes opencode.json with the remote MCP at runtime
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openvisio-agent",
-  "version": "0.9.0",
-  "description": "Connect your coding agent (Claude Code) to an OpenVisio team — MCP tools + optional autonomy — in one command. No shell scripts.",
+  "version": "0.10.1",
+  "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team — MCP tools + optional autonomy — in one command.",
   "type": "module",
   "bin": {
     "openvisio-agent": "bin/cli.mjs"
@@ -19,6 +19,7 @@
     "mcp",
     "claude",
     "claude-code",
+    "codex",
     "agent",
     "autonomy"
   ],

package/src/lib.mjs

@@ -78,6 +78,19 @@ export function ensureClaude() {
   return claude
 }
 
+/** Ensure the Codex CLI is installed. Authentication remains an explicit,
+ *  one-time user action (`codex login`); the watcher never handles OpenAI
+ *  credentials itself. */
+export function ensureCodex() {
+  let codex = onPath('codex')
+  if (codex) return codex
+  info('Codex CLI not found on PATH — installing @openai/codex globally…')
+  spawnSync('npm', ['i', '-g', '@openai/codex'], { stdio: 'inherit', shell: IS_WIN })
+  codex = onPath('codex')
+  if (!codex) fail('Codex still isn\'t on PATH after install.\n  Install it (npm i -g @openai/codex), run `codex login`, and re-run.')
+  return codex
+}
+
 export function writeJson(path, obj, secret = false) {
   mkdirSync(OV_DIR, { recursive: true })
   writeFileSync(path, JSON.stringify(obj, null, 2))

package/src/watch.mjs

@@ -122,9 +122,11 @@ const DENY_TOOLS = [
   'Bash(gh pr merge:*)', 'Bash(gh repo delete:*)',
 ]
 
-const FAST = 2500
-const SLOW = 6000
-const IDLE_AFTER = 60000
+// Poll promptly while activity is recent, then back off hard. A 6-second idle
+// poll across several agents creates thousands of needless network wakeups/day.
+const FAST = 5000
+const SLOW = 60000
+const IDLE_AFTER = 30000
 // Recycle the warm session after ONE cycle. Autonomy cycles are independent (a
 // mention → a reply, a task → its work), so keeping a session across cycles just
 // re-bills the entire prior history on every new cycle — the #1 token sink. Fresh
@@ -139,6 +141,24 @@ const SESSION_IDLE_MS = 1200000
 // minutes, and cutting it off mid-job is itself a "never circled back" failure.
 const MAX_CYCLE_MS = 240000
 const MAX_CODE_CYCLE_MS = 900000
+const STARTUP_SWEEP_MIN_MS = 6 * 60 * 60 * 1000
+
+// launchd/systemd may restart a service repeatedly during upgrades or transient
+// failures. Cap model-powered backend catch-up sweeps to one per six hours; live
+// WebSocket events continue to arrive immediately between sweeps.
+function claimStartupSweep(key) {
+  const marker = join(OV_DIR, 'sweep-' + slugify(key || 'openvisio') + '.at')
+  try {
+    const last = Number(readFileSync(marker, 'utf8')) || 0
+    if (Date.now() - last < STARTUP_SWEEP_MIN_MS) return false
+    mkdirSync(OV_DIR, { recursive: true })
+    writeFileSync(marker, String(Date.now()))
+    return true
+  } catch {
+    try { mkdirSync(OV_DIR, { recursive: true }); writeFileSync(marker, String(Date.now())) } catch { /* best-effort */ }
+    return true
+  }
+}
 
 // Refuse to run a SECOND watcher for the same agent. Two watchers connect to the
 // WS as the same agent and BOTH reply to every mention — the #1 cause of duplicate
@@ -168,10 +188,10 @@ export async function runWatch({ flags }) {
   const saved = slug ? readConfig(slug) : null
   const claude = String(flags.claude || onPath('claude') || 'claude')
   const mcpConfig = String(flags['mcp-config'] || (saved && saved.mcpConfig) || '')
-  // Which coding-agent runtime drives the cycles: Claude Code (warm stream-json
-  // session) or opencode (headless `opencode run` per cycle). Default claude.
+  // Which coding-agent runtime drives the cycles: Claude Code (warm stream-json),
+  // Codex (`codex exec`), or opencode (`opencode run`). Default claude.
   const agent = String(flags.agent || flags.runtime || (saved && saved.agent) || 'claude').toLowerCase()
-  if (agent !== 'claude' && agent !== 'opencode') fail(`Unknown --agent "${agent}". Supported runtimes: claude | opencode.`)
+  if (agent !== 'claude' && agent !== 'codex' && agent !== 'opencode') fail(`Unknown --agent "${agent}". Supported runtimes: claude | codex | opencode.`)
   const 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
@@ -186,11 +206,9 @@ export async function runWatch({ flags }) {
   const workdir = chatOnly ? '' : (explicitWorkdir || (saved && (saved.workspace || saved.workdir)) || DEFAULT_WORKSPACE)
   if (workdir) { try { mkdirSync(workdir, { recursive: true }) } catch { /* best-effort; spawn will surface a real problem */ } }
 
-  // Model the agent runs on. For Claude Code default SONNET (cost-effective) rather
-  // than whatever `claude` defaults to. For opencode, models are `provider/model`
-  // and multi-provider, so default to empty (use opencode's own configured default)
-  // unless set. Optional --chat-model runs the lighter chat/mention cycles cheaper.
-  const model = String(flags.model || (saved && saved.model) || (agent === 'opencode' ? '' : 'sonnet'))
+  // Claude defaults to Sonnet; Codex and OpenCode use their configured defaults
+  // unless explicitly overridden. Optional --chat-model can select a lighter model.
+  const model = String(flags.model || (saved && saved.model) || (agent === 'claude' ? 'sonnet' : ''))
   const chatModel = String(flags['chat-model'] || (saved && saved.chatModel) || '')
 
   // ONE watcher per agent. A second one (e.g. a manual `watch` alongside the
@@ -199,9 +217,21 @@ export async function runWatch({ flags }) {
   if (!flags.install) {
     const lock = acquireSingleInstance(slug || 'openvisio')
     if (lock.conflict) {
-      fail(`Another openvisio-agent watcher for "${slug || 'openvisio'}" is already running (pid ${lock.conflict}).\n` +
+      const watcherName = slug || 'openvisio'
+      const stop = process.platform === 'darwin'
+        ? `launchctl unload ~/Library/LaunchAgents/io.openvisio.${watcherName}.plist`
+        : process.platform === 'win32'
+          ? 'Stop the existing openvisio-agent process in Task Manager.'
+          : `systemctl --user stop openvisio-${watcherName}.service`
+      const logs = process.platform === 'darwin'
+        ? `tail -f ~/.openvisio/${watcherName}.log`
+        : `journalctl --user -u openvisio-${watcherName} -f`
+      fail(`Another openvisio-agent watcher for "${watcherName}" is already running (pid ${lock.conflict}).\n` +
         `  Two watchers for the same agent BOTH reply to every mention — that is what causes duplicate/contradicting messages.\n` +
-        `  Stop the other one (kill ${lock.conflict}), or rely on ONLY the background service. Refusing to start a second.`)
+        `  This is usually the auto-restarting background service; killing its PID only makes it restart.\n` +
+        `  To run in this terminal instead, stop the service first:\n    ${stop}\n` +
+        `  Or keep the service and inspect its log:\n    ${logs}\n` +
+        `  Refusing to start a second watcher.`)
     }
     process.on('exit', () => { try { lock.release && lock.release() } catch { /* noop */ } })
   }
@@ -284,6 +314,56 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
   return { runCycle, canCode }
 }
 
+// Codex has a purpose-built non-interactive mode. Run a fresh, ephemeral cycle
+// for each event and inject only this agent's OpenVisio MCP config on the command
+// line. That avoids inheriting unrelated user MCP servers while keeping the
+// user's normal Codex authentication. We deliberately never use Codex's dangerous
+// approval/sandbox bypass flag.
+function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, log, debug, model, systemPrompt }) {
+  const bin = onPath('codex') || 'codex'
+  const cwd = workdir || OV_DIR
+  const tomlString = (v) => JSON.stringify(String(v))
+  const headerEntries = Object.entries(mcpHeaders || {}).map(([k, v]) => `${JSON.stringify(k)} = ${tomlString(v)}`).join(', ')
+
+  function runCycle(prompt, cycleModel) {
+    return new Promise((resolve) => {
+      const m = cycleModel || model
+      const full = systemPrompt ? systemPrompt + '\n\n' + prompt : prompt
+      const mcpOverride = mcpUrl
+        ? `mcp_servers={ openvisio-team = { url = ${tomlString(mcpUrl)}${headerEntries ? `, http_headers = { ${headerEntries} }` : ''} } }`
+        : ''
+      const args = ['exec', '--ignore-user-config', '--skip-git-repo-check', '--ephemeral', '--json', '--color', 'never',
+        ...(canCode ? ['--approve-for-me'] : ['--sandbox', 'read-only']),
+        ...(m ? ['--model', m] : []),
+        ...(mcpOverride ? ['-c', mcpOverride] : []),
+        full]
+      let child = null, done = false
+      const finish = (o) => { if (done) return; done = true; clearTimeout(timer); resolve(o) }
+      const timer = setTimeout(() => {
+        log('codex cycle TIMED OUT after ' + Math.round(maxCycleMs / 1000) + 's — killing')
+        try { child && child.kill() } catch { /* gone */ }
+        finish({ type: 'result', subtype: 'timeout' })
+      }, maxCycleMs)
+      log('running codex cycle…' + (m ? ' [' + m + ']' : ''))
+      try {
+        child = spawn(bin, args, { cwd, stdio: ['ignore', debug ? 'pipe' : 'ignore', 'inherit'] })
+        if (debug && child.stdout) child.stdout.on('data', (d) => {
+          for (const line of String(d).split('\n')) if (line.trim()) log('  · ' + line.trim().slice(0, 220))
+        })
+      } catch (e) {
+        log('codex spawn failed: ' + (e && e.message ? e.message : e) + ' — is Codex installed and signed in? (`npm i -g @openai/codex`, then `codex login`)')
+        return finish({ type: 'result', subtype: 'spawn-failed' })
+      }
+      child.on('exit', (code) => { log('codex cycle done (' + (code === 0 ? 'ok' : 'exit ' + code) + ')'); finish({ type: 'result', subtype: code === 0 ? 'ok' : 'error' }) })
+      child.on('error', (e) => { log('codex error: ' + (e && e.message ? e.message : e)); finish({ type: 'result', subtype: 'error' }) })
+    })
+  }
+
+  if (!mcpUrl) log('WARNING: no --mcp-url — Codex has no openvisio-team tools to act with. Re-connect with --mcp-url.')
+  log('codex runner ready' + (model ? ' [model ' + model + ']' : '') + (canCode ? ' [CODE workspace ' + cwd + ']' : ' [CHAT-ONLY]'))
+  return { runCycle, canCode }
+}
+
 // ── Claude Code warm-session cycle runner (shared by the REST + WS loops) ─────
 // One persistent stream-json session, poked with a prompt per cycle. Recycled
 // after MAX_TURNS or SESSION_IDLE_MS. Returns { runCycle, canCode }.
@@ -293,6 +373,7 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
   // opencode drives cycles differently — a headless `opencode run` per cycle rather
   // than a persistent stream-json session. Same { runCycle, canCode } contract.
   if (agent === 'opencode') return createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model, systemPrompt })
+  if (agent === 'codex') return createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, log, debug, model, systemPrompt })
   let child = null
   // The model the CURRENT session was spawned with. runCycle can pass a different
   // model per cycle (cheap for chat, stronger for code) — a change recycles the
@@ -345,7 +426,17 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
         if (onTool && o.type === 'assistant' && o.message && Array.isArray(o.message.content)) {
           for (const b of o.message.content) if (b.type === 'tool_use' && b.name) { try { onTool(b.name) } catch { /* status is best-effort */ } }
         }
-        if (o.type === 'result') { log('cycle done (' + (o.subtype || 'ok') + (o.is_error ? ' · ERROR' : '') + ')'); settleTurn(o) }
+        if (o.type === 'result') {
+          log('cycle done (' + (o.subtype || 'ok') + (o.is_error ? ' · ERROR' : '') + ')')
+          settleTurn(o)
+          // Autonomy cycles are independent and MAX_TURNS is one. Do not leave a
+          // full Claude runtime resident until the next event; release its CPU,
+          // memory and file watchers as soon as the result has been received.
+          if (MAX_TURNS === 1 && c === child) {
+            child = null
+            try { c.kill() } catch { /* already gone */ }
+          }
+        }
       }
     })
     c.on('exit', (code) => { if (c !== child) { log('old session exited ' + code); return } log('session exited ' + code); child = null; settleTurn({ type: 'result', subtype: 'exit' }) })
@@ -482,6 +573,7 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
     const x = String(s || '').toLowerCase().replace(/[.,!?]+$/, '')
     if (x === 'opus' || x === 'sonnet' || x === 'haiku') return x
     if (/^claude-[a-z0-9.\-\[\]]+$/i.test(x)) return x
+    if (/^(?:gpt|codex|o[1-9])[a-z0-9.\-:]*$/i.test(x)) return x
     // opencode models are provider/model (e.g. anthropic/claude-sonnet-4, openai/gpt-4o).
     return /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9.\-:]*$/i.test(x) ? x : null
   }
@@ -590,7 +682,7 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
 
   const DAY_MS = 24 * 60 * 60 * 1000
   let introTimer = null, sweepStartTimer = null, sweepTimer = null
-  if (mcpConfig) {
+  if (mcpConfig || mcpUrl) {
     // Workspace ethics: a one-time hello the FIRST time this agent ever connects.
     const introMarker = join(OV_DIR, 'intro-' + slugify(identifier) + '.done')
     if (!existsSync(introMarker)) {
@@ -601,7 +693,11 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
     // Catch-up sweep: shortly after startup (covers downtime) + once every day.
     // Sooner rather than later: a freshly-added agent whose WS subscription isn't
     // live yet still catches pending mentions/tasks via this REST poll_inbox sweep.
-    sweepStartTimer = setTimeout(() => { log('startup catch-up sweep'); void drain('sweep', SWEEP) }, 12_000)
+    if (claimStartupSweep(identifier)) {
+      sweepStartTimer = setTimeout(() => { log('startup catch-up sweep'); void drain('sweep', SWEEP) }, 12_000)
+    } else {
+      log('startup catch-up sweep skipped (ran within the last 6h)')
+    }
     sweepTimer = setInterval(() => { log('daily catch-up sweep'); void drain('sweep', SWEEP) }, DAY_MS)
   } else {
     log('no MCP config — skipping intro + daily sweep (agent has no tools to post/act)')
@@ -642,17 +738,15 @@ function loop({ host, key, slug, claude, agent, mcpConfig, mcpUrl, workdir, mode
   // A one-off prompt (intro / daily sweep) the main loop runs the next time it's
   // free — keeps everything on the single runCycle so nothing overlaps.
   let queuedSpecial = null
-  if (mcpConfig) {
+  if (mcpConfig || mcpUrl) {
     const introMarker = join(OV_DIR, 'intro-' + (slug || 'openvisio') + '.done')
     if (!existsSync(introMarker)) {
       try { mkdirSync(OV_DIR, { recursive: true }); writeFileSync(introMarker, new Date().toISOString() + '\n') } catch { /* best-effort */ }
       log('first run — introducing self to the workspace')
       setTimeout(() => { queuedSpecial = INTRO }, 5000)
     }
-    // The startup poll marks pre-existing tasks as "seen" (so it won't re-handle old
-    // ones) — which would also skip tasks assigned while offline. A startup + daily
-    // sweep re-checks get_marching_orders so those are still picked up.
-    setTimeout(() => { log('startup catch-up sweep'); queuedSpecial = SWEEP + '\n\n' + fullPrompt }, 12_000)
+    // The first inbox response below decides whether a startup sweep is needed.
+    // Do not spend a model turn on every service restart when the inbox is empty.
     setInterval(() => { log('daily catch-up sweep'); queuedSpecial = SWEEP + '\n\n' + fullPrompt }, 24 * 60 * 60 * 1000)
   }
 
@@ -687,7 +781,12 @@ function loop({ host, key, slug, claude, agent, mcpConfig, mcpUrl, workdir, mode
         const items = Array.isArray(res.items) ? res.items : []
         if (firstCheck && Array.isArray(res.items)) {
           firstCheck = false
+          const hasTaskBacklog = items.some((i) => i.startsWith('tk:') || i.startsWith('clm:'))
           for (const i of items) if (i.startsWith('tk:') || i.startsWith('clm:')) seen.add(i)
+          if (hasTaskBacklog) {
+            log('startup task backlog -> catch-up sweep')
+            queuedSpecial = SWEEP + '\n\n' + fullPrompt
+          }
         }
         if (res.paused) {
           delay = SLOW
@@ -728,7 +827,7 @@ function loop({ host, key, slug, claude, agent, mcpConfig, mcpUrl, workdir, mode
 // ── background service install (launchd / systemd) ───────────────────────────
 export function installService({ slug, workdir }) {
   const binPath = onPath('openvisio-agent')
-  if (!binPath) {
+  if (!binPath || binPath.includes('/_npx/')) {
     info('Installing openvisio-agent globally so the background service has a stable path…')
     spawnSync('npm', ['i', '-g', 'openvisio-agent'], { stdio: 'inherit', shell: process.platform === 'win32' })
   }
@@ -736,7 +835,8 @@ export function installService({ slug, workdir }) {
   const nodeDir = dirname(process.execPath)
   const claudeBin = onPath('claude')
   const opencodeBin = onPath('opencode')
-  const runPath = [nodeDir, claudeBin ? dirname(claudeBin) : '', opencodeBin ? dirname(opencodeBin) : '', join(homedir(), '.opencode', 'bin'), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin'].filter(Boolean).join(':')
+  const codexBin = onPath('codex')
+  const runPath = [nodeDir, claudeBin ? dirname(claudeBin) : '', codexBin ? dirname(codexBin) : '', opencodeBin ? dirname(opencodeBin) : '', join(homedir(), '.opencode', 'bin'), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin'].filter(Boolean).join(':')
   const args = ['watch', '--name', slug, ...(workdir ? ['--workdir', workdir] : [])]
   mkdirSync(OV_DIR, { recursive: true })
   const logFile = join(OV_DIR, `${slug}.log`)