openvisio-agent 0.17.6 → 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.17.6",
+  "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,8 +21,13 @@ 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')
 const spec = readFileSync(join(repo, 'docs', 'CODEX_BYO_AGENT_SPEC.md'), 'utf8')
 
 const assertions = [
@@ -30,10 +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)')],
@@ -44,10 +58,19 @@ const assertions = [
   ['frontend consumes working event', activityHook.includes("'channel:agent:working'")],
   ['frontend consumes typing event', activityHook.includes("'channel:agent:typing'")],
   ['frontend activity TTL distinguishes work from typing', activityHook.includes('thinking: 6_000') && activityHook.includes('typing: 5_000') && activityHook.includes('working: 30_000')],
+  ['frontend consumes documented task comment events', taskHook.includes("'task:comment':") && taskHook.includes("'task:comment_updated':") && taskHook.includes("'task:comment_deleted':") && taskHook.includes("'task:comment_reacted':")],
   ['completion has an evidence failure gate', watcher.includes('WORK_CYCLE_FAILED')],
-  ['Codex policy rejection is captured from stderr', watcher.includes("stdio: ['ignore', 'pipe', 'pipe']") && watcher.includes('inspectDiagnostic(d)')],
+  ['OpenCode emits structured events for runtime evidence', watcher.includes("'--format', 'json'") && watcher.includes('opencodeEventEvidence(event)')],
+  ['OpenCode acknowledgements cannot satisfy coding completion', watcher.includes("agent === 'codex' || agent === 'opencode'") && watcher.includes('releaseTaskForRetry(activeTaskRef, prompt)')],
+  ['Codex policy rejection is captured from stderr', watcher.includes("stdio: ['ignore', 'pipe', 'pipe']") && watcher.includes('forwardDiagnostic(d)') && watcher.includes('inspectDiagnostic(incoming)')],
+  ['Codex recoverable subprocess diagnostics are not surfaced as activity', watcher.includes('shouldSuppressCodexDiagnostic(line)') && watcher.includes("forwardDiagnostic('', true)") && watcher.includes('RECOVER DEAD COMMAND SESSIONS')],
   ['policy rejection cannot be logged as successful', watcher.includes("subtype = policyBlock ? 'blocked'")],
   ['policy-blocked tickets are persisted and paused', watcher.includes('blockedTasks: [...blockedTasks]') && watcher.includes('WORK_CYCLE_BLOCKED')],
+  ['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

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