opencode-agent-skill 15.0.0 → 15.1.1

package/lib/memory-engine.mjs

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto"
 import { existsSync } from "node:fs"
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises"
 import { spawnSync } from "node:child_process"
 import path from "node:path"
 import { evidenceExists, putEvidence } from "./evidence-store.mjs"
+import { buildRepoGraphCached } from "./repo-graph.mjs"
 
 const MEMORY_DIR = ".ues-memory"
 const MEMORY_FILE = "MEMORY.json"
@@ -15,6 +16,72 @@ const STOP = new Set([
   "file","files","change","changes","được","các","cho","với","trong","này","một","những","không","theo",
 ])
 
+const MEMORY_WRITE_TAILS = new Map()
+const MEMORY_LOCK_STALE_MS = 15_000
+const MEMORY_LOCK_WAIT_MS = 20_000
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function memoryLockPath(root) {
+  return path.join(path.resolve(root), MEMORY_DIR, ".memory-write.lock")
+}
+
+async function withCrossProcessMemoryLock(root, fn) {
+  const lockDir = memoryLockPath(root)
+  await mkdir(path.dirname(lockDir), { recursive: true })
+  const deadline = Date.now() + MEMORY_LOCK_WAIT_MS
+  let delayMs = 8
+
+  while (true) {
+    try {
+      await mkdir(lockDir)
+      break
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error
+      const info = await stat(lockDir).catch(() => null)
+      if (info && Date.now() - info.mtimeMs > MEMORY_LOCK_STALE_MS) {
+        const confirmed = await stat(lockDir).catch(() => null)
+        if (
+          confirmed &&
+          confirmed.ino === info.ino &&
+          confirmed.mtimeMs === info.mtimeMs
+        ) {
+          await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+          continue
+        }
+      }
+      if (Date.now() >= deadline) throw new Error("Timed out waiting for memory write lock")
+      await sleep(delayMs)
+      delayMs = Math.min(100, delayMs * 2)
+    }
+  }
+
+  try {
+    return await fn()
+  } finally {
+    await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+async function withMemoryWriteLock(root, fn) {
+  const key = path.resolve(root)
+  const previous = MEMORY_WRITE_TAILS.get(key) || Promise.resolve()
+  let release
+  const barrier = new Promise((resolve) => { release = resolve })
+  const tail = previous.catch(() => {}).then(() => barrier)
+  MEMORY_WRITE_TAILS.set(key, tail)
+
+  await previous.catch(() => {})
+  try {
+    return await withCrossProcessMemoryLock(root, fn)
+  } finally {
+    release()
+    if (MEMORY_WRITE_TAILS.get(key) === tail) MEMORY_WRITE_TAILS.delete(key)
+  }
+}
+
 function now() {
   return new Date().toISOString()
 }
@@ -44,15 +111,35 @@ function normalizedContent(value) {
   return String(value || "").trim().replace(/\s+/g, " ")
 }
 
+function scopedIdentityFiles(scope, files = []) {
+  if (!["file", "module"].includes(String(scope || ""))) return []
+  return uniq((files || []).map(normalizeFile)).sort()
+}
+
 function idFor(input) {
+  const scope = input.scope || "project"
+  const scopedFiles = scopedIdentityFiles(scope, input.files)
   const key = input.key || [
-    input.scope || "project",
+    scope,
     input.type || "episodic",
+    scopedFiles.length ? scopedFiles.join(",") : "",
     normalizedContent(input.content),
   ].join(":")
   return createHash("sha256").update(String(key)).digest("hex").slice(0, 20)
 }
 
+function sameMemoryIdentity(item, input) {
+  if (!item) return false
+  if (String(item.scope || "project") !== String(input.scope || "project")) return false
+  if (String(item.type || "episodic") !== String(input.type || "episodic")) return false
+  if (normalizedContent(item.content) !== normalizedContent(input.content)) return false
+  const expectedFiles = scopedIdentityFiles(input.scope, input.files)
+  if (!expectedFiles.length) return true
+  const actualFiles = scopedIdentityFiles(item.scope, item.files)
+  return actualFiles.length === expectedFiles.length &&
+    actualFiles.every((file, index) => file === expectedFiles[index])
+}
+
 function memoryPath(root) {
   return path.join(path.resolve(root), MEMORY_DIR, MEMORY_FILE)
 }
@@ -97,52 +184,58 @@ export async function proposeMemory(root, input = {}) {
   if (!content) throw new Error("memory content is required")
   const type = VALID_TYPES.has(input.type) ? input.type : "episodic"
   const scope = VALID_SCOPES.has(input.scope) ? input.scope : "project"
-  const state = await readMemoryState(root)
   const id = idFor({ ...input, type, scope, content })
-  const timestamp = now()
-  const existing = state.memories.find((item) => item.id === id)
-  if (existing) {
-    const reinforced = {
-      ...existing,
-      lastSeenAt: timestamp,
-      reinforcementCount: Number(existing.reinforcementCount || 1) + 1,
-      evidenceRefs: uniq([...(existing.evidenceRefs || []), ...(input.evidenceRefs || [])]),
-      files: uniq([...(existing.files || []), ...(input.files || []).map(normalizeFile)]),
-      tags: uniq([...(existing.tags || []), ...(input.tags || [])]),
-      confidence: Math.max(clamp(existing.confidence), clamp(input.confidence, existing.confidence ?? 0.7)),
-      taskClass: input.taskClass || existing.taskClass || null,
-      expiresAt: input.expiresAt || existing.expiresAt || null,
+
+  return withMemoryWriteLock(root, async () => {
+    const state = await readMemoryState(root)
+    const timestamp = now()
+    const existing = state.memories.find((item) => item.id === id) ||
+      state.memories.find((item) => sameMemoryIdentity(item, { ...input, type, scope, content }))
+    if (existing) {
+      const reinforced = {
+        ...existing,
+        lastSeenAt: timestamp,
+        reinforcementCount: Number(existing.reinforcementCount || 1) + 1,
+        evidenceRefs: uniq([...(existing.evidenceRefs || []), ...(input.evidenceRefs || [])]),
+        files: uniq([...(existing.files || []), ...(input.files || []).map(normalizeFile)]),
+        dependencies: uniq([...(existing.dependencies || []), ...(input.dependencies || []).map(normalizeFile)]),
+        tags: uniq([...(existing.tags || []), ...(input.tags || [])]),
+        confidence: Math.max(clamp(existing.confidence), clamp(input.confidence, existing.confidence ?? 0.7)),
+        taskClass: input.taskClass || existing.taskClass || null,
+        expiresAt: input.expiresAt || existing.expiresAt || null,
+      }
+      await writeMemoryState(root, state.memories.map((item) => item.id === existing.id ? reinforced : item))
+      return reinforced
     }
-    await writeMemoryState(root, state.memories.map((item) => item.id === id ? reinforced : item))
-    return reinforced
-  }
 
-  const memory = {
-    id,
-    key: input.key || null,
-    type,
-    scope,
-    content,
-    status: "candidate",
-    confidence: clamp(input.confidence),
-    evidenceRefs: uniq(input.evidenceRefs || []),
-    files: uniq((input.files || []).map(normalizeFile)),
-    tags: uniq(input.tags || []),
-    sourceTask: input.sourceTask || null,
-    sourceCommit: input.sourceCommit || null,
-    taskClass: input.taskClass || null,
-    expiresAt: input.expiresAt || null,
-    createdAt: timestamp,
-    lastSeenAt: timestamp,
-    lastUsedAt: null,
-    useCount: 0,
-    reinforcementCount: 1,
-    verifiedAt: null,
-    verifier: null,
-    supersededBy: null,
-  }
-  await writeMemoryState(root, [...state.memories, memory])
-  return memory
+    const memory = {
+      id,
+      key: input.key || null,
+      type,
+      scope,
+      content,
+      status: "candidate",
+      confidence: clamp(input.confidence),
+      evidenceRefs: uniq(input.evidenceRefs || []),
+      files: uniq((input.files || []).map(normalizeFile)),
+      dependencies: uniq((input.dependencies || []).map(normalizeFile)),
+      tags: uniq(input.tags || []),
+      sourceTask: input.sourceTask || null,
+      sourceCommit: input.sourceCommit || null,
+      taskClass: input.taskClass || null,
+      expiresAt: input.expiresAt || null,
+      createdAt: timestamp,
+      lastSeenAt: timestamp,
+      lastUsedAt: null,
+      useCount: 0,
+      reinforcementCount: 1,
+      verifiedAt: null,
+      verifier: null,
+      supersededBy: null,
+    }
+    await writeMemoryState(root, [...state.memories, memory])
+    return memory
+  })
 }
 
 export async function verifyMemory(root, id, verification = {}) {
@@ -150,47 +243,52 @@ export async function verifyMemory(root, id, verification = {}) {
     throw new Error("memory verification requires verdict PASS")
   }
   if (!verification.verifier) throw new Error("memory verification requires an independent verifier identity")
-  const state = await readMemoryState(root)
-  const current = state.memories.find((item) => item.id === id)
-  if (!current) throw new Error("unknown memory: " + id)
-  if (current.status === "superseded") throw new Error("cannot verify a superseded memory")
-
-  const refs = uniq([...(current.evidenceRefs || []), ...(verification.evidenceRefs || [])])
-  if (!refs.length) throw new Error("memory verification requires at least one durable evidence reference")
-  for (const ref of refs) {
-    if (!(await evidenceExists(root, ref))) throw new Error("memory evidence reference is missing: " + ref)
-  }
 
-  const verified = {
-    ...current,
-    status: "verified",
-    evidenceRefs: refs,
-    verifier: String(verification.verifier),
-    verifiedAt: now(),
-    lastSeenAt: now(),
-    confidence: Math.max(clamp(current.confidence), clamp(verification.confidence, current.confidence ?? 0.7)),
-  }
-  await writeMemoryState(root, state.memories.map((item) => item.id === id ? verified : item))
-  return verified
+  return withMemoryWriteLock(root, async () => {
+    const state = await readMemoryState(root)
+    const current = state.memories.find((item) => item.id === id)
+    if (!current) throw new Error("unknown memory: " + id)
+    if (current.status === "superseded") throw new Error("cannot verify a superseded memory")
+
+    const refs = uniq([...(current.evidenceRefs || []), ...(verification.evidenceRefs || [])])
+    if (!refs.length) throw new Error("memory verification requires at least one durable evidence reference")
+    for (const ref of refs) {
+      if (!(await evidenceExists(root, ref))) throw new Error("memory evidence reference is missing: " + ref)
+    }
+
+    const verified = {
+      ...current,
+      status: "verified",
+      evidenceRefs: refs,
+      verifier: String(verification.verifier),
+      verifiedAt: now(),
+      lastSeenAt: now(),
+      confidence: Math.max(clamp(current.confidence), clamp(verification.confidence, current.confidence ?? 0.7)),
+    }
+    await writeMemoryState(root, state.memories.map((item) => item.id === id ? verified : item))
+    return verified
+  })
 }
 
 export async function supersedeMemory(root, id, replacementId) {
   if (!replacementId || replacementId === id) throw new Error("replacement memory id must be different")
-  const state = await readMemoryState(root)
-  const current = state.memories.find((item) => item.id === id)
-  const replacement = state.memories.find((item) => item.id === replacementId)
-  if (!current) throw new Error("unknown memory: " + id)
-  if (!replacement) throw new Error("unknown replacement memory: " + replacementId)
-  if (replacement.status !== "verified") throw new Error("replacement memory must be verified before supersession")
-  const timestamp = now()
-  const superseded = {
-    ...current,
-    status: "superseded",
-    supersededBy: replacementId,
-    lastSeenAt: timestamp,
-  }
-  await writeMemoryState(root, state.memories.map((item) => item.id === id ? superseded : item))
-  return superseded
+  return withMemoryWriteLock(root, async () => {
+    const state = await readMemoryState(root)
+    const current = state.memories.find((item) => item.id === id)
+    const replacement = state.memories.find((item) => item.id === replacementId)
+    if (!current) throw new Error("unknown memory: " + id)
+    if (!replacement) throw new Error("unknown replacement memory: " + replacementId)
+    if (replacement.status !== "verified") throw new Error("replacement memory must be verified before supersession")
+    const timestamp = now()
+    const superseded = {
+      ...current,
+      status: "superseded",
+      supersededBy: replacementId,
+      lastSeenAt: timestamp,
+    }
+    await writeMemoryState(root, state.memories.map((item) => item.id === id ? superseded : item))
+    return superseded
+  })
 }
 
 function tokenVector(value, dims = 96) {
@@ -312,6 +410,7 @@ export function buildMemorySnapshot(memories = []) {
       content: normalizedContent(item.content),
       confidence: clamp(item.confidence),
       files: uniq((item.files || []).map(normalizeFile)).sort(),
+      dependencies: uniq((item.dependencies || []).map(normalizeFile)).sort(),
       taskClass: item.taskClass || null,
       verifiedAt: item.verifiedAt || null,
       evidenceRefs: uniq(item.evidenceRefs || []).sort(),
@@ -330,6 +429,96 @@ export function buildMemorySnapshot(memories = []) {
   }
 }
 
+function dependencyAdjacency(edges = []) {
+  const graph = new Map()
+  const connect = (left, right) => {
+    if (!left || !right) return
+    if (!graph.has(left)) graph.set(left, new Set())
+    graph.get(left).add(right)
+  }
+  for (const edge of edges || []) {
+    const from = normalizeFile(edge?.from)
+    const to = normalizeFile(edge?.to)
+    if (!from || !to) continue
+    // Retrieval uses dependency proximity, not ownership direction, so both
+    // importers and imported modules are useful neighbors.
+    connect(from, to)
+    connect(to, from)
+  }
+  return graph
+}
+
+function dependencyGraphAffinity(queryFiles, memoryFiles, adjacency, maxDepth = 3) {
+  if (!queryFiles.length || !memoryFiles.length || !adjacency?.size) return 0
+  const targets = new Set(memoryFiles.map(normalizeFile))
+  let best = 0
+  for (const source of queryFiles.map(normalizeFile)) {
+    if (targets.has(source)) return 1
+    let frontier = new Set([source])
+    const seen = new Set(frontier)
+    for (let depth = 1; depth <= maxDepth && frontier.size; depth += 1) {
+      const next = new Set()
+      for (const current of frontier) {
+        for (const neighbor of adjacency.get(current) || []) {
+          if (targets.has(neighbor)) {
+            const score = depth === 1 ? 0.95 : depth === 2 ? 0.7 : 0.45
+            best = Math.max(best, score)
+          }
+          if (!seen.has(neighbor)) {
+            seen.add(neighbor)
+            next.add(neighbor)
+          }
+        }
+      }
+      frontier = next
+    }
+  }
+  return best
+}
+
+function exactFileAffinity(queryFiles, memoryFiles) {
+  const wanted = new Set(queryFiles.map(normalizeFile))
+  return memoryFiles.some((file) => wanted.has(normalizeFile(file))) ? 1 : 0
+}
+
+function scopeEligible(item, queryFiles, pathGraph) {
+  if (!queryFiles.length) return true
+  const memoryFiles = uniq((item.files || []).map(normalizeFile))
+  if (item.scope === "file") return exactFileAffinity(queryFiles, memoryFiles) === 1
+  if (item.scope === "module") return pathGraph >= 0.45
+  return true
+}
+
+function memoryAgeDays(item) {
+  const timestamp = Date.parse(item.lastSeenAt || item.verifiedAt || item.createdAt || "")
+  if (!timestamp) return 0
+  return Math.max(0, (Date.now() - timestamp) / 86_400_000)
+}
+
+function memoryHalfLifeDays(item) {
+  const base = {
+    failure: 45,
+    episodic: 75,
+    decision: 120,
+    procedural: 180,
+    semantic: 240,
+  }[item.type] || 120
+  const reinforcement = Math.max(1, Number(item.reinforcementCount || 1))
+  return base * (1 + Math.log2(reinforcement) * 0.2)
+}
+
+function agingScore(item) {
+  const age = memoryAgeDays(item)
+  const halfLife = memoryHalfLifeDays(item)
+  return Math.pow(0.5, age / Math.max(1, halfLife))
+}
+
+function reinforcementScore(item) {
+  const reinforcement = Math.max(0, Number(item.reinforcementCount || 0))
+  const use = Math.max(0, Number(item.useCount || 0))
+  return Math.min(1, (Math.log1p(reinforcement) + 0.55 * Math.log1p(use)) / 4)
+}
+
 export async function retrieveMemories(root, query, options = {}) {
   const state = await readMemoryState(root)
   const memories = state.memories.filter((item) => item.status === "verified" && !item.supersededBy && !isExpired(item))
@@ -337,60 +526,121 @@ export async function retrieveMemories(root, query, options = {}) {
   const queryVector = tokenVector(query)
   const queryFiles = uniq((options.files || []).map(normalizeFile))
   const lexical = bm25Scores(memories, queryTokens)
-  const rows = memories.map((item, index) => ({
-    item,
-    lexical: lexical[index] || 0,
-    semantic: Math.max(0, cosine(queryVector, tokenVector(item.content))),
-    graph: graphAffinity(queryFiles, item.files || []),
-    taskClass: taskClassAffinity(options.taskClass, item.taskClass),
-    recency: recencyScore(item.lastUsedAt || item.lastSeenAt || item.verifiedAt || item.createdAt),
-    confidence: clamp(item.confidence),
-    scope: 0,
-  }))
-  for (const row of rows) row.scope = scopeAffinity(row.item.scope, row.graph)
+
+  let repoGraph = null
+  if (queryFiles.length && memories.length && options.dependencyGraph !== false) {
+    repoGraph = await buildRepoGraphCached(root, {
+      maxFiles: Math.max(100, Math.min(6000, Number(options.maxGraphFiles || 2500))),
+      ...(options.workspaceFingerprint ? { workspaceFingerprint: options.workspaceFingerprint } : {}),
+    }).catch(() => null)
+  }
+  const adjacency = dependencyAdjacency(repoGraph?.edges || [])
+
+  const rows = memories.map((item, index) => {
+    const memoryFiles = uniq((item.files || []).map(normalizeFile))
+    const pathGraph = graphAffinity(queryFiles, memoryFiles)
+    const dependency = dependencyGraphAffinity(
+      queryFiles,
+      uniq([...memoryFiles, ...(item.dependencies || []).map(normalizeFile)]),
+      adjacency,
+    )
+    const graph = Math.max(pathGraph, dependency)
+    const aging = agingScore(item)
+    const reinforcement = reinforcementScore(item)
+    return {
+      item,
+      lexical: lexical[index] || 0,
+      semantic: Math.max(0, cosine(queryVector, tokenVector([item.content, ...(item.tags || []), ...memoryFiles].join(" ")))),
+      graph,
+      pathGraph,
+      dependency,
+      taskClass: taskClassAffinity(options.taskClass, item.taskClass),
+      recency: recencyScore(item.lastUsedAt || item.lastSeenAt || item.verifiedAt || item.createdAt),
+      aging,
+      reinforcement,
+      confidence: clamp(item.confidence) * (0.65 + 0.35 * aging),
+      scope: 0,
+      scopeEligible: true,
+    }
+  })
+  for (const row of rows) {
+    row.scope = scopeAffinity(row.item.scope, row.pathGraph)
+    row.scopeEligible = options.strictScope === false
+      ? true
+      : scopeEligible(row.item, queryFiles, row.pathGraph)
+  }
   const ranks = {
     lexical: rankMap(rows, "lexical"),
     semantic: rankMap(rows, "semantic"),
     graph: rankMap(rows, "graph"),
+    dependency: rankMap(rows, "dependency"),
     taskClass: rankMap(rows, "taskClass"),
     recency: rankMap(rows, "recency"),
+    aging: rankMap(rows, "aging"),
+    reinforcement: rankMap(rows, "reinforcement"),
   }
   for (const row of rows) {
     let rrf = 0
-    for (const key of ["lexical", "semantic", "graph", "taskClass", "recency"]) {
+    for (const key of ["lexical", "semantic", "graph", "dependency", "taskClass", "recency", "aging", "reinforcement"]) {
       const rank = ranks[key].get(row.item.id)
       if (rank) rrf += 1 / (60 + rank)
     }
-    row.score = rrf + row.confidence * 0.01 + row.graph * 0.01 + row.scope * 0.006 + row.taskClass * 0.008
+    row.score =
+      rrf +
+      row.confidence * 0.01 +
+      row.graph * 0.01 +
+      row.dependency * 0.012 +
+      row.scope * 0.006 +
+      row.taskClass * 0.008 +
+      row.reinforcement * 0.006 +
+      row.aging * 0.004
   }
   const limit = Math.max(1, Math.min(Number(options.limit || 6), 30))
   const results = rows
-    .filter((row) => row.lexical > 0 || row.semantic > 0.05 || row.graph > 0)
+    .filter((row) =>
+      row.scopeEligible &&
+      (row.lexical > 0 || row.semantic > 0.05 || row.graph > 0 || row.dependency > 0)
+    )
     .sort((a, b) => b.score - a.score || b.confidence - a.confidence || a.item.id.localeCompare(b.item.id))
     .slice(0, limit)
     .map((row) => ({
       ...row.item,
       retrieval: {
+        version: 2,
         score: Number(row.score.toFixed(8)),
         lexical: Number(row.lexical.toFixed(6)),
         semantic: Number(row.semantic.toFixed(6)),
         graph: Number(row.graph.toFixed(6)),
+        pathGraph: Number(row.pathGraph.toFixed(6)),
+        dependency: Number(row.dependency.toFixed(6)),
         taskClass: Number(row.taskClass.toFixed(6)),
         scope: Number(row.scope.toFixed(6)),
         recency: Number(row.recency.toFixed(6)),
+        aging: Number(row.aging.toFixed(6)),
+        reinforcement: Number(row.reinforcement.toFixed(6)),
+        effectiveConfidence: Number(row.confidence.toFixed(6)),
       },
     }))
   if (options.touch === true && results.length) {
     const used = new Set(results.map((item) => item.id))
     const timestamp = now()
-    await writeMemoryState(root, state.memories.map((item) => used.has(item.id)
-      ? { ...item, lastUsedAt: timestamp, useCount: Number(item.useCount || 0) + 1 }
-      : item))
+    await withMemoryWriteLock(root, async () => {
+      const latest = await readMemoryState(root)
+      await writeMemoryState(root, latest.memories.map((item) => used.has(item.id)
+        ? { ...item, lastUsedAt: timestamp, useCount: Number(item.useCount || 0) + 1 }
+        : item))
+    })
   }
   return {
     schemaVersion: SCHEMA_VERSION,
+    retrievalVersion: 2,
     query: String(query || ""),
     eligible: memories.length,
+    dependencyGraph: repoGraph ? {
+      scannedFiles: repoGraph.scannedFiles || 0,
+      edgeCount: Array.isArray(repoGraph.edges) ? repoGraph.edges.length : 0,
+      truncated: repoGraph.truncated === true,
+    } : null,
     results,
     snapshot: buildMemorySnapshot(results),
   }

package/lib/model-config.mjs

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs"
-import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises"
 import path from "node:path"
 import { defaultModelPolicy, resolveModel } from "./model-policy.mjs"
 import { normalizeCapabilityProfile } from "./capability-registry.mjs"
@@ -7,6 +7,70 @@ import { normalizePerformanceHistory, recordPerformanceOutcome } from "./model-p
 
 const TIERS = new Set(["light", "standard", "heavy"])
 
+const MODEL_POLICY_WRITE_TAILS = new Map()
+const MODEL_POLICY_LOCK_STALE_MS = 15_000
+const MODEL_POLICY_LOCK_WAIT_MS = 20_000
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function modelPolicyLockDir(configDir) {
+  return modelPolicyFile(configDir) + ".lock"
+}
+
+async function withCrossProcessModelPolicyLock(configDir, fn) {
+  const lockDir = modelPolicyLockDir(configDir)
+  await mkdir(path.dirname(lockDir), { recursive: true })
+  const deadline = Date.now() + MODEL_POLICY_LOCK_WAIT_MS
+  let delayMs = 8
+  while (true) {
+    try {
+      await mkdir(lockDir)
+      break
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error
+      const info = await stat(lockDir).catch(() => null)
+      if (info && Date.now() - info.mtimeMs > MODEL_POLICY_LOCK_STALE_MS) {
+        const confirmed = await stat(lockDir).catch(() => null)
+        if (
+          confirmed &&
+          confirmed.ino === info.ino &&
+          confirmed.mtimeMs === info.mtimeMs
+        ) {
+          await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+          continue
+        }
+      }
+      if (Date.now() >= deadline) throw new Error("Timed out waiting for model-policy write lock")
+      await sleep(delayMs)
+      delayMs = Math.min(100, delayMs * 2)
+    }
+  }
+  try {
+    return await fn()
+  } finally {
+    await rm(lockDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+async function withModelPolicyWriteLock(configDir, fn) {
+  const key = path.resolve(configDir)
+  const previous = MODEL_POLICY_WRITE_TAILS.get(key) || Promise.resolve()
+  let release
+  const barrier = new Promise((resolve) => { release = resolve })
+  const tail = previous.catch(() => {}).then(() => barrier)
+  MODEL_POLICY_WRITE_TAILS.set(key, tail)
+
+  await previous.catch(() => {})
+  try {
+    return await withCrossProcessModelPolicyLock(configDir, fn)
+  } finally {
+    release()
+    if (MODEL_POLICY_WRITE_TAILS.get(key) === tail) MODEL_POLICY_WRITE_TAILS.delete(key)
+  }
+}
+
 function validModelID(value) {
   return typeof value === "string" && /^[^\s/]+\/[^\s#]+(?:#[^\s]+)?$/.test(value)
 }
@@ -61,8 +125,7 @@ export async function readModelPolicy(configDir) {
   }
 }
 
-export async function writeModelPolicy(configDir, patch = {}) {
-  const current = await readModelPolicy(configDir)
+async function persistModelPolicy(configDir, current, patch = {}) {
   const merged = normalize({
     ...current,
     ...patch,
@@ -73,10 +136,24 @@ export async function writeModelPolicy(configDir, patch = {}) {
   })
   const file = modelPolicyFile(configDir)
   await mkdir(path.dirname(file), { recursive: true })
-  await writeFile(file, JSON.stringify(merged, null, 2) + "\n", "utf8")
+  const temp = file + "." + process.pid + "." + Date.now() + ".tmp"
+  await writeFile(temp, JSON.stringify(merged, null, 2) + "\n", "utf8")
+  try {
+    await rename(temp, file)
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => {})
+    throw error
+  }
   return { ...merged, file }
 }
 
+export async function writeModelPolicy(configDir, patch = {}) {
+  return withModelPolicyWriteLock(configDir, async () => {
+    const current = await readModelPolicy(configDir)
+    return persistModelPolicy(configDir, current, patch)
+  })
+}
+
 export function validateModelID(value) {
   return validModelID(value)
 }
@@ -102,7 +179,9 @@ export function applyConfiguredModel(source, role, policy) {
 }
 
 export async function recordModelPerformance(configDir, outcome = {}) {
-  const current = await readModelPolicy(configDir)
-  const performance = recordPerformanceOutcome(current.performance || {}, outcome)
-  return writeModelPolicy(configDir, { performance })
+  return withModelPolicyWriteLock(configDir, async () => {
+    const current = await readModelPolicy(configDir)
+    const performance = recordPerformanceOutcome(current.performance || {}, outcome)
+    return persistModelPolicy(configDir, current, { performance })
+  })
 }