openvisio-agent 0.4.0 → 0.6.0

package/bin/cli.mjs

@@ -26,7 +26,7 @@ Connect your coding agent to an OpenVisio team.
 Usage:
   openvisio-agent connect <ovs_code> --host <url> [--name "<agent>"] [--mcp-url <url>]
   openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--ws <wss-url>] [--mcp-url <url>]
-  openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--debug]
+  openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--model <m>] [--chat-model <m>] [--debug]
   openvisio-agent --help | --version
 
 connect
@@ -51,6 +51,13 @@ connect --backend
                      ~/openvisio-workspace; point it at an existing clones folder to
                      reuse those. (--workdir is an accepted alias.)
     --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".
+    --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).
     --no-service     skip the background service — just save config + print the
                      watch commands to run yourself.
 
@@ -110,7 +117,7 @@ async function runConnect({ positional, flags }) {
   const mcpCfg = mcpConfigPath(slug)
   writeJson(mcpCfg, { mcpServers: { 'openvisio-team': { type: 'http', url: mcpUrl, headers: { Authorization: `Bearer ${key}` } } } }, true)
   const wsWorkdir = flags.workdir === true ? process.cwd() : flags.workdir ? String(flags.workdir) : flags.workspace ? String(flags.workspace) : ''
-  writeJson(configPath(slug), { host: stripSlash(host), key, mcpUrl, name, slug, mcpConfig: mcpCfg, ...(wsWorkdir ? { workspace: wsWorkdir } : {}), ...(flags['chat-only'] ? { chatOnly: true } : {}) }, true)
+  writeJson(configPath(slug), { host: stripSlash(host), key, mcpUrl, name, slug, mcpConfig: mcpCfg, ...(wsWorkdir ? { workspace: wsWorkdir } : {}), ...(flags['chat-only'] ? { chatOnly: true } : {}), ...(flags.model ? { model: String(flags.model) } : {}), ...(flags['chat-model'] ? { chatModel: String(flags['chat-model']) } : {}) }, true)
 
   ok(`Connected "${name}" to ${host}.`)
   info()
@@ -122,6 +129,8 @@ async function runConnect({ positional, flags }) {
   info(`  openvisio-agent watch --name ${slug} --install             # background, auto-start on login`)
   info(`  openvisio-agent watch --name ${slug} --workspace <dir>     # reuse an existing clones folder`)
   info(`  openvisio-agent watch --name ${slug} --chat-only           # disable code work (chat/tickets only)`)
+  info(`  openvisio-agent watch --name ${slug} --model sonnet        # cheaper model (default); or opus/haiku`)
+  info('  (or change it live from chat: "@agent /model sonnet")')
 }
 
 // Backend mode — for agents created against the OpenVisio ORG BACKEND
@@ -176,7 +185,7 @@ async function runConnectBackend({ flags }) {
     writeJson(mcpConfig, { mcpServers: { 'openvisio-team': { type: 'http', url: mcpUrl, headers: { 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier } } } }, true)
   }
 
-  writeJson(configPath(slug), { mode: 'backend', backend, apiKey, identifier, name, slug, wsUrl, mcpUrl, mcpConfig, ...(workdir ? { workspace: workdir } : {}), ...(chatOnly ? { chatOnly: true } : {}) }, true)
+  writeJson(configPath(slug), { mode: 'backend', backend, apiKey, identifier, name, slug, wsUrl, mcpUrl, mcpConfig, ...(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 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Connect your coding agent (Claude Code) to an OpenVisio team — MCP tools + optional autonomy — in one command. No shell scripts.",
   "type": "module",
   "bin": {

package/src/watch.mjs

@@ -5,10 +5,10 @@
 // than written to disk from a pasted heredoc.
 
 import { spawn, spawnSync } from 'node:child_process'
-import { writeFileSync, mkdirSync } from 'node:fs'
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
-import { OV_DIR, DEFAULT_WORKSPACE, readConfig, onPath, fail, ok, info, slugify, stripSlash, chmodSafe } from './lib.mjs'
+import { OV_DIR, DEFAULT_WORKSPACE, readConfig, writeJson, configPath, onPath, fail, ok, info, slugify, stripSlash, chmodSafe } from './lib.mjs'
 import { connectAgentWs, assertWebSocket } from './ws.mjs'
 
 // Behaviour prompts. The openvisio-team MCP bridge requires the agent's
@@ -20,14 +20,27 @@ import { connectAgentWs, assertWebSocket } from './ws.mjs'
 // PROMISES work then stops, forcing the human to remind it to circle back. The
 // CHARTER blocks below assert the toolbox and mandate closing the loop in-cycle.
 
+// Applies to EVERY cycle (chat + code). This is what keeps an agent from becoming
+// noise — the failure modes seen in the wild: acknowledging the same task 3 times,
+// answering a question meant for a DIFFERENT agent, and claiming something works
+// then walking it back.
+const REPLY_DISCIPLINE = [
+  'REPLY DISCIPLINE — read the recent messages FIRST, then decide whether to speak at all:',
+  '  • IS IT FOR YOU? Act ONLY on messages addressed to YOU — an @mention of your exact name, a direct question to you, or a reply to something YOU said or did. If a DIFFERENT agent or person was @mentioned or asked to do something, STAY OUT: do not answer for them and do not pick up their task. When it is not yours, posting nothing is the correct move.',
+  '  • NO DUPLICATES. Before you post, scan the recent thread/channel for what YOU already said. If you already replied to or acknowledged this exact request, do NOT post again. One acknowledgement per task; one answer per question. While a task is in progress, post again ONLY when you have something genuinely NEW (a result, a link, a real blocker) — never re-post "on it".',
+  '  • BE SURE BEFORE YOU SPEAK. Do not claim something is possible, done, or broken until you have actually verified it — call the tool, read the code, check the real state. Never assert then contradict yourself. If you are unsure, verify FIRST, then give ONE clear, final answer instead of thinking out loud across several messages.',
+].join('\n')
+
 // ── CHAT-ONLY agents (no --workdir): chat/ticket tools, no code surface. ──────
 const CHAT_CHARTER = [
   'YOU ARE a connected agent in an OpenVisio team, running in CHAT-ONLY mode. Your tools are the openvisio-team chat/ticket tools (mcp__openvisio-team__*): post_message, poll_inbox, comment_ticket, react_message. You have NO file/Bash/git tools in this mode, so you cannot write code yourself.',
   'WORK ETHIC — behave like a dependable teammate: never leave a promise dangling. Either ACT now (reply, or file a ticket) or say plainly you can\'t and offer to file a ticket / tag a coding agent who can. Never invent progress. Close the loop every cycle — the human should never have to remind you to circle back.',
+  '',
+  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\nNew chat activity. If a specific mention is given above, post that reply FIRST with mcp__openvisio-team__post_message. Then call poll_inbox and handle any .followUps (thread replies you are part of, even without an @mention) — ignore .tasks/.claimable. Post AT MOST ONE reply per channel: if the same person sent several nudges, answer them together in ONE post. If asked for work you have no tool for, say so plainly and offer to file a ticket. Never invent progress. Reply in 1-3 sentences, no summary. Then stop.'
+const CYCLE_FAST = CHAT_CHARTER + '\n\nNew chat activity. If a specific mention FOR YOU is given above, reply to it with mcp__openvisio-team__post_message (once). Then call poll_inbox and look at .followUps — but reply ONLY to the ones actually directed at YOU (a question to you, or a reply to your own message); SKIP thread chatter aimed at someone else or another agent. Ignore .tasks/.claimable. AT MOST ONE reply per channel; answer several nudges together in ONE post; never repeat a reply you already sent. If asked for work you have no tool for, say so plainly and offer to file a ticket. Never invent progress. Reply in 1-3 sentences, no summary. Then stop.'
 
 // ── CODE agents (--workdir given): full file + Bash + git/gh surface. ─────────
 // A stable "who you are / how you work" charter prepended to every code cycle.
@@ -44,10 +57,13 @@ const CODE_CHARTER = [
   '  2. FINISH, then REPORT. Your LAST action every cycle is a status back to the requester: comment_ticket with what you did (branch + PR link + test result) AND a short channel reply that @mentions the person who asked, by their EXACT full name (a mention only links on an exact full-name match).',
   '  3. Be honest and specific. Never invent progress. If you are genuinely blocked (missing repo, unclear spec, a failing tool), say exactly what you need in one message — that IS closing the loop.',
   '  4. One reply per channel per cycle; answer several nudges together.',
+  '',
+  REPLY_DISCIPLINE,
 ].join('\n')
 
 const CODE_FULL = CODE_CHARTER + '\n\n' + [
   '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:',
   '  1. GET THE CODE: locate the target repo under your workspace root. If it\'s already a subfolder, cd in and `git pull`; if it isn\'t cloned yet, clone it into the workspace (gh repo clone <org>/<repo>, or git clone <url>) and cd in. Do this yourself — never ask the user for a path.',
   '  2. BRANCH: git checkout -B agent/<short-task-slug>. NEVER work on, commit to, or push main/master.',
@@ -59,12 +75,29 @@ const CODE_FULL = CODE_CHARTER + '\n\n' + [
 ].join('\n')
 
 const CODE_FAST = CODE_CHARTER + '\n\n' + [
-  'New chat activity. If a specific mention is given above, post that reply FIRST with mcp__openvisio-team__post_message — before any Bash.',
-  'Then poll_inbox and handle .followUps (thread replies you are part of, even without an @mention), at most one reply per channel.',
-  'If a message asks for real CODE work, do the WHOLE job now — branch (checkout -B agent/<slug>), edit, run tests, commit, push your branch, open a PR (gh pr create), then reply with the PR link and @mention the requester by exact full name. Never push to main, never --force, never merge.',
+  'New chat activity. If a specific mention FOR YOU is given above, reply to it FIRST with mcp__openvisio-team__post_message (once) — before any Bash.',
+  'Then poll_inbox and handle .followUps ONLY when the reply is directed at YOU (asks you something, or responds to your own message) — SKIP thread chatter aimed at someone else / another agent. At most one reply per channel, and never repeat a reply you already sent.',
+  'If a message asks YOU for real CODE work, do the WHOLE job now — branch (checkout -B agent/<slug>), edit, run tests, commit, push your branch, open a PR (gh pr create), then reply with the PR link and @mention the requester by exact full name. Never push to main, never --force, never merge.',
   'Do NOT promise and stop — finish and report in THIS cycle. Reply 1-3 sentences, no summary. Then stop.',
 ].join('\n')
 
+// ── Workspace-ethics cycles (both chat-only + code agents) ───────────────────
+// INTRO: a one-time hello when the agent first joins a workspace. SWEEP: a daily
+// (and on-startup) catch-up so nothing assigned while the agent was offline is
+// missed — TASKS especially.
+const INTRO = [
+  'You have just JOINED this OpenVisio workspace (your first connection). Workspace etiquette: introduce yourself so the team knows you are here and reachable.',
+  'Find the most general channel — call poll_inbox (or list channels) and pick the "general"/main one — then post_message there ONCE: give your name, say you are an AI teammate who picks up tasks assigned to you and answers @mentions, and invite people to mention you. 1-2 sentences, warm and professional.',
+  'Post it EXACTLY ONCE, then stop. Do NOT do any other work this cycle.',
+].join('\n')
+const SWEEP = [
+  'DAILY CATCH-UP — you may have missed items while offline. Prioritize TASKS.',
+  'Call get_marching_orders AND poll_inbox, then:',
+  '  1. For every task assigned to YOU that you have NOT started or acknowledged: acknowledge once (comment_ticket "Catching up — picking this up now"), then do the work end-to-end and report (branch/PR + a short channel note). Skip tasks assigned to other agents.',
+  '  2. Answer only the @mentions / follow-ups that were directed at YOU and that you have not already answered — at most one reply per channel. Do not reply to threads aimed at someone else.',
+  'If there is genuinely nothing outstanding, STOP silently — do NOT post a "nothing to do" message.',
+].join('\n')
+
 // Bash covers git/gh/clone/tests; the deny list is where the guardrails live.
 const CODE_TOOLS = ['Read', 'Grep', 'Glob', 'Edit', 'Write', 'MultiEdit', 'TodoWrite', 'Bash', 'mcp__openvisio-team__*']
 // Push + PR creation ARE allowed (agents raise PRs), but main/master, force-pushes,
@@ -110,6 +143,14 @@ 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. Default SONNET (cost-effective) rather than whatever
+  // `claude` defaults to — the agent shouldn't burn Opus tokens on routine chatter.
+  // Optional --chat-model runs the lighter chat/mention cycles on an even cheaper
+  // model while code cycles stay on the main one. Both persisted + live-changeable
+  // via the in-chat `/model` command (see loopBackendWs).
+  const model = String(flags.model || (saved && saved.model) || 'sonnet')
+  const chatModel = String(flags['chat-model'] || (saved && saved.chatModel) || '')
+
   // 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
@@ -121,7 +162,7 @@ export async function runWatch({ flags }) {
     if (!apiKey || !identifier) fail('No saved backend credentials for that agent.\n  Run `openvisio-agent connect --backend …` first, or pass --key and --id.')
     assertWebSocket(fail)
     if (flags.install) return installService({ slug: slug || 'openvisio', claude, mcpConfig, workdir })
-    return loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir, debug: !!flags.debug })
+    return loopBackendWs({ wsUrl, apiKey, identifier, slug: slug || 'openvisio', claude, mcpConfig, workdir, model, chatModel, debug: !!flags.debug })
   }
 
   const host = stripSlash(flags.host || (saved && saved.host) || '')
@@ -130,16 +171,20 @@ export async function runWatch({ flags }) {
 
   if (flags.install) return installService({ slug: slug || 'openvisio', claude, mcpConfig, workdir })
 
-  return loop({ host, key, claude, mcpConfig, workdir, debug: !!flags.debug })
+  return loop({ host, key, slug: slug || 'openvisio', claude, mcpConfig, workdir, model, chatModel, debug: !!flags.debug })
 }
 
 // ── 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, mcpConfig, workdir, log, debug }) {
+function createCycleRunner({ claude, mcpConfig, workdir, log, debug, model }) {
   const canCode = !!workdir
   const maxCycleMs = canCode ? MAX_CODE_CYCLE_MS : MAX_CYCLE_MS
   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
+  // session so the new model takes effect.
+  let sessionModel = model || null
   let turnsThisSession = 0
   let sessionStartedAt = 0
   let resolveTurn = null
@@ -165,7 +210,7 @@ function createCycleRunner({ claude, mcpConfig, workdir, log, debug }) {
   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]
+    const base = ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--strict-mcp-config', '--mcp-config', mcpConfig, ...(sessionModel ? ['--model', sessionModel] : [])]
     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
@@ -186,13 +231,19 @@ function createCycleRunner({ claude, mcpConfig, workdir, log, debug }) {
     })
     c.on('exit', (code) => { if (c !== child) { log('old session exited ' + code); return } log('session exited ' + code); child = null; settleTurn({ type: 'result', subtype: 'exit' }) })
     c.on('error', () => { if (c !== child) return; child = null; settleTurn({ type: 'result', subtype: 'error' }) })
-    log('warm session started' + (canCode
+    log('warm session started' + (sessionModel ? ' [model ' + sessionModel + ']' : '') + (canCode
       ? ' [CODE mode — workspace ' + workdir + ' — finds/clones the org\'s repos here, branches, pushes, opens PRs]'
       : ' [CHAT-ONLY mode (--chat-only) — chat/ticket tools only, no code work]'))
   }
 
-  function runCycle(prompt) {
+  function runCycle(prompt, cycleModel) {
     return new Promise((resolve) => {
+      // A per-cycle model override (e.g. chat on a cheaper model than code) — a
+      // change means the warm session must be respawned with the new --model.
+      if (cycleModel && cycleModel !== sessionModel) {
+        if (child) { log('model change ' + (sessionModel || 'default') + ' → ' + cycleModel + ' — recycling session'); try { child.kill() } catch { /* gone */ } child = null }
+        sessionModel = cycleModel
+      }
       if (child && (turnsThisSession >= MAX_TURNS || Date.now() - sessionStartedAt > SESSION_IDLE_MS)) {
         log('recycling session (turns=' + turnsThisSession + ')')
         try { child.kill() } catch { /* already gone */ }
@@ -219,19 +270,32 @@ function createCycleRunner({ claude, mcpConfig, workdir, log, debug }) {
 }
 
 // ── the backend WS loop ──────────────────────────────────────────────────────
-// Real-time: the backend pushes task:assigned / agent:mention over the WS; each
-// pushes ONE Claude cycle. Serialized (one cycle at a time) — events arriving
-// while busy are coalesced into a single follow-up cycle so a burst of mentions
-// doesn't stack up N sessions.
-function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir, debug }) {
+// Real-time: the backend pushes task:created/task:updated (assignments) + agent:mention
+// over the WS; each pushes ONE Claude cycle. Serialized (one cycle at a time) — events
+// arriving while busy are coalesced into a single follow-up cycle so a burst doesn't
+// stack up N sessions. Plus a one-time intro on first connect and a daily catch-up sweep.
+function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, mcpConfig, workdir, model, chatModel, debug }) {
   const log = (m) => process.stdout.write('[ws ' + new Date().toISOString() + '] ' + m + '\n')
-  const { runCycle, canCode } = createCycleRunner({ claude, mcpConfig, workdir, log, debug })
+  const { runCycle, canCode } = createCycleRunner({ claude, mcpConfig, workdir, log, debug, model })
   const fullPrompt = canCode ? CODE_FULL : CYCLE
   const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
+  // Live model state — changeable at runtime by the in-chat `/model` command.
+  // codeModel drives full/sweep cycles; chatModel (if set) the lighter fast/intro
+  // ones, so routine chatter can run cheaper than real code work.
+  let codeModel = model
+  let liteModel = chatModel || model
 
   let busy = false
-  let queued = null // 'full' | 'fast' — a cycle requested while one was running
+  let queued = null // 'full' | 'fast' | 'sweep' | 'intro' — a cycle requested while one was running
   let handle = null
+  // Tasks we've already reacted to (keyed task-id:agent — so a REASSIGNMENT to a
+  // different agent re-triggers), so a noisy stream of task:updated events doesn't
+  // re-acknowledge the same assignment.
+  const seenTasks = new Set()
+  // Mentions we've already reacted to (by message id) — the backend can re-deliver
+  // an agent:mention (reconnect replay, dup fan-out), which otherwise makes the
+  // agent reply to the SAME message twice.
+  const seenMentions = new Set()
   // Context lines from the events themselves (the WS payload already carries the
   // channel + message / task), so the agent acts on THEM directly instead of
   // hoping poll_inbox re-surfaces the same item. Accumulated across coalesced
@@ -243,16 +307,22 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
   // Hand them to the model up front so it never shells around hunting for them.
   const credNote = `AUTH: the openvisio-team (mcp__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, …). They are given to you right here — do NOT hunt for them (no Bash/grep/cat/find to locate credentials, 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
+
   async function drain(kind, context) {
     if (context) pending.push(context)
-    if (busy) { queued = (queued === 'full' || kind === 'full') ? 'full' : 'fast'; log('busy — queued a ' + kind + ' follow-up cycle'); return }
+    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 base = kind === 'full' ? fullPrompt : fastPrompt
-    const prompt = credNote + '\n\n' + (ctx.length ? ctx.join('\n') + '\n\n' : '') + base
-    log('running ' + kind + ' cycle…' + (ctx.length ? ' (' + ctx.length + ' event' + (ctx.length === 1 ? '' : 's') + ')' : ''))
+    const prompt = credNote + '\n\n' + (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
+    log('running ' + kind + ' cycle…' + (ctx.length ? ' (' + ctx.length + ' event' + (ctx.length === 1 ? '' : 's') + ')' : '') + (useModel ? ' [' + useModel + ']' : ''))
     try {
-      await runCycle(prompt)
+      await runCycle(prompt, useModel)
     } finally {
       busy = false
       if (queued || pending.length) { const next = queued || 'fast'; queued = null; void drain(next) }
@@ -267,13 +337,51 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
     return (`${s.first_name || ''} ${s.last_name || ''}`.trim() || s.name || s.email || '')
   }
 
+  // Engineers change the model under the hood from chat: "/model", "/model sonnet",
+  // "use model haiku", "switch model to opus". Returns {report} | {set} | {invalid}.
+  const normalizeModel = (s) => {
+    const x = String(s || '').toLowerCase().replace(/[.,!?]+$/, '')
+    if (x === 'opus' || x === 'sonnet' || x === 'haiku') return x
+    return /^claude-[a-z0-9.\-\[\]]+$/i.test(x) ? x : null
+  }
+  const parseModelCmd = (text) => {
+    // Slash form is unambiguous: "/model" (report) or "/model <name>".
+    const slash = /(?:^|\s)\/model\b(?:\s+(\S+))?/i.exec(text)
+    if (slash) { const a = slash[1]; if (!a) return { report: true }; const n = normalizeModel(a); return n ? { set: n } : { invalid: a } }
+    // Natural language: only when a VALID model name is explicitly given after the
+    // word "model" — so "use the model file in the repo" does NOT switch anything.
+    const nl = /\b(?:set|switch|change|use)\s+(?:the\s+|your\s+)?model\s+(?:to\s+)?(\S+)/i.exec(text)
+    if (nl) { const n = normalizeModel(nl[1]); if (n) return { set: n } }
+    if (/\b(?:which|what)\s+model\s+(?:are\s+you|do\s+you|you\b)/i.test(text)) return { report: true }
+    return null
+  }
+  // Persist a model change so a restart / the background service keeps it.
+  const persistModel = (mdl) => {
+    if (!slug) return
+    try { writeJson(configPath(slug), { ...(readConfig(slug) || {}), model: mdl, chatModel: mdl }, true) } catch { /* best-effort */ }
+  }
+
   function onEvent(k, d) {
     const raw = d && typeof d === 'object' ? d : {}
-    if (k === 'task:assigned') {
-      const t = raw.task || {}
-      log('task:assigned ' + (t.id != null ? '#' + t.id + ' “' + (t.title || '') + '”' : ''))
+    // The backend has NO `task:assigned` event — a task assigned to an agent arrives
+    // as `task:created` (assigned on create) or `task:updated` (assignee changed),
+    // fanned out org-wide. Catch both, keep only agent-assigned tasks, and let the
+    // cycle confirm ownership via get_marching_orders before acting.
+    if (k === 'task:created' || k === 'task:updated') {
+      const t = raw.task && typeof raw.task === 'object' ? raw.task : {}
+      const agentId = t.agent_id != null ? t.agent_id : (t.agentId != null ? t.agentId : null)
+      if (agentId == null) return // not assigned to an agent — ignore
+      // If the payload carries the agent's identifier, filter precisely to US and skip
+      // other agents' tasks entirely; otherwise let get_marching_orders confirm.
+      const ag = (t.agent && typeof t.agent === 'object') ? t.agent : null
+      const agIdent = ag && (ag.identifier || ag.slug) ? String(ag.identifier || ag.slug) : null
+      if (agIdent != null && agIdent !== identifier) return
+      const key = `${t.id}:${agentId}`
+      if (t.id != null && seenTasks.has(key)) return
+      if (t.id != null) { seenTasks.add(key); if (seenTasks.size > 500) seenTasks.clear() }
+      log('task ' + k.slice(5) + ' #' + (t.id != null ? t.id : '?') + ' (agent ' + agentId + ') “' + (t.title || '') + '”')
       const desc = t.description ? ' — ' + String(t.description).replace(/\s+/g, ' ').slice(0, 400) : ''
-      void drain('full', t.id != null ? `You were ASSIGNED task #${t.id}: "${t.title || ''}"${desc}. Handle it, then comment_ticket with a short summary.` : undefined)
+      void drain('full', `A task was just ${k === 'task:created' ? 'created and assigned' : 'assigned'} to an agent in this workspace — task #${t.id != null ? t.id : '?'}: "${t.title || ''}"${desc} (agent_id ${agentId}). Call get_marching_orders to confirm it is assigned to YOU. If it IS yours: FIRST post a brief comment_ticket acknowledgement ("On it — picking this up now, will update shortly"), THEN do the work end-to-end and report back (branch/PR + a channel note). If it is NOT yours, do nothing and stop.`)
     } else if (k === 'agent:mention') {
       const cid = raw.channel_id != null ? raw.channel_id : (raw.channelId != null ? raw.channelId : null)
       const msg = raw.message && typeof raw.message === 'object' ? raw.message : {}
@@ -284,9 +392,33 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
       const mid = msg.id != null ? msg.id : (msg.message_id != null ? msg.message_id : null)
       const parent = msg.parent_id != null ? msg.parent_id : (msg.parentId != null ? msg.parentId : null)
       const threadRoot = parent != null ? parent : mid
+      // De-dupe: the same mention re-delivered (reconnect replay / dup fan-out) must
+      // NOT trigger a second reply to the same message.
+      if (mid != null) {
+        if (seenMentions.has(mid)) { log('agent:mention (dup ' + mid + ') — skipped'); return }
+        seenMentions.add(mid); if (seenMentions.size > 500) seenMentions.clear()
+      }
+      // Under-the-hood model control from chat (view / switch the model the agent runs).
+      const mcmd = cid != null ? parseModelCmd(text) : null
+      if (mcmd) {
+        const thread = threadRoot != null ? `, parent_id ${threadRoot}` : ''
+        if (mcmd.report) {
+          log('model query → ' + codeModel + (liteModel !== codeModel ? ' / chat ' + liteModel : ''))
+          void drain('fast', `An engineer asked which model you're running. Reply once in channel ${cid}${thread} (with your agent creds): "I'm currently running on ${codeModel}${liteModel !== codeModel ? ` (chat replies on ${liteModel})` : ''}." One line. Then stop.`)
+        } else if (mcmd.invalid) {
+          void drain('fast', `An engineer tried to switch your model to "${mcmd.invalid}", which isn't one you recognize. Reply once in channel ${cid}${thread} (with your agent creds): say you support "opus", "sonnet", "haiku", or a full "claude-…" id, and ask which they meant. One line. Then stop.`)
+        } else {
+          const prev = codeModel
+          codeModel = mcmd.set; liteModel = mcmd.set
+          persistModel(mcmd.set)
+          log('model switched ' + prev + ' → ' + codeModel + (who ? ' (by ' + who + ')' : ''))
+          void drain('fast', `An engineer switched your underlying model to "${codeModel}" — it is now active for your next actions. Post ONE short confirmation in channel ${cid}${thread} (with your agent creds): e.g. "Switched to ${codeModel} — I'll run on it from here." Then stop.`)
+        }
+        return
+      }
       log('agent:mention in channel ' + (cid != null ? cid : '?') + (threadRoot != null ? ' (thread ' + threadRoot + ')' : ''))
       const ctx = cid != null
-        ? `You were @mentioned in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". Reply with mcp__openvisio-team__post_message as your FIRST action — arguments: channel_id ${cid}${threadRoot != null ? `, parent_id ${threadRoot} (reply IN THAT THREAD, do not start a new top-level message)` : ''}, plus agent_identifier + agent_api_key from the AUTH line above, and a 1-3 sentence reply.${who ? ` To @mention them back, write their EXACT full name "@${who}" (a mention only links when the name matches exactly — "@${who.split(' ')[0]}" alone will NOT).` : ''} You already have the message here — do NOT poll_inbox to find it.`
+        ? `You were @mentioned in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". This mention is FOR YOU — reply once with mcp__openvisio-team__post_message as your FIRST action — arguments: channel_id ${cid}${threadRoot != null ? `, parent_id ${threadRoot} (reply IN THAT THREAD, do not start a new top-level message)` : ''}, plus agent_identifier + agent_api_key from the AUTH line above, and a 1-3 sentence reply. FIRST read the recent messages in this thread: if you already answered this, or it turns out another agent was the one addressed, do NOT post. Be sure of your answer before sending — do not reply then correct yourself.${who ? ` To @mention them back, write their EXACT full name "@${who}" (a mention only links when the name matches exactly — "@${who.split(' ')[0]}" alone will NOT).` : ''} You already have the message here — do NOT poll_inbox to find it.`
         : undefined
       void drain('fast', ctx)
     } else if (k === 'error') {
@@ -297,35 +429,77 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
     }
   }
 
-  // NO polling — the WebSocket is the only trigger (task:assigned / agent:mention).
-  // A thread reply that @mentions the agent fires agent:mention and is handled
-  // in-thread above; genuinely un-mentioned thread activity has no WS event, so
-  // it's a backend concern (dispatch a thread event to participant agents), not a
-  // reason to poll.
+  // The WebSocket drives real-time reactions (task:created/updated assigned to us,
+  // agent:mention). A thread reply that @mentions the agent fires agent:mention and
+  // is handled in-thread above. In addition we run a DAILY (and on-startup) sweep
+  // so anything assigned while the agent was offline — tasks especially — is still
+  // picked up even though we don't hot-poll.
   log('up — backend WS watcher on ' + wsUrl + (canCode ? ' [code: ' + workdir + ']' : ''))
   handle = connectAgentWs({ wsUrl, apiKey, identifier, onEvent, log })
 
+  const DAY_MS = 24 * 60 * 60 * 1000
+  let introTimer = null, sweepStartTimer = null, sweepTimer = null
+  if (mcpConfig) {
+    // 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)) {
+      try { mkdirSync(OV_DIR, { recursive: true }); writeFileSync(introMarker, new Date().toISOString() + '\n') } catch { /* best-effort */ }
+      log('first connection — introducing self to the workspace')
+      introTimer = setTimeout(() => void drain('intro'), 5000) // let the socket subscribe first
+    }
+    // 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)
+    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)')
+  }
+
   return new Promise(() => {
-    // Run until killed. Tidy up the socket on termination so a restarting
-    // service doesn't leak a half-open connection.
-    const bye = () => { try { handle && handle.close() } catch { /* noop */ } process.exit(0) }
+    // Run until killed. Tidy up the socket + timers on termination so a restarting
+    // service doesn't leak a half-open connection or a dangling interval.
+    const bye = () => {
+      if (introTimer) clearTimeout(introTimer)
+      if (sweepStartTimer) clearTimeout(sweepStartTimer)
+      if (sweepTimer) clearInterval(sweepTimer)
+      try { handle && handle.close() } catch { /* noop */ }
+      process.exit(0)
+    }
     process.on('SIGTERM', bye)
     process.on('SIGINT', bye)
   })
 }
 
 // ── the warm loop ────────────────────────────────────────────────────────────
-function loop({ host, key, claude, mcpConfig, workdir, debug }) {
+function loop({ host, key, slug, claude, mcpConfig, 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, mcpConfig, workdir, log, debug })
+  const { runCycle, canCode } = createCycleRunner({ claude, mcpConfig, workdir, log, debug, model })
   const fullPrompt = canCode ? CODE_FULL : CYCLE
   const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
+  const liteModel = chatModel || model // cheaper model for chat/quick cycles
 
   const seen = new Set()
   let busy = false
   let firstCheck = true
   let lastNewAt = Date.now()
+  // 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) {
+    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)
+    setInterval(() => { log('daily catch-up sweep'); queuedSpecial = SWEEP + '\n\n' + fullPrompt }, 24 * 60 * 60 * 1000)
+  }
 
   async function check() {
     const res = await fetch(host + '/api/agent/inbox', { headers: { authorization: 'Bearer ' + key } })
@@ -345,6 +519,15 @@ function loop({ host, key, claude, mcpConfig, workdir, debug }) {
     for (;;) {
       let delay = FAST
       try {
+        // Run a queued one-off (intro / daily sweep) first when free, on the same
+        // runCycle so it never overlaps a normal cycle.
+        if (!busy && queuedSpecial) {
+          const p = queuedSpecial; queuedSpecial = null
+          busy = true
+          try { await runCycle(p, model) } finally { busy = false; lastNewAt = Date.now() }
+          await sleep(FAST)
+          continue
+        }
         const res = busy ? { items: [], paused: false } : await check()
         const items = Array.isArray(res.items) ? res.items : []
         if (firstCheck && Array.isArray(res.items)) {
@@ -362,14 +545,14 @@ function loop({ host, key, claude, mcpConfig, workdir, debug }) {
               const q = await quickReply()
               if (q && q.ok) {
                 log(fresh.length + ' new -> quick reply (' + (q.replied || 0) + ' posted)')
-                if (q.needsWork && canCode) { log('needs work -> full cycle'); await runCycle(fullPrompt) }
+                if (q.needsWork && canCode) { log('needs work -> full cycle'); await runCycle(fullPrompt, model) }
               } else {
                 log(fresh.length + ' new -> fast reply (claude fallback)')
-                await runCycle(fastPrompt)
+                await runCycle(fastPrompt, liteModel)
               }
             } else {
               log(fresh.length + ' new item(s) -> full cycle' + (canCode ? ' [code]' : ''))
-              await runCycle(fullPrompt)
+              await runCycle(fullPrompt, model)
             }
             for (const i of items) seen.add(i)
             if (seen.size > 500) { seen.clear(); for (const i of items) seen.add(i) }