openvisio-agent 0.16.2 → 0.17.1

package/README.md

@@ -58,6 +58,8 @@ Runs the **autonomy loop** — the agent replies to @mentions and picks up ticke
 
 Backend/BYO watchers reconcile immediately whenever the process starts or the WebSocket connects. A direct MCP session uses the backend's actual tools (`list_agents`, `list_projects`, `list_tasks`, `list_task_types`, and `list_activity`) to recover assigned tasks and recent mention activity missed while offline. The same zero-model check runs every five minutes as a safety net; a model starts only when pending work exists.
 
+Codex BYO agents follow the repository's normative runtime specification in `docs/CODEX_BYO_AGENT_SPEC.md`: one WebSocket identity, independent Sol reply/work lanes, authoritative `get_ticket` verification for assignments, REST-backed in-app activity, persistent replay suppression, and runtime evidence gates before completion. Maintainers must run `npm run certify` before publishing.
+
 Claude uses Haiku for routine coordination and Sonnet for repository work. Codex uses `gpt-5.6-sol` for every cycle, including messages, mentions, triage, board movement, MCP calls, and coding. This intentionally favors reliability and consistent tool use over the cheaper Codex tiers.
 
 ```bash

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "openvisio-agent",
-  "version": "0.16.2",
+  "version": "0.17.1",
   "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team — MCP tools + optional autonomy — in one command.",
   "type": "module",
   "bin": {
     "openvisio-agent": "bin/cli.mjs"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "certify": "node scripts/certify.mjs"
   },
   "files": [
     "bin",
+    "scripts",
     "src",
     "README.md"
   ],

package/scripts/certify.mjs

@@ -0,0 +1,57 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const repo = join(root, '..', '..')
+const failures = []
+
+function run(label, command, args, cwd = root) {
+  const result = spawnSync(command, args, { cwd, encoding: 'utf8', env: { ...process.env, npm_config_cache: '/private/tmp/openvisio-npm-cache' } })
+  if (result.status !== 0) failures.push(`${label}\n${result.stdout || ''}${result.stderr || ''}`)
+  else process.stdout.write(`✓ ${label}\n`)
+}
+
+for (const file of readdirSync(join(root, 'src')).filter((name) => name.endsWith('.mjs'))) run(`syntax ${file}`, process.execPath, ['--check', join(root, 'src', file)])
+for (const file of readdirSync(join(root, 'bin')).filter((name) => name.endsWith('.mjs'))) run(`syntax ${file}`, process.execPath, ['--check', join(root, 'bin', file)])
+run('unit and behavior tests', process.execPath, ['--test'])
+run('frontend typecheck', 'npm', ['run', 'typecheck'], join(repo, 'frontend'))
+run('package dry run', 'npm', ['pack', '--dry-run'])
+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 spec = readFileSync(join(repo, 'docs', 'CODEX_BYO_AGENT_SPEC.md'), 'utf8')
+
+const assertions = [
+  ['task:assigned is handled', watcher.includes("k === 'task:assigned'")],
+  ['task signals are verified with get_ticket', watcher.includes("callMcpTool('get_ticket'")],
+  ['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)')],
+  ['working heartbeat is battery-conscious', watcher.includes("emitLaneStatus(laneName, 'working'), 20_000")],
+  ['activity uses REST endpoint', watcher.includes('agentStateRequest(')],
+  ['websocket client cannot emit legacy agent_status', !websocket.includes('agent_status')],
+  ['frontend consumes thinking event', activityHook.includes("'channel:agent:thinking'")],
+  ['frontend consumes working event', activityHook.includes("'channel:agent:working'")],
+  ['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')],
+  ['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)')],
+  ['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, result.policyBlock)') && watcher.includes('[Agent action required]')],
+  ['normative certification gates are documented', spec.includes('## Mandatory certification gates')],
+]
+for (const [label, ok] of assertions) {
+  if (!ok) failures.push(label)
+  else process.stdout.write(`✓ ${label}\n`)
+}
+
+if (failures.length) {
+  process.stderr.write(`\nCERTIFICATION FAILED (${failures.length})\n\n${failures.join('\n\n')}\n`)
+  process.exit(1)
+}
+process.stdout.write('\nCERTIFICATION PASSED\n')

package/src/events.mjs

@@ -34,6 +34,29 @@ export function taskIsCompleted(task, completedTypeIds = new Set()) {
   return /\b(?:done|complete|completed|closed|cancelled|canceled|archived|resolved)\b/i.test(state)
 }
 
+export function agentStateRequest(backend, channelId, state, apiKey, identifier) {
+  if (!['thinking', 'working', 'typing'].includes(state)) throw new Error('invalid agent state')
+  const id = Number(channelId)
+  if (!Number.isFinite(id)) throw new Error('invalid channel id')
+  return {
+    url: String(backend || '').replace(/\/+$/, '') + `/channels/${id}/agent-state`,
+    init: {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json', 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier },
+      body: JSON.stringify({ state }),
+    },
+  }
+}
+
+export function codexPolicyBlock(value) {
+  const text = String(value || '')
+  if (!/rejected due to unacceptable risk|action was rejected due to unacceptable risk|explicitly approves? the action/i.test(text)) return null
+  const command = /exec_command failed for [`']([^`']+)[`']/.exec(text)?.[1] || ''
+  const reasonTail = text.split(/Reason:\s*/i)[1] || ''
+  const reason = reasonTail.split(/(?:\\n|\n)The agent\b/i)[0].replace(/[\\"') }]+$/, '').trim() || 'Codex requires explicit user approval for this external action.'
+  return { kind: 'authorization-required', command, reason: reason.slice(0, 900) }
+}
+
 // 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

@@ -10,7 +10,7 @@ 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 { requestTargetsLaterAgent, taskAgentId, taskFromEvent, taskIsCompleted } from './events.mjs'
+import { agentStateRequest, codexPolicyBlock, requestTargetsLaterAgent, taskAgentId, taskFromEvent, 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
@@ -247,6 +247,7 @@ export async function runWatch({ flags }) {
   // of REST-polling the frontend relay. Detected by the saved mode / a --ws flag.
   const backendMode = (saved && saved.mode === 'backend') || !!flags.ws
   if (backendMode) {
+    const backend = stripSlash(flags.backend || (saved && saved.backend) || '')
     const wsUrl = stripSlash(flags.ws || (saved && saved.wsUrl) || '')
     const apiKey = String(flags.key || (saved && saved.apiKey) || '')
     const identifier = String(flags.id || (saved && saved.identifier) || '')
@@ -254,7 +255,7 @@ export async function runWatch({ flags }) {
     if (!apiKey || !identifier) fail('No saved backend credentials for that agent.\n  Run `openvisio-agent connect --backend …` first, or pass --key and --id.')
     assertWebSocket(fail)
     if (flags.install) return installService({ slug: slug || 'openvisio', claude, mcpConfig, workdir })
-    return loopBackendWs({ wsUrl, apiKey, identifier, slug: slug || 'openvisio', claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug: !!flags.debug })
+    return loopBackendWs({ backend, wsUrl, apiKey, identifier, slug: slug || 'openvisio', claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug: !!flags.debug })
   }
 
   const host = stripSlash(flags.host || (saved && saved.host) || '')
@@ -326,7 +327,7 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
 // line. That avoids inheriting unrelated user MCP servers while keeping the
 // user's normal Codex authentication. We deliberately never use Codex's dangerous
 // approval/sandbox bypass flag.
-function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, log, debug, model, systemPrompt }) {
+function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, log, debug, model, onTool, systemPrompt }) {
   const bin = onPath('codex') || 'codex'
   const cwd = workdir || OV_DIR
   const tomlString = (v) => JSON.stringify(String(v))
@@ -344,7 +345,8 @@ 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, outputText = '', jsonlBuffer = ''
+      let child = null, done = false, didCode = false, didRepoMutation = false, didMessage = false, outputText = '', jsonlBuffer = '', stderrBuffer = ''
+      let policyBlock = null
       const mcpCalls = new Set(), mcpErrors = new Set()
       let didMcpTaskRead = false, didMcpTaskUpdate = false
       const finish = (o) => {
@@ -353,7 +355,12 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
         clearTimeout(timer)
         const calls = [...mcpCalls]
         log('codex MCP calls: ' + (calls.length ? calls.join(', ') : 'none') + (mcpErrors.size ? ' (failed: ' + [...mcpErrors].join(', ') + ')' : ''))
-        resolve({ ...o, didCode, didRepoMutation, didMessage, didMcpTaskRead, didMcpTaskUpdate, mcpCalls: calls, outputText })
+        resolve({ ...o, didCode, didRepoMutation, didMessage, didMcpTaskRead, didMcpTaskUpdate, mcpCalls: calls, mcpErrors: [...mcpErrors], outputText, policyBlock })
+      }
+      const inspectDiagnostic = (value) => {
+        const s = String(value || '')
+        stderrBuffer = (stderrBuffer + s).slice(-24_000)
+        policyBlock = codexPolicyBlock(stderrBuffer) || policyBlock
       }
       const inspectLine = (line) => {
         const s = line.trim()
@@ -368,6 +375,7 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
           if (item?.type === 'mcp_tool_call') {
             const tool = String(item.tool || item.name || item.method || 'unknown').replace(/^openvisio-team[.:/]/, '')
             mcpCalls.add(tool)
+            try { onTool && onTool(tool) } catch { /* activity is best-effort */ }
             if (/^(?:get_ticket|list_tasks|list_task_types)$/.test(tool)) didMcpTaskRead = true
             if (tool === 'update_ticket') didMcpTaskUpdate = true
             if (/post_message|comment_ticket/.test(tool)) didMessage = true
@@ -385,18 +393,27 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
       try {
         // Always inspect Codex JSONL so a successful process exit cannot be
         // mistaken for completed work. Keep it out of normal logs unless debug.
-        child = spawn(bin, args, { cwd, stdio: ['ignore', 'pipe', 'inherit'] })
+        child = spawn(bin, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] })
         if (child.stdout) child.stdout.on('data', (d) => {
           jsonlBuffer += String(d)
           const lines = jsonlBuffer.split('\n')
           jsonlBuffer = lines.pop() ?? ''
           for (const line of lines) inspectLine(line)
         })
+        if (child.stderr) child.stderr.on('data', (d) => {
+          inspectDiagnostic(d)
+          process.stderr.write(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 = ''; log('codex cycle done (' + (code === 0 ? 'ok' : 'exit ' + code) + ')'); finish({ type: 'result', subtype: code === 0 ? 'ok' : 'error' }) })
+      child.on('close', (code) => {
+        inspectLine(jsonlBuffer); jsonlBuffer = ''; inspectDiagnostic('')
+        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 })
+      })
       child.on('error', (e) => { log('codex error: ' + (e && e.message ? e.message : e)); finish({ type: 'result', subtype: 'error' }) })
     })
   }
@@ -415,7 +432,7 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
   // 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 === 'codex') return createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, log, debug, model, 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
   // model per cycle (cheap for chat, stronger for code) — a change recycles the
@@ -526,19 +543,30 @@ function createCycleRunner({ claude, agent, mcpUrl, mcpHeaders, cfgKey, mcpConfi
 // over the WS; each pushes ONE Claude cycle. Serialized (one cycle at a time) — events
 // arriving while busy are coalesced into a single follow-up cycle so a burst doesn't
 // stack up N sessions. Plus a one-time intro on first connect and a daily catch-up sweep.
-function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug }) {
+function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent, mcpConfig, mcpUrl, workdir, model, chatModel, debug }) {
   const log = (m) => process.stdout.write('[ws ' + new Date().toISOString() + '] ' + m + '\n')
   let handle = null
-  let statusEnabled = true
-  let lastStatusSentAt = 0
-  // Channels the agent is actively working in this cycle — drives the live
-  // agent:status broadcast (thinking → working → typing → done).
-  const statusTargets = new Set()
+  const statusBackoff = new Map()
+  // Activity belongs to a lane. Keeping work/reply targets separate prevents a
+  // quick reply from overwriting or clearing a long coding cycle's status.
+  const laneStatusTargets = { work: new Set(), reply: new Set() }
   const sendStatus = (channelId, state) => {
-    if (!statusEnabled) return
-    try { if (handle) { lastStatusSentAt = Date.now(); handle.sendStatus(channelId, state) } } catch { /* best-effort */ }
+    if (!backend || !['thinking', 'working', 'typing'].includes(state)) return
+    const key = Number(channelId)
+    if ((statusBackoff.get(key) || 0) > Date.now()) return
+    let request
+    try { request = agentStateRequest(backend, key, state, apiKey, identifier) } catch { return }
+    void fetch(request.url, request.init).then(async (res) => {
+      if (res.ok) { statusBackoff.delete(key); return }
+      const body = (await res.text().catch(() => '')).replace(/\s+/g, ' ').slice(0, 160)
+      statusBackoff.set(key, Date.now() + 30_000)
+      log(`agent state HTTP ${res.status}${body ? ': ' + body : ''}; backing off 30s`)
+    }).catch((e) => {
+      statusBackoff.set(key, Date.now() + 30_000)
+      log('agent state request failed: ' + (e?.message || e) + '; backing off 30s')
+    })
   }
-  const emitStatus = (state) => { for (const c of statusTargets) sendStatus(c, state) }
+  const emitLaneStatus = (lane, state) => { for (const c of laneStatusTargets[lane]) sendStatus(c, state) }
   const canCode = !!workdir
   // The Mastra bridge authenticates per-CALL: every openvisio-team tool needs
   // agent_identifier + agent_api_key as arguments. Hand them over up front.
@@ -549,14 +577,12 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   const runnerOptions = {
     claude, agent, mcpUrl, mcpHeaders: { 'x-agent-api-key': apiKey, 'x-agent-identifier': identifier },
     cfgKey: identifier, mcpConfig, workdir, log, debug, model, systemPrompt,
-    // The moment the agent calls post_message it is about to speak → "typing".
-    onTool: (name) => { if (/post_message/.test(name)) emitStatus('typing') },
   }
   // One watcher and one WS subscription, but two independent model lanes. This
   // avoids duplicate event delivery while mentions can be answered during code.
   const runners = {
-    work: createCycleRunner(runnerOptions),
-    reply: createCycleRunner({ ...runnerOptions, cfgKey: identifier + '-reply' }),
+    work: createCycleRunner({ ...runnerOptions, onTool: (name) => { if (/post_message/.test(name)) emitLaneStatus('work', 'typing') } }),
+    reply: createCycleRunner({ ...runnerOptions, cfgKey: identifier + '-reply', onTool: (name) => { if (/post_message/.test(name)) emitLaneStatus('reply', 'typing') } }),
   }
   const fullPrompt = canCode ? CODE_FULL : CYCLE
   const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
@@ -567,8 +593,8 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   let liteModel = chatModel || model
 
   const lanes = {
-    work: { busy: false, queued: null, pending: [] },
-    reply: { busy: false, queued: null, pending: [] },
+    work: { busy: false, queued: null, pending: [], targets: new Set() },
+    reply: { busy: false, queued: null, pending: [], targets: new Set() },
   }
   // Tasks we've already reacted to (keyed task-id:agent — so a REASSIGNMENT to a
   // different agent re-triggers), so a noisy stream of task:updated events doesn't
@@ -582,9 +608,14 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   try { replayState = JSON.parse(readFileSync(replayPath, 'utf8')) } catch { /* first run */ }
   const seenMentions = new Set(Array.isArray(replayState.seenMentions) ? replayState.seenMentions : [])
   const seenActivities = new Set(Array.isArray(replayState.seenActivities) ? replayState.seenActivities : [])
+  // 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 persistReplay = () => {
-    try { writeJson(replayPath, { seenMentions: [...seenMentions], seenActivities: [...seenActivities] }, true) } catch { /* best-effort */ }
+    try { writeJson(replayPath, { seenMentions: [...seenMentions], seenActivities: [...seenActivities], blockedTasks: [...blockedTasks] }, true) } catch { /* best-effort */ }
   }
   // Context lines from the events themselves (the WS payload already carries the
   // channel + message / task), so the agent acts on THEM directly instead of
@@ -594,6 +625,7 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   let lastTaskSignature = ''
   let lastTaskTriggeredAt = 0
   let lastInboxSignature = ''
+  let selfAgentId = null
   let mcpSessionId = ''
   let mcpRpcId = 0
 
@@ -618,7 +650,7 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   }
   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.16.2' } } }, false)
+    const res = await mcpPost({ jsonrpc: '2.0', id: ++mcpRpcId, method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'openvisio-agent', version: '0.17.1' } } }, false)
     if (!res.ok) throw new Error('MCP initialize HTTP ' + res.status)
     await mcpPayload(res)
     mcpSessionId = res.headers.get('mcp-session-id') || ''
@@ -648,6 +680,67 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
     try { return JSON.parse(text) } catch { return { text } }
   }
 
+  const statusChannelCache = new Map()
+  const projectStatusChannel = async (projectId) => {
+    const key = Number(projectId)
+    const cached = statusChannelCache.get(key)
+    if (cached && cached.expiresAt > Date.now()) return cached.channelId
+    try {
+      const data = toolData(await callMcpTool('list_channels', { project_id: key }))
+      const channels = Array.isArray(data.channels) ? data.channels : Array.isArray(data.data?.channels) ? data.data.channels : Array.isArray(data.data) ? data.data : Array.isArray(data.items) ? data.items : []
+      const usable = channels.filter((c) => Number.isFinite(Number(c.id)))
+      const preferred = usable.find((c) => /^(?:general|team|project|dev|development)$/i.test(String(c.name || '').trim())) || usable[0]
+      const channelId = preferred ? Number(preferred.id) : null
+      statusChannelCache.set(key, { channelId, expiresAt: Date.now() + 5 * 60_000 })
+      if (channelId == null) log('no channel available for project ' + key + '; task activity cannot be displayed')
+      return channelId
+    } catch (e) {
+      statusChannelCache.set(key, { channelId: null, expiresAt: Date.now() + 30_000 })
+      log('cannot resolve activity channel for project ' + key + ': ' + (e?.message || e))
+      return null
+    }
+  }
+
+  const reportPolicyBlock = async (prompt, block) => {
+    const taskMatch = /ticket\s+#?(\d+).*?project\s+(\d+)/i.exec(prompt)
+    const channelMatch = /channel\s+(\d+)/i.exec(prompt)
+    const parentMatch = /(?:parent_id|thread)\s+(\d+)/i.exec(prompt)
+    const command = block?.command || 'the requested external repository action'
+    const notice = `Action required: Codex reached ${command.includes('git push') ? 'the branch push step' : 'an external action'}, but the safety layer blocked \`${command}\` because private repository code cannot be sent to a remote without explicit approval for the destination and payload. Please explicitly authorize this exact push (repository remote + branch). Alex has paused the ticket and will not retry it automatically.`
+
+    if (channelMatch) {
+      await callMcpTool('post_message', {
+        channel_id: Number(channelMatch[1]),
+        ...(parentMatch ? { parent_id: Number(parentMatch[1]) } : {}),
+        content: notice,
+      })
+      return
+    }
+    if (!taskMatch) { log('policy blocker has no source channel or ticket to update'); return }
+
+    const ticketId = Number(taskMatch[1])
+    const projectId = Number(taskMatch[2])
+    const key = `${projectId}:${ticketId}`
+    blockedTasks.add(key)
+    persistReplay()
+    try {
+      await callMcpTool('comment_ticket', { project_id: projectId, ticket_id: ticketId, text: notice })
+      return
+    } catch (e) {
+      log('comment_ticket unavailable for policy blocker; recording it on ticket #' + ticketId)
+    }
+    const current = toolData(await callMcpTool('get_ticket', { project_id: projectId, ticket_id: ticketId }))
+    const ticket = current.ticket ?? current.task ?? current
+    const description = String(ticket.description || '')
+    if (!description.includes('[Agent action required]')) {
+      await callMcpTool('update_ticket', {
+        project_id: projectId,
+        ticket_id: ticketId,
+        description: `${description}${description ? '\n\n' : ''}[Agent action required]\n${notice}`,
+      })
+    }
+  }
+
   // Reconcile everything that may have arrived while disconnected. This spends no
   // model tokens unless the tools actually report pending work.
   const reconcileBacklog = async () => {
@@ -658,6 +751,7 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
       const agents = Array.isArray(agentsData.agents) ? agentsData.agents : []
       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)
       const projectsData = toolData(await callMcpTool('list_projects'))
       const projects = Array.isArray(projectsData.projects) ? projectsData.projects : []
       const assigned = []
