opencode-agent-skill 15.0.0 → 15.1.0

package/lib/performance-fabric.mjs

@@ -9,23 +9,41 @@ function clampInt(value, fallback, min, max) {
   return Math.max(min, Math.min(max, Math.trunc(parsed)))
 }
 
-function uniqueSignalLines(text, limit = 48) {
+function hintFor(options = {}) {
+  return String(options.command || options.source || options.kind || "")
+    .trim()
+    .replace(/\s+/g, " ")
+    .toLowerCase()
+}
+
+function uniqRows(rows, limit = 100) {
   const seen = new Set()
+  const result = []
+  for (const value of rows || []) {
+    const row = String(value || "").trimEnd()
+    if (!row || seen.has(row)) continue
+    seen.add(row)
+    result.push(row)
+    if (result.length >= limit) break
+  }
+  return result
+}
+
+function matchingLines(source, patterns, limit = 100) {
   const rows = []
-  for (const raw of String(text || "").split(/\r?\n/)) {
-    const line = raw.trimEnd()
-    if (!line || !SIGNAL_LINE.test(line) || seen.has(line)) continue
-    seen.add(line)
-    rows.push(line)
+  for (const raw of String(source || "").split(/\r?\n/)) {
+    if (patterns.some((pattern) => pattern.test(raw))) rows.push(raw)
     if (rows.length >= limit) break
   }
-  return rows
+  return uniqRows(rows, limit)
 }
 
-function testSummaryLines(source, limit = 80) {
-  const rows = []
-  const seen = new Set()
-  const patterns = [
+function uniqueSignalLines(text, limit = 48) {
+  return matchingLines(text, [SIGNAL_LINE], limit)
+}
+
+function npmTestRows(source, limit = 100) {
+  return matchingLines(source, [
     /^FAIL\b/i,
     /^PASS\b/i,
     /^Test Suites:/i,
@@ -38,80 +56,124 @@ function testSummaryLines(source, limit = 80) {
     /^\s*●\s+/,
     /^\s*at\s+.+:\d+:\d+/,
     /(?:AssertionError|Expected|Received|Traceback|panic:|FAILED\s)/i,
-  ]
-  for (const raw of String(source || "").split(/\r?\n/)) {
-    const line = raw.trimEnd()
-    if (!line || seen.has(line) || !patterns.some((re) => re.test(line))) continue
-    seen.add(line)
-    rows.push(line)
-    if (rows.length >= limit) break
-  }
-  return rows
+    /^not ok\b/i,
+    /^ok\s+\d+\b/i,
+    /^#\s+(?:tests|suites|pass|fail|cancelled|skipped|todo|duration_ms)\b/i,
+  ], limit)
 }
 
-function gitSummaryLines(source, limit = 120) {
-  const rows = []
-  for (const raw of String(source || "").split(/\r?\n/)) {
+function pytestRows(source, limit = 100) {
+  return matchingLines(source, [
+    /^(?:FAILED|ERROR)\b/,
+    /^=+\s+.*(?:passed|failed|error|skipped|xfailed|xpassed).*\s+=+$/i,
+    /^E\s{2,}/,
+    /^_+\s+.+\s+_+$/,
+    /^Traceback \(most recent call last\):/,
+    /^\s*File ".+", line \d+/,
+    /(?:AssertionError|ImportError|ModuleNotFoundError|pytest\.)/,
+    /collected\s+\d+\s+items?/i,
+  ], limit)
+}
+
+function gitDiffRows(source, limit = 140) {
+  return matchingLines(source, [
+    /^diff --git /,
+    /^index [0-9a-f.]+/i,
+    /^@@ /,
+    /^(?:---|\+\+\+) /,
+    /^fatal:/i,
+    /^error:/i,
+    /^CONFLICT\b/i,
+    /^rename (?:from|to) /,
+    /^new file mode /,
+    /^deleted file mode /,
+    /^\s*\d+ files? changed/i,
+  ], limit)
+}
+
+function rgRows(source, limit = 100) {
+  const lines = String(source || "").split(/\r?\n/).filter(Boolean)
+  const matched = []
+  for (const line of lines) {
     if (
-      /^diff --git /.test(raw) ||
-      /^@@ /.test(raw) ||
-      /^(?:---|\+\+\+) /.test(raw) ||
-      /^fatal:/i.test(raw) ||
-      /^error:/i.test(raw) ||
-      /^CONFLICT\b/i.test(raw)
-    ) {
-      rows.push(raw)
-      if (rows.length >= limit) break
-    }
+      /^(?:[^:\n]+:)?\d+(?::\d+)?:/.test(line) ||
+      /^\.?[^:\n]+:\s/.test(line) ||
+      /(?:error|permission denied|binary file|no such file)/i.test(line)
+    ) matched.push(line)
+    if (matched.length >= limit) break
   }
-  return rows
+  const rows = matched.length ? matched : lines.slice(0, limit)
+  return uniqRows(rows, limit)
 }
 
+function treeRows(source, limit = 120) {
+  const lines = String(source || "").split(/\r?\n/).filter(Boolean)
+  if (lines.length <= limit) return uniqRows(lines, limit)
+  const head = lines.slice(0, Math.max(1, limit - 12))
+  const tail = lines.slice(-12)
+  return uniqRows([...head, `...[tree omitted ${Math.max(0, lines.length - head.length - tail.length)} rows]...`, ...tail], limit)
+}
 
-function lintSummaryLines(source, limit = 100) {
-  const rows = []
-  const seen = new Set()
-  const patterns = [
-    /\b(?:error|warning)\b/i,
+function tscRows(source, limit = 120) {
+  return matchingLines(source, [
+    /\berror\s+TS\d+\b/i,
+    /^.+\(\d+,\d+\):\s+error\s+TS\d+/i,
+    /^.+:\d+:\d+\s+-\s+error\s+TS\d+/i,
+    /^Found\s+\d+\s+errors?/i,
+    /\b(?:ELIFECYCLE|ERR_|exit code)\b/i,
+  ], limit)
+}
+
+function eslintRows(source, limit = 120) {
+  return matchingLines(source, [
+    /^\/?[^\n]+\.[cm]?[jt]sx?$/i,
+    /^\s*\d+:\d+\s+(?:error|warning)\s+/i,
     /\b\d+\s+problems?\b/i,
     /\b\d+\s+errors?\b/i,
     /\b\d+\s+warnings?\b/i,
-    /\b(?:eslint|ruff|flake8|pylint|clippy)\b/i,
-    /:\d+:\d+\b/,
     /^✖\s+/,
-  ]
-  for (const raw of String(source || "").split(/\r?\n/)) {
-    const line = raw.trimEnd()
-    if (!line || seen.has(line) || !patterns.some((pattern) => pattern.test(line))) continue
-    seen.add(line)
-    rows.push(line)
-    if (rows.length >= limit) break
-  }
-  return rows
+    /\beslint\b.*\b(?:error|warning|failed)\b/i,
+  ], limit)
 }
 
-function buildSummaryLines(source, limit = 100) {
-  const rows = []
-  const seen = new Set()
-  const patterns = [
-    /\berror\s+TS\d+\b/i,
+function dockerRows(source, limit = 120) {
+  return matchingLines(source, [
+    /^#\d+\s+/,
+    /^\s*=>\s+/,
+    /\b(?:error|failed|failure|fatal|warning|unhealthy|exited)\b/i,
+    /^NAME\s+IMAGE\s+COMMAND/i,
+    /^NAME\s+STATUS/i,
+    /^\[?\+\]?\s+(?:Running|Started|Stopped|Created|Built|Recreated)/i,
+    /(?:container|service|network|volume).*(?:created|started|stopped|failed|error)/i,
+  ], limit)
+}
+
+function prismaRows(source, limit = 120) {
+  return matchingLines(source, [
+    /Prisma schema loaded from/i,
+    /Datasource\s+".+"/i,
+    /Applying migration/i,
+    /migrations? found/i,
+    /Generated Prisma Client/i,
+    /Your database is now in sync/i,
+    /The following migration/i,
+    /\bP\d{4}\b/,
+    /\b(?:error|failed|warning)\b/i,
+    /schema\.prisma:\d+/i,
+  ], limit)
+}
+
+function genericBuildRows(source, limit = 100) {
+  return matchingLines(source, [
     /\b(?:compile|compiled|compilation|build)\b.*\b(?:failed|success|succeeded|complete|completed)\b/i,
     /\b(?:failed|fatal|exception|panic)\b/i,
     /\bwarning\b/i,
     /:\d+:\d+\b/,
     /\b(?:ELIFECYCLE|ERR_|exit code)\b/i,
-  ]
-  for (const raw of String(source || "").split(/\r?\n/)) {
-    const line = raw.trimEnd()
-    if (!line || seen.has(line) || !patterns.some((pattern) => pattern.test(line))) continue
-    seen.add(line)
-    rows.push(line)
-    if (rows.length >= limit) break
-  }
-  return rows
+  ], limit)
 }
 
-function jsonSummaryLines(source, limit = 80) {
+function jsonRows(source, limit = 80) {
   const text = String(source || "").trim()
   if (!text || text.length > 4 * 1024 * 1024 || !/^[\[{]/.test(text)) return []
   let value
@@ -134,50 +196,132 @@ function jsonSummaryLines(source, limit = 80) {
       }
       return
     }
-    const rendered = JSON.stringify(current)
-    rows.push(`${prefix || "$"}: ${String(rendered).slice(0, 160)}`)
+    rows.push(`${prefix || "$"}: ${String(JSON.stringify(current)).slice(0, 160)}`)
   }
   visit(value, "", 0)
   return rows
 }
 
-function structuredSignalLines(source, options = {}) {
-  const hint = String(options.kind || options.source || options.command || "").toLowerCase()
-  if (/(jest|vitest|pytest|test|spec)/.test(hint)) {
-    const rows = testSummaryLines(source)
-    if (rows.length) return { kind: "test", rows }
-  }
-  if (/(eslint|lint|ruff|flake8|pylint|clippy)/.test(hint)) {
-    const rows = lintSummaryLines(source)
-    if (rows.length) return { kind: "lint", rows }
-  }
-  if (/(typecheck|tsc|compile|build|gradle|maven|cargo check|dotnet build)/.test(hint)) {
-    const rows = buildSummaryLines(source)
-    if (rows.length) return { kind: "build", rows }
+const REDUCERS = Object.freeze([
+  {
+    family: "npm-test",
+    match: (hint) => /(?:^|\s)(?:npm|pnpm|yarn)\s+(?:run\s+)?test\b|node\s+--test\b|\b(?:jest|vitest)\b/.test(hint),
+    rows: npmTestRows,
+  },
+  {
+    family: "pytest",
+    match: (hint) => /\b(?:pytest|py\.test)\b/.test(hint),
+    rows: pytestRows,
+  },
+  {
+    family: "git-diff",
+    match: (hint) => /\bgit\s+(?:diff|show)\b/.test(hint),
+    rows: gitDiffRows,
+  },
+  {
+    family: "ripgrep",
+    match: (hint) => /(?:^|\s)(?:rg|ripgrep)(?:\s|$)|\bgrep\b/.test(hint),
+    rows: rgRows,
+  },
+  {
+    family: "tree",
+    match: (hint) => /(?:^|[;&|]\s*|\s)(?:tree)(?:\s|$)/.test(hint) || hint === "tree",
+    rows: treeRows,
+  },
+  {
+    family: "tsc",
+    match: (hint) => /\b(?:tsc|typescript|typecheck)\b/.test(hint),
+    rows: tscRows,
+  },
+  {
+    family: "eslint",
+    match: (hint) => /\b(?:eslint|lint)\b/.test(hint),
+    rows: eslintRows,
+  },
+  {
+    family: "docker",
+    match: (hint) => /\bdocker(?:\s+compose)?\b/.test(hint),
+    rows: dockerRows,
+  },
+  {
+    family: "prisma",
+    match: (hint) => /\bprisma\b|schema\.prisma/.test(hint),
+    rows: prismaRows,
+  },
+  {
+    family: "build",
+    match: (hint) => /\b(?:compile|build|gradle|maven|mvn|cargo\s+check|dotnet\s+build)\b/.test(hint),
+    rows: genericBuildRows,
+  },
+])
+
+export const COMMAND_REDUCER_FAMILIES = Object.freeze(REDUCERS.map((item) => item.family))
+
+export function reduceCommandOutput(source, options = {}) {
+  const text = String(source || "")
+  const hint = hintFor(options)
+  const reducer = REDUCERS.find((item) => item.match(hint))
+  if (reducer) {
+    const rows = reducer.rows(text)
+    if (rows.length) {
+      return {
+        schemaVersion: 2,
+        family: reducer.family,
+        hint,
+        rows,
+        summary: `command-aware reducer=${reducer.family}; selected=${rows.length}; totalLines=${text.split(/\r?\n/).length}`,
+      }
+    }
   }
-  if (/(git|diff|status)/.test(hint)) {
-    const rows = gitSummaryLines(source)
-    if (rows.length) return { kind: "git", rows }
+
+  if (/(?:--json|\bjson\b)/.test(hint) || /^[\s]*[\[{]/.test(text)) {
+    const rows = jsonRows(text)
+    if (rows.length) {
+      return {
+        schemaVersion: 2,
+        family: "json",
+        hint,
+        rows,
+        summary: `command-aware reducer=json; selected=${rows.length}`,
+      }
+    }
   }
-  if (/(json|--json)/.test(hint) || /^[\s]*[\[{]/.test(String(source || ""))) {
-    const rows = jsonSummaryLines(source)
-    if (rows.length) return { kind: "json", rows }
+
+  const rows = uniqueSignalLines(text)
+  return {
+    schemaVersion: 2,
+    family: rows.length ? "signal" : "generic",
+    hint,
+    rows,
+    summary: rows.length
+      ? `generic signal reducer; selected=${rows.length}`
+      : "generic head/tail fallback; no structured signal reducer matched",
   }
-  const rows = uniqueSignalLines(source)
-  return { kind: rows.length ? "signal" : "generic", rows }
+}
+
+function legacyStrategyKind(source, options = {}) {
+  const hint = hintFor(options)
+  if (/(jest|vitest|pytest|test|spec)/.test(hint) && npmTestRows(source).length) return "test"
+  if (/(eslint|lint|ruff|flake8|pylint|clippy)/.test(hint) && eslintRows(source).length) return "lint"
+  if (/(typecheck|tsc|compile|build|gradle|maven|cargo check|dotnet build)/.test(hint) && genericBuildRows(source).length) return "build"
+  if (/(git|diff|status)/.test(hint) && gitDiffRows(source).length) return "git"
+  if ((/(json|--json)/.test(hint) || /^[\s]*[\[{]/.test(String(source || ""))) && jsonRows(source).length) return "json"
+  return uniqueSignalLines(source).length ? "signal" : "generic"
 }
 
 function boundedPreview(text, maxChars, options = {}) {
   const source = String(text || "")
-  const headBudget = Math.max(2048, Math.floor(maxChars * 0.24))
-  const tailBudget = Math.max(4096, Math.floor(maxChars * 0.30))
-  const signalBudget = Math.max(2048, maxChars - headBudget - tailBudget - 1800)
+  const headBudget = Math.max(1536, Math.floor(maxChars * 0.18))
+  const tailBudget = Math.max(2048, Math.floor(maxChars * 0.24))
+  const signalBudget = Math.max(2048, maxChars - headBudget - tailBudget - 1900)
   const head = source.slice(0, headBudget)
   const tail = source.slice(Math.max(head.length, source.length - tailBudget))
-  const structured = structuredSignalLines(source, options)
-  let signalText = structured.rows.join("\n")
-  if (signalText.length > signalBudget) signalText = signalText.slice(0, signalBudget) + "\n...[signal lines truncated]"
-  return { head, tail, signalText, signalKind: structured.kind }
+  const reduced = reduceCommandOutput(source, options)
+  let signalText = [reduced.summary, ...reduced.rows].join("\n")
+  if (signalText.length > signalBudget) {
+    signalText = signalText.slice(0, signalBudget) + "\n...[reducer output truncated]"
+  }
+  return { head, tail, signalText, reducer: reduced }
 }
 
 export async function compactReversibleOutput(root, text, options = {}) {
@@ -185,9 +329,10 @@ export async function compactReversibleOutput(root, text, options = {}) {
   const maxChars = clampInt(options.maxChars, DEFAULT_LIMIT, 8 * 1024, 256 * 1024)
   if (source.length <= maxChars) {
     return {
-      schemaVersion: 1,
+      schemaVersion: 2,
       compacted: false,
       strategy: "raw",
+      commandFamily: null,
       originalChars: source.length,
       returnedChars: source.length,
       evidenceRef: null,
@@ -195,35 +340,45 @@ export async function compactReversibleOutput(root, text, options = {}) {
     }
   }
 
+  // Raw bytes are persisted before any model-visible reduction. Reducers never
+  // become the verification source of truth; verifiers can recover exact data.
   const evidence = await putEvidence(root, source, {
     kind: options.kind || "raw-tool-output",
-    source: options.source || "ues-performance-fabric",
-    summary: options.summary || `Raw output preserved before model-visible compaction (${source.length} chars)`,
+    source: options.source || options.command || "ues-performance-fabric-v2",
+    summary: options.summary || `Raw output preserved before command-aware model-visible compaction (${source.length} chars)`,
   })
-  const { head, tail, signalText, signalKind } = boundedPreview(source, maxChars, options)
+  const { head, tail, signalText, reducer } = boundedPreview(source, maxChars, options)
   const recovery = `Raw captured output: ${evidence.ref}. Recover exact captured bytes in slices with: ues store get ${evidence.ref} --start N --max 24000`
   let preview = [
-    `[UES reversible output compaction: ${source.length} -> <=${maxChars} chars; reducer=${signalKind}]`,
+    `[UES command-aware reversible compaction v2: ${source.length} -> <=${maxChars} chars; reducer=${reducer.family}]`,
     recovery,
     "",
-    "--- head ---",
+    "--- reducer summary ---",
+    signalText,
+    "",
+    "--- bounded head ---",
     head,
-    signalText ? "\n--- high-signal lines ---\n" + signalText : "",
-    "\n--- tail ---",
+    "",
+    "--- bounded tail ---",
     tail,
   ].filter(Boolean).join("\n")
   if (preview.length > maxChars) {
-    const reserve = Math.min(1400, recovery.length + 160)
+    const reserve = Math.min(1500, recovery.length + 200)
     preview = preview.slice(0, Math.max(0, maxChars - reserve)) + `\n...[model-visible preview truncated]\n${recovery}`
   }
 
+  const compatibilityKind = legacyStrategyKind(source, options)
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     compacted: true,
-    strategy: `reversible-head-${signalKind}-tail`,
+    // Keep the V14 public strategy contract stable for callers/tests while
+    // exposing the richer V2 reducer identity separately.
+    strategy: `reversible-head-${compatibilityKind}-tail`,
+    strategyV2: `reversible-command-aware-${reducer.family}`,
+    commandFamily: reducer.family,
     originalChars: source.length,
     returnedChars: preview.length,
     evidenceRef: evidence.ref,
     text: preview,
   }
-}
+}

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),
+  }
+}