openvisio-agent 0.18.0 → 0.18.1

package/README.md

@@ -69,7 +69,16 @@ openvisio-agent watch --name ada --workdir ~/repo  # allow REAL work on a git br
 openvisio-agent stop --name ada                  # stop service + every ada watcher
 ```
 
-With `--workdir`, the agent gets file + Bash tools scoped to that repo and works on a branch. Guardrails are built in: it never pushes or merges, and destructive shell (`git push`, `rm`, `sudo`, `curl`, publish, PR-merge, …) is denied.
+With `--workdir`, the agent gets file + shell tools scoped to the workspace and works on an `agent/*` branch. For a codebase linked to OpenVisio, Codex first uses the authenticated MCP branch, commit, and pull-request tools. That creates the PR through the existing integration and avoids a local `git push`.
+
+When those linked-codebase tools are unavailable, a pull request still requires exporting the local branch to the private Git remote. The constrained fallback uses an explicit, one-time authorization per repository:
+
+```bash
+cd /path/to/private-repo
+openvisio-agent authorize-pr-push
+```
+
+That command installs a narrow Codex rule for `openvisio-agent push-pr-branch` and records the repository's exact root and `origin`. The helper accepts no arguments and can only push `HEAD` to the same `agent/*` branch on that authorized origin. It disables repository hooks and rejects main/master, other branch namespaces, changed remotes, force pushes, local/file remotes, and credential-bearing URLs. Revoke it from the repository with `openvisio-agent revoke-pr-push`.
 
 `--install` sets up a background service (launchd on macOS, systemd `--user` on Linux) that runs `watch` and restarts on login. Logs go to `~/.openvisio/<agent>.log` (macOS) or `journalctl --user -u openvisio-<agent>` (Linux).
 
@@ -79,7 +88,7 @@ Do not chase auto-changing watcher PIDs. `openvisio-agent stop --name <agent>` u
 
 - **No opaque script.** You run a named, versioned npm package you can read here and on [npmjs.com](https://www.npmjs.com/package/openvisio-agent).
 - **Single-use code.** The `ovs_` code is exchanged once for a key; a leaked code is already spent.
-- **Least privilege.** Chat mode exposes only the `openvisio-team` MCP tools. Coding mode is opt-in per repo, branch-only, with a shell denylist.
+- **Least privilege.** Chat mode exposes only the `openvisio-team` MCP tools. Codex private-repository pushes require an explicit per-repository opt-in and go through a no-argument `agent/*`-only helper; merges and protected-branch pushes remain unavailable.
 - **Local secrets.** Your agent key lives in `~/.openvisio/` with `600` permissions — never printed, never committed.
 
 ## Requirements

package/bin/cli.mjs

@@ -15,6 +15,7 @@ import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { parseFlags, slugify, stripSlash, exchangeToken, ensureClaude, ensureCodex, writeJson, mcpConfigPath, configPath, chmodSafe, onPath, OV_DIR, fail, ok, info } from '../src/lib.mjs'
 import { runWatch, installService, stopWatchers } from '../src/watch.mjs'
+import { authorizePrPush, pushPrBranch, revokePrPush } from '../src/pr-push.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const VERSION = (() => { try { return JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version } catch { return '0.0.0' } })()
@@ -28,6 +29,9 @@ Usage:
   openvisio-agent connect --backend <url> --key <api-key> --id <identifier> [--name "<agent>"] [--ws <wss-url>] [--mcp-url <url>] [--agent claude|codex|opencode]
   openvisio-agent watch   --name <agent> [--install] [--workspace <dir>] [--chat-only] [--model <m>] [--chat-model <m>] [--debug]
   openvisio-agent stop    --name <agent>
+  openvisio-agent authorize-pr-push [--repo <dir>]
+  openvisio-agent push-pr-branch
+  openvisio-agent revoke-pr-push [--repo <dir>]
   openvisio-agent --help | --version
 
 connect
@@ -78,6 +82,19 @@ stop
   remaining watcher with that exact --name and clears its stale lock. Use this
   instead of killing changing PIDs: openvisio-agent stop --name Alex
 
+authorize-pr-push
+  One-time, explicit authorization for the current private repository. Installs a
+  narrow Codex command rule and records the exact repository root + origin. The
+  permitted helper can only push the current agent/* branch and cannot force-push,
+  choose another remote/ref, push a protected branch, or merge.
+
+push-pr-branch
+  Pushes HEAD to the same agent/* branch on an origin previously authorized with
+  authorize-pr-push. Intended for Codex work cycles; accepts no arguments.
+
+revoke-pr-push
+  Removes the current repository from the helper's authorization list.
+
 Docs: https://www.npmjs.com/package/openvisio-agent`
 
 // Register the `openvisio-team` MCP at USER (global) scope so it's available in
@@ -291,6 +308,29 @@ async function main() {
     if (!name) fail('Missing agent name.\n  Usage: openvisio-agent stop --name <agent>')
     return stopWatchers({ slug: slugify(name) })
   }
+  if (cmd === 'authorize-pr-push') {
+    const cwd = String(rest.flags.repo || rest.positional[0] || process.cwd())
+    const result = authorizePrPush({ cwd })
+    ok('Authorized constrained PR-branch pushes for this repository.')
+    info(`Repository: ${result.root}`)
+    info(`Origin: ${result.remote}`)
+    info('Codex can now run: openvisio-agent push-pr-branch')
+    info('This does not allow pushes to main/master, force pushes, arbitrary remotes, or merges.')
+    return
+  }
+  if (cmd === 'push-pr-branch') {
+    if (rest.positional.length || Object.keys(rest.flags).length) fail('push-pr-branch accepts no arguments. It uses the current repository, origin, and agent/* branch.')
+    const result = pushPrBranch()
+    ok(`Pushed ${result.branch} to its matching origin branch.`)
+    return
+  }
+  if (cmd === 'revoke-pr-push') {
+    const cwd = String(rest.flags.repo || rest.positional[0] || process.cwd())
+    const result = revokePrPush({ cwd })
+    if (result.revoked) ok(`Revoked constrained PR pushes for ${result.root}.`)
+    else info(`No PR-push authorization was stored for ${result.root}.`)
+    return
+  }
   fail(`Unknown command "${cmd}".\n\n${HELP}`)
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openvisio-agent",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "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

@@ -21,6 +21,10 @@ 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 events = readFileSync(join(root, 'src', 'events.mjs'), 'utf8')
+const memory = readFileSync(join(root, 'src', 'memory.mjs'), 'utf8')
+const prPush = readFileSync(join(root, 'src', 'pr-push.mjs'), 'utf8')
+const cli = readFileSync(join(root, 'bin', 'cli.mjs'), 'utf8')
 const websocket = readFileSync(join(root, 'src', 'ws.mjs'), 'utf8')
 const activityHook = readFileSync(join(repo, 'frontend', 'hooks', 'useAgentActivity.ts'), 'utf8')
 const taskHook = readFileSync(join(repo, 'frontend', 'hooks', 'useBackendTasks.ts'), 'utf8')
@@ -31,13 +35,19 @@ const assertions = [
   ['task signals are verified with get_ticket', watcher.includes("callMcpTool('get_ticket'")],
   ['review and testing handoffs do not restart work', watcher.includes('taskIsAwaitingReview(task, reviewIds)') && watcher.includes('taskIsAwaitingReview(ticket)')],
   ['review handoff releases the task key for future rework', watcher.includes('seenTasks.delete(taskKey)') && watcher.includes('seenTasks.delete(key)')],
-  ['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 })")],
+  ['assigned coding completion is posted by the watcher', watcher.includes('announceTaskCompletion') && watcher.includes('postMessageOnce({ key: `completion:${report.key}`')],
   ['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')],
+  ['reconciled mentions reuse the guarded websocket delivery path', watcher.includes("onEvent('agent:mention'") && watcher.includes('_mentionAlreadyMarked: true')],
+  ['rendered backend replies are checked before every guarded thread post', watcher.includes("callMcpTool('list_message_thread'") && watcher.includes('renderedAgentMessages(live') && watcher.includes('same-content-rendered')],
+  ['Codex cannot race the watcher with post_message', watcher.includes("disabledMcpTools: ['post_message']") && watcher.includes('disabled_tools = [')],
+  ['reply delivery keys survive reconnects', watcher.includes('deliveredReplies: [...deliveredReplies]') && watcher.includes('deliveredReplies.has(deliveryKey)')],
+  ['guarded replies stay independent while a lane is busy', watcher.includes('lane.deferred.push') && watcher.includes('lane.deferred.shift()')],
+  ['BYO memory uses real ticket and thread identities', watcher.includes('createByoMemoryGraph') && watcher.includes('memory.context(memoryRefs)') && memory.includes('sameRef(r.projectId, refs.projectId)') && memory.includes('sameRef(r.threadId, refs.threadId)')],
   ['two internal lanes exist', watcher.includes('work: createCycleRunner') && watcher.includes('reply: createCycleRunner')],
   ['work and reply activity targets are isolated', watcher.includes("laneStatusTargets = { work: new Set(), reply: new Set() }") && watcher.includes("emitLaneStatus('work', 'typing')") && watcher.includes("emitLaneStatus('reply', 'typing')")],
   ['assigned task activity resolves a project channel', watcher.includes("callMcpTool('list_channels'") && watcher.includes('projectStatusChannel(projectId)')],
@@ -56,6 +66,11 @@ const assertions = [
   ['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')],
+  ['repository push authorization automatically resumes the paused ticket', watcher.includes('blockedTaskRepos: [...blockedTaskRepos]') && watcher.includes('repositoryHasPrPushAuthorization')],
+  ['Codex prefers linked-codebase MCP PR delivery', watcher.includes('CODEX PR DELIVERY') && watcher.includes('create_codebase_branch/create_codebase_commit/create_pull_request') && events.includes('const codebaseMutation')],
+  ['private PR pushes use an explicit constrained helper', cli.includes("cmd === 'authorize-pr-push'") && cli.includes("cmd === 'push-pr-branch'") && prPush.includes("'push', '-u', 'origin', destination")],
+  ['PR push helper rejects protected/alternate/force targets by construction', prPush.includes("/^agent\\/") && prPush.includes('entry?.root === root && entry?.remote === remote') && prPush.includes('accepts no force, remote, or ref args')],
+  ['Codex recognizes helper authorization as a blocker', events.includes('OPENVISIO_PR_PUSH_AUTH_REQUIRED') && watcher.includes("block?.kind === 'pr-push-authorization-required'")],
   ['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')],

package/src/events.mjs

@@ -95,8 +95,9 @@ export function opencodeEventEvidence(event) {
   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 knownMcp = /^(?:get_ticket|list_tasks|list_task_types|update_ticket|post_message|comment_ticket|react_message|list_projects|list_agents|list_activity|list_codebases|create_codebase_branch|create_codebase_commit|write_codebase_file|create_pull_request)$/
   const mcpTool = (prefixed?.[1] ? prefixed[1].replace(/[-.]/g, '_') : (knownMcp.test(bareTool) ? bareTool : '')).toLowerCase()
+  const codebaseMutation = /^(?:create_codebase_branch|create_codebase_commit|write_codebase_file|create_pull_request)$/.test(mcpTool)
   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)
@@ -106,8 +107,8 @@ export function opencodeEventEvidence(event) {
     ...(mcpTool ? { mcpTool } : {}),
     failed,
     completed,
-    didCode: completed && (mutationTool || bashTool),
-    didRepoMutation: completed && (mutationTool || (bashTool && commandMutation)),
+    didCode: completed && (mutationTool || bashTool || codebaseMutation),
+    didRepoMutation: completed && (mutationTool || codebaseMutation || (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),
@@ -131,6 +132,16 @@ export function agentStateRequest(backend, channelId, state, apiKey, identifier)
 
 export function codexPolicyBlock(value) {
   const text = String(value || '')
+  if (/OPENVISIO_PR_PUSH_AUTH_REQUIRED/i.test(text)) {
+    const root = /From\s+([^\n,]+),\s*run:\s*openvisio-agent authorize-pr-push/i.exec(text)?.[1]?.trim() || ''
+    return {
+      kind: 'pr-push-authorization-required',
+      command: 'openvisio-agent push-pr-branch',
+      reason: 'The repository has not received the one-time constrained PR-branch authorization.',
+      root,
+      setupCommand: 'openvisio-agent authorize-pr-push',
+    }
+  }
   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] || ''
@@ -172,6 +183,54 @@ export function mentionDedupeKeys(message, channelId) {
   }
 }
 
+export function normalizeRenderedMessageText(value) {
+  return String(value || '').replace(/\s+/g, ' ').trim().toLowerCase()
+}
+
+// Extract only messages visibly authored by this agent from the backend's live
+// thread response. REST and WebSocket payloads use several sender shapes, so this
+// mirrors the frontend normalizer instead of trusting one field name.
+export function renderedAgentMessages(value, identity = {}) {
+  const rows = []
+  const seen = new Set()
+  const visit = (node, depth = 0) => {
+    if (depth > 6 || node == null) return
+    if (Array.isArray(node)) { for (const item of node) visit(item, depth + 1); return }
+    if (typeof node !== 'object') return
+    const row = node
+    const content = row.content ?? row.body ?? row.text ?? (typeof row.message === 'string' ? row.message : undefined)
+    const rowId = row.id ?? row.message_id ?? row.messageId
+    if (content != null && rowId != null) {
+      const sender = [row.sender, row.user, row.author, row.member].find((item) => item && typeof item === 'object') || {}
+      const expanded = [row.senderAgent, row.sender_agent, row.agent, sender.agent].find((item) => item && typeof item === 'object')
+      const senderKind = String(sender.type ?? sender.kind ?? sender.sender_type ?? row.sender_type ?? row.author_type ?? '').toLowerCase()
+      const senderLooksLikeAgent = /agent|bot/.test(senderKind) || sender.agent_id != null || sender.identifier != null || (sender.slug != null && !sender.email)
+      const agent = expanded || (senderLooksLikeAgent ? sender : {})
+      const agentId = Number(agent.id ?? agent.agent_id ?? row.agent_id ?? row.sender_agent_id ?? row.senderAgentId ?? NaN)
+      const identifier = String(agent.identifier ?? agent.slug ?? row.agent_identifier ?? row.sender_identifier ?? '')
+      const name = String(agent.name ?? agent.display_name ?? (senderLooksLikeAgent ? sender.name : '') ?? '')
+      const aliases = new Set([identity.identifier, identity.slug, identity.name].map((item) => String(item || '').toLowerCase()).filter(Boolean))
+      const isSelf = (Number.isFinite(Number(identity.id)) && agentId === Number(identity.id)) || aliases.has(identifier.toLowerCase()) || (!!expanded && aliases.has(name.toLowerCase()))
+      if (isSelf) {
+        const key = String(rowId)
+        if (!seen.has(key)) {
+          seen.add(key)
+          rows.push({
+            id: rowId,
+            parentId: row.parent_id ?? row.parentId ?? row.thread_id ?? null,
+            content: String(content),
+          })
+        }
+      }
+    }
+    for (const key of ['messages', 'replies', 'items', 'data', 'result', 'thread', 'message']) {
+      if (row[key] && typeof row[key] === 'object') visit(row[key], depth + 1)
+    }
+  }
+  visit(value)
+  return rows
+}
+
 // 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/memory.mjs

@@ -0,0 +1,82 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const clean = (value, max = 320) => String(value || '').replace(/\s+/g, ' ').trim().slice(0, max)
+const sameRef = (a, b) => a != null && b != null && String(a) === String(b)
+
+// Small, deterministic memory graph for BYO watchers. Nodes are real events,
+// tickets and deliveries; edges record what a reply answered or where a task was
+// reported. It is intentionally not an LLM transcript or vector store: stable
+// backend ids make exact recall cheaper and prevent old work from being replayed.
+export function createByoMemoryGraph({ path, maxNodes = 1000, now = () => Date.now() }) {
+  let raw = {}
+  try { raw = JSON.parse(readFileSync(path, 'utf8')) } catch { /* first run */ }
+  const nodes = new Map((Array.isArray(raw.nodes) ? raw.nodes : []).filter((node) => node?.key).map((node) => [String(node.key), node]))
+  const edges = new Map((Array.isArray(raw.edges) ? raw.edges : []).filter((edge) => edge?.from && edge?.to && edge?.relation).map((edge) => [`${edge.from}|${edge.relation}|${edge.to}`, edge]))
+
+  const persist = () => {
+    try {
+      mkdirSync(dirname(path), { recursive: true })
+      writeFileSync(path, JSON.stringify({ version: 1, nodes: [...nodes.values()], edges: [...edges.values()] }, null, 2) + '\n', { mode: 0o600 })
+    } catch { /* memory is best-effort; live backend checks remain authoritative */ }
+  }
+  const trim = () => {
+    if (nodes.size <= maxNodes) return
+    const oldest = [...nodes.values()].sort((a, b) => Number(a.updatedAt || 0) - Number(b.updatedAt || 0)).slice(0, nodes.size - maxNodes)
+    const removed = new Set(oldest.map((node) => String(node.key)))
+    for (const key of removed) nodes.delete(key)
+    for (const [key, edge] of edges) if (removed.has(String(edge.from)) || removed.has(String(edge.to))) edges.delete(key)
+  }
+
+  const remember = ({ key, kind, state, summary, refs = {}, meta = {} }) => {
+    const id = String(key || '')
+    if (!id) return null
+    const previous = nodes.get(id)
+    const stamp = now()
+    const node = {
+      ...(previous || { key: id, createdAt: stamp }),
+      kind: clean(kind, 40) || previous?.kind || 'event',
+      state: clean(state, 40) || previous?.state || 'observed',
+      summary: clean(summary) || previous?.summary || '',
+      refs: { ...(previous?.refs || {}), ...refs },
+      meta: { ...(previous?.meta || {}), ...meta },
+      updatedAt: stamp,
+    }
+    nodes.set(id, node); trim(); persist()
+    return node
+  }
+
+  const connect = (from, to, relation) => {
+    const edge = { from: String(from || ''), to: String(to || ''), relation: clean(relation, 50), updatedAt: now() }
+    if (!edge.from || !edge.to || !edge.relation) return null
+    edges.set(`${edge.from}|${edge.relation}|${edge.to}`, edge); persist()
+    return edge
+  }
+
+  const recall = (refs = {}, limit = 8) => {
+    const direct = [...nodes.values()].filter((node) => {
+      const r = node.refs || {}
+      return sameRef(r.channelId, refs.channelId) && (refs.threadId == null || sameRef(r.threadId, refs.threadId)) ||
+        sameRef(r.projectId, refs.projectId) && sameRef(r.ticketId, refs.ticketId)
+    })
+    const keys = new Set(direct.map((node) => String(node.key)))
+    for (const edge of edges.values()) {
+      if (keys.has(String(edge.from))) keys.add(String(edge.to))
+      if (keys.has(String(edge.to))) keys.add(String(edge.from))
+    }
+    return [...nodes.values()].filter((node) => keys.has(String(node.key))).sort((a, b) => Number(b.updatedAt || 0) - Number(a.updatedAt || 0)).slice(0, limit)
+  }
+
+  const context = (refs = {}, limit = 8) => {
+    const items = recall(refs, limit)
+    if (!items.length) return ''
+    return ['RELEVANT VERIFIED MEMORY (do not repeat completed/delivered actions):', ...items.map((node) => `- ${node.kind} ${node.state}: ${node.summary || node.key}`)].join('\n')
+  }
+
+  const has = (key, state) => {
+    const node = nodes.get(String(key || ''))
+    return !!node && (state == null || node.state === state)
+  }
+
+  return { remember, connect, recall, context, has, persist }
+}