@@ -673,7 +767,15 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
           const taskAgentId = Number(task.agent_id ?? task.agentId ?? task.agent?.id)
           const taskIdent = String(task.agent?.identifier ?? task.agent?.slug ?? '')
           if (!taskIsCompleted(task, doneIds) && (taskAgentId === Number(self.id) || taskIdent === identifier)) {
-            assigned.push({ id: task.id, projectId: project.id, project: project.name, title: task.title, priority: task.priority, typeId: task.type_id ?? task.typeId })
+            const taskKey = `${project.id}:${task.id}`
+            if (blockedTasks.has(taskKey)) {
+              const approvalText = [task.title, task.description].filter(Boolean).join(' ')
+              if (/\b(?:i\s+)?(?:explicitly\s+)?(?:approve|authorize)\b[\s\S]{0,240}\b(?:git\s+push|push(?:ing)?\s+(?:the\s+)?(?:branch|code)|github|remote)\b/i.test(approvalText)) {
+                blockedTasks.delete(taskKey); seenTasks.delete(taskKey); persistReplay()
+                log('backlog ticket #' + task.id + ' now contains explicit push authorization — resuming')
+              } else continue
+            }
+            assigned.push({ id: task.id, projectId: project.id, project: project.name, title: task.title, priority: task.priority, typeId: task.type_id ?? task.typeId, updatedAt: task.updated_at ?? task.updatedAt })
           }
         }
         const activities = Array.isArray(activityData.activities) ? activityData.activities : Array.isArray(activityData.activity) ? activityData.activity : []
