openvisio-agent 0.18.13 → 0.18.15

package/package.json

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

@@ -92,6 +92,8 @@ const assertions = [
   ['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')],
+  ['assigned coding tickets prefer their prepared local worktree', watcher.includes('findTicketWorktree(workdir, ticketId)') && watcher.includes('A prepared local git worktree for this ticket exists') && watcher.includes('Do not call list_codebases, codebase_tree, or get_codebase') && watcher.includes('cwd: cycleCwd') && watcher.includes('workdir: ticketWorktree')],
   ['OpenCode emits structured events for runtime evidence', watcher.includes("'--format', 'json'") && watcher.includes('opencodeEventEvidence(event)')],
   ['OpenCode API-key MCP disables OAuth probing', opencodeConfig.includes("oauth: false") && opencodeConfig.includes('timeout: 15_000')],
   ['OpenCode identities use isolated configs outside the code workspace', watcher.includes('opencodeRuntimeLayout({ cfgKey, workdir })') && watcher.includes("'--dir', workspace") && watcher.includes('OPENCODE_CONFIG: opencodeConfigPath') && watcher.includes('OPENCODE_CONFIG_CONTENT: JSON.stringify(opencodeConfig)')],

package/src/events.mjs

@@ -36,6 +36,23 @@ export function ticketDisplaySlug(task) {
   return typeof value === 'string' ? value.trim().toUpperCase() : ''
 }
 
