openvisio-agent 0.21.1 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.23.0] — 2026-09-10
+
+- Add local semantic and keyword search over recorded conversations with source references, bounded retention, edit replacement, and backend/agent isolation.
+- Add live assignment lookup and intent-based discovery of currently advertised tools, including a task-offer cue in every agent cycle.
+- Expose two on-demand Mastra skills for assignment handling and conversation recall through the native runtime MCP bridge.
+- Run local embedding inference outside the agent loop, preserve keyword fallback during model download/failure, and keep live task state authoritative.
+- Known dependency finding: FastEmbed's ONNX installer inherits the `adm-zip` audit findings documented in the README. Local and simulated runtime tests pass; live team/model behavior requires validation in a safe test organization.
+
+## [0.22.0] — 2026-09-10
+
+- Carry the agent’s configured role and voice through every session, with cached identity when the roster is unavailable.
+- Let agents request their own coding workspace and carry forward findings without asking teammates to reassign work. Record the continuation in the source context graph and Studio.
+- Bound graph recall to direct source neighbors so shared nodes cannot pull in unrelated conversations.
+
+- Let the agent's native final turn end a cycle. Remove required code mutations, ticket updates, PR evidence, and forced recovery turns from the completion decision.
+- Deliver and persist the agent's actual response, including research, questions, and blockers, without automatically completing the ticket or rerunning an unchanged assignment after restart.
+- Expose advertised MCP capabilities independently of scheduling classification; allow native reading, search, browsing, planning, and context tools in reply sessions while keeping local writes scoped to coding workspaces.
+- Keep Claude context warm like Codex and OpenCode, tolerate unavailable optional history, and treat runtime deadlines as inactivity watchdogs.
+
 ## [0.21.1] — 2026-09-10
 
 - Recover identifier-owned assignments even when the agent is missing from `list_agents` or the roster request fails. Keep numeric-assignee compatibility, fresh ticket verification, and reassignment guards.

package/README.md

@@ -62,13 +62,28 @@ Runs the **autonomy loop** — the agent replies to @mentions and picks up ticke
 
 Codex and OpenCode cycles run through Mastra's ACP harness. Codex uses the packaged `codex-acp` adapter and reuses the machine's existing ChatGPT/Codex login; OpenCode uses its native `opencode acp` server. Each accepted ticket gets its own ACP session and worktree. Mastra Memory stores ticket/thread context in local libSQL under `~/.openvisio/`, while a compact JSON ledger retains only exact replay, cancellation, and delivery keys.
 
+Backend watchers also provide four local context tools through the authenticated MCP bridge:
+
+| Tool | Purpose |
+| --- | --- |
+| `openvisio_list_my_tasks` | Read live pending assignments, including when someone says “I have a task for you.” Does not claim or start work. |
+| `openvisio_find_tools` | Search currently advertised tools by intent and return their actual input schemas, plus available skill descriptions. |
+| `openvisio_search_conversations` | Search recorded conversations by meaning and keywords, optionally narrowed to a channel or thread. |
+| `openvisio_load_skill` | Load the `openvisio-work` or `conversation-recall` skill when useful, including after compaction. |
+
+Conversation search combines Mastra's `LibSQLVector` with local BGE-small embeddings from `@mastra/fastembed` and keyword ranking. The first search downloads the model; inference then runs locally without an embedding API key. A worker handles inference independently of the agent loop. Search reports `embeddingStatus` and returns keyword results during download or failure. No conversation text is sent to an embedding provider.
+
+The corpus contains accepted messages and messages obtained through successful `list_message_thread` or `post_message` calls. It does not automatically crawl the whole organization. Results include authors, timestamps when supplied, observation times, and source IDs. Messages retain up to 24,000 characters and are stored as overlapping excerpts, with a 5,000-excerpt retention cap per backend/agent. Observed edits replace previous content; observed deletions remove it. Deleted or changed messages not yet observed can remain in local history: verify material facts against live tools. Exact graph context and current ticket checks remain separate from historical search.
+
+The integration follows Mastra's [semantic memory](https://mastra.ai/docs/memory/semantic-recall), [skills](https://mastra.ai/docs/skills), [harness](https://mastra.ai/docs/harness/overview), and [workflow](https://mastra.ai/docs/workflows/overview) documentation. The two built-in skills use `createSkill()` and are exposed to native coding runtimes through MCP. Native project skills and context compaction remain owned by the selected runtime. Workflows coordinate predictable application steps; they do not prescribe the agent's investigation or decide whether its ticket is complete.
+
 Model selections are stable. Exact IDs (including reasoning effort) are preserved. An unsuffixed ACP model may resolve once to the same model with `medium` effort; the watcher saves that exact selection. Unavailable selections produce an explicit error rather than switching generations or families. Claude versioned IDs are preserved, with automatic family fallbacks disabled. Codex uses the configured chat model for replies.
 
 Backend/BYO watchers reconcile immediately whenever the process starts or the WebSocket connects. A direct MCP session discovers and caches the backend's actual `tools/list` response, then uses available tools such as `list_agents`, `list_projects`, `list_tasks`, `list_task_types`, and `list_activity` to recover assigned tasks and recent mention activity missed while offline. Optional actions such as ticket comments are used only when advertised; their absence cannot strand a completed ticket in a retry loop. The same zero-model check runs every five minutes as a safety net; a model starts only when pending work exists.
 
 The backend MCP may be stateful or stateless. A successful initialize response without `Mcp-Session-Id` is accepted as stateless, so OpenCode agents do not stop with “MCP initialize returned no session id.” Each OpenCode lane keeps its MCP identity in a private per-agent config directory while the repository is supplied separately with `--dir`; stale workspace configuration therefore cannot swap one agent's credentials for another's. The generated remote configuration sends the agent headers directly, disables OAuth probing, and backend cycles never request relay-only inbox calls or MCP resource-discovery tools in place of team actions.
 
