ostacky 0.9.7 → 0.10.1

package/assets/plugins/ostacky-controller/controller-core.ts

@@ -141,6 +141,10 @@ export const DEFAULT_STATE: any = {
   pendingFileAccess: {},
   lastHeartbeat: 0,
   watchdogEnabled: true,
+  // multi-sesión: dueño de la request activa (sessionId de OpenCode vía _meta).
+  // null = sin dueño conocido. Es UN campo (se sobreescribe) — nunca un archivo por sesión.
+  ownerSessionId: null,
+  ownerHeartbeat: 0,
   ts: Date.now(),
   specNotInSync: false,
   engramBypassCount: 0,

package/assets/plugins/ostacky-controller/index.ts

@@ -6,7 +6,7 @@
  * MCP queda thin solo para observabilidad (get_*).
  *
  * Single source security: mirrors generados desde src/security.ts via scripts/sync-controller-core.ts
- * Cache único: getDiscoverySnapshot es único entrypoint.
+ * Discovery: `codegraph_explore` completado; no hay cache de archivo.
  * Tiered cache-friendly: isTrivial sin reemplazar system[0], suffix hint + SKIP.
  * CodeGraph preventivo: bloquea Read/Grep masivo sin Discovery hit.
  */
@@ -73,31 +73,137 @@ function readState(directory: string): any | null {
   }
 }
 
