opencode-agent-skill 14.4.0 → 15.0.0

package/lib/task-policy.mjs

@@ -2,12 +2,32 @@ const SENSITIVE_DOMAIN = /(\bauth\b|authorization|authentication|security|permis
 const HIGH_RISK_MUTATION = /((?:fix|change|modify|update|alter|migrate|drop|truncate|delete|remove|rotate|deploy|publish|push|sửa|thay đổi|cập nhật|xóa|xoá|di trú|chuyển đổi|triển khai).{0,64}(?:\bauth\b|authorization|authentication|security|permission|payment(?: handling| flow)?|schema|database|production|public api|secret|credential|phân quyền|bảo mật|thanh toán|cơ sở dữ liệu|api công khai|bí mật|thông tin xác thực)|(?:\bauth\b|authorization|authentication|security|permission|payment(?: handling| flow)?|schema|database|production|public api|secret|credential|phân quyền|bảo mật|thanh toán|cơ sở dữ liệu|api công khai|bí mật|thông tin xác thực).{0,64}(?:fix|change|modify|update|alter|migrate|drop|truncate|delete|remove|rotate|deploy|publish|push|sửa|thay đổi|cập nhật|xóa|xoá|di trú|chuyển đổi|triển khai)|database migration|schema migration|migrate database|migrate schema|drop table|truncate table|deploy(?:ment)?\s+(?:to\s+)?production|production\s+deploy(?:ment)?|rotate\s+(?:secret|credential)|breaking\s+(?:change\s+to\s+)?(?:public\s+)?api|npm publish|git push|force push|reset --hard|git clean)/i
 const LONG = /(whole repo|whole repository|whole project|entire repo|entire project|large refactor|major refactor|long[- ](?:running|horizon)|durable state|dependency graph|integration verification|resume|refactor all|multi[- ]step migration|migration across|toàn bộ repo|toàn bộ repository|toàn bộ dự án|toàn bộ project|refactor lớn|tác vụ dài|nhiều file|nhiều module|tiếp tục công việc|refactor toàn bộ|xác minh tích hợp|kiểm tra tích hợp|chia (?:công việc|task|tác vụ).*(?:dependency|phụ thuộc))/i
 const DEBUG = /(fix|bug|debug|crash|regression|failure|error|broken|sửa lỗi|lỗi|điều tra lỗi|không chạy)/i
+const CONCRETE_DIAGNOSIS = /(\bdebug\b|diagnos|reproduce|stack\s*trace|exception|\bcrash(?:es|ed|ing)?\b|failing\s+test|tests?\s+(?:currently\s+)?fail(?:ing|ed)?|failure\s+(?:affects|occurs|happens|when|on)|error\s*[:=]|expected.{0,48}actual|actual.{0,48}expected|exit\s+code\s*[1-9]|\b(?:ECONN\w*|SQLSTATE|TypeError|ReferenceError|AssertionError)\b|điều\s+tra\s+lỗi|tái\s+hiện\s+lỗi|lỗi\s*[:=]|test.{0,32}(?:thất\s+bại|fail))/i
 const CONTRACT = /(public api|api contract|openapi|response schema|request schema|breaking api|hợp đồng api|api công khai)/i
 const DATA = /(database|sql|migration|schema|transaction|index|cơ sở dữ liệu|dữ liệu|migrate)/i
 const BROAD_FILE_SCOPE = /(across\s+(?:multiple|several|many)\s+(?:files|modules|packages)|multiple\s+(?:files|modules|packages)|several\s+(?:files|modules|packages)|many\s+(?:files|modules|packages)|nhiều\s+(?:file|tệp|module)|toàn bộ\s+(?:repo|repository|project|dự án))/i
 const CRITICAL_LOCAL_MUTATION = /(drop\s+table|truncate\s+table|reset\s+--hard|git\s+clean|force\s+push|npm\s+publish|deploy(?:ment)?\s+(?:to\s+)?production|production\s+deploy(?:ment)?|rotate\s+(?:secret|credential)|(?:secret|credential|token).{0,48}(?:rotate|replace|revoke|delete)|(?:authorization|authentication|permission|phân quyền|xác thực).{0,64}(?:change|modify|update|bypass|remove|delete|sửa|thay đổi)|(?:database|sql|schema).{0,64}(?:migration|migrate|drop|truncate|alter)|(?:migration|migrate).{0,64}(?:database|sql|schema)|payment.{0,64}(?:charge|capture|refund|webhook|checkout)|(?:charge|capture|refund|webhook|checkout).{0,64}payment|breaking\s+(?:change\s+to\s+)?(?:public\s+)?api)/i
+const EXPLICIT_READ_ONLY = /(?:\bread[- ]?only\b|\bdo not\s+(?:edit|modify|change|write|create|delete|remove)\b|\bwithout\s+(?:editing|modifying|changing|writing|creating|deleting|removing)\b|\bno\s+(?:source|file|code)?\s*(?:edits?|changes?|writes?)\b|không\s+(?:sửa|chỉnh sửa|thay đổi|ghi|tạo|xóa|xoá)\b|chỉ\s+(?:đọc|kiểm tra|rà soát)\b)/i
+const READ_ONLY_MODE = /(?:\bread[- ]?only\b|chế\s+độ\s+chỉ\s+đọc|chế\s+độ\s+read[- ]?only)/i
+const MUTATION_INTENT = /(?:\b(?:fix|repair|implement|add|edit|modify|change|write|create|delete|remove|update|refactor|migrate|rename)\b|(?:sửa|chỉnh sửa|thay đổi|ghi|tạo|xóa|xoá|cập nhật|refactor|di trú|đổi tên))/i
 const SOURCE_FILE_RE = /(?:^|[\s("'\x60])((?:[A-Za-z]:)?(?:[./\\\w@-]+[\\/])*[\w@.-]+\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|kts|cs|rb|php|swift|dart|vue|svelte))(?=$|[\s"'\x60),:;.])/gi
 
+const COMMAND_ONLY_READ_ONLY = /(?:chỉ\s+(?:chạy|thực hiện)(?:\s+đúng)?|only\s+(?:run|execute)|run\s+only|execute\s+only|exactly\s+(?:run|execute))/i
+
+const AUTO_ENGINEERING_ACTION = /(?:\b(?:fix|repair|debug|implement|add|edit|modify|change|update|refactor|migrate|review|audit|verify|test|build|run|inspect|scan|check|analy[sz]e|optimi[sz]e|cleanup|clean up|commit|push|continue|resume)\b|(?:sửa|chỉnh sửa|xử lý|điều tra|thêm|tạo|cập nhật|thay đổi|refactor|di trú|rà soát|kiểm tra|xác minh|chạy|test|build|xem|phân tích|tối ưu|dọn|commit|push|tiếp tục))/i
+const AUTO_ENGINEERING_TARGET = /(?:\b(?:repo(?:sitory)?|project|code|source|file|module|package|branch|commit|git|npm|pnpm|yarn|node|typescript|javascript|python|java|kotlin|swift|react|expo|android|ios|api|backend|frontend|mobile|web|database|db|sql|prisma|test|e2e|ci|build|lint|typecheck|runtime|server|client|bug|error|failure|exception)\b|(?:dự án|mã nguồn|tệp|nhánh|cơ sở dữ liệu|dữ liệu|kiểm thử|lỗi|ứng dụng|giao diện|máy chủ))/i
+const AUTO_INFORMATIONAL_ONLY = /(?:^|\b)(?:explain|what\s+is|what\s+are|how\s+does|why\s+does|compare|difference\s+between|giải\s+thích|là\s+gì|hoạt\s+động\s+(?:ra\s+sao|thế\s+nào)|tại\s+sao|so\s+sánh)(?:\b|\s)/i
+const AUTO_NON_TASK_CHAT = /^(?:xin\s*chào|chào|hello|hi|hey|cảm\s*ơn|cam\s*on|thanks?|ok(?:ay)?|được|ừ|uh|vâng|vang)[!?.\s]*$/i
+const AUTO_ACTIVE_CONTINUATION = /^(?:continue|resume|keep\s+going|go\s+on|tiếp\s+tục|làm\s+tiếp|lam\s+tiep|sửa\s+tiếp|sua\s+tiep|kiểm\s+tra\s+tiếp|kiem\s+tra\s+tiep)(?:\b|[.!?,;:\s])/i
+
+const SAFE_READ_ONLY_GIT_CHECKS = [
+  { id: "git-status-short", label: "git status --short", match: /^git\s+status\s+--short\b/i, args: ["status", "--short"] },
+  { id: "git-branch-current", label: "git branch --show-current", match: /^git\s+branch\s+--show-current\b/i, args: ["branch", "--show-current"] },
+  { id: "git-rev-parse-head", label: "git rev-parse HEAD", match: /^git\s+rev-parse\s+head\b/i, args: ["rev-parse", "HEAD"] },
+  { id: "git-rev-parse-root", label: "git rev-parse --show-toplevel", match: /^git\s+rev-parse\s+--show-toplevel\b/i, args: ["rev-parse", "--show-toplevel"] },
+  { id: "git-status", label: "git status", match: /^git\s+status\b/i, args: ["status"] },
+]
+
 function referencedSourceFiles(value) {
   const files = []
   const seen = new Set()
@@ -47,6 +67,107 @@ function riskTextFor(value) {
     .replace(/chỉ\s+đọc[^.\n]*/gi, "")
 }
 
+export function automaticUesContinuation(value, facts = {}) {
+  const text = String(value || "").trim()
+  if (!facts.activeRun) return { forward: false, reason: "no-active-run" }
+  if (!text || text.startsWith("/")) return { forward: false, reason: "not-continuation" }
+  if (!AUTO_ACTIVE_CONTINUATION.test(text)) return { forward: false, reason: "not-continuation" }
+  return { forward: true, reason: "active-run-continuation" }
+}
+
+export function automaticUesAdmission(value, facts = {}) {
+  const text = String(value || "").trim()
+  const native = (reason, policy = null) => ({
+    admit: false,
+    route: "native",
+    confidence: "low",
+    reason,
+    policy,
+  })
+
+  if (!text) return native("empty")
+  if (text.startsWith("/")) return native("explicit-command")
+  if (AUTO_NON_TASK_CHAT.test(text)) return native("casual-chat")
+  if (facts.inGitWorkspace === false) return native("not-git-workspace")
+
+  const policy = classifyEngineeringTask(text, facts)
+  const action = AUTO_ENGINEERING_ACTION.test(text)
+  const target = AUTO_ENGINEERING_TARGET.test(text)
+  const informationalOnly =
+    AUTO_INFORMATIONAL_ONLY.test(text) &&
+    !/(?:\b(?:fix|repair|debug|implement|edit|modify|change|update|refactor|migrate|test|build|run|commit|push)\b|(?:sửa|chỉnh sửa|xử lý|thay đổi|cập nhật|refactor|chạy|test|build|commit|push))/i.test(text)
+  const longStructured =
+    target &&
+    (
+      text.length >= 700 ||
+      policy.mode === "long-horizon" ||
+      /(?:^|\n)\s*(?:phase\s+\d+|mục\s+tiêu|requirements?|acceptance criteria|final report)\b/i.test(text)
+    )
+  const readOnlyEngineering =
+    policy.readOnly === true &&
+    /(?:repo(?:sitory)?|project|code|source|git|file|test|dự án|mã nguồn|tệp|kiểm tra repository)/i.test(text)
+
+  if (informationalOnly && !longStructured && !readOnlyEngineering) {
+    return native("informational-question", policy)
+  }
+
+  const admit = longStructured || (action && target) || readOnlyEngineering
+  if (!admit) return native("not-confident-engineering-task", policy)
+
+  const route = policy.risk === "high" ? "guarded" : "auto"
+  return {
+    admit: true,
+    route,
+    confidence: longStructured || readOnlyEngineering ? "high" : "medium",
+    reason:
+      route === "guarded"
+        ? "high-risk-engineering-task"
+        : longStructured
+          ? "long-structured-engineering-task"
+          : readOnlyEngineering
+            ? "read-only-engineering-task"
+            : "engineering-action-target",
+    policy,
+  }
+}
+
+export function deterministicReadOnlyGitCommands(value) {
+  const text = String(value || "")
+  if (!COMMAND_ONLY_READ_ONLY.test(text)) return []
+
+  const mentions = []
+  const lower = text.toLowerCase()
+  const gitRe = /\bgit\s+/g
+  let hit
+  while ((hit = gitRe.exec(lower))) {
+    const tail = text.slice(hit.index)
+    const matched = SAFE_READ_ONLY_GIT_CHECKS.find((item) => item.match.test(tail))
+    if (!matched) return []
+    mentions.push({ index: hit.index, id: matched.id, label: matched.label, command: "git", args: [...matched.args] })
+  }
+
+  if (!mentions.length) return []
+  const seen = new Set()
+  return mentions
+    .sort((a, b) => a.index - b.index)
+    .filter((item) => {
+      if (seen.has(item.id)) return false
+      seen.add(item.id)
+      return true
+    })
+    .map(({ id, label, command, args }) => ({ id, label, command, args }))
+}
+
+function readOnlyTask(value, facts = {}) {
+  if (facts.readOnly === true) return true
+  const text = String(value || "")
+  if (READ_ONLY_MODE.test(text)) return true
+  if (!EXPLICIT_READ_ONLY.test(text)) return false
+  // Negative file-scope constraints ("fix X, but do not modify Y") must not
+  // convert a mutating engineering task into a read-only inspection.
+  return !MUTATION_INTENT.test(riskTextFor(text))
+}
+
 function signal(name, matched, weight) {
   return matched ? { name, weight } : null
 }
@@ -185,6 +306,17 @@ export function shouldRunDedicatedDiagnosis(taskPolicy = {}, attempt = 1) {
     return recoveryPolicyForAttempt(taskPolicy, normalizedAttempt).requireDiagnosis === true
   }
 
+  // Long-horizon work already has an architect + independent plan gate. A generic
+  // word such as "fix" must not force a redundant debugger pass before planning.
+  // Keep first-pass diagnosis when the request contains concrete failure evidence.
+  if (
+    taskPolicy.mode === "long-horizon" &&
+    taskPolicy.requirePlanCheck === true &&
+    taskPolicy.diagnosisEvidence !== true
+  ) {
+    return false
+  }
+
   return taskPolicy.executionProfile !== "fast" || taskPolicy.risk !== "low"
 }
 
@@ -192,7 +324,8 @@ export function classifyEngineeringTask(text, facts = {}) {
   const value = String(text || "")
   const riskText = riskTextFor(value)
   const sensitiveDomain = SENSITIVE_DOMAIN.test(value)
-  const singleFileBounded = singleFileBoundedTask(value, facts)
+  const readOnly = readOnlyTask(value, facts)
+  const singleFileBounded = readOnly ? false : singleFileBoundedTask(value, facts)
   const rawSensitiveMutation = HIGH_RISK_MUTATION.test(riskText)
   const sensitiveMutation =
     rawSensitiveMutation &&
@@ -223,6 +356,7 @@ export function classifyEngineeringTask(text, facts = {}) {
     signal("declared-high-risk", declaredHighRisk, 2),
     signal("explicit-long-horizon", explicitLongHorizon, 2),
     signal("debugging", DEBUG.test(value), 1),
+    signal("read-only", readOnly, -1),
     signal("single-file-bounded", singleFileBounded, -2),
     signal("public-contract", CONTRACT.test(value) || facts.hasPublicContract, 2),
     signal("data-migration", dataMigration, 2),
@@ -234,6 +368,7 @@ 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 risk = highRisk ? "high" : singleFileBounded ? "low" : score >= 3 ? "medium" : "low"
   const mode =
     explicitLongHorizon
@@ -270,11 +405,22 @@ export function classifyEngineeringTask(text, facts = {}) {
     maxAttempts,
     contextBudget: profile.contextBudget,
     maxSkills: profile.maxSkills,
-    requirePlanCheck: profile.durableState || risk === "high",
-    requireIntegrationVerification: mode !== "inline" || risk === "high",
+    requirePlanCheck: readOnly ? false : profile.durableState || risk === "high",
+    requireIntegrationVerification: readOnly ? false : mode !== "inline" || risk === "high",
     requireFreshEvidence: true,
+    requireBehavioralReceipt: !readOnly,
+    readOnly,
     singleFileBounded,
-    profile,
+    diagnosisEvidence,
+    profile: readOnly
+      ? {
+          ...profile,
+          worktree: "off",
+          verification: "command-evidence",
+          fullCI: false,
+          containerVerification: "off",
+        }
+      : profile,
     domains: [...new Set(domains)],
     recovery: {
       escalateAfterFailure: true,

package/lib/trajectory.mjs

@@ -1,9 +1,115 @@
 import { createHash, randomUUID } from "node:crypto"
-import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises"
 import path from "node:path"
 
 const TRACE_DIR = ".ues-traces"
 const MAX_EVENT_BYTES = 64 * 1024
+const DEFAULT_MAX_TRACE_FILE_BYTES = 4 * 1024 * 1024
+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
+
+function positiveInt(value, fallback, min, max) {
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.max(min, Math.min(max, Math.trunc(parsed)))
+}
+
+function traceLimits(options = {}) {
+  return {
+    maxFileBytes: positiveInt(
+      options.maxFileBytes ?? process.env.UES_TRACE_MAX_FILE_BYTES,
+      DEFAULT_MAX_TRACE_FILE_BYTES,
+      256 * 1024,
+      64 * 1024 * 1024,
+    ),
+    maxTotalBytes: positiveInt(
+      options.maxTotalBytes ?? process.env.UES_TRACE_MAX_TOTAL_BYTES,
+      DEFAULT_MAX_TRACE_TOTAL_BYTES,
+      1024 * 1024,
+      512 * 1024 * 1024,
+    ),
+    maxFiles: positiveInt(
+      options.maxFiles ?? process.env.UES_TRACE_MAX_FILES,
+      DEFAULT_MAX_TRACE_FILES,
+      4,
+      256,
+    ),
+    maxAgeMs: positiveInt(
+      options.maxAgeMs ?? process.env.UES_TRACE_MAX_AGE_MS,
+      DEFAULT_MAX_TRACE_AGE_MS,
+      60_000,
+      90 * 86_400_000,
+    ),
+  }
+}
+
+async function compactTraceFile(file, maxFileBytes) {
+  const info = await stat(file).catch(() => null)
+  if (!info?.isFile() || info.size < maxFileBytes) return false
+
+  const source = await readFile(file)
+  const keepBytes = Math.max(128 * 1024, Math.floor(maxFileBytes / 2))
+  let kept = source.subarray(Math.max(0, source.length - keepBytes))
+  const newline = kept.indexOf(0x0a)
+  if (newline >= 0 && source.length > keepBytes) kept = kept.subarray(newline + 1)
+  const marker = Buffer.from(JSON.stringify({
+    schemaVersion: 1,
+    type: "trace.compacted",
+    at: new Date().toISOString(),
+    payload: { previousBytes: source.length, retainedBytes: kept.length },
+  }) + "\n")
+  await writeFile(file, Buffer.concat([marker, kept]))
+  return true
+}
+
+export async function pruneTrajectoryStore(root = process.cwd(), options = {}) {
+  root = path.resolve(root)
+  const dir = path.join(root, TRACE_DIR)
+  const limits = traceLimits(options)
+  const protect = options.protectTraceID ? cleanID(options.protectTraceID) + ".jsonl" : null
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+  const rows = []
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue
+    const file = path.join(dir, entry.name)
+    const info = await stat(file).catch(() => null)
+    if (!info?.isFile()) continue
+    rows.push({ name: entry.name, file, bytes: info.size, mtimeMs: info.mtimeMs })
+  }
+
+  rows.sort((a, b) => b.mtimeMs - a.mtimeMs)
+  let retainedBytes = 0
+  let retainedFiles = 0
+  const removed = []
+  const now = Date.now()
+
+  for (const row of rows) {
+    if (row.name === protect) {
+      retainedBytes += row.bytes
+      retainedFiles += 1
+      continue
+    }
+    const expired = limits.maxAgeMs > 0 && now - row.mtimeMs > limits.maxAgeMs
+    const overFiles = retainedFiles >= limits.maxFiles
+    const overBytes = retainedBytes + row.bytes > limits.maxTotalBytes
+    if (expired || overFiles || overBytes) {
+      await rm(row.file, { force: true }).catch(() => {})
+      removed.push(row.name)
+      continue
+    }
+    retainedBytes += row.bytes
+    retainedFiles += 1
+  }
+
+  return {
+    removed,
+    removedCount: removed.length,
+    retainedFiles,
+    retainedBytes,
+    limits,
+  }
+}
 
 function cleanID(value) {
   const text = String(value || "").trim()
@@ -49,8 +155,12 @@ export function trajectoryFile(root, traceID) {
 }
 
 export async function appendTrajectoryEvent(root, traceID, type, payload = {}) {
+  root = path.resolve(root)
   const file = trajectoryFile(root, traceID)
   await mkdir(path.dirname(file), { recursive: true })
+  const limits = traceLimits()
+  await compactTraceFile(file, limits.maxFileBytes).catch(() => false)
+  await pruneTrajectoryStore(root, { ...limits, protectTraceID: traceID }).catch(() => null)
   const scrubbed = scrubTrajectoryValue(payload)
   const rawPayload = JSON.stringify(scrubbed)
   const bounded = Buffer.byteLength(rawPayload, "utf8") <= MAX_EVENT_BYTES

package/lib/turbo-fast-path.mjs

@@ -0,0 +1,44 @@
+const FAST_ROLES = new Set(["executor", "verifier"])
+
+export function turboFastPathDecision(taskPolicy = {}, options = {}) {
+  const role = String(options.role || "")
+  const attempt = Math.max(1, Number(options.attempt || 1))
+  const browserRequested = options.browserRequested === true
+  const visualRequired = options.visualRequired === true
+  const reasons = []
+
+  if (attempt !== 1) reasons.push("recovery-attempt")
+  if (taskPolicy.executionProfile !== "fast") reasons.push("not-fast-profile")
+  if (taskPolicy.singleFileBounded !== true) reasons.push("not-single-file-bounded")
+  if (String(taskPolicy.risk || "").toLowerCase() !== "low") reasons.push("risk-not-low")
+  if (taskPolicy.requireIntegrationVerification === true) reasons.push("integration-required")
+  if (!FAST_ROLES.has(role)) reasons.push("role-not-fast-lane")
+  if (browserRequested) reasons.push("browser-required")
+  if (visualRequired) reasons.push("visual-required")
+
+  const eligible = reasons.length === 0
+  return {
+    schemaVersion: 1,
+    eligible,
+    strategy: eligible ? "single-model-deterministic-first" : "standard",
+    deterministicFirst: eligible,
+    verifierOnDemand: eligible,
+    failClosed: true,
+    maxModelLanes: eligible ? 1 : null,
+    reasons,
+  }
+}
+
+export function turboFastTimeoutBudget(options = {}) {
+  const number = (value, fallback, min, max) => {
+    const parsed = Number(value)
+    if (!Number.isFinite(parsed) || parsed <= 0) return fallback
+    return Math.max(min, Math.min(max, Math.trunc(parsed)))
+  }
+  return {
+    hardTimeoutMs: number(options.hardTimeoutMs, 180_000, 30_000, 10 * 60_000),
+    idleTimeoutMs: number(options.idleTimeoutMs, 60_000, 20_000, 5 * 60_000),
+    postToolErrorIdleTimeoutMs: number(options.postToolErrorIdleTimeoutMs, 30_000, 5_000, 2 * 60_000),
+    verificationTimeoutSec: number(options.verificationTimeoutSec, 90, 30, 300),
+  }
+}

package/lib/workspace-fingerprint.mjs

@@ -2,20 +2,11 @@ import { createHash } from "node:crypto"
 import { lstatSync, readFileSync, readlinkSync } from "node:fs"
 import { spawnSync } from "node:child_process"
 import path from "node:path"
+import { UES_RUNTIME_DIRS } from "./runtime-artifacts.mjs"
 
-const RUNTIME_DIRS = [
-  ".ues-cache",
-  ".ues-traces",
-  ".ues-work",
-  ".ues-learning",
-  ".ues-dashboard",
-  ".ues-sandboxes",
-  ".ues-memory",
-  ".ues-evals",
-]
 const RUNTIME_PATHSPECS = [
   ".",
-  ...RUNTIME_DIRS.map((dir) => `:(exclude)${dir}/**`),
+  ...UES_RUNTIME_DIRS.map((dir) => `:(exclude)${dir}/**`),
 ]
 
 let nonGitNonce = 0

package/lib/workspace-root.mjs

@@ -0,0 +1,49 @@
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+
+function runGit(cwd, args) {
+  return spawnSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    windowsHide: true,
+    shell: false,
+  })
+}
+
+export function resolveGitWorkspaceRoot(start = process.cwd()) {
+  const requested = path.resolve(String(start || process.cwd()))
+  const inside = runGit(requested, ["rev-parse", "--is-inside-work-tree"])
+  if (inside.status !== 0 || String(inside.stdout || "").trim() !== "true") {
+    return {
+      ok: false,
+      requested,
+      root: null,
+      error: String(inside.stderr || inside.stdout || "not a git worktree").trim(),
+    }
+  }
+
+  const top = runGit(requested, ["rev-parse", "--show-toplevel"])
+  if (top.status !== 0) {
+    return {
+      ok: false,
+      requested,
+      root: null,
+      error: String(top.stderr || top.stdout || "could not resolve git root").trim(),
+    }
+  }
+
+  const root = path.resolve(String(top.stdout || "").trim())
+  return { ok: true, requested, root, error: null }
+}
+
+export function requireGitWorkspaceRoot(start = process.cwd(), purpose = "UES") {
+  const resolved = resolveGitWorkspaceRoot(start)
+  if (resolved.ok) return resolved.root
+
+  const detail = resolved.error ? ": " + resolved.error : ""
+  throw new Error(
+    purpose +
+      " requires Pi to be opened inside a Git repository. Refusing to create UES runtime artifacts in " +
+      resolved.requested +
+      detail,
+  )
+}