package/src/pr-push.mjs

@@ -0,0 +1,112 @@
+import { spawnSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+const DEFAULT_AUTH_PATH = join(homedir(), '.openvisio', 'pr-push-authorizations.json')
+const DEFAULT_RULE_PATH = join(homedir(), '.codex', 'rules', 'openvisio-agent.rules')
+
+const gitText = (cwd, args, spawn = spawnSync) => {
+  const result = spawn('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+  if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || `git ${args.join(' ')} failed`).trim())
+  return String(result.stdout || '').trim()
+}
+
+const safeRemote = (value) => {
+  const remote = String(value || '').trim()
+  if (/^https?:\/\//i.test(remote) || /^ssh:\/\//i.test(remote)) {
+    const parsed = new URL(remote)
+    if (parsed.username || parsed.password) throw new Error('Origin contains credentials in its URL. Move credentials to your Git credential manager before authorizing PR pushes.')
+    return remote
+  }
+  if (/^[^@\s]+@[^:\s]+:[^\s]+$/.test(remote)) return remote
+  throw new Error('Origin must be an HTTPS or SSH repository URL. Local paths and file:// remotes cannot be authorized.')
+}
+
+export function isSafeAgentBranch(value) {
+  const branch = String(value || '')
+  return /^agent\/[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(branch) &&
+    !branch.includes('..') && !branch.includes('//') && !branch.includes('@{') &&
+    !/[~^:?*\[\\]/.test(branch) && !/[/.]$/.test(branch)
+}
+
+export function codexPrPushRule() {
+  return `# Generated by: openvisio-agent authorize-pr-push
+# The helper enforces an exact pre-authorized repository + origin and only
+# pushes the current agent/* branch. It accepts no force, remote, or ref args.
+prefix_rule(
+    pattern = ["openvisio-agent", "push-pr-branch"],
+    decision = "allow",
+    justification = "The user explicitly authorized OpenVisio's constrained agent-branch PR push helper.",
+    match = ["openvisio-agent push-pr-branch"],
+)
+`
+}
+
+function readAuthorizations(path) {
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'))
+    return Array.isArray(value.authorizations) ? value.authorizations : []
+  } catch { return [] }
+}
+
+function writePrivate(path, value) {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, value, { mode: 0o600 })
+  try { chmodSync(path, 0o600) } catch { /* Windows / best-effort */ }
+}
+
+export function repositoryPushIdentity(cwd = process.cwd(), spawn = spawnSync) {
+  const root = realpathSync(gitText(cwd, ['rev-parse', '--show-toplevel'], spawn))
+  const remote = safeRemote(gitText(root, ['remote', 'get-url', '--push', 'origin'], spawn))
+  const branch = gitText(root, ['branch', '--show-current'], spawn)
+  return { root, remote, branch }
+}
+
+export function validatePrPushAuthorization({ root, remote, branch, authorizations }) {
+  if (!isSafeAgentBranch(branch)) {
+    throw new Error(`Refusing to push branch "${branch || '(detached HEAD)'}". OpenVisio PR pushes require the current branch to match agent/*.`)
+  }
+  const allowed = (Array.isArray(authorizations) ? authorizations : []).some((entry) => entry?.root === root && entry?.remote === remote)
+  if (!allowed) {
+    throw new Error(`OPENVISIO_PR_PUSH_AUTH_REQUIRED: This repository and its exact origin are not authorized. From ${root}, run: openvisio-agent authorize-pr-push`)
+  }
+  return true
+}
+
+export function repositoryHasPrPushAuthorization({ cwd = process.cwd(), authPath = DEFAULT_AUTH_PATH, spawn = spawnSync } = {}) {
+  try {
+    const { root, remote } = repositoryPushIdentity(cwd, spawn)
+    return readAuthorizations(authPath).some((entry) => entry?.root === root && entry?.remote === remote)
+  } catch { return false }
+}
+
+export function authorizePrPush({ cwd = process.cwd(), authPath = DEFAULT_AUTH_PATH, rulePath = DEFAULT_RULE_PATH, spawn = spawnSync, now = () => new Date().toISOString() } = {}) {
+  const { root, remote } = repositoryPushIdentity(cwd, spawn)
+  const authorizations = readAuthorizations(authPath).filter((entry) => entry?.root !== root)
+  authorizations.push({ root, remote, authorizedAt: now() })
+  writePrivate(authPath, JSON.stringify({ version: 1, authorizations }, null, 2) + '\n')
+  writePrivate(rulePath, codexPrPushRule())
+  return { root, remote, authPath, rulePath }
+}
+
+export function revokePrPush({ cwd = process.cwd(), authPath = DEFAULT_AUTH_PATH, spawn = spawnSync } = {}) {
+  const root = realpathSync(gitText(cwd, ['rev-parse', '--show-toplevel'], spawn))
+  const before = readAuthorizations(authPath)
+  const authorizations = before.filter((entry) => entry?.root !== root)
+  if (existsSync(authPath)) writePrivate(authPath, JSON.stringify({ version: 1, authorizations }, null, 2) + '\n')
+  return { root, revoked: authorizations.length !== before.length }
+}
+
+export function pushPrBranch({ cwd = process.cwd(), authPath = DEFAULT_AUTH_PATH, spawn = spawnSync } = {}) {
+  const identity = repositoryPushIdentity(cwd, spawn)
+  validatePrPushAuthorization({ ...identity, authorizations: readAuthorizations(authPath) })
+  const destination = `HEAD:refs/heads/${identity.branch}`
+  // The helper runs outside Codex's workspace sandbox after the user authorizes
+  // it. Disable repository hooks so an edited pre-push hook cannot widen this
+  // one operation into arbitrary host execution.
+  const nullHooks = process.platform === 'win32' ? 'NUL' : '/dev/null'
+  const result = spawn('git', ['-c', `core.hooksPath=${nullHooks}`, 'push', '-u', 'origin', destination], { cwd: identity.root, stdio: 'inherit' })
+  if (result.status !== 0) throw new Error(`git push failed with exit code ${result.status ?? 'unknown'}`)
+  return identity
+}

package/src/watch.mjs

@@ -10,7 +10,9 @@ 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, mentionDedupeKeys, opencodeEventEvidence, requestTargetsLaterAgent, shouldSuppressCodexDiagnostic, taskAgentId, taskFromEvent, taskIsAwaitingReview, taskIsCompleted } from './events.mjs'
+import { agentStateRequest, buildTaskCompletionReport, codexPolicyBlock, mentionDedupeKeys, normalizeRenderedMessageText, opencodeEventEvidence, renderedAgentMessages, requestTargetsLaterAgent, shouldSuppressCodexDiagnostic, taskAgentId, taskFromEvent, taskIsAwaitingReview, taskIsCompleted } from './events.mjs'
+import { createByoMemoryGraph } from './memory.mjs'
+import { repositoryHasPrPushAuthorization } from './pr-push.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
@@ -402,12 +404,14 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
   const tomlString = (v) => JSON.stringify(String(v))
   const headerEntries = Object.entries(mcpHeaders || {}).map(([k, v]) => `${JSON.stringify(k)} = ${tomlString(v)}`).join(', ')
 
-  function runCycle(prompt, cycleModel) {
+  function runCycle(prompt, cycleModel, cycleOptions = {}) {
     return new Promise((resolve) => {
       const m = cycleModel || model
       const full = systemPrompt ? systemPrompt + '\n\n' + prompt : prompt
+      const disabledMcpTools = Array.isArray(cycleOptions.disabledMcpTools) ? cycleOptions.disabledMcpTools.filter(Boolean) : []
+      const disabledToolConfig = disabledMcpTools.length ? `, disabled_tools = [${disabledMcpTools.map(tomlString).join(', ')}]` : ''
       const mcpOverride = mcpUrl
-        ? `mcp_servers={ openvisio-team = { url = ${tomlString(mcpUrl)}${headerEntries ? `, http_headers = { ${headerEntries} }` : ''} } }`
+        ? `mcp_servers={ openvisio-team = { url = ${tomlString(mcpUrl)}${headerEntries ? `, http_headers = { ${headerEntries} }` : ''}${disabledToolConfig} } }`
         : ''
       const args = ['exec', '--ignore-user-config', '--skip-git-repo-check', '--ephemeral', '--json', '--color', 'never',
         ...(canCode ? ['--approve-for-me'] : ['--sandbox', 'read-only']),
@@ -448,8 +452,9 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
       const inspectLine = (line) => {
         const s = line.trim()
         if (!s) return
+        policyBlock = codexPolicyBlock(s) || policyBlock
         if (/command_execution|file_change|apply_patch|shell_command|exec_command/i.test(s)) didCode = true
-        if (/file_change|apply_patch/i.test(s) || /\b(?:git\s+(?:commit|push)|gh\s+pr\s+create)\b/i.test(s)) didRepoMutation = true
+        if (/file_change|apply_patch/i.test(s) || /\b(?:git\s+(?:commit|push)|gh\s+pr\s+create|openvisio-agent\s+push-pr-branch)\b/i.test(s)) didRepoMutation = true
         if (/post_message|comment_ticket/i.test(s)) didMessage = true
         try {
           const event = JSON.parse(s)
@@ -461,6 +466,7 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
             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 (/^(?:create_codebase_branch|create_codebase_commit|write_codebase_file|create_pull_request)$/.test(tool)) { didCode = true; didRepoMutation = true }
             if (/post_message|comment_ticket/.test(tool)) didMessage = true
             if (/post_message/.test(tool)) didChannelMessage = true
             if (/fail|error/i.test(String(item.status || '')) || item.error) mcpErrors.add(tool)
@@ -678,7 +684,10 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     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 codexPushGuide = agent === 'codex' && canCode
+    ? '\n\nCODEX PR DELIVERY: first inspect the OpenVisio MCP tools. When list_codebases, create_codebase_branch, create_codebase_commit (or write_codebase_file), and create_pull_request are available, use that authenticated linked-codebase flow to create the agent/* branch, publish the verified changed files, and open the PR. This is the preferred path and requires no local git push. If those tools are unavailable for the repository, do not run git push directly. From the repository run `openvisio-agent push-pr-branch`. It is a user-authorized constrained fallback that can only push HEAD to the matching agent/* branch on the exact authorized origin. If it reports OPENVISIO_PR_PUSH_AUTH_REQUIRED, do not retry or route around it. Report the one-time command `openvisio-agent authorize-pr-push` as the blocker.'
+    : ''
+  const fullPrompt = canCode ? CODE_FULL + codexPushGuide : CYCLE
   const fastPrompt = canCode ? CODE_FAST : CYCLE_FAST
   // Live model state — changeable at runtime by the in-chat `/model` command.
   // codeModel drives full/sweep cycles; chatModel (if set) the lighter fast/intro
@@ -687,8 +696,8 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   let liteModel = chatModel || model
 
   const lanes = {
-    work: { busy: false, queued: null, pending: [], targets: new Set(), taskRefs: [] },
-    reply: { busy: false, queued: null, pending: [], targets: new Set(), taskRefs: [] },
+    work: { busy: false, queued: null, pending: [], targets: new Set(), taskRefs: [], deferred: [] },
+    reply: { busy: false, queued: null, pending: [], targets: new Set(), taskRefs: [], deferred: [] },
   }
   // 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
@@ -703,6 +712,8 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   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 : [])
+  const deliveredReplies = new Set(Array.isArray(replayState.deliveredReplies) ? replayState.deliveredReplies : [])
+  const memory = createByoMemoryGraph({ path: join(OV_DIR, 'watch-' + slug + '-memory.json') })
   // 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.
@@ -714,6 +725,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   // 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 blockedTaskRepos = new Map(Array.isArray(replayState.blockedTaskRepos) ? replayState.blockedTaskRepos : [])
   const trimSeen = (set) => { while (set.size > 500) set.delete(set.values().next().value) }
   const MENTION_SIGNATURE_TTL_MS = 10 * 60 * 1000
   const pruneMentionSignatures = () => {
@@ -728,7 +740,9 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
         seenMentions: [...seenMentions],
         recentMentionSignatures: [...recentMentionSignatures],
         seenActivities: [...seenActivities],
+        deliveredReplies: [...deliveredReplies],
         blockedTasks: [...blockedTasks],
+        blockedTaskRepos: [...blockedTaskRepos],
         pendingCompletionReports: [...pendingCompletionReports],
         reportedCompletions: [...reportedCompletions],
         reportedTaskComments: [...reportedTaskComments],
@@ -778,7 +792,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.18.0' } } }, 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.1' } } }, false)
     if (!res.ok) throw new Error('MCP initialize HTTP ' + res.status)
     await mcpPayload(res)
     mcpSessionId = res.headers.get('mcp-session-id') || ''
@@ -797,7 +811,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     if (payload.error) throw new Error(`MCP ${name}: ${payload.error.message || 'tool error'}`)
     const result = payload.result ?? payload
     if (result?.isError) {
-      const detail = result.content?.find?.((c) => c?.type === 'text')?.text || 'tool error'
+      const detail = String(result.content?.find?.((c) => c?.type === 'text')?.text || 'tool error').split(apiKey).join('[redacted]')
       throw new Error(`MCP ${name}: ${detail}`)
     }
     return result
@@ -808,6 +822,48 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     try { return JSON.parse(text) } catch { return { text } }
   }
 
+  // All watcher-owned message delivery goes through this gate. For threaded
+  // replies it first reads the live backend thread and inspects rows already
+  // rendered as this agent. A persisted delivery key closes the crash/reconnect
+  // gap; an in-flight promise closes the two-lane race inside one watcher.
+  const messageDeliveries = new Map()
+  const postMessageOnce = async ({ key, channelId, parentId, projectId, content, skipIfAnyAgentReply = false, sourceKey = '' }) => {
+    const deliveryKey = String(key || '')
+    const message = String(content || '').trim()
+    if (!deliveryKey || !Number.isFinite(Number(channelId)) || !message) return { posted: false, reason: 'invalid-delivery' }
+    if (deliveredReplies.has(deliveryKey) || memory.has(deliveryKey, 'rendered')) return { posted: false, reason: 'remembered' }
+    if (messageDeliveries.has(deliveryKey)) return messageDeliveries.get(deliveryKey)
+
+    const run = (async () => {
+      if (parentId != null) {
+        const live = toolData(await callMcpTool('list_message_thread', { channel_id: Number(channelId), message_id: Number(parentId) }))
+        const rendered = renderedAgentMessages(live, { id: selfAgentId, identifier, slug, name: slug })
+        const duplicate = rendered.some((row) => normalizeRenderedMessageText(row.content) === normalizeRenderedMessageText(message))
+        if (duplicate || (skipIfAnyAgentReply && rendered.length)) {
+          deliveredReplies.add(deliveryKey); trimSeen(deliveredReplies); persistReplay()
+          memory.remember({ key: deliveryKey, kind: 'delivery', state: 'rendered', summary: duplicate ? message : rendered.at(-1)?.content, refs: { channelId: Number(channelId), threadId: Number(parentId) }, meta: { discoveredFromBackend: true } })
+          if (sourceKey) memory.connect(deliveryKey, sourceKey, 'responds_to')
+          log('message delivery ' + deliveryKey + ' already rendered — skipped')
+          return { posted: false, reason: duplicate ? 'same-content-rendered' : 'agent-reply-rendered' }
+        }
+      }
+
+      sendStatus(Number(channelId), 'typing')
+      const result = toolData(await callMcpTool('post_message', {
+        ...(Number.isFinite(Number(projectId)) ? { project_id: Number(projectId) } : {}),
+        channel_id: Number(channelId),
+        ...(parentId != null ? { parent_id: Number(parentId) } : {}),
+        content: message,
+      }))
+      deliveredReplies.add(deliveryKey); trimSeen(deliveredReplies); persistReplay()
+      memory.remember({ key: deliveryKey, kind: 'delivery', state: 'rendered', summary: message, refs: { channelId: Number(channelId), ...(parentId != null ? { threadId: Number(parentId) } : {}), ...(Number.isFinite(Number(projectId)) ? { projectId: Number(projectId) } : {}) }, meta: { messageId: result.id ?? result.message?.id ?? null } })
+      if (sourceKey) memory.connect(deliveryKey, sourceKey, 'responds_to')
+      return { posted: true, result }
+    })().finally(() => messageDeliveries.delete(deliveryKey))
+    messageDeliveries.set(deliveryKey, run)
+    return run
+  }
+
   const statusChannelCache = new Map()
   const projectStatusChannel = async (projectId) => {
     const key = Number(projectId)
@@ -829,6 +885,22 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     }
   }
 
+  const announceIntroduction = async () => {
+    const projectsData = toolData(await callMcpTool('list_projects'))
+    const projects = Array.isArray(projectsData.projects) ? projectsData.projects : []
+    const project = projects.find((item) => Number.isFinite(Number(item.id)))
+    if (!project) { log('no project available for first-connection introduction'); return false }
+    const channelId = await projectStatusChannel(project.id)
+    if (!Number.isFinite(Number(channelId))) return false
+    await postMessageOnce({
+      key: `intro:${identifier}:${project.id}`,
+      projectId: Number(project.id),
+      channelId: Number(channelId),
+      content: "I'm here, I pick up tasks assigned to me, and I respond to @mentions. Send work my way whenever you need me.",
+    })
+    return true
+  }
+
   const announceTaskCompletion = async (taskRef, result = {}) => {
     const projectId = Number(taskRef?.projectId)
     const ticketId = Number(taskRef?.ticketId)
@@ -838,6 +910,15 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     const ticket = current.ticket ?? current.task ?? current
     const report = buildTaskCompletionReport(ticket, { projectId, fallbackText: result.outputText })
     if (!report) return false
+    const memoryKey = `ticket:${projectId}:${ticketId}`
+    memory.remember({
+      key: memoryKey,
+      kind: 'ticket',
+      state: 'handoff',
+      summary: report.content,
+      refs: { projectId, ticketId },
+      meta: { reportKey: report.key, prUrl: report.prUrl },
+    })
     // 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.
@@ -862,10 +943,10 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     }
     const channelId = Number.isFinite(Number(taskRef.channelId)) ? Number(taskRef.channelId) : await projectStatusChannel(projectId)
     if (!Number.isFinite(channelId)) return false
-    sendStatus(channelId, 'typing')
-    await callMcpTool('post_message', { project_id: projectId, channel_id: channelId, content: report.content })
+    await postMessageOnce({ key: `completion:${report.key}`, projectId, channelId, content: report.content, sourceKey: memoryKey })
     reportedCompletions.add(report.key); trimSeen(reportedCompletions)
     pendingCompletionReports.delete(taskKey); persistReplay()
+    memory.remember({ key: memoryKey, kind: 'ticket', state: 'reported', summary: report.content, refs: { projectId, ticketId, channelId }, meta: { reportKey: report.key, prUrl: report.prUrl } })
     log('posted verified completion for ticket #' + ticketId + ' in channel ' + channelId)
     return true
   }
@@ -882,11 +963,9 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     let delivered = false
     if (Number.isFinite(channelId)) {
       try {
-        await callMcpTool('post_message', {
-          channel_id: channelId,
-          ...(parentMatch ? { parent_id: Number(parentMatch[1]) } : {}),
-          content: notice,
-        })
+        const parentId = parentMatch ? Number(parentMatch[1]) : null
+        const blockerKey = `blocker:${channelId}:${parentId ?? 'top'}:${normalizeRenderedMessageText(notice).slice(0, 180)}`
+        await postMessageOnce({ key: blockerKey, channelId, parentId, projectId, content: notice, sourceKey: Number.isFinite(ticketId) && Number.isFinite(projectId) ? `ticket:${projectId}:${ticketId}` : '' })
         delivered = true
       } catch (e) {
         log('failed to post blocker in channel ' + channelId + ': ' + (e?.message || e))
@@ -899,6 +978,13 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
 
     const key = `${projectId}:${ticketId}`
     if (pause) { blockedTasks.add(key); persistReplay() }
+    memory.remember({
+      key: `ticket:${projectId}:${ticketId}`,
+      kind: 'ticket',
+      state: pause ? 'authorization-blocked' : 'blocked',
+      summary: ticketNotice,
+      refs: { projectId, ticketId, ...(Number.isFinite(channelId) ? { channelId } : {}) },
+    })
     try {
       await callMcpTool('comment_ticket', { project_id: projectId, ticket_id: ticketId, text: ticketNotice })
       delivered = true
@@ -921,6 +1007,18 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   }
 
   const reportPolicyBlock = async (prompt, taskRef, block) => {
+    if (block?.kind === 'pr-push-authorization-required') {
+      const location = block.root ? ` from \`${block.root}\`` : ' from the repository'
+      const notice = `Action required: run \`openvisio-agent authorize-pr-push\`${location}. This is a one-time, repository-scoped opt-in. It permits only the constrained \`openvisio-agent push-pr-branch\` helper for the current \`agent/*\` branch, never main/master, force pushes, another remote, or merges. I've paused the ticket until it is enabled.`
+      const ticketNotice = `I'm paused before the PR push. Run \`openvisio-agent authorize-pr-push\`${location}; the watcher will resume this ticket after the repository-scoped helper is authorized.`
+      const projectId = Number(taskRef?.projectId)
+      const ticketId = Number(taskRef?.ticketId)
+      if (block.root && Number.isFinite(projectId) && Number.isFinite(ticketId)) {
+        blockedTaskRepos.set(`${projectId}:${ticketId}`, block.root)
+        persistReplay()
+      }
+      return publishBlocker({ prompt, taskRef, notice, ticketNotice, pause: true })
+    }
     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
@@ -962,12 +1060,13 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
           if (taskAgentId !== Number(self.id) && taskIdent !== identifier) continue
           const taskKey = `${project.id}:${task.id}`
           if (taskIsCompleted(task, doneIds) || taskIsAwaitingReview(task, reviewIds)) {
+            memory.remember({ key: `ticket:${project.id}:${task.id}`, kind: 'ticket', state: 'handoff', summary: task.title, refs: { projectId: project.id, ticketId: task.id } })
             if (pendingCompletionReports.has(taskKey)) {
               const activityChannel = await projectStatusChannel(project.id)
               try { await announceTaskCompletion({ projectId: project.id, ticketId: task.id, channelId: activityChannel }) }
               catch (e) { log('completion report retry failed for ticket #' + task.id + ': ' + (e?.message || e)) }
             }
-            if (blockedTasks.delete(taskKey)) persistReplay()
+            if (blockedTasks.delete(taskKey)) { blockedTaskRepos.delete(taskKey); persistReplay() }
             // Release the in-flight de-dupe key at handoff. If a reviewer moves
             // the ticket back to an actionable column, that update must start a
             // fresh work cycle.
@@ -976,11 +1075,14 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
           }
           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')
+            const blockedRepo = blockedTaskRepos.get(taskKey)
+            const helperAuthorized = blockedRepo && repositoryHasPrPushAuthorization({ cwd: blockedRepo })
+            if (helperAuthorized || /\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); blockedTaskRepos.delete(taskKey); seenTasks.delete(taskKey); persistReplay()
+              log('backlog ticket #' + task.id + (helperAuthorized ? ' has repository-scoped PR push authorization' : ' now contains explicit push authorization') + ' — resuming')
             } else continue
           }
+          memory.remember({ key: `ticket:${project.id}:${task.id}`, kind: 'ticket', state: 'assigned', summary: task.title, refs: { projectId: project.id, ticketId: task.id }, meta: { updatedAt: task.updated_at ?? task.updatedAt } })
           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 : []
@@ -999,7 +1101,13 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
             // 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 })
+            mentionActivity.push({
+              projectId: project.id,
+              project: project.name,
+              channelId: activityChannelId,
+              message: activityMessage,
+              activity: item,
+            })
           }
         }
       }