+// Failed coding cycles are paused at a concrete backend revision. The watcher
+// may write its own blocker onto the ticket after the failure, so a temporary
+// `pending` marker must also count as current until that write is observed.
+export function taskRevision(task) {
+  if (!task || typeof task !== 'object') return ''
+  const value = task.updated_at ?? task.updatedAt ?? task.modified_at ?? task.modifiedAt
+  return value == null ? '' : String(value).trim()
+}
+
+export function failedTaskRevisionIsCurrent(failedRevision, task) {
+  const failed = String(failedRevision || '').trim()
+  if (!failed) return false
+  if (failed === 'pending') return true
+  const current = taskRevision(task)
+  return !current || current === failed
+}
+
 export function taskIsCompleted(task, completedTypeIds = new Set()) {
   if (!task || typeof task !== 'object') return false
   if (task.deleted_at || task.deletedAt || task.completed_at || task.completedAt || task.closed_at || task.closedAt || task.archived_at || task.archivedAt) return true

package/src/watch.mjs

@@ -5,13 +5,13 @@
 // than written to disk from a pasted heredoc.
 
 import { spawn, spawnSync } from 'node:child_process'
-import { closeSync, writeFileSync, mkdirSync, existsSync, openSync, readFileSync, unlinkSync } from 'node:fs'
+import { closeSync, writeFileSync, mkdirSync, existsSync, openSync, readFileSync, readdirSync, unlinkSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 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 { agentAddedByName, agentStateRequest, buildTaskCompletionReport, claudeEventEvidence, classifyConversationTarget, codexEventEvidence, codexPolicyBlock, combineRuntimeWorkEvidence, conversationNeedsCode, mentionDedupeKeys, missingRuntimeWorkEvidence, normalizeRenderedMessageText, opencodeEventEvidence, renderedAgentMessages, shouldSuppressCodexDiagnostic, taskAgentId, taskFromEvent, taskIsAwaitingReview, taskIsCompleted, taskIsCoordinationOnly, ticketDisplaySlug } from './events.mjs'
+import { agentAddedByName, agentStateRequest, buildTaskCompletionReport, claudeEventEvidence, classifyConversationTarget, codexEventEvidence, codexPolicyBlock, combineRuntimeWorkEvidence, conversationNeedsCode, failedTaskRevisionIsCurrent, mentionDedupeKeys, missingRuntimeWorkEvidence, normalizeRenderedMessageText, opencodeEventEvidence, renderedAgentMessages, shouldSuppressCodexDiagnostic, taskAgentId, taskFromEvent, taskIsAwaitingReview, taskIsCompleted, taskIsCoordinationOnly, taskRevision, ticketDisplaySlug } from './events.mjs'
 import { createByoMemoryGraph } from './memory.mjs'
 import { repositoryHasPrPushAuthorization } from './pr-push.mjs'
 import { createMcpHttpClient } from './mcp-http.mjs'
@@ -20,6 +20,20 @@ import { buildCodexMcpOverride } from './codex-config.mjs'
 import { createCycleQueue } from './cycle-queue.mjs'
 import { modelProcessOptions, stopModelProcess } from './process-lifecycle.mjs'
 
+function findTicketWorktree(workspaceRoot, ticketId) {
+  if (!workspaceRoot || ticketId == null) return ''
+  try {
+    if (existsSync(join(workspaceRoot, '.git'))) return workspaceRoot
+    const suffix = `-ticket-${String(ticketId).toLowerCase()}`
+    for (const entry of readdirSync(workspaceRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory() || !entry.name.toLowerCase().endsWith(suffix)) continue
+      const candidate = join(workspaceRoot, entry.name)
+      if (existsSync(join(candidate, '.git'))) return candidate
+    }
+  } catch { /* workspace discovery is best-effort */ }
+  return ''
+}
+
 // Behaviour prompts. The openvisio-team MCP bridge requires the agent's
 // credentials as ARGUMENTS on every tool call — those are injected at runtime by
 // loopBackendWs (see credNote), NOT baked in here, so nothing needs hunting.
@@ -439,13 +453,14 @@ function createOpencodeRunner({ mcpUrl, mcpHeaders, cfgKey, workdir, canCode, ma
 // approval/sandbox bypass flag.
 function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, log, debug, model, onTool, systemPrompt }) {
   const bin = onPath('codex') || 'codex'
-  const cwd = workdir || OV_DIR
+  const defaultCwd = workdir || OV_DIR
   const proxyPath = fileURLToPath(new URL('./codex-mcp-proxy.mjs', import.meta.url))
   let cancelActive = null
 
   function runCycle(prompt, cycleModel, cycleOptions = {}) {
     return new Promise((resolve) => {
       const m = cycleModel || model
+      const cycleCwd = cycleOptions.workdir || defaultCwd
       const full = systemPrompt ? systemPrompt + '\n\n' + prompt : prompt
       const disabledMcpTools = Array.isArray(cycleOptions.disabledMcpTools) ? cycleOptions.disabledMcpTools.filter(Boolean) : []
       const mcpOverride = buildCodexMcpOverride({ mcpUrl, proxyCommand: process.execPath, proxyPath, disabledMcpTools })
@@ -528,7 +543,7 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
         // mistaken for completed work. Keep it out of normal logs unless debug.
         child = spawn(bin, args, {
           ...modelProcessOptions,
-          cwd,
+          cwd: cycleCwd,
           env: {
             ...process.env,
             ...(mcpUrl ? {
@@ -563,7 +578,7 @@ function createCodexRunner({ mcpUrl, mcpHeaders, workdir, canCode, maxCycleMs, l
   }
 
   if (!mcpUrl) log('WARNING: no --mcp-url — Codex has no openvisio-team tools to act with. Re-connect with --mcp-url.')
-  log('codex runner ready' + (model ? ' [model ' + model + ']' : '') + (canCode ? ' [CODE workspace ' + cwd + ']' : ' [CHAT-ONLY]'))
+  log('codex runner ready' + (model ? ' [model ' + model + ']' : '') + (canCode ? ' [CODE workspace ' + defaultCwd + ']' : ' [CHAT-ONLY]'))
   return { runCycle, canCode, cancelCurrent: () => cancelActive?.() }
 }
 
@@ -817,7 +832,8 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   const queues = Object.fromEntries(['work', 'reply'].map((laneName) => [laneName, createCycleQueue({
     run: (item) => executeCycle(item.kind, item.context, item.targetChannels, item.taskRef, item.delivery),
     onError: (error, item) => {
-      releaseTaskForRetry(item.taskRef, item.context || '')
+      pauseFailedTask(item.taskRef)
+      void finalizeFailedTaskPause(item.taskRef)
       log(laneName + ' cycle failed: ' + (error?.message || error))
     },
   })]))
@@ -842,6 +858,10 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   const pendingCompletionReports = new Set(Array.isArray(replayState.pendingCompletionReports) ? replayState.pendingCompletionReports : [])
   const reportedCompletions = new Set(Array.isArray(replayState.reportedCompletions) ? replayState.reportedCompletions : [])
   const reportedTaskComments = new Set(Array.isArray(replayState.reportedTaskComments) ? replayState.reportedTaskComments : [])
+  // Evidence-gate failures are held at the ticket revision that produced them.
+  // This is distinct from a policy block: any later human ticket change resumes
+  // the work, but reconnects and the watcher's own blocker update do not.
+  const failedTaskVersions = new Map(Array.isArray(replayState.failedTaskVersions) ? replayState.failedTaskVersions : [])
   // A policy-blocked task stays paused across reconnects. It is released only
   // after the ticket itself carries explicit authorization or is completed/
   // unassigned. This prevents a 30-minute reconciliation retry from repeatedly
@@ -849,6 +869,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
   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 trimMap = (map) => { while (map.size > 500) map.delete(map.keys().next().value) }
   const MENTION_SIGNATURE_TTL_MS = 10 * 60 * 1000
   const pruneMentionSignatures = () => {
     const cutoff = Date.now() - MENTION_SIGNATURE_TTL_MS
@@ -863,6 +884,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
         recentMentionSignatures: [...recentMentionSignatures],
         seenActivities: [...seenActivities],
         deliveredReplies: [...deliveredReplies],
+        failedTaskVersions: [...failedTaskVersions],
         blockedTasks: [...blockedTasks],
         blockedTaskRepos: [...blockedTaskRepos],
         pendingCompletionReports: [...pendingCompletionReports],
@@ -871,6 +893,49 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       }, true)
     } catch { /* best-effort */ }
   }
+  const pauseFailedTask = (taskRef) => {
+    const projectId = Number(taskRef?.projectId)
+    const ticketId = Number(taskRef?.ticketId)
+    if (!Number.isFinite(projectId) || !Number.isFinite(ticketId)) return
+    const key = `${projectId}:${ticketId}`
+    // Persist before publishing the blocker. Its update_ticket event can arrive
+    // while publishBlocker is awaiting the backend response.
+    failedTaskVersions.set(key, 'pending')
+    trimMap(failedTaskVersions)
+    seenTasks.add(key)
+    trimSeen(seenTasks)
+    lastTaskSignature = ''
+    persistReplay()
+  }
+  const finalizeFailedTaskPause = async (taskRef) => {
+    const projectId = Number(taskRef?.projectId)
+    const ticketId = Number(taskRef?.ticketId)
+    if (!Number.isFinite(projectId) || !Number.isFinite(ticketId)) return
+    const key = `${projectId}:${ticketId}`
+    try {
+      const current = toolData(await callMcpTool('get_ticket', { project_id: projectId, ticket_id: ticketId }))
+      const ticket = current.ticket ?? current.task ?? current
+      failedTaskVersions.set(key, taskRevision(ticket) || 'pending')
+      trimMap(failedTaskVersions)
+      persistReplay()
+    } catch (e) {
+      log('could not snapshot failed ticket revision for #' + ticketId + ': ' + (e?.message || e) + '; keeping it paused')
+    }
+  }
+  const clearFailedTask = (key) => {
+    if (!failedTaskVersions.delete(key)) return false
+    persistReplay()
+    return true
+  }
+  const failedTaskIsPaused = (key, ticket) => {
+    if (!failedTaskVersions.has(key)) return false
+    const failedRevision = failedTaskVersions.get(key)
+    if (failedTaskRevisionIsCurrent(failedRevision, ticket)) return true
+    failedTaskVersions.delete(key)
+    seenTasks.delete(key)
+    persistReplay()
+    return false
+  }
   const markMentionHandled = (message, channelId) => {
     pruneMentionSignatures()
     const { idKey, signatureKey } = mentionDedupeKeys(message, channelId)
@@ -1229,12 +1294,18 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
               catch (e) { log('completion report retry failed for ticket #' + task.id + ': ' + (e?.message || e)) }
             }
             if (blockedTasks.delete(taskKey)) { blockedTaskRepos.delete(taskKey); persistReplay() }
+            clearFailedTask(taskKey)
             // 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.
             seenTasks.delete(taskKey)
             continue
           }
+          if (failedTaskIsPaused(taskKey, task)) {
+            seenTasks.add(taskKey)
+            log('backlog ticket #' + task.id + ' is paused at its failed revision; waiting for a ticket change')
+            continue
+          }
           if (blockedTasks.has(taskKey)) {
             const blockedRepo = blockedTaskRepos.get(taskKey)
             const helperAuthorized = blockedRepo && repositoryHasPrPushAuthorization({ cwd: blockedRepo })
@@ -1349,6 +1420,11 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
     lane.activeDelivery = delivery
     const ctx = context ? [context] : []
     const activeTaskRef = taskRef
+    const ticketWorktree = kind === 'full' && activeTaskRef ? findTicketWorktree(workdir, activeTaskRef.ticketId) : ''
+    const runnerOptions = {
+      ...(delivery?.watcherOwned ? { disabledMcpTools: ['post_message'] } : {}),
+      ...(ticketWorktree ? { workdir: ticketWorktree } : {}),
+    }
     const targets = [...new Set(targetChannels.filter((id) => id != null && Number.isFinite(Number(id))).map(Number))]
     laneStatusTargets[laneName] = new Set(targets)
     // credNote + charter live in the cached system prompt now — the per-cycle
@@ -1385,7 +1461,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
         }
       }
       if (lane.cancelled) return
-      const result = await runners[laneName].runCycle(prompt, useModel, delivery?.watcherOwned ? { disabledMcpTools: ['post_message'] } : {})
+      const result = await runners[laneName].runCycle(prompt, useModel, runnerOptions)
       let completionResult = result
       if (lane.cancelled || result?.subtype === 'canceled') {
         log(laneName + ' cycle cancelled; no blocker or reply will be published')
@@ -1399,11 +1475,12 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       }
       if (!cycleSucceeded(result)) {
         const outcome = result?.subtype || 'an unknown runtime error'
-        const notice = `I'm blocked because the ${kind === 'full' ? 'coding' : 'reply'} cycle ended with ${outcome}. I'm not claiming completion.${activeTaskRef ? " I've left the ticket available for retry." : ''}`
+        const notice = `I'm blocked because the ${kind === 'full' ? 'coding' : 'reply'} cycle ended with ${outcome}. I'm not claiming completion.${activeTaskRef ? " I've paused this revision until the ticket changes." : ''}`
         log('WORK_CYCLE_BLOCKED ' + outcome + '; publishing blocker')
+        if (activeTaskRef) pauseFailedTask(activeTaskRef)
         try { await publishBlocker({ prompt, taskRef: activeTaskRef, delivery, notice }) }
         catch (e) { log('failed to publish cycle blocker: ' + (e?.message || e)) }
-        releaseTaskForRetry(activeTaskRef, prompt)
+        finally { if (activeTaskRef) await finalizeFailedTaskPause(activeTaskRef) }
         return
       }
       if (kind !== 'full' && result?.mcpErrors?.length) {
@@ -1421,7 +1498,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       if (kind === 'full' && cycleSucceeded(result) && missing.length) {
         log(agent + ' coding cycle incomplete; recovery requires: ' + missing.join(', '))
         const recoveryPrompt = `CONTINUE THE SAME OPENVISIO REQUEST. Your earlier output did not complete it. Missing runtime evidence: ${missing.join('; ')}. An intent or progress message is not completion. Continue the actual work now, verify it, and then provide one distinct final result or real blocker using the original delivery rule; a final result after an earlier progress message is explicitly allowed and required. Do not repeat the progress message. ${codexPushGuide}\n\nORIGINAL REQUEST AND ROUTING CONTEXT:\n${prompt}`
-        const recovery = await runners.work.runCycle(recoveryPrompt, codeModel, delivery?.watcherOwned ? { disabledMcpTools: ['post_message'] } : {})
+        const recovery = await runners.work.runCycle(recoveryPrompt, codeModel, runnerOptions)
         if (lane.cancelled || recovery?.subtype === 'canceled') return
         const recoveredResult = combineRuntimeWorkEvidence(result, recovery)
         const recoveryMissing = missingRuntimeWorkEvidence(recoveredResult, { ticketCycle, resultMessageRequired })
@@ -1431,12 +1508,13 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
             catch (e) { log('failed to publish recovery policy blocker: ' + (e?.message || e)) }
           } else {
             const unresolved = recoveryMissing.length ? recoveryMissing : [`the recovery cycle ended with ${recovery?.subtype || 'an unknown error'}`]
-            const notice = `I'm blocked after one recovery attempt. Missing required evidence: ${unresolved.join('; ')}. I've left the ticket open and I'm not claiming completion.`
+            const notice = `I'm blocked after one recovery attempt. Missing required evidence: ${unresolved.join('; ')}. I've paused this revision until the ticket changes, and I'm not claiming completion.`
+            if (activeTaskRef) pauseFailedTask(activeTaskRef)
             try { await publishBlocker({ prompt, taskRef: activeTaskRef, delivery, notice }) }
             catch (e) { log('failed to publish recovery blocker: ' + (e?.message || e)) }
+            finally { if (activeTaskRef) await finalizeFailedTaskPause(activeTaskRef) }
           }
-          releaseTaskForRetry(activeTaskRef, prompt)
-          log('WORK_CYCLE_FAILED evidence gate still incomplete after one recovery; ticket retained for retry')
+          log('WORK_CYCLE_FAILED evidence gate still incomplete after one recovery; ticket paused until its revision changes')
           return
         }
         completionResult = recoveredResult
@@ -1445,12 +1523,10 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
         try {
           const delivered = await announceTaskCompletion(activeTaskRef, completionResult)
           if (!delivered) {
-            releaseTaskForRetry(activeTaskRef, prompt)
-            log('completion report deferred for ticket #' + activeTaskRef.ticketId + '; waiting for verified review/done state and PR evidence; ticket remains retryable')
+            log('completion report deferred for ticket #' + activeTaskRef.ticketId + '; waiting for verified review/done state and PR evidence without rerunning repository work')
           }
         } catch (e) {
-          releaseTaskForRetry(activeTaskRef, prompt)
-          log('completion report failed for ticket #' + activeTaskRef.ticketId + ': ' + (e?.message || e) + '; retained for reconnect retry')
+          log('completion report failed for ticket #' + activeTaskRef.ticketId + ': ' + (e?.message || e) + '; retained for delivery retry without rerunning repository work')
         }
       }
       if (delivery?.watcherOwned) {
@@ -1536,7 +1612,7 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
           })
         }
         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
+        blockedTasks.delete(key); blockedTaskRepos.delete(key); pendingCompletionReports.delete(key); failedTaskVersions.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 } })
@@ -1545,10 +1621,17 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
           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); blockedTaskRepos.delete(key); persistReplay(); seenTasks.delete(key)
