openvisio-agent 0.17.5 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.17.5",
+  "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,14 +48,19 @@ 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: Alex is blocked')],
+  ['policy blocker is surfaced to the user', watcher.includes('reportPolicyBlock(prompt, activeTaskRef, result.policyBlock)') && watcher.includes("Action required: I'm blocked")],
   ['blocker routing carries explicit task identity', watcher.includes('taskRefs: []') && watcher.includes('activeTaskRef') && watcher.includes('taskRef: activeTaskRef')],
   ['all runtime blockers have a delivery path', watcher.includes('publishBlocker') && watcher.includes('WORK_CYCLE_BLOCKED') && watcher.includes('COORDINATION_CYCLE_BLOCKED')],
-  ['ticket blocker cannot self-authorize', watcher.includes('ticketNotice = `Alex is paused') && watcher.includes('publishBlocker({ prompt, taskRef, notice, ticketNotice, pause: true })')],
+  ['ticket blocker cannot self-authorize', watcher.includes("ticketNotice = `I'm paused") && watcher.includes('publishBlocker({ prompt, taskRef, notice, ticketNotice, pause: true })')],
+  ['agent messages use first-person voice', watcher.includes('FIRST-PERSON VOICE') && watcher.includes("I'm blocked") && !watcher.includes('Alex is blocked') && !watcher.includes('Alex is paused')],
   ['normative certification gates are documented', spec.includes('## Mandatory certification gates')],
 ]
 for (const [label, ok] of assertions) {

package/src/events.mjs

@@ -46,7 +46,7 @@ export function taskIsAwaitingReview(task, reviewTypeIds = new Set()) {
   return /\b(?:review|test|testing|qa|quality\s+assurance|verification|approval)\b/i.test(state)
 }
 
-export function buildTaskCompletionReport(task, { projectId, agentName, fallbackText = '' } = {}) {
+export function buildTaskCompletionReport(task, { projectId, fallbackText = '' } = {}) {
   if (!task || typeof task !== 'object' || task.id == null) return null
   if (!taskIsCompleted(task) && !taskIsAwaitingReview(task)) return null
 
@@ -59,13 +59,62 @@ export function buildTaskCompletionReport(task, { projectId, agentName, fallback
   const title = String(task.title || 'Untitled task').replace(/\s+/g, ' ').trim().slice(0, 180)
   const status = String(task.type?.name || task.task_type?.name || task.status || task.state || 'review').replace(/\s+/g, ' ').trim()
   const verification = /\bVerification:\s*([^\n]{1,180})/i.exec(evidence)?.[1]?.replace(/\s+/g, ' ').trim().replace(/[.]+$/, '') || ''
-  const who = String(agentName || 'The agent').trim()
   const mention = requester ? `@${requester} ` : ''
-  const content = `${mention}${who} finished ticket #${task.id} “${title}” and moved it to ${status}. PR: ${prUrl}.${verification ? ` Verification: ${verification}.` : ''}`
+  const content = `${mention}I finished ticket #${task.id} “${title}” and moved it to ${status}. PR: ${prUrl}.${verification ? ` Verification: ${verification}.` : ''}`
   const revision = task.updated_at ?? task.updatedAt ?? prUrl
   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)
@@ -91,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
@@ -27,6 +27,7 @@ import { agentStateRequest, buildTaskCompletionReport, codexPolicyBlock, request
 // then walking it back.
 const REPLY_DISCIPLINE = [
   'REPLY DISCIPLINE — read the recent messages FIRST, then decide whether to speak at all:',
+  '  • FIRST-PERSON VOICE. Speak as yourself: use “I”, “I\'m”, and “my”. Never refer to yourself by your agent name or in the third person, and never restate your own name in introductions, acknowledgements, progress, blockers, or results. The app already shows who sent the message. Sound like a warm, accountable teammate, not a status bot.',
   '  • IS IT FOR YOU? Act ONLY on messages addressed to YOU — an @mention of your exact name, a direct question to you, or a reply to something YOU said or did. If a DIFFERENT agent or person was @mentioned or asked to do something, STAY OUT: do not answer for them and do not pick up their task. When it is not yours, posting nothing is the correct move.',
   '  • NO DUPLICATES. Before you post, scan the recent thread/channel for what YOU already said. If you already replied to or acknowledged this exact request, do NOT post again. One acknowledgement per task; one answer per question. While a task is in progress, post again ONLY when you have something genuinely NEW (a result, a link, a real blocker) — never re-post "on it".',
   '  • BE SURE BEFORE YOU SPEAK. Do not claim something is possible, done, or broken until you have actually verified it — call the tool, read the code, check the real state. Never assert then contradict yourself. If you are unsure, verify FIRST, then give ONE clear, final answer instead of thinking out loud across several messages.',
@@ -37,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,
@@ -65,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.',
@@ -76,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')
@@ -89,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')
 
@@ -107,7 +109,7 @@ const CODE_FAST = [
 // missed — TASKS especially.
 const INTRO = [
   'You have just JOINED this OpenVisio workspace (your first connection). Workspace etiquette: introduce yourself so the team knows you are here and reachable.',
-  'Find the most general channel — call poll_inbox (or list channels) and pick the "general"/main one — then post_message there ONCE: give your name, say you are an AI teammate who picks up tasks assigned to you and answers @mentions, and invite people to mention you. 1-2 sentences, warm and professional.',
+  'Find the most general channel — call poll_inbox (or list channels) and pick the "general"/main one — then post_message there ONCE: say in first person that you are here, pick up tasks assigned to you, and answer @mentions. Do not state your name; the app already displays it. Keep it to 1-2 warm, professional sentences.',
   'Post it EXACTLY ONCE, then stop. Do NOT do any other work this cycle.',
 ].join('\n')
 const SWEEP = [
@@ -177,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 }
 }
@@ -228,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'
@@ -273,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'))
@@ -302,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' }) })
     })
   }
@@ -345,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
@@ -362,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
@@ -402,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 })
@@ -432,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
@@ -582,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
@@ -619,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
@@ -651,7 +754,6 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   let lastTaskTriggeredAt = 0
   let lastInboxSignature = ''
   let selfAgentId = null
-  let selfAgentName = slug
   let mcpSessionId = ''
   let mcpRpcId = 0
 
@@ -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.5' } } }, 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') || ''
@@ -734,8 +836,16 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     const taskKey = `${projectId}:${ticketId}`
     const current = toolData(await callMcpTool('get_ticket', { project_id: projectId, ticket_id: ticketId }))
     const ticket = current.ticket ?? current.task ?? current
