openvisio-agent 0.17.6 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.17.6",
+  "version": "0.18.0",
   "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team — MCP tools + optional autonomy — in one command.",
   "type": "module",
   "bin": {

package/scripts/certify.mjs

@@ -23,6 +23,7 @@ run('diff whitespace check', 'git', ['diff', '--check'], repo)
 const watcher = readFileSync(join(root, 'src', 'watch.mjs'), 'utf8')
 const websocket = readFileSync(join(root, 'src', 'ws.mjs'), 'utf8')
 const activityHook = readFileSync(join(repo, 'frontend', 'hooks', 'useAgentActivity.ts'), 'utf8')
+const taskHook = readFileSync(join(repo, 'frontend', 'hooks', 'useBackendTasks.ts'), 'utf8')
 const spec = readFileSync(join(repo, 'docs', 'CODEX_BYO_AGENT_SPEC.md'), 'utf8')
 
 const assertions = [
@@ -33,7 +34,10 @@ const assertions = [
   ['assigned coding completion is posted by the watcher', watcher.includes('announceTaskCompletion') && watcher.includes("callMcpTool('post_message', { project_id: projectId, channel_id: channelId, content: report.content })")],
   ['completion requires review/done state and PR evidence', watcher.includes('buildTaskCompletionReport') && watcher.includes('completion report deferred')],
   ['completion delivery survives reconnect and deduplicates', watcher.includes('pendingCompletionReports: [...pendingCompletionReports]') && watcher.includes('reportedCompletions: [...reportedCompletions]') && watcher.includes('reportedCompletions.has(report.key)')],
+  ['verified completion is persisted as one ticket comment', watcher.includes("callMcpTool('comment_ticket', { project_id: projectId, ticket_id: ticketId, text: report.content })") && watcher.includes('reportedTaskComments: [...reportedTaskComments]') && watcher.includes('reportedTaskComments.has(report.key)')],
   ['ticket comments cannot masquerade as channel completion', watcher.includes('didChannelMessage') && watcher.includes("mcpCalls.includes('post_message')")],
+  ['single-watcher acquisition is atomic and fails closed', watcher.includes("openSync(lockPath, 'wx')") && watcher.includes('Could not acquire the single-watcher lock')],
+  ['websocket and activity mention delivery share a replay guard', watcher.includes('markMentionHandled(activityMessage, activityChannelId)') && watcher.includes('markMentionHandled(msg, cid)') && watcher.includes('recentMentionSignatures')],
   ['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')")],
   ['assigned task activity resolves a project channel', watcher.includes("callMcpTool('list_channels'") && watcher.includes('projectStatusChannel(projectId)')],
@@ -44,8 +48,12 @@ const assertions = [
   ['frontend consumes working event', activityHook.includes("'channel:agent:working'")],
   ['frontend consumes typing event', activityHook.includes("'channel:agent:typing'")],
   ['frontend activity TTL distinguishes work from typing', activityHook.includes('thinking: 6_000') && activityHook.includes('typing: 5_000') && activityHook.includes('working: 30_000')],
+  ['frontend consumes documented task comment events', taskHook.includes("'task:comment':") && taskHook.includes("'task:comment_updated':") && taskHook.includes("'task:comment_deleted':") && taskHook.includes("'task:comment_reacted':")],
   ['completion has an evidence failure gate', watcher.includes('WORK_CYCLE_FAILED')],
-  ['Codex policy rejection is captured from stderr', watcher.includes("stdio: ['ignore', 'pipe', 'pipe']") && watcher.includes('inspectDiagnostic(d)')],
+  ['OpenCode emits structured events for runtime evidence', watcher.includes("'--format', 'json'") && watcher.includes('opencodeEventEvidence(event)')],
+  ['OpenCode acknowledgements cannot satisfy coding completion', watcher.includes("agent === 'codex' || agent === 'opencode'") && watcher.includes('releaseTaskForRetry(activeTaskRef, prompt)')],
+  ['Codex policy rejection is captured from stderr', watcher.includes("stdio: ['ignore', 'pipe', 'pipe']") && watcher.includes('forwardDiagnostic(d)') && watcher.includes('inspectDiagnostic(incoming)')],
+  ['Codex recoverable subprocess diagnostics are not surfaced as activity', watcher.includes('shouldSuppressCodexDiagnostic(line)') && watcher.includes("forwardDiagnostic('', true)") && watcher.includes('RECOVER DEAD COMMAND SESSIONS')],
   ['policy rejection cannot be logged as successful', watcher.includes("subtype = policyBlock ? 'blocked'")],
   ['policy-blocked tickets are persisted and paused', watcher.includes('blockedTasks: [...blockedTasks]') && watcher.includes('WORK_CYCLE_BLOCKED')],
   ['policy blocker is surfaced to the user', watcher.includes('reportPolicyBlock(prompt, activeTaskRef, result.policyBlock)') && watcher.includes("Action required: I'm blocked")],

package/src/events.mjs

@@ -65,6 +65,56 @@ export function buildTaskCompletionReport(task, { projectId, fallbackText = '' }
   return { key: `${projectId ?? task.project_id ?? task.projectId ?? '?'}:${task.id}:${revision}`, content, prUrl }
 }
 
+// OpenCode's `run --format json` emits one JSON object per completed text/tool
+// part. Reduce each event to the small set of facts the watcher is allowed to
+// trust. In particular, model prose and process exit 0 are never work evidence.
+export function opencodeEventEvidence(event) {
+  if (!event || typeof event !== 'object') return {}
+  const part = event.part ?? event.properties?.part ?? event.item ?? event
+  if (!part || typeof part !== 'object') return {}
+
+  const eventType = String(event.type ?? '')
+  const partType = String(part.type ?? '')
+  if (eventType === 'text' || partType === 'text') {
+    return { outputText: typeof part.text === 'string' ? part.text : '' }
+  }
+  if (eventType === 'error') {
+    return { runtimeError: String(event.error?.message ?? event.message ?? part.error ?? 'OpenCode runtime error') }
+  }
+  if (eventType !== 'tool_use' && partType !== 'tool') return {}
+
+  const tool = String(part.tool ?? part.name ?? event.tool ?? '').trim()
+  if (!tool) return {}
+  const state = part.state && typeof part.state === 'object' ? part.state : {}
+  const status = String(state.status ?? part.status ?? '').toLowerCase()
+  const failed = /error|failed|denied|rejected/.test(status) || state.error != null || part.error != null
+  const completed = !failed && (!status || /completed|success|succeeded|ok/.test(status))
+  const input = state.input && typeof state.input === 'object' ? state.input : (part.input && typeof part.input === 'object' ? part.input : {})
+  const command = String(input.command ?? input.cmd ?? '')
+
+  const lowerTool = tool.toLowerCase()
+  const prefixed = /^(?:mcp__)?openvisio(?:-team|_team)(?:__|[_.:/-])(.+)$/i.exec(tool)
+  const bareTool = lowerTool.replace(/[-.]/g, '_')
+  const knownMcp = /^(?:get_ticket|list_tasks|list_task_types|update_ticket|post_message|comment_ticket|react_message|list_projects|list_agents|list_activity)$/
+  const mcpTool = (prefixed?.[1] ? prefixed[1].replace(/[-.]/g, '_') : (knownMcp.test(bareTool) ? bareTool : '')).toLowerCase()
+  const mutationTool = /^(?:edit|write|patch|apply_patch|multiedit|multi_edit)$/i.test(tool)
+  const bashTool = /^(?:bash|shell|terminal|exec|command)$/i.test(tool)
+  const commandMutation = /\b(?:git\s+(?:commit|push)|gh\s+pr\s+create)\b/i.test(command)
+
+  return {
+    tool,
+    ...(mcpTool ? { mcpTool } : {}),
+    failed,
+    completed,
+    didCode: completed && (mutationTool || bashTool),
+    didRepoMutation: completed && (mutationTool || (bashTool && commandMutation)),
+    didMcpTaskRead: completed && /^(?:get_ticket|list_tasks|list_task_types)$/.test(mcpTool),
+    didMcpTaskUpdate: completed && mcpTool === 'update_ticket',
+    didMessage: completed && /^(?:post_message|comment_ticket)$/.test(mcpTool),
+    didChannelMessage: completed && mcpTool === 'post_message',
+  }
+}
+
 export function agentStateRequest(backend, channelId, state, apiKey, identifier) {
   if (!['thinking', 'working', 'typing'].includes(state)) throw new Error('invalid agent state')
   const id = Number(channelId)
@@ -90,6 +140,38 @@ export function codexPolicyBlock(value) {
   return { kind: 'authorization-required', command, reason: reason.slice(0, 900), commit, remote: push?.[1] || '', branch: push?.[2] || '' }
 }
 
+// Codex emits this plumbing notice whenever `exec` sees non-interactive stdin,
+// even when stdin is intentionally closed and there is nothing to read. It is
+// not agent activity, progress, or a blocker, so keep it out of watcher logs.
+export function shouldSuppressCodexDiagnostic(value) {
+  const line = String(value || '').trim()
+  if (/^Reading additional input from stdin\.\.\.$/.test(line)) return true
+
+  // `codex exec` can emit these after it has already recovered: the watcher
+  // pins the requested model, so a background catalog-refresh timeout does not
+  // change the active cycle, and an unknown write_stdin pid means that one
+  // command session exited before Codex polled it. The model still receives the
+  // tool error and can start a fresh command; these internals should not masquerade
+  // as agent activity or an OpenVisio work failure in the user's watcher log.
+  if (/\bERROR codex_models_manager::manager: failed to refresh available models: timeout waiting for child process to exit$/.test(line)) return true
+  return /\bERROR codex_core::tools::router: error=write_stdin failed: Unknown process id \d+$/.test(line)
+}
+
+// Build both a durable id key and a short-lived content signature for a mention.
+// The backend can surface one logical message through WebSocket delivery and
+// activity reconciliation with different envelope ids; the signature closes that
+// gap without permanently suppressing a genuinely repeated question later.
+export function mentionDedupeKeys(message, channelId) {
+  const m = message && typeof message === 'object' ? message : {}
+  const id = m.message_id ?? m.messageId ?? m.id
+  const parent = m.parent_id ?? m.parentId ?? ''
+  const text = String(m.content ?? m.body ?? m.text ?? m.message ?? '').replace(/\s+/g, ' ').trim().slice(0, 180)
+  return {
+    idKey: id != null ? `id:${id}` : '',
+    signatureKey: text ? `sig:${channelId ?? '?'}|${parent}|${text}` : '',
+  }
+}
+
 // A mention event means this agent's name appeared somewhere, not necessarily
 // that the request was addressed to it. Reject a later-agent hand-off before a
 // model starts, while keeping explicitly shared requests addressed to both.

package/src/watch.mjs

@@ -5,12 +5,12 @@
 // than written to disk from a pasted heredoc.
 
 import { spawn, spawnSync } from 'node:child_process'
-import { writeFileSync, mkdirSync, existsSync, readFileSync, unlinkSync } from 'node:fs'
+import { closeSync, writeFileSync, mkdirSync, existsSync, openSync, readFileSync, unlinkSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
 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 { agentStateRequest, buildTaskCompletionReport, codexPolicyBlock, requestTargetsLaterAgent, taskAgentId, taskFromEvent, taskIsAwaitingReview, taskIsCompleted } from './events.mjs'
+import { agentStateRequest, buildTaskCompletionReport, codexPolicyBlock, mentionDedupeKeys, opencodeEventEvidence, requestTargetsLaterAgent, shouldSuppressCodexDiagnostic, taskAgentId, taskFromEvent, taskIsAwaitingReview, taskIsCompleted } from './events.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
@@ -38,7 +38,7 @@ const REPLY_DISCIPLINE = [
 
 // ── 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. Use only tools that actually appear in your openvisio-team tool list. Backend MCP commonly provides post_message, react_message, list_agents, list_projects, list_tasks, get_ticket, update_ticket, and list_activity. Some relay runtimes also provide poll_inbox or get_marching_orders. Never call a tool that is absent. You have NO file/Bash/git tools in this mode, so you cannot write code yourself.',
+  'YOU ARE a connected agent in an OpenVisio team, running in CHAT-ONLY mode. Use only tools that actually appear in your openvisio-team tool list. Backend MCP provides post_message, react_message, list_agents, list_projects, list_tasks, get_ticket, update_ticket, comment_ticket, and list_activity. Some relay runtimes also provide poll_inbox or get_marching_orders. Never call a tool that is absent. You have NO file/Bash/git tools in this mode, so you cannot write code yourself.',
   'WORK ETHIC — behave like a dependable teammate: never leave a promise dangling. Either ACT now (reply, or file a ticket) or say plainly you can\'t and offer to file a ticket / tag a coding agent who can. Never invent progress. Close the loop every cycle — the human should never have to remind you to circle back.',
   '',
   REPLY_DISCIPLINE,
@@ -66,7 +66,7 @@ const COORDINATE = [
 // 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 tools — use the names actually present. Backend MCP provides project/task discovery through list_agents, list_projects, list_tasks, get_ticket, update_ticket, plus post_message/react_message/list_activity. Relay runtimes may additionally expose poll_inbox, get_marching_orders, or comment_ticket.',
+  '  • openvisio-team tools — use the names actually present. Backend MCP provides project/task discovery through list_agents, list_projects, list_tasks, get_ticket, update_ticket, and comment_ticket, plus post_message/react_message/list_activity. Relay runtimes may additionally expose poll_inbox or get_marching_orders.',
   '  • 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. Reuse existing clones and the context you already verified. Read repository AGENTS.md instructions before changing code. For any task: locate the relevant repo under the workspace; clone it only when it is genuinely absent, then work inside that subfolder. Never ask the user for a path you can discover yourself.',
@@ -77,6 +77,7 @@ const CODE_CHARTER = [
   '  2. FINISH, then REPORT. Always update/move the ticket with update_ticket. Reply in a supplied human source thread when one exists. For backlog-assigned work, do not call post_message yourself: the watcher publishes one evidence-verified result in the project channel after the PR and ticket handoff are confirmed.',
   '  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.',
+  '  5. RECOVER DEAD COMMAND SESSIONS. If write_stdin reports “Unknown process id”, that command session has already exited. Never poll the same process id again. Start a fresh exec_command when more work is required, then continue the task and verify the final state.',
   '',
   REPLY_DISCIPLINE,
 ].join('\n')
@@ -90,7 +91,7 @@ const CODE_FULL = [
   '  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: move/update the ticket with update_ticket. Reply with the summary + PR link in a source thread explicitly supplied by the event. For backlog-only tickets, do not call post_message yourself; the watcher sends one verified project-channel completion message and deduplicates it across reconnects.',
+  '  6. CLOSE THE LOOP: use comment_ticket for a concrete ticket-scoped blocker or clarification, then move/update the ticket with update_ticket. The watcher adds one evidence-verified final ticket comment after handoff. Reply with the summary + PR link in a source thread explicitly supplied by the event. For backlog-only tickets, do not call post_message yourself; the watcher sends one verified project-channel completion message and deduplicates it across reconnects.',
   'Bash is for git / gh / tests / clone ONLY — never to hunt for credentials (they are given to you above).',
 ].join('\n')
 
@@ -178,18 +179,31 @@ function claimStartupSweep(key) {
 // are taken over. Returns { release } or { conflict: <pid> }.
 function acquireSingleInstance(key) {
   const lockPath = join(OV_DIR, 'watch-' + key + '.lock')
-  try {
-    mkdirSync(OV_DIR, { recursive: true })
-    if (existsSync(lockPath)) {
-      const pid = parseInt(String(readFileSync(lockPath, 'utf8')).trim(), 10)
-      if (pid && pid !== process.pid) {
-        let alive = false
-        try { process.kill(pid, 0); alive = true } catch (e) { alive = !!(e && e.code === 'EPERM') }
-        if (alive) return { conflict: pid }
-      }
+  try { mkdirSync(OV_DIR, { recursive: true }) } catch (error) { return { error } }
+  // `existsSync` followed by `writeFileSync` is a race: two KeepAlive starts can
+  // both observe no file and both become watchers. `wx` makes creation atomic.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let fd = null
+    try {
+      fd = openSync(lockPath, 'wx')
+      writeFileSync(fd, String(process.pid))
+      closeSync(fd); fd = null
+      break
+    } catch (error) {
+      if (fd != null) { try { closeSync(fd) } catch { /* already closed */ } }
+      if (error?.code !== 'EEXIST') return { error }
+      let pid = 0
+      try { pid = parseInt(String(readFileSync(lockPath, 'utf8')).trim(), 10) } catch { /* an in-flight creator owns it */ }
+      if (!pid) return { conflict: 'unknown' }
+      let alive = false
+      try { process.kill(pid, 0); alive = true } catch (e) { alive = !!(e && e.code === 'EPERM') }
+      if (alive) return { conflict: pid }
+      // Exact stale lock only. If another process wins the retry, its atomic file
+      // remains and this process will return conflict on the next iteration.
+      try { unlinkSync(lockPath) } catch (e) { if (e?.code !== 'ENOENT') return { error: e } }
+      if (attempt === 1) return { conflict: 'unknown' }
     }
-    writeFileSync(lockPath, String(process.pid))
-  } catch { /* if the lock can't be written, don't block the agent from running */ }
+  }
   const release = () => { try { if (parseInt(String(readFileSync(lockPath, 'utf8')).trim(), 10) === process.pid) unlinkSync(lockPath) } catch { /* already gone */ } }
   return { release }
 }
@@ -229,6 +243,7 @@ export async function runWatch({ flags }) {
   // both connect as the same agent and both answer every mention. Refuse to start.
   if (!flags.install) {
     const lock = acquireSingleInstance(slug || 'openvisio')
+    if (lock.error) fail(`Could not acquire the single-watcher lock for "${slug || 'openvisio'}": ${lock.error.message || lock.error}`)
     if (lock.conflict) {
       const watcherName = slug || 'openvisio'
       const logs = process.platform === 'darwin'
@@ -274,7 +289,7 @@ export async function runWatch({ flags }) {
 // The openvisio-team MCP is declared in an `opencode.json` written into the run cwd
 // (opencode reads it from there). `--auto` approves tool use non-interactively.
 // Same { runCycle, canCode } contract as the Claude runner.
-function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model, systemPrompt }) {
+function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model, onTool, systemPrompt }) {
   // opencode reads opencode.json from its CWD: the code workspace, or a dedicated
   // per-agent dir for chat-only agents.
   const cwd = workdir || join(OV_DIR, 'opencode-' + (cfgKey || 'agent'))
@@ -303,18 +318,71 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
       // opencode has no system-prompt flag; each run is a fresh process, so fold the
       // charter/creds into the message (still not re-accumulated across cycles).
       const full = systemPrompt ? systemPrompt + '\n\n' + prompt : prompt
-      const args = ['run', full, '--auto', ...(m ? ['--model', m] : [])]
-      let child = null, done = false
-      const finish = (o) => { if (done) return; done = true; clearTimeout(timer); resolve(o) }
+      // JSON mode is the evidence boundary. Formatted stdout only tells us that
+      // OpenCode exited; raw events tell us which tools actually completed.
+      const args = ['run', full, '--auto', '--format', 'json', ...(m ? ['--model', m] : [])]
+      let child = null, done = false, didCode = false, didRepoMutation = false, didMessage = false, didChannelMessage = false, didMcpTaskRead = false, didMcpTaskUpdate = false
+      let outputText = '', jsonlBuffer = ''
+      const mcpCalls = new Set(), mcpErrors = new Set(), runtimeErrors = new Set()
+      const finish = (o) => {
+        if (done) return
+        done = true
+        clearTimeout(timer)
+        const calls = [...mcpCalls]
+        log('opencode MCP calls: ' + (calls.length ? calls.join(', ') : 'none') + (mcpErrors.size ? ' (failed: ' + [...mcpErrors].join(', ') + ')' : ''))
+        resolve({ ...o, didCode, didRepoMutation, didMessage, didChannelMessage, didMcpTaskRead, didMcpTaskUpdate, mcpCalls: calls, mcpErrors: [...mcpErrors], outputText })
+      }
+      const inspectLine = (line) => {
+        const value = String(line || '').trim()
+        if (!value) return
+        let event
+        try { event = JSON.parse(value) } catch {
+          if (debug) log('  · unparsed opencode output: ' + value.slice(0, 180))
+          return
+        }
+        const evidence = opencodeEventEvidence(event)
+        if (evidence.outputText) {
+          outputText += ' ' + evidence.outputText
+          if (debug) log('  · ' + evidence.outputText.replace(/\s+/g, ' ').slice(0, 180))
+        }
+        if (evidence.runtimeError) runtimeErrors.add(evidence.runtimeError)
+        if (!evidence.tool) return
+        if (debug) log('  → tool ' + evidence.tool + (evidence.failed ? ' (failed)' : evidence.completed ? ' (completed)' : ''))
+        try { onTool && onTool(evidence.tool) } catch { /* activity is best-effort */ }
+        if (evidence.mcpTool) {
+          mcpCalls.add(evidence.mcpTool)
+          if (evidence.failed) mcpErrors.add(evidence.mcpTool)
+          else if (evidence.completed) mcpErrors.delete(evidence.mcpTool)
+        }
+        didCode ||= !!evidence.didCode
+        didRepoMutation ||= !!evidence.didRepoMutation
+        didMessage ||= !!evidence.didMessage
+        didChannelMessage ||= !!evidence.didChannelMessage
+        didMcpTaskRead ||= !!evidence.didMcpTaskRead
+        didMcpTaskUpdate ||= !!evidence.didMcpTaskUpdate
+      }
       const timer = setTimeout(() => {
         log('opencode cycle TIMED OUT after ' + Math.round(maxCycleMs / 1000) + 's — killing')
         try { child && child.kill() } catch { /* gone */ }
         finish({ type: 'result', subtype: 'timeout' })
       }, maxCycleMs)
       log('running opencode cycle…' + (m ? ' [' + m + ']' : ''))
-      try { child = spawn(bin, args, { cwd, stdio: ['ignore', debug ? 'inherit' : 'ignore', 'inherit'] }) }
+      try {
+        child = spawn(bin, args, { cwd, stdio: ['ignore', 'pipe', 'inherit'] })
+        child.stdout?.on('data', (data) => {
+          jsonlBuffer += String(data)
+          const lines = jsonlBuffer.split('\n')
+          jsonlBuffer = lines.pop() ?? ''
+          for (const line of lines) inspectLine(line)
+        })
+      }
       catch (e) { log('opencode spawn failed: ' + (e && e.message ? e.message : e) + ' — is opencode installed? (npm i -g opencode-ai, then `opencode auth login`)'); return finish({ type: 'result', subtype: 'spawn-failed' }) }
-      child.on('exit', (code) => { log('opencode cycle done (' + (code === 0 ? 'ok' : 'exit ' + code) + ')'); finish({ type: 'result', subtype: code === 0 ? 'ok' : 'error' }) })
+      child.on('close', (code) => {
+        inspectLine(jsonlBuffer); jsonlBuffer = ''
+        const subtype = code === 0 && runtimeErrors.size === 0 ? 'ok' : 'error'
+        log('opencode cycle done (' + (subtype === 'ok' ? 'ok' : 'exit ' + code) + ')')
+        finish({ type: 'result', subtype })
+      })
       child.on('error', (e) => { log('opencode error: ' + (e && e.message ? e.message : e)); finish({ type: 'result', subtype: 'error' }) })
     })
   }
@@ -346,7 +414,7 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
         ...(m ? ['--model', m] : []),
         ...(mcpOverride ? ['-c', mcpOverride] : []),
         full]
-      let child = null, done = false, didCode = false, didRepoMutation = false, didMessage = false, didChannelMessage = false, outputText = '', jsonlBuffer = '', stderrBuffer = ''
+      let child = null, done = false, didCode = false, didRepoMutation = false, didMessage = false, didChannelMessage = false, outputText = '', jsonlBuffer = '', stderrBuffer = '', stderrLineBuffer = ''
       let policyBlock = null
       const mcpCalls = new Set(), mcpErrors = new Set()
       let didMcpTaskRead = false, didMcpTaskUpdate = false
@@ -363,6 +431,20 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
         stderrBuffer = (stderrBuffer + s).slice(-24_000)
         policyBlock = codexPolicyBlock(stderrBuffer) || policyBlock
       }
+      const forwardDiagnostic = (value, flush = false) => {
+        const incoming = String(value || '')
+        inspectDiagnostic(incoming)
+        stderrLineBuffer += incoming
+        const lines = stderrLineBuffer.split('\n')
+        stderrLineBuffer = lines.pop() ?? ''
+        for (const line of lines) {
+          if (!shouldSuppressCodexDiagnostic(line)) process.stderr.write(line + '\n')
+        }
+        if (flush && stderrLineBuffer) {
+          if (!shouldSuppressCodexDiagnostic(stderrLineBuffer)) process.stderr.write(stderrLineBuffer)
+          stderrLineBuffer = ''
+        }
+      }
       const inspectLine = (line) => {
         const s = line.trim()
         if (!s) return
@@ -403,15 +485,14 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
           for (const line of lines) inspectLine(line)
         })
         if (child.stderr) child.stderr.on('data', (d) => {
-          inspectDiagnostic(d)
-          process.stderr.write(d)
+          forwardDiagnostic(d)
         })
       } catch (e) {
         log('codex spawn failed: ' + (e && e.message ? e.message : e) + ' — is Codex installed and signed in? (`npm i -g @openai/codex`, then `codex login`)')
         return finish({ type: 'result', subtype: 'spawn-failed' })
       }
       child.on('close', (code) => {
-        inspectLine(jsonlBuffer); jsonlBuffer = ''; inspectDiagnostic('')
+        inspectLine(jsonlBuffer); jsonlBuffer = ''; forwardDiagnostic('', true)
         const subtype = policyBlock ? 'blocked' : code === 0 ? 'ok' : 'error'
         log('codex cycle done (' + (subtype === 'blocked' ? 'BLOCKED: user authorization required' : subtype === 'ok' ? 'ok' : 'exit ' + code) + ')')
         finish({ type: 'result', subtype })
@@ -433,7 +514,7 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
   const maxCycleMs = canCode ? MAX_CODE_CYCLE_MS : MAX_CYCLE_MS
   // opencode drives cycles differently — a headless `opencode run` per cycle rather
   // than a persistent stream-json session. Same { runCycle, canCode } contract.
-  if (agent === 'opencode') return createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model, systemPrompt })
+  if (agent === 'opencode') return createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, maxCycleMs, log, debug, model, onTool, systemPrompt })
   if (agent === 'codex') return createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, log, debug, model, onTool, systemPrompt })
   let child = null
   // The model the CURRENT session was spawned with. runCycle can pass a different
