openvisio-agent 0.3.7 → 0.5.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] [--workdir <repo>] [--debug]
+  openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--debug]
   openvisio-agent --help | --version
 
 connect
@@ -45,14 +45,23 @@ connect --backend
                      — enables real-time autonomy (task:assigned / agent:mention).
     --mcp-url <url>  registers the openvisio-team MCP so the agent has tools to ACT
                      on those events. Needs Node >= 21 for the WebSocket.
-    --workdir <repo> the always-on listener may do real coding on a branch there.
+    --workspace <dir> where the agent works. CODE mode is ON BY DEFAULT — it finds
+                     the org's repos here (cloning any it doesn't have yet), branches,
+                     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.)
+    --chat-only      disable code work — chat/ticket tools only.
     --no-service     skip the background service — just save config + print the
                      watch commands to run yourself.
 
 watch
-  Runs the event-driven autonomy loop (reply to mentions, pick up tickets). Add
-  --install to run it in the background on login. Add --workdir <repo> to let it do
-  real work on a git branch (never pushes).
+  Runs the event-driven autonomy loop (reply to mentions, pick up tickets). CODE
+  mode is ON BY DEFAULT: the agent finds the org's repos in its workspace
+  (~/openvisio-workspace, cloning any it doesn't have yet), branches, commits, pushes
+  its agent/* branch, opens PRs, then circles back with the PR link and @mentions the
+  requester — never touching main/master, never force-pushing or merging. No per-repo
+  setup needed. Use --workspace <dir> to relocate it (e.g. an existing clones folder),
+  --chat-only to disable code work, and --install to run in the background on login.
 
 Docs: https://www.npmjs.com/package/openvisio-agent`
 
@@ -100,16 +109,19 @@ async function runConnect({ positional, flags }) {
   // A scoped MCP config (for the watcher's --strict-mcp-config) + a saved profile.
   const mcpCfg = mcpConfigPath(slug)
   writeJson(mcpCfg, { mcpServers: { 'openvisio-team': { type: 'http', url: mcpUrl, headers: { Authorization: `Bearer ${key}` } } } }, true)
-  writeJson(configPath(slug), { host: stripSlash(host), key, mcpUrl, name, slug, mcpConfig: mcpCfg }, 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)
 
   ok(`Connected "${name}" to ${host}.`)
   info()
   info('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):')
-  info(`  openvisio-agent watch --name ${slug}                    # run now, in this terminal`)
-  info(`  openvisio-agent watch --name ${slug} --install          # run in the background on login`)
-  info(`  openvisio-agent watch --name ${slug} --workdir <repo>   # allow real coding on a branch`)
+  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):')
+  info(`  openvisio-agent watch --name ${slug}                       # run now, in this terminal`)
+  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)`)
 }
 
 // Backend mode — for agents created against the OpenVisio ORG BACKEND
@@ -140,6 +152,13 @@ async function runConnectBackend({ flags }) {
   const name = (flags.name && String(flags.name)) || 'backend-agent'
   const slug = slugify(name)
 
+  // Code workspace preference (optional). CODE mode is on by default; this only
+  // pins WHERE the agent works. Persisted so the always-on `watch` reuses it.
+  const chatOnly = !!flags['chat-only']
+  const workdir = flags.workdir === true ? process.cwd()
+    : flags.workdir ? String(flags.workdir)
+    : flags.workspace ? String(flags.workspace) : ''
+
   // Optional real-time autonomy: --ws is the org's API-Gateway WS base (same value
   // as the frontend's NEXT_PUBLIC_BACKEND_WS_URL). --mcp-url gives the agent a tool
   // surface so WS events (task:assigned / agent:mention) can drive a Claude cycle.
@@ -157,7 +176,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 }, true)
+  writeJson(configPath(slug), { mode: 'backend', backend, apiKey, identifier, name, slug, wsUrl, mcpUrl, mcpConfig, ...(workdir ? { workspace: workdir } : {}), ...(chatOnly ? { chatOnly: true } : {}) }, true)
   // A sourceable env file, matching the setup snippet OpenVisio shows.
   const envPath = join(OV_DIR, `${slug}.env`)
   mkdirSync(OV_DIR, { recursive: true })
@@ -188,7 +207,6 @@ async function runConnectBackend({ flags }) {
   // Real-time autonomy IS the point of a backend agent: install the command and a
   // background service that auto-starts on login, so a mention is always caught —
   // no terminal left open, survives reboot. Opt out with --no-service.
-  const workdir = flags.workdir === true ? process.cwd() : (flags.workdir ? String(flags.workdir) : '')
   if (flags['no-service'] || process.platform === 'win32') {
     ensureAgentInstalled()
     info()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.3.7",
+  "version": "0.5.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/lib.mjs

@@ -7,6 +7,12 @@ import { join } from 'node:path'
 import { mkdirSync, writeFileSync, readFileSync, chmodSync } from 'node:fs'
 
 export const OV_DIR = join(homedir(), '.openvisio')
+// The agent's default code WORKSPACE — a single dedicated root that holds the org's
+// repos as subfolders. Code mode is on by default and the agent clones missing
+// repos in here, so a coding assistant works out of the box with NO per-repo config
+// (override with --workdir/--workspace to point at an existing clones folder). Kept
+// separate from the user's own checkouts so the agent never stomps a working tree.
+export const DEFAULT_WORKSPACE = join(homedir(), 'openvisio-workspace')
 const IS_WIN = process.platform === 'win32'
 
 export function fail(msg) { console.error('✖ ' + msg); process.exit(1) }

package/src/watch.mjs

@@ -5,22 +5,97 @@
 // 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, readConfig, onPath, fail, ok, info, slugify, stripSlash, chmodSafe } from './lib.mjs'
+import { OV_DIR, DEFAULT_WORKSPACE, readConfig, 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
 // credentials as ARGUMENTS on every tool call — those are injected at runtime by
 // loopBackendWs (see credNote), NOT baked in here, so nothing needs hunting.
-const CYCLE = 'Run one OpenVisio autonomy cycle.'
-const CYCLE_FAST = 'New chat activity in OpenVisio. 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. HONESTY: your only tools are the openvisio-team chat/ticket tools — you cannot write code or touch other tools; if asked for work you have no tool for, say so plainly in one short message (or offer to file a ticket). Never invent progress. Reply in 1-3 sentences, no summary. Then stop.'
-const CODE_FULL = 'Run one OpenVisio autonomy cycle. Call get_marching_orders and poll_inbox. You have file + Bash tools and a git repo at your working directory FOR CODE WORK ONLY. For assigned tickets or mentions asking for real code work: FIRST "git checkout -B agent/work", make the changes with Read/Edit/Write, run tests if present, then "git add -A && git commit -m ...". NEVER git push, merge, or touch main. Then comment_ticket with a short summary + the branch name, and post a brief channel reply. Do NOT use Bash to find credentials — they are given to you. If you truly cannot (missing repo/specs), say so in one message — never fabricate.'
-const CODE_FAST = 'New chat activity in OpenVisio. If a specific mention is given above, post that reply FIRST with mcp__openvisio-team__post_message — do this 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. Only if a message asks for real CODE work in your git repo, do it on a branch (checkout -B agent/work, edit, commit locally — never push/merge) and reply with the branch name. Bash is for git/tests ONLY, never for credentials. 1-3 sentences, no summary. Then stop.'
+//
+// Two recurring failures these prompts fix head-on: (1) the agent UNDER-READS its
+// own capabilities — says "I can't check a codebase" when it can — and (2) it
+// 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.
 
+// ── 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.',
+].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.'
+
+// ── CODE agents (--workdir given): full file + Bash + git/gh surface. ─────────
+// A stable "who you are / how you work" charter prepended to every code cycle.
+const CODE_CHARTER = [
+  'YOU ARE a connected CODING agent in an OpenVisio team, running ON THE USER\'S LAPTOP. You have REAL tools — use them; do NOT claim you lack a capability without checking what you actually hold. Your toolbox:',
+  '  • openvisio-team chat/ticket tools (mcp__openvisio-team__*) — read mentions, post messages, comment on tickets, react.',
+  '  • Read / Grep / Glob / Edit / Write / MultiEdit — inspect AND change code.',
+  '  • Bash — git (branch, commit, push a branch), gh (clone repos, open PRs), run tests/builds.',
+  'YOUR WORKSPACE: your working directory is a WORKSPACE ROOT that holds the org\'s repos as subfolders. You are NOT limited to one repo — you work across ALL of them from here. For any task: find the relevant repo under the workspace; if it isn\'t cloned yet, CLONE it (gh repo clone <org>/<repo>, or git clone <url>) and then work inside that subfolder. Never make the user tell you a path or clone things for you.',
+  'CAPABILITY CHECK: before you EVER answer "I can\'t do that", verify against the tools above. If a tool exists for it, DO it. To be explicit: you CAN read/inspect any of the org\'s codebases, clone a repo you don\'t have yet, work on it, create a branch, and raise a PR — say YES to these and then actually do them.',
+  '',
+  'WORK ETHIC — how a reliable teammate behaves (this is the difference between useful and ignored):',
+  '  1. CLOSE THE LOOP in THIS cycle. Never say "I\'ll do X" and stop. If you commit to something, do it NOW — the human must never have to remind you to circle back.',
+  '  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.',
+].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 FIRST: for a task assigned to you, post a one-line comment_ticket ("On it — picking this up now") BEFORE you start, so the team sees you have it. Then do the work and report when done.',
+  '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.',
+  '  3. CHANGE + VERIFY: Read/Edit/Write the files; run the tests or build if the repo has them.',
+  '  4. COMMIT + PUSH YOUR BRANCH: git add -A && git commit -m "…"; then git push -u origin agent/<slug>. Only ever push your own agent/* branch. Never --force, never push to main/master, never merge.',
+  '  5. RAISE A PR: gh pr create --fill --base <default-branch> --head agent/<slug> (a clear title + a body summarizing the change and how you verified it). Never gh pr merge.',
+  '  6. CLOSE THE LOOP: comment_ticket with the summary + PR link/branch, and post a channel reply that @mentions the requester by their exact full name.',
+  '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' + [
+  '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.',
+  '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: post a brief comment_ticket acknowledgement first ("Catching up — picking this up now"), then do the work end-to-end and report (branch/PR + a short channel note).',
+  '  2. Answer any @mentions or thread follow-ups you missed — at most one reply per channel.',
+  '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__*']
-const DENY_TOOLS = ['Bash(git push:*)', 'Bash(git reset --hard:*)', 'Bash(git clean:*)', 'Bash(rm:*)', 'Bash(sudo:*)', 'Bash(chmod:*)', 'Bash(curl:*)', 'Bash(wget:*)', 'Bash(npm publish:*)', 'Bash(pnpm publish:*)', 'Bash(gh pr merge:*)', 'Bash(gh repo:*)']
+// Push + PR creation ARE allowed (agents raise PRs), but main/master, force-pushes,
+// merges and destructive/publishing/repo-deleting commands stay blocked.
+const DENY_TOOLS = [
+  'Bash(git push --force:*)', 'Bash(git push -f:*)', 'Bash(git push --force-with-lease:*)',
+  'Bash(git push origin main:*)', 'Bash(git push origin master:*)',
+  'Bash(git push origin HEAD:main:*)', 'Bash(git push origin HEAD:master:*)',
+  'Bash(git reset --hard:*)', 'Bash(git clean:*)',
+  'Bash(rm:*)', 'Bash(sudo:*)', 'Bash(chmod:*)', 'Bash(curl:*)', 'Bash(wget:*)',
+  'Bash(npm publish:*)', 'Bash(pnpm publish:*)',
+  'Bash(gh pr merge:*)', 'Bash(gh repo delete:*)',
+]
 
 const FAST = 2500
 const SLOW = 6000
@@ -29,15 +104,29 @@ const MAX_TURNS = 15
 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
-// true forever and silently queue every later mention.
+// true forever and silently queue every later mention. Code cycles get a much
+// longer budget: a real clone → branch → test → push → PR flow legitimately takes
+// 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
 
 export async function runWatch({ flags }) {
   const slug = flags.name ? slugify(String(flags.name)) : null
   const saved = slug ? readConfig(slug) : null
   const claude = String(flags.claude || onPath('claude') || 'claude')
   const mcpConfig = String(flags['mcp-config'] || (saved && saved.mcpConfig) || '')
-  const workdir = flags.workdir === true ? process.cwd() : (flags.workdir ? String(flags.workdir) : '')
+  // Code mode is the DEFAULT: an agent lives on the user's laptop and should just be
+  // able to work across the org's repos with no per-repo setup. So `workdir` resolves
+  // to (in order) an explicit --workdir/--workspace, the saved workspace, or the
+  // shared DEFAULT_WORKSPACE — always non-empty unless the agent is opted into
+  // --chat-only. It's a WORKSPACE ROOT (holds repos as subfolders + clones missing
+  // ones), not a single repo. Created on demand so the Claude session can cwd into it.
+  const chatOnly = !!flags['chat-only'] || (saved && saved.chatOnly === true)
+  const explicitWorkdir = flags.workdir === true ? process.cwd()
+    : flags.workdir ? String(flags.workdir)
+    : flags.workspace ? String(flags.workspace) : ''
+  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 */ } }
 
   // 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.