-    const report = buildTaskCompletionReport(ticket, { projectId, agentName: selfAgentName, fallbackText: result.outputText })
+    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
@@ -814,10 +924,10 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     const command = block?.command || 'the requested external repository action'
     const payload = [block?.commit && `commit ${block.commit}`, block?.branch && `branch ${block.branch}`, block?.remote && `remote ${block.remote}`].filter(Boolean).join(', ')
     const approval = block?.commit && block?.branch
-      ? `Reply with: “I explicitly authorize Alex to push commit ${block.commit} to the exact repository URL for ${block.remote || 'the configured remote'}, on branch ${block.branch}.”`
+      ? `Reply with: “I explicitly authorize you to push commit ${block.commit} to the exact repository URL for ${block.remote || 'the configured remote'}, on branch ${block.branch}.”`
       : 'Explicitly authorize the exact repository URL, commit, and branch in your reply.'
-    const notice = `Action required: Alex is blocked at \`${command}\`${payload ? ` (${payload})` : ''}. Codex requires confirmation before exporting private repository code. ${approval} The ticket is paused until that approval is recorded.`
-    const ticketNotice = `Alex is paused at \`${command}\`${payload ? ` (${payload})` : ''}. Repository push confirmation is required in the project channel; no automatic retry will occur.`
+    const notice = `Action required: I'm blocked at \`${command}\`${payload ? ` (${payload})` : ''}. Codex requires confirmation before exporting private repository code. ${approval} I've paused the ticket until that approval is recorded.`
+    const ticketNotice = `I'm paused at \`${command}\`${payload ? ` (${payload})` : ''}. Repository push confirmation is required in the project channel; I won't retry automatically.`
     return publishBlocker({ prompt, taskRef, notice, ticketNotice, pause: true })
   }
 
@@ -832,11 +942,11 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       const self = agents.find((a) => String(a.identifier || a.slug || '') === identifier)
       if (!self?.id) throw new Error('list_agents did not return this BYO agent')
       selfAgentId = Number(self.id)
-      selfAgentName = String(self.name || selfAgentName)
       const projectsData = toolData(await callMcpTool('list_projects'))
       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),
@@ -880,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)
@@ -916,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'
@@ -953,14 +1110,15 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
         return
       }
       if (kind === 'full' && ['timeout', 'spawn-failed', 'error'].includes(result?.subtype)) {
-        const notice = `Alex is blocked: the coding cycle ended with ${result.subtype}. No completion is being claimed and the ticket remains open for retry.`
+        const notice = `I'm blocked because the coding cycle ended with ${result.subtype}. I'm not claiming completion, and I've left the ticket open for retry.`
         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) {
-        const notice = `Alex is blocked by failed OpenVisio actions: ${result.mcpErrors.join(', ')}. No success is being claimed; the item needs retry or intervention.`
+        const notice = `I'm blocked by failed OpenVisio actions: ${result.mcpErrors.join(', ')}. I'm not claiming success; this needs a retry or intervention.`
         log('COORDINATION_CYCLE_BLOCKED failed MCP calls; publishing blocker')
         try { await publishBlocker({ prompt, taskRef: activeTaskRef, notice }) }
         catch (e) { log('failed to publish coordination blocker: ' + (e?.message || e)) }
@@ -969,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 = `Alex is blocked after one recovery attempt. Missing required evidence: ${missing.join('; ')}. The ticket remains open and no completion is being claimed.`
+            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')
         }
       }
@@ -1065,7 +1222,6 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
         const agentsData = toolData(await callMcpTool('list_agents'))
         const self = (Array.isArray(agentsData.agents) ? agentsData.agents : []).find((a) => String(a.identifier || a.slug || '') === identifier)
         selfAgentId = self?.id != null ? Number(self.id) : null
-        selfAgentName = String(self?.name || selfAgentName)
       }
       const ticketData = toolData(await callMcpTool('get_ticket', { project_id: projectId, ticket_id: ticketId }))
       const ticket = ticketData.ticket ?? ticketData.task ?? ticketData
@@ -1126,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