@@ -583,7 +664,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   const canCode = !!workdir
   // The Mastra bridge authenticates per-CALL: every openvisio-team tool needs
   // agent_identifier + agent_api_key as arguments. Hand them over up front.
-  const credNote = `AUTH: the openvisio-team tools REQUIRE two arguments on EVERY call — agent_identifier: "${identifier}" and agent_api_key: "${apiKey}". Include BOTH on every openvisio-team tool call. Use ONLY names shown in the current tool list. On backend MCP, discover work with list_agents, list_projects, list_tasks, get_ticket, update_ticket, and list_activity; get_marching_orders, poll_inbox, and comment_ticket may be absent. Tools may be namespaced — call whichever names actually appear. The credentials are given here; do NOT hunt for them. Bash/git/gh ARE for code work; this rule only forbids searching for keys.`
+  const credNote = `AUTH: the openvisio-team tools REQUIRE two arguments on EVERY call — agent_identifier: "${identifier}" and agent_api_key: "${apiKey}". Include BOTH on every openvisio-team tool call. Use ONLY names shown in the current tool list. On backend MCP, discover and update work with list_agents, list_projects, list_tasks, get_ticket, update_ticket, comment_ticket, and list_activity; get_marching_orders and poll_inbox may be absent. Tools may be namespaced — call whichever names actually appear. The credentials are given here; do NOT hunt for them. Bash/git/gh ARE for code work; this rule only forbids searching for keys.`
   // The STATIC charter + creds are the session system prompt (cached, billed once),
   // NOT re-sent in every cycle's user message — the big token saving.
   const systemPrompt = (canCode ? CODE_CHARTER : CHAT_CHARTER) + '\n\n' + credNote