-Codex BYO agents follow the repository's normative runtime specification in `docs/CODEX_BYO_AGENT_SPEC.md`: one WebSocket identity, independent reply/work queues, authoritative `get_ticket` verification for assignments, silent transient activity, persistent replay suppression, and runtime evidence gates before completion. Maintainers must run `npm run certify` before publishing.
+Codex BYO agents follow the repository's normative runtime specification in `docs/CODEX_BYO_AGENT_SPEC.md`: one WebSocket identity, independent reply/work queues, authoritative `get_ticket` verification for assignments, silent transient activity, persistent replay suppression, and agent-controlled turn completion. Maintainers must run `npm run certify` before publishing.
 
 Both `agent:mention` and organization `channel:message` events pass through the same source-recipient, ownership, and deduplication checks before any model starts. The watcher subscribes only to the organization verified from its own authenticated agent profile and restores that subscription after reconnect. Self-authored source messages are ignored; embedded old agent replies cannot hide a human follow-up. An explicit tag establishes durable ownership of that thread, so later human follow-ups remain addressed to the agent without another @mention. Messages redirected to another agent and unaddressed agent chatter stay silent, while a direct stand-down cancels queued/running work and releases ownership for that thread. Concrete roots verified as belonging to someone else have a bounded one-minute cache; missing authors and failed reads remain immediately retryable. The watcher does not broadcast working, thinking, or typing presence updates. Claude and OpenCode may add one concrete progress update after work begins, but must continue and post a distinct verified result or blocker afterward; Codex keeps cancellation-safe delivery watcher-owned and renders the verified final answer once.
 