@@ -696,8 +798,11 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
         if (signature !== lastTaskSignature || retryDue) {
           lastTaskSignature = signature
           lastTaskTriggeredAt = Date.now()
-          log('backlog reconciliation found ' + assigned.length + ' assigned task(s) -> coding cycle')
-          void drain('full', `Backlog reconciliation verified these open tasks are assigned to YOU: ${JSON.stringify(assigned)}. Start with the highest-priority/oldest one immediately. This is backlog-only work with NO source message or requester thread: do NOT post_message and do not announce progress or completion in any channel. Use get_ticket if more detail is needed, move it to the active column with update_ticket, complete the repository work, verify it, open the PR, then update the ticket with the evidence and move it to done when appropriate.`)
+          const priorityRank = { critical: 0, high: 1, medium: 2, low: 3 }
+          const next = [...assigned].sort((a, b) => (priorityRank[a.priority] ?? 9) - (priorityRank[b.priority] ?? 9) || String(a.updatedAt || '').localeCompare(String(b.updatedAt || '')))[0]
+          log('backlog reconciliation found ' + assigned.length + ' assigned task(s); queueing only ticket #' + next.id)
+          const activityChannel = await projectStatusChannel(next.projectId)
+          void drain('full', `Backlog reconciliation verified this open ticket is assigned to YOU: ${JSON.stringify(next)}. Process this ONE ticket only. This is backlog-only work with NO source message or requester thread: do NOT post_message and do not announce progress or completion in any channel. Call get_ticket, use list_task_types and update_ticket to move it active, complete and verify the work, open the PR, then update the ticket with evidence and move it to done when appropriate.`, activityChannel == null ? [] : [activityChannel])
         }
       }
       const inboxSignature = JSON.stringify(mentionActivity.slice(-20)).slice(0, 4000)