@@ -620,29 +701,50 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   let replayState = {}
   try { replayState = JSON.parse(readFileSync(replayPath, 'utf8')) } catch { /* first run */ }
   const seenMentions = new Set(Array.isArray(replayState.seenMentions) ? replayState.seenMentions : [])
+  const recentMentionSignatures = new Map(Array.isArray(replayState.recentMentionSignatures) ? replayState.recentMentionSignatures : [])
   const seenActivities = new Set(Array.isArray(replayState.seenActivities) ? replayState.seenActivities : [])
   // 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.
   const pendingCompletionReports = new Set(Array.isArray(replayState.pendingCompletionReports) ? replayState.pendingCompletionReports : [])
   const reportedCompletions = new Set(Array.isArray(replayState.reportedCompletions) ? replayState.reportedCompletions : [])
+  const reportedTaskComments = new Set(Array.isArray(replayState.reportedTaskComments) ? replayState.reportedTaskComments : [])
   // A policy-blocked task stays paused across reconnects. It is released only
   // after the ticket itself carries explicit authorization or is completed/
   // unassigned. This prevents a 30-minute reconciliation retry from repeatedly
   // attempting the same rejected egress action.
   const blockedTasks = new Set(Array.isArray(replayState.blockedTasks) ? replayState.blockedTasks : [])
   const trimSeen = (set) => { while (set.size > 500) set.delete(set.values().next().value) }
