openvisio-agent 0.8.1 → 0.10.0

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).
@@ -100,7 +99,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 +138,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 +150,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 +216,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.8.1",
-  "description": "Connect your coding agent (Claude Code) to an OpenVisio team — MCP tools + optional autonomy — in one command. No shell scripts.",
+  "version": "0.10.0",
+  "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

@@ -40,8 +40,11 @@ const CHAT_CHARTER = [
   REPLY_DISCIPLINE,
 ].join('\n')
 
-const CYCLE = CHAT_CHARTER + '\n\nRun one OpenVisio autonomy cycle: call poll_inbox and handle mentions + follow-ups. Reply in 1-3 sentences, @mention people by their EXACT full name, at most one reply per channel. Then stop.'
-const CYCLE_FAST = CHAT_CHARTER + '\n\n' + [
+// NOTE: the CHARTER (who you are + reply discipline) is NOT prepended here — it is
+// passed ONCE as the session's system prompt (cacheable, not re-billed every cycle).
+// These bases are the small per-cycle instructions only. See createCycleRunner.
+const CYCLE = 'Run one OpenVisio autonomy cycle: call poll_inbox and handle mentions + follow-ups. Reply in 1-3 sentences, @mention people by their EXACT full name, at most one reply per channel. Then stop.'
+const CYCLE_FAST = [
   'New chat activity. Do EXACTLY ONE of these:',
   '  • IF a specific mention/message FOR YOU is given above: reply to THAT ONE message exactly once with post_message, then STOP. Do NOT call poll_inbox and do NOT answer anything else this cycle — you already have the message; polling would make you re-answer it and double-post.',
   '  • IF NO specific mention is given above: call poll_inbox and reply only to items truly directed at YOU (a question to you, or a reply to your own message) — SKIP chatter aimed at someone else / another agent, ignore .tasks/.claimable, at most one reply per channel.',
@@ -67,7 +70,7 @@ const CODE_CHARTER = [
   REPLY_DISCIPLINE,
 ].join('\n')
 
-const CODE_FULL = CODE_CHARTER + '\n\n' + [
+const CODE_FULL = [
   'THIS CYCLE: call get_marching_orders and poll_inbox to see assigned tickets + mentions, then act on them.',
   'ACKNOWLEDGE ONCE: for a task assigned to you that you have NOT already acknowledged, post a SINGLE one-line comment_ticket ("On it — picking this up now") before you start. First check the ticket/thread — if you already acknowledged it on an earlier cycle, skip this and just keep working. Then report only when you have the result.',
   'For real code work (an assigned ticket, or a mention asking for changes), run the full flow end-to-end:',
@@ -80,7 +83,7 @@ const CODE_FULL = CODE_CHARTER + '\n\n' + [
   'Bash is for git / gh / tests / clone ONLY — never to hunt for credentials (they are given to you above).',
 ].join('\n')
 
-const CODE_FAST = CODE_CHARTER + '\n\n' + [
+const CODE_FAST = [
   'New chat activity. Do EXACTLY ONE of these:',
   '  • IF a specific mention/message FOR YOU is given above: reply to THAT ONE message exactly once with post_message, then STOP. Do NOT call poll_inbox and do NOT answer anything else this cycle — polling would re-surface the same message and make you double-post.',
   '  • IF NO specific mention is given above: call poll_inbox and reply only to items directed at YOU (asks you something, or responds to your own message) — SKIP chatter aimed at someone else / another agent; at most one reply per channel.',
@@ -119,10 +122,17 @@ const DENY_TOOLS = [
   'Bash(gh pr merge:*)', 'Bash(gh repo delete:*)',
 ]
 
-const FAST = 2500
-const SLOW = 6000
-const IDLE_AFTER = 60000
-const MAX_TURNS = 15
+// 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
+// per cycle keeps each cycle's cost to its own work (the static charter/creds ride
+// in the cached system prompt, so a fresh spawn is cheap).
+const MAX_TURNS = 1
 const SESSION_IDLE_MS = 1200000
 // A single cycle must finish within this or it's abandoned — otherwise a hung
 // cycle (e.g. an MCP tool stalling on a down bridge) would leave `busy` stuck
@@ -131,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
@@ -160,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
@@ -178,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
@@ -227,7 +253,7 @@ export async function runWatch({ flags }) {
 // The openvisio-team MCP is declared in an `opencode.json` written into the run cwd
 // (opencode reads it from there). `--auto` approves tool use non-interactively.
 // Same { runCycle, canCode } contract as the Claude runner.
-function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model }) {
+function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model, systemPrompt }) {
   // opencode reads opencode.json from its CWD: the code workspace, or a dedicated
   // per-agent dir for chat-only agents.
   const cwd = workdir || join(OV_DIR, 'opencode-' + (cfgKey || 'agent'))
@@ -253,7 +279,10 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
     return new Promise((resolve) => {
       ensureConfig()
       const m = cycleModel || model
-      const args = ['run', prompt, '--auto', ...(m ? ['--model', m] : [])]
+      // opencode has no system-prompt flag; each run is a fresh process, so fold the
+      // charter/creds into the message (still not re-accumulated across cycles).
+      const full = systemPrompt ? systemPrompt + '\n\n' + prompt : prompt
+      const args = ['run', full, '--auto', ...(m ? ['--model', m] : [])]
       let child = null, done = false
       const finish = (o) => { if (done) return; done = true; clearTimeout(timer); resolve(o) }
       const timer = setTimeout(() => {
@@ -273,15 +302,66 @@ 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',
+        '--sandbox', canCode ? 'workspace-write' : 'read-only', '--approve-for-me',
+        ...(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 }.
-function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfig, workdir, log, debug, model, onTool }) {
+function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfig, workdir, log, debug, model, onTool, systemPrompt }) {
   const canCode = !!workdir
   const maxCycleMs = canCode ? MAX_CODE_CYCLE_MS : MAX_CYCLE_MS
   // 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 })
+  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
@@ -312,7 +392,9 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
   function ensureSession() {
     if (child && !child.killed) return
     if (!mcpConfig) { log('WARNING: no MCP config — the agent can react to events but has no tools to act. Re-connect with --mcp-url.') }
-    const base = ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--strict-mcp-config', '--mcp-config', mcpConfig, ...(sessionModel ? ['--model', sessionModel] : [])]
+    // The charter + creds ride in the system prompt (cacheable → not re-billed each
+    // cycle), leaving only the small per-cycle instruction in the user message.
+    const base = ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--strict-mcp-config', '--mcp-config', mcpConfig, ...(sessionModel ? ['--model', sessionModel] : []), ...(systemPrompt ? ['--append-system-prompt', systemPrompt] : [])]
     const args = canCode ? [...base, '--allowedTools', ...CODE_TOOLS, '--disallowedTools', ...DENY_TOOLS] : [...base, '--allowedTools', 'mcp__openvisio-team__*']
     const c = spawn(claude, args, { cwd: workdir || undefined, stdio: ['pipe', 'pipe', 'inherit'] })
     child = c
@@ -332,7 +414,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' }) })
@@ -387,9 +479,16 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   // agent:status broadcast (thinking → working → typing → done).
   const statusTargets = new Set()
   const emitStatus = (state) => { for (const c of statusTargets) { try { handle && handle.sendStatus(c, state) } catch { /* best-effort */ } } }
-  const { runCycle, canCode } = createCycleRunner({
+  const canCode = !!workdir
+  // The Mastra bridge authenticates per-CALL: every openvisio-team tool needs
+  // agent_identifier + agent_api_key as arguments. Hand them over up front.
+  const credNote = `AUTH: the openvisio-team tools REQUIRE two arguments on EVERY call — agent_identifier: "${identifier}" and agent_api_key: "${apiKey}". Include BOTH on every openvisio-team tool call (post_message, poll_inbox, react_message, comment_ticket, get_marching_orders, …). These tools may appear in your tool list namespaced (mcp__openvisio-team__post_message on Claude Code, openvisio-team_post_message on opencode) — call whichever names you actually see. The credentials are given to you right here — do NOT hunt for them (no Bash/grep/cat/find, no reading memory); just call the tools with these exact values. (Bash/git/gh ARE for your code work — this rule is only about not searching for these keys.)`
+  // The STATIC charter + creds are the session system prompt (cached, billed once),
+  // NOT re-sent in every cycle's user message — the big token saving.
+  const systemPrompt = (canCode ? CODE_CHARTER : CHAT_CHARTER) + '\n\n' + credNote
+  const { runCycle } = createCycleRunner({
     claude, agent, mcpUrl, mcpHeaders: { 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier },
-    cfgKey: identifier, mcpConfig, workdir, log, debug, model,
+    cfgKey: identifier, mcpConfig, workdir, log, debug, model, systemPrompt,
     // The moment the agent calls post_message it is about to speak → "typing".
     onTool: (name) => { if (/post_message/.test(name)) emitStatus('typing') },
   })
@@ -417,11 +516,6 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   // events and drained into the next cycle's prompt.
   const pending = []
 
-  // The Mastra bridge authenticates per-CALL, not per-connection: every
-  // openvisio-team tool needs agent_identifier + agent_api_key as arguments.
-  // Hand them to the model up front so it never shells around hunting for them.
-  const credNote = `AUTH: the openvisio-team tools REQUIRE two arguments on EVERY call — agent_identifier: "${identifier}" and agent_api_key: "${apiKey}". Include BOTH on every openvisio-team tool call (post_message, poll_inbox, react_message, comment_ticket, get_marching_orders, …). These tools may appear in your tool list namespaced (mcp__openvisio-team__post_message on Claude Code, openvisio-team_post_message on opencode) — call whichever names you actually see. The credentials are given to you right here — do NOT hunt for them (no Bash/grep/cat/find, no reading memory); just call the tools with these exact values. (Bash/git/gh ARE for your code work — this rule is only about not searching for these keys.)`
-
   // Higher rank wins when coalescing cycles requested while one is running.
   const RANK = { fast: 0, intro: 1, sweep: 2, full: 3 }
   const baseFor = (kind) => kind === 'intro' ? INTRO : (kind === 'full' || kind === 'sweep') ? fullPrompt : fastPrompt
@@ -431,7 +525,9 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
     if (busy) { queued = (RANK[kind] ?? 0) >= (RANK[queued] ?? 0) ? kind : queued; log('busy — queued a ' + kind + ' follow-up cycle'); return }
     busy = true
     const ctx = pending.splice(0) // take everything accumulated so far
-    const prompt = credNote + '\n\n' + (ctx.length ? ctx.join('\n') + '\n\n' : '') + baseFor(kind)
+    // credNote + charter live in the cached system prompt now — the per-cycle
+    // message is just the event context + the small base instruction.
+    const prompt = (ctx.length ? ctx.join('\n') + '\n\n' : '') + baseFor(kind)
     // Chat-shaped cycles (mentions/intro) may run on the cheaper chat model; code
     // work (full/sweep) uses the main model.
     const useModel = (kind === 'fast' || kind === 'intro') ? liteModel : codeModel
@@ -465,6 +561,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
   }
@@ -573,7 +670,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)) {
@@ -584,7 +681,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)')
@@ -609,7 +710,11 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
 function loop({ host, key, slug, claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug }) {
   const log = (m) => process.stdout.write('[warm ' + new Date().toISOString() + '] ' + m + '\n')
   const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
-  const { runCycle, canCode } = createCycleRunner({ claude, agent, mcpUrl, mcpHeaders: { Authorization: 'Bearer ' + key }, cfgKey: slug, mcpConfig, workdir, log, debug, model })
+  const canCode = !!workdir
+  // Static charter as the cached system prompt (this loop's MCP authenticates via a
+  // Bearer header, so no per-call creds are needed in the prompt).
+  const systemPrompt = canCode ? CODE_CHARTER : CHAT_CHARTER
+  const { runCycle } = createCycleRunner({ claude, agent, mcpUrl, mcpHeaders: { Authorization: 'Bearer ' + key }, cfgKey: slug, mcpConfig, workdir, log, debug, model, systemPrompt })
   const fullPrompt = canCode ? CODE_FULL : CYCLE
   const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
   const liteModel = chatModel || model // cheaper model for chat/quick cycles
@@ -621,17 +726,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)
   }
 
@@ -666,7 +769,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
@@ -715,7 +823,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`)