@@ -1022,8 +1130,18 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       const inboxSignature = JSON.stringify(mentionActivity.slice(-20)).slice(0, 4000)
       if (mentionActivity.length && inboxSignature !== lastInboxSignature) {
         lastInboxSignature = inboxSignature
-        log('backlog reconciliation found mention activity -> reply cycle')
-        void drain('fast', `Recent project activity contains these messages mentioning YOU: ${inboxSignature}. Handle each still-unanswered mention once using the channel/message ids in the activity. Do not call nonexistent poll_inbox or get_marching_orders tools. Skip anything already answered by you.`)
+        log('backlog reconciliation found ' + mentionActivity.length + ' mention(s) -> guarded reply cycle(s)')
+        // Replay each real message through the exact same delivery path as a live
+        // WebSocket mention. This preserves thread ids and lets postMessageOnce
+        // consult the rendered thread before any reply is emitted.
+        for (const mention of mentionActivity) {
+          onEvent('agent:mention', {
+            project_id: mention.projectId,
+            channel_id: mention.channelId,
+            message: mention.message,
+            _mentionAlreadyMarked: true,
+          })
+        }
       } else if (!mentionActivity.length) lastInboxSignature = ''
     } catch (e) {
       mcpSessionId = ''
@@ -1074,9 +1192,16 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     lastTaskSignature = ''
   }
 