+  const MENTION_SIGNATURE_TTL_MS = 10 * 60 * 1000
+  const pruneMentionSignatures = () => {
+    const cutoff = Date.now() - MENTION_SIGNATURE_TTL_MS
+    for (const [key, at] of recentMentionSignatures) if (Number(at) < cutoff) recentMentionSignatures.delete(key)
+    while (recentMentionSignatures.size > 500) recentMentionSignatures.delete(recentMentionSignatures.keys().next().value)
+  }
   const persistReplay = () => {
     try {
+      pruneMentionSignatures()
       writeJson(replayPath, {
         seenMentions: [...seenMentions],
+        recentMentionSignatures: [...recentMentionSignatures],
         seenActivities: [...seenActivities],
         blockedTasks: [...blockedTasks],
         pendingCompletionReports: [...pendingCompletionReports],
         reportedCompletions: [...reportedCompletions],
+        reportedTaskComments: [...reportedTaskComments],
       }, true)
     } catch { /* best-effort */ }
   }
+  const markMentionHandled = (message, channelId) => {
+    pruneMentionSignatures()
+    const { idKey, signatureKey } = mentionDedupeKeys(message, channelId)
+    const duplicate = (idKey && seenMentions.has(idKey)) || (signatureKey && recentMentionSignatures.has(signatureKey))
+    if (duplicate) return true
+    if (idKey) { seenMentions.add(idKey); trimSeen(seenMentions) }
+    if (signatureKey) recentMentionSignatures.set(signatureKey, Date.now())
+    persistReplay()
+    return false
+  }
   // 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