+        blockedTasks.delete(key); blockedTaskRepos.delete(key); failedTaskVersions.delete(key); persistReplay(); seenTasks.delete(key)
         log(kind + ' ticket #' + ticketId + ' is already complete or awaiting review — ignored')
         return
       }
+      const hadFailedRevision = failedTaskVersions.has(key)
+      if (failedTaskIsPaused(key, ticket)) {
+        seenTasks.add(key)
+        log(kind + ' ticket #' + ticketId + ' is paused at its failed revision; waiting for a ticket change')
+        return
+      }
+      if (hadFailedRevision) log(kind + ' ticket #' + ticketId + ' changed since its failed cycle — resuming once')
       if (blockedTasks.has(key)) {
         const blockedRepo = blockedTaskRepos.get(key)
         const helperAuthorized = blockedRepo && repositoryHasPrPushAuthorization({ cwd: blockedRepo })
@@ -1567,12 +1650,14 @@ function loopBackendWs({ backend, wsUrl, apiKey, identifier, slug, claude, agent
       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 && !taskIsCoordinationOnly(taskText) ? 'full' : 'coord'
+      const preparedWorktree = cycleKind === 'full' ? findTicketWorktree(workdir, ticketId) : ''
       log(kind + ' verified ticket #' + ticketId + ' “' + title + '” -> ' + cycleKind + ' lane')
       const activityChannel = await projectStatusChannel(projectId)
       if (activityChannel != null) sendStatus(activityChannel, 'thinking')
       if (cycleKind === 'full') { pendingCompletionReports.add(key); trimSeen(pendingCompletionReports); persistReplay() }
       const humanTicketRef = ticketSlug ? `ticket ${ticketSlug}` : `the ticket “${title}”`
-      void drain(cycleKind, `Authoritative get_ticket verification confirms ${humanTicketRef} is open and assigned to YOU. Internal tool identity: project_id ${projectId}, ticket_id ${ticketId}. For every get_ticket call pass exactly { project_id: ${projectId}, ticket_id: ${ticketId} }; for list_task_types pass exactly { project_id: ${projectId} }. Numeric ids are MCP arguments only and must never appear in human-facing text; use ${ticketSlug || 'the ticket title'} instead. Ticket details: ${JSON.stringify({ slug: ticketSlug, title, description: ticket.description, priority: ticket.priority, typeId: ticket.type_id ?? ticket.typeId })}. This assignment has no source thread: do not call post_message yourself. Use list_task_types and update_ticket to move it active, complete and verify the work, open the PR when applicable, then update/move the ticket with evidence. For coding work, the watcher will publish exactly one verified completion result in the project channel.`, activityChannel == null ? [] : [activityChannel], { projectId, ticketId, channelId: activityChannel })
+      const workspaceDirective = preparedWorktree ? ` A prepared local git worktree for this ticket exists at ${JSON.stringify(preparedWorktree)}. Start repository inspection and edits there. Do not call list_codebases, codebase_tree, or get_codebase while this local worktree is available.` : ''
+      void drain(cycleKind, `Authoritative get_ticket verification confirms ${humanTicketRef} is open and assigned to YOU. Internal tool identity: project_id ${projectId}, ticket_id ${ticketId}. For every get_ticket call pass exactly { project_id: ${projectId}, ticket_id: ${ticketId} }; for list_task_types pass exactly { project_id: ${projectId} }. Numeric ids are MCP arguments only and must never appear in human-facing text; use ${ticketSlug || 'the ticket title'} instead. Ticket details: ${JSON.stringify({ slug: ticketSlug, title, description: ticket.description, priority: ticket.priority, typeId: ticket.type_id ?? ticket.typeId })}.${workspaceDirective} This assignment has no source thread: do not call post_message yourself. Use list_task_types and update_ticket to move it active, complete and verify the work, open the PR when applicable, then update/move the ticket with evidence. For coding work, the watcher will publish exactly one verified completion result in the project channel.`, activityChannel == null ? [] : [activityChannel], { projectId, ticketId, channelId: activityChannel })
     } catch (e) {
       log(kind + ' ticket verification failed for #' + ticketId + ': ' + (e?.message || e))
     }