@@ -716,13 +821,17 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
   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
 
-  async function drain(kind, context) {
+  async function drain(kind, context, targetChannels = []) {
     const laneName = kind === 'full' ? 'work' : 'reply'
     const lane = lanes[laneName]
     if (context) lane.pending.push(context)
+    for (const channelId of targetChannels) if (Number.isFinite(Number(channelId))) lane.targets.add(Number(channelId))
     if (lane.busy) { lane.queued = (RANK[kind] ?? 0) >= (RANK[lane.queued] ?? 0) ? kind : lane.queued; log(laneName + ' lane busy — queued a ' + kind + ' follow-up cycle'); return }
     lane.busy = true
     const ctx = lane.pending.splice(0)
+    const targets = [...lane.targets]
+    lane.targets.clear()
+    laneStatusTargets[laneName] = new Set(targets)
     // credNote + charter live in the cached system prompt now — the per-cycle
     // message is just the event context + the small base instruction.
     const prompt = (ctx.length ? ctx.join('\n') + '\n\n' : '') + baseFor(kind)
@@ -732,24 +841,38 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
     log('running ' + kind + ' cycle…' + (ctx.length ? ' (' + ctx.length + ' event' + (ctx.length === 1 ? '' : 's') + ')' : '') + (useModel ? ' [' + useModel + ']' : ''))
     // Live status: "working" now + a heartbeat so the UI (and its TTL) stays lit
     // through a long cycle; onTool flips it to "typing" when post_message fires.
-    const targets = [...statusTargets]
-    emitStatus('working')
-    const heartbeat = targets.length ? setInterval(() => emitStatus('working'), 9000) : null
+    emitLaneStatus(laneName, 'working')
+    // Backend activity TTL is refreshed well before expiry, but only once every
+    // 20 seconds so long coding runs do not create needless network/battery load.
+    const heartbeat = targets.length ? setInterval(() => emitLaneStatus(laneName, 'working'), 20_000) : null
     try {
       const result = await runners[laneName].runCycle(prompt, useModel)
-      // A zero exit is not proof of work. Assigned-ticket cycles must both use
-      // the task MCP and leave repository evidence. A simple `ls` no longer
-      // counts as completion. Do not retry a verified real blocker.
-      const legitimateNoWork = /\b(?:no (?:open |assigned |pending )?tasks?|not assigned to (?:me|you)|assigned to (?:another|someone else)|blocked|cannot|can't|missing|need access|permission|unclear)\b/i.test(result?.outputText || '')
-      const incomplete = !result?.didRepoMutation || !result?.didMcpTaskRead || !result?.didMcpTaskUpdate
-      if (agent === 'codex' && kind === 'full' && result?.subtype === 'ok' && incomplete && !legitimateNoWork) {
-        const missing = [!result.didMcpTaskRead && 'read the ticket through get_ticket/list_tasks', !result.didRepoMutation && 'perform and verify the repository change', !result.didMcpTaskUpdate && 'update the ticket through update_ticket'].filter(Boolean)
+      if (agent === 'codex' && result?.subtype === 'blocked' && result?.policyBlock) {
+        log('WORK_CYCLE_BLOCKED authorization required; pausing this ticket and publishing an action-required notice')
+        try { await reportPolicyBlock(prompt, result.policyBlock) }
+        catch (e) { log('failed to publish policy blocker: ' + (e?.message || e)) }
+        return
+      }
+      // Model prose never proves success or a blocker. Full cycles must produce
+      // runtime-observed ticket reads, repository evidence, and ticket updates.
+      const ticketCycle = /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(', '))
-        await runners.work.runCycle(`The assigned task is NOT complete. Missing evidence: ${missing.join('; ')}. Do not post another acknowledgement or plan. Resume now. First use get_ticket/list_tasks and list_task_types, then do the repository work, verify it, commit and push an agent/* branch, open the PR, call update_ticket with the correct board column, and post exactly one result update with evidence. If a real blocker appears, report it once.`, codeModel)
+        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 taskMatch = /ticket\s+#?(\d+).*?project\s+(\d+)/i.exec(prompt)
+          if (taskMatch) seenTasks.delete(`${taskMatch[2]}:${taskMatch[1]}`)
+          lastTaskSignature = ''
+          log('WORK_CYCLE_FAILED evidence gate still incomplete after one recovery; ticket retained for retry')
+        }
       }
     } finally {
       if (heartbeat) clearInterval(heartbeat)
-      for (const c of targets) { sendStatus(c, 'done'); statusTargets.delete(c) }
+      laneStatusTargets[laneName].clear()
       lane.busy = false
       if (lane.queued || lane.pending.length) { const next = lane.queued || (laneName === 'work' ? 'full' : 'fast'); lane.queued = null; void drain(next) }
     }
@@ -798,33 +921,53 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
     try { writeJson(configPath(slug), { ...(readConfig(slug) || {}), model: codeModel, chatModel: liteModel !== codeModel ? liteModel : '' }, true) } catch { /* best-effort */ }
   }
 