-  async function drain(kind, context, targetChannels = [], taskRef = null) {
+  async function drain(kind, context, targetChannels = [], taskRef = null, delivery = null) {
     const laneName = kind === 'full' ? 'work' : 'reply'
     const lane = lanes[laneName]
+    // A guarded reply is never coalesced with another event. It carries one
+    // source message and one delivery key, so queue it as an independent cycle.
+    if (lane.busy && delivery) {
+      lane.deferred.push({ kind, context, targetChannels, taskRef, delivery })
+      log(laneName + ' lane busy — queued one guarded ' + kind + ' cycle')
+      return
+    }
     if (context) lane.pending.push(context)
     if (taskRef) lane.taskRefs.push(taskRef)
     for (const channelId of targetChannels) if (Number.isFinite(Number(channelId))) lane.targets.add(Number(channelId))
@@ -1089,7 +1214,11 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     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)
+    const memoryRefs = delivery
+      ? { channelId: delivery.channelId, threadId: delivery.parentId }
+      : activeTaskRef ? { projectId: activeTaskRef.projectId, ticketId: activeTaskRef.ticketId } : {}
+    const recalled = memory.context(memoryRefs)
+    const prompt = (ctx.length ? ctx.join('\n') + '\n\n' : '') + (recalled ? recalled + '\n\n' : '') + baseFor(kind)
     // Chat-shaped cycles (mentions/intro) may run on the cheaper chat model; code
     // work (full/sweep) uses the main model.
     const useModel = agent === 'codex' ? codeModel : kind === 'full' ? codeModel : liteModel
@@ -1101,7 +1230,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     // 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)
+      const result = await runners[laneName].runCycle(prompt, useModel, agent === 'codex' && delivery ? { disabledMcpTools: ['post_message'] } : {})
       let completionResult = result
       if (agent === 'codex' && result?.subtype === 'blocked' && result?.policyBlock) {
         log('WORK_CYCLE_BLOCKED authorization required; pausing this ticket and publishing an action-required notice')
@@ -1130,7 +1259,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       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 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, publish an agent/* branch, open the PR, and call update_ticket with the correct board column. ${agent === 'codex' ? 'Prefer the available OpenVisio create_codebase_branch/create_codebase_commit/create_pull_request tools. Only when that linked-codebase flow is unavailable, run openvisio-agent push-pr-branch; never retry a rejected direct git push.' : ''} Post only when the original context supplies a source thread.`, codeModel, agent === 'codex' && delivery ? { disabledMcpTools: ['post_message'] } : {})
         const recoveredResult = combineWorkEvidence(result, recovery)
         const recoveryMissing = missingWorkEvidence(recoveredResult, ticketCycle)
         if (recovery?.subtype !== 'ok' || recoveryMissing.length) {
@@ -1161,11 +1290,22 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
           log('completion report failed for ticket #' + activeTaskRef.ticketId + ': ' + (e?.message || e) + '; retained for reconnect retry')
         }
       }
+      if (agent === 'codex' && delivery) {
+        const reply = String(completionResult?.outputText || '').trim()
+        if (!reply) {
+          log('guarded reply produced no final text; leaving delivery unrecorded for retry')
+        } else {
+          try { await postMessageOnce({ ...delivery, content: reply }) }
+          catch (e) { log('guarded reply delivery failed closed: ' + (e?.message || e)) }
+        }
+      }
     } finally {
       if (heartbeat) clearInterval(heartbeat)
       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) }
+      const deferred = lane.deferred.shift()
+      if (deferred) void drain(deferred.kind, deferred.context, deferred.targetChannels, deferred.taskRef, deferred.delivery)
+      else if (lane.queued || lane.pending.length) { const next = lane.queued || (laneName === 'work' ? 'full' : 'fast'); lane.queued = null; void drain(next) }
     }
   }
 
@@ -1229,22 +1369,28 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       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); pendingCompletionReports.delete(key); persistReplay(); seenTasks.delete(key); log(kind + ' ticket #' + ticketId + ' is not assigned to this agent — ignored'); return }
+      if (!belongsToSelf) {
+        memory.remember({ key: `ticket:${projectId}:${ticketId}`, kind: 'ticket', state: 'unassigned', summary: ticket.title, refs: { projectId, ticketId } })
+        blockedTasks.delete(key); blockedTaskRepos.delete(key); pendingCompletionReports.delete(key); persistReplay(); seenTasks.delete(key); log(kind + ' ticket #' + ticketId + ' is not assigned to this agent — ignored'); return
+      }
       if (taskIsCompleted(ticket) || taskIsAwaitingReview(ticket)) {
+        memory.remember({ key: `ticket:${projectId}:${ticketId}`, kind: 'ticket', state: 'handoff', summary: ticket.title, refs: { projectId, ticketId } })
         if (pendingCompletionReports.has(key)) {
           const activityChannel = await projectStatusChannel(projectId)
           try { await announceTaskCompletion({ projectId, ticketId, channelId: activityChannel }) }
           catch (e) { log('completion report failed for ticket #' + ticketId + ': ' + (e?.message || e) + '; retained for reconnect retry') }
         }
-        blockedTasks.delete(key); persistReplay(); seenTasks.delete(key)
+        blockedTasks.delete(key); blockedTaskRepos.delete(key); persistReplay(); seenTasks.delete(key)
         log(kind + ' ticket #' + ticketId + ' is already complete or awaiting review — 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')
+        const blockedRepo = blockedTaskRepos.get(key)
+        const helperAuthorized = blockedRepo && repositoryHasPrPushAuthorization({ cwd: blockedRepo })
+        if (helperAuthorized || /\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); blockedTaskRepos.delete(key); seenTasks.delete(key); persistReplay()
+          log(kind + ' ticket #' + ticketId + (helperAuthorized ? ' has repository-scoped PR push authorization' : ' contains explicit push authorization') + ' — resuming')
         } else {
           log(kind + ' ticket #' + ticketId + ' is paused for explicit repository push authorization — ignored')
           return
@@ -1253,6 +1399,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       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 || '')
+      memory.remember({ key: `ticket:${projectId}:${ticketId}`, kind: 'ticket', state: 'queued', summary: title, refs: { projectId, ticketId }, meta: { sourceEvent: kind } })
       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')
@@ -1282,20 +1429,28 @@ 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.
-      if (markMentionHandled(msg, cid)) { log('agent:mention (dup) — skipped'); return }
+      if (!raw._mentionAlreadyMarked && 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
       }
+      const mentionKeys = mentionDedupeKeys(msg, cid)
+      const sourceKey = `mention:${cid ?? '?'}:${mentionKeys.idKey || mentionKeys.signatureKey || threadRoot || Date.now()}`
+      memory.remember({ key: sourceKey, kind: 'mention', state: 'received', summary: text, refs: { channelId: cid, threadId: threadRoot, messageId: mid } })
+      const guardedDelivery = (stage = 'reply', skipIfAnyAgentReply = stage !== 'result') => agent === 'codex' && cid != null
+        ? { key: `reply:${sourceKey}:${stage}`, channelId: Number(cid), parentId: threadRoot, skipIfAnyAgentReply, sourceKey }
+        : null
       // Under-the-hood model control from chat (view / switch the model the agent runs).
       const mcmd = cid != null ? parseModelCmd(text) : null
       if (mcmd) {
         const thread = threadRoot != null ? `, parent_id ${threadRoot}` : ''
         if (mcmd.report) {
           log('model query → code ' + codeModel + ' / chat ' + liteModel)
-          void drain('fast', `An engineer asked which model you're running. Reply once in channel ${cid}${thread} (with your agent creds): "I'm on ${codeModel} for code work${liteModel !== codeModel ? ` and ${liteModel} for chat replies` : ' (and chat)'}." One line. Then stop.`)
+          const delivery = guardedDelivery('model')
+          void drain('fast', `An engineer asked which model you're running. ${delivery ? `Return exactly this one-line final answer without calling post_message: "I'm on ${codeModel} for code work${liteModel !== codeModel ? ` and ${liteModel} for chat replies` : ' (and chat)'}.” The watcher will verify and deliver it once.` : `Reply once in channel ${cid}${thread} (with your agent creds): "I'm on ${codeModel} for code work${liteModel !== codeModel ? ` and ${liteModel} for chat replies` : ' (and chat)'}.” One line. Then stop.`}`, [cid], null, delivery)
         } else if (mcmd.invalid) {
-          void drain('fast', `An engineer tried to switch your model to "${mcmd.invalid}", which isn't one you recognize. Reply once in channel ${cid}${thread} (with your agent creds): say you support "opus", "sonnet", "haiku", or a full "claude-…" id, and ask which they meant. One line. Then stop.`)
+          const delivery = guardedDelivery('model')
+          void drain('fast', `An engineer tried to switch your model to "${mcmd.invalid}", which isn't one you recognize. ${delivery ? 'Return one short final answer saying you support "opus", "sonnet", "haiku", or a full model id and asking which they meant. Do not call post_message; the watcher will verify and deliver it once.' : `Reply once in channel ${cid}${thread} (with your agent creds): say you support "opus", "sonnet", "haiku", or a full "claude-…" id, and ask which they meant. One line. Then stop.`}`, [cid], null, delivery)
         } else {
           const tgt = mcmd.target // 'chat' | 'code' | 'both'
           const prev = `code ${codeModel}/chat ${liteModel}`
@@ -1305,7 +1460,8 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
           persistModel()
           const label = tgt === 'chat' ? 'chat model' : tgt === 'code' ? 'code model' : 'model'
           log('model switched (' + tgt + ') ' + prev + ' → code ' + codeModel + '/chat ' + liteModel + (who ? ' (by ' + who + ')' : ''))
-          void drain('fast', `An engineer switched your ${label} to "${mcmd.set}" — active for your next ${tgt === 'chat' ? 'chat replies' : tgt === 'code' ? 'code cycles' : 'actions'}. Post ONE short confirmation in channel ${cid}${thread} (with your agent creds): e.g. "Switched my ${label} to ${mcmd.set} — I'll use it from here." Then stop.`)
+          const delivery = guardedDelivery('model')
+          void drain('fast', `An engineer switched your ${label} to "${mcmd.set}" — active for your next ${tgt === 'chat' ? 'chat replies' : tgt === 'code' ? 'code cycles' : 'actions'}. ${delivery ? `Return one short final confirmation such as "Switched my ${label} to ${mcmd.set}. I'll use it from here." Do not call post_message; the watcher will verify and deliver it once.` : `Post ONE short confirmation in channel ${cid}${thread} (with your agent creds): e.g. "Switched my ${label} to ${mcmd.set} — I'll use it from here." Then stop.`}`, [cid], null, delivery)
         }
         return
       }
@@ -1314,16 +1470,24 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       // subsequent working/typing heartbeat for its lane.
       if (cid != null) sendStatus(cid, 'thinking')
       const codingMention = canCode && needsCode(text)
+      const replyDelivery = guardedDelivery(codingMention ? 'result' : 'reply', !codingMention)
       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.`
+        ? replyDelivery
+          ? `You were @mentioned in OpenVisio channel ${cid}${who ? ` by "${who}"` : ''}: "${text}". This mention is FOR YOU. ${codingMention ? 'Complete the repository work and verification first.' : 'Answer the request.'} Do NOT call post_message; it is intentionally unavailable. Return only the final 1-3 sentence reply as your final answer. The watcher will read the real thread, check its persistent memory graph, and render that answer at most once.${who ? ` To mention the requester, use their exact full name "@${who}".` : ''} Do not poll_inbox.`
+          : `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.`
         : undefined
       if (codingMention) {
-        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, cid == null ? [] : [cid])
-        void drain('full', ctx, cid == null ? [] : [cid])
-      } else void drain('fast', ctx, cid == null ? [] : [cid])
+        if (agent === 'codex' && cid != null) {
+          const ack = `${who ? `@${who} ` : ''}I've picked this up and will return here with the verified result.`
+          void postMessageOnce({ ...guardedDelivery('ack'), content: ack }).catch((e) => log('guarded acknowledgement failed closed: ' + (e?.message || e)))
+        } else {
+          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, cid == null ? [] : [cid])
+        }
+        void drain('full', ctx, cid == null ? [] : [cid], null, replyDelivery)
+      } else void drain('fast', ctx, cid == null ? [] : [cid], null, replyDelivery)
     } else if (k === 'error') {
       const detail = raw && (raw.message || raw.error || raw.reason || raw.code || raw.d?.message || raw.d?.error)
       log('error event: ' + (detail ? String(detail) : JSON.stringify(raw)).slice(0, 220))
@@ -1345,9 +1509,17 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     // Workspace ethics: a one-time hello the FIRST time this agent ever connects.
     const introMarker = join(OV_DIR, 'intro-' + slugify(identifier) + '.done')
     if (!existsSync(introMarker)) {
-      try { mkdirSync(OV_DIR, { recursive: true }); writeFileSync(introMarker, new Date().toISOString() + '\n') } catch { /* best-effort */ }
+      if (agent !== 'codex') {
+        try { mkdirSync(OV_DIR, { recursive: true }); writeFileSync(introMarker, new Date().toISOString() + '\n') } catch { /* best-effort */ }
+      }
       log('first connection — introducing self to the workspace')
-      introTimer = setTimeout(() => void drain('intro'), 5000) // let the socket subscribe first
+      introTimer = setTimeout(() => {
+        if (agent !== 'codex') { void drain('intro'); return }
+        void announceIntroduction().then((delivered) => {
+          if (!delivered) return
+          try { mkdirSync(OV_DIR, { recursive: true }); writeFileSync(introMarker, new Date().toISOString() + '\n') } catch { /* best-effort */ }
+        }).catch((e) => log('guarded introduction failed: ' + (e?.message || e)))
+      }, 5000) // let the socket subscribe first
     }
     // Reconciliation replaces the old model-driven startup/daily sweep. It uses
     // supported MCP tools directly, stays silent when empty, and hands verified