opencode-agent-skill 15.0.0 → 15.1.1

package/lib/semantic-index.mjs

@@ -45,6 +45,28 @@ async function atomicJson(file, value) {
   }
 }
 
+function indexIoConcurrency(value) {
+  const fallback = process.platform === "win32" ? 12 : 16
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback
+  return Math.max(1, Math.min(32, Math.trunc(parsed)))
+}
+
+async function mapLimit(items, limit, worker) {
+  if (!items.length) return []
+  const results = new Array(items.length)
+  let next = 0
+  const runners = Array.from({ length: Math.min(Math.max(1, limit), items.length) }, async () => {
+    while (true) {
+      const index = next++
+      if (index >= items.length) return
+      results[index] = await worker(items[index], index)
+    }
+  })
+  await Promise.all(runners)
+  return results
+}
+
 async function walk(root, options = {}) {
   const maxFiles = Math.max(100, Number(options.maxFiles || 6000))
   const maxDepth = Math.max(2, Number(options.maxDepth || 14))
@@ -164,32 +186,55 @@ export async function buildSemanticIndex(root = process.cwd(), options = {}) {
   let reparsed = 0
   let skippedLarge = 0
   const maxFileBytes = Math.max(64 * 1024, Number(options.maxFileBytes || 1024 * 1024))
+  const ioConcurrency = indexIoConcurrency(options.ioConcurrency)
 
-  for (const full of discovered.files) {
+  const indexed = await mapLimit(discovered.files, ioConcurrency, async (full) => {
     const info = await stat(full).catch(() => null)
-    if (!info?.isFile()) continue
+    if (!info?.isFile()) return null
     const relative = rel(root, full)
     const signature = info.size + ":" + Math.trunc(info.mtimeMs)
     const old = previous?.files?.[relative]
+    const tooLarge = info.size > maxFileBytes
+
+    // Reuse only when the current size policy makes the same parse/skip choice.
     if (old?.signature === signature) {
-      nextFiles[relative] = old
-      reused += 1
-      continue
+      const wasTooLarge = old?.skipped === "too-large"
+      if (wasTooLarge === tooLarge) {
+        return { relative, entry: old, outcome: "reused" }
+      }
     }
-    if (info.size > maxFileBytes) {
-      nextFiles[relative] = { signature, bytes: info.size, skipped: "too-large", symbols: [], identifiers: {} }
-      skippedLarge += 1
-      continue
+
+    if (tooLarge) {
+      return {
+        relative,
+        entry: { signature, bytes: info.size, skipped: "too-large", symbols: [], identifiers: {} },
+        outcome: "skipped-large",
+      }
     }
+
     const source = await readFile(full, "utf8").catch(() => "")
-    const parsed = source ? parseSource(source, path.extname(relative).toLowerCase()) : { symbols: [], identifiers: {} }
-    nextFiles[relative] = {
-      signature,
-      bytes: info.size,
-      symbols: parsed.symbols,
-      identifiers: parsed.identifiers,
+    const parsed = source
+      ? parseSource(source, path.extname(relative).toLowerCase())
+      : { symbols: [], identifiers: {} }
+    return {
+      relative,
+      entry: {
+        signature,
+        bytes: info.size,
+        symbols: parsed.symbols,
+        identifiers: parsed.identifiers,
+      },
+      outcome: "reparsed",
     }
-    reparsed += 1
+  })
+
+  // Keep cache JSON deterministic even though file I/O is concurrent.
+  for (const row of indexed) {
+    if (!row) continue
+    nextFiles[row.relative] = row.entry
+    if (row.outcome === "reused") reused += 1
+    else if (row.outcome === "skipped-large") skippedLarge += 1
+    else reparsed += 1
   }
 
   const removed = previous
@@ -217,6 +262,7 @@ export async function buildSemanticIndex(root = process.cwd(), options = {}) {
       truncated: discovered.truncated,
       cacheFile: rel(root, cachePath(root)),
       durationMs: Date.now() - started,
+      ioConcurrency,
     },
   }
 }
@@ -323,14 +369,15 @@ const RUNTIME_SEMANTIC_INFLIGHT = new Map()
 export async function buildSemanticIndexCached(root = process.cwd(), options = {}) {
   root = path.resolve(root)
   const fingerprint = String(options.workspaceFingerprint || "")
-  if (!fingerprint || fingerprint === "unknown") {
-    return buildSemanticIndex(root, options)
+  if (!fingerprint || fingerprint === "unknown" || options.rebuild === true) {
+    const value = await buildSemanticIndex(root, options)
+    return { ...value, runtimeCacheHit: false }
   }
 
   const maxFiles = Number(options.maxFiles ?? 6000)
   const maxDepth = Number(options.maxDepth ?? 14)
-  const maxBytes = Number(options.maxBytes ?? 768 * 1024)
-  const key = [root, fingerprint, maxFiles, maxDepth, maxBytes].join("\u0000")
+  const maxFileBytes = Math.max(64 * 1024, Number(options.maxFileBytes ?? 1024 * 1024))
+  const key = [root, fingerprint, maxFiles, maxDepth, maxFileBytes].join("\u0000")
   if (RUNTIME_SEMANTIC_CACHE.has(key)) {
     const value = RUNTIME_SEMANTIC_CACHE.get(key)
     RUNTIME_SEMANTIC_CACHE.delete(key)

package/lib/skill-compiler.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url"
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
 const SKILLS_ROOT = path.join(PACKAGE_ROOT, "global-config", "skills")
 const SKILL_SOURCE_CACHE = new Map()
+const SKILL_SOURCE_INFLIGHT = new Map()
 const COMPILED_SKILL_CACHE = new Map()
 
 const DOMAIN_SKILLS = Object.freeze({
@@ -66,27 +67,87 @@ function compileText(raw, maxChars) {
   return selected.join("\n").slice(0, maxChars)
 }
 
+function skillNameTokens(name) {
+  return String(name || "")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length >= 4 && !["engineering", "engineer"].includes(token))
+}
+
 export function selectSkillNames(taskPolicy = {}, role = "executor", options = {}) {
   const maxSkills = Math.max(1, Math.min(5, Number(options.maxSkills || taskPolicy.maxSkills || 3)))
-  const names = []
-  for (const name of ROLE_SKILLS[role] || []) names.push(name)
+  const roleNames = [...(ROLE_SKILLS[role] || [])]
+  const domainNames = []
   for (const domain of taskPolicy.domains || []) {
     const mapped = DOMAIN_SKILLS[domain]
-    if (mapped) names.push(mapped)
+    if (mapped) domainNames.push(mapped)
   }
-  return [...new Set(names)].slice(0, maxSkills)
+  const names = [...new Set([...roleNames, ...domainNames])]
+  const taskText = String(options.taskText || "").toLowerCase()
+  if (!taskText) return names.slice(0, maxSkills)
+
+  const primaryRole = roleNames[0] || null
+  const scored = names.map((name, index) => {
+    let score = Math.max(0, 40 - index)
+    const reasons = []
+    if (name === primaryRole) {
+      score += 120
+      reasons.push("primary-role")
+    } else if (roleNames.includes(name)) {
+      score += 55
+      reasons.push("role")
+    }
+    if (domainNames.includes(name)) {
+      score += 75
+      reasons.push("domain")
+    }
+    const overlaps = skillNameTokens(name).filter((token) => taskText.includes(token))
+    if (overlaps.length) {
+      score += Math.min(60, overlaps.length * 30)
+      reasons.push("task-text")
+    }
+    if (name === "task-planner" && /\b(plan|planning|architecture|migration|multi[- ]step|phase)\b/i.test(taskText)) {
+      score += 45
+      reasons.push("planning-signal")
+    }
+    if (name === "test-verification" && /\b(test|verify|verification|regression|failing|failure)\b/i.test(taskText)) {
+      score += 45
+      reasons.push("verification-signal")
+    }
+    if (name === "bug-diagnosis" && /\b(debug|bug|error|failure|crash|regression)\b/i.test(taskText)) {
+      score += 45
+      reasons.push("debug-signal")
+    }
+    return { name, score, index, reasons }
+  })
+
+  return scored
+    .sort((a, b) => b.score - a.score || a.index - b.index || a.name.localeCompare(b.name))
+    .slice(0, maxSkills)
+    .map((item) => item.name)
 }
 
 async function skillSource(name) {
   if (SKILL_SOURCE_CACHE.has(name)) return SKILL_SOURCE_CACHE.get(name)
-  const file = path.join(SKILLS_ROOT, name, "SKILL.md")
-  if (!existsSync(file)) {
-    SKILL_SOURCE_CACHE.set(name, "")
-    return ""
+  if (SKILL_SOURCE_INFLIGHT.has(name)) return SKILL_SOURCE_INFLIGHT.get(name)
+
+  const load = (async () => {
+    const file = path.join(SKILLS_ROOT, name, "SKILL.md")
+    if (!existsSync(file)) {
+      SKILL_SOURCE_CACHE.set(name, "")
+      return ""
+    }
+    const raw = await readFile(file, "utf8").catch(() => "")
+    SKILL_SOURCE_CACHE.set(name, raw)
+    return raw
+  })()
+
+  SKILL_SOURCE_INFLIGHT.set(name, load)
+  try {
+    return await load
+  } finally {
+    SKILL_SOURCE_INFLIGHT.delete(name)
   }
-  const raw = await readFile(file, "utf8").catch(() => "")
-  SKILL_SOURCE_CACHE.set(name, raw)
-  return raw
 }
 
 export async function compileSkillContext(taskPolicy = {}, role = "executor", options = {}) {
@@ -98,13 +159,16 @@ export async function compileSkillContext(taskPolicy = {}, role = "executor", op
     return { ...COMPILED_SKILL_CACHE.get(cacheKey), cacheHit: true }
   }
 
-  const skills = []
-  for (const name of names) {
-    const raw = await skillSource(name)
-    if (!raw) continue
-    const text = compileText(raw, perSkill)
-    if (text) skills.push({ name, text })
-  }
+  const loadedSources = await Promise.all(
+    names.map(async (name) => ({ name, raw: await skillSource(name) })),
+  )
+  const skills = loadedSources
+    .map(({ name, raw }) => {
+      if (!raw) return null
+      const text = compileText(raw, perSkill)
+      return text ? { name, text } : null
+    })
+    .filter(Boolean)
 
   const result = {
     schemaVersion: 1,
@@ -116,6 +180,7 @@ export async function compileSkillContext(taskPolicy = {}, role = "executor", op
       .map((item) => `### Skill: ${item.name}\n${item.text}`)
       .join("\n\n")
       .slice(0, totalChars),
+    selectionMode: options.taskText ? "relevance-ranked" : "role-domain-order",
     cacheHit: false,
   }
   COMPILED_SKILL_CACHE.set(cacheKey, result)
@@ -124,5 +189,6 @@ export async function compileSkillContext(taskPolicy = {}, role = "executor", op
 
 export function clearSkillCompilerCache() {
   SKILL_SOURCE_CACHE.clear()
+  SKILL_SOURCE_INFLIGHT.clear()
   COMPILED_SKILL_CACHE.clear()
 }

package/lib/subagent-artifacts.mjs

@@ -0,0 +1,182 @@
+import { createHash, randomUUID } from "node:crypto"
+import { existsSync } from "node:fs"
+import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises"
+import path from "node:path"
+import { putEvidence } from "./evidence-store.mjs"
+
+const ARTIFACT_DIR = path.join(".ues-work", ".subagents")
+const HANDLE_PATTERN = /^sa-[a-z0-9]+-[a-f0-9]{8}$/
+
+function now() {
+  return new Date().toISOString()
+}
+
+function hash(value) {
+  return createHash("sha256").update(String(value || "")).digest("hex").slice(0, 20)
+}
+
+function artifactDir(root) {
+  return path.join(path.resolve(root), ARTIFACT_DIR)
+}
+
+function artifactPath(root, handle) {
+  if (!HANDLE_PATTERN.test(String(handle || ""))) throw new Error("invalid subagent handle")
+  return path.join(artifactDir(root), handle + ".json")
+}
+
+async function atomicJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true })
+  const temp = file + "." + process.pid + "." + Date.now() + ".tmp"
+  await writeFile(temp, JSON.stringify(value, null, 2) + "\n", "utf8")
+  try {
+    await rename(temp, file)
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+function publicArtifact(root, artifact) {
+  return {
+    ...artifact,
+    file: path.relative(path.resolve(root), artifactPath(root, artifact.handle)).replaceAll("\\", "/"),
+  }
+}
+
+export async function createSubagentArtifact(root, input = {}) {
+  const handle = "sa-" + Date.now().toString(36) + "-" + randomUUID().replaceAll("-", "").slice(0, 8)
+  const task = String(input.task || "")
+  const taskEvidence = await putEvidence(root, task, {
+    kind: "subagent-task",
+    source: handle,
+    summary: `Exact delegated task for ${input.agent || "UES child"}`,
+  })
+  const timestamp = now()
+  const artifact = {
+    schemaVersion: 1,
+    handle,
+    status: "running",
+    agent: input.agent || null,
+    role: input.role || null,
+    attempt: Math.max(1, Number(input.attempt || 1)),
+    traceID: input.traceID || null,
+    model: input.model || null,
+    modelTier: input.modelTier || null,
+    workspaceFingerprint: input.workspaceFingerprint || null,
+    taskHash: hash(task),
+    taskPreview: task.replace(/\s+/g, " ").trim().slice(0, 1200),
+    taskRef: taskEvidence.ref,
+    startedAt: timestamp,
+    updatedAt: timestamp,
+    completedAt: null,
+    result: null,
+    resume: {
+      state: "running",
+      taskRef: taskEvidence.ref,
+      outputRef: null,
+      instruction: "Inspect this handle for status. Do not infer completion until status and verification evidence say so.",
+    },
+  }
+  await atomicJson(artifactPath(root, handle), artifact)
+  return publicArtifact(root, artifact)
+}
+
+export async function readSubagentArtifact(root, handle) {
+  const file = artifactPath(root, handle)
+  const parsed = JSON.parse(await readFile(file, "utf8"))
+  return publicArtifact(root, parsed)
+}
+
+export async function finalizeSubagentArtifact(root, handle, result = {}) {
+  const current = await readSubagentArtifact(root, handle)
+  const output = String(result.output || "")
+  const outputEvidence = output
+    ? await putEvidence(root, output, {
+        kind: "subagent-output",
+        source: handle,
+        summary: `Exact bounded child output for ${current.agent || "UES child"}`,
+      })
+    : null
+  const aborted = Number(result.exitCode) === 130 || String(result.stopReason || "").toLowerCase() === "aborted"
+  const status = aborted ? "aborted" : Number(result.exitCode || 0) === 0 ? "completed" : "failed"
+  const timestamp = now()
+  const artifact = {
+    ...current,
+    file: undefined,
+    status,
+    updatedAt: timestamp,
+    completedAt: timestamp,
+    result: {
+      exitCode: Number(result.exitCode ?? 1),
+      verdict: result.verdict || null,
+      stopReason: result.stopReason || null,
+      durationMs: Number(result.durationMs || 0),
+      toolCalls: Number(result.toolCalls || 0),
+      toolNames: Array.isArray(result.toolNames) ? result.toolNames.slice(0, 40) : [],
+      childRuntime: result.childRuntime || null,
+      workerReused: result.workerReused === true,
+      outputRef: outputEvidence?.ref || null,
+      outputPreview: output.replace(/\s+/g, " ").trim().slice(0, 1000),
+    },
+    resume: {
+      state: status,
+      taskRef: current.taskRef,
+      outputRef: outputEvidence?.ref || null,
+      instruction: status === "completed"
+        ? "Reuse the output evidence by reference; do not replay the child unless new evidence or a new task requires it."
+        : "Inspect task/output evidence and dispatch a fresh bounded child attempt from this handle's exact task context; do not trust partial narrative state.",
+    },
+  }
+  await atomicJson(artifactPath(root, handle), artifact)
+  return publicArtifact(root, artifact)
+}
+
+export async function failSubagentArtifact(root, handle, error) {
+  const current = await readSubagentArtifact(root, handle)
+  const timestamp = now()
+  const artifact = {
+    ...current,
+    file: undefined,
+    status: "failed",
+    updatedAt: timestamp,
+    completedAt: timestamp,
+    result: {
+      exitCode: 1,
+      verdict: "FAIL",
+      stopReason: "launch-error",
+      error: String(error instanceof Error ? error.message : error).slice(0, 2000),
+      outputRef: null,
+    },
+    resume: {
+      state: "failed",
+      taskRef: current.taskRef,
+      outputRef: null,
+      instruction: "The child did not complete. Re-dispatch from taskRef after diagnosing the launch/runtime failure.",
+    },
+  }
+  await atomicJson(artifactPath(root, handle), artifact)
+  return publicArtifact(root, artifact)
+}
+
+export async function listSubagentArtifacts(root, options = {}) {
+  const dir = artifactDir(root)
+  if (!existsSync(dir)) return { schemaVersion: 1, root: dir, count: 0, artifacts: [] }
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+  const rows = []
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue
+    try {
+      const parsed = JSON.parse(await readFile(path.join(dir, entry.name), "utf8"))
+      if (!HANDLE_PATTERN.test(String(parsed.handle || ""))) continue
+      rows.push(publicArtifact(root, parsed))
+    } catch {}
+  }
+  rows.sort((a, b) => Date.parse(b.updatedAt || b.startedAt || "") - Date.parse(a.updatedAt || a.startedAt || "") || a.handle.localeCompare(b.handle))
+  const limit = Math.max(1, Math.min(100, Number(options.limit || 20)))
+  return {
+    schemaVersion: 1,
+    root: path.relative(path.resolve(root), dir).replaceAll("\\", "/"),
+    count: rows.length,
+    artifacts: rows.slice(0, limit),
+  }
+}

package/lib/task-policy.mjs

@@ -172,6 +172,28 @@ function signal(name, matched, weight) {
   return matched ? { name, weight } : null
 }
 
+function taskDecisionConfidence(input = {}) {
+  if (
+    input.declaredHighRisk === true ||
+    input.sensitiveMutation === true ||
+    input.explicitLongHorizon === true ||
+    input.readOnly === true ||
+    input.singleFileBounded === true
+  ) return 0.96
+  if (input.debugging === true && input.boundedDebugHint === true) return 0.84
+  if (input.debugging === true && input.diagnosisEvidence !== true) return 0.68
+  if (Number(input.score || 0) >= 3) return 0.86
+  if (Number(input.score || 0) >= 2) return 0.80
+  return 0.74
+}
+
+function confidenceBand(value) {
+  const score = Number(value || 0)
+  if (score >= 0.90) return "high"
+  if (score >= 0.72) return "medium"
+  return "low"
+}
+
 function profileFor(mode, risk) {
   if (mode === "inline" && risk === "low") {
     return {
@@ -348,6 +370,7 @@ export function classifyEngineeringTask(text, facts = {}) {
     /\blong\s*[/|,+]\s*(?:high|critical)[-\s]?risk\b/i.test(value) ||
     /\b(?:high|critical)[-\s]?risk\s*[/|,+]\s*long\b/i.test(value)
   const explicitLongHorizon = declaredLongHorizon || compoundLongRisk || LONG.test(value)
+  const debugging = DEBUG.test(value)
   const signals = [
     signal("long-request-text", value.length > 700, 1),
     signal("medium-request-text", value.length > 250, 1),
@@ -355,7 +378,7 @@ export function classifyEngineeringTask(text, facts = {}) {
     signal("high-risk-operation", sensitiveMutation, 2),
     signal("declared-high-risk", declaredHighRisk, 2),
     signal("explicit-long-horizon", explicitLongHorizon, 2),
-    signal("debugging", DEBUG.test(value), 1),
+    signal("debugging", debugging, 1),
     signal("read-only", readOnly, -1),
     signal("single-file-bounded", singleFileBounded, -2),
     signal("public-contract", CONTRACT.test(value) || facts.hasPublicContract, 2),
@@ -369,18 +392,46 @@ export function classifyEngineeringTask(text, facts = {}) {
   const score = Math.max(0, signals.reduce((sum, item) => sum + item.weight, 0))
   const highRisk = declaredHighRisk || sensitiveMutation || Boolean(facts.hasMigration) || Boolean(facts.hasPublicContract)
   const diagnosisEvidence = facts.failureEvidence === true || CONCRETE_DIAGNOSIS.test(value)
+  const boundedDebugHint =
+    /\b(?:local|helper|parser|function|method|hook|useeffect|component|single|one)\b/i.test(value) &&
+    !BROAD_FILE_SCOPE.test(value)
+  const ambiguousDebug =
+    debugging &&
+    !diagnosisEvidence &&
+    !singleFileBounded &&
+    !boundedDebugHint &&
+    !explicitLongHorizon &&
+    !highRisk
   const risk = highRisk ? "high" : singleFileBounded ? "low" : score >= 3 ? "medium" : "low"
   const mode =
     explicitLongHorizon
       ? "long-horizon"
       : singleFileBounded && !highRisk
         ? "inline"
-        : score >= 4
-          ? "long-horizon"
-          : score >= 2
-            ? "standard"
-            : "inline"
-  const modelTier = risk === "high" || mode === "long-horizon" ? "heavy" : score >= 2 ? "standard" : "light"
+        : ambiguousDebug
+          ? "standard"
+          : score >= 4
+            ? "long-horizon"
+            : score >= 2
+              ? "standard"
+              : "inline"
+  const modelTier =
+    risk === "high" || mode === "long-horizon"
+      ? "heavy"
+      : ambiguousDebug || score >= 2
+        ? "standard"
+        : "light"
+  const decisionConfidence = taskDecisionConfidence({
+    declaredHighRisk,
+    sensitiveMutation,
+    explicitLongHorizon,
+    readOnly,
+    singleFileBounded,
+    debugging,
+    diagnosisEvidence,
+    boundedDebugHint,
+    score,
+  })
   const maxAttempts = risk === "high" ? 2 : 3
   const profile = profileFor(mode, risk)
 
@@ -412,6 +463,28 @@ export function classifyEngineeringTask(text, facts = {}) {
     readOnly,
     singleFileBounded,
     diagnosisEvidence,
+    ambiguousDebug,
+    boundedDebugHint,
+    decision: {
+      schemaVersion: 1,
+      kind: "task-route",
+      source: "deterministic",
+      confidence: decisionConfidence,
+      confidenceBand: confidenceBand(decisionConfidence),
+      value: { mode, risk, modelTier },
+      crossCheckRecommended: decisionConfidence < 0.72,
+      reason: ambiguousDebug
+        ? "debug-task-not-yet-bounded-by-file-or-concrete-failure-evidence"
+        : singleFileBounded
+          ? "single-file-bounded"
+          : boundedDebugHint
+            ? "bounded-debug-hint"
+            : explicitLongHorizon
+            ? "explicit-long-horizon"
+            : highRisk
+              ? "high-risk-signal"
+              : "weighted-task-signals",
+    },
     profile: readOnly
       ? {
           ...profile,

package/lib/trajectory.mjs

@@ -9,6 +9,25 @@ const DEFAULT_MAX_TRACE_TOTAL_BYTES = 24 * 1024 * 1024
 const DEFAULT_MAX_TRACE_FILES = 32
 const DEFAULT_MAX_TRACE_AGE_MS = 7 * 86_400_000
 
+const TRACE_WRITE_TAILS = new Map()
+
+async function withTraceWriteLock(root, fn) {
+  const key = path.resolve(root)
+  const previous = TRACE_WRITE_TAILS.get(key) || Promise.resolve()
+  let release
+  const barrier = new Promise((resolve) => { release = resolve })
+  const tail = previous.catch(() => {}).then(() => barrier)
+  TRACE_WRITE_TAILS.set(key, tail)
+
+  await previous.catch(() => {})
+  try {
+    return await fn()
+  } finally {
+    release()
+    if (TRACE_WRITE_TAILS.get(key) === tail) TRACE_WRITE_TAILS.delete(key)
+  }
+}
+
 function positiveInt(value, fallback, min, max) {
   const parsed = Number(value)
   if (!Number.isFinite(parsed)) return fallback
@@ -154,7 +173,7 @@ export function trajectoryFile(root, traceID) {
   return path.join(path.resolve(root), TRACE_DIR, cleanID(traceID) + ".jsonl")
 }
 
-export async function appendTrajectoryEvent(root, traceID, type, payload = {}) {
+async function appendTrajectoryEventUnlocked(root, traceID, type, payload = {}) {
   root = path.resolve(root)
   const file = trajectoryFile(root, traceID)
   await mkdir(path.dirname(file), { recursive: true })
@@ -182,6 +201,11 @@ export async function appendTrajectoryEvent(root, traceID, type, payload = {}) {
   return { file: path.relative(path.resolve(root), file).replaceAll("\\", "/"), event }
 }
 
+export async function appendTrajectoryEvent(root, traceID, type, payload = {}) {
+  root = path.resolve(root)
+  return withTraceWriteLock(root, () => appendTrajectoryEventUnlocked(root, traceID, type, payload))
+}
+
 export async function readTrajectory(root, traceID, options = {}) {
   const file = trajectoryFile(root, traceID)
   const source = await readFile(file, "utf8").catch(() => "")