+  const handleTaskSignal = async (kind, raw) => {
+    const hinted = taskFromEvent(raw)
+    const ticketId = hinted && (hinted.id ?? hinted.task_id ?? hinted.taskId)
+    const projectId = hinted && (hinted.project_id ?? hinted.projectId ?? raw.project_id ?? raw.projectId)
+    if (ticketId == null || projectId == null) { log(kind + ' missing ticket/project identity — ignored'); return }
+    try {
+      if (selfAgentId == null) {
+        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
+      }
+      const ticketData = toolData(await callMcpTool('get_ticket', { project_id: projectId, ticket_id: ticketId }))
+      const ticket = ticketData.ticket ?? ticketData.task ?? ticketData
+      const assignedId = Number(taskAgentId(ticket) ?? ticket.agent?.id ?? ticket.assigned_agent?.id)
+      const assignedIdentifier = String(ticket.agent?.identifier ?? ticket.assigned_agent?.identifier ?? '')
+      const belongsToSelf = (selfAgentId != null && assignedId === selfAgentId) || assignedIdentifier === identifier
+      const key = `${projectId}:${ticketId}`
+      if (!belongsToSelf) { blockedTasks.delete(key); persistReplay(); seenTasks.delete(key); log(kind + ' ticket #' + ticketId + ' is not assigned to this agent — ignored'); return }
+      if (taskIsCompleted(ticket)) { blockedTasks.delete(key); persistReplay(); seenTasks.add(key); log(kind + ' ticket #' + ticketId + ' is already complete — ignored'); return }
+      if (blockedTasks.has(key)) {
+        const approvalText = [ticket.title, ticket.description].filter(Boolean).join(' ')
+        if (/\b(?:i\s+)?(?:explicitly\s+)?(?:approve|authorize)\b[\s\S]{0,240}\b(?:git\s+push|push(?:ing)?\s+(?:the\s+)?(?:branch|code)|github|remote)\b/i.test(approvalText)) {
+          blockedTasks.delete(key); seenTasks.delete(key); persistReplay()
+          log(kind + ' ticket #' + ticketId + ' contains explicit push authorization — resuming')
+        } else {
+          log(kind + ' ticket #' + ticketId + ' is paused for explicit repository push authorization — ignored')
+          return
+        }
+      }
+      if (seenTasks.has(key)) { log(kind + ' ticket #' + ticketId + ' already queued/active — ignored'); return }
+      seenTasks.add(key); trimSeen(seenTasks)
+      const title = String(ticket.title || hinted.title || '')
+      const taskText = [title, ticket.description, ticket.type, ticket.kind].filter(Boolean).join(' ')
+      const cycleKind = canCode && !coordinationOnly(taskText) ? 'full' : 'coord'
+      log(kind + ' verified ticket #' + ticketId + ' “' + title + '” -> ' + cycleKind + ' lane')
+      const activityChannel = await projectStatusChannel(projectId)
+      if (activityChannel != null) sendStatus(activityChannel, 'thinking')
+      void drain(cycleKind, `Authoritative get_ticket verification confirms ticket #${ticketId} in project ${projectId} is open and assigned to YOU: ${JSON.stringify({ id: ticketId, projectId, title, description: ticket.description, priority: ticket.priority, typeId: ticket.type_id ?? ticket.typeId })}. This assignment has no source channel: do not post_message. Use list_task_types and update_ticket to move it active, complete and verify the work, open the PR when applicable, then update/move the ticket with evidence. Never announce it in a channel.`, activityChannel == null ? [] : [activityChannel])
+    } catch (e) {
+      log(kind + ' ticket verification failed for #' + ticketId + ': ' + (e?.message || e))
+    }
+  }
+
   function onEvent(k, d) {
     const raw = d && typeof d === 'object' ? d : {}
-    // The backend has NO `task:assigned` event — a task assigned to an agent arrives
-    // as `task:created` (assigned on create) or `task:updated` (assignee changed),
-    // fanned out org-wide. Catch both, keep only agent-assigned tasks, and let the
-    // cycle confirm ownership via get_marching_orders before acting.
-    if (k === 'task:created' || k === 'task:updated') {
-      const envelope = raw.data && typeof raw.data === 'object' ? raw.data : raw
-      const t = envelope.task && typeof envelope.task === 'object' ? envelope.task : envelope
-      const ag = (t.agent && typeof t.agent === 'object') ? t.agent : (t.assigned_agent && typeof t.assigned_agent === 'object') ? t.assigned_agent : null
-      const agentId = t.agent_id ?? t.agentId ?? t.assigned_agent_id ?? t.assignedAgentId ?? t.assignee_agent_id ?? t.assigneeAgentId ?? ag?.id ?? ag?.agent_id ?? null
-      if (agentId == null) return // not assigned to an agent — ignore
-      // If the payload carries the agent's identifier, filter precisely to US and skip
-      // other agents' tasks entirely; otherwise let get_marching_orders confirm.
-      const agIdent = ag && (ag.identifier || ag.slug) ? String(ag.identifier || ag.slug) : null
-      if (agIdent != null && agIdent !== identifier) return
-      const key = `${t.id}:${agentId}`
-      if (t.id != null && seenTasks.has(key)) return
-      if (t.id != null) { seenTasks.add(key); if (seenTasks.size > 500) seenTasks.clear() }
-      log('task ' + k.slice(5) + ' #' + (t.id != null ? t.id : '?') + ' (agent ' + agentId + ') “' + (t.title || '') + '”')
-      const desc = t.description ? ' — ' + String(t.description).replace(/\s+/g, ' ').slice(0, 400) : ''
-      const taskText = [t.title, t.description, t.type, t.kind, Array.isArray(t.labels) ? t.labels.join(' ') : t.labels].filter(Boolean).join(' ')
-      // An assigned task is presumed to require execution. Only explicit board or
-      // messaging work stays on the cheap lane; vague verbs such as "create",
-      // "make", or "improve" must not strand a coding task in coordination.
-      const kind = canCode && !coordinationOnly(taskText) ? 'full' : 'coord'
-      void drain(kind, `A task was just ${k === 'task:created' ? 'created and assigned' : 'assigned'} to an agent in this workspace: task #${t.id != null ? t.id : '?'}: "${t.title || ''}"${desc} (agent_id ${agentId}). Call get_marching_orders to confirm it is assigned to YOU. If it is yours, acknowledge it once, complete it with the tools appropriate to this ${kind === 'full' ? 'coding' : 'coordination'} lane, move the ticket when appropriate, and report the verified result. If it is not yours, do nothing and stop.`)
+    if (k === 'task:assigned' || k === 'task:updated') {
+      void handleTaskSignal(k, raw)
     } else if (k === 'agent:mention') {
       const cid = raw.channel_id != null ? raw.channel_id : (raw.channelId != null ? raw.channelId : null)
       const msg = raw.message && typeof raw.message === 'object' ? raw.message : {}
@@ -868,9 +1011,9 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
         return
       }
       log('agent:mention in channel ' + (cid != null ? cid : '?') + (threadRoot != null ? ' (thread ' + threadRoot + ')' : ''))
-      // Light up the live status the instant we pick this up (thinking → the cycle
-      // takes it to working → typing → done).
-      if (cid != null) { statusTargets.add(cid); sendStatus(cid, 'thinking') }
+      // Light up the live status the instant we pick this up; drain owns the
+      // subsequent working/typing heartbeat for its lane.
+      if (cid != null) sendStatus(cid, 'thinking')
       const codingMention = canCode && needsCode(text)
       const ctx = cid != null
         ? `You were @mentioned in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". This mention is FOR YOU. ${codingMention ? 'This is repository work: complete the coding flow first, then send' : 'Send'} EXACTLY ONE reply with post_message: arguments: channel_id ${cid}${threadRoot != null ? `, parent_id ${threadRoot} (reply IN THAT THREAD, do not start a new top-level message)` : ''}, plus agent_identifier + agent_api_key from the AUTH line above, and a 1-3 sentence reply. Compose the whole answer, then post it ONCE. Do not post a first reply and then a revised version. FIRST read the recent messages in this thread: if you already answered this, or another agent was the one addressed, do NOT post at all. Be sure of your answer before sending.${who ? ` To @mention them back, write their EXACT full name "@${who}". A mention only links when the name matches exactly.` : ''} You ALREADY have the message here. Do not poll_inbox, and after your single reply, STOP.`
@@ -879,19 +1022,12 @@ function loopBackendWs({ wsUrl, apiKey, identifier, slug, claude, agent, mcpConf
         const ack = cid != null
           ? `You were asked for repository work in channel ${cid}${threadRoot != null ? `, thread ${threadRoot}` : ''}. The dedicated work lane has accepted it. Post exactly one short reply with post_message in that same thread saying you have picked it up and will return there with the verified result. Include agent_identifier + agent_api_key. Do not inspect or edit code in this reply lane.`
           : undefined
-        void drain('coord', ack)
-        void drain('full', ctx)
-      } else void drain('fast', ctx)
+        void drain('coord', ack, cid == null ? [] : [cid])
+        void drain('full', ctx, cid == null ? [] : [cid])
+      } else void drain('fast', ctx, cid == null ? [] : [cid])
     } else if (k === 'error') {
       const detail = raw && (raw.message || raw.error || raw.reason || raw.code || raw.d?.message || raw.d?.error)
-      // Older backend stages reject agent_status. Stop its heartbeat after the
-      // first immediate rejection instead of producing an error every nine seconds.
-      if (statusEnabled && lastStatusSentAt && Date.now() - lastStatusSentAt < 3000) {
-        statusEnabled = false
-        log('live agent status unsupported by this backend; disabling status heartbeat' + (detail ? ': ' + String(detail).slice(0, 160) : ''))
-      } else {
-        log('error event: ' + (detail ? String(detail) : JSON.stringify(raw)).slice(0, 220))
-      }
+      log('error event: ' + (detail ? String(detail) : JSON.stringify(raw)).slice(0, 220))
     } else {
       log('event ' + k)
     }

package/src/ws.mjs

@@ -101,12 +101,6 @@ export function connectAgentWs({ wsUrl, apiKey, identifier, onEvent, onConnect,
   const api = {
     /** Fire-and-forget send (no-op if the socket isn't open). */
     send(obj) { try { if (ws && ws.readyState === 1) ws.send(JSON.stringify(obj)) } catch { /* closing */ } },
-    /** Show the agent as typing in a channel (docs/WEBSOCKET.md `{type:'typing'}`). */
-    sendTyping(channelId) { api.send({ type: 'typing', channel_id: channelId }) },
-    /** Broadcast a richer live activity state for the agent in a channel — the
-     *  backend fans it out as `agent:status` (see docs/AGENT_STATUS.md). state is
-     *  one of thinking | working | typing | done. */
-    sendStatus(channelId, state, detail) { api.send({ type: 'agent_status', channel_id: channelId, state, ...(detail ? { detail: String(detail).slice(0, 120) } : {}) }) },
     close() {
       closed = true
       clearKeepalive()