@@ -59,7 +148,7 @@ 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, debug: !!flags.debug })
 }
 
 // ── Claude Code warm-session cycle runner (shared by the REST + WS loops) ─────
@@ -67,6 +156,7 @@ export async function runWatch({ flags }) {
 // after MAX_TURNS or SESSION_IDLE_MS. Returns { runCycle, canCode }.
 function createCycleRunner({ claude, mcpConfig, workdir, log, debug }) {
   const canCode = !!workdir
+  const maxCycleMs = canCode ? MAX_CODE_CYCLE_MS : MAX_CYCLE_MS
   let child = null
   let turnsThisSession = 0
   let sessionStartedAt = 0
@@ -114,7 +204,9 @@ 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')
+    log('warm session started' + (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) {
@@ -131,11 +223,11 @@ function createCycleRunner({ claude, mcpConfig, workdir, log, debug }) {
       // and queued mentions can proceed.
       clearCycleTimer()
       cycleTimer = setTimeout(() => {
-        log('cycle TIMED OUT after ' + Math.round(MAX_CYCLE_MS / 1000) + 's — killing the session so the queue can proceed')
+        log('cycle TIMED OUT after ' + Math.round(maxCycleMs / 1000) + 's — killing the session so the queue can proceed')
         try { child && child.kill() } catch { /* already gone */ }
         child = null
         settleTurn({ type: 'result', subtype: 'timeout' })
-      }, MAX_CYCLE_MS)
+      }, maxCycleMs)
       try { child.stdin.write(JSON.stringify({ type: 'user', message: { role: 'user', content: prompt } }) + '\n') }
       catch { settleTurn({ type: 'result', subtype: 'write-failed' }) }
     })
@@ -145,10 +237,10 @@ 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.
+// 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, claude, mcpConfig, workdir, debug }) {
   const log = (m) => process.stdout.write('[ws ' + new Date().toISOString() + '] ' + m + '\n')
   const { runCycle, canCode } = createCycleRunner({ claude, mcpConfig, workdir, log, debug })
@@ -156,8 +248,12 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
   const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
 
   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()
   // 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
@@ -167,15 +263,18 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
   // 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 (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 search for them, do NOT run Bash/shell/grep/cat/find, do NOT read memory — just call the tools with these exact values.`
+  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
+    const prompt = credNote + '\n\n' + (ctx.length ? ctx.join('\n') + '\n\n' : '') + baseFor(kind)
     log('running ' + kind + ' cycle…' + (ctx.length ? ' (' + ctx.length + ' event' + (ctx.length === 1 ? '' : 's') + ')' : ''))
     try {
       await runCycle(prompt)
@@ -195,11 +294,25 @@ function loopBackendWs({ wsUrl, apiKey, identifier, claude, mcpConfig, workdir,
 
   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 : {}
@@ -223,25 +336,48 @@ 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.
+    sweepStartTimer = setTimeout(() => { log('startup catch-up sweep'); void drain('sweep', SWEEP) }, 30_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, 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 })
@@ -252,6 +388,22 @@ function loop({ host, key, claude, mcpConfig, workdir, debug }) {
   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 }, 30_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 } })
@@ -271,6 +423,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) } 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)) {