@@ -676,7 +778,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   }
   const ensureMcpSession = async () => {
     if (mcpSessionId) return
-    const res = await mcpPost({ jsonrpc: '2.0', id: ++mcpRpcId, method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'openvisio-agent', version: '0.17.6' } } }, false)
+    const res = await mcpPost({ jsonrpc: '2.0', id: ++mcpRpcId, method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'openvisio-agent', version: '0.18.0' } } }, false)
     if (!res.ok) throw new Error('MCP initialize HTTP ' + res.status)
     await mcpPayload(res)
     mcpSessionId = res.headers.get('mcp-session-id') || ''
@@ -736,6 +838,14 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     const ticket = current.ticket ?? current.task ?? current
     const report = buildTaskCompletionReport(ticket, { projectId, fallbackText: result.outputText })
     if (!report) return false
+    // Ticket comments are now a backend first-class surface. The watcher owns the
+    // final comment so every runtime (Claude, Codex, OpenCode) closes the ticket
+    // loop consistently, and the persisted report key prevents reconnect repeats.
+    if (!reportedTaskComments.has(report.key)) {
+      await callMcpTool('comment_ticket', { project_id: projectId, ticket_id: ticketId, text: report.content })
+      reportedTaskComments.add(report.key); trimSeen(reportedTaskComments); persistReplay()
+      log('posted verified ticket comment for #' + ticketId)
+    }
     if (reportedCompletions.has(report.key)) {
       pendingCompletionReports.delete(taskKey)
       persistReplay()
@@ -794,7 +904,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       delivered = true
       return
     } catch (e) {
-      log('comment_ticket unavailable for blocker; recording it on ticket #' + ticketId)
+      log('comment_ticket failed for blocker; falling back to the ticket description for #' + ticketId)
     }
     const current = toolData(await callMcpTool('get_ticket', { project_id: projectId, ticket_id: ticketId }))
     const ticket = current.ticket ?? current.task ?? current