@@ -83,6 +98,10 @@ openvisio-agent watch --name ada --workdir ~/repo  # allow REAL work on a git br
 openvisio-agent stop --name ada                  # stop service + every ada watcher
 ```
 
+Agents choose their tools, investigation steps, context management, and when to end a turn. Each turn receives the agent’s configured identity, role, and voice when supplied by its profile; that context is cached across restarts. Reply sessions can request their configured coding workspace through `openvisio_request_work_session`, carrying their findings, source thread, and permissions into the continuation. They do not ask you to reassign work because of an internal scheduling choice. A successful native final turn ends the cycle; it does not mark a ticket done. The agent decides when to update the board. Research, audits, and already-satisfied requests can finish without code changes, ticket mutations, or a PR. Tool failures stay visible as diagnostics without forcing another model turn or replacing the agent's explanation.
+
+The context graph records source-to-continuation relationships and recalls direct neighbors without walking into unrelated conversations. The watcher saves the agent's final response for delivery retry and avoids rerunning an unchanged assignment after restart. Claude, Codex, and OpenCode keep context within a ticket or conversation; native runtimes handle compaction. A stalled-session watchdog resets when activity arrives, so ongoing work is not stopped by a fixed task duration. Ownership, cancellation, delivery deduplication, credential injection, and repository permissions remain enforced.
+
 The watcher can run up to three assigned coding tasks concurrently. Each ticket gets an isolated model runtime and ticket-specific worktree; tasks sharing the same mutable workspace remain serialized to prevent branch and file conflicts. Replies to one thread stay serialized while up to three independent threads run concurrently, and cancellation targets only the matching ticket or source thread. The work pool reuses local clones and is instructed to preserve dirty/staged work, create unique branches, and stage only task-owned changes. The independent reply lane receives a chat charter and no coding workspace. Codex publishes local branches through the constrained helper, then opens a PR with `gh pr create`; linked-codebase MCP operations are a fallback when the repository cannot be obtained locally.
 
 PR publishing is part of normal coding setup. `connect` authorizes the selected `--workspace` (or `~/openvisio-workspace`) for routine agent-branch pushes and installs the constrained Codex helper rule. New clones and linked worktrees inherit that workspace authority. Existing coding configurations migrate on their next watcher start. Use `--no-pr-push` during setup to opt out.
@@ -107,7 +126,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 setup grants routine PR publishing inside its workspace through a no-argument `agent/*`-only helper. Repositories outside that workspace need an exact repository grant. The helper cannot merge or push protected branches.
+- **Scoped workspace access.** Chat sessions can discover advertised MCP actions and use reading, search, browsing, planning, and context tools. Local writes and shell execution require a coding workspace. Coding setup grants routine PR publishing inside its workspace through a no-argument `agent/*`-only helper. Repositories outside that workspace need an exact repository grant. The helper cannot merge or push protected branches.
 - **Local secrets.** Your agent key lives in `~/.openvisio/` with `600` permissions — never printed, never committed.
 
 ## Requirements
@@ -156,4 +175,8 @@ Watchers running this version record bounded, credential-redacted activity under
 
 `npm test` includes the executable BYO scenario catalogue. `npm run test:scenarios -- --report /tmp/byo-results.json` writes every case, result, category, and duration. Cases cover routing, runtime lifecycle, transport, memory, authorization, and complete watcher sequences against simulated service/runtime boundaries. They do not invoke paid models or mutate a live workspace.
 
+`node scripts/smoke-context-search.mjs` explicitly downloads the local embedding model and tests paraphrase retrieval against synthetic conversations. Set `OPENVISIO_SEARCH_SMOKE_DIR` to a persistent temporary directory to reuse that model download between runs. Ordinary tests use deterministic injected embeddings and require no model download.
+
+Dependency review (2026-09-10): `@mastra/fastembed@1.3.1` pins `onnxruntime-node@1.26.0`, whose installer depends on `adm-zip@0.5.x`. npm reports a [high-severity ZIP allocation issue](https://github.com/advisories/GHSA-xcpc-8h2w-3j85) and a [symlink extraction issue](https://github.com/advisories/GHSA-vwc7-r8mq-g2x9), propagated to the parent dependencies. Conversation text does not enter this ZIP installer; the unresolved dependency findings still need an upstream update before claiming a clean audit.
+
 The watcher now stores pending threaded replies before posting and retries their authoritative delivery checks without rerunning the model. Distinct source message IDs remain distinct requests even when their text is identical. Stable agent IDs take precedence over display names at every assignment gate.

package/USER_GUIDE.md

@@ -4,6 +4,14 @@ Connect your coding agent to your team, let it handle assigned work, and follow
 
 Already connected? Jump to [start your watcher](#start-your-watcher), [open Agent Studio](#open-agent-studio), or [solve a problem](#solve-a-problem).
 
+## Finding work and earlier conversations
+
+You can tell your agent “I have a task for you” or ask it to check its assignments. Its local tool guide explains how to read the live board, discover available tools, and load short skills when needed. Looking up assignments does not itself claim or complete a ticket.
+
+For earlier context, ask something like “What did we decide about credential storage?” The agent can search conversations it has recorded, with channel and thread references for checking the original discussion. This includes messages it has received and threads it has fetched; it is not a search of every conversation in your organization.
+
+The first semantic search downloads a local embedding model. Keyword search remains available while it loads, and later searches run on your computer without an embedding API key. Search history survives watcher restarts. The agent still chooses which tools and skills to use, how to manage its context, and when to finish its turn.
+
 ## Before you begin
 
 You need Node.js **22.13 or newer**, access to your OpenVisio team, and a supported coding agent: Claude Code, Codex, or OpenCode. Authenticate your chosen coding agent on this machine before asking it to work. Your provider’s usual usage limits and charges apply when the agent runs.
@@ -91,7 +99,7 @@ The demo makes no model calls. Close it with `Ctrl+C` in its terminal and run St
 ### Find a result
 
 1. Select an agent in the sidebar.
-2. Select **Cycles**. A cycle is a group of actions for one unit of work.
+2. Select **Cycles**. A cycle is one agent turn, including its tool calls. The agent chooses when to finish; ticket completion is a separate action.
 3. Search for the ticket reference, such as `OVS-57`, and select the matching row.
 4. Switch between **Plan**, **Commands**, and **Response** to inspect steps, tool calls, and the final response. Expand **Runtime details** or **Cycle history** for more context.
 
@@ -113,7 +121,7 @@ Watchers running version **0.21.0 or newer** apply saved settings to the next re
 | --- | --- |
 | Live | Your browser is connected to Studio. Each watcher has its own connection status. |
 | Queued / Active | Work is waiting or running in the current watcher run. |
-| Completed | The selected action or cycle reported completion. Review the final result and ticket. |
+| Completed | The selected action finished, or the agent ended its turn. This does not automatically mark a ticket done. Review the final response for the outcome. |
 | Blocked / Failed / Timed out | Read the outcome and watcher log. Resolve the stated cause before requesting more work. |
 | Offline | The watcher stopped reporting or restarted. An unfinished cycle has no known final outcome in the available history. |
 | No explicit plan recorded | No plan was provided in the available history. This alone is not a failure. |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openvisio-agent",
-  "version": "0.21.1",
-  "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team \u2014 MCP tools + optional autonomy \u2014 in one command.",
+  "version": "0.23.0",
+  "description": "Connect Claude Code, Codex, or OpenCode to an OpenVisio team — MCP tools + optional autonomy — in one command.",
   "type": "module",
   "bin": {
     "openvisio-agent": "bin/cli.mjs"
@@ -43,6 +43,7 @@
     "@agentclientprotocol/codex-acp": "1.10.0",
     "@mastra/acp": "0.4.1",
     "@mastra/core": "1.64.0",
+    "@mastra/fastembed": "1.3.1",
     "@mastra/libsql": "1.22.3",
     "@mastra/memory": "1.28.2"
   }

package/scenarios/runtime.scenarios.mjs

@@ -27,10 +27,10 @@ const formats = [
 
 // Tool identity, runtime representation, and lane capability are independent
 // dimensions: every row checks the actual permission boundary, not a snapshot.
-for (const tool of [...readTools, ...coordinationTools, ...repositoryTools, ...localTools]) {
+for (const tool of [...readTools, ...coordinationTools, ...repositoryTools]) {
   for (const mode of modes) for (const format of formats) {
     add(`permission-${mode.name}-${format.name}-${tool}`, 'runtime-permissions', `${mode.name} handles ${tool} from ${format.name} with only that lane's authority`, async () => {
-      const permitted = mode.canCode || readTools.includes(tool) || (mode.canCoordinate && coordinationTools.includes(tool))
+      const permitted = mode.canCode || !localTools.includes(tool)
       const result = acpPermissionResponse({ options: permissionOptions, toolCall: format.call(tool) }, mode)
       assert.equal(result.outcome.optionId, permitted ? 'yes' : 'no')
     })
@@ -317,12 +317,7 @@ for (const agent of ['codex', 'opencode']) for (const mode of modes) for (const
         assert.equal(server.command, process.execPath)
         const env = Object.fromEntries(server.env.map(({ name, value }) => [name, value]))
         const allowed = JSON.parse(env.OPENVISIO_CODEX_ALLOWED_TOOLS)
-        if (mode.canCode) assert.equal(allowed, null)
-        else {
-          assert.ok(allowed.includes('get_ticket'))
-          assert.equal(allowed.includes('update_ticket'), mode.canCoordinate)
-          assert.equal(allowed.includes('write_codebase_file'), false)
-        }
+        assert.equal(allowed, null, 'Scheduling lanes do not hide advertised capabilities')
       }
       if (agent === 'opencode') {
         const value = JSON.parse(config.env.OPENCODE_CONFIG_CONTENT)
@@ -353,10 +348,10 @@ for (const change of ['same', 'cwd', 'disabled-tools', 'model']) {
 }
 
 for (const localTool of localTools) {
-  add(`opencode-local-denial-${localTool}`, 'runtime-session-config', `OpenCode reply configuration denies inherited ${localTool} access globally and at agent level`, async () => {
+  add(`opencode-local-denial-${localTool}`, 'runtime-session-config', `OpenCode reply configuration scopes ${localTool} access globally and at agent level`, async () => {
     const config = buildOpencodeConfig({ canCode: false, mcpUrl: 'https://fixture.invalid/mcp', mcpHeaders: headers })
-    assert.equal(config.permission[localTool], 'deny')
-    assert.equal(config.agent['openvisio-reply'].permission[localTool], 'deny')
+    assert.equal(config.permission[localTool], ['read', 'task'].includes(localTool) ? 'allow' : 'deny')
+    assert.equal(config.agent['openvisio-reply'].permission[localTool], ['read', 'task'].includes(localTool) ? 'allow' : 'deny')
     assert.equal(config.mcp['openvisio-team'].oauth, false)
     assert.equal(config.mcp['openvisio-team'].headers['x-agent-api-key'], 'fixture-secret-key')
   })

package/scenarios/workspace.scenarios.mjs

@@ -16,7 +16,7 @@ async function eventually(predicate, description) {
   assert.fail(`Watcher did not reach: ${description}`)
 }
 
-export function fixture({ agent = 'codex', task = true, run, threadError = false, commentTools = [], onComment, selfProfile = self, listAgents, getTicket } = {}) {
+export function fixture({ agent = 'codex', task = true, run, threadError = false, commentTools = [], onComment, selfProfile = self, listAgents, getTicket, listChannels } = {}) {
   const dir = mkdtempSync(join(tmpdir(), 'byo-workspace-'))
   const posts = [], runs = [], calls = [], logs = [], messages = [], subscriptions = []
   const ticket = { id: 77, project_id: 1, slug: 'OPEN-77', title: 'Repair the component', agent_id: 7, status: 'In Progress', type_id: 1, updated_at: 'revision-1' }
@@ -33,6 +33,7 @@ export function fixture({ agent = 'codex', task = true, run, threadError = false
       if (name === 'list_task_types') return { types: [{ id: 1, name: 'In Progress' }, { id: 2, name: 'Testing' }, { id: 3, name: 'Done' }] }
       if (name === 'get_ticket') { assert.equal(args.project_id, 1); assert.equal(args.ticket_id, 77); return { ticket: getTicket ? getTicket(ticket) : { ...ticket } } }
       if (name === 'update_ticket') { Object.assign(ticket, args); return { ticket: { ...ticket } } }
+      if (name === 'list_channels' && listChannels) return { channels: await listChannels() }
       if (name === 'list_channels') return { channels: [{ id: 2, name: 'alex', agent_id: 7 }, { id: 9, name: 'general' }] }
       if (name === 'list_activity') return { activities: [] }
       if (name === 'list_message_thread') {

package/scripts/certify.mjs

@@ -55,7 +55,7 @@ const assertions = [
   ['review and testing handoffs do not restart work', watcher.includes('taskIsAwaitingReview(task, reviewIds)') && watcher.includes('taskIsAwaitingReview(ticket, typeSets.review)')],
   ['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('postMessageOnce({ key: `completion:${report.key}`')],
-  ['completion requires review/done state and PR evidence', watcher.includes('buildTaskCompletionReport') && watcher.includes('completion report deferred')],
+  ['agent results are delivered independently of ticket completion', watcher.includes('agentFinal: true') && watcher.includes('pendingAgentResults')],
   ['completion delivery survives reconnect and deduplicates', watcher.includes('pendingCompletionReports: [...pendingCompletionReports]') && watcher.includes('reportedCompletions: [...reportedCompletions]') && watcher.includes('reportedCompletions.has(report.key)')],
   ['optional ticket comments cannot block verified completion', watcher.includes('callOptionalTicketComment({ projectId, ticketId, content: report.content })') && watcher.includes('no ticket comment tool is exposed; completing ticket') && watcher.includes('reportedTaskComments: [...reportedTaskComments]') && watcher.includes('reportedTaskComments.has(report.key)')],
   ['ticket comments prefer the advertised modern schema with legacy compatibility', watcher.includes("names.has('create_task_comment') ? 'create_task_comment' : names.has('comment_ticket') ? 'comment_ticket' : ''") && watcher.includes("name === 'create_task_comment' ? { content } : { text: content }")],
@@ -75,7 +75,7 @@ const assertions = [
   ['human-facing ticket references require slugs, never database ids', watcher.includes('TICKET SLUGS, NEVER DATABASE IDS') && watcher.includes('ticketDisplaySlug(task)') && events.includes('export function ticketDisplaySlug') && !events.includes('I finished ticket #${task.id}')],
   ['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']") && codexConfig.includes('disabled_tools = [')],
-  ['ACP sessions receive the authenticated OpenVisio proxy', mastraHarness.includes("name: 'openvisio-team-watcher'") && mastraHarness.includes('OPENVISIO_CODEX_MCP_URL') && watcher.includes('missingRuntimeWorkEvidence(result')],
+  ['ACP sessions receive the authenticated OpenVisio proxy', mastraHarness.includes("name: 'openvisio-team-watcher'") && mastraHarness.includes('OPENVISIO_CODEX_MCP_URL')],
   ['Codex discovers deferred OpenVisio actions before claiming they are missing', watcher.includes('Codex may defer MCP actions') && watcher.includes('use tool_search to find that exact action') && watcher.includes('initial-list miss is NOT evidence that the server is disconnected')],
   ['Codex authentication is injected outside the model', codexConfig.includes('OPENVISIO_CODEX_API_KEY') && codexProxy.includes('toolWithoutCredentialInputs') && codexProxy.includes('client.callTool') && watcher.includes('local OpenVisio MCP bridge injects authentication outside the model')],
   ['reply delivery keys survive reconnects', watcher.includes('deliveredReplies: [...deliveredReplies]') && watcher.includes('deliveredReplies.has(deliveryKey)')],
@@ -106,18 +106,18 @@ const assertions = [
   ['bare-agent runs handle one source conversation', bareRun.includes('messageId?: string') && bareRun.includes('const targetRoot = target.parentId ?? target.messageId') && bareDriver.includes('messageId: source.messageId')],
   ['bare-agent posts have a live conversation guard', bareRun.includes('const canPostMessage') && bareRun.includes('{ canPostMessage }') && bareRuntime.includes('reply suppressed because the live thread was redirected, cancelled, or already answered')],
   ['quick replies preserve distinct top-level conversations', quickReply.includes('m.parentId ?? m.messageId') && quickReply.includes('...(parentId ? { parentId } : {})')],
-  ['completion has an evidence failure gate', watcher.includes('WORK_CYCLE_FAILED')],
-  ['failed evidence revisions persist and suppress self-triggered retries', watcher.includes('failedTaskVersions: [...failedTaskVersions]') && watcher.includes("failedTaskVersions.set(key, 'pending')") && watcher.includes('failedTaskRevisionIsCurrent(failedRevision, ticket)') && watcher.includes('ticket paused until its revision changes')],
+  ['completion follows the native agent turn without a forced recovery', watcher.includes("cycleControl.finishedBy = 'agent'") && !watcher.includes('missingRuntimeWorkEvidence') && !watcher.includes('cycle.recovery')],
+  ['runtime failures persist without restoring legacy evidence gates', watcher.includes('failedTaskVersions: [...failedTaskVersions]') && watcher.includes("replayState.completionPolicy === 'agent'") && watcher.includes('failedTaskRevisionIsCurrent(failedRevision, ticket)')],
   ['assigned coding tickets prefer their prepared local worktree', watcher.includes('findTicketWorktree(workdir, ticketId)') && watcher.includes('A prepared local git worktree for this ticket exists') && mastraHarness.includes('cwd: cycleCwd') && watcher.includes('workdir: ticketWorktree')],
   ['ACP evidence requires completed tools', mastraHarness.includes("if (tool.status !== 'completed') continue") && mastraHarness.includes('codexPolicyBlock(json(tool.rawOutput))')],
   ['OpenCode API-key MCP disables OAuth probing', opencodeConfig.includes("oauth: false") && opencodeConfig.includes('timeout: 15_000')],
   ['OpenCode ACP isolates server identity and reply permissions', mastraHarness.includes('OPENCODE_CONFIG_CONTENT') && mastraHarness.includes('buildOpencodeConfig({ canCode })') && mastraHarness.includes('mcpServers,')],
-  ['OpenCode backend prompts forbid relay and resource-discovery tools', watcher.includes('BACKEND MCP RULE') && ['get_marching_orders', 'poll_inbox', 'get_resource', 'list_mcp_resources', 'list_mcp_resource_templates'].every((name) => watcher.includes(name))],
+  ['agents can discover tools and choose context', watcher.includes('TOOL DISCOVERY') && watcher.includes('context compaction')],
   ['ACP tool failures retain sanitized diagnostics', mastraHarness.includes('for (const [name, detail] of errors)') && mastraHarness.includes('redact(detail)')],
-  ['all runtime acknowledgements cannot satisfy coding completion', watcher.includes('missingRuntimeWorkEvidence(result') && watcher.includes('claudeEventEvidence(o, turnToolUses)') && watcher.includes('releaseTaskForRetry(activeTaskRef, prompt)')],
+  ['tool telemetry remains separate from the native final response', watcher.includes('claudeEventEvidence(o, turnToolUses)') && watcher.includes('outputText: finalText')],
   ['ACP prose cannot masquerade as repository evidence', mastraHarness.includes("if (event.type === 'text') { outputText += event.text; continue }") && mastraHarness.includes("if (tool.status !== 'completed') continue")],
   ['ACP MCP failures retain sanitized per-call diagnostics', mastraHarness.includes('mcpErrorDetails: Object.fromEntries(errors)') && mastraHarness.includes("join('[redacted]')")],
-  ['coding recovery retains source context and requires a final result', watcher.includes('ORIGINAL REQUEST AND ROUTING CONTEXT') && events.includes('resultMessageRequired && !result?.didResultMessage') && events.includes("outputText: second?.outputText || first?.outputText || ''")],
+  ['same-source context stays warm across native turns', !watcher.includes('MAX_TURNS') && mastraHarness.includes('persistSession: true')],
   ['backend MCP accepts stateless initialize responses', mcpHttp.includes("mode = () => !initialized ? 'uninitialized' : sessionId ? 'stateful' : 'stateless'") && !watcher.includes('MCP initialize returned no session id')],
   ['MCP initialize is shared across concurrent startup probes', mcpHttp.includes('if (initializePromise) return initializePromise')],
   ['stateless tool errors do not cause initialize loops', mcpHttp.includes('if (hadSession && !retried')],
@@ -129,17 +129,17 @@ const assertions = [
   ['policy rejection cannot close a work cycle', mastraHarness.includes("subtype: policyBlock ? 'blocked' : 'ok'") && watcher.includes("result?.subtype === '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')],
-  ['BYO coding prefers an existing local repository', watcher.includes('A usable local clone is your primary code surface') && watcher.includes('do not use remote codebase tools') && watcher.includes('Remote codebase tools are a fallback only when the repository cannot be obtained locally')],
+  ['BYO coding prefers an existing local repository', watcher.includes('A usable local clone is your primary code surface') && watcher.includes('Remote codebase tools are a fallback only when the repository cannot be obtained locally')],
   ['Codex publishes local branches with the constrained helper', watcher.includes('CODEX PR DELIVERY') && watcher.includes('openvisio-agent push-pr-branch') && watcher.includes('Use list_codebases/create_codebase_branch/create_codebase_commit/create_pull_request only as a fallback') && 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', identity.remote, destination")],
   ['PR push helper restricts branch and destination within setup authority', prPush.includes('isSafeAgentBranch(branch)') && prPush.includes('policyAllows(') && 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, delivery)') && watcher.includes("The local runtime rejected")],
   ['blocker routing carries explicit task identity', watcher.includes('const activeTaskRef = taskRef') && watcher.includes('taskRef: activeTaskRef')],
-  ['reply discovery failures stay scoped while failed mutations fail closed', watcher.includes('blockingReplyMcpErrors(result?.mcpErrors)') && watcher.includes('preserving the scoped model reply') && events.includes('export function blockingReplyMcpErrors')],
+  ['agents retain control of their response after tool failures', watcher.includes('agent ended its turn with tool diagnostics') && !watcher.includes('blockingReplyMcpErrors')],
   ['pending-ticket questions use watcher-owned MCP reads without a chat model cycle', watcher.includes('conversationAsksPendingTickets(text)') && watcher.includes('pending-ticket question -> watcher-owned MCP lookup') && watcher.includes("callMcpReadWithRetry('list_tasks'")],
-  ['chat ACP allows opaque MCP approvals behind a strict read-only proxy', mastraHarness.includes('export function acpPermissionResponse') && mastraHarness.includes('opaqueMcpApproval') && mastraHarness.includes('OPENVISIO_CODEX_ALLOWED_TOOLS') && codexProxy.includes('export function toolAllowed') && codexProxy.includes('allowedTools.has(name)')],
-  ['all runtime blockers have a delivery path', watcher.includes('publishBlocker') && watcher.includes('WORK_CYCLE_BLOCKED') && watcher.includes('COORDINATION_CYCLE_BLOCKED')],
+  ['chat ACP discovers advertised tools through the authenticated proxy', mastraHarness.includes('opaqueMcpApproval') && !mastraHarness.includes('CHAT_SAFE_MCP_READS') && codexProxy.includes('export function toolAllowed')],
+  ['runtime failures have a delivery path', watcher.includes('publishBlocker') && watcher.includes('WORK_CYCLE_BLOCKED')],
   ['ticket blocker cannot self-authorize', watcher.includes("ticketNotice = `I'm paused") && watcher.includes('publishBlocker({ prompt, taskRef, delivery, notice, ticketNotice, pause: true })') && !watcher.includes('test(approvalText)')],
   ['agent messages use first-person voice', watcher.includes('FIRST-PERSON VOICE') && watcher.includes("I'm blocked") && !watcher.includes('Alex is blocked') && !watcher.includes('Alex is paused')],
   ['normative certification gates are documented', spec.includes('## Mandatory certification gates')],

package/scripts/smoke-context-search.mjs

@@ -0,0 +1,33 @@
+// Explicit opt-in integration check: downloads Mastra's local embedding model.
+// Uses synthetic conversations only. Keep OPENVISIO_SEARCH_SMOKE_DIR between
+// runs to reuse the model download; otherwise the temporary cache is removed.
+import assert from 'node:assert/strict'
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createContextSearch } from '../src/context-search.mjs'
+
+const directory = process.env.OPENVISIO_SEARCH_SMOKE_DIR || mkdtempSync(join(tmpdir(), 'openvisio-semantic-smoke-'))
+mkdirSync(directory, { recursive: true })
+const search = createContextSearch({ directory, resourceId: 'synthetic-smoke' })
+try {
+  search.remember({ key: 'security', text: 'Keep production credentials in the vault and rotate them monthly.', refs: { channelId: 1, messageId: 1 } })
+  search.remember({ key: 'lunch', text: 'The team is ordering pizza for lunch on Friday.', refs: { channelId: 1, messageId: 2 } })
+  search.remember({ key: 'work', text: 'Alex owns the pending ticket to repair the login form.', refs: { channelId: 1, messageId: 3 } })
+  await search.search({ query: 'How should we protect passwords?', waitMs: 1 })
+  await search.settled()
+  const result = await search.search({ query: 'How should we protect passwords?', limit: 1, waitMs: 10_000 })
+  assert.equal(result.mode, 'hybrid', JSON.stringify(result))
+  assert.equal(result.matches[0]?.key, 'security', JSON.stringify(result))
+  assert.equal(result.matches[0]?.match, 'semantic', 'Paraphrase has no overlapping keywords')
+  const assignments = await search.search({ query: 'Who is fixing the sign-in bug?', limit: 1, waitMs: 10_000 })
+  assert.equal(assignments.matches[0]?.key, 'work', JSON.stringify(assignments))
+  assert.equal(assignments.matches[0]?.match, 'semantic')
+  const vague = await search.search({ query: 'What assignments need attention?', limit: 1, waitMs: 10_000 })
+  assert.equal(vague.matches.length, 0, 'Weak similarity must not invent an answer to a vague request')
+  console.log('Real local embeddings retrieved the security conversation from a paraphrased query.')
+  console.log('Real local embeddings also recovered the pending work discussion by intent.')
+} finally {
+  await search.close()
+  if (!process.env.OPENVISIO_SEARCH_SMOKE_DIR) rmSync(directory, { recursive: true, force: true })
+}

package/src/codex-mcp-proxy.mjs

@@ -1,7 +1,9 @@
 import { createInterface } from 'node:readline'
 import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { WORK_SESSION_TOOL, runtimeControlTools, requestWorkSession } from './runtime-control.mjs'
 import { createMcpHttpClient } from './mcp-http.mjs'
+import { contextTools, contextToolNames, callContextService, validateContextArguments } from './context-tools.mjs'
 
 export function toolWithoutCredentialInputs(tool) {
   const copy = structuredClone(tool)
@@ -78,9 +80,26 @@ export function runCodexMcpProxy() {
   const url = process.env.OPENVISIO_CODEX_MCP_URL
   const apiKey = process.env.OPENVISIO_CODEX_API_KEY
   const identifier = process.env.OPENVISIO_CODEX_IDENTIFIER
+  const capabilities = { canCode: process.env.OPENVISIO_CAN_CODE === 'true', workspaceAvailable: process.env.OPENVISIO_WORKSPACE_AVAILABLE === 'true' }
+  const contextEnvironment = { OPENVISIO_CONTEXT_URL: process.env.OPENVISIO_CONTEXT_URL, OPENVISIO_CONTEXT_TOKEN: process.env.OPENVISIO_CONTEXT_TOKEN }
+  const localContext = contextEnvironment.OPENVISIO_CONTEXT_URL && contextEnvironment.OPENVISIO_CONTEXT_TOKEN ? contextTools : []
+  let available = []
   const { disabled, allowed: allowedTools } = proxyToolPolicyFromEnvironment()
   if (!url || !apiKey || !identifier) throw new Error('OpenVisio Codex MCP bridge is missing its watcher environment.')
   const client = createMcpHttpClient({ url, apiKey, identifier, clientVersion: 'openvisio-agent-codex-proxy' })
+  const discoverTools = async () => {
+    const controls = [...runtimeControlTools(capabilities), ...localContext]
+    let remote
+    try { remote = await client.listTools() }
+    catch (error) {
+      if (!controls.length) throw error
+      process.stderr.write('OpenVisio backend discovery is unavailable; local capabilities remain available.\n')
+      remote = []
+    }
+    const tools = [...remote.filter((tool) => tool.name !== WORK_SESSION_TOOL && !contextToolNames.has(tool.name)), ...controls]
+    available = tools.filter((tool) => toolAllowed(tool.name, { disabled, allowed: allowedTools })).map(toolWithoutCredentialInputs)
+    return available
+  }
   const reply = (id, result) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n')
   const fail = (id, error, request) => {
     const message = String(error?.message || error || 'MCP bridge error').split(apiKey).join('[redacted]')
@@ -109,11 +128,24 @@ export function runCodexMcpProxy() {
       } else if (request.method === 'ping') {
         reply(id, {})
       } else if (request.method === 'tools/list') {
-        const tools = await client.listTools()
-        reply(id, { tools: tools.filter((tool) => toolAllowed(tool.name, { disabled, allowed: allowedTools })).map(toolWithoutCredentialInputs) })
+        reply(id, { tools: await discoverTools() })
       } else if (request.method === 'tools/call') {
         const name = String(request.params?.name || '')
         if (!toolAllowed(name, { disabled, allowed: allowedTools })) throw new Error('This tool is disabled for the current delivery lane.')
+        if (name === WORK_SESSION_TOOL) { reply(id, requestWorkSession(request.params?.arguments, capabilities)); return }
+        if (contextToolNames.has(name)) {
+          if (!localContext.length) throw new Error('Local context tools are unavailable')
+          const args = validateContextArguments(name, request.params?.arguments)
+          if (name === 'openvisio_find_tools') await discoverTools()
+          const data = await callContextService(contextEnvironment, { name, arguments: args, availableNames: available.map((tool) => tool.name) })
+          if (name === 'openvisio_find_tools') {
+            // The current proxy is the authority on runtime availability and the
+            // sanitized schema, even if the backend catalog changed mid-search.
+            const catalog = new Map(available.map((tool) => [tool.name, tool]))
+            data.matches = (data.matches || []).filter((tool) => catalog.has(tool.name)).map((tool) => ({ ...catalog.get(tool.name), match: tool.match }))
+          }
+          reply(id, { content: [{ type: 'text', text: JSON.stringify(data) }] }); return
+        }
         let result
         try { result = await client.callTool(name, request.params?.arguments || {}) }
         catch (error) {
@@ -122,6 +154,10 @@ export function runCodexMcpProxy() {
           if (!(allowedTools instanceof Set) || !allowedTools.has(name) || !/^(?:list_|get_|codebase_tree$)/.test(name)) throw error
           result = await client.callTool(name, request.params?.arguments || {})
         }
+        if (localContext.length && ['list_message_thread', 'post_message'].includes(name) && !result?.isError) {
+          try { await callContextService(contextEnvironment, { action: 'observe', name, args: request.params?.arguments || {}, result }, 1000) }
+          catch { /* optional indexing cannot fail the successful backend action */ }
+        }
         reply(id, /^(?:list_agents|get_agent|get_agent_details)$/.test(name) ? agentResultWithoutCredentials(result) : result)
       } else if (id != null) {
         process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found' } }) + '\n')

package/src/context-search.mjs

@@ -0,0 +1,168 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, existsSync, chmodSync } from 'node:fs'
+import { join } from 'node:path'
+import { Worker } from 'node:worker_threads'
+import { LibSQLVector } from '@mastra/libsql'
+import { writeJson } from './lib.mjs'
+
+const hash = (text) => createHash('sha256').update(text).digest('hex')
+const stopWords = new Set('a an and are as at be been by can could did do does for from had has have how i if in is it its me my of on or our should that the their them there these they this to was we were what when where which who will with would you your'.split(' '))
+const words = (text) => new Set((String(text).toLowerCase().match(/[\p{L}\p{N}_-]{2,}/gu) || []).filter((word) => !stopWords.has(word)))
+const waitBriefly = async (promise, ms) => {
+  let timer
+  try { return await Promise.race([promise, new Promise((resolve) => { timer = setTimeout(resolve, ms) })]) }
+  finally { clearTimeout(timer) }
+}
+
+export function createLocalEmbedder({ cacheDir }) {
+  let worker, sequence = 0, closed = false
+  const pending = new Map()
+  const rejectAll = () => {
+    for (const { reject, timer } of pending.values()) { clearTimeout(timer); reject(new Error('Local embedding unavailable')) }
+    pending.clear()
+    const previous = worker; worker = null
+    void previous?.terminate()
+  }
+  return {
+    embed(texts, { query = false } = {}) {
+      if (closed) return Promise.reject(new Error('Local embedding closed'))
+      if (!worker) {
+        worker = new Worker(new URL('./embedding-worker.mjs', import.meta.url), { workerData: { cacheDir } })
+        const current = worker
+        worker.on('error', () => { if (worker === current) rejectAll() })
+        worker.on('exit', () => { if (worker === current) rejectAll() })
+        worker.on('message', ({ id, vectors, error }) => {
+          const job = pending.get(id)
+          if (!job) return
+          pending.delete(id); clearTimeout(job.timer)
+          if (error) job.reject(new Error(error)); else job.resolve(vectors)
+        })
+      }
+      return new Promise((resolve, reject) => {
+        const id = ++sequence
+        pending.set(id, { resolve, reject, timer: setTimeout(rejectAll, 120_000) })
+        worker.postMessage({ id, texts, query })
+      })
+    },
+    async close() { closed = true; const previous = worker; rejectAll(); await previous?.terminate() },
+  }
+}
+
+// Separate from the exact coordination graph: historical messages are searchable
+// evidence, never instructions or the source of live assignment/completion state.
+export function createContextSearch({ directory, resourceId, embedder, vector, maxRecords = 5000, now = Date.now }) {
+  if (!Number.isSafeInteger(maxRecords) || maxRecords < 1 || maxRecords > 20_000) throw new Error('Invalid conversation retention capacity')
+  const scope = hash(String(resourceId)).slice(0, 24)
+  const file = join(directory, `context-${scope}.json`)
+  const database = join(directory, `context-${scope}.db`)
+  const indexName = 'context_bge_small_en_v15_retrieval'
+  const model = embedder || createLocalEmbedder({ cacheDir: join(directory, `embeddings-${scope}`) })
+  const vectors = vector || new LibSQLVector({ id: `context-${scope}`, url: `file:${database}`, maxRetries: 1 })
+  let raw
+  try { raw = JSON.parse(readFileSync(file, 'utf8')) } catch { /* first run */ }
+  const records = new Map((raw?.version === 1 && raw?.resourceId === resourceId && Array.isArray(raw.records) ? raw.records : [])
+    .filter((entry) => entry?.id && typeof entry.text === 'string').map((entry) => [entry.id, entry]))
+  if (raw?.indexName !== indexName || !vector && !existsSync(database)) for (const entry of records.values()) delete entry.indexedHash
+  let closed = false, indexing = null, initialized = false, retryAfter = 0, flushTimer
+  let state = 'idle'
+  const persist = () => { clearTimeout(flushTimer); writeJson(file, { version: 1, resourceId, indexName, records: [...records.values()] }, true) }
+  const schedulePersist = () => { clearTimeout(flushTimer); flushTimer = setTimeout(() => { try { persist() } catch { /* search still works in memory */ } }, 100); flushTimer.unref() }
+  const forget = (key) => {
+    for (const [id, entry] of records) if (entry.key === key) records.delete(id)
+    // Stale vectors are rejected against canonical records, including in-flight
+    // writes. Remove them on the next indexing pass as well.
+    schedulePersist()
+  }
+  const remember = ({ key, kind = 'conversation', text, refs = {}, author = '', timestamp = '', ...rest }) => {
+    if (closed || !key || typeof text !== 'string' || !text.trim()) return
+    const bounded = text.trim().slice(0, 24_000)
+    const chunks = []
+    for (let offset = 0; offset < bounded.length; offset += 1000) chunks.push(bounded.slice(offset, offset + 1200))
+    const ids = new Set()
+    for (let part = 0; part < chunks.length; part++) {
+      const id = hash(`${scope}:${key}:${part}`)
+      ids.add(id)
+      const textHash = hash(JSON.stringify([chunks[part], kind, refs]))
+      const previous = records.get(id)
+      records.set(id, { id, key, kind, text: chunks[part], refs, author, timestamp, part, textHash,
+        indexedHash: previous?.textHash === textHash ? previous.indexedHash : undefined,
+        updatedAt: now(), truncated: text.length > bounded.length, ...(rest.name ? { name: rest.name } : {}) })
+    }
+    for (const [id, entry] of records) if (entry.key === key && !ids.has(id)) records.delete(id)
+    if (records.size > maxRecords) {
+      const oldest = [...records.values()].sort((a, b) => a.updatedAt - b.updatedAt).slice(0, records.size - maxRecords)
+      for (const entry of oldest) records.delete(entry.id)
+    }
+    schedulePersist()
+    if (state !== 'idle') void startIndexing()
+  }
+  const startIndexing = () => {
+    if (closed || indexing || now() < retryAfter) return indexing || Promise.resolve()
+    indexing = (async () => {
+      state = 'indexing'
+      if (!initialized) {
+        await vectors.createIndex({ indexName, dimension: 384, metric: 'cosine' })
+        if (!vector) chmodSync(database, 0o600)
+        initialized = true
+      }
+      // Bound disk growth to retained canonical records. Metadata never contains
+      // conversation text or arbitrary tool outputs.
+      await vectors.deleteVectors({ indexName, filter: { id: { $nin: [...records.keys()] } } })
+      while (!closed) {
+        const batch = [...records.values()].filter((entry) => entry.indexedHash !== entry.textHash).slice(0, 16)
+        if (!batch.length) break
+        const embeddings = await model.embed(batch.map((entry) => entry.text))
+        if (closed) return
+        if (embeddings.length !== batch.length || embeddings.some((v) => v.length !== 384 || v.some((n) => !Number.isFinite(n)))) throw new Error('Invalid local embeddings')
+        await vectors.upsert({ indexName, ids: batch.map((entry) => entry.id), vectors: embeddings,
+          metadata: batch.map((entry) => ({ id: entry.id, key: entry.key, kind: entry.kind, hash: entry.textHash, ...entry.refs })) })
+        for (const entry of batch) if (records.get(entry.id)?.textHash === entry.textHash) records.get(entry.id).indexedHash = entry.textHash
+        schedulePersist()
+      }
+      state = 'ready'
+    })().catch(() => { state = 'unavailable'; retryAfter = now() + 60_000 }).finally(() => { indexing = null })
+    return indexing
+  }
+  const search = async ({ query, kind = 'conversation', channelId, threadId, keys, limit = 6, waitMs = 1000 }) => {
+    if (typeof query !== 'string' || !query.trim() || query.length > 2000) throw new Error('Search query must contain 1–2000 characters')
+    if (!Number.isInteger(limit) || limit < 1 || limit > 12) throw new Error('Search limit must be between 1 and 12')
+    const eligible = (entry) => entry && entry.kind === kind && (!keys || keys.includes(entry.key)) && (channelId == null || String(entry.refs.channelId) === String(channelId)) && (threadId == null || String(entry.refs.threadId) === String(threadId))
+    const tokens = words(query)
+    const ranked = [...records.values()].filter(eligible).map((entry) => {
+      const terms = words(entry.text)
+      return { entry, lexical: [...tokens].reduce((n, token) => n + (terms.has(token) ? 1 : 0), 0) / Math.max(1, tokens.size) }
+    }).filter((hit) => hit.lexical > 0).sort((a, b) => b.lexical - a.lexical || b.entry.updatedAt - a.entry.updatedAt)
+    const scores = new Map(ranked.map((hit, rank) => [hit.entry.id, { entry: hit.entry, score: 1 / (60 + rank), match: 'keyword' }]))
+    await waitBriefly(startIndexing(), waitMs)
+    let mode = 'keyword'
+    if (state === 'ready') {
+      try {
+        const result = await waitBriefly((async () => {
+          const [queryVector] = await model.embed([query], { query: true })
+          return vectors.query({ indexName, queryVector, topK: Math.min(maxRecords, limit * 8), minScore: 0.45,
+            filter: { kind, ...(keys ? { key: { $in: keys } } : {}), ...(channelId == null ? {} : { channelId }), ...(threadId == null ? {} : { threadId }) } })
+        })(), waitMs)
+        if (result) {
+          mode = 'hybrid'
+          result.forEach((hit, rank) => {
+            const entry = records.get(hit.id)
+            if (!eligible(entry) || entry.textHash !== hit.metadata?.hash) return
+            const previous = scores.get(hit.id)
+            scores.set(hit.id, { entry, score: (previous?.score || 0) + 1 / (60 + rank), match: previous ? 'hybrid' : 'semantic' })
+          })
+        }
+      } catch { state = 'unavailable'; retryAfter = now() + 60_000 }
+    }
+    const seen = new Set()
+    const matches = [...scores.values()].filter(({ entry }) => records.get(entry.id)?.textHash === entry.textHash && eligible(records.get(entry.id)))
+      .map((hit) => ({ ...hit, entry: records.get(hit.entry.id) })).sort((a, b) => b.score - a.score).filter(({ entry }) => {
+      if (seen.has(entry.key)) return false
+      seen.add(entry.key); return true
+    }).slice(0, limit).map(({ entry, match }) => ({ key: entry.key, text: entry.text, refs: entry.refs, author: entry.author,
+      timestamp: entry.timestamp, observedAt: new Date(entry.updatedAt).toISOString(), match, part: entry.part, truncated: entry.truncated, ...(entry.name ? { name: entry.name } : {}) }))
+    return { mode, embeddingStatus: state, coverage: 'Locally recorded messages visible to this agent; not the entire team archive.', matches }
+  }
+  return { remember, forget, search, async settled() { await indexing; persist() }, async close() {
+    closed = true; clearTimeout(flushTimer); await model.close?.(); await indexing; persist(); await vectors.close?.()
+  } }
+}