-function persistState(directory: string, state: any): void {
+/** Sleep sincrónico acotado — los call sites del plugin son sync. */
+function sleepSync(ms: number): void {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+  } catch {
+    const end = Date.now() + ms
+    while (Date.now() < end) {
+      /* spin de último recurso */
+    }
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Toma EL MISMO lock que el MCP (`<state>.lock.pid` con `wx`) para serializar
+ * plugin ↔ MCP cross-proceso. Devuelve una función de release; si no se pudo
+ * tomar, devuelve un no-op (la escritura sigue siendo segura por el merge).
+ */
+function acquireStateLock(statePath: string): () => void {
+  const pidPath = statePath + ".lock.pid"
+  const tsPath = statePath + ".lock.timestamp"
+  const staleWindow = 15_000
+  let acquired = false
+  for (let attempt = 0; attempt < 8 && !acquired; attempt++) {
+    // Lock viejo: solo lo liberamos si el dueño NO está vivo (mismo criterio que el MCP).
+    try {
+      const ts = parseInt(readFileSync(tsPath, "utf-8"), 10)
+      if (!Number.isNaN(ts) && Date.now() - ts >= staleWindow) {
+        const owner = parseInt(readFileSync(pidPath, "utf-8").trim(), 10)
+        if (!isPidAlive(owner)) {
+          try { unlinkSync(pidPath) } catch {}
+          try { unlinkSync(tsPath) } catch {}
+        }
+      }
+    } catch {}
+    try {
+      writeFileSync(pidPath, String(process.pid), { encoding: "utf-8", flag: "wx" })
+      try { writeFileSync(tsPath, String(Date.now()), "utf-8") } catch {}
+      acquired = true
+    } catch {
+      sleepSync(5 + attempt * 10)
+    }
+  }
+  if (!acquired) return () => {}
+  return () => {
+    try {
+      if (readFileSync(pidPath, "utf-8").trim() !== String(process.pid)) return
+    } catch {
+      return
+    }
+    try { unlinkSync(pidPath) } catch {}
+    try { unlinkSync(tsPath) } catch {}
+  }
+}
+
+let persistSeq = 0
+
+/**
+ * Merge puro: parte del estado FRESCO de disco y le aplica SOLO las claves que
+ * el plugin posee. Garantiza estructuralmente que una escritura del plugin no
+ * pueda borrar un avance del MCP (transición, audit, tasks, revision).
+ */
+export function mergePluginOwnedState(fresh: any, state: any, ownedKeys: string[]): any {
+  const payload: any = { ...fresh }
+  for (const k of ownedKeys) {
+    if (Object.prototype.hasOwnProperty.call(state, k)) payload[k] = state[k]
+  }
+  return payload
+}
+
+/**
+ * Persiste estado SIN poder pisar al MCP.
+ *
+ * El MCP es la autoridad de la máquina de estados; el plugin solo escribe un
+ * puñado de campos "advisory" (`ownedKeys`). Antes el plugin hacía
+ * readState → mutar → write del snapshot COMPLETO: si el MCP avanzaba en el
+ * medio (transición/audit/tasks), la escritura del plugin borraba ese avance.
+ *
+ * Ahora: (1) lock compartido con el MCP, (2) re-lectura fresca de disco DENTRO
+ * del lock, (3) se aplican SOLO las claves propias sobre el estado fresco,
+ * (4) write atómico (tmp único + rename). El `revision` se preserva del disco:
+ * las escrituras del plugin no son transiciones de la máquina de estados.
+ */
+export function persistState(directory: string, state: any, ownedKeys?: string[]): void {
   const p = getStatePath(directory)
   const dir = dirname(p)
   try { mkdirSync(dir, { recursive: true }) } catch {}
-  let serialized = JSON.stringify(state, null, 2)
-  if (serialized.length > MAX_STATE_FILE_SIZE) {
-    state.stateOversizedCount = (state.stateOversizedCount || 0) + 1
-    const trimmed = { ...state, snapshots: { codegraph: null, execution: null }, audit: (state.audit || []).slice(-50) }
-    serialized = JSON.stringify(trimmed, null, 2)
-    if (serialized.length > MAX_STATE_FILE_SIZE) return
-    state.snapshots = { codegraph: null, execution: null }
-    serialized = JSON.stringify(state, null, 2)
-  }
-  const tmp = p + ".tmp." + process.pid
+
+  const release = acquireStateLock(p)
   try {
-    writeFileSync(tmp, serialized, "utf-8")
-    renameSync(tmp, p)
-    try { renameSync(p + ".backup", p + ".backup.1") } catch {}
-    try { renameSync(p + ".backup.1", p + ".backup.2") } catch {}
+    let payload: any = state
+    if (ownedKeys && ownedKeys.length > 0) {
+      let fresh: any = null
+      try { fresh = JSON.parse(readFileSync(p, "utf-8")) } catch {}
+      if (fresh && typeof fresh === "object" && !Array.isArray(fresh)) {
+        payload = mergePluginOwnedState(fresh, state, ownedKeys)
+      }
+    }
+    let serialized = JSON.stringify(payload, null, 2)
+    if (serialized.length > MAX_STATE_FILE_SIZE) {
+      payload.stateOversizedCount = (payload.stateOversizedCount || 0) + 1
+      const trimmed = { ...payload, snapshots: { codegraph: null, execution: null }, audit: (payload.audit || []).slice(-50) }
+      serialized = JSON.stringify(trimmed, null, 2)
+      if (serialized.length > MAX_STATE_FILE_SIZE) return
+      payload.snapshots = { codegraph: null, execution: null }
+      serialized = JSON.stringify(payload, null, 2)
+    }
+    const tmp = p + ".tmp." + process.pid + "." + ++persistSeq
     try {
-      const backupTmp = p + ".backup.tmp." + process.pid
-      writeFileSync(backupTmp, serialized, "utf-8")
-      renameSync(backupTmp, p + ".backup")
+      writeFileSync(tmp, serialized, "utf-8")
+      renameSync(tmp, p)
+      try { renameSync(p + ".backup", p + ".backup.1") } catch {}
+      try { renameSync(p + ".backup.1", p + ".backup.2") } catch {}
+      try {
+        const backupTmp = p + ".backup.tmp." + process.pid + "." + persistSeq
+        writeFileSync(backupTmp, serialized, "utf-8")
+        renameSync(backupTmp, p + ".backup")
+      } catch {}
     } catch {}
-  } catch {}
+  } finally {
+    release()
+  }
 }
 
 function fastFingerprint(filePath: string): string | null {
@@ -122,25 +228,6 @@ function isPathInsideProject(filePath: string, directory: string): boolean {
   } catch { return false }
 }
 
-function getDiscoveryCacheHit(directory: string): boolean {
-  try {
-    const cacheDir = join(directory, ".opencode", "cache", "codegraph")
-    if (!existsSync(cacheDir)) return false
-    const files = readdirSync(cacheDir).filter((f: string) => f.startsWith("discovery-"))
-    if (files.length === 0) return false
-    // check if any file is recent (<1h) and valid
-    const now = Date.now()
-    for (const f of files) {
-      try {
-        const raw = readFileSync(join(cacheDir, f), "utf-8")
-        const data = JSON.parse(raw)
-        if (typeof data.ts === "number" && now - data.ts < 60*60*1000) return true
-      } catch {}
-    }
-    return false
-  } catch { return false }
-}
-
 function isCodegraphAvailable(directory: string): boolean {
   // If codegraph binary exists, assume OK. Otherwise fallback allows Read.
   try {
@@ -153,6 +240,217 @@ function isCodegraphAvailable(directory: string): boolean {
   } catch { return false }
 }
 
+/**
+ * ¿Este read/grep/glob esta sujeto al gate de discovery?
+ * Exenciones: docs/json/md, openspec/changes|specs, grep de literales, y archivos ya
+ * trackeados (refresh honesto post-complete necesita Read fresco sin Discovery hit).
+ */
+export function isCodeReadGated(input: {
+  isCodeFile: boolean
+  isLiteralGrep: boolean
+  isSpecTasksPath: boolean
+  isDocsPath: boolean
+  isTaskTracked: boolean
+}): boolean {
+  return (
+    input.isCodeFile &&
+    !input.isLiteralGrep &&
+    !input.isSpecTasksPath &&
+    !input.isDocsPath &&
+    !input.isTaskTracked
+  )
+}
+
+/**
+ * Predicado puro del gate de CodeGraph: ¿bloquear esta lectura de codigo?
+ *
+ * Extraido a funcion para poder testear el INVARIANTE, no el mensaje. El test anterior hacia
+ * `expect(src).toContain("Usa getDiscoverySnapshot primero")`: verificaba que el texto existiera
+ * y pasaba verde con el gate inescapable adentro (fix-codegraph-gate).
+ */
+export function shouldBlockCodeRead(input: {
+  isCodeFile: boolean
+  isLiteralGrep: boolean
+  isSpecTasksPath: boolean
+  isDocsPath: boolean
+  isTaskTracked: boolean
+  codegraphOk: boolean
+  hasDiscoveryHit: boolean
+}): boolean {
+  return isCodeReadGated(input) && input.codegraphOk && !input.hasDiscoveryHit
+}
+
+/**
+ * Tools cuyo completado constituye evidencia REAL de discovery estructural en la sesion.
+ *
+ * `codegraph_explore` es la senal fuerte: llamada real, resultado inspeccionable por el plugin.
+ * No hay cache de discovery: `getDiscoverySnapshot` nunca existió y se retiró.
+ *
+ * Historia (fix-codegraph-gate): antes la UNICA senal era `getDiscoverySnapshot`, una tool que nunca
+ * se registro ni en el plugin ni en el MCP. `hasDiscoveryHit` era siempre false y el gate bloqueaba
+ * todo read/grep/glob de codigo sin salida posible; un `codegraph_explore` completado NO lo abria,
+ * contradiciendo la instruccion "CodeGraph primero" del agente.
+ */
+export function marksDiscovery(toolName: string): boolean {
+  return (
+    toolName.includes("codegraph_explore")
+  )
+}
+
+/**
+ * Mismo criterio de "archivo de código" que el gate de read (index.ts:552),
+ * sin la cláusula de `pattern` que es específica de glob. Docs/JSON quedan fuera:
+ * un .md bajo assets/ es documentación, no código.
+ */
+export function isCodePath(p: string): boolean {
+  if (!p) return false
+  if (/\.(md|json)$/i.test(p)) return false
+  return /\.(ts|js|tsx|jsx|mts|cts)$/i.test(p) || p.includes("src/") || p.includes("assets/")
+}
+
+/**
+ * Evidencia de una corrida de shell para las tasks `test:` (change
+ * test-verification-execution). Devuelve null si el evento no permite afirmar
+ * nada: sin comando o sin `exit` numérico.
+ *
+ * NO consulta `status`: medido en OpenCode 2.0.32, `sh -c 'exit 3'` llega con
+ * `status: "completed"` y `result.metadata.status: "completed"`. El único dato
+ * veraz es `result.metadata.exit`.
+ */
+export function shellEvidence(event: any): { cmd: string; exit: number; ts: number } | null {
+  if (!event || event.tool !== "shell") return null
+  const cmd = event.input?.command
+  const exit = event.result?.metadata?.exit
+  if (typeof cmd !== "string" || !cmd.trim()) return null
+  if (typeof exit !== "number") return null
+  return { cmd: cmd.trim(), exit, ts: Date.now() }
+}
+
+/** Tools que mutan archivos: avanzan `lastMutationTs`. */
+export function isMutatingTool(tool: string): boolean {
+  return tool === "edit" || tool === "write" || tool === "patch"
+}
+
+/**
+ * Comando shell que escribe en disco. Predicado compartido por el gate de
+ * mutación y por `lastMutationTs`: si no se compartiera, un `sed -i` aprobado
+ * por el gate mutaría el código sin avanzar el timestamp, y una corrida de test
+ * previa seguiría contando como evidencia.
+ */
+export function isShellMutation(command: string): boolean {
+  if (!command) return false
+  // `2>&1`, `1>&2`, `2>/dev/null` son redirects de stderr, no mutación.
+  const cmdSansStderr = command.replace(/2>&1/g, "").replace(/1>&2/g, "").replace(/2>\s*\/dev\/null/g, "")
+  return /(^|[^0-9&])>{1,2}\s*(?!&)\S+|\bsed\b[^|;]*-i|\btruncate\b|\btee\b|\bcp\s+|\bmv\s+|\brm\s+|python.*open.*w/.test(cmdSansStderr)
+}
+
+/**
+ * Verbos cuyo output revela el CONTENIDO de un archivo. No incluye verbos que
+ * sólo mencionan paths (`bun test x.ts`, `tsc src/x.ts`, `git diff`): el gate
+ * distingue "revela" de "menciona" — ver change shell-code-read-gate.
+ */
+const SHELL_READ_VERBS = new Set([
+  "cat", "head", "tail", "sed", "awk", "grep", "rg", "ag", "ack", "less", "more",
+  "nl", "bat", "tac", "strings", "xxd", "od", "base64", "diff", "cut", "paste",
+  "sort", "uniq", "column", "expand", "fold",
+])
+
+const SHELL_WRAPPERS = new Set(["sudo", "env", "time", "command", "exec", "nohup"])
+
+/**
+ * Paths de código que `command` REVELA (no los que menciona).
+ *
+ * Fail-open por diseño: redirección => escritura, `sed -i` => escritura, verbo
+ * fuera de la allowlist => []. Un gate de shell nunca es hermético; el objetivo
+ * es quitar el bypass casual (`cat src/x.ts`), no demostrar imposibilidad.
+ * Bypass residual documentado en el spec: `git show`, `python -c`, `node -e`,
+ * `find -exec`, `xargs`.
+ */
+export function shellReadTargets(command: string): string[] {
+  if (!command) return []
+  const targets: string[] = []
+  // Split por pipes/separadores, NO por `>`: necesitamos ver la redirección.
+  const segments = command.replace(/&&/g, ";").replace(/\|\|/g, ";").split(/[|;\n]+/)
+  for (const seg of segments) {
+    const trimmed = seg
+      // Redirects de stderr no son escritura: sin esto, `cat src/x.ts 2>&1`
+      // pasaba el check `>` de abajo y se colaba del gate (bypass casual).
+      // Mismo criterio que isShellMutation, el sibling de este módulo.
+      .replace(/2>&1/g, "")
+      .replace(/1>&2/g, "")
+      .replace(/2>\s*\/dev\/null/g, "")
+      .trim()
+    if (!trimmed) continue
+    // Escritura real (cat > f, tee, heredoc): no es lectura.
+    if (/>/.test(trimmed)) continue
+    const tokens = (trimmed.match(/(?:[^\s"'`\\]+|"[^"]*"|'[^']*'|`[^`]*`)+/g) || [])
+      .map((t) => t.replace(/["'`]/g, "").replace(/\\/g, ""))
+      .filter(Boolean)
+    if (tokens.length === 0) continue
+    let i = 0
+    while (i < tokens.length && SHELL_WRAPPERS.has(tokens[i])) i++
+    const verb = tokens[i] || ""
+    const base = verb.split("/").pop() || verb
+    if (!SHELL_READ_VERBS.has(base)) continue
+    // sed -i es escritura in-place, no lectura.
+    if (base === "sed" && tokens.some((t) => t === "-i" || t.startsWith("-i") || t === "--in-place" || t.startsWith("--in-place"))) continue
+    // diff -q/--brief/--stat sólo compara metadatos: no revela contenido.
+    if (base === "diff" && tokens.some((t) => t === "-q" || t === "--quiet" || t === "--brief" || t === "--stat" || /^-[a-zA-Z]*q[a-zA-Z]*$/.test(t))) continue
+    for (const p of extractPathsFromBash(trimmed)) {
+      if (isCodePath(p)) targets.push(p)
+    }
+  }
+  return [...new Set(targets)]
+}
+
+/**
+ * Predicado puro del gate de shell: ¿leer este path por shell está EXENTO?
+ *
+ * Extraído del hook para poder testear el INVARIANTE (mismo criterio que
+ * shouldBlockCodeRead). Exenciones:
+ * 1. Paths FUERA del proyecto: no son código de este codebase (fixtures
+ *    temporales de tests, reportes generados); bloquearlos rompe pipelines sin
+ *    escape hatch — el falso positivo que el diseño prohibió.
+ * 2. Specs/docs (.md/.json, openspec, assets/docs).
+ * 3. Archivos ya trackeados en tasks/fileFingerprints/lastValidated (el refresh
+ *    honesto post-complete necesita re-leerlos).
+ */
+export function isShellPathExempt(p: string, directory: string, freshState: any): boolean {
+  if (!isPathInsideProject(p, directory)) return true
+  if (p.includes("openspec/changes") || p.includes("openspec/specs")) return true
+  if (p.includes("assets/docs") || p.includes("/docs/") || /\.md$/i.test(p) || /\.json$/i.test(p)) return true
+  try {
+    if (freshState) {
+      const fps = Object.keys(freshState.fileFingerprints || {})
+      const taskFiles = Object.values(freshState.tasks || {}).map((t: any) => t.filePath).filter(Boolean)
+      const lv: any = (freshState as any).lastValidated || null
+      const lvByFile = lv?.byFile && typeof lv.byFile === "object" ? lv.byFile : null
+      const lvPaths: string[] = [
+        ...(lvByFile ? Object.keys(lvByFile) : []),
+        ...(lv?.filePath ? [lv.filePath as string] : []),
+      ]
+      const matches = (f: string): boolean => p.endsWith(f) || f.endsWith(p) || p.includes(f) || f.includes(p)
+      if (fps.some(matches) || taskFiles.some(matches)) return true
+      if (lvPaths.some((lf) => p.endsWith(lf) || lf.endsWith(p))) return true
+    }
+  } catch {}
+  return false
+}
+
+/** Comandos `test:` declarados en taskVerifications, ya normalizados (sin prefijo). */
+export function testVerifyCommands(state: any): Set<string> {
+  const out = new Set<string>()
+  try {
+    for (const v of Object.values((state as any)?.taskVerifications || {})) {
+      if (typeof v === "string" && v.trim().startsWith("test:")) {
+        const cmd = v.trim().slice("test:".length).trim()
+        if (cmd) out.add(cmd)
+      }
+    }
+  } catch {}
+  return out
+}
+
 function jsonContent(value: unknown): { content: string } {
   try {
     return { content: JSON.stringify(value) ?? "null" }
@@ -226,7 +524,7 @@ export default {
           const pending = Array.isArray(s.expectedTasks) ? s.expectedTasks.filter((id: string) => !s.tasks?.[id] || s.tasks[id].status !== "COMPLETED").length : "?"
           const msg = `[ostacky] Sigo trabajando — ${s.state} • ${completed}/${total} (${pending} pendientes) • hace ${Math.round(idle/1000)}s sin output`
           try { console.log(msg) } catch {}
-          try { const st = readState(directory); if (st) { (st as any).lastPingTs = now; persistState(directory, st) } } catch {}
+          try { const st = readState(directory); if (st) { (st as any).lastPingTs = now; persistState(directory, st, ["lastPingTs"]) } } catch {}
         } catch {}
       }, 30_000)
       if (pingInterval && typeof (pingInterval as any).unref === 'function') (pingInterval as any).unref()
@@ -237,6 +535,18 @@ export default {
       const sessionId: string = event.sessionID ?? "default"
       const text = (event.prompt.text ?? "").trim()
       const state = readState(directory)
+      // task-verification-integrity D4: registrar el texto ORIGINAL del usuario (antes de los
+      // hints de abajo) para que `implementation_complete({force:true})` se apoye en evidencia
+      // real y no en el audit, que lo redacta el agente. `ownedKeys` evita pisar el avance del MCP.
+      // Cada prompt lleva `ts`: el MCP sólo acepta confirmaciones POSTERIORES al último
+      // intento de force, así un "¿qué hace force:true?" viejo no abre el gate.
+      if (text && state) {
+        try {
+          const prev = Array.isArray((state as any).lastUserPrompts) ? (state as any).lastUserPrompts : []
+          ;(state as any).lastUserPrompts = [...prev, { text: text.slice(0, 500), ts: Date.now() }].slice(-5)
+          persistState(directory, state, ["lastUserPrompts"])
+        } catch {}
+      }
       const currentState = state?.state ?? "DONE"
       const trivial = isTrivial(text, currentState)
       trivialBySession.set(sessionId, trivial)
@@ -335,7 +645,7 @@ export default {
             if (st) {
               st.engramBypassCount = (st.engramBypassCount || 0) + 1
               // no persist cada vez si es muy frecuente: single-writer ya persiste en after, pero acá persistimos directo para auditoría
-              persistState(directory, st)
+              persistState(directory, st, ["engramBypassCount"])
             }
           } catch {}
         }
@@ -413,14 +723,20 @@ export default {
               (lvFile ? lvFile.some((lf) => targetPath.endsWith(lf) || lf.endsWith(targetPath)) : false)
           }
         } catch {}
-        if (isCodeFile && !isLiteralGrep && !isSpecTasksPath && !isDocsPath && !isTaskTracked) {
-          const hasDiscoveryHit = discoveryHitByRequest.get(sessionId) ?? getDiscoveryCacheHit(directory)
-          const codegraphOk = isCodegraphAvailable(directory)
-          if (codegraphOk && !hasDiscoveryHit) {
-            // Allow if file is not indexable or trivial?
-            // Block with suggestion
-            throw new Error(`BLOCKED: Usá getDiscoverySnapshot primero — sugerencia: getDiscoverySnapshot("${targetPath || "query"}")`)
-          }
+        // Orden cheap -> caro: el path no hace I/O; codegraph y la cache en disco solo se evalúan
+        // si el path esta realmente sujeto al gate (`read`/`grep`/`glob` corren en cada turno).
+        const gated = isCodeReadGated({ isCodeFile, isLiteralGrep, isSpecTasksPath, isDocsPath, isTaskTracked })
+        const codegraphOk = gated ? isCodegraphAvailable(directory) : false
+        // Sin fallback a disco: la única evidencia válida es un codegraph_explore
+        // COMPLETADO en esta sesión (discoveryHitByRequest). El memo se limpia con
+        // session.deleted, así "esta sesión" es literal.
+        const hasDiscoveryHit = codegraphOk ? discoveryHitByRequest.get(sessionId) === true : false
+        if (shouldBlockCodeRead({
+          isCodeFile, isLiteralGrep, isSpecTasksPath, isDocsPath, isTaskTracked, codegraphOk, hasDiscoveryHit,
+        })) {
+          throw new Error(
+            `BLOCKED: sin discovery estructural en esta sesión — llamá codegraph_codegraph_explore("${targetPath || "query"}") antes de Read/Grep/Glob de código`
+          )
         }
       }
 
@@ -454,12 +770,32 @@ export default {
         }
       }
 
+      // ── 3.2) CodeGraph gate para shell: leer código sin discovery → BLOCKED ──
+      // El gate de código (arriba) sólo mira read/grep/glob; `cat src/x.ts` revela
+      // lo mismo y no costaba nada. Fail-open a propósito: `read` falla cerrado
+      // porque es inequívoco; `shell` es ambiguo y un falso positivo rompe tests o
+      // builds sin escape hatch para el usuario (change shell-code-read-gate).
+      if (tool === "shell") {
+        const cmdForRead: string = args?.command || args?.cmd || ""
+        if (typeof cmdForRead === "string" && cmdForRead) {
+          const shellTargets = shellReadTargets(cmdForRead)
+          if (shellTargets.length > 0) {
+            const gatedShell = shellTargets.filter((p) => !isShellPathExempt(p, directory, freshState))
+            const codegraphOkShell = gatedShell.length > 0 ? isCodegraphAvailable(directory) : false
+            const hasDiscoveryShell = codegraphOkShell ? discoveryHitByRequest.get(sessionId) === true : false
+            if (gatedShell.length > 0 && codegraphOkShell && !hasDiscoveryShell) {
+              throw new Error(
+                `BLOCKED: sin discovery estructural en esta sesión — llamá codegraph_codegraph_explore("${gatedShell[0]}") antes de leer código por shell`
+              )
+            }
+          }
+        }
+      }
+
       // ── 3.5) Shell file-mutation gate (harden-task-integrity: shell mutante requiere validate_edit) ──
       if (tool === "shell" && freshState && ["EXECUTING_INLINE", "EXECUTING_SUBAGENTS"].includes(freshState.state)) {
         const cmdForMutation: string = args?.command || args?.cmd || ""
-        // Fix falso positivo: `2>&1`, `1>&2`, `2>/dev/null` son redirects de stderr, no mutación.
-        const cmdSansStderr = cmdForMutation.replace(/2>&1/g, "").replace(/1>&2/g, "").replace(/2>\s*\/dev\/null/g, "")
-        const isMutating = /(^|[^0-9&])>{1,2}\s*(?!&)\S+|\bsed\b[^|;]*-i|\btruncate\b|\btee\b|\bcp\s+|\bmv\s+|python.*open.*w/.test(cmdSansStderr)
+        const isMutating = isShellMutation(cmdForMutation)
         if (isMutating) {
           const mPaths = extractPathsFromBash(cmdForMutation)
           for (const p of mPaths) {
@@ -541,7 +877,7 @@ export default {
               try {
                 const st = readState(directory) || { ...DEFAULT_STATE }
                 st.staleContentAttempts = (st.staleContentAttempts || 0) + 1
-                persistState(directory, st)
+                persistState(directory, st, ["staleContentAttempts"])
               } catch {}
               throw new Error(`CONFLICT: stale fingerprint for ${targetPath}`)
             }
@@ -599,6 +935,13 @@ export default {
                 ts: Date.now(),
                 mode: isCreate ? 'create' : 'replace',
               }
+              // FIX multi-sesión: persistir lastValidated. Antes se mutaba un objeto
+              // local y se descartaba → complete_task leía un lastValidated viejo
+              // desde disco → CONFLICT → las tareas quedaban pending y el cierre
+              // (implementation_complete) se bloqueaba.
+              // `["lastValidated"]` = se escribe SOLO esa clave sobre el estado
+              // fresco que se re-lee bajo el lock compartido con el MCP.
+              persistState(directory, st, ["lastValidated"])
             }
           } catch {}
         }
@@ -609,24 +952,52 @@ export default {
       // Track discovery hit to allow subsequent Reads
       const tool: string = event.tool as string
       const sessionId: string = (event.sessionID ?? "default") as string
-      const resultText = event.status === "completed" && event.result ? JSON.stringify(event.result) : ""
-      if (tool.includes("getDiscoverySnapshot") || tool.includes("get_discovery_snapshot")) {
-        // if output indicates hit, mark it
+      // (fix-codegraph-gate) Evidencia REAL de discovery: un `codegraph_explore` completado en ESTA
+      // sesión abre el gate de lecturas de código. Se marca aunque el resultado venga vacío, a
+      // propósito: "CodeGraph no tiene este archivo en su índice" es justamente el caso donde el
+      // Read TIENE que poder pasar si hubo `codegraph_explore`.
+      if (marksDiscovery(tool)) {
         try {
-          const text = resultText
-          if (text && !text.includes("null") && text.length > 10) {
-            discoveryHitByRequest.set(sessionId, true)
-          }
-          // Engram hit via discovery snapshot (contiene engramHits)
-          if (text && text.includes("engramHits")) {
-            engramHitBySession.set(sessionId, true)
-          }
+          if (event.status === "completed") discoveryHitByRequest.set(sessionId, true)
         } catch {}
       }
       // Track Engram hit (mem_search / mem_context / dedup) para soft gate 1.6
-      if (tool.includes("engram_mem_search") || tool.includes("engram_mem_context") || tool.includes("mem_search") || tool.includes("mem_context") || tool.includes("getEngramDedup") || tool.includes("engram_mem_")) {
+      if (tool.includes("engram_mem_search") || tool.includes("engram_mem_context") || tool.includes("mem_search") || tool.includes("mem_context") || tool.includes("engram_mem_")) {
         engramHitBySession.set(sessionId, true)
       }
+      // test-verification-execution: evidencia para tasks `test:`.
+      // `status` miente con exit != 0 (ver shellEvidence): sólo se registra con exit numérico.
+      // D10 respectado: NO cada shell persiste (git/ls/builds no tienen valor de evidencia y
+      // cada persist cuesta lock + re-read + write + 3 renames de backup). Se persisten sólo
+      // las corridas cuyo comando matchea un `test:` declarado en taskVerifications — que son
+      // las ÚNICAS que complete_task / verifyIntegrity consultan via findTestEvidence.
+      // Tradeoff fail-closed: si taskVerifications aún no llegó al state cuando se corre el
+      // test, la evidencia no se registra → complete_task pide re-correr (razón explícita).
+      try {
+        const ev = shellEvidence(event as any)
+        // Un shell que escribe (exit 0) también invalida evidencia de test:
+        // si no, `sed -i` mutaría el código sin avanzar el timestamp.
+        const mutating =
+          (isMutatingTool(tool) && event.status === "completed") ||
+          (!!ev && ev.exit === 0 && isShellMutation(ev.cmd))
+        const isTestRun = !!ev && testVerifyCommands(readState(directory)).has(ev.cmd)
+        if (isTestRun || mutating) {
+          const s = readState(directory)
+          if (s) {
+            const owned: string[] = []
+            if (ev && isTestRun) {
+              const prev = Array.isArray((s as any).shellRuns) ? (s as any).shellRuns : []
+              ;(s as any).shellRuns = [...prev, ev].slice(-25)
+              owned.push("shellRuns")
+            }
+            if (mutating) {
+              ;(s as any).lastMutationTs = Date.now()
+              owned.push("lastMutationTs")
+            }
+            if (owned.length > 0) persistState(directory, s, owned)
+          }
+        }
+      } catch {}
       // Heartbeat: single-writer — plugin memo, no persist cada tool (D10)
       try {
         const s = readState(directory)
@@ -636,7 +1007,7 @@ export default {
           const shouldPersist = process.env.OSTACKY_PLUGIN_PERSIST === "1" || (now - (s.lastHeartbeat || 0) > 30000)
           if (shouldPersist) {
             s.lastHeartbeat = now
-            try { persistState(directory, s) } catch {}
+            try { persistState(directory, s, ["lastHeartbeat"]) } catch {}
           }
         }
       } catch {}

package/assets/skills/brainstorming/SKILL.md

@@ -36,12 +36,12 @@ Do NOT invoke any implementation skill, write any code, or scaffold any project
 
 ### Process
 
-1. **Check discovery-cache first** — `src/discovery-cache.ts` `getDiscoverySnapshot(query)` + `getEngramDedup(query, requestId)`. Si hit válido (TTL+gitDiffHash), **reusar** sin llamar tools. Solo si miss → `engram_mem_search` + `codegraph_codegraph_explore` y **SHALL `putDiscoverySnapshot`** antes de avanzar. No re-llamar si área difiere <30% del snapshot.
+1. **Reusar discovery** — si ya llamaste `codegraph_codegraph_explore` para el área en este request, reusá ese output; si no, `engram_mem_search` + `codegraph_codegraph_explore`. No repitas la misma query sin motivo. No hay cache de archivo.
 2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
 4. **Propose 2-3 approaches (hardening-v2 — SHALL)** — con tabla trade-offs (coste|riesgo|complejidad) + evidencia CodeGraph+Engram sin alucinar, YAGNI, y recomendación con razón; cada approach cita symbols existentes y mem_search hits verificables
 5. **Present design** — in sections scaled to complexity, get user approval after each section. **Gate post-brainstorming (hardening-v2):** tras presentar diseño, preguntar "¿Procedo con este diseño o querés ajustar algo?" y esperar confirmación explícita antes de `record_discovery`, `openspec-propose` o implementación directa
 6. **Write design doc (output path condicional — router exclusivo) — SHALL read fresco + edit no write + sync proactiva:**
-   - Antes de `write` SHALL `read` fresco de `openspec/changes/<id>/{proposal,design,tasks}` o `docs/superpowers/specs/*.md` si existen; si existen SHALL `edit` (no `write`); `write` solo si no existía. `getDiscoverySnapshot` no aplica a specs/docs. Para `open-explore` sin archivo SHALL `mem_save topic_key:brainstorm/<hash>` por iteración.
+   - Antes de `write` SHALL `read` fresco de `openspec/changes/<id>/{proposal,design,tasks}` o `docs/superpowers/specs/*.md` si existen; si existen SHALL `edit` (no `write`); `write` solo si no existía. El discovery no aplica a specs/docs. Para `open-explore` sin archivo SHALL `mem_save topic_key:brainstorm/<hash>` por iteración.
    - Si trigger + `level 1+` no-downgradeable (`estLines>30` o `fileCount>2` o API pública) y change activo → escribir `openspec/changes/<id>/design.md` sección `## Alternatives Considered` con 2-3 approaches (tabla coste|riesgo|complejidad + evidencia CodeGraph+Engram), no `docs/`. No invocar `openspec-propose` separado — este es el diseño. Si ya existe, SHALL `edit` no `write`.
    - Si trigger + `0/0+1` o `1+` downgradeable (`estLines<30`&&`fileCount==1`&&sin API) → solo `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` + gate único `¿Procedo?` → DIRECT sin change. SHALL sugerir downgrade: `"Esto parece 0+1 (~X líneas, 1 archivo). ¿Lo tratamos sin spec?"` y esperar. Si `docsSpec` ya existe SHALL `read` + `edit`.
    - Gate post-brainstorming es **único**; no hay segundo `¿Procedo con spec?`. `get_audit` `WARN:duplicate_design_generated` si ambos artefactos mismo `requestId`.