openvisio-agent 0.18.15 → 0.19.1

package/README.md

@@ -17,7 +17,7 @@ That's it. Your selected runtime now has the team's tools (channels, tickets, do
 
 ## What it does
 
-`openvisio-agent` is a tiny, dependency-free CLI. It does exactly two things, and nothing is fetched-and-executed — the whole source is right here and on npm.
+`openvisio-agent` is a local CLI and autonomy harness. Nothing is fetched-and-executed outside its declared npm dependencies; the source is here and on npm.
 
 ### `connect <ovs_code> --host <url>`
 
@@ -50,11 +50,15 @@ npx -y openvisio-agent@latest connect --backend https://api.your-org.example/dev
 - `--ws <wss-url>` — the org's API-Gateway WebSocket base (the same value the frontend uses as `NEXT_PUBLIC_BACKEND_WS_URL`).
 - `--mcp-url <url>` — registers the `openvisio-team` MCP (authed with the agent header pair) so the agent has tools to **act** on the events.
 
-Then `watch --name ada` auto-detects the backend agent and runs a WebSocket loop instead of polling: it connects with `?api_key=&identifier=`, keeps the connection warm with keepalives, reconnects with backoff, and queues each accepted assignment or mention independently. A work cycle can contain many assistant, tool, and message actions; emitting a progress message does not end it. Needs **Node ≥ 21** for the built-in WebSocket (Node 20: run with `--experimental-websocket`).
+Then `watch --name ada` auto-detects the backend agent and runs a WebSocket loop instead of polling: it connects with `?api_key=&identifier=`, keeps the connection warm with keepalives, reconnects with backoff, and queues each accepted assignment or mention independently. A work cycle can contain many assistant, tool, and message actions; emitting a progress message does not end it. The Mastra runtime requires **Node ≥ 22.13**.
 
 ### `watch --name <agent>`
 
-Runs the **autonomy loop** — the agent replies to @mentions and picks up tickets on its own. It cheaply polls an inbox endpoint (no model spend when idle) and pokes a single warm Claude Code session only when something new arrives.
+Runs the **autonomy loop** — the agent replies to @mentions and picks up tickets on its own. It cheaply polls an inbox endpoint (no model spend when idle) and starts isolated runtime sessions only when something new arrives.
+
+Codex and OpenCode cycles run through Mastra's ACP harness. Codex uses the packaged `codex-acp` adapter and reuses the machine's existing ChatGPT/Codex login; OpenCode uses its native `opencode acp` server. Each accepted ticket gets its own ACP session and worktree. Mastra Memory stores ticket/thread context in local libSQL under `~/.openvisio/`, while a compact JSON ledger retains only exact replay, cancellation, and delivery keys.
+
+Model names are negotiated at session start. Codex and OpenCode match the configured name against the models advertised by ACP, preferring the same family and reasoning effort (`medium` for an unsuffixed family); provider-qualified and nearby generation names are resolved automatically. Claude versioned names are normalized to its stable `sonnet`, `opus`, `haiku`, or `fable` aliases and use the CLI's native ordered fallback chain.
 
 Backend/BYO watchers reconcile immediately whenever the process starts or the WebSocket connects. A direct MCP session discovers and caches the backend's actual `tools/list` response, then uses available tools such as `list_agents`, `list_projects`, `list_tasks`, `list_task_types`, and `list_activity` to recover assigned tasks and recent mention activity missed while offline. Optional actions such as ticket comments are used only when advertised; their absence cannot strand a completed ticket in a retry loop. The same zero-model check runs every five minutes as a safety net; a model starts only when pending work exists.
 
@@ -62,7 +66,7 @@ The backend MCP may be stateful or stateless. A successful initialize response w
 
 Codex BYO agents follow the repository's normative runtime specification in `docs/CODEX_BYO_AGENT_SPEC.md`: one WebSocket identity, independent Sol reply/work lanes, authoritative `get_ticket` verification for assignments, REST-backed in-app activity, persistent replay suppression, and runtime evidence gates before completion. Maintainers must run `npm run certify` before publishing.
 
-An `agent:mention` event only wakes the watcher; it does not grant ownership of the conversation. The actual source message is checked before any model starts. Messages redirected to another agent and unaddressed agent chatter stay silent, while a direct stand-down cancels queued/running work for that thread. Accepted coding work uses the activity indicator instead of a generic pickup message. Claude and OpenCode may add one concrete progress update after work begins, but must continue and post a distinct verified result or blocker afterward; Codex keeps cancellation-safe delivery watcher-owned and renders the verified final answer once.
+An `agent:mention` event only wakes the watcher; it does not grant ownership of the conversation. The actual source message is checked before any model starts. Messages redirected to another agent and unaddressed agent chatter stay silent, while a direct stand-down cancels queued/running work for that thread. The watcher does not broadcast working, thinking, or typing presence updates. Claude and OpenCode may add one concrete progress update after work begins, but must continue and post a distinct verified result or blocker afterward; Codex keeps cancellation-safe delivery watcher-owned and renders the verified final answer once.
 
 Ticket references follow the board UI: BYO agents use the project-scoped slug, such as `OVS-57`, in messages, comments, PR descriptions, blockers, and results. Numeric `project_id` and `ticket_id` values remain internal MCP arguments and are never used as human-facing ticket names. If an older backend omits the slug, the agent uses the ticket title rather than inventing one.
 
@@ -75,7 +79,7 @@ openvisio-agent watch --name ada --workdir ~/repo  # allow REAL work on a git br
 openvisio-agent stop --name ada                  # stop service + every ada watcher
 ```
 
-The work lane uses the configured workspace and an `agent/*` branch. It reuses local clones and is instructed to preserve dirty/staged work, create unique branches, use separate worktrees for shared checkouts, and stage only task-owned changes. The independent reply lane receives a chat charter and no coding workspace. Codex publishes local branches through the constrained helper, then opens a PR with `gh pr create`; linked-codebase MCP operations are a fallback when the repository cannot be obtained locally.
+The watcher can run up to three assigned coding tasks concurrently. Each ticket gets an isolated model runtime and ticket-specific worktree; tasks sharing the same mutable workspace remain serialized to prevent branch and file conflicts. Chat replies stay serialized, and cancellation targets only the matching ticket or source thread. The work pool reuses local clones and is instructed to preserve dirty/staged work, create unique branches, and stage only task-owned changes. The independent reply lane receives a chat charter and no coding workspace. Codex publishes local branches through the constrained helper, then opens a PR with `gh pr create`; linked-codebase MCP operations are a fallback when the repository cannot be obtained locally.
 
 Publishing a local branch uses an explicit, one-time authorization per repository:
 
@@ -86,7 +90,7 @@ openvisio-agent authorize-pr-push
 
 That command installs a narrow Codex rule for `openvisio-agent push-pr-branch` and records the repository's exact root and `origin`. The helper accepts no arguments and can only push `HEAD` to the same `agent/*` branch on that authorized origin. It disables repository hooks and rejects main/master, other branch namespaces, changed remotes, force pushes, local/file remotes, and credential-bearing URLs. Revoke it from the repository with `openvisio-agent revoke-pr-push`.
 
-Assignments use independent FIFO entries with stable-key duplicate suppression. Backlog recovery uses the same ticket verification path as WebSocket events, and each queued ticket is checked again before a model starts. MCP calls have a 20-second deadline including response bodies; tool discovery is cached and paginated. Activity requests are limited to one in flight per channel. Cancellation waits for process closure, with POSIX process-group termination for tool children. Credentials, replay state, and memory use atomic file replacement.
+Assignments use independent FIFO entries with stable-key duplicate suppression and bounded, worktree-aware concurrency. Backlog recovery uses the same ticket verification path as WebSocket events, and each queued ticket is checked again before a model starts. MCP calls have a 20-second deadline including response bodies; tool discovery is cached and paginated. Codex MCP failures retain a bounded, credential-redacted reason in the watcher log. Cancellation targets only its ACP session. Credentials and replay state use atomic file replacement; Mastra persists contextual memory in libSQL.
 
 See `docs/BYO_SYSTEM_AUDIT.md` in the repository for the audit results and remaining live-validation limits. Local certification does not certify a deployed agent's behavior.
 
@@ -103,7 +107,7 @@ Do not chase auto-changing watcher PIDs. `openvisio-agent stop --name <agent>` u
 
 ## Requirements
 
-- Node.js ≥ 18
+- Node.js ≥ 22.13
 - Claude Code, Codex (`@openai/codex`), or OpenCode (the selected CLI is auto-installed if missing)
 
 ## Getting a setup code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.18.15",
+  "version": "0.19.1",
   "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team — MCP tools + optional autonomy — in one command.",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.13"
   },
   "keywords": [
     "openvisio",
@@ -34,5 +34,11 @@
     "url": "git+https://github.com/syntaxPriest/OpenVisio.git",
     "directory": "packages/openvisio-agent"
   },
-  "dependencies": {}
+  "dependencies": {
+    "@agentclientprotocol/codex-acp": "1.10.0",
+    "@mastra/acp": "0.4.1",
+    "@mastra/core": "1.64.0",
+    "@mastra/libsql": "1.22.3",
+    "@mastra/memory": "1.28.2"
+  }
 }

package/scripts/certify.mjs

@@ -31,6 +31,8 @@ const prPush = readFileSync(join(root, 'src', 'pr-push.mjs'), 'utf8')
 const cli = readFileSync(join(root, 'bin', 'cli.mjs'), 'utf8')
 const websocket = readFileSync(join(root, 'src', 'ws.mjs'), 'utf8')
 const cycleQueue = readFileSync(join(root, 'src', 'cycle-queue.mjs'), 'utf8')
+const mastraHarness = readFileSync(join(root, 'src', 'mastra-harness.mjs'), 'utf8')
+const modelSelection = readFileSync(join(root, 'src', 'model-selection.mjs'), 'utf8')
 const activityHook = readFileSync(join(repo, 'frontend', 'hooks', 'useAgentActivity.ts'), 'utf8')
 const taskHook = readFileSync(join(repo, 'frontend', 'hooks', 'useBackendTasks.ts'), 'utf8')
 const liveTasks = readFileSync(join(repo, 'frontend', 'lib', 'collab', 'liveTasks.ts'), 'utf8')
@@ -56,7 +58,7 @@ const assertions = [
   ['reconciled mentions reuse the guarded websocket delivery path', watcher.includes("onEvent('agent:mention'") && watcher.includes('_mentionAlreadyMarked: true')],
   ['conversation wake events are recipient-filtered before model start', watcher.includes('classifyConversationTarget(msg, [...selfAliases])') && events.includes("reason: 'explicit-other-recipient'") && events.includes("reason: 'other-agent-chatter'")],
   ['coding mentions require an action and concrete repository target', watcher.includes('conversationNeedsCode(text)') && events.includes('const action =') && events.includes('const target =')],
-  ['stand-down and redirects cancel source-thread work across runtimes', watcher.includes('cancelThread(cid, threadRoot') && watcher.includes('activeDelivery') && watcher.includes('cancelCurrent') && watcher.includes("subtype === 'canceled'")],
+  ['stand-down and redirects cancel only source-thread workers', watcher.includes('cancelThread(cid, threadRoot') && watcher.includes('item.control.cancelled = true') && watcher.includes('item.control.runner?.cancelCurrent') && watcher.includes("subtype === 'canceled'")],
   ['thread cancellation is rechecked immediately before watcher delivery', watcher.includes('const newlyCancelled = suppressCancelled()') && watcher.includes('if (newlyCancelled) return newlyCancelled')],
   ['generic coding pickup messages are absent', !watcher.includes("I've picked this up and will return here with the verified result")],
   ['human-facing ticket references require slugs, never database ids', watcher.includes('TICKET SLUGS, NEVER DATABASE IDS') && watcher.includes('ticketDisplaySlug(task)') && events.includes('export function ticketDisplaySlug') && !events.includes('I finished ticket #${task.id}')],
@@ -66,17 +68,19 @@ const assertions = [
   ['Codex discovers deferred OpenVisio actions before claiming they are missing', watcher.includes('Codex may defer MCP actions') && watcher.includes('use tool_search to find that exact action') && watcher.includes('initial-list miss is NOT evidence that the server is disconnected')],
   ['Codex authentication is injected outside the model', codexConfig.includes('OPENVISIO_CODEX_API_KEY') && codexProxy.includes('toolWithoutCredentialInputs') && codexProxy.includes('client.callTool') && watcher.includes('local OpenVisio MCP bridge injects authentication outside the model')],
   ['reply delivery keys survive reconnects', watcher.includes('deliveredReplies: [...deliveredReplies]') && watcher.includes('deliveredReplies.has(deliveryKey)')],
-  ['tickets and guarded replies use the behavior-tested serial queue', watcher.includes('createCycleQueue({') && watcher.includes('queues[laneName].enqueue') && cycleQueue.includes('const pending = new Map()')],
+  ['tickets and guarded replies use the behavior-tested bounded queue', watcher.includes('createCycleQueue({') && watcher.includes('queues[laneName].enqueue') && cycleQueue.includes('const pending = new Map()') && cycleQueue.includes('activeGroups')],
   ['queued assignments are checked again before model execution', watcher.includes('queued ticket no longer actionable; skipped before model start')],
   ['feature titles cannot be mistaken for coordination commands', watcher.includes('taskIsCoordinationOnly(taskText)') && events.includes('Uploading files as messages') && events.includes('explicitCoordination')],
-  ['reply runner has no coding workspace or coding charter', watcher.includes("workdir: '', systemPrompt: CHAT_CHARTER") && opencodeConfig.includes("'*': 'deny'")],
+  ['reply runner has no coding workspace or coding charter', watcher.includes("workdir: ''") && watcher.includes("systemPrompt: CHAT_CHARTER + '\\n\\n' + credNote") && opencodeConfig.includes("'*': 'deny'")],
   ['MCP requests have a deadline including response bodies', mcpHttp.includes('controller.abort()') && mcpHttp.includes('const body = await res.text()')],
-  ['BYO memory uses real ticket and thread identities', watcher.includes('createByoMemoryGraph') && watcher.includes('memory.context(memoryRefs)') && memory.includes('sameRef(r.projectId, refs.projectId)') && memory.includes('sameRef(r.threadId, refs.threadId)')],
-  ['two internal lanes exist', watcher.includes('work: createCycleRunner') && watcher.includes('reply: createCycleRunner')],
-  ['work and reply activity targets are isolated', watcher.includes("laneStatusTargets = { work: new Set(), reply: new Set() }") && watcher.includes("emitLaneStatus('work', 'typing')") && watcher.includes("emitLaneStatus('reply', 'typing')")],
+  ['Mastra memory uses real ticket and thread identities', watcher.includes('createMastraMemory') && watcher.includes('await memory.context(memoryRefs)') && memory.includes('new Memory({ storage') && memory.includes('new LibSQLStore') && memory.includes('ticket:${refs.projectId}:${refs.ticketId}') && memory.includes('channel:${refs.channelId}:thread:')],
+  ['Codex and OpenCode use isolated Mastra ACP sessions', watcher.includes('createMastraAcpRunner') && mastraHarness.includes('new AcpAgentClass') && mastraHarness.includes('persistSession: false') && mastraHarness.includes("runtime: 'mastra-acp'")],
+  ['runtime models are resolved before work starts', mastraHarness.includes('getAvailableModels()') && mastraHarness.includes('resolveAvailableModel(requestedModel') && mastraHarness.includes('await acp.setModel(selectedModel)') && modelSelection.includes("const DEFAULT_EFFORT = 'medium'") && watcher.includes('resolveClaudeModel') && watcher.includes("'--fallback-model'" )],
+  ['one watcher owns isolated concurrent work and serial reply runtimes', watcher.includes('MAX_CONCURRENT_WORKERS = 3') && watcher.includes('createWorkRunner(item.control, item.workdir)') && watcher.includes('const replyRunner = createCycleRunner')],
+  ['workers serialize shared worktrees while independent worktrees run concurrently', watcher.includes('groupKey: (item) => item.workdir || workdir') && cycleQueue.includes('active.size < concurrency') && cycleQueue.includes('activeGroups.has(entry.group)')],
+  ['work and reply cancellation targets are isolated', watcher.includes('item.control.cancelled = true') && watcher.includes('item.control.runner?.cancelCurrent')],
   ['assigned task activity resolves a project channel', watcher.includes("callMcpTool('list_channels'") && watcher.includes('projectStatusChannel(projectId)')],
-  ['working heartbeat is battery-conscious', watcher.includes("emitLaneStatus(laneName, 'working'), 20_000")],
-  ['activity uses REST endpoint', watcher.includes('agentStateRequest(')],
+  ['presence notification requests are disabled', watcher.includes('const sendStatus = () => {}') && !watcher.includes('agentStateRequest(') && !watcher.includes("setInterval(() => emitStatusTargets")],
   ['websocket client cannot emit legacy agent_status', !websocket.includes('agent_status')],
   ['frontend consumes thinking event', activityHook.includes("'channel:agent:thinking'")],
   ['frontend consumes working event', activityHook.includes("'channel:agent:working'")],
@@ -101,6 +105,7 @@ const assertions = [
   ['OpenCode tool failures retain sanitized diagnostics', events.includes('toolError: toolError.replace') && watcher.includes("opencode tool '") && watcher.includes("split(redactKey).join('[redacted]')")],
   ['all runtime acknowledgements cannot satisfy coding completion', watcher.includes('missingRuntimeWorkEvidence(result') && watcher.includes('claudeEventEvidence(o, turnToolUses)') && watcher.includes('releaseTaskForRetry(activeTaskRef, prompt)')],
   ['Codex prose cannot masquerade as repository evidence', watcher.includes('codexEventEvidence(event)') && events.includes("item.type === 'agent_message'") && events.includes("event.type === 'item.completed'")],
+  ['Codex MCP failures retain sanitized per-call diagnostics', events.includes('rawToolError = item.error') && watcher.includes('mcpErrorDetails.set(evidence.mcpTool, safe)') && watcher.includes("join('[redacted]')")],
   ['coding recovery retains source context and requires a final result', watcher.includes('ORIGINAL REQUEST AND ROUTING CONTEXT') && events.includes('resultMessageRequired && !result?.didResultMessage') && events.includes("outputText: second?.outputText || first?.outputText || ''")],
   ['backend MCP accepts stateless initialize responses', mcpHttp.includes("mode = () => !initialized ? 'uninitialized' : sessionId ? 'stateful' : 'stateless'") && !watcher.includes('MCP initialize returned no session id')],
   ['MCP initialize is shared across concurrent startup probes', mcpHttp.includes('if (initializePromise) return initializePromise')],

package/src/codex-mcp-proxy.mjs

@@ -21,6 +21,9 @@ export function runCodexMcpProxy() {
   const url = process.env.OPENVISIO_CODEX_MCP_URL
   const apiKey = process.env.OPENVISIO_CODEX_API_KEY
   const identifier = process.env.OPENVISIO_CODEX_IDENTIFIER
+  let disabledTools = []
+  try { disabledTools = JSON.parse(process.env.OPENVISIO_CODEX_DISABLED_TOOLS || '[]') } catch { /* no disabled tools */ }
+  const disabled = new Set(Array.isArray(disabledTools) ? disabledTools.map(String) : [])
   if (!url || !apiKey || !identifier) throw new Error('OpenVisio Codex MCP bridge is missing its watcher environment.')
   const client = createMcpHttpClient({ url, apiKey, identifier, clientVersion: 'openvisio-agent-codex-proxy' })
   const reply = (id, result) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n')