@@ -836,6 +946,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       const projects = Array.isArray(projectsData.projects) ? projectsData.projects : []
       const assigned = []
       const mentionActivity = []
+      let activityReplayTouched = false
       for (const project of projects) {
         const [tasksData, typesData, activityData] = await Promise.all([
           callMcpTool('list_tasks', { project_id: project.id }).then(toolData),
@@ -879,12 +990,20 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
           const lower = text.toLowerCase()
           const activityKey = String(project.id) + ':' + String(item.id ?? item.message_id ?? item.messageId ?? text.slice(0, 500))
           if (!seenActivities.has(activityKey) && mentionNeedles.some((needle) => lower.includes(needle)) && /message|mention|channel/i.test(text)) {
-            seenActivities.add(activityKey); trimSeen(seenActivities)
+            const data = item?.data && typeof item.data === 'object' ? item.data : null
+            const activityMessage = item?.message && typeof item.message === 'object'
+              ? item.message
+              : data?.message && typeof data.message === 'object' ? data.message : item
+            const activityChannelId = item?.channel_id ?? item?.channelId ?? data?.channel_id ?? data?.channelId
+            seenActivities.add(activityKey); trimSeen(seenActivities); activityReplayTouched = true
+            // The same logical mention may already have arrived over WebSocket.
+            // Share the id/signature guard instead of starting a second model turn.
+            if (markMentionHandled(activityMessage, activityChannelId)) continue
             mentionActivity.push({ projectId: project.id, project: project.name, activity: item })
           }
         }
       }
-      if (mentionActivity.length) persistReplay()
+      if (activityReplayTouched) persistReplay()
       if (!assigned.length) lastTaskSignature = ''
       else {
         const signature = JSON.stringify(assigned)
@@ -915,6 +1034,45 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   // Higher rank wins when coalescing cycles requested while one is running.
   const RANK = { fast: 0, intro: 1, coord: 2, sweep: 2, full: 3 }
   const baseFor = (kind) => kind === 'intro' ? INTRO : kind === 'full' ? fullPrompt : (kind === 'coord' || kind === 'sweep') ? COORDINATE : fastPrompt
+  // Codex and OpenCode expose structured action streams. Require runtime facts
+  // from those streams before accepting a full coding cycle. Claude's evidence
+  // shape is different and remains on its existing completion path.
+  const evidenceGatedRuntime = agent === 'codex' || agent === 'opencode'
+  const missingWorkEvidence = (result, ticketCycle) => {
+    const missing = [
+      ticketCycle && !result?.didMcpTaskRead && 'read the ticket through get_ticket/list_tasks',
+      !result?.didRepoMutation && 'perform and verify the repository change',
+      ticketCycle && !result?.didMcpTaskUpdate && 'update the ticket through update_ticket',
+    ].filter(Boolean)
+    if (result?.mcpErrors?.length) missing.push('resolve failed MCP calls: ' + result.mcpErrors.join(', '))
+    return missing
+  }
+  const combineWorkEvidence = (first, second) => ({
+    ...second,
+    didCode: !!first?.didCode || !!second?.didCode,
+    didRepoMutation: !!first?.didRepoMutation || !!second?.didRepoMutation,
+    didMessage: !!first?.didMessage || !!second?.didMessage,
+    didChannelMessage: !!first?.didChannelMessage || !!second?.didChannelMessage,
+    didMcpTaskRead: !!first?.didMcpTaskRead || !!second?.didMcpTaskRead,
+    didMcpTaskUpdate: !!first?.didMcpTaskUpdate || !!second?.didMcpTaskUpdate,
+    mcpCalls: [...new Set([...(first?.mcpCalls || []), ...(second?.mcpCalls || [])])],
+    // A focused recovery is allowed to clear an earlier MCP failure. Only calls
+    // still failing in the recovery remain blockers.
+    mcpErrors: second?.mcpErrors || [],
+    outputText: [first?.outputText, second?.outputText].filter(Boolean).join(' '),
+  })
+  const releaseTaskForRetry = (taskRef, prompt) => {
+    const directProject = Number(taskRef?.projectId)
+    const directTicket = Number(taskRef?.ticketId)
+    if (Number.isFinite(directProject) && Number.isFinite(directTicket)) seenTasks.delete(`${directProject}:${directTicket}`)
+    else {
+      const match = /ticket\s+#?(\d+).*?project\s+(\d+)/i.exec(prompt)
+      if (match) seenTasks.delete(`${match[2]}:${match[1]}`)
+    }
+    // The next task update or periodic reconciliation must be allowed to queue
+    // this work again. An acknowledgement is not a terminal task signature.
+    lastTaskSignature = ''
+  }
 
   async function drain(kind, context, targetChannels = [], taskRef = null) {
     const laneName = kind === 'full' ? 'work' : 'reply'
@@ -956,6 +1114,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
         log('WORK_CYCLE_BLOCKED ' + result.subtype + '; publishing blocker')
         try { await publishBlocker({ prompt, taskRef: activeTaskRef, notice }) }
         catch (e) { log('failed to publish cycle blocker: ' + (e?.message || e)) }
+        releaseTaskForRetry(activeTaskRef, prompt)
         return
       }
       if (kind !== 'full' && result?.mcpErrors?.length) {
@@ -968,38 +1127,37 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       // Model prose never proves success or a blocker. Full cycles must produce
       // runtime-observed ticket reads, repository evidence, and ticket updates.
       const ticketCycle = !!activeTaskRef || /ticket\s+#?\d+.*?project\s+\d+/i.test(prompt)
-      const incomplete = !result?.didRepoMutation || (ticketCycle && (!result?.didMcpTaskRead || !result?.didMcpTaskUpdate)) || result?.mcpErrors?.length
-      if (agent === 'codex' && kind === 'full' && result?.subtype === 'ok' && incomplete) {
-        const missing = [ticketCycle && !result.didMcpTaskRead && 'read the ticket through get_ticket/list_tasks', !result.didRepoMutation && 'perform and verify the repository change', ticketCycle && !result.didMcpTaskUpdate && 'update the ticket through update_ticket'].filter(Boolean)
-        if (result.mcpErrors?.length) missing.push('resolve failed MCP calls: ' + result.mcpErrors.join(', '))
-        log('coding cycle incomplete; recovery requires: ' + missing.join(', '))
+      const missing = missingWorkEvidence(result, ticketCycle)
+      if (evidenceGatedRuntime && kind === 'full' && result?.subtype === 'ok' && missing.length) {
+        log(agent + ' coding cycle incomplete; recovery requires: ' + missing.join(', '))
         const recovery = await runners.work.runCycle(`The assigned task is NOT complete. Missing runtime evidence: ${missing.join('; ')}. Do not post an acknowledgement or claim success. Resume now. Use get_ticket/list_tasks and list_task_types, perform and verify the repository work, commit and push an agent/* branch, open the PR, and call update_ticket with the correct board column. Post only when the original context supplies a source thread.`, codeModel)
-        const recoveryIncomplete = recovery?.subtype !== 'ok' || !recovery?.didRepoMutation || (ticketCycle && (!recovery?.didMcpTaskRead || !recovery?.didMcpTaskUpdate)) || recovery?.mcpErrors?.length
-        if (recoveryIncomplete) {
+        const recoveredResult = combineWorkEvidence(result, recovery)
+        const recoveryMissing = missingWorkEvidence(recoveredResult, ticketCycle)
+        if (recovery?.subtype !== 'ok' || recoveryMissing.length) {
           if (recovery?.subtype === 'blocked' && recovery?.policyBlock) {
             try { await reportPolicyBlock(prompt, activeTaskRef, recovery.policyBlock) }
             catch (e) { log('failed to publish recovery policy blocker: ' + (e?.message || e)) }
           } else {
-            const notice = `I'm blocked after one recovery attempt. Missing required evidence: ${missing.join('; ')}. I've left the ticket open and I'm not claiming completion.`
+            const unresolved = recoveryMissing.length ? recoveryMissing : [`the recovery cycle ended with ${recovery?.subtype || 'an unknown error'}`]
+            const notice = `I'm blocked after one recovery attempt. Missing required evidence: ${unresolved.join('; ')}. I've left the ticket open and I'm not claiming completion.`
             try { await publishBlocker({ prompt, taskRef: activeTaskRef, notice }) }
             catch (e) { log('failed to publish recovery blocker: ' + (e?.message || e)) }
           }
-          if (activeTaskRef) seenTasks.delete(`${activeTaskRef.projectId}:${activeTaskRef.ticketId}`)
-          else {
-            const taskMatch = /ticket\s+#?(\d+).*?project\s+(\d+)/i.exec(prompt)
-            if (taskMatch) seenTasks.delete(`${taskMatch[2]}:${taskMatch[1]}`)
-          }
-          lastTaskSignature = ''
+          releaseTaskForRetry(activeTaskRef, prompt)
           log('WORK_CYCLE_FAILED evidence gate still incomplete after one recovery; ticket retained for retry')
           return
         }
-        completionResult = recovery
+        completionResult = recoveredResult
       }
       if (kind === 'full' && activeTaskRef) {
         try {
           const delivered = await announceTaskCompletion(activeTaskRef, completionResult)
-          if (!delivered) log('completion report deferred for ticket #' + activeTaskRef.ticketId + '; waiting for verified review/done state and PR evidence')
+          if (!delivered) {
+            releaseTaskForRetry(activeTaskRef, prompt)
+            log('completion report deferred for ticket #' + activeTaskRef.ticketId + '; waiting for verified review/done state and PR evidence; ticket remains retryable')
+          }
         } catch (e) {
+          releaseTaskForRetry(activeTaskRef, prompt)
           log('completion report failed for ticket #' + activeTaskRef.ticketId + ': ' + (e?.message || e) + '; retained for reconnect retry')
         }
       }
@@ -1124,9 +1282,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       // De-dupe: the same mention re-delivered (reconnect replay / dup fan-out) must
       // NOT trigger a second reply. Key by message id, or a channel+text signature
       // when the payload carries no id.
-      const dedupeKey = mid != null ? 'id:' + mid : 'sig:' + (cid != null ? cid : '?') + '|' + text.slice(0, 100)
-      if (seenMentions.has(dedupeKey)) { log('agent:mention (dup) — skipped'); return }
-      seenMentions.add(dedupeKey); trimSeen(seenMentions); persistReplay()
+      if (markMentionHandled(msg, cid)) { log('agent:mention (dup) — skipped'); return }
       if (requestTargetsLaterAgent(text, [slug, identifier])) {
         log('agent:mention addressed to a later-mentioned agent — skipped')
         return