@@ -52,8 +55,9 @@ export function runCodexMcpProxy() {
         reply(id, {})
       } else if (request.method === 'tools/list') {
         const tools = await client.listTools()
-        reply(id, { tools: tools.map(toolWithoutCredentialInputs) })
+        reply(id, { tools: tools.filter((tool) => !disabled.has(String(tool.name))).map(toolWithoutCredentialInputs) })
       } else if (request.method === 'tools/call') {
+        if (disabled.has(String(request.params?.name || ''))) throw new Error('This tool is disabled for the current delivery lane.')
         reply(id, await client.callTool(request.params?.name, request.params?.arguments || {}))
       } else if (id != null) {
         process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found' } }) + '\n')

package/src/cycle-queue.mjs

@@ -1,33 +1,45 @@
 // One immutable source per cycle. A Map provides FIFO ordering and constant-time
 // replay checks without merging ticket identities or starving older assignments.
-export function createCycleQueue({ run, onError = () => {} }) {
+// Bounded concurrency is opt-in. `groupKey` keeps items sharing a repository or
+// another mutable resource serialized while independent work can run in parallel.
+export function createCycleQueue({ run, onError = () => {}, concurrency = 1, groupKey = () => '' }) {
+  if (!Number.isInteger(concurrency) || concurrency < 1) throw new Error('cycle queue concurrency must be a positive integer')
   const pending = new Map()
-  let active = null
+  const active = new Map()
+  const activeGroups = new Set()
   let sequence = 0
 
-  const pump = async () => {
-    if (active || !pending.size) return
-    const [key, entry] = pending.entries().next().value
-    pending.delete(key)
-    active = { key, ...entry }
-    try { entry.resolve(await run(entry.item)) }
-    catch (error) {
-      try { onError(error, entry.item) } catch { /* logging cannot strand the queue */ }
-      entry.resolve({ status: 'failed' })
-    } finally {
-      active = null
-      void pump()
+  const pump = () => {
+    while (active.size < concurrency && pending.size) {
+      const available = [...pending].find(([, entry]) => !entry.group || !activeGroups.has(entry.group))
+      if (!available) return
+      const [key, entry] = available
+      pending.delete(key)
+      active.set(key, entry)
+      if (entry.group) activeGroups.add(entry.group)
+      void (async () => {
+        try { entry.resolve(await run(entry.item)) }
+        catch (error) {
+          try { onError(error, entry.item) } catch { /* logging cannot strand the queue */ }
+          entry.resolve({ status: 'failed' })
+        } finally {
+          active.delete(key)
+          if (entry.group) activeGroups.delete(entry.group)
+          pump()
+        }
+      })()
     }
   }
 
   return {
     enqueue(item, key = `cycle:${++sequence}`) {
-      if (active?.key === key) return active.promise
+      if (active.has(key)) return active.get(key).promise
       if (pending.has(key)) return pending.get(key).promise
       let resolve
       const promise = new Promise((done) => { resolve = done })
-      pending.set(key, { item, promise, resolve })
-      void pump()
+      const group = String(groupKey(item) || '')
+      pending.set(key, { item, promise, resolve, group })
+      pump()
       return promise
     },
     cancel(predicate, cancelActive = () => {}) {
@@ -36,9 +48,10 @@ export function createCycleQueue({ run, onError = () => {} }) {
         pending.delete(key)
         entry.resolve({ status: 'canceled' })
       }
-      if (active && predicate(active.item)) cancelActive(active.item)
+      for (const entry of active.values()) if (predicate(entry.item)) cancelActive(entry.item)
     },
-    has(key) { return active?.key === key || pending.has(key) },
-    get size() { return pending.size + (active ? 1 : 0) },
+    has(key) { return active.has(key) || pending.has(key) },
+    get size() { return pending.size + active.size },
+    get activeSize() { return active.size },
   }
 }

package/src/events.mjs

@@ -189,10 +189,14 @@ export function codexEventEvidence(event) {
   const prefixed = /^(?:mcp__)?openvisio(?:-team|_team)(?:__|[_.:/-])(.+)$/i.exec(rawTool)
   const mcpTool = String(prefixed?.[1] ?? rawTool).replace(/[-.]/g, '_')
   const succeeded = completed && !failed
+  const resultText = item.result?.content?.find?.((part) => part?.type === 'text')?.text
+  const rawToolError = item.error ?? item.result?.error ?? resultText
+  const toolError = rawToolError == null ? '' : (typeof rawToolError === 'string' ? rawToolError : JSON.stringify(rawToolError))
   return {
     mcpTool,
     failed,
     completed: succeeded,
+    ...(failed && toolError ? { toolError: toolError.replace(/\s+/g, ' ').slice(0, 500) } : {}),
     didCode: succeeded && /^(?:create_codebase_branch|create_codebase_commit|write_codebase_file|create_pull_request)$/.test(mcpTool),
     didRepoMutation: succeeded && /^(?:create_codebase_branch|create_codebase_commit|write_codebase_file|create_pull_request)$/.test(mcpTool),
     didMcpTaskRead: succeeded && /^(?:get_ticket|list_tasks)$/.test(mcpTool),

package/src/mastra-harness.mjs

@@ -0,0 +1,199 @@
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { AcpAgent } from '@mastra/acp'
+import { onPath } from './lib.mjs'
+import { resolveAvailableModel } from './model-selection.mjs'
+
+const MCP_TOOL_NAMES = [
+  'list_agents', 'list_projects', 'list_tasks', 'list_task_types', 'get_ticket',
+  'update_ticket', 'list_channels', 'list_message_thread', 'list_activity',
+  'post_message', 'react_message', 'list_codebases', 'get_codebase',
+  'codebase_tree', 'create_codebase_branch', 'create_codebase_commit',
+  'create_pull_request',
+]
+
+const clean = (value, max = 300) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max)
+const json = (value) => { try { return JSON.stringify(value) } catch { return String(value ?? '') } }
+
+function commandFor(agent) {
+  if (agent === 'opencode') return { command: onPath('opencode') || 'opencode', args: ['acp'] }
+  if (agent === 'codex') {
+    const filename = process.platform === 'win32' ? 'codex-acp.cmd' : 'codex-acp'
+    return { command: fileURLToPath(new URL(`../node_modules/.bin/${filename}`, import.meta.url)), args: [] }
+  }
+  return null
+}
+
+const proxyPath = fileURLToPath(new URL('./codex-mcp-proxy.mjs', import.meta.url))
+
+function repositorySnapshot(cwd) {
+  if (!cwd) return ''
+  const result = spawnSync('git', ['status', '--porcelain=v1', '--untracked-files=all'], {
+    cwd, encoding: 'utf8', timeout: 10_000,
+  })
+  return result.status === 0 ? String(result.stdout || '') : ''
+}
+
+function toolName(update) {
+  const haystack = `${update?.title || ''} ${json(update?.rawInput)}`
+  return MCP_TOOL_NAMES.find((name) => new RegExp(`(?:^|[^a-z0-9_])${name}(?:$|[^a-z0-9_])`, 'i').test(haystack)) || ''
+}
+
+function contentText(content) {
+  if (!content || typeof content !== 'object') return ''
+  if (content.type === 'text') return String(content.text || '')
+  if (content.type === 'content') return contentText(content.content)
+  return ''
+}
+
+export function createMastraAcpRunner({
+  agent, mcpUrl, mcpHeaders = {}, workdir, canCode = !!workdir, maxCycleMs,
+  log = () => {}, debug = false, model, onTool, systemPrompt = '', AcpAgentClass = AcpAgent,
+}) {
+  const runtime = commandFor(agent)
+  if (!runtime) return null
+  let active = null
+  const defaultCwd = workdir || process.cwd()
+
+  async function runCycle(prompt, cycleModel, cycleOptions = {}) {
+    const cycleCwd = cycleOptions.workdir || defaultCwd
+    const controller = new AbortController()
+    let timedOut = false
+    const before = repositorySnapshot(canCode ? cycleCwd : '')
+    const calls = new Set()
+    const errors = new Map()
+    const tools = new Map()
+    let outputText = ''
+    let didCode = false
+    let didRepoMutation = false
+    let didMessage = false
+    let didChannelMessage = false
+    let didResultMessage = false
+    let didMcpTaskRead = false
+    let didMcpTaskUpdate = false
+
+    const headers = Object.entries(mcpHeaders).filter(([, value]) => value != null && value !== '').map(([name, value]) => ({ name, value: String(value) }))
+    const disabledMcpTools = Array.isArray(cycleOptions.disabledMcpTools) ? cycleOptions.disabledMcpTools.filter(Boolean) : []
+    const mcpServers = !mcpUrl ? [] : agent === 'codex' ? [{
+      name: 'openvisio-team', command: process.execPath, args: [proxyPath], env: [
+        { name: 'OPENVISIO_CODEX_MCP_URL', value: mcpUrl },
+        { name: 'OPENVISIO_CODEX_API_KEY', value: String(mcpHeaders['x-agent-api-key'] || '') },
+        { name: 'OPENVISIO_CODEX_IDENTIFIER', value: String(mcpHeaders['x-agent-identifier'] || '') },
+        { name: 'OPENVISIO_CODEX_DISABLED_TOOLS', value: JSON.stringify(disabledMcpTools) },
+      ],
+    }] : [{ type: 'http', name: 'openvisio-team', url: mcpUrl, headers }]
+    const acp = new AcpAgentClass({
+      id: `openvisio-${agent}-${Date.now()}`,
+      name: `OpenVisio ${agent}`,
+      description: 'An isolated OpenVisio coding-agent run.',
+      command: runtime.command,
+      args: runtime.args,
+      cwd: cycleCwd,
+      env: agent === 'codex' ? {
+        INITIAL_AGENT_MODE: canCode ? 'agent' : 'read-only',
+        NO_BROWSER: '1',
+      } : {},
+      session: {
+        cwd: cycleCwd,
+        mcpServers,
+      },
+      persistSession: false,
+      onPermissionRequest: async ({ options }) => {
+        const kind = canCode ? 'allow_once' : 'reject_once'
+        const selected = options.find((option) => option.kind === kind) || options.find((option) => option.kind.startsWith(canCode ? 'allow' : 'reject'))
+        return selected ? { outcome: { outcome: 'selected', optionId: selected.optionId } } : { outcome: { outcome: 'cancelled' } }
+      },
+      // codex-acp publishes account-status extension notifications. They are
+      // useful to interactive clients but should be silent in a background
+      // watcher, and the stock Mastra ACP client intentionally knows only ACP.
+      createClient: agent === 'codex' ? (client) => new Proxy(client, {
+        get(target, property, receiver) {
+          if (property === 'extNotification') return async () => {}
+          return Reflect.get(target, property, receiver)
+        },
+      }) : undefined,
+    })
+    active = { acp, controller }
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); acp.connection.disconnect() }, maxCycleMs)
+    const requestedModel = cycleModel || model || ''
+    let selectedModel = ''
+    try {
+      if (requestedModel) {
+        const availableModels = await acp.getAvailableModels()
+        const resolution = resolveAvailableModel(requestedModel, availableModels)
+        selectedModel = resolution.selected
+        if (selectedModel) {
+          await acp.setModel(selectedModel)
+          if (selectedModel !== requestedModel) log(`model ${requestedModel} resolved to available ${selectedModel} [${resolution.reason}]`)
+        } else {
+          log(`model ${requestedModel} could not be negotiated because ${agent} did not advertise selectable models; using its session default`)
+        }
+      }
+      log(`running ${agent} cycle via Mastra ACP…${selectedModel || requestedModel ? ` [${selectedModel || requestedModel}]` : ' [runtime default]'}`)
+      const fullPrompt = systemPrompt ? `${systemPrompt}\n\n${prompt}` : prompt
+      for await (const event of acp.connection.promptStream(fullPrompt, controller.signal)) {
+        if (event.type === 'text') { outputText += event.text; continue }
+        const update = event.update || {}
+        if (update.sessionUpdate === 'agent_message_chunk') {
+          outputText += contentText(update.content)
+          continue
+        }
+        if (!['tool_call', 'tool_call_update'].includes(update.sessionUpdate)) continue
+        const prior = tools.get(update.toolCallId) || {}
+        const merged = { ...prior, ...update }
+        tools.set(update.toolCallId, merged)
+        const name = toolName(merged)
+        const label = name || clean(merged.title, 100) || 'tool'
+        try { onTool?.(label) } catch { /* status is best-effort */ }
+        if (debug && update.sessionUpdate === 'tool_call') log(`  → tool ${label}`)
+        if (name) {
+          calls.add(name)
+          if (merged.status === 'failed') errors.set(name, clean(json(merged.rawOutput) || merged.title))
+          else if (merged.status === 'completed') errors.delete(name)
+          didMessage ||= name === 'post_message'
+          didChannelMessage ||= name === 'post_message'
+          didMcpTaskRead ||= ['list_tasks', 'list_task_types', 'get_ticket'].includes(name)
+          didMcpTaskUpdate ||= name === 'update_ticket'
+        }
+        const title = clean(merged.title, 200).toLowerCase()
+        const looksLikeMutation = merged.kind === 'edit' || /\b(edit|write|patch|create|delete|commit)\b/.test(title)
+        didCode ||= ['edit', 'execute'].includes(merged.kind) || looksLikeMutation
+        didRepoMutation ||= looksLikeMutation
+      }
+      const after = repositorySnapshot(canCode ? cycleCwd : '')
+      if (before !== after) { didCode = true; didRepoMutation = true }
+      didResultMessage = didChannelMessage && didRepoMutation
+      log(`${agent} cycle done via Mastra ACP (ok)`)
+      return {
+        type: 'result', subtype: 'ok', runtime: 'mastra-acp', model: selectedModel || null, requestedModel: requestedModel || null, outputText: outputText.trim(),
+        mcpCalls: [...calls], mcpErrors: [...errors.keys()], mcpErrorDetails: Object.fromEntries(errors),
+        didCode, didRepoMutation, didMessage, didChannelMessage, didResultMessage,
+        didMcpTaskRead, didMcpTaskUpdate,
+      }
+    } catch (error) {
+      const canceled = controller.signal.aborted
+      const subtype = timedOut ? 'timeout' : canceled ? 'canceled' : 'error'
+      log(`${agent} cycle done via Mastra ACP (${subtype}${!canceled && error?.message ? ': ' + clean(error.message) : ''})`)
+      return {
+        type: 'result', subtype, runtime: 'mastra-acp', model: selectedModel || null, requestedModel: requestedModel || null, outputText: outputText.trim(),
+        mcpCalls: [...calls], mcpErrors: [...errors.keys()], mcpErrorDetails: Object.fromEntries(errors),
+        didCode, didRepoMutation, didMessage, didChannelMessage, didResultMessage,
+        didMcpTaskRead, didMcpTaskUpdate,
+      }
+    } finally {
+      clearTimeout(timer)
+      acp.connection.disconnect()
+      if (active?.acp === acp) active = null
+    }
+  }
+
+  const cancelCurrent = async () => {
+    if (!active) return
+    active.controller.abort()
+    try { await active.acp.connection.cancel() } catch { /* already stopped */ }
+    active.acp.connection.disconnect()
+  }
+
+  log(`${agent} Mastra ACP runner ready${canCode ? ` [CODE workspace ${defaultCwd}]` : ' [CHAT-ONLY]'}`)
+  return { runCycle, canCode, cancelCurrent, harness: 'mastra-acp' }
+}

package/src/memory.mjs

@@ -1,4 +1,7 @@
 import { readFileSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
 import { writeJson } from './lib.mjs'
 
 const clean = (value, max = 320) => String(value || '').replace(/\s+/g, ' ').trim().slice(0, max)
@@ -79,3 +82,70 @@ export function createByoMemoryGraph({ path, maxNodes = 1000, now = () => Date.n
 
   return { remember, connect, recall, context, has, persist }
 }
+
+const memoryThreadId = (refs = {}) => {
+  if (refs.projectId != null && refs.ticketId != null) return `ticket:${refs.projectId}:${refs.ticketId}`
+  if (refs.channelId != null) return `channel:${refs.channelId}:thread:${refs.threadId ?? 'root'}`
+  return ''
+}
+
+const messageText = (message) => {
+  const parts = message?.content?.parts
+  if (!Array.isArray(parts)) return clean(message?.content?.content, 2000)
+  return clean(parts.filter((part) => part?.type === 'text').map((part) => part.text).join(' '), 2000)
+}
+
+// Mastra owns durable task/thread context. The JSON graph remains a deliberately
+// small coordination ledger for exact replay and delivery keys; it is not used as
+// the primary transcript once the libSQL thread has messages.
+export function createMastraMemory({ ledgerPath, databasePath, resourceId, maxNodes = 1000, now = () => Date.now() }) {
+  const ledger = createByoMemoryGraph({ path: ledgerPath, maxNodes, now })
+  const storage = new LibSQLStore({ id: `openvisio-memory-${resourceId}`, url: `file:${databasePath}` })
+  const memory = new Memory({ storage, options: { lastMessages: 12, semanticRecall: false, workingMemory: { enabled: false } } })
+  const threads = new Map()
+  let pending = Promise.resolve()
+
+  const ensureThread = (threadId) => {
+    if (!threads.has(threadId)) {
+      threads.set(threadId, (async () => {
+        const existing = await memory.getThreadById({ threadId, resourceId })
+        return existing || memory.createThread({ threadId, resourceId, title: threadId })
+      })())
+    }
+    return threads.get(threadId)
+  }
+
+  const queueMessage = (entry) => {
+    const threadId = memoryThreadId(entry?.refs)
+    if (!threadId) return
+    pending = pending.then(async () => {
+      await ensureThread(threadId)
+      const text = `${entry.kind || 'event'} ${entry.state || 'observed'}: ${entry.summary || entry.key}`
+      await memory.saveMessages({ messages: [{
+        id: randomUUID(), role: 'assistant', createdAt: new Date(now()), threadId, resourceId,
+        content: { format: 2, parts: [{ type: 'text', text }], metadata: { openvisioKey: entry.key } },
+      }] })
+    }).catch(() => { /* memory is best-effort; live backend checks stay authoritative */ })
+  }
+
+  const remember = (entry) => {
+    const node = ledger.remember(entry)
+    if (node) queueMessage(node)
+    return node
+  }
+
+  const context = async (refs = {}, limit = 8) => {
+    const threadId = memoryThreadId(refs)
+    if (!threadId) return ''
+    await pending
+    try {
+      const recalled = await memory.recall({ threadId, resourceId, perPage: limit })
+      const items = recalled.messages.map(messageText).filter(Boolean).slice(-limit)
+      if (items.length) return ['RELEVANT VERIFIED MEMORY (do not repeat completed/delivered actions):', ...items.map((item) => `- ${item}`)].join('\n')
+    } catch { /* fall through to the migration-safe ledger */ }
+    return ledger.context(refs, limit)
+  }
+
+  const settled = async () => { await pending; await memory.settled() }
+  return { remember, connect: ledger.connect, recall: ledger.recall, context, has: ledger.has, persist: ledger.persist, settled, provider: 'mastra-libsql' }
+}

package/src/model-selection.mjs

@@ -0,0 +1,75 @@
+const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'ultra']
+const DEFAULT_EFFORT = 'medium'
+
+const text = (value) => String(value ?? '').trim()
+const lower = (value) => text(value).toLowerCase()
+
+function parts(value) {
+  const raw = text(value)
+  const effortMatch = /\[([^\]]+)\]$/.exec(raw)
+  const withoutEffort = effortMatch ? raw.slice(0, effortMatch.index) : raw
+  const path = lower(withoutEffort).split('/').filter(Boolean)
+  const leaf = path.at(-1) || ''
+  const tokens = leaf.split(/[^a-z0-9]+/).filter(Boolean)
+  return { raw, id: lower(raw), base: lower(withoutEffort), leaf, tokens, provider: path.slice(0, -1).join('/'), effort: lower(effortMatch?.[1]) }
+}
+
+const effortDistance = (actual, preferred) => {
+  const actualIndex = EFFORTS.indexOf(actual)
+  const preferredIndex = EFFORTS.indexOf(preferred)
+  if (actualIndex < 0) return 20
+  return Math.abs(actualIndex - (preferredIndex < 0 ? EFFORTS.indexOf(DEFAULT_EFFORT) : preferredIndex))
+}
+
+function similarity(requested, candidate, preferredEffort) {
+  if (candidate.id === requested.id) return 100_000
+  let score = 0
+  if (candidate.base === requested.base || candidate.leaf === requested.leaf) score += 50_000
+  if (requested.provider && candidate.provider === requested.provider) score += 2_000
+  const requestedTokens = new Set(requested.tokens)
+  const shared = candidate.tokens.filter((token) => requestedTokens.has(token)).length
+  score += shared * 1_000
+  if (requested.leaf && (candidate.leaf.includes(requested.leaf) || requested.leaf.includes(candidate.leaf))) score += 10_000
+  let prefix = 0
+  while (prefix < requested.leaf.length && prefix < candidate.leaf.length && requested.leaf[prefix] === candidate.leaf[prefix]) prefix++
+  score += prefix * 10
+  score -= effortDistance(candidate.effort, requested.effort || preferredEffort) * 100
+  return score
+}
+
+export function resolveAvailableModel(requestedValue, availableModels = [], { preferredEffort = DEFAULT_EFFORT } = {}) {
+  const requested = parts(requestedValue)
+  const choices = availableModels.map((entry) => typeof entry === 'string' ? entry : entry?.modelId).map(text).filter(Boolean)
+  if (!choices.length) return { requested: requested.raw, selected: '', reason: 'runtime-default', available: [] }
+  if (!requested.raw) return { requested: '', selected: '', reason: 'runtime-default', available: choices }
+
+  const ranked = choices.map((id, index) => {
+    const candidate = parts(id)
+    return { id, index, score: similarity(requested, candidate, preferredEffort) }
+  }).sort((a, b) => b.score - a.score || a.index - b.index)
+  const winner = ranked[0]
+  return {
+    requested: requested.raw,
+    selected: winner.id,
+    reason: lower(winner.id) === requested.id ? 'exact' : parts(winner.id).base === requested.base || parts(winner.id).leaf === requested.leaf ? 'family-effort' : 'nearest',
+    available: choices,
+  }
+}
+
+const CLAUDE_FAMILIES = ['sonnet', 'opus', 'haiku', 'fable']
+
+export function resolveClaudeModel(requestedValue) {
+  const requested = lower(requestedValue)
+  if (!requested) return ''
+  const family = CLAUDE_FAMILIES.find((name) => requested === name || requested.startsWith('claude-') && requested.includes(name))
+  return family || text(requestedValue)
+}
+
+export function claudeFallbackModels(selectedValue) {
+  const selected = lower(selectedValue)
+  const preferred = selected === 'opus' ? ['sonnet', 'haiku']
+    : selected === 'haiku' ? ['sonnet', 'opus']
+      : selected === 'fable' ? ['sonnet', 'opus'] : ['opus', 'haiku']
+  return preferred.filter((model) => model !== selected)
+}
+

package/src/watch.mjs

@@ -11,14 +11,16 @@ import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { OV_DIR, DEFAULT_WORKSPACE, readConfig, writeJson, configPath, onPath, fail, ok, info, slugify, stripSlash, chmodSafe } from './lib.mjs'
 import { connectAgentWs, assertWebSocket } from './ws.mjs'
-import { agentAddedByName, agentStateRequest, buildTaskCompletionReport, claudeEventEvidence, classifyConversationTarget, codexEventEvidence, codexPolicyBlock, combineRuntimeWorkEvidence, conversationNeedsCode, failedTaskRevisionIsCurrent, mentionDedupeKeys, missingRuntimeWorkEvidence, normalizeRenderedMessageText, opencodeEventEvidence, renderedAgentMessages, shouldSuppressCodexDiagnostic, taskAgentId, taskFromEvent, taskIsAwaitingReview, taskIsCompleted, taskIsCoordinationOnly, taskRevision, ticketDisplaySlug } from './events.mjs'
-import { createByoMemoryGraph } from './memory.mjs'
+import { agentAddedByName, buildTaskCompletionReport, claudeEventEvidence, classifyConversationTarget, codexEventEvidence, codexPolicyBlock, combineRuntimeWorkEvidence, conversationNeedsCode, failedTaskRevisionIsCurrent, mentionDedupeKeys, missingRuntimeWorkEvidence, normalizeRenderedMessageText, opencodeEventEvidence, renderedAgentMessages, shouldSuppressCodexDiagnostic, taskAgentId, taskFromEvent, taskIsAwaitingReview, taskIsCompleted, taskIsCoordinationOnly, taskRevision, ticketDisplaySlug } from './events.mjs'
+import { createMastraMemory } from './memory.mjs'
 import { repositoryHasPrPushAuthorization } from './pr-push.mjs'
 import { createMcpHttpClient } from './mcp-http.mjs'
 import { buildOpencodeConfig, opencodeRuntimeLayout } from './opencode-config.mjs'
 import { buildCodexMcpOverride } from './codex-config.mjs'
 import { createCycleQueue } from './cycle-queue.mjs'
 import { modelProcessOptions, stopModelProcess } from './process-lifecycle.mjs'
+import { createMastraAcpRunner } from './mastra-harness.mjs'
+import { claudeFallbackModels, resolveClaudeModel } from './model-selection.mjs'
 
 function findTicketWorktree(workspaceRoot, ticketId) {
   if (!workspaceRoot || ticketId == null) return ''
@@ -473,7 +475,7 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
       let terminationResult = null
       let cancel = null
       let policyBlock = null
-      const mcpCalls = new Set(), mcpErrors = new Set()
+      const mcpCalls = new Set(), mcpErrors = new Set(), mcpErrorDetails = new Map()
       let didMcpTaskRead = false, didMcpTaskUpdate = false
       const finish = (o) => {
         if (done) return
@@ -481,8 +483,9 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
         if (cancelActive === cancel) cancelActive = null
         clearTimeout(timer)
         const calls = [...mcpCalls]
-        log('codex MCP calls: ' + (calls.length ? calls.join(', ') : 'none') + (mcpErrors.size ? ' (failed: ' + [...mcpErrors].join(', ') + ')' : ''))
-        resolve({ ...o, didCode, didRepoMutation, didMessage, didChannelMessage, didResultMessage, didMcpTaskRead, didMcpTaskUpdate, mcpCalls: calls, mcpErrors: [...mcpErrors], outputText, policyBlock })
+        const failedSummary = [...mcpErrors].map((name) => `${name}${mcpErrorDetails.get(name) ? ': ' + mcpErrorDetails.get(name) : ''}`).join('; ')
+        log('codex MCP calls: ' + (calls.length ? calls.join(', ') : 'none') + (failedSummary ? ' (failed: ' + failedSummary + ')' : ''))
+        resolve({ ...o, didCode, didRepoMutation, didMessage, didChannelMessage, didResultMessage, didMcpTaskRead, didMcpTaskUpdate, mcpCalls: calls, mcpErrors: [...mcpErrors], mcpErrorDetails: Object.fromEntries(mcpErrorDetails), outputText, policyBlock })
       }
       const terminate = (subtype) => {
         terminationResult ||= { type: 'result', subtype }
@@ -518,8 +521,18 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
           if (evidence.mcpTool) {
             mcpCalls.add(evidence.mcpTool)
             try { onTool && onTool(evidence.mcpTool) } catch { /* activity is best-effort */ }
-            if (evidence.failed) mcpErrors.add(evidence.mcpTool)
-            else if (evidence.completed) mcpErrors.delete(evidence.mcpTool)
+            if (evidence.failed) {
+              mcpErrors.add(evidence.mcpTool)
+              if (evidence.toolError) {
+                const secret = String(mcpHeaders?.['x-agent-api-key'] || '')
+                const detail = String(evidence.toolError)
+                const safe = (secret ? detail.split(secret).join('[redacted]') : detail).slice(0, 300)
+                mcpErrorDetails.set(evidence.mcpTool, safe)
+              }
+            } else if (evidence.completed) {
+              mcpErrors.delete(evidence.mcpTool)
+              mcpErrorDetails.delete(evidence.mcpTool)
+            }
           }
           if (evidence.didChannelMessage && didRepoMutation) didResultMessage = true
           didCode ||= !!evidence.didCode
@@ -588,6 +601,11 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
 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
+  // Codex and OpenCode run through Mastra's ACP harness. Each queue worker gets
+  // its own ACP session and worktree, so cancellation, permissions and context
+  // cannot bleed across concurrently assigned tickets.
+  const mastraRunner = createMastraAcpRunner({ agent, mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, log, debug, model, onTool, systemPrompt })
+  if (mastraRunner) return mastraRunner
   // 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, onTool, systemPrompt })
@@ -596,7 +614,7 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
   // 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 sessionModel = resolveClaudeModel(model) || null
   let turnsThisSession = 0
   let sessionStartedAt = 0
   let resolveTurn = null
@@ -653,7 +671,8 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
     if (!mcpConfig) { log('WARNING: no MCP config — the agent can react to events but has no tools to act. Re-connect with --mcp-url.') }
     // 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 fallbackModels = claudeFallbackModels(sessionModel)
+    const base = ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--strict-mcp-config', '--mcp-config', mcpConfig, ...(sessionModel ? ['--model', sessionModel, ...(fallbackModels.length ? ['--fallback-model', fallbackModels.join(',')] : [])] : []), ...(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, { ...modelProcessOptions, cwd: workdir || undefined, stdio: ['pipe', 'pipe', 'inherit'] })
     child = c
@@ -714,9 +733,11 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
     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
+      const resolvedCycleModel = resolveClaudeModel(cycleModel)
+      if (resolvedCycleModel && resolvedCycleModel !== sessionModel) {
+        if (child) { log('model change ' + (sessionModel || 'default') + ' → ' + resolvedCycleModel + ' — recycling session'); try { child.kill() } catch { /* gone */ } child = null }
+        if (resolvedCycleModel !== cycleModel) log('model ' + cycleModel + ' resolved to Claude family alias ' + resolvedCycleModel)
+        sessionModel = resolvedCycleModel
       }
       if (child && (turnsThisSession >= MAX_TURNS || Date.now() - sessionStartedAt > SESSION_IDLE_MS)) {
         log('recycling session (turns=' + turnsThisSession + ')')
@@ -768,29 +789,13 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
 function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug }) {
   const log = (m) => process.stdout.write('[ws ' + new Date().toISOString() + '] ' + m + '\n')
   let handle = null
-  const statusBackoff = new Map()
-  const statusInFlight = new Set()
-  // Activity belongs to a lane. Keeping work/reply targets separate prevents a
-  // quick reply from overwriting or clearing a long coding cycle's status.
-  const laneStatusTargets = { work: new Set(), reply: new Set() }
-  const sendStatus = (channelId, state) => {
-    if (!backend || !['thinking', 'working', 'typing'].includes(state)) return
-    const key = Number(channelId)
-    if (statusInFlight.has(key) || (statusBackoff.get(key) || 0) > Date.now()) return
-    let request
-    try { request = agentStateRequest(backend, key, state, apiKey, identifier) } catch { return }
-    statusInFlight.add(key)
-    void fetch(request.url, { ...request.init, signal: AbortSignal.timeout(10_000) }).then(async (res) => {
-      if (res.ok) { statusBackoff.delete(key); return }
-      const body = (await res.text().catch(() => '')).replace(/\s+/g, ' ').slice(0, 160)
-      statusBackoff.set(key, Date.now() + 30_000)
-      log(`agent state HTTP ${res.status}${body ? ': ' + body : ''}; backing off 30s`)
-    }).catch((e) => {
-      statusBackoff.set(key, Date.now() + 30_000)
-      log('agent state request failed: ' + (e?.message || e) + '; backing off 30s')
-    }).finally(() => statusInFlight.delete(key))
-  }
-  const emitLaneStatus = (lane, state) => { for (const c of laneStatusTargets[lane]) sendStatus(c, state) }
+  // Activity belongs to an individual cycle. Independent ticket workers must
+  // not clear or overwrite each other's status targets.
+  const replyStatusTargets = new Set()
+  // Working/thinking/typing presence updates are intentionally silent. They
+  // generated notification noise without adding durable progress evidence.
+  const sendStatus = () => {}
+  const emitStatusTargets = (targets, state) => { for (const c of targets) sendStatus(c, state) }
   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.
@@ -805,12 +810,23 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     claude, agent, mcpUrl, mcpHeaders: { 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier },
     cfgKey: identifier, mcpConfig, workdir, log, debug, model, systemPrompt,
   }
-  // One watcher and one WS subscription, but two independent model lanes. This
-  // avoids duplicate event delivery while mentions can be answered during code.
-  const runners = {
-    work: createCycleRunner({ ...runnerOptions, onTool: (name) => { if (/post_message/.test(name)) emitLaneStatus('work', 'typing') } }),
-    reply: createCycleRunner({ ...runnerOptions, workdir: '', systemPrompt: CHAT_CHARTER + '\n\n' + credNote, cfgKey: identifier + '-reply', onTool: (name) => { if (/post_message/.test(name)) emitLaneStatus('reply', 'typing') } }),
-  }
+  // One watcher and one WS subscription, with a bounded pool of isolated coding
+  // runtimes. Replies remain serialized so one agent cannot answer two messages
+  // at once and race duplicate-delivery guards.
+  const MAX_CONCURRENT_WORKERS = 3
+  const activeWorkRunners = new Set()
+  const createWorkRunner = (control, workerWorkdir = '') => createCycleRunner({
+    ...runnerOptions,
+    ...(workerWorkdir ? { workdir: workerWorkdir } : {}),
+    onTool: (name) => { if (/post_message/.test(name)) emitStatusTargets(control.statusTargets, 'typing') },
+  })
+  const replyRunner = createCycleRunner({
+    ...runnerOptions,
+    workdir: '',
+    systemPrompt: CHAT_CHARTER + '\n\n' + credNote,
+    cfgKey: identifier + '-reply',
+    onTool: (name) => { if (/post_message/.test(name)) emitStatusTargets(replyStatusTargets, 'typing') },
+  })
   const codexPushGuide = agent === 'codex' && canCode
     ? '\n\nCODEX PR DELIVERY: when the repository exists in the local workspace, use that clone for branch creation, edits, tests, and commits; do not inspect or mutate it through linked-codebase MCP tools. To publish the local agent/* branch, run `openvisio-agent push-pr-branch` from the repository, then open the PR with `gh pr create`. The helper can only push HEAD to the matching agent/* branch on the exact authorized origin. If it reports OPENVISIO_PR_PUSH_AUTH_REQUIRED, do not retry or route around it. Report the one-time command `openvisio-agent authorize-pr-push` as the blocker. Use list_codebases/create_codebase_branch/create_codebase_commit/create_pull_request only as a fallback when the repository cannot be obtained locally.'
     : ''
@@ -825,18 +841,32 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   let codeModel = model
   let liteModel = chatModel || model
 
-  const lanes = {
-    work: { activeDelivery: null, cancelled: false },
-    reply: { activeDelivery: null, cancelled: false },
+  const queues = {
+    work: createCycleQueue({
+      concurrency: MAX_CONCURRENT_WORKERS,
+      groupKey: (item) => item.workdir || workdir || 'shared-workspace',
+      run: async (item) => {
+        const runner = createWorkRunner(item.control, item.workdir)
+        item.control.runner = runner
+        activeWorkRunners.add(runner)
+        try { return await executeCycle(item.kind, item.context, item.targetChannels, item.taskRef, item.delivery, runner, item.control, item.workdir) }
+        finally { activeWorkRunners.delete(runner); item.control.runner = null }
+      },
+      onError: (error, item) => {
+        pauseFailedTask(item.taskRef)
+        void finalizeFailedTaskPause(item.taskRef)
+        log('work cycle failed: ' + (error?.message || error))
+      },
+    }),
+    reply: createCycleQueue({
+      run: (item) => executeCycle(item.kind, item.context, item.targetChannels, item.taskRef, item.delivery, replyRunner, item.control, ''),
+      onError: (error, item) => {
+        pauseFailedTask(item.taskRef)
+        void finalizeFailedTaskPause(item.taskRef)
+        log('reply cycle failed: ' + (error?.message || error))
+      },
+    }),
   }
-  const queues = Object.fromEntries(['work', 'reply'].map((laneName) => [laneName, createCycleQueue({
-    run: (item) => executeCycle(item.kind, item.context, item.targetChannels, item.taskRef, item.delivery),
-    onError: (error, item) => {
-      pauseFailedTask(item.taskRef)
-      void finalizeFailedTaskPause(item.taskRef)
-      log(laneName + ' cycle failed: ' + (error?.message || error))
-    },
-  })]))
   // 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.
@@ -851,7 +881,11 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   const recentMentionSignatures = new Map(Array.isArray(replayState.recentMentionSignatures) ? replayState.recentMentionSignatures : [])
   const seenActivities = new Set(Array.isArray(replayState.seenActivities) ? replayState.seenActivities : [])
   const deliveredReplies = new Set(Array.isArray(replayState.deliveredReplies) ? replayState.deliveredReplies : [])
-  const memory = createByoMemoryGraph({ path: join(OV_DIR, 'watch-' + slug + '-memory.json') })
+  const memory = createMastraMemory({
+    ledgerPath: join(OV_DIR, 'watch-' + slug + '-memory.json'),
+    databasePath: join(OV_DIR, 'watch-' + slug + '-mastra.db'),
+    resourceId: identifier,
+  })
   // Completion delivery is runtime-owned for assigned coding work. Persist both
   // pending and delivered keys so a reconnect can finish a missed notification
   // without re-running the model or posting the same result twice.
@@ -1024,11 +1058,11 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     const controlKey = threadControlKey(channelId, parentId)
     if (!controlKey) return
     memory.remember({ key: controlKey, kind: 'thread', state: 'cancelled', summary, refs: { channelId: Number(channelId), threadId: parentId } })
-    for (const [laneName, lane] of Object.entries(lanes)) {
-      queues[laneName].cancel((item) => sameDeliveryThread(item.delivery, channelId, parentId), () => {
-        lane.cancelled = true
+    for (const [laneName, queue] of Object.entries(queues)) {
+      queue.cancel((item) => sameDeliveryThread(item.delivery, channelId, parentId), (item) => {
+        item.control.cancelled = true
         log(`${laneName} lane cancelled by a newer redirect/stand-down in thread ${parentId}`)
-        runners[laneName].cancelCurrent?.('thread-cancelled')
+        void item.control.runner?.cancelCurrent?.('thread-cancelled')
       })
     }
   }
@@ -1410,40 +1444,40 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   function drain(kind, context, targetChannels = [], taskRef = null, delivery = null) {
     const laneName = kind === 'full' ? 'work' : 'reply'
     const key = taskRef ? `ticket:${taskRef.projectId}:${taskRef.ticketId}` : delivery?.key
-    return queues[laneName].enqueue({ kind, context, targetChannels, taskRef, delivery }, key)
+    const itemWorkdir = laneName === 'work' && taskRef ? findTicketWorktree(workdir, taskRef.ticketId) : ''
+    const control = { cancelled: false, runner: null, statusTargets: new Set() }
+    return queues[laneName].enqueue({ kind, context, targetChannels, taskRef, delivery, workdir: itemWorkdir, control }, key)
   }
 
-  async function executeCycle(kind, context, targetChannels = [], taskRef = null, delivery = null) {
+  async function executeCycle(kind, context, targetChannels = [], taskRef = null, delivery = null, runner, control, preparedWorkdir = '') {
     const laneName = kind === 'full' ? 'work' : 'reply'
-    const lane = lanes[laneName]
-    lane.cancelled = false
-    lane.activeDelivery = delivery
+    const cycleControl = control || { cancelled: false, runner, statusTargets: new Set() }
     const ctx = context ? [context] : []
     const activeTaskRef = taskRef
-    const ticketWorktree = kind === 'full' && activeTaskRef ? findTicketWorktree(workdir, activeTaskRef.ticketId) : ''
+    const ticketWorktree = preparedWorkdir || (kind === 'full' && activeTaskRef ? findTicketWorktree(workdir, activeTaskRef.ticketId) : '')
     const runnerOptions = {
       ...(delivery?.watcherOwned ? { disabledMcpTools: ['post_message'] } : {}),
       ...(ticketWorktree ? { workdir: ticketWorktree } : {}),
     }
     const targets = [...new Set(targetChannels.filter((id) => id != null && Number.isFinite(Number(id))).map(Number))]
-    laneStatusTargets[laneName] = new Set(targets)
+    cycleControl.statusTargets = laneName === 'reply' ? replyStatusTargets : new Set(targets)
+    if (laneName === 'reply') {
+      replyStatusTargets.clear()
+      for (const target of targets) replyStatusTargets.add(target)
+    }
     // credNote + charter live in the cached system prompt now — the per-cycle
     // message is just the event context + the small base instruction.
     const memoryRefs = delivery
       ? { channelId: delivery.channelId, threadId: delivery.parentId }
       : activeTaskRef ? { projectId: activeTaskRef.projectId, ticketId: activeTaskRef.ticketId } : {}
-    const recalled = memory.context(memoryRefs)
+    const recalled = await memory.context(memoryRefs)
     const prompt = (ctx.length ? ctx.join('\n') + '\n\n' : '') + (recalled ? recalled + '\n\n' : '') + baseFor(kind, delivery)
     // Chat-shaped cycles (mentions/intro) may run on the cheaper chat model; code
     // work (full/sweep) uses the main model.
     const useModel = agent === 'codex' ? codeModel : kind === 'full' ? codeModel : liteModel
     log('running ' + kind + ' cycle…' + (ctx.length ? ' (' + ctx.length + ' event' + (ctx.length === 1 ? '' : 's') + ')' : '') + (useModel ? ' [' + useModel + ']' : ''))
-    // Live status: "working" now + a heartbeat so the UI (and its TTL) stays lit
-    // through a long cycle; onTool flips it to "typing" when post_message fires.
-    emitLaneStatus(laneName, 'working')
-    // Backend activity TTL is refreshed well before expiry, but only once every
-    // 20 seconds so long coding runs do not create needless network/battery load.
-    const heartbeat = targets.length ? setInterval(() => emitLaneStatus(laneName, 'working'), 20_000) : null
+    // Presence notifications are intentionally disabled; durable messages and
+    // ticket transitions are the only user-visible progress signals.
     try {
       // The ticket may have been reassigned or handed to review while waiting.
       // Re-check at dequeue, before any model can edit the repository.
@@ -1460,10 +1494,10 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
           return
         }
       }
-      if (lane.cancelled) return
-      const result = await runners[laneName].runCycle(prompt, useModel, runnerOptions)
+      if (cycleControl.cancelled) return
+      const result = await runner.runCycle(prompt, useModel, runnerOptions)
       let completionResult = result
-      if (lane.cancelled || result?.subtype === 'canceled') {
+      if (cycleControl.cancelled || result?.subtype === 'canceled') {
         log(laneName + ' cycle cancelled; no blocker or reply will be published')
         return
       }
@@ -1498,8 +1532,8 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       if (kind === 'full' && cycleSucceeded(result) && missing.length) {
         log(agent + ' coding cycle incomplete; recovery requires: ' + missing.join(', '))
         const recoveryPrompt = `CONTINUE THE SAME OPENVISIO REQUEST. Your earlier output did not complete it. Missing runtime evidence: ${missing.join('; ')}. An intent or progress message is not completion. Continue the actual work now, verify it, and then provide one distinct final result or real blocker using the original delivery rule; a final result after an earlier progress message is explicitly allowed and required. Do not repeat the progress message. ${codexPushGuide}\n\nORIGINAL REQUEST AND ROUTING CONTEXT:\n${prompt}`
-        const recovery = await runners.work.runCycle(recoveryPrompt, codeModel, runnerOptions)
-        if (lane.cancelled || recovery?.subtype === 'canceled') return
+        const recovery = await runner.runCycle(recoveryPrompt, codeModel, runnerOptions)
+        if (cycleControl.cancelled || recovery?.subtype === 'canceled') return
         const recoveredResult = combineRuntimeWorkEvidence(result, recovery)
         const recoveryMissing = missingRuntimeWorkEvidence(recoveredResult, { ticketCycle, resultMessageRequired })
         if (!cycleSucceeded(recovery) || recoveryMissing.length) {
@@ -1539,9 +1573,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
         }
       }
     } finally {
-      if (heartbeat) clearInterval(heartbeat)
-      laneStatusTargets[laneName].clear()
-      lane.activeDelivery = null
+      cycleControl.statusTargets.clear()
     }
   }
 
@@ -1606,9 +1638,9 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       const key = `${projectId}:${ticketId}`
       if (!belongsToSelf) {
         for (const [name, queue] of Object.entries(queues)) {
-          queue.cancel((item) => String(item.taskRef?.projectId) === String(projectId) && String(item.taskRef?.ticketId) === String(ticketId), () => {
-            lanes[name].cancelled = true
-            void runners[name].cancelCurrent?.()
+          queue.cancel((item) => String(item.taskRef?.projectId) === String(projectId) && String(item.taskRef?.ticketId) === String(ticketId), (item) => {
+            item.control.cancelled = true
+            void item.control.runner?.cancelCurrent?.()
           })
         }
         memory.remember({ key: `ticket:${projectId}:${ticketId}`, kind: 'ticket', state: 'unassigned', summary: ticket.title, refs: { projectId, ticketId } })
@@ -1802,11 +1834,13 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       if (taskProbeStartTimer) clearTimeout(taskProbeStartTimer)
       if (taskProbeTimer) clearInterval(taskProbeTimer)
       try { handle && handle.close() } catch { /* noop */ }
-      for (const [name, queue] of Object.entries(queues)) {
-        lanes[name].cancelled = true
-        queue.cancel(() => true)
+      for (const queue of Object.values(queues)) {
+        queue.cancel(() => true, (item) => {
+          item.control.cancelled = true
+          void item.control.runner?.cancelCurrent?.()
+        })
       }
-      await Promise.all(Object.values(runners).map((runner) => runner.cancelCurrent?.()))
+      await Promise.all([replyRunner.cancelCurrent?.(), ...[...activeWorkRunners].map((runner) => runner.cancelCurrent?.())])
       process.exit(0)
     }
     process.on('SIGTERM', bye)